@north-light/api 0.3.579 → 0.3.587

package/dist/clients/attach/session/surface-host.d.ts

@@ -0,0 +1,65 @@
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import type { SurfaceComponent, SurfaceHandle, SurfaceHost } from '../../surfaces/host.js';
+import type { MouseReporting } from './mouse.js';
+/** The status line's notice options, which the host preserves on both paths. */
+export interface NoticeOptions {
+    /** Keep the notice up until it is replaced or cleared, with no auto-clear. */
+    sticky?: boolean;
+}
+export interface ViewerSurfaceHostOptions {
+    tui: TUI;
+    mouse: MouseReporting;
+    /** The host's assigned row count; surfaces never read terminal geometry. */
+    rows: () => number;
+    /** Fallback notice sink used when no surface is mounted. */
+    statusNotice: (text: string, opts?: NoticeOptions) => void;
+    /** Styling supplied by the viewer's status-line palette. */
+    formatNotice: (text: string) => string;
+    noticeMs: number;
+    /** The session facts; the host itself publishes `selfPane` from below. */
+    capabilities: Omit<SurfaceHost['capabilities'], 'selfPane'>;
+    selfPane?: string;
+}
+/** The viewer's one host for full-pane surfaces. */
+export declare class ViewerSurfaceHost implements SurfaceHost {
+    readonly capabilities: SurfaceHost['capabilities'];
+    private readonly tui;
+    private readonly mouse;
+    private readonly getRows;
+    private readonly statusNotice;
+    private readonly formatNotice;
+    private readonly noticeMs;
+    private readonly selfPane;
+    private readonly stack;
+    private noticeOverlay;
+    private noticeTimer;
+    constructor(options: ViewerSurfaceHostOptions);
+    mount(component: SurfaceComponent, opts?: {
+        focus?: Component;
+    }): SurfaceHandle;
+    /**
+     * The one visible notice channel. Surfaces call this with a message only; the
+     * viewer routes its whole notice verb through here, so both status-line
+     * semantics survive a mounted surface: an empty string clears the current
+     * notice rather than painting a bare warning icon, and `sticky` suppresses the
+     * auto-clear for a condition that is not time-bounded (a reconnect loop, an
+     * armed confirmation).
+     */
+    notice(text: string, opts?: NoticeOptions): void;
+    suspendForChild(): () => void;
+    focusNode(nodeId: string): Promise<boolean>;
+    pickReviewFile(spec: {
+        candidates: readonly string[];
+        cwd: string;
+        title?: string;
+    }): Promise<string | null>;
+    /** Offer wheel input to the topmost surface only. */
+    handleWheel(direction: 'up' | 'down', lines: number): boolean;
+    /** Whether a full-pane surface currently owns input. */
+    hasFullPaneSurface(): boolean;
+    /** Close the whole stack before the viewer tears down its TUI. */
+    closeAll(): void;
+    private closeEntry;
+    private disposeNotice;
+    private disposeNoticeOverlay;
+}

package/dist/clients/attach/session/surface-host.js

