@north-light/api 0.3.579 → 0.3.587

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

@@ -0,0 +1,294 @@
+// chrome/roster.ts — the inline subagent scroll+swap roster below the editor.
+//
+// The one report list below the editor doubles as a navigable roster. ↓ at the
+// editor's visual bottom drops the cursor into the list; within it ↑/↓ move the
+// highlight, ↑ off the TOP row returns to the editor, ↓ CLAMPS at the bottom,
+// Enter opens the row (SWAPS this pane in place onto a node, or opens the wait
+// detail surface for a cron/bash/review/object row: a cron row the Inspector's
+// schedule section, a bash row the Inspector's jobs section, a review row the
+// review's companion viewer, an object-wait row the watched object's
+// `crtr canvas read` in a popup),
+// Esc / any typed key returns to the editor. Disabled entirely for a REMOTE
+// attach: a remote graph id has no local pane to swap into and no local
+// jobs/crons to inspect.
+//
+// ONE EDITOR COUPLING IS OWNED HERE, deliberately and exclusively:
+// `editor.onCursorDownAtBottom` — the boundary handoff. The editor owns native
+// ↓ navigation and calls this only after both its visual cursor and its prompt
+// history are exhausted, which makes the handoff a direct boundary transition
+// rather than a global-listener replay. The hollow-cursor state lives in
+// session/pane-focus.ts; the roster reports its held highlight through
+// `active()` and pokes `hooks.syncCursor` on every repaint.
+//
+// Repainting a selection is purely local: canvas reads can traverse the whole
+// graph, so `refresh()` rebuilds the cached rows asynchronously while arrow
+// movement only reverses the selected cached row and renders immediately.
+import { execFile } from 'node:child_process';
+import { Text, decodeKittyPrintable, matchesKey } from '@earendil-works/pi-tui';
+import { cliClient } from '../../../commands/api-client.js';
+import { focusNode } from '../../../core/runtime/focus-viewer.js';
+import { daemonErrorMessage } from '../../inbox/resolve.js';
+import { toBashJobStatus } from './bash-jobs.js';
+import { fillBar, fillWidth, stripSgr, REVERSE } from '../../../core/canvas/nav-render.js';
+import { buildCanvasPanelLines } from './canvas-panels.js';
+/** How long an armed `x` waits for its `y`. */
+const ARM_TIMEOUT_MS = 15_000;
+export function createRoster(s, hooks) {
+    const { editor, tui, pal, nodeId, remote, role, canvasSource } = s;
+    // The node's app comes from the node row the viewer already holds; resolving it from canvas.db would open the db in this process.
+    const reports = s.containers.reports;
+    let items = [];
+    let selKey; // undefined ⇒ roster inactive (editor owns the cursor)
+    // Set by the in-place swap to the previously open node id. That node becomes
+    // visible in the new viewer's self-excluding roster, preserving cursor continuity.
+    let autoSelect = process.env['CRTR_ATTACH_ROSTER'];
+    if (autoSelect !== undefined)
+        delete process.env['CRTR_ATTACH_ROSTER'];
+    // Armed job cancellation: `x` on the bash row names the job, `y` confirms.
+    // Held here (not in the item list) so any other key, a selection move, or a
+    // rebuild that retires the job drops it — a stale confirmation must never
+    // kill a job the user is no longer looking at.
+    let pendingKill;
+    let killTimer;
+    const paint = () => {
+        hooks.syncCursor();
+        reports.clear();
+        for (const item of items) {
+            const selected = item.key === selKey;
+            // Selected rows highlight as ONE uniform bar: strip the row's own colours
+            // first, because reverse-video turns every tinted span into a coloured
+            // block and the bar reads as a patchwork otherwise.
+            reports.addChild(new Text(selected ? fillBar(stripSgr(item.line), fillWidth(), REVERSE) : item.line, 1, 0));
+        }
+        tui.requestRender();
+    };
+    const listJobs = async () => (await cliClient().listBashJobs(nodeId)).map(toBashJobStatus);
+    const refresh = async () => {
+        const ownedCrons = remote
+            ? []
+            : (await cliClient().listCrons({ created_by: nodeId })).filter((cron) => cron.created_by === nodeId);
+        // Local-only, same gate as ownedCrons: a local nodeId collision must never leak background jobs.
+        const bashJobs = remote ? [] : await listJobs();
+        // Reviews this node is the origin of: the person still holds an open one, or
+        // the daemon is finishing a submitted one behind its companion. Local-only,
+        // like the crons above — a remote graph id has no local review surface.
+        const reviews = remote
+            ? []
+            : (await cliClient().listReviews({ state: 'open', origin_node_id: nodeId })).reviews;
+        const built = await buildCanvasPanelLines(nodeId, hooks.asks(), pal, canvasSource, ownedCrons, bashJobs, reviews);
+        items = built.items;
+        // After an in-place swap, land on the previously open node, which has taken
+        // the swapped-to node's place in this self-excluding roster.
+        if (autoSelect !== undefined) {
+            const previousId = autoSelect;
+            autoSelect = undefined;
+            const previous = items.find((item) => item.kind === 'node' && item.nodeId === previousId);
+            if (previous !== undefined)
+                selKey = previous.key;
+        }
+        // The selected row may have vanished (child finished, ask answered, cron
+        // fired) — drop back to the editor so no ghost highlight lingers.
+        if (selKey !== undefined && !items.some((item) => item.key === selKey)) {
+            selKey = undefined;
+        }
+        if (pendingKill !== undefined && !bashJobs.some((job) => job.jobId === pendingKill?.jobId))
+            disarmKill(true);
+        paint();
+    };
+    /** Drop an armed stop, and the question with it. */
+    const disarmKill = (clearNotice) => {
+        if (killTimer !== undefined) {
+            clearTimeout(killTimer);
+            killTimer = undefined;
+        }
+        if (pendingKill === undefined)
+            return;
+        pendingKill = undefined;
+        if (clearNotice)
+            hooks.setNotice('');
+    };
+    const exit = () => {
+        disarmKill(true);
+        if (selKey !== undefined) {
+            selKey = undefined;
+            paint();
+        }
+    };
+    /** The printable character a keystroke carries, under both plain and Kitty
+     *  encodings — the roster's own `x`/`y` verbs are letters, not chords. */
+    const typed = (data) => decodeKittyPrintable(data) ?? (data.length === 1 ? data : undefined);
+    /** First line of a command, for the confirmation prompt. */
+    const commandHead = (command, cap = 40) => {
+        const line = (command.split('\n')[0] ?? '').replace(/\s+/g, ' ').trim();
+        return line.length > cap ? `${line.slice(0, cap - 1)}…` : line;
+    };
+    /** `x` on the bash row: arm cancellation for the one live job. With several
+     *  jobs there is no single target on a summary row, so send the user into the
+     *  Inspector, where each job is separately selectable. */
+    const armKill = async () => {
+        if (role !== 'controller') {
+            hooks.setNotice('Read-only observer attach — cannot stop background jobs');
+            return;
+        }
+        const jobs = await listJobs();
+        if (jobs.length === 0) {
+            hooks.setNotice('Background job already finished');
+            hooks.requestChromeRefresh();
+            return;
+        }
+        if (jobs.length > 1) {
+            hooks.setNotice(`${jobs.length} background jobs — press ↵ to pick one in the Inspector`);
+            return;
+        }
+        const job = jobs[0];
+        pendingKill = { jobId: job.jobId, label: commandHead(job.command) };
+        hooks.setNotice(`Stop “${pendingKill.label}”? Press y to confirm.`, { sticky: true });
+        // An unanswered question expires rather than sitting armed forever — a `y`
+        // typed minutes later belongs to whatever the user is doing then.
+        killTimer = setTimeout(() => disarmKill(true), ARM_TIMEOUT_MS);
+    };
+    const confirmKill = () => {
+        const target = pendingKill;
+        if (target === undefined)
+            return;
+        disarmKill(false);
+        hooks.setNotice(`Stopping “${target.label}”…`);
+        execFile('crtr', ['node', 'bash', 'kill', target.jobId, '--node', nodeId], (err) => {
+            hooks.setNotice(err === null ? `Stopped “${target.label}”.` : `Could not stop the job: ${err.message.split('\n')[0]}`);
+            hooks.requestChromeRefresh();
+        });
+    };
+    editor.onCursorDownAtBottom = remote ? undefined : () => {
+        if (selKey !== undefined || items.length === 0)
+            return;
+        selKey = items[0].key;
+        paint();
+    };
+    const openSelected = () => {
+        const item = items.find((candidate) => candidate.key === selKey);
+        if (item === undefined || remote)
+            return;
+        if (item.kind === 'crons') {
+            exit();
+            hooks.openInspector('schedule');
+            return;
+        }
+        if (item.kind === 'review') {
+            if (role !== 'controller') {
+                hooks.setNotice('Read-only observer attach — cannot open the review companion');
+                return;
+            }
+            exit();
+            // Beside this pane, never in place: the person is asking to watch the
+            // companion, not to give up the view they are asking from.
+            // Runs the shared focus decision in-process (no cold `crtr` boot).
+            const companionPane = process.env['TMUX_PANE'];
+            if (companionPane === undefined || companionPane === '') {
+                hooks.setNotice('Could not open the companion: no tmux pane');
+                return;
+            }
+            void (async () => {
+                const client = cliClient();
+                const companion = await client.getNode(item.companionNodeId);
+                const res = await focusNode(client, companion, { pane: companionPane });
+                if (!res.focused)
+                    hooks.setNotice('Could not open the companion');
+            })().catch((err) => hooks.setNotice(`Could not open the companion: ${daemonErrorMessage(err).split('\n')[0]}`));
+            return;
+        }
+        if (item.kind === 'bash') {
+            void listJobs().then((jobs) => {
+                if (jobs.length === 0) {
+                    hooks.setNotice('Background job already finished');
+                    hooks.requestChromeRefresh();
+                    return;
+                }
+                exit();
+                hooks.openInspector('jobs');
+            }, (err) => hooks.setNotice(`Could not list background jobs: ${daemonErrorMessage(err).split('\n')[0]}`));
+            return;
+        }
+        if (item.kind === 'object-wait') {
+            exit();
+            hooks.openObject(item.objectId);
+            return;
+        }
+        const id = item.nodeId;
+        if (id === nodeId) {
+            exit();
+            return;
+        } // already viewing this one
+        if (role !== 'controller') {
+            hooks.setNotice('Read-only observer attach — cannot focus nodes');
+            return;
+        }
+        const pane = process.env['TMUX_PANE'];
+        if (pane === undefined || pane === '') {
+            hooks.setNotice('cannot swap — no tmux pane');
+            return;
+        }
+        // Drive the respawn from OUTSIDE this pane's process tree: `surface node focus
+        // --in-place` re-execs THIS pane onto the child (respawn-pane -k), which would
+        // kill a direct child process mid-swap. `tmux run-shell` runs in the server
+        // context, detached from the pane. `crtr` is on PATH here (same assumption as
+        // the Alt+]/[ node-cycle bindings).
+        execFile('tmux', ['run-shell', '-b', `crtr surface node focus ${id} --pane ${pane} --in-place >/dev/null 2>&1`], () => { });
+    };
+    const handleKey = (data) => {
+        if (remote)
+            return false; // no local node/wait detail target on a remote graph
+        const down = matchesKey(data, 'down');
+        const up = matchesKey(data, 'up');
+        // Until the roster is active, every key follows the normal focused-editor
+        // path. TitledEditor invokes the boundary callback above only after native ↓
+        // can move neither its visual cursor nor prompt history.
+        if (selKey === undefined)
+            return false;
+        // Roster active. Explicit boundaries on the single list: ↑ off the TOP row
+        // returns to the editor; ↓ CLAMPS at the bottom row.
+        const i = items.findIndex((item) => item.key === selKey);
+        const selected = items[i];
+        // Confirmation first: while a kill is armed, `y` fires it and every other
+        // key disarms it before taking its normal meaning.
+        if (pendingKill !== undefined) {
+            if (typed(data) === 'y') {
+                confirmKill();
+                return true;
+            }
+            disarmKill(true);
+        }
+        if (selected?.kind === 'bash' && typed(data) === 'x') {
+            void armKill().catch((err) => hooks.setNotice(`Could not list background jobs: ${daemonErrorMessage(err).split('\n')[0]}`));
+            return true;
+        }
+        if (up) {
+            if (i <= 0)
+                exit();
+            else {
+                selKey = items[i - 1].key;
+                paint();
+            }
+            return true;
+        }
+        if (down) {
+            if (i >= 0 && i < items.length - 1) {
+                selKey = items[i + 1].key;
+                paint();
+            }
+            return true;
+        }
+        if (matchesKey(data, 'enter')) {
+            openSelected();
+            return true;
+        }
+        if (matchesKey(data, 'escape')) {
+            exit();
+            return true;
+        }
+        // Any other key (the user started typing) returns to the editor AND passes
+        // through, so the keystroke lands in the input.
+        exit();
+        return false;
+    };
+    return { refresh, handleKey, active: () => selKey !== undefined, exit };
+}

