@north-light/api 0.3.580 → 0.3.588

package/dist/clients/attach/overlays/help.d.ts

@@ -0,0 +1,33 @@
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import type { AttachPalette } from '../config.js';
+import type { AttachBindings } from '../session/bindings.js';
+/** A bounded, focused reference for the attach viewer's viewport controls. */
+export declare class HelpOverlay implements Component {
+    private readonly tui;
+    private readonly pal;
+    private handle;
+    private bindings;
+    private scrollTop;
+    private lastContentRows;
+    constructor(tui: TUI, pal: AttachPalette);
+    /** Re-resolve key spellings after `/reload` (mirrors GraphOverlay.setBindings). */
+    setBindings(bindings: AttachBindings): void;
+    toggle(): void;
+    close(): void;
+    isOpen(): boolean;
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): boolean;
+    private open;
+    private matchesBinding;
+    private scrollBy;
+    private pageSize;
+    private body;
+    private lines;
+    private binding;
+    private wrap;
+    private style;
+    private boxRow;
+    private borderRow;
+    private renderNarrow;
+}

package/dist/clients/attach/overlays/help.js

@@ -0,0 +1,214 @@
+import { matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
+import { ATTACH_CONTROL_BINDINGS, BINDING_CATALOG, formatBinding, matchesPiTuiInput, } from '../../../core/keybindings/index.js';
+const HEIGHT_PCT = 0.72;
+const OVERLAY_OPTIONS = { anchor: 'center', width: '72%', minWidth: 48, maxHeight: '72%', margin: 1 };
+/** A bounded, focused reference for the attach viewer's viewport controls. */
+export class HelpOverlay {
+    tui;
+    pal;
+    handle;
+    bindings;
+    scrollTop = 0;
+    lastContentRows = 1;
+    constructor(tui, pal) {
+        this.tui = tui;
+        this.pal = pal;
+    }
+    /** Re-resolve key spellings after `/reload` (mirrors GraphOverlay.setBindings). */
+    setBindings(bindings) {
+        this.bindings = bindings;
+        if (this.handle !== undefined)
+            this.tui.requestRender();
+    }
+    toggle() {
+        if (this.handle === undefined)
+            this.open();
+        else
+            this.close();
+    }
+    close() {
+        if (this.handle === undefined)
+            return;
+        this.handle.hide();
+        this.handle = undefined;
+        this.tui.requestRender();
+    }
+    isOpen() {
+        return this.handle !== undefined;
+    }
+    invalidate() {
+        if (this.handle !== undefined)
+            this.tui.requestRender();
+    }
+    render(width) {
+        const panelWidth = Math.max(1, width);
+        if (panelWidth < 5)
+            return this.renderNarrow(panelWidth);
+        const innerWidth = panelWidth - 4;
+        const allLines = this.body(innerWidth);
+        const terminalRows = Math.max(1, this.tui.terminal.rows);
+        const maxPanelHeight = Math.max(3, Math.min(Math.floor(terminalRows * HEIGHT_PCT), Math.max(3, terminalRows - 2)));
+        const bodyRows = Math.max(1, maxPanelHeight - 2);
+        const overflow = allLines.length > bodyRows;
+        const contentRows = overflow && bodyRows >= 3 ? bodyRows - 2 : 1;
+        this.lastContentRows = contentRows;
+        this.scrollTop = Math.max(0, Math.min(this.scrollTop, Math.max(0, allLines.length - contentRows)));
+        const end = Math.min(allLines.length, this.scrollTop + contentRows);
+        const body = [];
+        if (overflow && bodyRows >= 3) {
+            body.push(this.scrollTop > 0 ? this.pal.muted(`↑ ${this.scrollTop} more`) : '');
+        }
+        body.push(...allLines.slice(this.scrollTop, end));
+        if (overflow && bodyRows >= 3) {
+            body.push(end < allLines.length ? this.pal.muted(`↓ ${allLines.length - end} more`) : '');
+        }
+        else if (overflow && bodyRows === 2) {
+            body.push(end < allLines.length ? this.pal.muted(`↓ ${allLines.length - end} more`) : '');
+        }
+        while (body.length < bodyRows)
+            body.push('');
+        const title = this.pal.bold(this.pal.accent('⌨ attach help'));
+        const hint = this.pal.muted('esc dismiss · ↑↓ scroll');
+        return [
+            this.borderRow('╭', '╮', title, panelWidth),
+            ...body.map((line) => this.boxRow(line, panelWidth)),
+            this.borderRow('╰', '╯', hint, panelWidth),
+        ].map(this.pal.surface);
+    }
+    handleInput(data) {
+        if (matchesKey(data, 'escape') || matchesKey(data, 'q')) {
+            this.close();
+            return true;
+        }
+        if (matchesKey(data, 'up') || this.matchesBinding('crtr.attach.scroll.up', data))
+            return this.scrollBy(-1);
+        if (matchesKey(data, 'down') || this.matchesBinding('crtr.attach.scroll.down', data))
+            return this.scrollBy(1);
+        if (matchesKey(data, 'pageUp') || this.matchesBinding('crtr.attach.scroll.page-up', data))
+            return this.scrollBy(-this.pageSize());
+        if (matchesKey(data, 'pageDown') || this.matchesBinding('crtr.attach.scroll.page-down', data))
+            return this.scrollBy(this.pageSize());
+        return true;
+    }
+    open() {
+        this.scrollTop = 0;
+        this.handle = this.tui.showOverlay(this, OVERLAY_OPTIONS);
+    }
+    matchesBinding(id, data) {
+        return this.bindings !== undefined && matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    scrollBy(lines) {
+        const lineCount = this.body(Math.max(1, this.tui.terminal.columns - 4)).length;
+        const maxTop = Math.max(0, lineCount - this.lastContentRows);
+        const next = Math.max(0, Math.min(maxTop, this.scrollTop + lines));
+        if (next !== this.scrollTop) {
+            this.scrollTop = next;
+            this.tui.requestRender();
+        }
+        return true;
+    }
+    pageSize() {
+        return Math.max(1, this.lastContentRows - 1);
+    }
+    body(width) {
+        return this.lines().flatMap((line) => this.wrap(line.text, width).map((text) => this.style(text, line.style)));
+    }
+    lines() {
+        const binding = (id, description) => ({
+            text: `${this.binding(id)}  ${description}`,
+            style: 'plain',
+        });
+        const heading = (text) => ({ text, style: 'heading' });
+        const muted = (text) => ({ text, style: 'muted' });
+        const blank = { text: '', style: 'plain' };
+        const otherKeys = ATTACH_CONTROL_BINDINGS.map(({ actionId }) => {
+            const name = BINDING_CATALOG.find((definition) => definition.id === actionId)?.name ?? actionId;
+            return binding(actionId, name);
+        });
+        return [
+            heading('Learning crouter'),
+            { text: '/tutorial  the guided crouter tutorial — your agent teaches it, one lesson at a time', style: 'plain' },
+            blank,
+            heading('Scrolling'),
+            binding('crtr.attach.scroll.up', 'scroll one line up'),
+            binding('crtr.attach.scroll.down', 'scroll one line down'),
+            binding('crtr.attach.scroll.page-up', 'scroll one page up'),
+            binding('crtr.attach.scroll.page-down', 'scroll one page down'),
+            binding('crtr.attach.scroll.live', 'return to the live bottom'),
+            muted('mouse wheel (when reporting is on)'),
+            blank,
+            heading('Searching the transcript'),
+            { text: `${this.binding('crtr.attach.search')}  search what the transcript is currently showing. Type to jump as you go, enter to browse the matches.`, style: 'plain' },
+            { text: `${this.binding('crtr.attach.search.next')} / ${this.binding('crtr.attach.search.previous')}  next and previous match · ${this.binding('crtr.attach.search.edit')}  edit the query · ${this.binding('crtr.attach.search.close')}  close. Typing anything else closes search and returns to the editor.`, style: 'plain' },
+            { text: 'A lowercase query ignores case; any uppercase letter makes it case-sensitive.', style: 'plain' },
+            { text: 'Folded tool output is not on screen, so it is not searched — unfold it to include it.', style: 'muted' },
+            blank,
+            heading('Selection and copy'),
+            { text: 'Drag with the mouse to select; releasing copies the selection to the clipboard (and the tmux buffer). Any key clears the highlight.', style: 'plain' },
+            { text: 'prefix + [  tmux copy-mode selects and copies the visible screenful; it works even while mouse reporting is on.', style: 'plain' },
+            { text: 'Option-drag (iTerm2, Terminal.app) or Shift-drag (Ghostty, Alacritty, xterm) makes a true terminal selection that bypasses mouse reporting.', style: 'plain' },
+            { text: 'Block-copy commands copy transcript content and are not capped at one screenful.', style: 'plain' },
+            blank,
+            heading('Copy commands'),
+            { text: '/copy  last assistant message.', style: 'plain' },
+            { text: `/copy-message (${this.binding('crtr.attach.copy.message')})  newest copyable block entirely visible in the viewport; otherwise the newest one that intersects it.`, style: 'plain' },
+            { text: "/copy-tool  newest tool call's result text.", style: 'plain' },
+            { text: "/copy-transcript  every copyable block's text, oldest to newest, joined by blank lines.", style: 'plain' },
+            blank,
+            heading('Mouse'),
+            { text: `/mouse or ${this.binding('crtr.attach.mouse.toggle')}  toggle mouse reporting — wheel scrolling and viewer drag-select. Turning it off restores tmux drag-select and copy-mode mouse.`, style: 'plain' },
+            blank,
+            heading('Other attach keys'),
+            ...otherKeys,
+        ];
+    }
+    binding(id) {
+        return this.bindings === undefined ? 'Loading…' : formatBinding(this.bindings, id);
+    }
+    wrap(text, width) {
+        if (text === '')
+            return [''];
+        const limit = Math.max(1, width);
+        const words = text.split(/\s+/);
+        const lines = [];
+        let current = '';
+        for (const word of words) {
+            const candidate = current === '' ? word : `${current} ${word}`;
+            if (current !== '' && visibleWidth(candidate) > limit) {
+                lines.push(truncateToWidth(current, limit, '', true));
+                current = `  ${word}`;
+            }
+            else {
+                current = candidate;
+            }
+        }
+        if (current !== '')
+            lines.push(truncateToWidth(current, limit, '', true));
+        return lines;
+    }
+    style(text, style) {
+        switch (style) {
+            case 'heading': return this.pal.bold(this.pal.accent(text));
+            case 'muted': return this.pal.muted(text);
+            case 'plain': return text;
+        }
+    }
+    boxRow(content, width) {
+        const innerWidth = width - 4;
+        const clipped = truncateToWidth(content, innerWidth, '', true);
+        const padding = ' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)));
+        return `${this.pal.border('│')} ${clipped}${padding} ${this.pal.border('│')}`;
+    }
+    borderRow(left, right, label, width) {
+        if (width < 6)
+            return truncateToWidth(`${this.pal.border(left)}${label}${this.pal.border(right)}`, width, '', true);
+        const span = width - 5;
+        const clipped = truncateToWidth(label, span, '…');
+        const fill = Math.max(0, width - 5 - visibleWidth(clipped));
+        return `${this.pal.border(`${left}─`)} ${clipped} ${this.pal.border('─'.repeat(fill) + right)}`;
+    }
+    renderNarrow(width) {
+        const title = truncateToWidth(this.pal.bold(this.pal.accent('help')), width, '', true);
+        return [this.pal.surface(title)];
+    }
+}

package/dist/clients/attach/overlays/mcp.d.ts

@@ -0,0 +1,32 @@
+import type { ClientToBroker } from '../../../core/runtime/broker-protocol.js';
+import type { Picker } from './pickers.js';
+/** One configured MCP server, joined against the adapter's tool cache. */
+export interface McpServerRow {
+    name: string;
+    /** 'http' | 'sse' | 'stdio' — the config's `type`, or inferred (url → http, command → stdio). */
+    transport: string;
+    /** The connection target: the url (http) or the command line (stdio). */
+    target: string;
+    /** Cached tool count, or null when the server has no cache entry (never connected). */
+    toolCount: number | null;
+    /** True when a cache entry exists but its configHash no longer matches the
+     *  current config — the adapter treats that cache as a miss, so the tool
+     *  count is stale. Always false when toolCount is null. */
+    stale: boolean;
+}
+/** Read + merge the adapter's config sources (see file header) and join the
+ *  tool cache into display rows. Returns [] when nothing is configured. */
+export declare function readMcpServers(home?: string, cwd?: string): McpServerRow[];
+/** The hint shown when no source configures any server — lists the same
+ *  sources readMcpServers actually reads (mirroring the adapter). */
+export declare const MCP_EMPTY_STATE_HINT = "No MCP servers configured \u2014 add one to ~/.config/mcp/mcp.json, ~/.pi/agent/mcp.json, <cwd>/.mcp.json, or <cwd>/.pi/mcp.json";
+/** Enter on a row: bridge the right adapter action to the engine via a
+ *  `prompt` frame. Never connected → OAuth kick-off; connected before →
+ *  reconnect, falling back to auth-start (the re-auth path — expired OAuth
+ *  still shows as cached, so reconnect must always be reachable). */
+export declare function startMcpServerAction(row: McpServerRow, send: (frame: ClientToBroker) => void, notify: (message: string) => void): void;
+/** Build the /mcp status panel as an inline picker. Enter on any row acts:
+ *  never-connected → OAuth kick-off, cached → reconnect/re-auth (see
+ *  startMcpServerAction). Status reflects the CACHE — "cached" means the
+ *  server connected before under this config, not that it is connected now. */
+export declare function buildMcpPicker(rows: McpServerRow[], send: (frame: ClientToBroker) => void, close: () => void, notify: (message: string) => void): Picker;

package/dist/clients/attach/overlays/mcp.js

@@ -0,0 +1,302 @@
+// overlays/mcp.ts — the native /mcp panel for `crtr surface attach`.
+//
+// The pi-mcp-adapter's own /mcp is an interactive pi TUI command, DEAD in
+// crtr's print-mode broker — so the viewer renders MCP server status natively,
+// from the adapter's own on-disk state (no MCP protocol reimplementation).
+//
+// Config sources MIRROR the adapter's `getConfigSources` (pi-mcp-adapter
+// config.ts), in the same precedence order (later sources override earlier,
+// field-level merge per server):
+//   1. ~/.config/mcp/mcp.json      (generic user-global standard MCP)
+//   2. <agentDir>/mcp.json         (pi global override — $PI_CODING_AGENT_DIR,
+//                                   else ~/.pi/agent, like the adapter's getAgentPath)
+//   3. <cwd>/.mcp.json             (project standard MCP)
+//   4. <cwd>/.pi/mcp.json          (project pi override)
+// Each file may name servers under `mcpServers` OR the `mcp-servers` alias,
+// and may declare `imports` (cursor / claude-code / claude-desktop / codex /
+// windsurf / vscode) whose servers merge UNDER the file's own entries —
+// all mirroring the adapter's validateConfig/expandImports/extractServers
+// (incl. the alias being honored only for cursor/windsurf/vscode imports, and
+// a non-object `mcpServers` invalidating a file's own imports too).
+//
+// Status joins <agentDir>/mcp-cache.json (the adapter's tool cache). A cache
+// entry means the server has CONNECTED BEFORE — it does NOT prove live
+// connectivity or valid auth. The entry is validated like the adapter's
+// `isServerCacheValid`: its `configHash` is compared against a local
+// recomputation of `computeServerHash`, AND an entry older than 7 days is a
+// miss; either failure marks the row stale. (The hash interpolates env vars from THIS process — a viewer whose
+// env differs from the engine's can report a false "config changed", which
+// only softens the wording, never hides a server.)
+//
+// All reads are best-effort: a missing/corrupt file degrades to an empty
+// state, never a crash.
+//
+// The action: Enter bridges to the ENGINE (the adapter runtime lives in the
+// engine process, unreachable from the viewer) by sending a `prompt` frame —
+// a never-connected server gets an OAuth kick-off (mcp({ action:
+// "auth-start", server })), a previously-connected one gets a reconnect with
+// auth-start as the fallback, covering the re-auth case (expired OAuth shows
+// as cached but fails to reconnect). Action names verified against the
+// installed adapter (pi-mcp-adapter index.ts: "auth-start" / "auth-complete" /
+// "ui-messages"; `connect: <name>`).
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { piAgentDir } from '../../../core/runtime/package-health.js';
+import { SelectList, visibleWidth } from '@earendil-works/pi-tui';
+import { getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { readJsonOrNull } from '../../../core/fs-utils.js';
+/** Adapter metadata-cache.ts CACHE_MAX_AGE_MS — entries older than this are misses. */
+const CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** The adapter's import-source table (pi-mcp-adapter config.ts IMPORT_PATHS).
+ *  Relative candidates (vscode) resolve against the cwd. */
+function importPathCandidates(kind, home) {
+    switch (kind) {
+        case 'cursor':
+            return [join(home, '.cursor', 'mcp.json')];
+        case 'claude-code':
+            return [
+                join(home, '.claude', 'mcp.json'),
+                join(home, '.claude.json'),
+                join(home, '.claude', 'claude_desktop_config.json'),
+            ];
+        case 'claude-desktop':
+            return [join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')];
+        case 'codex':
+            return [join(home, '.codex', 'config.json')];
+        case 'windsurf':
+            return [join(home, '.windsurf', 'mcp.json')];
+        case 'vscode':
+            return ['.vscode/mcp.json'];
+        default:
+            return [];
+    }
+}
+/** Mirror of the adapter's validateConfig (config.ts): a source file's own
+ *  servers may live under `mcpServers` OR the `mcp-servers` alias — but a
+ *  non-object value invalidates the WHOLE file, dropping its `imports` too. */
+function validateConfigSource(raw) {
+    const servers = raw.mcpServers ?? raw['mcp-servers'] ?? {};
+    if (typeof servers !== 'object' || servers === null || Array.isArray(servers)) {
+        return { servers: {}, imports: [] };
+    }
+    return {
+        servers: servers,
+        imports: Array.isArray(raw.imports) ? raw.imports : [],
+    };
+}
+/** Mirror of the adapter's extractServers (config.ts): the `mcp-servers`
+ *  alias is honored only for cursor/windsurf/vscode imports —
+ *  claude-code/claude-desktop/codex read `mcpServers` only. */
+function extractImportedServers(raw, kind) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const obj = raw;
+    let servers;
+    switch (kind) {
+        case 'claude-desktop':
+        case 'claude-code':
+        case 'codex':
+            servers = obj.mcpServers;
+            break;
+        case 'cursor':
+        case 'windsurf':
+        case 'vscode':
+            servers = obj.mcpServers ?? obj['mcp-servers'];
+            break;
+        default:
+            return {};
+    }
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers))
+        return {};
+    return servers;
+}
+/** Field-level per-server merge — the adapter's mergeServerMaps. */
+function mergeServerMaps(base, next) {
+    const merged = { ...base };
+    for (const [name, spec] of Object.entries(next)) {
+        merged[name] = { ...(merged[name] ?? {}), ...spec };
+    }
+    return merged;
+}
+/** Read one config file: its own servers layered OVER any `imports` servers
+ *  (first import wins per name, own config wins overall — adapter expandImports). */
+function readConfigSource(path, cwd, home) {
+    const raw = readJsonOrNull(path);
+    if (raw === null)
+        return {};
+    const { servers: own, imports } = validateConfigSource(raw);
+    const imported = {};
+    for (const kind of imports) {
+        // The adapter's resolveImportPath selects the first EXISTING candidate
+        // (existsSync) and only then reads it — a corrupt first candidate yields
+        // nothing for this import kind, never a fall-through to the next path.
+        const full = importPathCandidates(kind, home)
+            .map((candidate) => (candidate.startsWith('.') ? resolve(cwd, candidate) : candidate))
+            .find((candidate) => existsSync(candidate));
+        if (full === undefined)
+            continue;
+        const importedRaw = readJsonOrNull(full);
+        if (importedRaw === null)
+            continue;
+        for (const [name, spec] of Object.entries(extractImportedServers(importedRaw, kind))) {
+            if (!(name in imported))
+                imported[name] = spec;
+        }
+    }
+    return mergeServerMaps(imported, own);
+}
+// configHash recomputation — mirrors pi-mcp-adapter metadata-cache.ts
+function interpolateEnvVars(value) {
+    return value
+        .replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? '')
+        .replace(/\$env:(\w+)/g, (_, name) => process.env[name] ?? '');
+}
+function interpolateEnvRecord(values) {
+    if (!values)
+        return undefined;
+    const resolved = {};
+    for (const [key, value] of Object.entries(values))
+        resolved[key] = interpolateEnvVars(value);
+    return resolved;
+}
+function resolveConfigPath(value) {
+    if (value === undefined)
+        return undefined;
+    const resolved = interpolateEnvVars(value);
+    if (resolved === '~')
+        return homedir();
+    if (resolved.startsWith('~/') || resolved.startsWith('~\\'))
+        return join(homedir(), resolved.slice(2));
+    return resolved;
+}
+function resolveBearerToken(spec) {
+    if (spec.bearerToken !== undefined)
+        return interpolateEnvVars(spec.bearerToken);
+    return spec.bearerTokenEnv ? process.env[spec.bearerTokenEnv] : undefined;
+}
+function stableStringify(value) {
+    if (value === null || value === undefined || typeof value !== 'object') {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? 'undefined' : serialized;
+    }
+    if (Array.isArray(value))
+        return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}
+/** The adapter's computeServerHash: sha256 over the identity fields only. */
+function computeServerHash(spec) {
+    const identity = {
+        command: spec.command,
+        args: spec.args,
+        env: interpolateEnvRecord(spec.env),
+        cwd: resolveConfigPath(spec.cwd),
+        url: spec.url,
+        headers: interpolateEnvRecord(spec.headers),
+        auth: spec.auth,
+        bearerToken: resolveBearerToken(spec),
+        bearerTokenEnv: spec.bearerTokenEnv,
+        exposeResources: spec.exposeResources,
+        excludeTools: spec.excludeTools,
+    };
+    return createHash('sha256').update(stableStringify(identity)).digest('hex');
+}
+/** Read + merge the adapter's config sources (see file header) and join the
+ *  tool cache into display rows. Returns [] when nothing is configured. */
+export function readMcpServers(home = homedir(), cwd = process.cwd()) {
+    // The pi-global config AND the tool cache live in the agent dir, which
+    // honors $PI_CODING_AGENT_DIR — piAgentDir mirrors the adapter's getAgentDir.
+    const agentDir = piAgentDir(home);
+    const sourcePaths = [...new Set([
+            join(home, '.config', 'mcp', 'mcp.json'),
+            join(agentDir, 'mcp.json'),
+            resolve(cwd, '.mcp.json'),
+            resolve(cwd, '.pi', 'mcp.json'),
+        ])];
+    let servers = {};
+    for (const path of sourcePaths) {
+        servers = mergeServerMaps(servers, readConfigSource(path, cwd, home));
+    }
+    const cache = readJsonOrNull(join(agentDir, 'mcp-cache.json'));
+    return Object.entries(servers).map(([name, spec]) => {
+        const transport = spec.type ?? (spec.url !== undefined ? 'http' : 'stdio');
+        const target = spec.url ?? [spec.command, ...(spec.args ?? [])].filter(Boolean).join(' ');
+        const entry = cache?.servers?.[name];
+        const tools = entry?.tools;
+        const toolCount = Array.isArray(tools) ? tools.length : null;
+        const stale = toolCount !== null && entry !== undefined && !isCacheEntryFresh(entry, spec);
+        return { name, transport, target, toolCount, stale };
+    });
+}
+/** Mirror of the adapter's isServerCacheValid (metadata-cache.ts): a hash
+ *  mismatch, a missing/invalid cachedAt, or an entry older than
+ *  CACHE_MAX_AGE_MS is a cache miss — the adapter would refetch. */
+function isCacheEntryFresh(entry, spec) {
+    if (entry.configHash !== computeServerHash(spec))
+        return false;
+    if (!entry.cachedAt || typeof entry.cachedAt !== 'number')
+        return false;
+    if (Date.now() - entry.cachedAt > CACHE_MAX_AGE_MS)
+        return false;
+    return true;
+}
+/** The hint shown when no source configures any server — lists the same
+ *  sources readMcpServers actually reads (mirroring the adapter). */
+export const MCP_EMPTY_STATE_HINT = 'No MCP servers configured — add one to ~/.config/mcp/mcp.json, ~/.pi/agent/mcp.json, <cwd>/.mcp.json, or <cwd>/.pi/mcp.json';
+/** Enter on a row: bridge the right adapter action to the engine via a
+ *  `prompt` frame. Never connected → OAuth kick-off; connected before →
+ *  reconnect, falling back to auth-start (the re-auth path — expired OAuth
+ *  still shows as cached, so reconnect must always be reachable). */
+export function startMcpServerAction(row, send, notify) {
+    const nameJson = JSON.stringify(row.name);
+    if (row.toolCount === null) {
+        send({
+            type: 'prompt',
+            text: `Run mcp({ action: "auth-start", server: ${nameJson} }) and show me the returned OAuth URL verbatim (with any instructions). If the server does not need OAuth, run mcp({ connect: ${nameJson} }) instead and report the result.`,
+        });
+        notify(`Asking the engine to start OAuth for ${row.name}…`);
+    }
+    else {
+        send({
+            type: 'prompt',
+            text: `Run mcp({ connect: ${nameJson} }) to reconnect that MCP server and report the result. If it fails with an authentication or authorization error, run mcp({ action: "auth-start", server: ${nameJson} }) and show me the returned OAuth URL verbatim (with any instructions).`,
+        });
+        notify(`Asking the engine to reconnect ${row.name}…`);
+    }
+}
+/** Build the /mcp status panel as an inline picker. Enter on any row acts:
+ *  never-connected → OAuth kick-off, cached → reconnect/re-auth (see
+ *  startMcpServerAction). Status reflects the CACHE — "cached" means the
+ *  server connected before under this config, not that it is connected now. */
+export function buildMcpPicker(rows, send, close, notify) {
+    const items = rows.map((r) => ({
+        value: r.name,
+        label: r.toolCount === null
+            ? `○ ${r.name} — ${r.transport} · never connected (Enter to connect/OAuth)`
+            : r.stale
+                ? `△ ${r.name} — ${r.transport} · config changed — ${r.toolCount} tool${r.toolCount === 1 ? '' : 's'} cached, stale (Enter to reconnect)`
+                : `✓ ${r.name} — ${r.transport} · ${r.toolCount} tool${r.toolCount === 1 ? '' : 's'} cached (Enter to reconnect)`,
+        description: r.target,
+    }));
+    // Widen the primary column past the 30-cell default so the status labels
+    // aren't truncated mid-word. visibleWidth (not .length) so wide/emoji server
+    // names measure in cells, matching what SelectList itself renders. Math.max
+    // is floored at 0 so an empty rows array stays locally safe (-Infinity guard).
+    const width = Math.max(0, ...items.map((i) => visibleWidth(i.label))) + 2;
+    const list = new SelectList(items, 12, getSelectListTheme(), {
+        minPrimaryColumnWidth: width,
+        maxPrimaryColumnWidth: width,
+    });
+    list.onSelect = (item) => {
+        const row = rows.find((r) => r.name === item.value);
+        if (row === undefined)
+            return;
+        close();
+        startMcpServerAction(row, send, notify);
+    };
+    list.onCancel = () => close();
+    return { component: list, focus: list };
+}

