@oar-sh/oar 0.9.2 → 0.9.4

package/server/public/app/mention-autocomplete.mjs

@@ -0,0 +1,298 @@
+// The composer's @mention popup for remote relays: typing "@" at the start of a
+// word lists the relays this relay is paired with, and picking one inserts
+// "@name " — the mention that unlocks that relay for the conversation's agent
+// (docs/plans/2026-09-27-remote-relays.md, decisions 9 and 10).
+//
+// A sibling of slash-autocomplete.mjs with the same key contract: nothing is
+// highlighted by default, so plain Enter keeps its newline and Ctrl/Cmd+Enter
+// keeps sending; only an arrow-selected row makes Enter accept; Tab accepts
+// the highlighted row or the top one. The popup closes as soon as the typed
+// token matches no relay — "@file:" and friends are never touched — and it
+// never opens while the slash menu is open, so exactly one popup owns the keys.
+
+import { mentionQueryAt, mentionTokenEnd } from './remote-relay-shared.mjs';
+import {
+  ensureRemoteRelaysLoaded,
+  getRemoteRelays,
+  getRemoteRelaysSnapshot,
+  remoteRelayStatus,
+  subscribeRemoteRelays,
+} from './remote-relays-store.mjs';
+import { isSlashAutocompleteOpen } from './slash-autocomplete.mjs';
+
+const POPUP_ID = 'mention-autocomplete-popup';
+const OPTION_ID_PREFIX = 'mention-autocomplete-option-';
+
+let openState = null; // { items, start } while the popup is visible
+let selectedIndex = -1;
+// The composer that typed "@" before the list was loaded; the load re-runs it.
+let pendingInput = null;
+
+function popupEl() {
+  return document.getElementById(POPUP_ID);
+}
+
+function composerInput() {
+  return document.getElementById('msg-input');
+}
+
+function hostOf(relay) {
+  const explicit = String(relay?.host || '').trim().toLowerCase();
+  if (explicit) return explicit;
+  try {
+    return new URL(String(relay?.url || '')).hostname.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The popup rows for `query` (the text after "@", lowercase): relays whose name
+ * or URL host starts with it. `insert` is what a pick writes: "@name", or
+ * "@host" when the name is empty or shared by two relays (a shared name is
+ * ambiguous and would unlock nothing).
+ */
+export function mentionCandidates(relays, query = '') {
+  const list = Array.isArray(relays) ? relays : [];
+  const wanted = String(query || '').trim().toLowerCase();
+  const nameCounts = new Map();
+  for (const relay of list) {
+    const key = String(relay?.name || '').trim().toLowerCase();
+    if (key) nameCounts.set(key, (nameCounts.get(key) || 0) + 1);
+  }
+  const items = [];
+  for (const relay of list) {
+    const id = String(relay?.id || '').trim();
+    const name = String(relay?.name || '').trim();
+    const host = hostOf(relay);
+    if (!id || (!name && !host)) continue;
+    if (wanted && !name.toLowerCase().startsWith(wanted) && !host.startsWith(wanted)) continue;
+    const ambiguous = !!name && nameCounts.get(name.toLowerCase()) > 1;
+    const insertName = (!name || ambiguous) && host ? host : name;
+    items.push({
+      id,
+      name: name || host,
+      host,
+      status: remoteRelayStatus(relay),
+      insert: `@${insertName}`,
+    });
+  }
+  return items;
+}
+
+export function isMentionAutocompleteOpen() {
+  return openState !== null;
+}
+
+function syncInputAria(input) {
+  const target = input || composerInput();
+  if (!target) return;
+  if (!openState) {
+    target.removeAttribute('aria-activedescendant');
+    target.setAttribute('aria-expanded', 'false');
+    return;
+  }
+  target.setAttribute('aria-controls', POPUP_ID);
+  target.setAttribute('aria-expanded', 'true');
+  if (selectedIndex >= 0) target.setAttribute('aria-activedescendant', `${OPTION_ID_PREFIX}${selectedIndex}`);
+  else target.removeAttribute('aria-activedescendant');
+}
+
+export function closeMentionAutocomplete() {
+  const wasOpen = openState !== null;
+  openState = null;
+  selectedIndex = -1;
+  const popup = popupEl();
+  if (popup) {
+    popup.classList.remove('visible');
+    popup.setAttribute('aria-hidden', 'true');
+    popup.textContent = '';
+  }
+  if (wasOpen) syncInputAria(null);
+}
+
+function renderPopup(input) {
+  const popup = popupEl();
+  if (!popup || !openState) return;
+  popup.textContent = '';
+  openState.items.forEach((item, index) => {
+    const row = document.createElement('div');
+    row.className = 'slash-item mention-item';
+    if (index === selectedIndex) row.classList.add('slash-item-selected');
+    row.id = `${OPTION_ID_PREFIX}${index}`;
+    row.setAttribute('role', 'option');
+    row.setAttribute('aria-selected', index === selectedIndex ? 'true' : 'false');
+    row.dataset.index = String(index);
+    row.dataset.relayId = item.id;
+
+    const dot = document.createElement('span');
+    dot.className = 'remote-relay-dot';
+    dot.dataset.status = item.status;
+    dot.setAttribute('aria-hidden', 'true');
+    row.appendChild(dot);
+
+    // textContent throughout: names come from other relays.
+    const nameEl = document.createElement('span');
+    nameEl.className = 'slash-item-name';
+    nameEl.textContent = item.name;
+    row.appendChild(nameEl);
+
+    if (item.host && item.host !== item.name.toLowerCase()) {
+      const hostEl = document.createElement('span');
+      hostEl.className = 'slash-item-desc';
+      hostEl.textContent = item.host;
+      row.appendChild(hostEl);
+    }
+    popup.appendChild(row);
+  });
+  popup.classList.add('visible');
+  popup.setAttribute('aria-hidden', 'false');
+  syncInputAria(input);
+}
+
+/**
+ * Recomputes the popup for the composer's text and caret. The composer calls
+ * this from its input handler, after the slash menu had its turn.
+ */
+export function updateMentionAutocomplete(input) {
+  if (!input) return;
+  if (isSlashAutocompleteOpen()) {
+    pendingInput = null;
+    closeMentionAutocomplete();
+    return;
+  }
+  const text = String(input.value || '');
+  const caret = Number.isFinite(input.selectionStart) ? input.selectionStart : text.length;
+  const selectionEnd = Number.isFinite(input.selectionEnd) ? input.selectionEnd : caret;
+  const query = selectionEnd === caret ? mentionQueryAt(text, caret) : null;
+  if (!query) {
+    pendingInput = null;
+    closeMentionAutocomplete();
+    return;
+  }
+  if (!getRemoteRelaysSnapshot()) {
+    // First "@" of the page: fetch the list, and come back once it is here.
+    pendingInput = input;
+    closeMentionAutocomplete();
+    void ensureRemoteRelaysLoaded();
+    return;
+  }
+  pendingInput = null;
+  const items = mentionCandidates(getRemoteRelays(), query.query);
+  if (!items.length) {
+    closeMentionAutocomplete();
+    return;
+  }
+  // A rebuild replaces the rows, so a highlight only survives on the same relay.
+  const previous = selectedIndex >= 0 ? openState?.items?.[selectedIndex] : null;
+  openState = { items, start: query.start };
+  selectedIndex = previous ? items.findIndex((item) => item.id === previous.id) : -1;
+  renderPopup(input);
+}
+
+function acceptItem(input, index) {
+  const item = openState?.items?.[index];
+  if (!item || !input) return false;
+  const value = String(input.value || '');
+  const caret = Number.isFinite(input.selectionStart) ? input.selectionStart : value.length;
+  // Re-read the token at the caret: the caret may have moved since the popup
+  // was drawn, and a stale range must never overwrite unrelated text.
+  const query = mentionQueryAt(value, caret);
+  if (!query || query.start !== openState.start) {
+    closeMentionAutocomplete();
+    return false;
+  }
+  const end = mentionTokenEnd(value, caret);
+  const after = value.slice(end);
+  const inserted = /^\s/.test(after) ? item.insert : `${item.insert} `;
+  input.value = `${value.slice(0, query.start)}${inserted}${after}`;
+  const nextCaret = query.start + item.insert.length + 1;
+  input.selectionStart = nextCaret;
+  input.selectionEnd = nextCaret;
+  closeMentionAutocomplete();
+  input.focus();
+  // Re-runs the composer's input pipeline (autoResize, draft sync, the menus).
+  input.dispatchEvent(new Event('input', { bubbles: true }));
+  return true;
+}
+
+/**
+ * Offers a keydown to the popup. Returns true when consumed; the composer's
+ * handleKey calls this after the slash menu's handler and stops on true.
+ */
+export function handleMentionAutocompleteKey(event, input) {
+  if (!openState || event?.isComposing) return false;
+
+  if (event.key === 'Escape') {
+    closeMentionAutocomplete();
+    event.preventDefault();
+    // Swallowed so document-level Escape handlers (modals, pickers) stay put.
+    event.stopPropagation();
+    return true;
+  }
+
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    const count = openState.items.length;
+    if (!count) return false;
+    if (event.key === 'ArrowDown') {
+      selectedIndex = selectedIndex >= count - 1 ? 0 : selectedIndex + 1;
+    } else {
+      // ↑ from the top row returns to "nothing highlighted", so plain Enter's
+      // newline stays reachable without Escape.
+      selectedIndex = selectedIndex <= 0 ? -1 : selectedIndex - 1;
+    }
+    renderPopup(input);
+    event.preventDefault();
+    return true;
+  }
+
+  if (event.key === 'Tab' && !event.ctrlKey && !event.metaKey && !event.altKey) {
+    if (!openState.items.length) return false;
+    // A pick the caret no longer supports closes the popup and lets the key through.
+    if (!acceptItem(input, selectedIndex >= 0 ? selectedIndex : 0)) return false;
+    event.preventDefault();
+    return true;
+  }
+
+  if (event.key === 'Enter' && !event.ctrlKey && !event.metaKey && !event.shiftKey) {
+    if (selectedIndex < 0) return false;
+    if (!acceptItem(input, selectedIndex)) return false;
+    event.preventDefault();
+    return true;
+  }
+
+  return false;
+}
+
+export function initMentionAutocomplete() {
+  const popup = popupEl();
+  if (!popup || popup.dataset.bound === '1') return;
+  popup.dataset.bound = '1';
+  // pointerdown, not click: the textarea loses focus on the tap, and a click
+  // handler would race the focus-driven close.
+  popup.addEventListener('pointerdown', (event) => {
+    const row = event.target?.closest?.('.mention-item');
+    if (!row || !openState) return;
+    event.preventDefault();
+    const input = composerInput();
+    if (input) acceptItem(input, Number(row.dataset.index));
+  });
+  document.addEventListener('pointerdown', (event) => {
+    if (!openState) return;
+    const target = event.target;
+    if (popupEl()?.contains(target)) return;
+    if (composerInput()?.contains?.(target)) return;
+    closeMentionAutocomplete();
+  });
+  // The list arrived (lazy load) or changed (remote_relays_updated): redraw
+  // for the composer that is waiting on it or showing it.
+  subscribeRemoteRelays(() => {
+    const waiting = pendingInput;
+    pendingInput = null;
+    if (waiting && document.activeElement === waiting) {
+      updateMentionAutocomplete(waiting);
+      return;
+    }
+    if (openState) updateMentionAutocomplete(composerInput());
+  });
+}

package/server/public/app/model-selector-options.mjs

@@ -2,7 +2,7 @@ import { tokenLabel } from './context-tier-options.mjs';
 
 /**
  * The composer placeholder, decided by the MODEL FAMILY of the current
- * selection (Simon's rule: the hint names who answers, whatever runtime serves
+ * selection (maintainer's rule: the hint names who answers, whatever runtime serves
  * it — claude-* through Cursor's catalog still reads "Message Claude…").
  * Provider only breaks ties: Auto/empty follows the conversation's bound
  * provider, unknown families on the OpenAI BYOK provider read OpenAI, and

package/server/public/app/push-settings.js

@@ -10,6 +10,7 @@ const PUSH_EVENT_CONTROL_IDS = {
   turnFailed: 'push-event-turn-failed-toggle',
   board: 'push-event-board-toggle',
   cliOffline: 'push-event-cli-offline-toggle',
+  hostSuspend: 'push-event-host-suspend-toggle',
 };
 
 let pushUpdateInFlight = false;

package/server/public/app/pwa-install.js

@@ -306,6 +306,8 @@ export function initFullscreenButton() {
 // The app name is stored on the relay and baked into /manifest.webmanifest by
 // the server, so every manifest fetch — including Android's out-of-page WebAPK
 // update checks — sees the same name. The client only edits the setting.
+// Settings shows it as "Relay name": it is also the name paired relays know
+// this one by (and mention it by).
 
 function paintPwaAppNameInput() {
   const input = document.getElementById('pwa-app-name-input');
@@ -330,16 +332,19 @@ export async function updatePwaAppName(rawValue) {
   const seq = ++pwaAppNameRequestSeq;
   const result = await updatePwaAppNameSetting(rawValue);
   if (!result || typeof result.appName !== 'string') {
-    alert('Failed to update the install app name.');
+    alert('Failed to update the relay name.');
     if (seq === pwaAppNameRequestSeq) paintPwaAppNameInput();
     return;
   }
   if (seq !== pwaAppNameRequestSeq) return; // a newer edit owns the UI now
   pwaAppName = result.appName;
   showTransientRelayNotice(result.appName
-    ? `Install app name updated to "${result.appName}".`
-    : 'Install app name reset to default.');
+    ? `Relay name updated to "${result.appName}".`
+    : 'Relay name reset to default.');
   paintPwaAppNameInput();
+  // The same name is what paired relays see (GET /api/relay/identity); the
+  // Relays tab re-reads it, including the host-name fallback for an empty one.
+  window.dispatchEvent(new CustomEvent('oar:relay-name-changed', { detail: { name: result.appName } }));
 }
 
 /**

package/server/public/app/question-multi-select.mjs

@@ -0,0 +1,52 @@
+// Multi-select question cards: the pure rules the card renderer and its
+// submit path share, kept DOM-free so they are unit-testable.
+//
+// Two card hints ride the question's `context` (kept by the relay's
+// services/relay-question-context.mjs allow-list):
+//  - `multiSelect: true` — several answers are allowed. Claude states this on
+//    every AskUserQuestion question; Copilot models declare it through the
+//    relay's own `ask_user` (`multi_select`), and the worker falls back to the
+//    wording ("select all that apply").
+//  - `allowMultiSelect: true` — the provider cannot always tell (Copilot), so
+//    the card offers a "Select several" switch. Claude cards never carry it:
+//    they follow Claude's flag strictly (maintainer decision, 2026-09-25).
+// A multi-select card offers checkmarks and one "Reply with selection"; the
+// answer is the selected labels joined with ", " — plus whatever the user
+// typed as an extra answer — which is Claude's own multi-select answer format.
+
+function choiceCount(question) {
+  return Array.isArray(question?.choices) ? question.choices.length : 0;
+}
+
+/** Whether the card offers the "Select several" switch. */
+export function offersMultiSelectToggle(question) {
+  if (!question || typeof question !== 'object') return false;
+  return choiceCount(question) >= 2 && question?.context?.allowMultiSelect === true;
+}
+
+/**
+ * Whether the card renders checkmarks. `override` is the user's switch
+ * position for this card (true/false), or undefined while untouched — then the
+ * provider's flag decides. The switch only counts on cards that offer it.
+ */
+export function isMultiSelectQuestion(question, override = undefined) {
+  if (!question || typeof question !== 'object') return false;
+  if (choiceCount(question) < 2) return false;
+  if (typeof override === 'boolean' && offersMultiSelectToggle(question)) return override;
+  return question?.context?.multiSelect === true;
+}
+
+/**
+ * The answer string for a multi-select card: the selected labels in offer
+ * order, then the free-text answer (if any) as one more item. Empty when
+ * nothing was selected or typed.
+ */
+export function composeMultiSelectAnswer(selectedLabels, freeText = '') {
+  const labels = (Array.isArray(selectedLabels) ? selectedLabels : [])
+    .map((label) => String(label ?? '').trim())
+    .filter(Boolean)
+    .filter((label, index, all) => all.indexOf(label) === index);
+  const extra = String(freeText ?? '').trim();
+  if (extra && !labels.includes(extra)) labels.push(extra);
+  return labels.join(', ');
+}

package/server/public/app/relay-prompt-sanitizer.mjs

@@ -1,3 +1,5 @@
+import { stripRemotePromptHeader } from './remote-relay-shared.mjs';
+
 const RELAY_TOOL_GUIDANCE = [
   '# Relay Tool Guidance',
   'For any user-facing question or clarification, use the ask_user tool so the web relay can render question cards and buttons. Never ask questions in plain assistant text.',
@@ -108,7 +110,46 @@ function stripAttachmentPromptArtifacts(text) {
 // structurally — the heading plus its single paragraph — rather than verbatim.
 const MEDIA_EMBED_BLOCK_PATTERN = /##\s*Embedding media in replies\s+[\s\S]*?(?=\n\s*\n|$)/gi;
 
-export function stripRelayPromptContext(text, relayMode = '') {
+// A steered message's hidden note (shared/steer-note.mjs) leads the prompt the
+// runtime stored, right after any mode marker. Matched by its stable opening
+// words, because the browser copy of this module cannot import shared/.
+const STEER_NOTE_PATTERN = /^\s*\[Sent while you were still working on my previous message\.[^\]\n]*\]\s*/;
+
+// The Claude worker's slash-command guard (shared/slash-command-guard.mjs): a
+// zero-width space in front of a "/x" it delivers as text. trim() keeps it, so
+// it is matched on its own, and only where it guards a "/".
+const SLASH_COMMAND_GUARD_PATTERN = /^\u200B(?=\s*\/)/;
+
+// The hint the relay adds to a turn whose user message mentions a remote relay
+// (docs/plans/2026-09-27-remote-relays.md §5.5). stripAttachmentPromptArtifacts
+// already drops every <system_reminder>; this narrower pattern is for text that
+// did not come through that path (a stored bubble the server already sanitised).
+const REMOTE_RELAY_MENTION_HINT_PATTERN = /<system_reminder>\s*The user mentioned the remote OAR relay[\s\S]*?<\/system_reminder>\s*/gi;
+
+function hasRemoteOrigin(origin) {
+  return !!origin && typeof origin === 'object';
+}
+
+function stripLeadingRelayNotes(text, { origin = null } = {}) {
+  const remote = hasRemoteOrigin(origin);
+  let stripped = String(text || '');
+  // A prompt another relay's agent sent starts with a header line naming it;
+  // the bubble's provenance badge carries the same facts, so it is hidden —
+  // but only when the message really carries `origin`, never on a lookalike a
+  // human typed. A steer note may sit in front of it.
+  if (remote) stripped = stripRemotePromptHeader(stripped.trimStart());
+  stripped = stripped.replace(STEER_NOTE_PATTERN, '');
+  if (remote) stripped = stripRemotePromptHeader(stripped.trimStart());
+  stripped = stripped.replace(SLASH_COMMAND_GUARD_PATTERN, '');
+  return stripped.trim() ? stripped.trim() : String(text || '').trim();
+}
+
+/**
+ * `options.origin`: the message's remote-relay provenance, when it has one.
+ * Only then is the remote prompt header line stripped.
+ */
+export function stripRelayPromptContext(text, relayMode = '', options = {}) {
+  const origin = options && typeof options === 'object' ? options.origin : null;
   const value = stripAttachmentPromptArtifacts(text)
     .replace(MEDIA_EMBED_BLOCK_PATTERN, '')
     .trim();
@@ -116,7 +157,24 @@ export function stripRelayPromptContext(text, relayMode = '') {
   const patterns = buildPromptPrefixPatterns(relayMode);
   for (const pattern of patterns) {
     const stripped = value.replace(pattern, '').trim();
-    if (stripped && stripped !== value) return stripped;
+    if (stripped && stripped !== value) return stripLeadingRelayNotes(stripped, { origin });
+  }
+  return stripLeadingRelayNotes(value, { origin });
+}
+
+/**
+ * For a user bubble's text as it is about to render (already sanitised by the
+ * relay): drops a stray remote-relay mention hint, and the remote prompt header
+ * when the message carries `origin`. Text without either is returned untouched.
+ */
+export function stripRemoteRelayDisplayArtifacts(text, { origin = null } = {}) {
+  const value = String(text ?? '');
+  let next = value.replace(REMOTE_RELAY_MENTION_HINT_PATTERN, '');
+  if (hasRemoteOrigin(origin)) {
+    const leading = next.trimStart();
+    const withoutHeader = stripRemotePromptHeader(leading);
+    if (withoutHeader !== leading) next = withoutHeader;
   }
-  return value;
+  if (next === value) return value;
+  return next.trim() ? next.trim() : value.trim();
 }

package/server/public/app/remote-relay-origin-view.mjs

@@ -0,0 +1,76 @@
+// Provenance of work another relay's agent started here: the badge on a user
+// bubble ("↗ from win-test · “report builder” · claude-sonnet-5", linking back
+// to the source session) and the "↗ win-test" marker on the sidebar row of a
+// conversation such an agent created. Both read the `origin` the relay stores
+// with the message or conversation (docs/plans/2026-09-27-remote-relays.md §4).
+
+import { remoteConversationUrl } from './remote-relay-shared.mjs';
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function oneLine(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/** The display fields of an `origin`, or null when it names no relay. */
+export function normalizeRemoteOrigin(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const relayName = oneLine(raw.relayName);
+  const relayId = oneLine(raw.relayId);
+  if (!relayName && !relayId) return null;
+  const relayUrl = oneLine(raw.relayUrl);
+  return {
+    relayName: relayName || relayId,
+    relayUrl: /^https?:\/\//i.test(relayUrl) ? relayUrl : '',
+    conversationId: oneLine(raw.conversationId),
+    conversationTitle: oneLine(raw.conversationTitle),
+    model: oneLine(raw.model),
+  };
+}
+
+export function remoteOriginBadgeText(origin) {
+  const normalized = normalizeRemoteOrigin(origin);
+  if (!normalized) return '';
+  const parts = [`↗ from ${normalized.relayName}`];
+  if (normalized.conversationTitle) parts.push(`“${normalized.conversationTitle}”`);
+  if (normalized.model) parts.push(normalized.model);
+  return parts.join(' · ');
+}
+
+/** `<relayUrl>/?conv=<conversationId>`, or '' when the origin has no URL. */
+export function remoteOriginLink(origin) {
+  const normalized = normalizeRemoteOrigin(origin);
+  if (!normalized?.relayUrl) return '';
+  return remoteConversationUrl(normalized.relayUrl, normalized.conversationId);
+}
+
+/**
+ * The badge row that sits above a user bubble's text. `linkable: false` (the
+ * shared read-only view) renders it without the link to the other relay.
+ */
+export function renderRemoteOriginBadgeHtml(origin, { linkable = true } = {}) {
+  const normalized = normalizeRemoteOrigin(origin);
+  if (!normalized) return '';
+  const label = escapeHtml(remoteOriginBadgeText(normalized));
+  const href = linkable ? remoteOriginLink(normalized) : '';
+  const name = escapeHtml(normalized.relayName);
+  if (href) {
+    return `<div class="msg-origin"><a class="msg-origin-badge" href="${escapeHtml(href)}" target="_blank" rel="noopener" title="Sent by an agent on relay ${name}. Opens its session there.">${label}</a></div>`;
+  }
+  return `<div class="msg-origin"><span class="msg-origin-badge" title="Sent by an agent on relay ${name}.">${label}</span></div>`;
+}
+
+/** The sidebar marker for a conversation another relay's agent created. */
+export function renderConversationOriginMarkerHtml(conversation) {
+  const normalized = normalizeRemoteOrigin(conversation?.origin);
+  if (!normalized) return '';
+  const name = escapeHtml(normalized.relayName);
+  return `<span class="conv-origin-marker" title="Started by an agent on relay ${name}">↗ ${name}</span>`;
+}

package/server/public/app/remote-relay-shared.mjs

@@ -0,0 +1,85 @@
+// Browser mirror of the pieces of shared/remote-relay-contract.mjs and
+// shared/remote-relay-mentions.mjs the web UI needs. The browser cannot import
+// shared/ (only server/public is served), so these are hand-kept copies;
+// remote-relay-shared.test.mjs asserts they behave exactly like the originals.
+
+export const REMOTE_RELAY_PERMISSIONS = Object.freeze(['read', 'prompt', 'full']);
+export const REMOTE_RELAY_DEFAULT_PERMISSION = 'full';
+export const REMOTE_RELAY_SOCKET_EVENT = 'remote_relays_updated';
+
+// The header line a relay puts at the top of a prompt it forwards. The UI
+// hides it on bubbles that carry `origin` (the badge shows the same facts).
+export const REMOTE_PROMPT_HEADER_PATTERN = /^\[Remote prompt from an agent on relay "[^"\r\n]*"[^\r\n]*\](?:\r?\n){1,2}/;
+
+const NAME_CHAR = /[a-z0-9._-]/;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function hostOf(url) {
+  try {
+    return new URL(String(url)).hostname.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+export function normalizeRemoteRelayPermission(value) {
+  const permission = toText(value).toLowerCase();
+  return REMOTE_RELAY_PERMISSIONS.includes(permission) ? permission : REMOTE_RELAY_DEFAULT_PERMISSION;
+}
+
+export function stripRemotePromptHeader(text) {
+  return String(text ?? '').replace(REMOTE_PROMPT_HEADER_PATTERN, '');
+}
+
+/** Link that opens one conversation in a relay's web UI. */
+export function remoteConversationUrl(baseUrl, conversationId) {
+  const base = toText(baseUrl).replace(/\/+$/, '');
+  const id = toText(conversationId);
+  if (!base) return '';
+  return id ? `${base}/?conv=${encodeURIComponent(id)}` : `${base}/`;
+}
+
+/** localhost (and *.localhost), an IPv4 literal, or an IPv6 literal (bracketed as URL hosts are). */
+export function isAddressHost(host) {
+  const value = toText(host).toLowerCase();
+  if (!value) return false;
+  if (value === 'localhost' || value.endsWith('.localhost')) return true;
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(value)) return true;
+  return value.startsWith('[') || value.includes(':');
+}
+
+/** The lowercase aliases a relay can be mentioned by: its name and its URL host, unless that is an address. */
+export function remoteRelayAliases(relay) {
+  const aliases = new Set();
+  const name = toText(relay?.name).toLowerCase();
+  if (name) aliases.add(name);
+  const host = hostOf(relay?.url);
+  if (host && !isAddressHost(host)) aliases.add(host);
+  return [...aliases];
+}
+
+/**
+ * For the composer: the partial `@word` token ending at `caret`, or null.
+ * `{ start, end, query }` where start is the index of the `@`.
+ */
+export function mentionQueryAt(text, caret) {
+  const value = String(text ?? '');
+  const end = Number.isInteger(caret) ? Math.min(Math.max(caret, 0), value.length) : value.length;
+  let start = end;
+  while (start > 0 && NAME_CHAR.test(value[start - 1].toLowerCase())) start -= 1;
+  if (start === 0 || value[start - 1] !== '@') return null;
+  const at = start - 1;
+  if (at > 0 && !/\s|[([{"'`,;]/.test(value[at - 1])) return null;
+  return { start: at, end, query: value.slice(start, end).toLowerCase() };
+}
+
+/** How far the mention token that starts at `from` runs (the rest of a word the caret sits in). */
+export function mentionTokenEnd(text, from) {
+  const value = String(text ?? '');
+  let end = Math.min(Math.max(Number(from) || 0, 0), value.length);
+  while (end < value.length && NAME_CHAR.test(value[end].toLowerCase())) end += 1;
+  return end;
+}