package/dist/clients/attach/chrome/status-line.d.ts

@@ -0,0 +1,38 @@
+import type { BindingId, BindingResolution } from '../../../core/keybindings/index.js';
+import type { SessionState } from '../../../core/session-model/session-state.js';
+import type { AttachSession } from '../session/context.js';
+/** Shell/bash mode: 0 = off, 1 = `!` (output goes to the agent's context),
+ *  2 = `!!` (output hidden from the agent). Drives both the editor border hue
+ *  and the leading status segment explaining what will happen. */
+export type BashMode = 0 | 1 | 2;
+export type StatusLineSession = Pick<AttachSession, 'nodeId' | 'remote' | 'tui' | 'pal' | 'containers'>;
+export interface StatusLineHooks {
+    /** The reducer-folded broker state — role, engine, context tokens, queue. */
+    state: () => SessionState;
+    /** The editor's current bash level. */
+    bashMode: () => BashMode;
+    /** Per-node human-ticket counts for this canvas. */
+    asks: () => Record<string, number>;
+    /** The live resolved keybinding snapshot (refreshed by /reload), so shortcut
+     *  hints never go stale against a rebound key. */
+    bindings: () => BindingResolution<BindingId>;
+    /** Whether to render the closed-inbox affordance at all. Meaningful only for
+     *  a LOCAL in-tmux attach: a remote attach's local inbox registry cannot open
+     *  the remote canvas's filesystem tickets. */
+    inboxAffordance: boolean;
+    /** Whether mouse reporting is currently enabled. When false, displays a
+     *  low-priority 'mouse off' indicator in the status bar. */
+    mouseEnabled: () => boolean;
+}
+export interface AttachStatusLine {
+    /** Repaint the bar from current state. */
+    render: () => void;
+    /** Show a transient notice in the right slot. `sticky` keeps it up until
+     *  explicitly replaced instead of auto-clearing. */
+    setNotice: (msg: string, opts?: {
+        sticky?: boolean;
+    }) => void;
+    /** Cancel the pending auto-clear. Part of the viewer's local shutdown. */
+    dispose: () => void;
+}
+export declare function createStatusLine(s: StatusLineSession, hooks: StatusLineHooks): AttachStatusLine;