@@ -0,0 +1,256 @@
+import { truncateToWidth, } from '@earendil-works/pi-tui';
+import { cliClient } from '../../../commands/api-client.js';
+import { focusViewer } from '../../../core/runtime/focus-viewer.js';
+import { daemonErrorMessage } from '../../inbox/resolve.js';
+import { buildFileReviewPicker } from '../overlays/file-review.js';
+import { reportInvariant as report } from './invariant.js';
+import { SurfaceFrame } from './surface-frame.js';
+const SURFACE_OVERLAY_OPTIONS = {
+    anchor: 'top-left',
+    width: '100%',
+    maxHeight: '100%',
+    margin: 0,
+};
+const NOTICE_OVERLAY_OPTIONS = {
+    anchor: 'top-left',
+    width: '100%',
+    margin: 0,
+    nonCapturing: true,
+};
+/** The viewer's one host for full-pane surfaces. */
+export class ViewerSurfaceHost {
+    capabilities;
+    tui;
+    mouse;
+    getRows;
+    statusNotice;
+    formatNotice;
+    noticeMs;
+    selfPane;
+    stack = [];
+    noticeOverlay;
+    noticeTimer;
+    constructor(options) {
+        this.tui = options.tui;
+        this.mouse = options.mouse;
+        this.getRows = options.rows;
+        this.statusNotice = options.statusNotice;
+        this.formatNotice = options.formatNotice;
+        this.noticeMs = options.noticeMs;
+        this.selfPane = options.selfPane;
+        this.capabilities = { ...options.capabilities, selfPane: options.selfPane };
+    }
+    mount(component, opts) {
+        this.disposeNotice();
+        const frame = new SurfaceFrame(component, opts?.focus ?? component, this.getRows);
+        const overlay = this.tui.showOverlay(frame, SURFACE_OVERLAY_OPTIONS);
+        const entry = { component, frame, overlay, cleanup: [], closed: false, closing: false };
+        const previous = this.stack[this.stack.length - 1];
+        if (previous)
+            previous.overlay.setHidden(true);
+        this.stack.push(entry);
+        return {
+            close: () => this.closeEntry(entry, true),
+            invalidate: () => {
+                if (!entry.closed && this.stack[this.stack.length - 1] === entry)
+                    this.tui.requestRender();
+            },
+            onClose: (fn) => {
+                if (entry.closed || entry.closing) {
+                    reportInvariant('onClose registered after surface close');
+                    return;
+                }
+                entry.cleanup.push(fn);
+            },
+        };
+    }
+    /**
+     * The one visible notice channel. Surfaces call this with a message only; the
+     * viewer routes its whole notice verb through here, so both status-line
+     * semantics survive a mounted surface: an empty string clears the current
+     * notice rather than painting a bare warning icon, and `sticky` suppresses the
+     * auto-clear for a condition that is not time-bounded (a reconnect loop, an
+     * armed confirmation).
+     */
+    notice(text, opts) {
+        this.disposeNotice();
+        if (this.stack.length === 0) {
+            this.statusNotice(text, opts);
+            return;
+        }
+        if (text === '')
+            return;
+        const notice = new NoticeOverlay(() => this.formatNotice(text));
+        this.noticeOverlay = this.tui.showOverlay(notice, NOTICE_OVERLAY_OPTIONS);
+        if (opts?.sticky !== true && this.noticeMs > 0) {
+            this.noticeTimer = setTimeout(() => {
+                this.noticeTimer = undefined;
+                this.disposeNoticeOverlay();
+            }, this.noticeMs);
+        }
+    }
+    suspendForChild() {
+        this.tui.stop();
+        return () => {
+            this.tui.start();
+            this.mouse.reassert();
+            this.tui.invalidate();
+            this.tui.requestRender(true);
+        };
+    }
+    async focusNode(nodeId) {
+        if (!this.capabilities.canFocusNode || this.selfPane === undefined || this.selfPane === '') {
+            this.notice('Focusing a node needs a local viewer in tmux');
+            return false;
+        }
+        try {
+            const client = cliClient();
+            const node = await client.getNode(nodeId);
+            const result = await focusViewer(client, nodeId, {
+                pane: this.selfPane,
+                cwd: node.cwd,
+                name: node.name,
+            });
+            if (!result.focused)
+                this.notice('Could not open that node’s viewer');
+            return result.focused;
+        }
+        catch (error) {
+            this.notice(daemonErrorMessage(error));
+            return false;
+        }
+    }
+    pickReviewFile(spec) {
+        return new Promise((resolve) => {
+            let handle;
+            let settled = false;
+            const settle = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+                handle.close();
+            };
+            const picker = buildFileReviewPicker(spec.candidates, spec.cwd, (file) => settle(file), () => settle(null), (message) => this.notice(message));
+            handle = this.mount(titled(picker.component, spec.title), { focus: picker.focus });
+            handle.onClose(() => settle(null));
+        });
+    }
+    /** Offer wheel input to the topmost surface only. */
+    handleWheel(direction, lines) {
+        return this.stack[this.stack.length - 1]?.component.handleWheel?.(direction, lines) ?? false;
+    }
+    /** Whether a full-pane surface currently owns input. */
+    hasFullPaneSurface() {
+        return this.stack.length > 0;
+    }
+    /** Close the whole stack before the viewer tears down its TUI. */
+    closeAll() {
+        const bottom = this.stack[0];
+        if (bottom)
+            this.closeEntry(bottom, false);
+        this.disposeNotice();
+    }
+    closeEntry(entry, restore) {
+        if (entry.closed || entry.closing)
+            return;
+        const index = this.stack.indexOf(entry);
+        if (index === -1) {
+            entry.closed = true;
+            return;
+        }
+        entry.closing = true;
+        // Closing a parent owns every descendant. Close top-down, without
+        // restoring an intermediate surface that is about to be closed too.
+        while (this.stack.indexOf(entry) !== -1) {
+            const currentIndex = this.stack.indexOf(entry);
+            const child = this.stack[currentIndex + 1];
+            if (!child)
+                break;
+            this.closeEntry(child, false);
+        }
+        try {
+            entry.overlay.hide();
+        }
+        catch (error) {
+            reportInvariant(`surface overlay hide failed: ${errorMessage(error)}`);
+        }
+        for (const cleanup of entry.cleanup) {
+            try {
+                const result = cleanup();
+                if (result && typeof result.then === 'function') {
+                    void result.catch((error) => reportInvariant(`surface cleanup failed: ${errorMessage(error)}`));
+                }
+            }
+            catch (error) {
+                reportInvariant(`surface cleanup failed: ${errorMessage(error)}`);
+            }
+        }
+        entry.cleanup.length = 0;
+        entry.closed = true;
+        entry.closing = false;
+        const currentIndex = this.stack.indexOf(entry);
+        if (currentIndex !== -1)
+            this.stack.splice(currentIndex, 1);
+        if (restore) {
+            // A notice belongs to the surface it was raised over, so it goes when that
+            // surface does — including when the stack empties and no lower surface is
+            // left to restore, which would otherwise strand the overlay above the
+            // bare cockpit.
+            this.disposeNotice();
+            const top = this.stack[this.stack.length - 1];
+            if (top)
+                top.overlay.setHidden(false);
+        }
+    }
+    disposeNotice() {
+        this.disposeNoticeOverlay();
+        if (this.noticeTimer !== undefined) {
+            clearTimeout(this.noticeTimer);
+            this.noticeTimer = undefined;
+        }
+    }
+    disposeNoticeOverlay() {
+        this.noticeOverlay?.hide();
+        this.noticeOverlay = undefined;
+    }
+}
+class NoticeOverlay {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+    render(width) {
+        return [truncateToWidth(this.text(), Math.max(0, width), '', true)];
+    }
+    invalidate() { }
+}
+/**
+ * Apply an optional picker title without giving the host a second picker. A
+ * surface owes the host exactly its assigned rows, so this fills the rectangle
+ * the picker's natural height leaves short instead of handing the frame a
+ * three-row component and tripping its invariant on every render.
+ */
+function titled(component, title) {
+    let rows = 0;
+    return {
+        setRows: (value) => {
+            rows = Math.max(0, Math.floor(value));
+        },
+        render: (width) => {
+            const lines = component.render(width);
+            const body = title === undefined ? lines : [truncateToWidth(title, Math.max(0, width), '', true), ...lines.slice(1)];
+            const frame = body.slice(0, rows);
+            while (frame.length < rows)
+                frame.push('');
+            return frame;
+        },
+        invalidate: () => component.invalidate(),
+    };
+}
+function reportInvariant(message) {
+    report('surface-host', message);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/clients/attach/session/teardown.d.ts

@@ -0,0 +1,30 @@
+import type { AttachSession } from './context.js';
+export type TeardownReason = 'detach' | 'broker-gone' | 'signal' | 'node-done';
+export type TeardownSession = Pick<AttachSession, 'nodeId' | 'remote' | 'tui' | 'socket'>;
+export interface TeardownHooks {
+    /** Stop everything this viewer runs locally — timers, the graph overlay, the
+     *  pane tag, the global key listener, the chat view's animations. Runs FIRST,
+     *  before the socket is told anything, so nothing can fire into a dead socket. */
+    stopLocal: () => void;
+    /** The last socket-level error, so a broker-gone teardown can report the
+     *  precise reason (e.g. an oversized-frame overflow) instead of the generic
+     *  message. Read at teardown time, not captured at wiring time. */
+    lastSocketError: () => string | undefined;
+    /** This viewer's tmux pane, as self-tagged at startup. Used only by the
+     *  node-done path to close our own pane. */
+    tagPane: () => string | undefined;
+}
+export interface AttachTeardown {
+    /** Resolves when the session has ended — `runAttach` awaits this. */
+    readonly done: Promise<void>;
+    /** End the session. Idempotent: the first reason wins, later calls no-op. */
+    teardown: (reason: TeardownReason) => void;
+    /** True once teardown has begun. Long-running loops must check this. */
+    isTornDown: () => boolean;
+    /** Register SIGTERM/SIGHUP/SIGINT. Call only AFTER every collaborator
+     *  `stopLocal` touches exists, or a signal races a half-built session.
+     *  (Raw mode swallows ctrl+c as data, so SIGINT is unlikely — handled for
+     *  completeness.) */
+    installSignalHandlers: () => void;
+}
+export declare function createTeardown(s: TeardownSession, hooks: TeardownHooks): AttachTeardown;

package/dist/clients/attach/session/teardown.js

@@ -0,0 +1,94 @@
+// session/teardown.ts — how an attach session ends, exactly once.
+//
+// Four reasons converge here and they are NOT interchangeable:
+//   detach      the user left. Say `bye` so the broker drops this viewer; the
+//               ENGINE RUNS ON (the documented B2 contract). No reaping — see
+//               the note in `teardown` below for why that moved to prune.
+//   broker-gone the socket died and the reconnect supervisor gave up on a node
+//               that is dead/canceled/reaped. Print the precise socket error if
+//               we have one, and leave the pane as a visible corpse.
+//   node-done   the node reached `done` — a CLEAN finalize, not a break. Print
+//               a friendly line and close our OWN pane so the slot clears
+//               instead of stranding a frozen "broker gone" corpse.
+//   signal      a pane kill or daemon teardown.
+//
+// TWO ORDERING RULES the sequence exists to enforce, both easy to break by
+// accident: local activity stops BEFORE the socket does (a timer that fires
+// against a closed socket throws inside a torn-down TUI), and the terminal is
+// restored BEFORE anything is written to stderr (writing through a live
+// alternate-screen frame paints raw bytes over it). `restore` is additionally
+// registered on `process.exit` so a hard exit still un-hides the cursor.
+//
+// This module also owns the `tornDown` latch, which is the session's one
+// "stop doing things" fact — the chrome refresh loop and the identity refresh
+// read it through `isTornDown()` so they cannot outlive the viewer.
+import { closePane, currentTmux, inTmux } from '../../../core/runtime/placement-tmux.js';
+import { FOCUS_REPORTING_OFF } from './focus-events.js';
+export function createTeardown(s, hooks) {
+    const { tui, socket, nodeId, remote } = s;
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        try {
+            process.stdout.write(FOCUS_REPORTING_OFF);
+            tui.stop();
+        }
+        catch {
+            /* best-effort terminal restore */
+        }
+    };
+    process.once('exit', restore);
+    let tornDown = false;
+    let resolveDone;
+    const done = new Promise((r) => {
+        resolveDone = r;
+    });
+    const teardown = (reason) => {
+        if (tornDown)
+            return;
+        tornDown = true;
+        hooks.stopLocal();
+        // A clean detach tells the broker to drop this viewer (the engine runs on);
+        // on broker-gone the socket is already dead, so skip `bye`.
+        if (reason === 'detach')
+            socket.send({ type: 'bye' });
+        socket.close();
+        restore();
+        // A clean detach leaves the broker running (the engine runs on) — the
+        // documented "detach leaves the broker running" contract. Teardown reaps
+        // nothing per-action: reaping an empty husk here would need a direct
+        // canvas.db mutation the API-only client cannot reach, and no per-node reap
+        // route exposes one. Disposition of an abandoned empty broker: `crtr canvas
+        // prune --empty` (reapEmptyNodes) sweeps it, but only ONCE its pid is dead
+        // — it deliberately spares a LIVE broker as the daemon's domain. So an empty
+        // broker lingers until it idle-releases (or is closed) to a dormant husk,
+        // then prune reaps it, leaving a narrow, transient live-empty window — the
+        // only faithful option under the API boundary. A per-node reap route would
+        // buy immediate cleanup (future work).
+        if (reason === 'broker-gone') {
+            const msg = hooks.lastSocketError() ??
+                `broker gone — node ${nodeId} is no longer running its engine. Re-focus to reattach.`;
+            process.stderr.write(`\n${msg}\n`);
+        }
+        // Local tmux only — a remote attach has no local pane to close, and a
+        // non-tmux/pipe invocation just prints the line. Pane close is pane-granular
+        // (siblings in a swap-pane window survive); the daemon reconciles the
+        // now-gone viewer row.
+        if (reason === 'node-done') {
+            process.stderr.write(`\n✓ node ${nodeId} finished — final report submitted.\n`);
+            const pane = hooks.tagPane() ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+            if (!remote && pane !== undefined && inTmux())
+                closePane(pane);
+        }
+        resolveDone();
+    };
+    const installSignalHandlers = () => {
+        const onSignal = () => teardown('signal');
+        process.once('SIGTERM', onSignal);
+        process.once('SIGHUP', onSignal);
+        process.once('SIGINT', onSignal);
+    };
+    return { done, teardown, isTornDown: () => tornDown, installSignalHandlers };
+}