package/dist/clients/attach/overlays/pickers.d.ts

@@ -0,0 +1,56 @@
+import { type Component, type KeybindingsManager, type TUI } from '@earendil-works/pi-tui';
+import type { ClientToBroker, GetSettingsData, GetTreeData, ListModelsData, ListScopedModelsData } from '../../../core/runtime/broker-protocol.js';
+import type { ReadOpRequest } from '../../../core/broker-client/index.js';
+/** A built picker overlay: the `component` to show, and the `focus` target the
+ *  caller must `setFocus` (the component itself, or the inner list that owns
+ *  `handleInput`). */
+export interface Picker {
+    component: Component;
+    focus: Component;
+}
+/** Controls handed to a picker builder by InputController.showPicker. `close`
+ *  tears the whole picker down + restores editor focus; `replace` swaps the
+ *  CURRENTLY-mounted component for a new one IN THE SAME inline slot (no centered
+ *  overlay), focusing it — used by multi-step flows like /login, where selecting
+ *  a provider replaces the selector with the login dialog right under the editor. */
+export interface PickerControls {
+    close: () => void;
+    replace: (component: Component, focus: Component) => void;
+}
+/** Send a command frame to the broker (= InputController hooks.onCommand). */
+type Send = (frame: ClientToBroker) => void;
+/** Issue a correlated read-op (lazy loaders need it after construction). */
+type Request = (frame: ReadOpRequest) => Promise<unknown>;
+/** Tear the picker overlay down (owned by InputController). */
+type Close = () => void;
+/** Surface a one-line viewer notice. */
+type Notify = (message: string) => void;
+/** `/model` (and ctrl+l) — the real model selector with search + scope toggle.
+ *  Select → `set_model` with the resolved `provider/id` (the broker's
+ *  `findModelSpec` requires that form). */
+export declare function buildModelPicker(tui: TUI, data: ListModelsData, send: Send, close: Close): Picker;
+/** `/resume` — the real session selector. Opens INSTANTLY and reconstructs from
+ *  async loaders that fetch each scope on demand — the component's own Loading
+ *  header covers the scan (listing a large session dir takes seconds, so the
+ *  fetch must stay off the open path). Select → `switch_session`. Rename/delete
+ *  are out of scope (no command frame). */
+export declare function buildSessionPicker(tui: TUI, currentSessionFile: string | undefined, request: Request, keybindings: KeybindingsManager, send: Send, close: Close): Picker;
+/** `/tree` — the real tree navigator (pure data). Select → `navigate_tree`.
+ *  Label-edit is out of scope (no command frame) → no `onLabelChange`. */
+export declare function buildTreePicker(tui: TUI, data: GetTreeData, send: Send, close: Close): Picker;
+/** `/fork` — the real prior-user-message selector (pure data, from
+ *  `get_tree.forkPoints`). Select → `fork`. The outer component has no
+ *  `handleInput`; the inner `getMessageList()` does (focus target). */
+export declare function buildForkPicker(data: GetTreeData, send: Send, close: Close): Picker;
+/** `/settings` exposes only the two settings attach can actually mutate over
+ *  view.sock. Upstream's selector has no item-omission API and always includes its
+ *  fullscreen controls, which are not real attach state because attach is fixed to
+ *  TuiMainScreen's normal buffer. */
+export declare function buildSettingsPicker(data: GetSettingsData, send: Send, close: Close): Picker;
+/** `/scoped-models` — READ-ONLY via a pi-tui SelectList. CONTRACT GAP: pi (through
+ *  0.79.1) does not re-export `ScopedModelsSelectorComponent`, and the contract
+ *  exposes no command frame for its enable/disable/persist mutations, so a
+ *  faithful editable picker is not buildable in scope. This shows the registry
+ *  with the enabled set marked; select notifies that toggling is unsupported. */
+export declare function buildScopedModelsPicker(data: ListScopedModelsData, close: Close, notify: Notify): Picker;
+export {};