package/dist/clients/attach/chrome/status-line.js

@@ -0,0 +1,127 @@
+// chrome/status-line.ts — the bottom status bar and the transient notice slot.
+//
+// A themed, aligned bar: live state on the LEFT (bash mode · role · model ·
+// context · queued · attention · hint), the transient notice pushed to the
+// RIGHT edge — not jammed inline. Segments are ordered by priority because the
+// left side is ANSI-truncated to fit the terminal width: whatever is appended
+// LAST is what disappears first under a narrow pane.
+//
+// The bar RENDERS state, it does not hold it. Everything it shows lives
+// upstream — the reducer-folded `SessionState`, the editor's bash level, the
+// canvas ask counts, the resolved keybinding snapshot — and is read through the
+// hooks below on every paint, so the bar can never show a stale copy of a fact
+// that changed somewhere else.
+//
+// The one piece of state that IS the bar's own is the notice, because it has a
+// lifetime: transient notices auto-clear after a few seconds so a stale
+// "error: …" doesn't linger forever, while a `sticky` notice stays up until
+// explicitly replaced (the reconnect indicator, cleared by hand on redial).
+// That timer is why this module has a `dispose`.
+import { Text, truncateToWidth } from '@earendil-works/pi-tui';
+import { visibleWidth } from '../../../core/canvas/nav-render.js';
+import { inTmux } from '../../../core/runtime/placement-tmux.js';
+import { formatBinding, inboxOpenHint } from '../../../core/keybindings/index.js';
+import { viewerKeyHint } from './key-hint.js';
+const NOTICE_CLEAR_MS = 3_000;
+const formatTokens = (n) => n >= 1000 ? `${(n / 1000).toFixed(n >= 10000 ? 0 : 1)}k` : `${n}`;
+export function createStatusLine(s, hooks) {
+    const { pal, tui, nodeId, remote } = s;
+    const footer = s.containers.footer;
+    let notice = '';
+    let noticeTimer;
+    const render = () => {
+        const session = hooks.state();
+        const bashMode = hooks.bashMode();
+        const bindings = hooks.bindings();
+        const segs = [];
+        if (session.role !== 'controller')
+            segs.push(pal.muted('○ read-only'));
+        // Bash mode leads the bar (most salient while typing a `!` command) and
+        // spells out the consequence: a single `!` feeds output to the agent; `!!`
+        // hides it. Hue matches the editor border (dull vs bright green).
+        if (bashMode === 2)
+            segs.unshift(pal.bashModeAlt('● bash — output hidden from agent'));
+        else if (bashMode === 1)
+            segs.unshift(pal.bashMode('● bash — output added to context'));
+        const engine = session.engine;
+        if (engine?.model)
+            segs.push(pal.info(engine.model.id));
+        if (engine?.isStreaming)
+            segs.push(pal.active('⟳'));
+        // Live context occupancy is the prompt-token count of the most recent
+        // assistant turn (input + cacheRead + cacheWrite = everything sent to the
+        // model, since with prompt caching bare `input` is just the uncached slice
+        // and badly understates the context), folded by the reducer off the relayed
+        // message_end stream. It rides data the viewer already receives, so the
+        // indicator needs no broker/protocol change.
+        if (session.contextTokens !== undefined) {
+            segs.push(pal.muted(`${formatTokens(session.contextTokens)} ctx`));
+        }
+        if (engine && engine.pendingMessageCount > 0) {
+            segs.push(pal.muted(`queued ${engine.pendingMessageCount}`));
+        }
+        // Closed-inbox affordance (low-priority, after queued state): the pending
+        // human-ticket total for THIS canvas plus how to open the inbox popup. The
+        // segment disappears at zero. It is a count + affordance only: no ticket
+        // content, no picker, no auto-open. When the binding is disabled the
+        // shortcut clause is omitted in favor of the CLI affordance, never the word
+        // "Disabled".
+        let inboxPending = false;
+        if (hooks.inboxAffordance) {
+            const total = Object.values(hooks.asks()).reduce((sum, n) => sum + n, 0);
+            if (total > 0) {
+                inboxPending = true;
+                segs.push(pal.muted(`⚑ ${total} · ${inboxOpenHint(bindings)}`));
+            }
+        }
+        // Mouse reporting state: show "mouse off" when reporting is disabled, so
+        // users are aware that tmux drag-select and copy-mode mouse work again.
+        if (!hooks.mouseEnabled()) {
+            segs.push(pal.muted('mouse off'));
+        }
+        // The file-review affordance, tmux-only like the surface it opens.
+        if (inTmux() && bindings.gestures('crtr.attach.file-review').length > 0) {
+            segs.push(pal.muted(`${formatBinding(bindings, 'crtr.attach.file-review')} review file`));
+        }
+        // Persistent, dim, lowest priority (appended last, so a narrow pane drops it
+        // first): how to reach the action menu and inbox. The menu is a tmux menu, so
+        // the hint only appears for a local in-tmux attach. When the pending-inbox
+        // segment above already names the inbox key, only the menu half shows.
+        if (hooks.inboxAffordance) {
+            segs.push(pal.muted(viewerKeyHint(bindings, { inbox: !inboxPending })));
+        }
+        const left = segs.join(pal.muted(' · '));
+        const right = notice ? pal.warning(`⚠ ${notice}`) : '';
+        // Text(_, 1, 0) pads 1 col each side, so the usable span is columns - 2.
+        const span = Math.max(1, (process.stdout.columns ?? 80) - 2);
+        const rightW = visibleWidth(right);
+        // Truncate the left segment (ANSI-aware) so a long model/notice never wraps;
+        // the right-aligned notice keeps its slot.
+        const maxLeft = right ? Math.max(0, span - rightW - 1) : span;
+        const leftFit = visibleWidth(left) > maxLeft ? truncateToWidth(left, maxLeft, '…') : left;
+        const gap = Math.max(right ? 1 : 0, span - visibleWidth(leftFit) - rightW);
+        const line = right ? leftFit + ' '.repeat(gap) + right : leftFit;
+        footer.clear();
+        footer.addChild(new Text(line, 1, 0));
+        tui.requestRender();
+    };
+    const clearTimer = () => {
+        if (noticeTimer !== undefined) {
+            clearTimeout(noticeTimer);
+            noticeTimer = undefined;
+        }
+    };
+    const setNotice = (msg, opts) => {
+        notice = msg;
+        clearTimer();
+        if (msg && !opts?.sticky) {
+            noticeTimer = setTimeout(() => {
+                noticeTimer = undefined;
+                notice = '';
+                render();
+            }, NOTICE_CLEAR_MS);
+        }
+        render();
+    };
+    return { render, setNotice, dispose: clearTimer };
+}

