@north-light/cli 0.0.0 → 0.3.414

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;

package/dist/clients/attach/config.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var t=(e,o)=>y(e,"name",{value:o,configurable:!0});import{readFileSync as p}from"node:fs";import{createRequire as b}from"node:module";import{piAgentDir as h}from"../../core/runtime/package-health.js";import{join as s}from"node:path";import{pathToFileURL as x}from"node:url";import{KeybindingsManager as K,TUI_KEYBINDINGS as w,setKeybindings as k}from"@earendil-works/pi-tui";import{getMarkdownTheme as l,getSelectListTheme as T}from"@earendil-works/pi-coding-agent";import{initCrtrTheme as E}from"../../core/runtime/crtr-theme.js";import{surfaceBgAnsi as B}from"../../core/runtime/surface-bg.js";function i(){return h()}t(i,"defaultAgentDir");const I={"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"},"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"}};function R(e=i()){try{const o=JSON.parse(p(s(e,"keybindings.json"),"utf8")),n=o&&typeof o=="object"&&"keybindings"in o?o.keybindings:o;return!n||typeof n!="object"?void 0:n}catch{return}}t(R,"loadUserKeybindings");const $={"tui.input.newLine":{defaultKeys:["shift+enter","alt+enter"],description:"Insert new line"}};function H(e=i()){const o={...w,...I,...$},n=new K(o,R(e));return k(n),n}t(H,"createKeybindingsManager");let a;function u(){return a||(a=(async()=>{try{const e=import.meta.resolve("@earendil-works/pi-coding-agent"),o=b(e).resolve("@earendil-works/pi-tui");return await import(x(o).href)}catch{return}})()),a}t(u,"editorPiTui");async function J(e){(await u())?.setKeybindings(e)}t(J,"mirrorKeybindingsToEditor");async function V(e){(await u())?.setKittyProtocolActive(e)}t(V,"mirrorKittyProtocolToEditor");let c;function z(){return c||(c=(async()=>{try{const e=import.meta.resolve("@earendil-works/pi-coding-agent");return await(await import(new URL("./utils/tools-manager.js",e).href)).ensureTool("fd",!0)??null}catch{return null}})()),c}t(z,"resolveFdPath");function C(e){const o=[s(e?.cwd??process.cwd(),".pi","settings.json"),s(e?.agentDir??i(),"settings.json")];for(const n of o)try{const r=JSON.parse(p(n,"utf8"));if(r&&typeof r=="object"&&typeof r.theme=="string")return r.theme}catch{}}t(C,"loadThemeName");function Q(e){E(C(e),e?.agentDir??i())}t(Q,"applyTheme");const D=t(e=>`\x1B[2m${e}\x1B[22m`,"FAINT"),N=t(e=>`\x1B[31m${e}\x1B[39m`,"RED"),P=t(e=>`\x1B[33m${e}\x1B[39m`,"YELLOW"),f=t(e=>`\x1B[32m${e}\x1B[39m`,"GREEN"),O=t(e=>`\x1B[92m${e}\x1B[39m`,"BRIGHT_GREEN"),v=t(e=>`\x1B[91m${e}\x1B[39m`,"DIFF_REMOVED"),d="\x1B[48;2;36;36;36m";function A(e,o){return`${d}${e(o).replace(/\x1b\[0m/g,`\x1B[0m${d}`)}`}t(A,"codeSurfaceFragment");function W(){const e=l(),o=t((n,r)=>A(n,r),"paint");return{...e,codeBlockIndent:`${d}${e.codeBlockIndent??"  "}`,codeBlock:t(n=>o(e.codeBlock,n),"codeBlock"),codeBlockBorder:t(n=>o(e.codeBlockBorder,n),"codeBlockBorder"),highlightCode:e.highlightCode?(n,r)=>e.highlightCode(n,r).map(m=>o(g=>g,m)):void 0}}t(W,"attachMarkdownTheme");function X(){const e=l(),o=T(),n=B();return{accent:e.heading,active:e.code,info:e.link,muted:o.description,faint:D,border:e.hr,bold:e.bold,error:N,warning:P,diffAdded:f,diffRemoved:v,bashMode:f,bashModeAlt:O,surface:t(r=>`${n}${r.replace(/\x1b\[0m/g,`\x1B[0m${n}`)}\x1B[49m`,"surface")}}t(X,"attachPalette");export{Q as applyTheme,W as attachMarkdownTheme,X as attachPalette,H as createKeybindingsManager,i as defaultAgentDir,C as loadThemeName,R as loadUserKeybindings,J as mirrorKeybindingsToEditor,V as mirrorKittyProtocolToEditor,z as resolveFdPath};

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';
+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. Remote viewers are observers
+ * even when a caller supplied a controller role; keep that invariant local to
+ * this construction boundary. */
+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 @@
+var o=Object.defineProperty;var r=(e,s)=>o(e,"name",{value:s,configurable:!0});function l(e){const s=e.remote,t=s?"observer":e.role,a=new Set;return s||(a.add("local-canvas-inspect"),a.add("canvas-inbox")),t==="controller"&&(a.add("engine-drive"),a.add("dequeue"),a.add("wake-dormant"),a.add("auth"),a.add("canvas-resume")),{role:t,remote:s,nodeId:e.nodeId,profileId:e.profileId,permittedOperations:a,permits:r(n=>a.has(n),"permits"),refusal:r((n,i)=>{const c=i===void 0?"":`/${i} `;if(e.isBrokerOffline?.()===!0&&(n==="engine-drive"||n==="dequeue"||n==="auth"))return`${c}needs a live broker; this node is parked \u2014 submit a message to wake it`;if(!a.has(n))return s&&(n==="canvas-resume"||n==="local-canvas-inspect"||n==="canvas-inbox")?`${c}Read-only remote attach \u2014 not available with --canvas because it acts on this machine's local canvas`:s?`${c}Read-only remote attach \u2014 not available with --canvas (view-only)`:`${c}is not available to a read-only observer attach (--observer) \u2014 it would drive this node`},"refusal")}}r(l,"createViewerCapabilities");function u(e){switch(e.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}}r(u,"viewerOperationForFrame");function v(e,s,t){if(t)switch(e){case"resume":return"canvas-resume";case"context":case"node-metadata":return"local-canvas-inspect";case"plugins":return;case"inbox":return"canvas-inbox";case"clear":case"promote":case"rename":case"resume-session":case"tutorial":case"mcp":return"engine-drive";default:return}if(s)switch(e){case"copy":case"session":case"changelog":case"hotkeys":case"quit":return;case"login":case"logout":return"auth";default:return"engine-drive"}}r(v,"viewerOperationForSlash");export{l as createViewerCapabilities,u as viewerOperationForFrame,v as viewerOperationForSlash};

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 {};

package/dist/clients/attach/input/clipboard-image.js

@@ -0,0 +1,20 @@
+var g=Object.defineProperty;var o=(n,e)=>g(n,"name",{value:e,configurable:!0});import{spawnSync as c}from"node:child_process";import{mkdirSync as y,readFileSync as b,unlinkSync as h,writeFileSync as T}from"node:fs";import{tmpdir as m}from"node:os";import{join as a}from"node:path";import{convertToPng as w,formatDimensionNote as S,resizeImage as x}from"@earendil-works/pi-coding-agent";const p=1568,s=3*1024*1024,u=64*1024*1024,f=3e3;function F(n){const e=a(m(),"crtr-clip-images");y(e,{recursive:!0});const t=n.mimeType==="image/jpeg"?"jpg":"png",r=a(e,`paste-${Date.now()}-${process.pid}.${t}`);return T(r,Buffer.from(n.data,"base64")),r}o(F,"writeClipboardImageToFile");async function $(){const n=B(),e=n.image;if(!e)return n.note?{note:n.note}:null;const t=await x(new Uint8Array(e.bytes),e.mimeType,{maxWidth:p,maxHeight:p,maxBytes:s});if(t)return{image:{type:"image",data:t.data,mimeType:t.mimeType},note:t.wasResized?S(t):void 0};const r=await w(e.bytes.toString("base64"),e.mimeType);return l(r?{type:"image",data:r.data,mimeType:r.mimeType}:{type:"image",data:e.bytes.toString("base64"),mimeType:e.mimeType})}o($,"readClipboardImage");function l(n){const e=Buffer.byteLength(n.data);if(e<=s)return{image:n};const t=o(r=>Math.round(r/(1024*1024)),"mib");return{note:`Image not attached: ${t(e)} MiB exceeds the ${t(s)} MiB attach limit (clipboard resizer unavailable)`}}o(l,"capped");function B(){return process.platform==="darwin"?I(d,E):_(d,M())}o(B,"readRawClipboardImage");function I(n,e){const t=n("pngpaste",["-"]);return t.bytes?{image:{bytes:t.bytes,mimeType:"image/png"}}:e()}o(I,"selectMacOutcome");function _(n,e){let t=!1;if(e){const r=n("wl-paste",["--type","image/png","--no-newline"]);if(r.bytes)return{image:{bytes:r.bytes,mimeType:"image/png"}};r.missing||(t=!0)}for(const r of["image/png","image/jpeg"]){const i=n("xclip",["-selection","clipboard","-t",r,"-o"]);if(i.bytes)return{image:{bytes:i.bytes,mimeType:r}};i.missing||(t=!0)}return t?{}:{note:e?"No clipboard tool found \u2014 install wl-clipboard (wl-paste) to paste images":"No clipboard tool found \u2014 install xclip to paste images"}}o(_,"selectLinuxOutcome");const A=`on run argv
+  set outPath to item 1 of argv
+  try
+    set pngData to (the clipboard as \xABclass PNGf\xBB)
+  on error
+    return "NO_IMAGE"
+  end try
+  set fh to open for access (POSIX file outPath) with write permission
+  try
+    set eof fh to 0
+    write pngData to fh
+    close access fh
+  on error
+    try
+      close access fh
+    end try
+    return "WRITE_FAILED"
+  end try
+  return "OK"
+end run`;function E(){const n=a(m(),`crtr-clip-${process.pid}-${Date.now()}.png`);try{const e=c("osascript",["-e",A,n],{timeout:f,maxBuffer:u,encoding:"utf-8"});if(e.error||e.status!==0)return{note:"Could not read the clipboard (osascript failed)"};const t=(e.stdout??"").trim();if(t==="NO_IMAGE")return{};if(t!=="OK")return{note:"Could not read the clipboard image"};let r;try{r=b(n)}catch{return{note:"Could not read the clipboard image"}}return r.length>0?{image:{bytes:r,mimeType:"image/png"}}:{}}finally{try{h(n)}catch{}}}o(E,"readMacClipboardViaOsascript");function M(){return!!process.env.WAYLAND_DISPLAY||process.env.XDG_SESSION_TYPE==="wayland"}o(M,"isWayland");function d(n,e){const t=c(n,e,{timeout:f,maxBuffer:u});if(t.error)return{missing:t.error.code==="ENOENT"};if(t.status!==0)return{};const r=t.stdout;return!r||r.length===0?{}:{bytes:Buffer.isBuffer(r)?r:Buffer.from(r)}}o(d,"run");export{$ as readClipboardImage,_ as selectLinuxOutcome,I as selectMacOutcome,F as writeClipboardImageToFile};

package/dist/clients/attach/input/completion-frecency.d.ts

@@ -0,0 +1,45 @@
+export interface FrecencyStore {
+    /** Bump an item's count and stamp it now. `id` is namespaced by the caller
+     *  (`command:<name>` / `ref:<canonicalName>`) so a command and a ref of the
+     *  same name never collide. */
+    record(id: string): void;
+    /** The non-negative bonus to SUBTRACT from an item's fuzzy score. */
+    bonus(id: string, now?: number): number;
+}
+/** Create the viewer's single frecency store. Loads once; writes are debounced
+ *  and unref'd so they never hold the process open. */
+export declare function createFrecencyStore(filePath?: string): FrecencyStore;
+/**
+ * Filter `items` to fuzzy matches of `query` and sort by combined
+ * `fuzzyScore − frecencyBonus` (ascending; lower = better, matching pi-tui's
+ * convention). An empty query matches everything at fuzzy score 0, so the
+ * result is ordered purely by frecency — the bare-`/` "most-used first" list.
+ *
+ * `fuzzyMatch` is pi-tui's own exported matcher, so for a single-token query
+ * this produces exactly pi-tui's per-item score; the frecency term is the only
+ * perturbation.
+ */
+export declare function rankByFuzzyFrecency<T>(items: readonly T[], query: string, opts: {
+    searchableOf: (item: T) => string;
+    idOf: (item: T) => string;
+    store: FrecencyStore;
+    now?: number;
+}): T[];
+/**
+ * The string a namespaced name is fuzzy-matched against. Users reach for the
+ * meaningful LEAF ("dev"), so the leaf is placed first (earning pi-tui's
+ * word-boundary bonus) and the full name follows. This is what lets a
+ * cross-segment query like `devacm` match `acme/dev` — `dev` from the
+ * leaf then `acm` from `acme` — which a subsequence over the raw name
+ * cannot do.
+ *
+ * One helper serves both inventories: memory refs are namespaced with `/`
+ * (canonical `acme/dev`) and slash commands with `:` (the same doc
+ * invoked as `/acme:dev`), so the leaf is whatever follows the last
+ * separator of either kind.
+ */
+export declare function leafFirstSearchable(name: string): string;
+/** Normalize a typed ref query for matching: drop the surface `:` separators so
+ *  a typed `acme:dev` matches the `/`-separated canonical searchable text,
+ *  and so cross-segment queries are not blocked by a separator mismatch. */
+export declare function normalizeRefQuery(surfacePrefixWithoutSlash: string): string;

package/dist/clients/attach/input/completion-frecency.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var c=(e,t)=>u(e,"name",{value:t,configurable:!0});import{mkdirSync as f,readFileSync as a,writeFileSync as m}from"node:fs";import{dirname as p,join as y}from"node:path";import{fuzzyMatch as d}from"@earendil-works/pi-tui";import{userScopeRoot as l}from"../../../core/scope.js";const b="completion-frecency.json",h=336*60*60*1e3,F=8,M=1e3;function S(e,t){if(!e)return 0;const n=Math.max(0,t-e.t),s=Math.pow(.5,n/h),o=1-Math.exp(-e.n/3);return F*s*o}c(S,"frecencyBonus");function x(e){const t={};try{const n=JSON.parse(a(e,"utf8"));if(!n||typeof n!="object"||Array.isArray(n))return t;for(const[s,o]of Object.entries(n)){if(!o||typeof o!="object")continue;const{n:r,t:i}=o;typeof r!="number"||!Number.isFinite(r)||r<=0||typeof i!="number"||!Number.isFinite(i)||(t[s]={n:r,t:i})}}catch{}return t}c(x,"loadMap");function O(e,t){try{f(p(e),{recursive:!0}),m(e,JSON.stringify(t),"utf8")}catch{}}c(O,"saveMap");function z(e=y(l(),b)){const t=x(e);let n;const s=c(()=>{n||(n=setTimeout(()=>{n=void 0,O(e,t)},M),n.unref?.())},"scheduleWrite");return{record:c(o=>{const r=t[o];t[o]={n:(r?.n??0)+1,t:Date.now()},s()},"record"),bonus:c((o,r=Date.now())=>S(t[o],r),"bonus")}}c(z,"createFrecencyStore");function A(e,t,n){const s=n.now??Date.now(),o=[];for(const r of e){const i=d(t,n.searchableOf(r));i.matches&&o.push({item:r,score:i.score-n.store.bonus(n.idOf(r),s)})}return o.sort((r,i)=>r.score-i.score),o.map(r=>r.item)}c(A,"rankByFuzzyFrecency");function I(e){const t=Math.max(e.lastIndexOf("/"),e.lastIndexOf(":"));return t<0?e:`${e.slice(t+1)} ${e}`}c(I,"leafFirstSearchable");function v(e){return e.replace(/:/g,"")}c(v,"normalizeRefQuery");export{z as createFrecencyStore,I as leafFirstSearchable,v as normalizeRefQuery,A as rankByFuzzyFrecency};

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

@@ -0,0 +1,91 @@
+import type { CustomEditor } from '@earendil-works/pi-coding-agent';
+import type { Component, KeybindingsManager, TUI } from '@earendil-works/pi-tui';
+import { type BrokerDataFrame, type BrokerSnapshot, type ClientToBroker, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
+import type { ReadOpRequest } from '../../../core/broker-client/index.js';
+import type { FrecencyStore } from './completion-frecency.js';
+import type { CopyTarget } from '../render/transcript-copy.js';
+import { type ViewerCapabilities } from './capabilities.js';
+import { InputOverlayOwner } from './overlay-owner.js';
+export interface InputControllerHooks {
+    onCommand: (frame: ClientToBroker) => void;
+    onDialogResponse: (response: RpcExtensionUIResponse) => void;
+    onNotice?: (message: string) => void;
+    onGraph?: () => void;
+    onInbox?: () => void;
+    onHelp?: () => void;
+    onQuit?: () => void;
+    onCopy?: () => void;
+    onCopyTarget?: (target: CopyTarget) => void;
+    onToggleMouse?: () => void;
+    onColor?: (color: string | null) => void;
+    onNodeMetadata?: () => void;
+    onToggleToolsExpand?: () => void;
+    onFoldTools?: () => void;
+    onToggleThinking?: () => void;
+    onRequest?: (frame: ReadOpRequest) => Promise<BrokerDataFrame>;
+    onMountPicker?: (component: Component) => void;
+    onUnmountPicker?: () => void;
+    /** Viewer-local auth entry points. Their presence is an affordance, not
+     * permission; input-wiring supplies them only when capabilities permit auth. */
+    openLoginPicker?: () => void;
+    openLogoutPicker?: () => void;
+    isDormant?: () => boolean;
+    onDormantSubmit?: (text: string) => void;
+    onPromptSent?: () => void;
+    /** Per-user completion frecency store — usage recorded here biases the sort
+     *  order the next time `/` completion opens. */
+    frecency?: FrecencyStore;
+    /** Canonical names of currently-resolvable memory refs, so a submitted
+     *  message records ONLY real refs, not arbitrary slash tokens. */
+    knownRefNames?: () => ReadonlySet<string>;
+}
+export declare class InputController {
+    private readonly tui;
+    private readonly editor;
+    private readonly keybindings;
+    private readonly hooks;
+    private readonly capabilities;
+    private readonly overlays;
+    private state;
+    private lastEscapeAt;
+    private pastedImages;
+    private pasteSeq;
+    constructor(tui: TUI, editor: CustomEditor, keybindings: KeybindingsManager, hooks: InputControllerHooks, capabilities: ViewerCapabilities);
+    cycleLadder(direction: 'forward' | 'backward'): void;
+    sendInterrupting(text: string): boolean;
+    /** Cancel the running turn without sending a message — the ctrl+c "stop the
+     *  agent" chord. Mirrors Esc's abort semantics. Returns false when nothing is
+     *  streaming to cancel, so the caller can hint at detach instead. */
+    abortTurn(): boolean;
+    attachDialog(request: RpcExtensionUIRequest): void;
+    dismissDialog(id: string): void;
+    setState(state: BrokerSnapshot['state']): void;
+    openFileReviewPicker(candidates: string[], cwd: string, onChoose: (file: string) => void): void;
+    /** Retained as a narrow delegate for auth affordances wired by the session. */
+    openAuthPicker(prepare: Parameters<InputOverlayOwner['openAuthPicker']>[0]): Promise<void>;
+    private readonly send;
+    private emitCommand;
+    private openBrokerPicker;
+    private wire;
+    private slashContext;
+    /** Record a leading slash command as used. Called only once the command has
+     *  actually run — after a successful local dispatch or a successful send — so
+     *  refused, unsupported, and rejected submissions never bias completion. */
+    private recordCommandUse;
+    /** Record usage so `/` completion can bias toward frequently/recently used
+     *  items next time. A leading slash token is a command; every resolvable
+     *  memory ref found in submitted prose is a ref use. Called only on the
+     *  success paths of `handleSubmit` — never for bash, a refused drive, or a
+     *  submission that classified out. */
+    private recordCompletionUse;
+    private handleSubmit;
+    private handleFollowUp;
+    private handleDequeue;
+    private emitDrive;
+    private handlePaste;
+    private attachImage;
+    private expandImagePlaceholders;
+    private clearPastedImages;
+    private openExternalEditor;
+    private notify;
+}

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

@@ -0,0 +1,7 @@
+var p=Object.defineProperty;var r=(d,e)=>p(d,"name",{value:e,configurable:!0});import{spawn as u}from"node:child_process";import{readFileSync as f,unlinkSync as k,writeFileSync as g}from"node:fs";import{tmpdir as y}from"node:os";import{join as P}from"node:path";import{BROKER_READ_CAPS as v,encodeFrame as x}from"../../../core/runtime/broker-protocol.js";import{classifySubmit as w}from"../../conversation/submit.js";import{findRefTokens as C}from"../../../shared/inline-ref-grammar.js";import{dispatchSlashCommand as T,isSlashCommand as m}from"../slash/dispatch.js";import{viewerOperationForFrame as S}from"./capabilities.js";import{readClipboardImage as b,writeClipboardImageToFile as I}from"./clipboard-image.js";import{InputOverlayOwner as E}from"./overlay-owner.js";import{announceFallbackEditor as A,NO_EDITOR_MESSAGE as D,resolveEditor as q}from"../../../core/editor-resolver.js";const M=500,F=v.maxLineBytes-4*1024*1024;class z{static{r(this,"InputController")}tui;editor;keybindings;hooks;capabilities;overlays;state;lastEscapeAt=0;pastedImages=new Map;pasteSeq=0;constructor(e,t,o,i,s){this.tui=e,this.editor=t,this.keybindings=o,this.hooks=i,this.capabilities=s,this.overlays=new E(e,t,o,{send:r(n=>this.emitCommand(n),"send"),notify:r(n=>this.notify(n),"notify"),onDialogResponse:i.onDialogResponse,onRequest:i.onRequest,onMountPicker:i.onMountPicker,onUnmountPicker:i.onUnmountPicker,state:r(()=>this.state,"state")}),this.wire()}cycleLadder(e){this.emitCommand({type:"cycle_ladder",direction:e})}sendInterrupting(e){return this.emitDrive({type:"prompt",text:e,interrupt:!0})}abortTurn(){return this.state?.isStreaming!==!0?!1:this.emitCommand({type:"abort"})}attachDialog(e){this.overlays.attachDialog(e)}dismissDialog(e){this.overlays.dismissDialog(e)}setState(e){this.state=e}openFileReviewPicker(e,t,o){this.overlays.openFileReviewPicker(e,t,o)}openAuthPicker(e){return this.overlays.openAuthPicker(e)}send=r(e=>{this.emitCommand(e)},"send");emitCommand(e){const t=S(e),o=t===void 0?void 0:this.capabilities.refusal(t);return o===void 0?(this.hooks.onCommand(e),!0):(this.notify(o),!1)}openBrokerPicker(e){const t=this.capabilities.refusal("engine-drive");if(t!==void 0){this.notify(t);return}e()}wire(){this.editor.onSubmit=t=>this.handleSubmit(t),this.editor.onEscape=()=>{if(this.state?.isStreaming){this.emitCommand({type:"abort"});return}if(this.editor.getText().trim())return;const t=Date.now();t-this.lastEscapeAt<M?(this.lastEscapeAt=0,this.openBrokerPicker(()=>{this.overlays.openTreePicker()})):this.lastEscapeAt=t},this.editor.onPasteImage=()=>{this.handlePaste()};const e=this.editor;e.onPasteImagePath=t=>(this.attachImage(t),!0),this.editor.onAction("app.session.new",()=>this.emitCommand({type:"new_session"})),this.editor.onAction("app.model.cycleForward",()=>this.emitCommand({type:"cycle_model",direction:"forward"})),this.editor.onAction("app.model.cycleBackward",()=>this.emitCommand({type:"cycle_model",direction:"backward"})),this.editor.onAction("app.thinking.cycle",()=>this.emitCommand({type:"cycle_thinking"})),this.editor.onAction("app.message.followUp",()=>this.handleFollowUp()),this.editor.onAction("app.message.dequeue",()=>{this.handleDequeue()}),this.editor.onAction("app.tools.expand",()=>this.hooks.onToggleToolsExpand?.()),this.editor.onAction("app.thinking.toggle",()=>this.hooks.onToggleThinking?.()),this.editor.onAction("app.editor.external",()=>{this.openExternalEditor()}),this.editor.onAction("app.model.select",()=>this.openBrokerPicker(()=>{this.overlays.openModelPicker()})),this.editor.onAction("app.session.tree",()=>this.openBrokerPicker(()=>{this.overlays.openTreePicker()})),this.editor.onAction("app.session.fork",()=>this.openBrokerPicker(()=>{this.overlays.openForkPicker()})),this.editor.onAction("app.session.resume",()=>this.openBrokerPicker(()=>{this.overlays.openSessionPicker()}))}slashContext(){return{send:this.send,notify:r(e=>this.notify(e),"notify"),capabilities:this.capabilities,state:this.state,cwd:process.cwd(),onGraph:this.hooks.onGraph,onInbox:this.hooks.onInbox,onHelp:this.hooks.onHelp,onQuit:this.hooks.onQuit,onCopy:this.hooks.onCopy,onCopyTarget:this.hooks.onCopyTarget,onToggleMouse:this.hooks.onToggleMouse,onColor:this.hooks.onColor,onNodeMetadata:this.hooks.onNodeMetadata,onFoldTools:this.hooks.onFoldTools,openModelPicker:r(()=>this.openBrokerPicker(()=>{this.overlays.openModelPicker()}),"openModelPicker"),openSessionPicker:r(()=>this.openBrokerPicker(()=>{this.overlays.openSessionPicker()}),"openSessionPicker"),openForkPicker:r(()=>this.openBrokerPicker(()=>{this.overlays.openForkPicker()}),"openForkPicker"),openTreePicker:r(()=>this.openBrokerPicker(()=>{this.overlays.openTreePicker()}),"openTreePicker"),openSettingsPicker:r(()=>this.openBrokerPicker(()=>{this.overlays.openSettingsPicker()}),"openSettingsPicker"),openScopedModelsPicker:r(()=>this.openBrokerPicker(()=>{this.overlays.openScopedModelsPicker()}),"openScopedModelsPicker"),openMcpPicker:r(e=>this.overlays.openMcpPicker(e),"openMcpPicker"),openLoginPicker:this.hooks.openLoginPicker,openLogoutPicker:this.hooks.openLogoutPicker}}recordCommandUse(e){const t=this.hooks.frecency;if(!t)return;const o=e.slice(1).split(/\s/,1)[0];o&&t.record(`command:${o}`)}recordCompletionUse(e){const t=this.hooks.frecency;if(!t)return;const o=e.trim();if(m(o)){this.recordCommandUse(o);return}const i=this.hooks.knownRefNames?.();if(!i||i.size===0)return;const s=new Set;for(const n of C(e))i.has(n.candidate)&&!s.has(n.candidate)&&(s.add(n.candidate),t.record(`ref:${n.candidate}`))}handleSubmit(e){const t=e.trim();if(!t)return;if(m(t)&&T(t,this.slashContext())){this.recordCommandUse(t),this.editor.setText("");return}const o=this.hooks.isDormant?.()===!0;if(o&&(t.startsWith("/")||t.startsWith("!"))){this.notify("This node is parked \u2014 submit a message to wake it; broker commands need a live engine");return}const i=w(e,{isDormant:o,canWakeDormant:o&&this.capabilities.permits("wake-dormant")&&this.hooks.onDormantSubmit!==void 0,isStreaming:this.state?.isStreaming===!0});if(i.kind==="empty")return;if(i.kind==="dormant"){const a=this.hooks.onDormantSubmit;if(a===void 0)return;a(this.expandImagePlaceholders(i.text)),this.recordCompletionUse(e),this.editor.addToHistory(i.trimmed),this.editor.setText(""),this.clearPastedImages(),this.hooks.onPromptSent?.();return}if(i.kind==="bash"){if(!this.emitDrive({type:"bash",command:i.command,excludeFromContext:i.excludeFromContext}))return;this.editor.addToHistory(i.trimmed),this.editor.setText("");return}const s=i.kind==="slash"?this.state?.isStreaming===!0?"steer":"prompt":i.kind;if(s!=="steer"&&s!=="prompt")return;const n=this.expandImagePlaceholders(i.kind==="slash"?e:i.text);this.emitDrive(s==="steer"?{type:"steer",text:n}:{type:"prompt",text:n})&&(this.recordCompletionUse(e),this.editor.addToHistory(i.trimmed),this.editor.setText(""),this.clearPastedImages(),this.hooks.onPromptSent?.())}handleFollowUp(){const e=this.editor.getText(),t=e.trim();t&&this.emitDrive({type:"follow_up",text:this.expandImagePlaceholders(e)})&&(this.editor.addToHistory(t),this.editor.setText(""),this.clearPastedImages())}async handleDequeue(){const e=this.capabilities.refusal("dequeue");if(e!==void 0){this.notify(e);return}const t=this.hooks.onRequest;if(t===void 0){this.notify("Restoring queued messages isn't available in this viewer");return}let o;try{o=await t({type:"dequeue"})}catch(s){this.notify(`Could not restore queued messages: ${s instanceof Error?s.message:String(s)}`);return}if(o.kind!=="dequeue"){this.notify("Unexpected reply restoring queued messages");return}const i=[...o.steering,...o.followUp];if(i.length===0){this.notify("No queued messages to restore");return}this.editor.setText([i.join(`
+
+`),this.editor.getText()].filter(s=>s.trim()).join(`
+
+`)),this.tui.requestRender(),this.notify(`Restored ${i.length} queued message${i.length>1?"s":""} to editor`)}emitDrive(e){try{const t=Buffer.byteLength(x(e));if(t>F)return this.notify(`Message too large to send (${Math.round(t/(1024*1024))} MiB) \u2014 shorten the text or remove an attached image`),!1}catch{return this.notify("Message could not be encoded"),!1}return this.emitCommand(e)}async handlePaste(){try{const e=await b();if(!e){this.notify("No image in the clipboard");return}if(!e.image){this.notify(e.note??"Image not pasted");return}this.attachImage(I(e.image),e.note)}catch{this.notify("Could not read the clipboard image")}}attachImage(e,t){const o=++this.pasteSeq;this.pastedImages.set(o,e);const i=this.editor.getText();this.editor.insertTextAtCursor(`${i&&!/\s$/.test(i)?" ":""}[Image #${o}] `),this.notify(t?`Image #${o} attached (${t})`:`Image #${o} attached`),this.tui.requestRender()}expandImagePlaceholders(e){return e.replace(/\[Image #(\d+)\]/g,(t,o)=>this.pastedImages.get(Number(o))??t)}clearPastedImages(){this.pastedImages.clear(),this.pasteSeq=0}async openExternalEditor(){const e=q();if(e===null){this.notify(D);return}const t=e.command,o=this.editor,i=P(y(),`crtr-attach-editor-${Date.now()}.pi.md`);try{g(i,o.getExpandedText?.()??this.editor.getText(),"utf-8"),this.tui.stop();const[s,...n]=t.split(" ");process.stdout.write(`Launching external editor: ${t}
+The viewer resumes when it exits.
+`),A(e);const a=await new Promise(h=>{const c=u(s,[...n,i],{stdio:"inherit",shell:process.platform==="win32"});c.on("error",()=>h(null)),c.on("close",l=>h(l))});a===null&&e.source==="fallback"&&this.notify(`Could not launch ${t} \u2014 set $EDITOR to an editor you have installed`),a===0&&this.editor.setText(f(i,"utf-8").replace(/\n$/,""))}catch(s){this.notify(`External editor failed: ${s instanceof Error?s.message:String(s)}`)}finally{try{k(i)}catch{}this.tui.start(),this.tui.requestRender(!0)}}notify(e){this.hooks.onNotice?.(e)}}export{z as InputController};

package/dist/clients/attach/input/overlay-owner.d.ts

@@ -0,0 +1,41 @@
+import type { CustomEditor } from '@earendil-works/pi-coding-agent';
+import type { Component, KeybindingsManager, TUI } from '@earendil-works/pi-tui';
+import type { BrokerDataFrame, BrokerSnapshot, ClientToBroker, RpcExtensionUIRequest, RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
+import type { ReadOpRequest } from '../../../core/broker-client/index.js';
+import { type Picker, type PickerControls } from '../overlays/pickers.js';
+export interface InputOverlayHooks {
+    send: (frame: ClientToBroker) => void;
+    notify: (message: string) => void;
+    onDialogResponse: (response: RpcExtensionUIResponse) => void;
+    onRequest?: (frame: ReadOpRequest) => Promise<BrokerDataFrame>;
+    onMountPicker?: (component: Component) => void;
+    onUnmountPicker?: () => void;
+    state: () => BrokerSnapshot['state'] | undefined;
+}
+/** Owns transient dialog and picker lifetime. Editor submission remains with
+ * InputController; this collaborator owns mount, replacement, dismissal, and
+ * focus restoration for every transient input surface. */
+export declare class InputOverlayOwner {
+    private readonly tui;
+    private readonly editor;
+    private readonly keybindings;
+    private readonly hooks;
+    private dialog;
+    private dialogId;
+    private picker;
+    private openSeq;
+    constructor(tui: TUI, editor: CustomEditor, keybindings: KeybindingsManager, hooks: InputOverlayHooks);
+    attachDialog(request: RpcExtensionUIRequest): void;
+    dismissDialog(id: string): void;
+    openModelPicker(): Promise<void>;
+    openSessionPicker(): Promise<void>;
+    openTreePicker(): Promise<void>;
+    openForkPicker(): Promise<void>;
+    openSettingsPicker(): Promise<void>;
+    openScopedModelsPicker(): Promise<void>;
+    openMcpPicker(serverName?: string): void;
+    openFileReviewPicker(candidates: string[], cwd: string, onChoose: (file: string) => void): void;
+    openAuthPicker(prepare: () => Promise<(controls: PickerControls) => Picker>): Promise<void>;
+    private openPicker;
+    private showPicker;
+}

package/dist/clients/attach/input/overlay-owner.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var h=(u,e)=>f(u,"name",{value:e,configurable:!0});import{isBlockingDialog as a,renderDialog as g}from"../overlays/dialogs.js";import{buildForkPicker as P,buildModelPicker as y,buildScopedModelsPicker as m,buildSessionPicker as S,buildSettingsPicker as w,buildTreePicker as _}from"../overlays/pickers.js";import{buildMcpPicker as b,readMcpServers as M,startMcpServerAction as R,MCP_EMPTY_STATE_HINT as q}from"../overlays/mcp.js";import{buildFileReviewPicker as v}from"../overlays/file-review.js";const T={anchor:"center",width:"80%",maxHeight:"85%"};class O{static{h(this,"InputOverlayOwner")}tui;editor;keybindings;hooks;dialog;dialogId;picker;openSeq=0;constructor(e,i,t,s){this.tui=e,this.editor=i,this.keybindings=t,this.hooks=s}attachDialog(e){if(e.method==="notify"){const i=e.notifyType==="error"?"Error: ":e.notifyType==="warning"?"Warning: ":"";this.hooks.notify(`${i}${e.message}`),this.tui.requestRender();return}a(e)&&(this.dialog?.dismiss(),this.dialogId=e.id,this.dialog=g(this.tui,e,i=>{this.dialog=void 0,this.dialogId=void 0,this.hooks.onDialogResponse(i)},this.keybindings),this.tui.requestRender())}dismissDialog(e){this.dialogId===e&&(this.dialog?.dismiss(),this.dialog=void 0,this.dialogId=void 0,this.tui.requestRender())}openModelPicker(){return this.openPicker({type:"list_models"},"list_models","model",(e,i)=>y(this.tui,e,this.hooks.send,i))}openSessionPicker(){const e=this.hooks.onRequest;return e===void 0?(this.hooks.notify("The session picker isn't available in this viewer"),Promise.resolve()):(this.openSeq++,this.showPicker(i=>S(this.tui,this.hooks.state()?.sessionFile,e,this.keybindings,this.hooks.send,i.close)),Promise.resolve())}openTreePicker(){return this.openPicker({type:"get_tree"},"get_tree","tree",(e,i)=>_(this.tui,e,this.hooks.send,i))}openForkPicker(){return this.openPicker({type:"get_tree"},"get_tree","fork",(e,i)=>P(e,this.hooks.send,i))}openSettingsPicker(){return this.openPicker({type:"get_settings"},"get_settings","settings",(e,i)=>w(e,this.hooks.send,i))}openScopedModelsPicker(){return this.openPicker({type:"list_scoped_models"},"list_scoped_models","scoped-models",(e,i)=>m(e,i,this.hooks.notify))}openMcpPicker(e){const i=M();if(i.length===0){this.hooks.notify(q);return}if(e!==void 0){const t=i.find(s=>s.name===e);if(t===void 0){this.hooks.notify(`No MCP server named ${JSON.stringify(e)} \u2014 usage: /mcp [server]`);return}R(t,this.hooks.send,this.hooks.notify);return}this.showPicker(t=>b(i,this.hooks.send,t.close,this.hooks.notify))}openFileReviewPicker(e,i,t){this.showPicker(s=>v(e,i,n=>{s.close(),t(n)},s.close,this.hooks.notify))}async openAuthPicker(e){const i=++this.openSeq;let t;try{t=await e()}catch(s){this.hooks.notify(`Could not open the auth picker: ${s instanceof Error?s.message:String(s)}`);return}i===this.openSeq&&this.showPicker(t)}async openPicker(e,i,t,s){const n=this.hooks.onRequest;if(n===void 0){this.hooks.notify(`The ${t} picker isn't available in this viewer`);return}const c=++this.openSeq;let d;try{d=await n(e)}catch(r){this.hooks.notify(`Could not open the ${t} picker: ${r instanceof Error?r.message:String(r)}`);return}if(c===this.openSeq){if(d.kind!==i){this.hooks.notify(`Unexpected reply building the ${t} picker`);return}this.showPicker(r=>s(d,r.close))}}showPicker(e){this.picker?.dismiss();const i=this.hooks.onMountPicker!==void 0&&this.hooks.onUnmountPicker!==void 0;let t,s,n=!1;const c=h(()=>{const o=s?.component;try{o?.dispose?.()}catch{}},"disposeCurrent"),d=h(o=>{i?this.hooks.onMountPicker(o.component):t=this.tui.showOverlay(o.component,T),this.tui.setFocus(o.focus)},"mount"),r=h(()=>{i?this.hooks.onUnmountPicker?.():t?.hide()},"unmount"),k=h((o,p)=>{n||(c(),r(),s={component:o,focus:p},d(s),this.tui.requestRender())},"replace"),l=h(()=>{n||(n=!0,c(),r(),this.picker=void 0,this.tui.setFocus(this.editor),this.tui.requestRender())},"close");try{s=e({close:l,replace:k})}catch(o){this.hooks.notify(`Could not open picker: ${o instanceof Error?o.message:String(o)}`);return}d(s),this.picker={dismiss:h(()=>{n||(n=!0,c(),r())},"dismiss")},this.tui.requestRender()}}export{O as InputOverlayOwner};

package/dist/clients/attach/input/ref-autocomplete.d.ts

@@ -0,0 +1,77 @@
+import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from '@earendil-works/pi-tui';
+import type { RefMeta } from '../../../core/runtime/broker-protocol.js';
+import { type FrecencyStore } from './completion-frecency.js';
+/** The caret's classification for completion purposes. `null` means the caret
+ *  is not touching any slash token at all (every other autocomplete mode —
+ *  file, `@`, etc. — is unaffected and this provider fully delegates). */
+export type RefCompletionContext = {
+    kind: 'leading';
+    startCol: number;
+    endCol: number;
+    prefix: string;
+} | {
+    kind: 'ref';
+    startCol: number;
+    endCol: number;
+    prefix: string;
+};
+/**
+ * Classify the slash token (if any) touching the caret at
+ * `(cursorLine, cursorCol)` in the editor's logical `lines`. Joins the lines
+ * with `\n` (the editor's own logical-text convention — no grammar character
+ * is `\n`, so a token can never straddle a line boundary) and delegates the
+ * actual token detection to the shared `findRefTokenAtCaret`.
+ *
+ * `kind: 'leading'` means the token's `/` sits at the very start of the whole
+ * message (global offset 0) — the existing command-only leading-completion
+ * context, which this provider must not touch. Anything else — including a
+ * `/` at the start of a LATER logical line, where the preceding joined-text
+ * character is `\n`, not "start of input" — is `kind: 'ref'`.
+ *
+ * Returns `null` when the caret is not touching a token at all: it is not at
+ * a token-starting `/` (offset zero or after ASCII whitespace only), it is
+ * after non-whitespace, or it has moved past the end of the grammar run.
+ */
+export declare function findRefCompletionContext(lines: readonly string[], cursorLine: number, cursorCol: number): RefCompletionContext | null;
+/**
+ * Wraps an existing command-only `AutocompleteProvider` (in practice always a
+ * `CombinedAutocompleteProvider`) so that:
+ *
+ * - Leading-command context (`kind: 'leading'`) and every non-ref context
+ *   (`context === null`, e.g. file/`@` completion) delegate verbatim — byte-
+ *   for-byte unchanged command/file/`@` completion.
+ * - A non-leading ref context (`kind: 'ref'`) is served entirely from the
+ *   supplied `refs` inventory instead: case-sensitive prefix filtering by the
+ *   typed surface form, `shortForm` as the row description, and a completion
+ *   that replaces only the detected token range with no trailing separator.
+ *
+ * Refs are never merged into the wrapped provider's command list, so leading
+ * `/` completion always remains commands-only even when a ref shares a name
+ * with something in `refs`.
+ */
+export declare class RefAwareAutocompleteProvider implements AutocompleteProvider {
+    private readonly refs;
+    private readonly refNames;
+    private readonly delegate;
+    private readonly frecency;
+    constructor(refs: ReadonlyArray<RefMeta>, delegate: AutocompleteProvider, frecency: FrecencyStore);
+    /** Pass through unchanged — pi-tui's editor explicitly discards `/` as a
+     *  trigger character regardless, and `CombinedAutocompleteProvider` doesn't
+     *  declare any of its own, so this is normally `undefined`. */
+    get triggerCharacters(): string[] | undefined;
+    getSuggestions(lines: string[], cursorLine: number, cursorCol: number, options: {
+        signal: AbortSignal;
+        force?: boolean;
+    }): Promise<AutocompleteSuggestions | null>;
+    applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+        lines: string[];
+        cursorLine: number;
+        cursorCol: number;
+    };
+    /** Admits forced (Tab) completion in a non-leading ref context, where
+     *  pi-tui's own leading-slash short-circuit doesn't apply (the current
+     *  line's text before the cursor doesn't start with `/`, so its Tab
+     *  handler routes through the forced-file path gated by this method).
+     *  Every other case delegates unchanged. */
+    shouldTriggerFileCompletion(lines: string[], cursorLine: number, cursorCol: number): boolean;
+}

package/dist/clients/attach/input/ref-autocomplete.js

@@ -0,0 +1,2 @@
+var x=Object.defineProperty;var o=(f,e)=>x(f,"name",{value:e,configurable:!0});import{findRefTokenAtCaret as C,formatRefToken as m}from"../../../shared/inline-ref-grammar.js";import{leafFirstSearchable as u,normalizeRefQuery as y,rankByFuzzyFrecency as p}from"./completion-frecency.js";function h(f,e,n){const i=f.join(`
+`);let t=0;for(let s=0;s<e&&s<f.length;s++)t+=f[s].length+1;const l=t+n,a=C(i,l);if(!a)return null;const c=a.start-t,r=a.end-t;return{kind:a.start===0?"leading":"ref",startCol:c,endCol:r,prefix:a.surfacePrefix}}o(h,"findRefCompletionContext");class v{static{o(this,"RefAwareAutocompleteProvider")}refs;refNames;delegate;frecency;constructor(e,n,i){this.refs=e,this.refNames=new Set(e.map(t=>t.name)),this.delegate=n,this.frecency=i}get triggerCharacters(){return this.delegate.triggerCharacters}async getSuggestions(e,n,i,t){const l=h(e,n,i);if(!l)return this.delegate.getSuggestions(e,n,i,t);if(l.kind==="leading"){if(t.force)return this.delegate.getSuggestions(e,n,i,t);const r=(e[n]??"").slice(0,i),g=await this.delegate.getSuggestions(["/"],0,1,t);if(!g)return null;const s=p(g.items,r.slice(1),{searchableOf:o(d=>u(d.value),"searchableOf"),idOf:o(d=>`command:${d.value}`,"idOf"),store:this.frecency});return s.length===0?null:{items:s,prefix:r}}const a=p(this.refs,y(l.prefix.slice(1)),{searchableOf:o(r=>u(r.name),"searchableOf"),idOf:o(r=>`ref:${r.name}`,"idOf"),store:this.frecency});return a.length===0?null:{items:a.map(r=>({value:r.name,label:m(r.name),description:r.shortForm||void 0})),prefix:l.prefix.slice(1)}}applyCompletion(e,n,i,t,l){const a=h(e,n,i);if(a&&a.kind==="ref"&&this.refNames.has(t.value)){const c=m(t.value),r=e[n]??"",g=r.slice(0,a.startCol)+c+r.slice(a.endCol),s=e.slice();return s[n]=g,{lines:s,cursorLine:n,cursorCol:a.startCol+c.length}}return this.delegate.applyCompletion(e,n,i,t,l)}shouldTriggerFileCompletion(e,n,i){const t=h(e,n,i);return t&&t.kind==="ref"?!0:this.delegate.shouldTriggerFileCompletion?this.delegate.shouldTriggerFileCompletion(e,n,i):!1}}export{v as RefAwareAutocompleteProvider,h as findRefCompletionContext};