@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/chrome/ticket-panel.js

@@ -0,0 +1,280 @@
+// chrome/ticket-panel.ts — the inline ticket page at the top of the pane.
+//
+// Enter on an inbox-strip row opens the ticket's page HERE, directly beneath
+// the recap header where the strip's notification row sat — the row expands
+// into the full page. It takes only the rows the page needs, growing all the
+// way down to the cockpit for a tall page (the transcript compresses to zero
+// before the editor gives a row), instead of the full-pane inbox surface.
+// While open it owns every keystroke — pages carry text inputs — so the
+// global key listener routes chunks to `handleKey` ahead of the strip and
+// roster; Esc at the page top closes back to the editor.
+//
+// The claim lifecycle mirrors the inbox surface's detail screen: claim on
+// open, heartbeat every 10s, resolve through the daemon on complete, release
+// on close. Review tickets and unreadable pages fall back to the full-pane
+// inbox seated on the row.
+//
+// The page itself comes from the daemon, addressed by the row's opaque inbox
+// ticket id. Refresh is driven by inbox activity rather than a watch on the
+// request directory: a `--replace` revision is a NEW directory selected in SQL
+// before the activity signal fires, so the directory the panel opened on never
+// sees the replacement. Each signal re-reads the ticket once and compares its
+// revision and state — a moved revision reloads, a terminal state closes.
+import { claimTicket, heartbeatClaim, releaseClaim } from '../../../core/human/claim.js';
+import { watchInboxActivity } from '../../../core/human/root.js';
+import { resolvePageComponents } from '../../../core/config.js';
+import { fillBar, stripSgr, truncate, REVERSE } from '../../../core/canvas/nav-render.js';
+import { cliClient } from '../../../commands/api-client.js';
+import { visibleWidth } from '../../inbox/tui/ansi.js';
+import { pageViewFromDTO, settledStatusOf } from '../../inbox/dto-adapt.js';
+import { PageAdapter } from '../../inbox/page-adapter.js';
+import { decodeInboxKey } from '../../inbox/tui/keys.js';
+import { daemonErrorMessage, resolveFailureKind, resolveTicketPage } from '../../inbox/resolve.js';
+import { editBufferInEditor } from '../../inbox/review/roundtrip.js';
+export function createTicketPanel(s, hooks) {
+    const { tui, pal } = s;
+    let session;
+    let submitting = false;
+    let lastCols = 0;
+    let lastRows = 0;
+    /** Content rows offered to the page: everything but the recap header and the
+     *  cockpit's minimum (activity · padding · editor · status) plus our own
+     *  title bar and closing rule. The frame clips to the rows actually free. */
+    const capRows = () => Math.max(3, tui.terminal.rows - 10);
+    const closeSession = (release) => {
+        const open = session;
+        if (open === undefined)
+            return;
+        session = undefined;
+        clearInterval(open.heartbeat);
+        open.unwatch();
+        open.adapter.close();
+        if (release)
+            releaseClaim(open.dir, open.token);
+        hooks.syncCursor();
+        hooks.refreshStrip();
+        tui.requestRender();
+    };
+    const complete = async (open, responses) => {
+        submitting = true;
+        try {
+            await resolveTicketPage(open.id, responses);
+            closeSession(false);
+            hooks.setNotice('Response sent');
+        }
+        catch (error) {
+            const failure = resolveFailureKind(error);
+            if (failure === 'unreachable' || failure === 'other') {
+                hooks.setNotice(daemonErrorMessage(error));
+                return; // keep the page open — nothing was submitted
+            }
+            closeSession(false);
+            hooks.setNotice(failure === 'already_settled' ? await resolvedElsewhereNotice(open.ticketId) : daemonErrorMessage(error));
+        }
+        finally {
+            submitting = false;
+        }
+    };
+    /** One read per activity signal decides everything: a moved revision is a
+     *  replacement, a terminal state is a settlement somewhere else. */
+    const onActivity = async (open) => {
+        if (session !== open || submitting)
+            return;
+        let page;
+        try {
+            page = await cliClient().getHumanInboxPage(open.ticketId);
+        }
+        catch (error) {
+            if (session !== open)
+                return;
+            closeSession(true);
+            hooks.setNotice(`Ticket could not be read: ${daemonErrorMessage(error)}`);
+            return;
+        }
+        if (session !== open || submitting)
+            return;
+        if (page.state === 'resolved' || page.state === 'canceled') {
+            closeSession(true);
+            hooks.setNotice(page.state === 'canceled' ? 'Ticket was canceled by its requester' : 'Ticket was resolved elsewhere');
+            return;
+        }
+        if (page.revision === open.revision)
+            return;
+        open.revision = page.revision;
+        try {
+            open.adapter.reload(pageViewFromDTO(page));
+        }
+        catch {
+            hooks.setNotice('Page could not be read');
+        }
+        tui.requestRender();
+    };
+    const editPageInput = (open) => {
+        const buffer = open.adapter.inputBuffer();
+        if (buffer === undefined)
+            return;
+        const resume = hooks.suspendForChild();
+        let result = { text: buffer };
+        try {
+            result = editBufferInEditor(buffer);
+        }
+        finally {
+            resume();
+            open.adapter.setInputBuffer(result.text);
+            if (result.error !== undefined)
+                hooks.setNotice(result.error);
+            tui.requestRender();
+        }
+    };
+    const open = async (ticket) => {
+        if (session !== undefined)
+            closeSession(true);
+        if (ticket.kind !== 'page') {
+            hooks.openInbox(ticket.dir);
+            return;
+        }
+        const claim = claimTicket(ticket.dir);
+        if (claim === null) {
+            hooks.setNotice('Ticket is being edited by another inbox');
+            return;
+        }
+        let view;
+        let revision;
+        try {
+            const page = await cliClient().getHumanInboxPage(ticket.inboxTicketId);
+            // The claim is a presenter lock, not settlement authority, so a request
+            // that settled between the row being listed and this read would still
+            // claim. This projection already carries the state that decides it.
+            if (page.state === 'resolved' || page.state === 'canceled') {
+                releaseClaim(ticket.dir, claim.token);
+                hooks.setNotice(settledStatusOf(page));
+                return;
+            }
+            view = pageViewFromDTO(page);
+            revision = page.revision;
+        }
+        catch {
+            releaseClaim(ticket.dir, claim.token);
+            hooks.openInbox(ticket.dir);
+            return;
+        }
+        // Awaiting the read gave another open (or a close) the chance to land first;
+        // that session owns the panel, so this one releases its claim and stops.
+        if (session !== undefined) {
+            releaseClaim(ticket.dir, claim.token);
+            return;
+        }
+        lastCols = Math.max(20, tui.terminal.columns - 2);
+        lastRows = capRows();
+        const entry = {
+            dir: ticket.dir,
+            id: ticket.id,
+            ticketId: ticket.inboxTicketId,
+            title: ticket.title,
+            token: claim.token,
+            revision,
+            adapter: new PageAdapter({
+                ticketId: ticket.inboxTicketId,
+                page: view,
+                productKinds: resolvePageComponents(),
+                cols: lastCols,
+                rows: lastRows,
+                onDirty: () => tui.requestRender(),
+                onBack: () => closeSession(true),
+                onComplete: (responses) => { void complete(entry, responses); },
+                onEditorRequest: () => editPageInput(entry),
+            }),
+            unwatch: () => { },
+            heartbeat: setInterval(() => {
+                if (session === entry)
+                    heartbeatClaim(entry.dir, entry.token);
+            }, 10_000),
+        };
+        entry.unwatch = watchInboxActivity(() => { void onActivity(entry); });
+        session = entry;
+        hooks.syncCursor();
+        hooks.refreshStrip();
+        tui.requestRender();
+    };
+    const handleKey = (data) => {
+        const entry = session;
+        if (entry === undefined)
+            return false;
+        const { input, key } = decodeInboxKey(data);
+        entry.adapter.handleKey(input, key);
+        tui.requestRender();
+        return true;
+    };
+    const component = {
+        render(width) {
+            const entry = session;
+            if (entry === undefined)
+                return [];
+            const cols = Math.max(20, width - 2);
+            const rows = capRows();
+            if (cols !== lastCols || rows !== lastRows) {
+                lastCols = cols;
+                lastRows = rows;
+                entry.adapter.resize(cols, rows);
+            }
+            // The strip row's highlight carries into the open page: the same
+            // reversed full-width bar, now a title bar, with a closing rule beneath
+            // the content so the page reads as one bounded region over the chat.
+            const header = fillBar(stripSgr(truncate(` ⚑ ${entry.title} · Esc closes`, width)), width, REVERSE);
+            // The body sits on the same background the crouter context cards use, so
+            // the open ticket reads as one solid panel distinct from the chat.
+            const bg = contextCardBg();
+            const body = trimTrailingBlank(entry.adapter.render()).map((line) => paintBg(` ${line}`, width, bg));
+            return [header, ...body, pal.border('─'.repeat(Math.max(0, width)))];
+        },
+        invalidate() { },
+    };
+    return {
+        component,
+        open,
+        handleKey,
+        close: () => closeSession(true),
+        active: () => session !== undefined,
+        currentDir: () => session?.dir,
+    };
+}
+/** Why a settlement was refused, in the panel's sentence case. */
+async function resolvedElsewhereNotice(ticketId) {
+    let status;
+    try {
+        status = settledStatusOf(await cliClient().getHumanInboxPage(ticketId));
+    }
+    catch (error) {
+        return `Ticket result is unreadable: ${daemonErrorMessage(error)}`;
+    }
+    return status.charAt(0).toUpperCase() + status.slice(1);
+}
+/** The SGR opening the theme's `customMessageBg` — the background the crouter
+ *  context cards use. pi shares its live theme across module loaders on this
+ *  well-known global (it exports no direct handle); a missing or incomplete
+ *  theme just means no fill, never a throw. */
+function contextCardBg() {
+    const t = globalThis[Symbol.for('@earendil-works/pi-coding-agent:theme')];
+    try {
+        return t?.getBgAnsi?.('customMessageBg');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fill one row with `bg` edge to edge, re-asserting it across the line's own
+ *  full resets and background resets so interior styling cannot punch holes. */
+function paintBg(line, width, bg) {
+    if (bg === undefined)
+        return line;
+    const kept = line.replaceAll('\x1b[0m', `\x1b[0m${bg}`).replaceAll('\x1b[49m', bg);
+    const pad = ' '.repeat(Math.max(0, width - visibleWidth(line)));
+    return `${bg}${kept}${pad}\x1b[49m`;
+}
+/** Short pages take only their rows: the adapter pads to its rectangle. */
+function trimTrailingBlank(lines) {
+    let end = lines.length;
+    while (end > 0 && stripSgr(lines[end - 1]).trim() === '')
+        end--;
+    return lines.slice(0, end);
+}

package/dist/clients/attach/chrome/widgets.d.ts

@@ -0,0 +1,9 @@
+import type { SessionState } from '../../../core/session-model/session-state.js';
+import type { AttachSession } from '../session/context.js';
+export interface ChromeWidgets {
+    /** Paint serializable extension widgets into their fixed cockpit slots. */
+    renderExtensionWidgets: () => void;
+    /** Paint the pending steering messages above the editor. */
+    renderQueued: () => void;
+}
+export declare function createChromeWidgets(ctx: Pick<AttachSession, 'tui' | 'pal' | 'containers'>, state: () => SessionState): ChromeWidgets;

package/dist/clients/attach/chrome/widgets.js

@@ -0,0 +1,51 @@
+// chrome/widgets.ts — the two broker-fed container painters: pi extension
+// widgets in their fixed cockpit slots, and the queued-steering panel above
+// the editor. Both read the folded `SessionState` the orchestrator owns, so it
+// arrives as a getter rather than a captured value.
+import { Text, truncateToWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { splitRecapLines } from './recap.js';
+export function createChromeWidgets(ctx, state) {
+    const { tui, pal } = ctx;
+    const { aboveWidgets, belowWidgets, queued } = ctx.containers;
+    /** Paint serializable extension widgets into their fixed cockpit slots. */
+    const renderExtensionWidgets = () => {
+        const session = state();
+        aboveWidgets.clear();
+        belowWidgets.clear();
+        // The recap widget is split: its goal line is painted by the pinned
+        // header, while its state line lands here in the widget's own cockpit
+        // slot, label stripped and faint.
+        const span = Math.max(1, (process.stdout.columns ?? 80) - 2);
+        for (const [key, widget] of Object.entries(session.display.widgets)) {
+            const recap = key === 'crtr-recap';
+            const lines = recap ? splitRecapLines(widget.lines).state : widget.lines;
+            const target = widget.placement === 'belowEditor' ? belowWidgets : aboveWidgets;
+            for (const line of lines) {
+                // Styled before wrapping so a wrapped continuation stays faint.
+                const styled = recap ? pal.faint(line) : line;
+                for (const wrapped of wrapTextWithAnsi(styled, span)) {
+                    target.addChild(new Text(wrapped, 1, 0));
+                }
+            }
+        }
+        tui.requestRender();
+    };
+    // Queued steering/follow-up messages, shown above the editor so you can SEE
+    // what is waiting (not just the footer count). Texts arrive on `queue_update`;
+    // the welcome snapshot carries only a count, so the panel fills from the first
+    // queue change after attach.
+    const renderQueued = () => {
+        const session = state();
+        queued.clear();
+        if (session.queued.length > 0) {
+            const span = Math.max(1, (process.stdout.columns ?? 80) - 4);
+            queued.addChild(new Text(pal.muted(`queued (${session.queued.length}):`), 1, 0));
+            for (const msg of session.queued) {
+                const oneLine = msg.text.replace(/\s+/g, ' ').trim();
+                queued.addChild(new Text(pal.faint(`  ⋯ ${truncateToWidth(oneLine, span, '…')}`), 1, 0));
+            }
+        }
+        tui.requestRender();
+    };
+    return { renderExtensionWidgets, renderQueued };
+}

package/dist/clients/attach/command.d.ts

@@ -0,0 +1,3 @@
+import type { BranchDef } from '../../core/command.js';
+import type { SubTier } from '../../core/help.js';
+export declare function registerAttach(namespace: string, tier: SubTier): BranchDef;

package/dist/clients/attach/command.js

@@ -0,0 +1,107 @@
+// command.ts — the LIGHT `crtr surface attach` command definition.
+//
+// This module holds only the command metadata (help schema, flags) and the
+// thin `run` entry. It is deliberately kept OFF the heavy pi-coding-agent module
+// graph so registering the `surface` subtree costs a cheap command-framework
+// load, not the ~363ms ESM load of the esbuild-bundled attach viewer (`viewer.ts`,
+// which pulls pi-coding-agent's babel/highlight.js). The viewer runtime is
+// dynamically imported inside `run`, so the bundle loads ONLY when a viewer
+// actually opens.
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { mark } from '../../core/timing.js';
+function attachToLeaf(namespace) {
+    return defineLeaf({
+        name: 'to',
+        description: 'attach an interactive terminal viewer to a node (reviving it if dormant)',
+        whenToUse: 'you want to WATCH or DRIVE a headless node live in this pane — it connects over the node\'s unix socket to the broker hosting the engine and renders the same chat stream. Attaches are writable by default, remote ones included (a remote canvas admits a writer only with message permission on the node); use --observer for read-only. A DORMANT node is revived first: crtrd runs reviveNode server-side, then the viewer streams over the broker\'s socket. The configured detach shortcuts leave the engine running',
+        help: {
+            name: `${namespace} attach to`,
+            summary: 'attach a terminal viewer to a headless node\'s running broker (writable by default, --observer for read-only); configured detach shortcuts leave the engine running',
+            params: [
+                {
+                    kind: 'positional',
+                    name: 'node',
+                    required: true,
+                    constraint: 'Node id to attach to. A dormant node is revived (server-side) before the viewer connects.',
+                },
+                {
+                    kind: 'flag',
+                    name: 'observer',
+                    type: 'bool',
+                    required: false,
+                    default: false,
+                    constraint: 'Attach READ-ONLY: request the observer role (needs only read permission). Default attaches, local or --canvas, request the writable controller role.',
+                },
+                {
+                    kind: 'flag',
+                    name: 'canvas',
+                    type: 'string',
+                    required: false,
+                    constraint: 'Attach against a remote canvas target configured via `crtr canvas config add` instead of the local canvas — connects over a relayed WebSocket to the target\'s preview endpoint using the relay token from the 0600 secrets store. A remote attach is writable by default and needs message permission on the node; with read permission only, the attach is refused and --observer is required. Omit for local (default): connects to the node\'s local unix socket, which must already exist in THIS machine\'s canvas.db. Does NOT honor `crtr canvas use` — this flag is the only way to attach remotely.',
+                },
+            ],
+            output: [
+                {
+                    name: 'note',
+                    type: 'string',
+                    required: false,
+                    constraint: 'Only set on the non-TTY/piped path (a static notice); the interactive path returns nothing.',
+                },
+            ],
+            outputKind: 'object',
+            effects: [
+                'Takes over the current pane in raw mode and renders the node\'s live engine stream until you use a configured detach shortcut or the broker exits.',
+                'As a writable controller: sends prompts/steers/dialog answers to the engine over the socket. As observer: read-only. Multiple writable viewers may drive the same broker.',
+                'A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects; this LOCAL process NEVER spawns pi and NEVER writes the session — it holds only a socket to the broker.',
+                'Outside a TTY (piped): prints a short notice and exits 0 — attach is an interactive program, not a pipe stage.',
+            ],
+        },
+        run: async (input) => {
+            const nodeId = input['node'];
+            const observer = input['observer'] ?? false;
+            const canvasName = input['canvas'];
+            const wakeParked = process.env['CRTR_ATTACH_WAKE_PARKED'] !== '0';
+            delete process.env['CRTR_ATTACH_WAKE_PARKED'];
+            // attach IS the in-pane interactive program — it only needs a TTY (crtr is
+            // tmux-only, but the pane itself is the surface). Non-TTY (piped) → static
+            // notice + exit, never a non-tmux interactive fallback. Guarded BEFORE the
+            // heavy import so a piped invocation never pays the viewer's load cost.
+            if (!process.stdout.isTTY) {
+                return {
+                    note: `crtr surface attach is an interactive terminal viewer — run it in a tmux pane (a TTY), not a pipe. Node: ${nodeId}`,
+                };
+            }
+            // The viewer runtime (the pi-coding-agent-heavy bundle) loads only here.
+            mark('viewer.bundle_import_start');
+            const { runAttach } = await import('./viewer.js');
+            mark('viewer.bundle_loaded');
+            await runAttach(nodeId, observer, canvasName, wakeParked);
+            // The session has sent its final broker frame and restored the terminal.
+            // Force this one-shot viewer process out now: pi's bundled UI dependencies
+            // can retain libuv handles after their visible work is finished. The exit
+            // handler registered by teardown still runs, so terminal restoration remains
+            // safe if the normal path raced a signal.
+            process.exit(0);
+        },
+        render: (result) => (result['note'] !== undefined ? String(result['note']) : ''),
+    });
+}
+export function registerAttach(namespace, tier) {
+    return defineBranch({
+        name: 'attach',
+        description: 'a terminal viewer for a headless node — connect over its socket and drive (or watch) the live engine',
+        whenToUse: 'you want to open a headless node live in this pane — watch its engine stream and drive it by typing, without the node ever running pi in your window. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects over a unix socket; this local process never starts the engine itself. Configured detach shortcuts leave the engine running.',
+        tier,
+        rootEntry: {
+            concept: 'a terminal viewer for a headless node — connect over its socket and drive (or watch) the live engine',
+            desc: 'attach a terminal viewer to a headless node',
+            useWhen: 'you want to open a headless node live in this pane — watch its engine stream and drive it by typing, without the node ever running pi in your window. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects over a unix socket; this local process never starts the engine itself. Configured detach shortcuts leave the engine running.',
+        },
+        help: {
+            name: `${namespace} attach`,
+            summary: 'attach a terminal viewer to a headless node\'s running broker',
+            model: 'The branch opens a viewer in the current pane. A TTY is required; piped invocation prints a notice and exits. Attaches request the writable controller role, local or --canvas; --observer is read-only. Multiple writable viewers may watch and drive one broker. Configured detach shortcuts detach cleanly and the engine runs on. A dormant node is revived server-side (crtrd runs reviveNode) before the viewer connects. If the broker exits, the viewer holds the pane and auto-reconnects — through a yield/refresh relaunch, and across dormancy until the node wakes again — reporting "broker gone" and exiting only when the node is terminal (done/dead/canceled) or deleted. This local process NEVER spawns pi or writes the session — it holds only a socket to the broker. --canvas <name> is the escape hatch for a node hosted on a different machine\'s canvas — see the leaf\'s own -h.',
+        },
+        children: [attachToLeaf(namespace)],
+    });
+}

package/dist/clients/attach/config.d.ts

@@ -0,0 +1,95 @@
+import { KeybindingsManager, type KeybindingsConfig, type MarkdownTheme } from '@earendil-works/pi-tui';
+/** pi's user config dir: `~/.pi/agent/`. */
+export declare function defaultAgentDir(): string;
+/**
+ * Read `~/.pi/agent/keybindings.json` (if present) and return the user's binding
+ * overrides. Tolerates a flat `{action: keys}` map or a `{keybindings: {...}}`
+ * wrapper; a missing/malformed file → `undefined` (fall back to defaults).
+ */
+export declare function loadUserKeybindings(agentDir?: string): KeybindingsConfig | undefined;
+export declare function createKeybindingsManager(agentDir?: string): KeybindingsManager;
+/** Register the manager on the editor's pi-tui instance too (see `editorPiTui`),
+ *  so the editor's newline/submit handling honors the same (user-overridden)
+ *  bindings as the rest of the viewer. Call once, after `createKeybindingsManager`. */
+export declare function mirrorKeybindingsToEditor(km: KeybindingsManager): Promise<void>;
+/** Mirror the negotiated kitty-keyboard-protocol flag onto the editor's pi-tui
+ *  instance (ProcessTerminal sets it only on OUR copy). Call after the terminal
+ *  has negotiated, i.e. after `tui.start()`. */
+export declare function mirrorKittyProtocolToEditor(active: boolean): Promise<void>;
+export declare function resolveFdPath(): Promise<string | null>;
+/**
+ * The user's theme name from pi settings — project (`<cwd>/.pi/settings.json`)
+ * overrides global (`~/.pi/agent/settings.json`). `undefined` → pi's default.
+ */
+export declare function loadThemeName(opts?: {
+    agentDir?: string;
+    cwd?: string;
+}): string | undefined;
+/** Resolve + activate the user's theme so the reused pi components (markdown,
+ *  editor, select-list themes) render at parity with the user's pi. */
+export declare function applyTheme(opts?: {
+    agentDir?: string;
+    cwd?: string;
+}): void;
+/**
+ * The named styling roles the attach chrome paints with, all theme-derived so the
+ * viewer matches whatever theme the user configured for pi. Each is a
+ * `str => str` colorizer applied to a whole token.
+ */
+export interface AttachPalette {
+    /** Headings / badges / panel titles — the theme accent (gold in the default). */
+    accent: (s: string) => string;
+    /** Live/active markers + the working spinner — the theme's bright accent (teal). */
+    active: (s: string) => string;
+    /** Informational values (model name, counts) — the theme link color (blue). */
+    info: (s: string) => string;
+    /** Secondary text — the theme muted gray. */
+    muted: (s: string) => string;
+    /** Least-important text — SGR faint (a style, not a hue). */
+    faint: (s: string) => string;
+    /** Border rules / frames — the theme border color. */
+    border: (s: string) => string;
+    /** Distinct-surface paint for a modal/overlay: wraps a WHOLE rendered line so
+     *  it sits on the theme's `selectedBg` background, edge to edge, re-asserting
+     *  the bg after every embedded full-reset so an inner `\x1b[0m` (a status dot,
+     *  the cursor bar) can't punch a hole in the surface. Closes with a bg-only
+     *  reset so the surface never bleeds past the line. */
+    surface: (s: string) => string;
+    /** Emphasis. */
+    bold: (s: string) => string;
+    /** Error text. pi's public theme API does NOT surface the `error` ThemeColor
+     *  (only markdown/select-list/settings-list derived colors are re-exported), so
+     *  this is the semantically-correct ANSI red — NOT an ad-hoc hardcode. */
+    error: (s: string) => string;
+    /** Warning / transient notices. Same constraint as `error` → ANSI yellow. */
+    warning: (s: string) => string;
+    /** Added display-diff prefixes/line numbers. pi exposes no foreground role here. */
+    diffAdded: (s: string) => string;
+    /** Removed display-diff prefixes/line numbers. pi exposes no foreground role here. */
+    diffRemoved: (s: string) => string;
+    /** Editor border for a SINGLE-`!` bash command (output IS added to the agent's
+     *  context). Dull/normal ANSI green — pi paints shell mode from its `bashMode`
+     *  theme color (default `green`), which pi does NOT re-export through its public
+     *  surface, so like `error`/`warning` this is the semantically-correct ANSI green. */
+    bashMode: (s: string) => string;
+    /** Editor border for a `!!` bash command (output is HIDDEN from the agent).
+     *  BRIGHT ANSI green, so the more consequential "agent won't see this" form
+     *  reads as visually hotter than the plain `!`. */
+    bashModeAlt: (s: string) => string;
+}
+/** Markdown theme for the attach transcript. Fenced code keeps pi's native
+ *  shape and syntax, but its content is painted on a distinct theme surface. */
+export declare function attachMarkdownTheme(): MarkdownTheme;
+/**
+ * Build the attach chrome's color palette from the LIVE theme. Call AFTER
+ * `applyTheme()` — the colors are pulled from pi's `getMarkdownTheme()` /
+ * `getSelectListTheme()`, which read the active theme singleton at call time.
+ *
+ * pi does not re-export the raw `Theme` instance (its `.` export map omits the
+ * `theme` const and `getEditorTheme`/`getTheme`), so the accent/border/muted hues
+ * are sourced from the markdown + select-list theme colorizers, which ARE
+ * re-exported and are themselves backed by `theme.fg(...)`. The two semantic
+ * colors pi never exposes through that surface — `error`/`warning` — fall back to
+ * standard ANSI red/yellow.
+ */
+export declare function attachPalette(): AttachPalette;