package/dist/clients/attach/chrome/ticket-panel.d.ts

@@ -0,0 +1,29 @@
+import type { Component } from '@earendil-works/pi-tui';
+import type { InboxRow } from '../../inbox/dto-adapt.js';
+import type { AttachSession } from '../session/context.js';
+export type PanelSession = Pick<AttachSession, 'tui' | 'pal'>;
+export interface TicketPanelHooks {
+    /** Recompute the editor's hollow-cursor state (session/pane-focus.ts). */
+    syncCursor: () => void;
+    /** Repaint the strip — its rows hide while the panel is their expansion. */
+    refreshStrip: () => void;
+    setNotice: (msg: string) => void;
+    /** Fallback: the full-pane inbox surface seated on this ticket dir. */
+    openInbox: (dir: string) => void;
+    /** Release the terminal to $EDITOR for the comment roundtrip. */
+    suspendForChild: () => () => void;
+}
+export interface TicketPanel {
+    /** Mounted once into the frame's `ticketPanel` slot; empty while closed. */
+    readonly component: Component;
+    /** Open a ticket's page inline; review/unreadable tickets fall back. */
+    open(ticket: InboxRow): Promise<void>;
+    /** Panel key routing — consumes EVERY chunk while open. */
+    handleKey(data: string): boolean;
+    close(): void;
+    /** True while a page is open (the editor's cursor hollows). */
+    active(): boolean;
+    /** The open ticket's dir, for escalating to the full inbox surface. */
+    currentDir(): string | undefined;
+}
+export declare function createTicketPanel(s: PanelSession, hooks: TicketPanelHooks): TicketPanel;