synabun 2.0.0 → 2.0.5

package/neural-interface/public/shared/cdx/cdx-tabs.js

@@ -13,6 +13,7 @@ import {
 } from './cdx-plan.js';
 import { fetchBlobNamespace, putBlob, deleteBlob, flushBlobs } from '../blob-store.js';
 import { state as appState, on as appOn } from '../state.js';
+import { forgetGreeting, mountGreeting } from '../greeting/greeting-card.js';
 import { fetchProjects, searchSessions } from '../api.js';
 import {
   getCodexModelName,
@@ -24,6 +25,8 @@ import { syncSidepanelLayout, focusSidepanel, isHostedSessionFocused } from '../
 import { notify, NOTIF_TYPE } from '../ui-notifications.js';
 import { createStickyScrollController } from '../ui-scroll-follow.js';
 import { requestGeneratedSessionTitle } from '../session-title.js';
+import { fileLinkText } from '../ui-file-links.js';
+import { WORKER_END_CLASS, backToAssistant, buildWorkerEndCard, endWorkerRunOnClose, forgetWorkerEnd } from '../ui-worker-end.js';
 import {
   CODEX_COMMANDS, CODEX_COMMAND_BY_NAME, parseCodexCommand, codexCommandHints,
   capabilityAvailability, latestCompletedCodexText, configValue, configRestriction,
@@ -467,6 +470,8 @@ function buildWsCallbacks(tab, options = {}) {
         clearTranscript();
       }
       restoreServerRequests(heldRequests);
+      // The history rebuilt the transcript: a dispatched worker's end card goes back at its end.
+      placeWorkerEnd(tab);
       if (options.historyOnly) {
         tab._automationHydrated = true;
         closeAutomationHistorySocket(tab);
@@ -1247,6 +1252,7 @@ function writeThreadSnapshot(tab, { force = false } = {}) {
   const accountId = String(tab.accountId || 'default');
   const snapshotNodes = [...messagesEl.children].filter((node) => (
     !node.classList?.contains('cxp-empty') && !node.classList?.contains('cxp-thinking')
+    && !node.classList?.contains(WORKER_END_CLASS)
   ));
   const ownsEveryNode = codexTranscriptNodesHaveOwnership(snapshotNodes, { threadId, accountId });
   if (!ownsEveryNode) {
@@ -1257,6 +1263,8 @@ function writeThreadSnapshot(tab, { force = false } = {}) {
   }
   const snapshotEl = messagesEl.cloneNode(true);
   stripMcpAppRuntime(snapshotEl);
+  // A worker's end card is drawn again from its run, never restored from markup.
+  snapshotEl.querySelectorAll(`.${WORKER_END_CLASS}`).forEach((node) => node.remove());
   const html = snapshotEl.innerHTML || '';
   if (!html.trim()) return;
   const ownedItemNodes = snapshotNodes.filter((node) => node.dataset?.itemId);
@@ -1506,6 +1514,11 @@ function storedAutoAccept() {
 function releaseAutomationForManualUse(tab = _boundTab) {
   const runId = detachTerminalCodexAutomation(tab, storedAutoAccept());
   if (!runId) return false;
+  // While the tab still shows the run's thread, the dock's Focus on the run raises it (cdx-panel.js).
+  tab.releasedRunId = runId;
+  forgetWorkerEnd(runId);
+  tab._workerEnd = null;
+  placeWorkerEnd(tab);
   window.dispatchEvent(new CustomEvent('native-loop:dismissed', { detail: { runId } }));
   if (isActiveTab(tab)) syncToolbarState();
   saveTabs();
@@ -2843,6 +2856,7 @@ export function createTab(saved = {}, { autoSwitch = true } = {}) {
     automationRunId,
     automationActive: !!saved.automationActive,
     automationOwnerId: saved.automationOwnerId || null,
+    releasedRunId: automationRunId ? null : (saved.releasedRunId || null),
   };
   tab.messagesEl = createMessagesEl(tab);
   tab.pillEl = createTrayPill(tab);
@@ -2870,15 +2884,18 @@ export function closeTab(idx, { detachAutomation = false } = {}) {
   const tab = _tabs[idx];
   teardownMcpApps(tab, 'Tab closed');
   if (tab.automationRunId && !detachAutomation) {
+    const runId = tab.automationRunId;
     window.dispatchEvent(new CustomEvent('native-loop:dismissed', {
-      detail: { runId: tab.automationRunId },
+      detail: { runId },
     }));
-    fetch('/api/loop/stop', {
+    // A worker that finished its task is completed; any other run is stopped.
+    endWorkerRunOnClose(runId, () => fetch('/api/loop/stop', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ runId: tab.automationRunId }),
-    }).catch(() => {});
+      body: JSON.stringify({ runId }),
+    }).catch(() => {}));
   }
+  if (tab.automationRunId) forgetWorkerEnd(tab.automationRunId);
   wsDisconnectTab(tab, { releaseWriter: !tabHasActiveWriterWork(tab) });
   tab.closed = true;
   tab.titleRequestController?.abort();
@@ -2923,6 +2940,31 @@ export function closeTab(idx, { detachAutomation = false } = {}) {
   saveTabs();
 }
 
+/**
+ * The end of a worker the Assistant dispatched (ui-worker-end.js), as
+ * `tab._workerEnd` says it: one card, the last node of the transcript, put
+ * back after a history render and never in a snapshot. Its button closes the
+ * tab the way the X does (a warm worker that finished its task is completed,
+ * one still at work is stopped; its record stays for the Assistant) and shows
+ * the Assistant session that dispatched it.
+ */
+export function placeWorkerEnd(tab) {
+  const messagesEl = tab?.messagesEl;
+  if (!messagesEl || tab.closed) return;
+  messagesEl.querySelectorAll(`:scope > .${WORKER_END_CLASS}`).forEach((node) => node.remove());
+  const view = tab._workerEnd;
+  if (!view) return;
+  messagesEl.appendChild(buildWorkerEndCard(view, {
+    classes: { card: 'cxp-worker-end', title: 'cxp-post-plan-header', detail: 'cxp-post-plan-note', button: 'cxp-request-btn' },
+    onBack: () => {
+      const idx = _tabs.indexOf(tab);
+      if (idx >= 0) closeTab(idx);
+      backToAssistant(view.assistantSessionId);
+    },
+  }));
+  if (isActiveTab(tab)) scrollEnd(true);
+}
+
 export function saveTabs() {
   try {
     commitBoundState();
@@ -2977,6 +3019,7 @@ export function saveTabs() {
           automationRunId: tab.automationRunId || null,
           automationActive: !!tab.automationActive,
           automationOwnerId: tab.automationOwnerId || null,
+          releasedRunId: tab.releasedRunId || null,
         };
       });
     const localRunIds = new Set(localTabs.map((tab) => tab.automationRunId).filter(Boolean));
@@ -3097,6 +3140,34 @@ export function updateTrayPillRunning() {
 }
 
 
+// ── Greeting (shared/greeting/, lib/greeting/) ──
+// What SynaBun says when a person comes back and opens a new thread: one or two sentences in the
+// empty state, written by SynaBun ahead of time (the thread's model never greets). Only for the
+// bound tab while it holds no thread and shows no automation run; the short wait lets a tab that
+// was made for a run, or is restoring a thread, say so first. Its id goes back with the first
+// prompt (`greetingId`), so the model is told once what was said.
+function offerGreetingSoon() {
+  const tab = _boundTab;
+  if (!tab) return;
+  setTimeout(() => { try { offerGreeting(tab); } catch { /* a thread always opens */ } }, 300);
+}
+function offerGreeting(tab) {
+  if (tab !== _boundTab || tab.closed || _threadId || _running || _startingThread || tab.automationActive || tab.automationRunId) return;
+  const host = _messagesEl?.querySelector(':scope > .cxp-empty');
+  if (!host || host.style.display === 'none') return;
+  // "Restoring Codex thread…" / "Starting fresh Codex thread…": not an idle new thread.
+  if (host.querySelector('.cxp-empty-status')?.textContent) return;
+  const key = () => `${tab.id}.${tab.greetSeq || 0}`;
+  const session = key();
+  mountGreeting(host, {
+    surface: 'codex-panel', session, cwd: _project || tab.project || '',
+    onOpenMemory: (id) => { if (id) emit('memory:open', { id }); },
+    isCurrent: () => tab === _boundTab && !_threadId && session === key() && !!_messagesEl?.contains(host),
+  }).then((greeting) => {
+    if (session === key()) tab.greeting = greeting ? { id: greeting.id, session } : null;
+  }).catch(() => {});
+}
+
 // ── Thread state (lines 4711-5000) ──
 function hideEmpty() {
   const empty = _messagesEl?.querySelector('.cxp-empty');
@@ -3125,6 +3196,7 @@ export function clearTranscript(emptyText = freshThreadText()) {
   for (const child of [..._messagesEl.children]) retireMcpAppNode(child, () => child.remove());
   _messagesEl.insertAdjacentHTML('afterbegin', `<div class="cxp-empty"><div class="cxp-empty-logo">${OPENAI_ICON}</div><span class="cxp-empty-name">Codex</span><span class="cxp-empty-status"></span></div>`);
   document.dispatchEvent(new CustomEvent('cdx-empty-rebuilt'));
+  if (!emptyText) offerGreetingSoon();
   _items.clear();
   _requestCards.clear();
   _blockingServerRequests = new Map();
@@ -3285,6 +3357,8 @@ export function resetThreadState({ tone = 'ready', preserveStatus = false } = {}
   clearPostCompactionState(_boundTab, { updateTranscript: false });
   setSessionLabel('New session', { persist: false });
   if (!preserveStatus) setStatus(_project ? 'Fresh thread ready' : 'Select a project', tone);
+  // A new thread in the same tab is a new opening for the greeting.
+  if (_boundTab) { _boundTab.greetSeq = (_boundTab.greetSeq || 0) + 1; _boundTab.greeting = null; }
   clearTranscript();
   syncInputEnabled();
   syncSessionControls();
@@ -4954,6 +5028,14 @@ export function dispatchPrompt(prompt, { tab = activeTab(), images = null, paths
   };
   if (tab?.model) msg.model = tab.model;
   if (tab?.effort && tab.effort !== 'off') msg.effort = tab.effort;
+  // A person's own turn: the greeting engine keeps when they were last here. The greeting this
+  // tab opened with goes back once, with the first prompt of its new thread.
+  msg.human = true;
+  if (tab?.greeting?.id) {
+    if (msg.fresh) msg.greetingId = tab.greeting.id;
+    forgetGreeting('codex-panel', tab.greeting.session);
+    tab.greeting = null;
+  }
   if (imageList.length) {
     msg.images = imageList;
   }
@@ -7929,6 +8011,7 @@ export function initContextBridge() {
     withRequestTab: withTab,
     sendSocket,
     emit,
+    fileLinkText,
     activeTab,
     isActiveTab,
     dispatchPrompt,

package/neural-interface/public/shared/constants.js

@@ -64,6 +64,7 @@ export const KEYS = {
   WORKSPACES:          'neural-workspaces',
   ACTIVE_WORKSPACE:    'neural-active-workspace',  // sessionStorage
   GRID_SNAP:           'neural-grid-snap',
+  TOPRIGHT_TOOLS_HIDDEN: 'neural-topright-tools-hidden',  // the workspace tools toggle is off ('true')
   CATEGORIES_VISIBLE:  'neural-categories-visible',
   WHITEBOARD:          'neural-whiteboard',
   WHITEBOARD_RULESET_ALERT_DISMISSED: 'neural-whiteboard-ruleset-alert-dismissed',
@@ -85,6 +86,10 @@ export const KEYS = {
   FILE_EXPLORER_SORT:     'neural-file-explorer-sort',
   FILE_EXPLORER_PROJECT:  'neural-file-explorer-project',
   FILE_EXPLORER_FOLDER_COLORS: 'neural-file-explorer-folder-colors',
+  // Per project: the open folders, the selection, the scroll position, "changed only" (shared/explorer/fx-main.js).
+  FILE_EXPLORER_TREE:     'neural-file-explorer-tree',
+  // Code editor — open tabs per project { v, projects: { [path]: { at, active, tabs: [{ path, pinned, anchor, head, top, dirty }] } } }
+  EDITOR_TABS:            'neural-editor-tabs',
   ACTIVE_SKIN:            'neural-active-skin',
   COST_WIDGET_POS:        'neural-cost-widget-pos',
   COST_WIDGET_COLLAPSED:  'neural-cost-widget-collapsed',
@@ -97,6 +102,7 @@ export const KEYS = {
   ASSISTANT_DOCK_OPEN:    'neural-assistant-dock-open',
   ASSISTANT_DOCK_SHOW_ALL:'neural-assistant-dock-show-all',
   ASSISTANT_ROUTE_MODE:   'neural-assistant-route-mode', // last-used route mode (always-ask|ask-unsure|never)
+  ASSISTANT_TEST_DENSITY: 'neural-assistant-test-density', // last-used test density (none|light|standard|thorough)
   // Assistant sidepanel — open tabs {v:1, activeIdx, tabs:[{sessionId,label,userRenamed}]}
   ASSISTANT_PANEL_TABS:   'synabun-assistant-panel-tabs',
 };
@@ -141,7 +147,6 @@ export const KEYBIND_META = {
   'toggle-explorer':     { label: 'Toggle Explorer',       group: 'Navigation' },
   'toggle-focus-mode':   { label: 'Toggle Focus Mode',     group: 'Navigation' },
   'toggle-minimap':      { label: 'Toggle Minimap',        group: 'View' },
-  'toggle-toolbar':      { label: 'Hide All Toolbars',    group: 'View' },
   'open-settings':       { label: 'Open Settings',          group: 'Settings' },
   'open-keybinds':       { label: 'Open Keybinds',         group: 'Settings' },
   'launch-assistant':    { label: 'Assistant',             group: 'Launch App', icon: 'assistant' },

package/neural-interface/public/shared/cp/cp-rehydrate.js

@@ -14,7 +14,8 @@
 
 import { pagerState } from './cp-restore.js';
 
-const STALE_ROWS = '.thinking, .msg-permission-prompt, .post-plan-card';
+// (A worker's end card is drawn again from its run: ui-worker-end.js.)
+const STALE_ROWS = '.thinking, .msg-permission-prompt, .post-plan-card, .worker-end-card';
 const STALE_PROMPTS = '.cp-plan-approval-card.active-perm, .perm-card.active-perm, .cp-rewind-confirm';
 const SELF_WIRED_CARDS = '.tool-card.cp-bash-card, .tool-card.cp-diff-card, .tool-card.cp-agent-card';
 

package/neural-interface/public/shared/cp/cp-styles.js

@@ -346,4 +346,19 @@ a.cp-chip:hover { text-decoration: underline; }
 .cp-ctxpop-copy { padding: 0; border: none; background: none; font: inherit; line-height: 20px; cursor: pointer; }
 .cp-ctxpop-copy:hover, .cp-ctxpop-copy.cp-ctxpop-copied { color: rgba(220,195,140,0.9); }
 .cp-ctxpop-btn:focus-visible, .cp-ctxpop-link:focus-visible, .cp-ctxpop-copy:focus-visible { outline: 1px solid rgba(255,255,255,0.45); outline-offset: 2px; }
+
+/* ═══ A dispatched worker's end (ui-worker-end.js) ═══
+   The post-plan card's frame, header and primary action, in the transcript column. The title says the state in
+   words; its colour is the panel's success / warning / error. */
+.cp-messages .cp-worker-end { margin: 8px 14px 10px 48px; padding: 8px 10px; border: 1px solid rgba(255,255,255,0.07); border-radius: 8px; background: rgba(255,255,255,0.02); }
+.cp-worker-end .post-plan-header { margin-bottom: 4px; }
+.cp-worker-end[data-tone="ok"] .post-plan-header { color: #5fcf83; }
+.cp-worker-end[data-tone="warn"] .post-plan-header { color: #e0a33e; }
+.cp-worker-end[data-tone="err"] .post-plan-header { color: #ef7070; }
+.cp-worker-end .worker-end-detail { font: 11.5px/1.55 Inter, sans-serif; color: var(--t-secondary); overflow-wrap: anywhere; }
+.cp-worker-end .worker-end-meta { margin-top: 4px; font: 9.5px/1.5 'JetBrains Mono', monospace; color: rgba(255,255,255,0.28); }
+.cp-worker-end .worker-end-note { margin-top: 4px; font: 10.5px/1.5 Inter, sans-serif; color: var(--t-muted); }
+.cp-worker-end .post-plan-actions { margin-top: 8px; }
+.cp-worker-end .post-plan-action:disabled { opacity: 0.45; cursor: default; }
+.cp-worker-end .post-plan-action:focus-visible { outline: 1px solid rgba(255,255,255,0.45); outline-offset: 2px; }
 `;

package/neural-interface/public/shared/editor/editor-ai-logic.js

@@ -0,0 +1,409 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Code editor: AI autocomplete, the decisions
+// ═══════════════════════════════════════════
+//
+// What AI autocomplete decides without a page: whether a request may be made at
+// all, which text around the caret is sent, which files and texts are never
+// sent, what is left of a suggestion while the user types it, and what the
+// status-bar chip says. editor-ai.js acts on these; the server's
+// lib/editor-completion.js imports the limits and the never-sent rules from
+// here, so the two sides cannot disagree about them. No DOM and no imports:
+// loaded by `node --test` as it is.
+
+/** Sizes of what a request carries (docs/design/code-editor/SPEC.md, section 9.3). */
+export const AI_LIMITS = Object.freeze({
+  prefixChars: 6000,      // before the caret, cut at a line start
+  suffixChars: 1500,      // after the caret, cut at a line end
+  headerLines: 40,        // the file's first lines, when the prefix does not start at offset 0
+  headerChars: 4000,
+  neighborCount: 2,       // snippets of other open tabs
+  neighborChars: 1200,
+  pathChars: 1000,
+  completionChars: 1200,  // the most a suggestion holds
+  cacheSize: 20,          // results kept
+  cacheBefore: 300,       // characters before the caret in a cache key
+  cacheAfter: 100,        // characters after it
+});
+
+// The prefix starts on a multiple of this many characters (then at the next line start), so it stays the same
+// text for a while as the caret moves on: a provider that caches the start of a prompt can reuse it.
+const PREFIX_GRID = 1000;
+
+/** What may follow the caret on its line for a suggestion to be asked for: nothing, or closing punctuation. */
+const CLOSING_ONLY = /^[\s)\]}'"`;,]*$/;
+
+const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
+
+// ── Never sent ──
+
+/** The last part of a path, whichever slash it uses. */
+export function fileNameOf(path) {
+  const text = String(path ?? '');
+  return text.slice(Math.max(text.lastIndexOf('/'), text.lastIndexOf('\\')) + 1);
+}
+
+function globToRegExp(glob) {
+  const body = String(glob).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.');
+  return new RegExp(`^${body}$`, 'i');
+}
+
+/**
+ * Whether a file is one AI autocomplete never reads. The globs (`*` any run of characters, `?` one) are matched
+ * on the file's name, not on its folder, whatever the case of its letters.
+ * @param {string} path a path or a bare file name
+ * @param {string[]} globs `ai.exclude`
+ */
+export function matchesExclude(path, globs) {
+  const name = fileNameOf(path);
+  if (!name || !Array.isArray(globs)) return false;
+  return globs.some((glob) => typeof glob === 'string' && glob && globToRegExp(glob).test(name));
+}
+
+/** Whether any of the texts holds the first line of a private key. */
+export function hasPrivateKey(...texts) {
+  return texts.some((text) => typeof text === 'string' && PRIVATE_KEY.test(text));
+}
+
+// ── When to ask ──
+
+/** Whether the rest of the caret's line lets a suggestion in: empty, or only closing punctuation. */
+export function restOfLineAllows(after) {
+  return CLOSING_ONLY.test(String(after ?? ''));
+}
+
+/**
+ * Whether a suggestion may be asked for right now.
+ * @param {object} s
+ * @param {boolean} s.enabled `ai.enabled`
+ * @param {boolean} s.capable the server has the `complete` capability
+ * @param {boolean} [s.readOnly] the document cannot be edited (a save is under way)
+ * @param {boolean} s.focused the document has the keyboard
+ * @param {boolean} s.visible the page is visible
+ * @param {number} s.carets how many carets or selections there are
+ * @param {boolean} s.hasSelection any of them selects text
+ * @param {boolean} s.composing an IME composition is under way
+ * @param {string} s.lineAfter the text after the caret on its line
+ * @param {string} s.path the file's path
+ * @param {string[]} s.exclude `ai.exclude`
+ * @returns {{ ok: true } | { ok: false, reason: 'off' | 'read-only' | 'unfocused' | 'hidden' | 'multiple' | 'selection'
+ *   | 'composing' | 'excluded' | 'mid-line' }} An open completion list is no reason to wait: the suggestion is
+ *   asked for, and kept hidden until the list closes.
+ */
+export function shouldRequest(s = {}) {
+  const no = (reason) => ({ ok: false, reason });
+  if (!s.enabled || !s.capable) return no('off');
+  if (!s.path || matchesExclude(s.path, s.exclude)) return no('excluded');
+  if (s.readOnly) return no('read-only');
+  if (!s.focused) return no('unfocused');
+  if (!s.visible) return no('hidden');
+  if (s.carets !== 1) return no('multiple');
+  if (s.hasSelection) return no('selection');
+  if (s.composing) return no('composing');
+  if (!restOfLineAllows(s.lineAfter)) return no('mid-line');
+  return { ok: true };
+}
+
+/**
+ * Whether suggestions are expected for a document: the feature is on and the server has it, the file is not one
+ * that is never read, and there is a model to ask. While they are, the completion list leaves the words of the
+ * document out unless it is asked for them (Ctrl-Space): a list that opened for every word would cover the
+ * suggestion each time.
+ * @param {{ capable: boolean, enabled: boolean, excluded?: boolean, problem?: { kind: string } | null }} s
+ */
+export function suggestionsExpected({ capable, enabled, excluded = false, problem = null } = {}) {
+  if (!capable || !enabled || excluded) return false;
+  return problem?.kind !== 'no-model' && problem?.kind !== 'no-endpoint';
+}
+
+// ── What is sent ──
+
+/**
+ * The text around the caret that a request carries.
+ * @param {object} o
+ * @param {(from: number, to: number) => string} o.slice reads part of the document (line breaks as "\n")
+ * @param {number} o.length the document's length
+ * @param {number} o.pos the caret
+ * @returns {{ prefix: string, suffix: string, header: string, prefixStart: number, suffixEnd: number }}
+ *   `prefix`: up to 6,000 characters before the caret, from a line start; `suffix`: up to 1,500 after it, to a
+ *   line end; `header`: the file's first 40 lines when the prefix does not reach the start of the file, else ''.
+ */
+export function completionWindow({ slice, length, pos }) {
+  const at = Math.max(0, Math.min(length, pos));
+  let prefixStart = Math.ceil(Math.max(0, at - AI_LIMITS.prefixChars) / PREFIX_GRID) * PREFIX_GRID;
+  let prefix = slice(prefixStart, at);
+  if (prefixStart > 0) {
+    const lineStart = prefix.indexOf('\n');
+    if (lineStart >= 0) { prefixStart += lineStart + 1; prefix = prefix.slice(lineStart + 1); }
+  }
+  let suffixEnd = Math.min(length, at + AI_LIMITS.suffixChars);
+  let suffix = slice(at, suffixEnd);
+  if (suffixEnd < length) {
+    const lineEnd = suffix.lastIndexOf('\n');
+    if (lineEnd >= 0) { suffixEnd = at + lineEnd; suffix = suffix.slice(0, lineEnd); }
+  }
+  // The header stops where the prefix begins: no line is sent twice.
+  const header = prefixStart > 0 ? clampHeader(slice(0, Math.min(prefixStart, AI_LIMITS.headerChars + 1))) : '';
+  return { prefix, suffix, header, prefixStart, suffixEnd };
+}
+
+/** At most the last 6,000 characters of a prefix, from a line start. */
+export function clampPrefix(text) {
+  const prefix = String(text ?? '');
+  if (prefix.length <= AI_LIMITS.prefixChars) return prefix;
+  const cut = prefix.slice(prefix.length - AI_LIMITS.prefixChars);
+  const lineStart = cut.indexOf('\n');
+  return lineStart >= 0 ? cut.slice(lineStart + 1) : cut;
+}
+
+/** At most the first 1,500 characters of a suffix, to a line end. */
+export function clampSuffix(text) {
+  const suffix = String(text ?? '');
+  if (suffix.length <= AI_LIMITS.suffixChars) return suffix;
+  const cut = suffix.slice(0, AI_LIMITS.suffixChars);
+  const lineEnd = cut.lastIndexOf('\n');
+  return lineEnd >= 0 ? cut.slice(0, lineEnd) : cut;
+}
+
+/** At most the first 40 lines and 4,000 characters of a header, whole lines only. */
+export function clampHeader(text) {
+  let header = String(text ?? '').split('\n').slice(0, AI_LIMITS.headerLines).join('\n');
+  if (header.length > AI_LIMITS.headerChars) {
+    const cut = header.slice(0, AI_LIMITS.headerChars);
+    const lineEnd = cut.lastIndexOf('\n');
+    header = lineEnd >= 0 ? cut.slice(0, lineEnd) : cut;
+  }
+  return header.replace(/\n+$/, '');
+}
+
+/**
+ * The body of `POST /api/editor/complete`.
+ * @param {object} o
+ * @param {string} o.path
+ * @param {string} [o.language] the language's name as the status bar shows it
+ * @param {string} [o.indentUnit] one level of indentation (spaces, or a tab)
+ * @param {{ prefix: string, suffix: string, header: string }} o.window from completionWindow()
+ * @param {{ path: string, text: string }[]} [o.neighbors]
+ * @param {'auto' | 'manual'} [o.trigger]
+ */
+export function requestBody({ path, language = '', indentUnit = '  ', window, neighbors = [], trigger = 'auto' }) {
+  const body = { path, language, indentUnit, prefix: window.prefix, suffix: window.suffix, trigger: trigger === 'manual' ? 'manual' : 'auto' };
+  if (window.header) body.header = window.header;
+  if (neighbors.length) body.neighbors = neighbors.slice(0, AI_LIMITS.neighborCount).map((n) => ({ path: n.path, text: String(n.text).slice(0, AI_LIMITS.neighborChars) }));
+  return body;
+}
+
+/**
+ * The part of another open document that is sent along: the 1,200 characters around its caret (the whole text
+ * when it is shorter), whole lines where the window allows.
+ * @param {{ slice: (from: number, to: number) => string, length: number, head?: number }} doc
+ */
+export function neighborSnippet({ slice, length, head = 0 }) {
+  const size = AI_LIMITS.neighborChars;
+  if (length <= size) return slice(0, length);
+  const from = Math.max(0, Math.min(length - size, Math.floor(Number(head) || 0) - size / 2));
+  let text = slice(from, from + size);
+  if (from > 0) {
+    const lineStart = text.indexOf('\n');
+    if (lineStart >= 0 && lineStart < text.length - 1) text = text.slice(lineStart + 1);
+  }
+  if (from + size < length) {
+    const lineEnd = text.lastIndexOf('\n');
+    if (lineEnd > 0) text = text.slice(0, lineEnd);
+  }
+  return text;
+}
+
+/**
+ * Snippets of other open tabs for a request: up to two, of the document's own language, the tabs used last
+ * first. Never a file on the excluded list, never a text that holds a private key, never without a language
+ * (plain text is not code to learn from).
+ * @param {object} o
+ * @param {{ path: string, language: string }} o.current the document the request is for
+ * @param {{ path: string, language: string, length: number, head?: number, slice: (from: number, to: number) => string }[]} o.tabs
+ *   the other open documents, the most recently used first
+ * @param {string[]} o.exclude `ai.exclude`
+ * @returns {{ path: string, text: string }[]}
+ */
+export function pickNeighbors({ current, tabs, exclude } = {}) {
+  const out = [];
+  if (!current?.language) return out;
+  for (const tab of tabs || []) {
+    if (out.length >= AI_LIMITS.neighborCount) break;
+    if (!tab || !tab.path || tab.path === current.path || tab.language !== current.language) continue;
+    if (matchesExclude(tab.path, exclude) || out.some((taken) => taken.path === tab.path)) continue;
+    const text = neighborSnippet(tab);
+    if (!text.trim() || hasPrivateKey(text)) continue;
+    out.push({ path: tab.path, text });
+  }
+  return out;
+}
+
+// ── Results kept ──
+
+function fnv1a(text) {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/** The key a result is kept under: the last 300 characters before the caret, the first 100 after it, and the path. */
+export function cacheKey({ path, prefix, suffix }) {
+  const before = String(prefix ?? '').slice(-AI_LIMITS.cacheBefore);
+  const after = String(suffix ?? '').slice(0, AI_LIMITS.cacheAfter);
+  return `${fnv1a(`${before}\u0000${after}`)}${fnv1a(`${after}\u0000${before}\u0000${path ?? ''}`)}`;
+}
+
+/** The last results, the most recently used last. */
+export function createSuggestionCache(max = AI_LIMITS.cacheSize) {
+  const entries = new Map();
+  return {
+    get(key) {
+      if (!entries.has(key)) return undefined;
+      const value = entries.get(key);
+      entries.delete(key);
+      entries.set(key, value);
+      return value;
+    },
+    set(key, value) {
+      entries.delete(key);
+      entries.set(key, value);
+      while (entries.size > max) entries.delete(entries.keys().next().value);
+    },
+    delete(key) { return entries.delete(key); },
+    clear() { entries.clear(); },
+    get size() { return entries.size; },
+  };
+}
+
+// ── A suggestion while the user types ──
+
+/**
+ * What is left of a suggestion after a change to the document.
+ * @param {{ from: number, text: string } | null} suggestion what is shown: `text` would be inserted at `from`
+ * @param {{ from: number, to: number, insert: string, head: number }} change one change: `insert` replaced
+ *   `from`..`to`, and the caret is at `head` afterwards
+ * @returns {{ typed: boolean, suggestion: { from: number, text: string } | null }} `typed`: the user typed what
+ *   the suggestion begins with (no new request is needed while a remainder is left); `suggestion`: the remainder
+ */
+export function typeThrough(suggestion, change) {
+  const miss = { typed: false, suggestion: null };
+  if (!suggestion || !change || typeof change.insert !== 'string' || !change.insert) return miss;
+  if (change.from !== change.to || change.from !== suggestion.from) return miss;
+  if (change.head !== change.from + change.insert.length) return miss;
+  if (!suggestion.text.startsWith(change.insert)) return miss;
+  const rest = suggestion.text.slice(change.insert.length);
+  return { typed: true, suggestion: rest ? { from: change.head, text: rest } : null };
+}
+
+const WORD = /^(\s*)(?:[\p{L}\p{N}_$]+|[^\s\p{L}\p{N}_$]+)/u;
+
+/** The part of a suggestion "accept one word" takes: the white space in front of the next word, and that word (or run of punctuation). */
+export function nextWord(text) {
+  const value = String(text ?? '');
+  const match = WORD.exec(value);
+  return match ? match[0] : value;
+}
+
+// ── The chip ──
+
+/**
+ * What the status-bar chip shows.
+ * @param {object} s
+ * @param {boolean} s.capable the server has the `complete` capability (without it there is no chip)
+ * @param {boolean} s.enabled `ai.enabled`
+ * @param {boolean} [s.excluded] the open file is one that is never read
+ * @param {boolean} [s.busy] a request is under way
+ * @param {{ kind: string } | null} [s.problem] the last request's failure, until one succeeds
+ * @returns {'hidden' | 'off' | 'ready' | 'thinking' | 'problem'}
+ */
+export function chipState({ capable, enabled, excluded = false, busy = false, problem = null } = {}) {
+  if (!capable) return 'hidden';
+  if (!enabled || excluded) return 'off';
+  if (busy) return 'thinking';
+  if (problem) return 'problem';
+  return 'ready';
+}
+
+/**
+ * What a failed request means.
+ * @param {{ status?: number, body?: object | null, error?: string | null }} failure what the server answered, or
+ *   why there was no answer
+ * @returns {{ kind: 'disabled' | 'excluded' | 'rate' | 'engine' | 'no-model' | 'no-endpoint' | 'timeout' | 'network' | 'server',
+ *   retryAfterMs: number, message: string }} `disabled` and `excluded` are not problems: the feature is off, or
+ *   off for this file. `message` is the engine's own words when it gave any.
+ */
+export function describeFailure({ status = 0, body = null, error = null } = {}) {
+  const message = typeof body?.message === 'string' ? body.message.replace(/\s+/g, ' ').trim().slice(0, 300) : '';
+  const out = (kind, retryAfterMs = 0) => ({ kind, retryAfterMs, message });
+  if (status === 409 && body?.code === 'disabled') return out('disabled');
+  if (status === 403 && body?.code === 'excluded') return out('excluded');
+  if (status === 429) {
+    const wait = Number(body?.retryAfterMs);
+    return out('rate', Number.isFinite(wait) && wait > 0 ? Math.min(wait, 120_000) : 5000);
+  }
+  if (status === 502 && body?.code === 'engine') {
+    if (body.reason === 'no-model') return out('no-model');
+    if (body.reason === 'no-endpoint') return out('no-endpoint');
+    if (body.reason === 'timeout') return out('timeout');
+    return out('engine');
+  }
+  if (!status) return { kind: 'network', retryAfterMs: 0, message: String(error ?? '').slice(0, 300) };
+  return out('server');
+}
+
+/** The i18n key of a failure's sentence (parameters: `message`, `seconds`). */
+export function failureKey(failure) {
+  switch (failure?.kind) {
+    case 'rate': return 'editor.ai.problem.rate';
+    case 'no-model': return 'editor.ai.problem.noModel';
+    case 'no-endpoint': return 'editor.ai.problem.noEndpoint';
+    case 'timeout': return 'editor.ai.problem.timeout';
+    case 'network': return 'editor.ai.problem.network';
+    case 'engine': return failure.message ? 'editor.ai.problem.engine' : 'editor.ai.problem.engineUnknown';
+    default: return 'editor.ai.problem.server';
+  }
+}
+
+/**
+ * The popover's line about today's use, from the answer of `GET /api/editor/complete/usage`.
+ * "No requests today" is said only for an answer that says so: no answer, or one that is not one, is a read
+ * that failed.
+ * @param {{ ok?: boolean, today?: { requests: number, tokensIn: number, tokensOut: number } } | null} answer
+ * @returns {{ key: string, params: object }}
+ */
+export function usageLine(answer) {
+  const day = answer && answer.ok === true && answer.today && typeof answer.today === 'object' ? answer.today : null;
+  if (!day) return { key: 'editor.ai.todayFailed', params: {} };
+  const requests = Math.round(Number(day.requests) || 0);
+  if (requests <= 0) return { key: 'editor.ai.todayNone', params: {} };
+  return {
+    key: requests === 1 ? 'editor.ai.today.one' : 'editor.ai.today.other',
+    params: { count: formatCount(requests), input: formatCount(day.tokensIn), output: formatCount(day.tokensOut) },
+  };
+}
+
+/**
+ * Whether the popover's read of the models failed. They are asked for with the OpenCode engine only; an answer
+ * that says OpenCode is not running is an answer (it has a sentence of its own).
+ * @param {{ engine: string, models: object | null }} s `models`: the answer of `GET /api/editor/complete/models`
+ */
+export function modelsReadFailed({ engine, models } = {}) {
+  return engine !== 'endpoint' && !(models && models.ok === true);
+}
+
+/** A count the way the popover writes it: 950, 1.2k, 3.4M. */
+export function formatCount(value) {
+  const n = Math.max(0, Math.round(Number(value) || 0));
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0).replace(/\.0$/, '')}k`;
+  return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+}
+
+/** A duration the way a model's test result is written: 640 ms, 1.2 s. */
+export function formatMs(value) {
+  const ms = Math.max(0, Math.round(Number(value) || 0));
+  return ms < 1000 ? `${ms} ms` : `${(ms / 1000).toFixed(1)} s`;
+}