@north-light/api 0.3.580 → 0.3.587

package/dist/clients/attach/config.js

@@ -0,0 +1,275 @@
+// config.ts — load the user's pi keybindings + theme for `crtr surface attach` (M8).
+//
+// These loaders are CLI-layer: pi does the *resolution* (the KeybindingsManager
+// matcher, `initTheme`) but the FILE reads are not reusable from pi, so we own
+// them. We read pi's own config locations so an attach viewer honors the same
+// `~/.pi/agent/keybindings.json` + theme the user already configured for pi.
+//
+// THE KEYBINDINGS MANAGER. pi's app-level KeybindingsManager (`core/keybindings`,
+// with `.create()` + the `app.*` definition table `KEYBINDINGS`) is NOT exported
+// — only its TYPE is re-exported, and the `KEYBINDINGS` const not at all. So we
+// construct pi-tui's KeybindingsManager (the base class CustomEditor actually
+// matches against) over the merged definition set: pi-tui's `TUI_KEYBINDINGS`
+// (editor/cursor/select bindings) + a VENDORED copy of pi's `app.*` editor
+// bindings below (required — CustomEditor.handleInput gates onEscape/onPasteImage/
+// onAction on `keybindings.matches(data, "app.*")`, so without the app defs those
+// never fire). We also register it globally via `setKeybindings` so the reused
+// pi-tui components (SelectList autocomplete, the dialog editor) honor overrides.
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { piAgentDir } from '../../core/runtime/package-health.js';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { KeybindingsManager, TUI_KEYBINDINGS, setKeybindings, } from '@earendil-works/pi-tui';
+import { getMarkdownTheme, getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { initCrtrTheme } from '../../core/runtime/crtr-theme.js';
+import { surfaceBgAnsi } from '../../core/runtime/surface-bg.js';
+/** pi's user config dir: `~/.pi/agent/`. */
+export function defaultAgentDir() {
+    return piAgentDir();
+}
+/**
+ * pi's `app.*` editor keybindings — VENDORED from pi `core/keybindings.ts`
+ * `KEYBINDINGS` (the const is not exported). This is the subset CustomEditor's
+ * main editor consults; the selector-internal bindings (`app.tree.*`,
+ * `app.models.*`, session delete/rename) are omitted because the attach viewer
+ * does not open those selectors. Re-sync on each SDK
+ * bump against `core/keybindings.js`.
+ */
+const APP_KEYBINDINGS = {
+    'app.interrupt': { defaultKeys: 'escape', description: 'Cancel or abort' },
+    'app.clear': { defaultKeys: 'ctrl+c', description: 'Clear editor' },
+    'app.exit': { defaultKeys: 'ctrl+d', description: 'Exit when editor is empty' },
+    'app.suspend': { defaultKeys: 'ctrl+z', description: 'Suspend to background' },
+    'app.thinking.cycle': { defaultKeys: 'shift+tab', description: 'Cycle thinking level' },
+    'app.model.cycleForward': { defaultKeys: 'ctrl+p', description: 'Cycle to next model' },
+    'app.model.cycleBackward': { defaultKeys: 'shift+ctrl+p', description: 'Cycle to previous model' },
+    'app.model.select': { defaultKeys: 'ctrl+l', description: 'Open model selector' },
+    'app.tools.expand': { defaultKeys: 'ctrl+o', description: 'Toggle tool output' },
+    'app.thinking.toggle': { defaultKeys: 'ctrl+t', description: 'Toggle thinking blocks' },
+    'app.editor.external': { defaultKeys: 'ctrl+g', description: 'Open external editor' },
+    // Alt+Enter inserts a newline in the attach editor (shift+enter is unreliable
+    // across terminals), so the follow-up-queue action drops its alt+enter default
+    // to free the chord — see ATTACH_KEYBINDING_OVERRIDES below.
+    'app.message.followUp': { defaultKeys: [], description: 'Queue follow-up message' },
+    'app.message.dequeue': { defaultKeys: 'alt+up', description: 'Restore queued messages' },
+    'app.clipboard.pasteImage': { defaultKeys: ['alt+v', 'ctrl+v'], description: 'Paste image from clipboard' },
+    'app.session.new': { defaultKeys: [], description: 'Start a new session' },
+    'app.session.tree': { defaultKeys: [], description: 'Open session tree' },
+    'app.session.fork': { defaultKeys: [], description: 'Fork current session' },
+    'app.session.resume': { defaultKeys: [], description: 'Resume a session' },
+};
+/**
+ * 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 function loadUserKeybindings(agentDir = defaultAgentDir()) {
+    try {
+        const raw = JSON.parse(readFileSync(join(agentDir, 'keybindings.json'), 'utf8'));
+        const obj = raw && typeof raw === 'object' && 'keybindings' in raw
+            ? raw.keybindings
+            : raw;
+        if (!obj || typeof obj !== 'object')
+            return undefined;
+        return obj;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the KeybindingsManager the attach viewer drives input with: TUI defaults
+ * + vendored `app.*` defs, with the user's overrides applied, registered as the
+ * global pi-tui keybindings so reused components pick up the same bindings.
+ * (`as unknown as` bridges the readonly `TUI_KEYBINDINGS`/string-literal defs to
+ * the mutable `KeybindingDefinitions` param — vendoring cast, no behavior change.)
+ */
+/**
+ * Attach-specific default overrides applied OVER pi's TUI defaults. Alt+Enter
+ * inserts a newline here (the follow-up-queue action gives up its alt+enter
+ * default above), because shift+enter — pi's stock newline chord — does not
+ * transmit a distinct sequence in many terminals. User `keybindings.json` still
+ * wins on top of these (applied as the manager's override config).
+ */
+const ATTACH_KEYBINDING_OVERRIDES = {
+    'tui.input.newLine': { defaultKeys: ['shift+enter', 'alt+enter'], description: 'Insert new line' },
+};
+export function createKeybindingsManager(agentDir = defaultAgentDir()) {
+    const definitions = {
+        ...TUI_KEYBINDINGS,
+        ...APP_KEYBINDINGS,
+        ...ATTACH_KEYBINDING_OVERRIDES,
+    };
+    const km = new KeybindingsManager(definitions, loadUserKeybindings(agentDir));
+    setKeybindings(km);
+    return km;
+}
+/**
+ * pi-coding-agent's `CustomEditor` resolves `@earendil-works/pi-tui` from its OWN
+ * `node_modules`, which can be a SEPARATE module instance from the one this file
+ * imports (a non-deduped install leaves a nested copy). The editor's newline /
+ * submit handling reads keybindings AND the kitty-protocol flag from THAT
+ * instance's module-globals via `getKeybindings()` / `isKittyProtocolActive()`,
+ * so state we set only on our copy is invisible to it — the user's `alt+enter`
+ * newline binding never applies and Enter falls through to submit. We mirror our
+ * state onto the editor's instance too. When the install IS deduped both resolve
+ * to one module and the mirror is a harmless re-set. Best-effort: a resolution /
+ * import failure leaves the editor on our copy's state (the deduped case).
+ */
+let editorPiTuiPromise;
+function editorPiTui() {
+    if (!editorPiTuiPromise) {
+        editorPiTuiPromise = (async () => {
+            try {
+                const pcaEntry = import.meta.resolve('@earendil-works/pi-coding-agent');
+                const piTuiPath = createRequire(pcaEntry).resolve('@earendil-works/pi-tui');
+                return (await import(pathToFileURL(piTuiPath).href));
+            }
+            catch {
+                return undefined;
+            }
+        })();
+    }
+    return editorPiTuiPromise;
+}
+/** 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 async function mirrorKeybindingsToEditor(km) {
+    (await editorPiTui())?.setKeybindings(km);
+}
+/** 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 async function mirrorKittyProtocolToEditor(active) {
+    (await editorPiTui())?.setKittyProtocolActive(active);
+}
+/**
+ * Resolve the `fd` binary path the @-mention file picker needs. pi-tui's
+ * `CombinedAutocompleteProvider` only returns file suggestions when handed an
+ * `fdPath` (its third ctor arg) — without it, typing `@` triggers the picker but
+ * `getFuzzyFileSuggestions` returns `[]`, so the picker never appears.
+ * pi's own interactive mode resolves this via `ensureTool('fd')` from its
+ * internal `utils/tools-manager` (checks pi's managed bin dir + system PATH,
+ * downloading the binary if missing). That module is NOT on pi-coding-agent's
+ * `.`-only export map, so we reach it the same way we reach the editor's pi-tui
+ * instance: resolve the package entry, then import the sibling file by URL
+ * (file URLs bypass the bare-specifier exports gate). Best-effort: any
+ * resolution/import failure (or no fd available) → `null`, and the picker stays
+ * file-less rather than crashing.
+ */
+let fdPathPromise;
+export function resolveFdPath() {
+    if (!fdPathPromise) {
+        fdPathPromise = (async () => {
+            try {
+                const pcaEntry = import.meta.resolve('@earendil-works/pi-coding-agent');
+                const toolsManagerUrl = new URL('./utils/tools-manager.js', pcaEntry).href;
+                const toolsManager = (await import(toolsManagerUrl));
+                return (await toolsManager.ensureTool('fd', true)) ?? null;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return fdPathPromise;
+}
+/**
+ * The user's theme name from pi settings — project (`<cwd>/.pi/settings.json`)
+ * overrides global (`~/.pi/agent/settings.json`). `undefined` → pi's default.
+ */
+export function loadThemeName(opts) {
+    const files = [
+        join(opts?.cwd ?? process.cwd(), '.pi', 'settings.json'),
+        join(opts?.agentDir ?? defaultAgentDir(), 'settings.json'),
+    ];
+    for (const file of files) {
+        try {
+            const raw = JSON.parse(readFileSync(file, 'utf8'));
+            if (raw && typeof raw === 'object' && typeof raw.theme === 'string') {
+                return raw.theme;
+            }
+        }
+        catch {
+            /* missing/malformed — try the next location */
+        }
+    }
+    return 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 function applyTheme(opts) {
+    initCrtrTheme(loadThemeName(opts), opts?.agentDir ?? defaultAgentDir());
+}
+const FAINT = (s) => `\x1b[2m${s}\x1b[22m`;
+const RED = (s) => `\x1b[31m${s}\x1b[39m`;
+const YELLOW = (s) => `\x1b[33m${s}\x1b[39m`;
+const GREEN = (s) => `\x1b[32m${s}\x1b[39m`;
+const BRIGHT_GREEN = (s) => `\x1b[92m${s}\x1b[39m`;
+const DIFF_REMOVED = (s) => `\x1b[91m${s}\x1b[39m`;
+// Terminals do not support alpha. This neutral charcoal is the dark-theme
+// equivalent of a low-opacity gray overlay, without borrowing the purple
+// selection surface used by interactive chrome.
+const CODE_BLOCK_BACKGROUND = '\x1b[48;2;36;36;36m';
+/** Paint a code-block fragment and keep its background active through the
+ *  renderer's trailing spaces, so the surface reaches the transcript's edge.
+ *  TUI applies a full reset after every rendered line. */
+function codeSurfaceFragment(render, text) {
+    return `${CODE_BLOCK_BACKGROUND}${render(text).replace(/\x1b\[0m/g, `\x1b[0m${CODE_BLOCK_BACKGROUND}`)}`;
+}
+/** 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 function attachMarkdownTheme() {
+    const base = getMarkdownTheme();
+    const paint = (render, text) => codeSurfaceFragment(render, text);
+    return {
+        ...base,
+        // `Markdown` emits this before each body line; leave the surface on until
+        // the following code fragment closes it.
+        codeBlockIndent: `${CODE_BLOCK_BACKGROUND}${base.codeBlockIndent ?? '  '}`,
+        codeBlock: (text) => paint(base.codeBlock, text),
+        codeBlockBorder: (text) => paint(base.codeBlockBorder, text),
+        highlightCode: base.highlightCode
+            ? (code, language) => base.highlightCode(code, language).map((line) => paint((value) => value, line))
+            : undefined,
+    };
+}
+/**
+ * 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 function attachPalette() {
+    const md = getMarkdownTheme();
+    const sel = getSelectListTheme();
+    // The distinct-surface bg-on SGR, captured once. Re-asserted after every
+    // embedded `\x1b[0m` (full reset) inside a line so a coloured cell can't drop
+    // back to the default background mid-row; the line ends with `\x1b[49m` (reset
+    // background only) so the surface never bleeds onto the next line.
+    const bgOn = surfaceBgAnsi();
+    return {
+        accent: md.heading,
+        active: md.code,
+        info: md.link,
+        muted: sel.description,
+        faint: FAINT,
+        border: md.hr,
+        bold: md.bold,
+        error: RED,
+        warning: YELLOW,
+        diffAdded: GREEN,
+        diffRemoved: DIFF_REMOVED,
+        bashMode: GREEN,
+        bashModeAlt: BRIGHT_GREEN,
+        surface: (line) => `${bgOn}${line.replace(/\x1b\[0m/g, `\x1b[0m${bgOn}`)}\x1b[49m`,
+    };
+}

package/dist/clients/attach/input/capabilities.d.ts

@@ -0,0 +1,30 @@
+import type { ClientRole, ClientToBroker } from '../../../core/runtime/broker-protocol.js';
+/** Actions the attach input surface may perform. Frame-level broker enforcement
+ * remains authoritative; this is the viewer-side refusal contract. */
+export type ViewerOperation = 'engine-drive' | 'dequeue' | 'wake-dormant' | 'auth' | 'canvas-resume' | 'local-canvas-inspect' | 'canvas-inbox' | 'local-host';
+export interface ViewerCapabilities {
+    readonly role: ClientRole;
+    readonly remote: boolean;
+    readonly nodeId: string;
+    readonly profileId: string | undefined;
+    readonly permittedOperations: ReadonlySet<ViewerOperation>;
+    permits(operation: ViewerOperation): boolean;
+    refusal(operation: ViewerOperation, command?: string): string | undefined;
+}
+export interface ViewerCapabilityInput {
+    role: ClientRole;
+    remote: boolean;
+    nodeId: string;
+    profileId: string | undefined;
+    /** Dynamic transport state. Authorization stays role-based; broker-only
+     * operations refuse locally while a parked viewer has no live engine. */
+    isBrokerOffline?: () => boolean;
+}
+/** Build the one authority for a viewer session. A remote viewer drives only
+ * the broker (engine operations); everything that acts on this machine's local
+ * canvas, auth store or daemon stays unavailable to it. */
+export declare function createViewerCapabilities(input: ViewerCapabilityInput): ViewerCapabilities;
+/** The slash dispatcher asks the capability model for a command's operation;
+ * commands with no returned operation are viewer-local/read-only. */
+export declare function viewerOperationForFrame(frame: ClientToBroker): ViewerOperation | undefined;
+export declare function viewerOperationForSlash(name: string, builtin: boolean, canvas: boolean): ViewerOperation | undefined;

package/dist/clients/attach/input/capabilities.js

@@ -0,0 +1,112 @@
+/** Build the one authority for a viewer session. A remote viewer drives only
+ * the broker (engine operations); everything that acts on this machine's local
+ * canvas, auth store or daemon stays unavailable to it. */
+export function createViewerCapabilities(input) {
+    const remote = input.remote;
+    const role = input.role;
+    const permittedOperations = new Set();
+    // Viewer-local reads and inspection remain available to a local observer.
+    if (!remote) {
+        permittedOperations.add('local-canvas-inspect');
+        permittedOperations.add('canvas-inbox');
+    }
+    if (role === 'controller') {
+        permittedOperations.add('engine-drive');
+        permittedOperations.add('dequeue');
+    }
+    // These act on THIS machine (its daemon, auth.json, canvas), the wrong host
+    // for a remote node.
+    if (role === 'controller' && !remote) {
+        permittedOperations.add('wake-dormant');
+        permittedOperations.add('auth');
+        permittedOperations.add('canvas-resume');
+        permittedOperations.add('local-host');
+    }
+    return {
+        role,
+        remote,
+        nodeId: input.nodeId,
+        profileId: input.profileId,
+        permittedOperations,
+        permits: (operation) => permittedOperations.has(operation),
+        refusal: (operation, command) => {
+            const prefix = command === undefined ? '' : `/${command} `;
+            if (input.isBrokerOffline?.() === true
+                && (operation === 'engine-drive' || operation === 'dequeue' || operation === 'auth')) {
+                return `${prefix}needs a live broker; this node is parked — submit a message to wake it`;
+            }
+            if (permittedOperations.has(operation))
+                return undefined;
+            if (remote && (operation === 'canvas-resume' || operation === 'local-canvas-inspect' || operation === 'canvas-inbox')) {
+                return `${prefix}Not available with --canvas because it acts on this machine's local canvas`;
+            }
+            if (remote && role === 'controller')
+                return `${prefix}Not available with --canvas because it acts on this machine, not the remote node`;
+            return `${prefix}is not available to a read-only observer attach (--observer) — it would drive this node`;
+        },
+    };
+}
+/** The slash dispatcher asks the capability model for a command's operation;
+ * commands with no returned operation are viewer-local/read-only. */
+export function viewerOperationForFrame(frame) {
+    switch (frame.type) {
+        case 'prompt':
+        case 'steer':
+        case 'follow_up':
+        case 'abort':
+        case 'bash':
+        case 'set_model':
+        case 'cycle_model':
+        case 'cycle_ladder':
+        case 'cycle_thinking':
+        case 'set_thinking_level':
+        case 'set_auto_retry':
+        case 'set_auto_compaction':
+        case 'compact':
+        case 'new_session':
+        case 'switch_session':
+        case 'fork':
+        case 'set_session_name':
+        case 'navigate_tree':
+        case 'reload':
+        case 'export':
+        case 'clone':
+        case 'share':
+        case 'reload_auth': return 'engine-drive';
+        default: return undefined;
+    }
+}
+export function viewerOperationForSlash(name, builtin, canvas) {
+    if (canvas) {
+        switch (name) {
+            case 'resume': return 'canvas-resume';
+            case 'context':
+            case 'node-metadata': return 'local-canvas-inspect';
+            // `/plugins` configures the local machine, not this node; observers and
+            // remote attaches can open its local popup.
+            case 'plugins': return undefined;
+            case 'inbox': return 'canvas-inbox';
+            case 'clear':
+            case 'resume-session':
+            case 'tutorial': return 'engine-drive';
+            // These run local `crtr node …`, rewrite this machine's tmux titles, or read this machine's MCP config:
+            // with --canvas they would act on a same-id local node or local state, not the remote node.
+            case 'promote':
+            case 'rename':
+            case 'mcp': return 'local-host';
+            default: return undefined;
+        }
+    }
+    if (!builtin)
+        return undefined;
+    switch (name) {
+        case 'copy':
+        case 'session':
+        case 'changelog':
+        case 'hotkeys':
+        case 'quit': return undefined;
+        case 'login':
+        case 'logout': return 'auth';
+        default: return 'engine-drive';
+    }
+}

package/dist/clients/attach/input/clipboard-image.d.ts

@@ -0,0 +1,55 @@
+import type { ImageContent } from '@earendil-works/pi-ai';
+/** A clipboard image ready to attach, plus an optional note for the controller
+ *  to surface — either a resize note (from pi's `formatDimensionNote`) or, when
+ *  no image was attached, the reason (dropped over the cap, or no clipboard
+ *  tool / read failure). */
+export interface ClipboardImageResult {
+    /** Ready to push into a `prompt`/`steer`/`follow_up` frame's `images?`. ABSENT
+     *  when the image was read but DROPPED (a fallback exceeded MAX_BYTES base64),
+     *  or when there was no image to read but a precise reason is worth surfacing;
+     *  `note` then carries that reason and the caller attaches nothing. */
+    image?: ImageContent;
+    /** Either a resize note ("Resized from 4032×3024 to 1568×1176", present only
+     *  when resized) or, when `image` is absent, the reason no image was attached. */
+    note?: string;
+}
+/** Persist a (already-resized) clipboard image to a stable temp file and return
+ *  its absolute path, so the attach editor can drop the PATH inline into the
+ *  prompt instead of inlining base64 the agent can't see. The broker runs on the
+ *  same host, so a tmpdir path is readable by the engine. */
+export declare function writeClipboardImageToFile(image: ImageContent): string;
+/** Read + resize the current clipboard image. Returns `null` ONLY when the
+ *  clipboard genuinely holds no image; a `note`-only result means there is a
+ *  precise reason to surface (no clipboard tool, read failure, or an over-cap
+ *  drop). All best-effort — the caller shows a brief notice and carries on. */
+export declare function readClipboardImage(): Promise<ClipboardImageResult | null>;
+interface RawImage {
+    bytes: Buffer;
+    mimeType: string;
+}
+/** Outcome of the raw clipboard read, distinguishing the three cases the caller
+ *  must tell apart: `image` present → got bytes; `note` present → no image AND a
+ *  precise reason to surface (no clipboard tool / read failure); both absent →
+ *  the clipboard genuinely holds no image. */
+export interface RawReadOutcome {
+    image?: RawImage;
+    note?: string;
+}
+/** Result of probing one clipboard tool, distinguishing a MISSING binary (so the
+ *  caller can say "no clipboard tool") from a tool that ran but produced no image
+ *  (`bytes` absent, `missing` false → genuinely empty). */
+export interface RunResult {
+    /** Tool stdout when it produced non-empty output. */
+    bytes?: Buffer;
+    /** The binary was not found on PATH (ENOENT). */
+    missing?: boolean;
+}
+/** Pure macOS dispatch (the regression-test seam): try `pngpaste` if present,
+ *  else fall through to the native osascript read — a missing `pngpaste` must
+ *  NOT collapse to "no image", which was the stock-Mac bug. */
+export declare function selectMacOutcome(runTool: (command: string, args: string[]) => RunResult, readNative: () => RawReadOutcome): RawReadOutcome;
+/** Pure Linux dispatch (the regression-test seam): Wayland (`wl-paste`) first,
+ *  then X11 (`xclip`), PNG then JPEG. If NO tool binary was found, surface a
+ *  precise "install …" note; if a tool ran but found no image, report empty. */
+export declare function selectLinuxOutcome(runTool: (command: string, args: string[]) => RunResult, wayland: boolean): RawReadOutcome;
+export {};