package/dist/clients/attach/session/transcript-search.d.ts

@@ -0,0 +1,20 @@
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import type { AttachPalette } from '../config.js';
+import type { TranscriptViewport } from '../render/viewport.js';
+import type { TranscriptSearchModel } from '../render/transcript-search.js';
+import { type AttachBindings } from './bindings.js';
+export interface TranscriptSearch {
+    /** The bar, mounted as a fixed frame slot; renders nothing while closed. */
+    readonly component: Component;
+    /** Enter search. A repeat open re-edits the previous query. */
+    open(): void;
+    close(): void;
+    /** True when search owns the key chunk. Declines everything it does not own,
+     *  so scroll bindings and ordinary editor input still work while it is up. */
+    handleKey(data: string): boolean;
+}
+export interface TranscriptSearchHooks {
+    bindings: () => AttachBindings;
+    setNotice: (message: string) => void;
+}
+export declare function createTranscriptSearch(tui: TUI, pal: AttachPalette, viewport: TranscriptViewport, model: TranscriptSearchModel, hooks: TranscriptSearchHooks): TranscriptSearch;

package/dist/clients/attach/session/transcript-search.js

@@ -0,0 +1,151 @@
+// session/transcript-search.ts — incremental transcript search: the mode, its
+// one-row bar, and the keys that drive it.
+//
+// The viewer keeps the terminal in the normal buffer and renders exactly one
+// screenful per frame, so tmux copy-mode's `/` only ever sees what is already
+// on screen. Searching the transcript therefore has to happen here, against the
+// same rendered rows the viewport draws.
+//
+// Two states, both visible on the bar. EDITING owns typed characters and jumps
+// as you type; BROWSING owns only n/N (and `/` to edit again), and any other
+// printable key closes search and falls through to the editor, so getting back
+// to typing a prompt never needs a deliberate dismissal.
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import { visibleWidth } from '../../../core/canvas/nav-render.js';
+import { formatBinding } from '../../../core/keybindings/index.js';
+import { matchesAttachBinding } from './bindings.js';
+/** A chunk is typed text only when every code point in it is printable — an
+ *  escape sequence, control byte, or paste of either is somebody else's. */
+function printableText(data) {
+    if (data === '')
+        return undefined;
+    for (const character of data) {
+        const code = character.codePointAt(0);
+        if (code < 0x20 || code === 0x7f)
+            return undefined;
+    }
+    return data;
+}
+export function createTranscriptSearch(tui, pal, viewport, model, hooks) {
+    let mode = 'closed';
+    /** Where the query search started from, so editing re-seeks from one place
+     *  instead of chasing its own jumps character by character. */
+    let anchor = 0;
+    let draft = '';
+    const width = () => tui.terminal.columns;
+    const jump = (match) => {
+        if (match !== undefined)
+            viewport.scrollToLine(match.line);
+        tui.requestRender();
+    };
+    const applyDraft = () => {
+        model.setQuery(draft, anchor);
+        jump(model.current(width()));
+    };
+    const close = () => {
+        mode = 'closed';
+        draft = '';
+        model.setQuery('', undefined);
+        tui.requestRender();
+    };
+    const open = () => {
+        if (mode === 'closed')
+            anchor = viewport.topLine() ?? 0;
+        mode = 'editing';
+        draft = model.query();
+        tui.requestRender();
+    };
+    const step = (direction) => {
+        const match = model.step(width(), direction);
+        if (match === undefined) {
+            hooks.setNotice(`No matches for “${model.query()}”`);
+            return;
+        }
+        jump(match);
+    };
+    const component = {
+        render(renderWidth) {
+            if (mode === 'closed')
+                return [];
+            const { index, total } = model.status(renderWidth);
+            const left = mode === 'editing'
+                ? `${pal.accent('⌕')} ${draft}${pal.accent('▌')}`
+                : `${pal.accent('⌕')} ${draft}`;
+            const count = total === 0
+                ? (model.query() === '' ? pal.faint('type to search what is on screen') : pal.error('no matches'))
+                : pal.info(`${index}/${total}`);
+            const hints = mode === 'editing'
+                ? pal.faint('enter browse · esc cancel')
+                : pal.faint([
+                    `${formatBinding(hooks.bindings(), 'crtr.attach.search.next')} next`,
+                    `${formatBinding(hooks.bindings(), 'crtr.attach.search.previous')} prev`,
+                    `${formatBinding(hooks.bindings(), 'crtr.attach.search.edit')} edit`,
+                    `${formatBinding(hooks.bindings(), 'crtr.attach.search.close')} close`,
+                ].join(' · '));
+            const right = `${count}  ${hints}`;
+            const gap = renderWidth - visibleWidth(left) - visibleWidth(right) - 2;
+            const line = gap < 1
+                ? truncateToWidth(` ${left}`, renderWidth, '', true)
+                : ` ${left}${' '.repeat(gap)}${right} `;
+            return [line];
+        },
+        invalidate() {
+            /* Rendered fresh from the model on every frame. */
+        },
+    };
+    const handleKey = (data) => {
+        if (mode === 'closed')
+            return false;
+        const bindings = hooks.bindings();
+        if (matchesAttachBinding(bindings, 'crtr.attach.search.close', data)) {
+            close();
+            return true;
+        }
+        if (mode === 'editing') {
+            if (data === '\x03') {
+                close();
+                return true;
+            }
+            if (data === '\r' || data === '\n') {
+                if (model.status(width()).total === 0) {
+                    hooks.setNotice(draft === '' ? 'Type something to search for' : `No matches for “${draft}”`);
+                    return true;
+                }
+                mode = 'browsing';
+                tui.requestRender();
+                return true;
+            }
+            if (data === '\x7f' || data === '\b') {
+                draft = [...draft].slice(0, -1).join('');
+                applyDraft();
+                return true;
+            }
+            const typed = printableText(data);
+            if (typed === undefined)
+                return false;
+            draft += typed;
+            applyDraft();
+            return true;
+        }
+        if (matchesAttachBinding(bindings, 'crtr.attach.search.next', data) || data === '\r' || data === '\n') {
+            step(1);
+            return true;
+        }
+        if (matchesAttachBinding(bindings, 'crtr.attach.search.previous', data)) {
+            step(-1);
+            return true;
+        }
+        if (matchesAttachBinding(bindings, 'crtr.attach.search.edit', data)) {
+            open();
+            return true;
+        }
+        // Browsing holds only its own gestures. Ordinary typing means the user is
+        // done searching: dismiss and let the chunk land in the editor as typed.
+        if (printableText(data) !== undefined) {
+            close();
+            return false;
+        }
+        return false;
+    };
+    return { component, open, close, handleKey };
+}

package/dist/clients/attach/session/whip-achievements.d.ts

@@ -0,0 +1,4 @@
+import type { AttachPalette } from '../config.js';
+/** Count one whip and celebrate the milestone it reaches, if any. Called once
+ *  per whip that actually reached the agent. */
+export declare function recordWhip(pal: AttachPalette, filePath?: string): void;