@oar-sh/oar 0.9.2 → 0.9.4

package/shared/remote-relay-contract.mjs

@@ -0,0 +1,539 @@
+// The shared contract of the remote-relay feature: one OAR relay lets the
+// agents of its sessions work on OTHER OAR relays it is paired with.
+//
+// Everything that more than one side has to agree on lives here — the tool
+// name, description and schema every provider adapter registers, the action
+// → permission map the relay enforces, the limits, the error codes, the
+// provenance ("origin") shape a relay attaches when its agent prompts a remote
+// session, the prompt header line, and the URL policy for remote addresses.
+//
+// SDK-free and side-effect free: imported by the server, the session workers,
+// the stdio MCP server and (for the header/URL helpers) the browser.
+
+export const REMOTE_RELAY_TOOL_NAME = 'remote_relay';
+
+// Bumped when a relay starts relying on a newer inbound behaviour of its peers.
+// 0 = a relay without this feature (reachable read/prompt only, no pairing).
+export const REMOTE_RELAY_PROTOCOL = 1;
+
+// Every agent path converges on this one local endpoint; the relay does the
+// gating, approval, forwarding and waiting.
+export const REMOTE_RELAY_TOOL_ENDPOINT = '/api/remote-relays/tool';
+
+export const REMOTE_RELAY_ACTIONS = Object.freeze([
+  'list_relays',
+  'relay_info',
+  'list_sessions',
+  'read_session',
+  'wait',
+  'send',
+  'create_session',
+  'answer_question',
+  'stop',
+  'archive',
+]);
+
+export const REMOTE_RELAY_PERMISSIONS = Object.freeze(['read', 'prompt', 'full']);
+export const REMOTE_RELAY_DEFAULT_PERMISSION = 'full';
+
+// null = allowed without a mention and without a permission (local data only).
+export const REMOTE_RELAY_ACTION_PERMISSION = Object.freeze({
+  list_relays: null,
+  relay_info: 'read',
+  list_sessions: 'read',
+  read_session: 'read',
+  wait: 'read',
+  send: 'prompt',
+  create_session: 'full',
+  answer_question: 'full',
+  stop: 'full',
+  archive: 'full',
+});
+
+// Actions that change something on the remote relay: they need approval when
+// the calling session runs in ask or plan mode.
+export const REMOTE_RELAY_WRITE_ACTIONS = Object.freeze(['send', 'create_session', 'answer_question', 'stop', 'archive']);
+
+export const REMOTE_RELAY_APPROVAL_MODES = Object.freeze(['ask', 'plan']);
+
+export const REMOTE_RELAY_SESSION_SCOPES = Object.freeze(['active', 'recent', 'all']);
+export const REMOTE_RELAY_PROVIDERS = Object.freeze(['github', 'openai', 'claude', 'cursor', 'grok']);
+export const REMOTE_RELAY_MODES = Object.freeze(['plan', 'ask', 'agent', 'autopilot']);
+export const REMOTE_RELAY_IF_BUSY = Object.freeze(['queue', 'fail']);
+
+export const REMOTE_RELAY_RESULT_STATUSES = Object.freeze([
+  'queued',
+  'running',
+  'waiting_for_answer',
+  'done',
+  'failed',
+  'stopped',
+  'cancelled',
+  'duplicate',
+]);
+
+export const REMOTE_RELAY_LIMITS = Object.freeze({
+  waitDefaultSeconds: 120,
+  waitMaxSeconds: 600,
+  listDefault: 20,
+  listMax: 100,
+  readDefault: 10,
+  readMax: 50,
+  maxCharsDefault: 12000,
+  maxCharsMax: 50000,
+  perMessageChars: 4000,
+  textMax: 100000,
+  hopLimit: 2,
+  callsPerMinute: 60,
+  writesPerMinute: 10,
+  healthIntervalMs: 60_000,
+  requestTimeoutMs: 15_000,
+  responseMaxBytes: 5 * 1024 * 1024,
+});
+
+export const REMOTE_RELAY_ERROR_CODES = Object.freeze({
+  invalidInput: 'REMOTE_RELAY_INVALID_INPUT',
+  unknown: 'REMOTE_RELAY_UNKNOWN',
+  locked: 'REMOTE_RELAY_LOCKED',
+  forbidden: 'REMOTE_RELAY_FORBIDDEN',
+  hopLimit: 'REMOTE_RELAY_HOP_LIMIT',
+  approvalDenied: 'REMOTE_RELAY_APPROVAL_DENIED',
+  rateLimited: 'REMOTE_RELAY_RATE_LIMITED',
+  offline: 'REMOTE_RELAY_OFFLINE',
+  unauthorized: 'REMOTE_RELAY_UNAUTHORIZED',
+  inboundDisabled: 'REMOTE_INBOUND_DISABLED',
+  unsupported: 'REMOTE_RELAY_UNSUPPORTED',
+  notFound: 'REMOTE_RELAY_NOT_FOUND',
+  providerUnavailable: 'REMOTE_RELAY_PROVIDER_UNAVAILABLE',
+  busy: 'REMOTE_RELAY_BUSY',
+  noTurn: 'REMOTE_RELAY_NO_ACTIVE_TURN',
+  internal: 'REMOTE_RELAY_INTERNAL',
+  // Prefix: the remote answered with this HTTP status, e.g. REMOTE_RELAY_HTTP_409.
+  httpPrefix: 'REMOTE_RELAY_HTTP_',
+});
+
+// app_settings keys (JSON values). `remote_relays` holds tokens for remotes
+// that use their own token: never return that value through an API.
+export const REMOTE_RELAY_SETTING_KEYS = Object.freeze({
+  instanceId: 'relay_instance_id',
+  relays: 'remote_relays',
+  publicUrl: 'relay_public_url',
+  inboundEnabled: 'remote_relay_inbound_enabled',
+});
+
+// Headers a relay adds to every call it forwards to a remote. The remote uses
+// them for the inbound switch and to carry the hop count; never the X-Relay-*
+// worker identity headers.
+export const REMOTE_RELAY_HEADERS = Object.freeze({
+  origin: 'x-oar-remote-origin',
+  hops: 'x-oar-remote-hops',
+});
+
+export const REMOTE_RELAY_SOCKET_EVENT = 'remote_relays_updated';
+
+export const REMOTE_RELAY_TOOL_DESCRIPTION =
+  'Work with sessions on other OAR relays this relay is paired with ("remote relays"): '
+  + 'list the relays, list or read their sessions, prompt a session, start a new one, '
+  + 'wait for its reply, and answer or stop it. Use it only when the user asks for work '
+  + 'on another relay or mentions one. Start with {action:"list_relays"}. A relay stays '
+  + 'locked until the user mentions it in this conversation (for example @name); a '
+  + 'locked relay refuses everything except list_relays, so ask the user to mention it. '
+  + 'send and create_session queue the prompt and wait up to wait_seconds (default 120, '
+  + 'max 600) for the reply. If the remote turn is still running you get status '
+  + '"running" with progress: call {action:"wait", relay, session, message_id} to keep '
+  + 'waiting. A remote agent that answers but keeps working in the background also comes '
+  + 'back as "running", with its latest reply so far; "done" means it has finished. '
+  + 'If a result lists pendingQuestions, the remote agent is waiting for an '
+  + 'answer: ask the user (unless they told you to decide yourself) and pass the answer '
+  + 'with answer_question. Write actions can first need the user\'s approval. Always '
+  + 'tell the user which relay and session you worked on.';
+
+export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
+  type: 'object',
+  properties: {
+    action: {
+      type: 'string',
+      enum: [...REMOTE_RELAY_ACTIONS],
+      description: 'list_relays: paired relays and whether each is unlocked here. relay_info: providers, models, '
+        + 'workspaces of a relay. list_sessions / read_session: discover and read sessions. send: prompt an '
+        + 'existing session. create_session: start a new session with a first prompt. wait: keep waiting for '
+        + 'a reply. answer_question: answer a question the remote agent asked. stop: stop the running turn. '
+        + 'archive: archive a session.',
+    },
+    relay: { type: 'string', description: 'Relay name (or its host) from list_relays. Required except for list_relays.' },
+    session: { type: 'string', description: 'Remote session (conversation) id from list_sessions or create_session.' },
+    text: { type: 'string', description: 'send / create_session: the prompt for the remote agent.' },
+    message_id: { type: 'string', description: 'wait: the message_id that send or create_session returned.' },
+    wait_seconds: {
+      type: 'integer',
+      minimum: 0,
+      maximum: REMOTE_RELAY_LIMITS.waitMaxSeconds,
+      description: 'send / create_session / wait: how long to wait for the reply (default 120, 0 = do not wait).',
+    },
+    scope: {
+      type: 'string',
+      enum: [...REMOTE_RELAY_SESSION_SCOPES],
+      description: 'list_sessions: active = working now, recent = newest first (default), all = page through everything.',
+    },
+    query: { type: 'string', description: 'list_sessions: only sessions whose title contains this text.' },
+    limit: { type: 'integer', minimum: 1, maximum: REMOTE_RELAY_LIMITS.listMax, description: 'list_sessions: page size (default 20).' },
+    cursor: { type: 'string', description: 'list_sessions: nextCursor from the previous page.' },
+    last: { type: 'integer', minimum: 1, maximum: REMOTE_RELAY_LIMITS.readMax, description: 'read_session: how many recent messages (default 10).' },
+    before: { type: 'string', description: 'read_session: olderCursor from the previous read, to page back.' },
+    include_activity: { type: 'boolean', description: 'read_session: include the tool activity lines of each reply.' },
+    max_chars: {
+      type: 'integer',
+      minimum: 500,
+      maximum: REMOTE_RELAY_LIMITS.maxCharsMax,
+      description: 'read_session: total text budget (default 12000).',
+    },
+    provider: {
+      type: 'string',
+      enum: [...REMOTE_RELAY_PROVIDERS],
+      description: 'create_session: provider (default: the same provider as this session).',
+    },
+    model: {
+      type: 'string',
+      description: 'create_session: model id (default: this session\'s model when the remote offers it, else the remote\'s default). '
+        + 'send: switch the remote session to this model (default: it keeps its own).',
+    },
+    cwd: { type: 'string', description: 'create_session: working directory on the remote relay (default: its default workspace).' },
+    mode: {
+      type: 'string',
+      enum: [...REMOTE_RELAY_MODES],
+      description: 'send / create_session: relay mode for the remote turn (default: this session\'s mode).',
+    },
+    title: { type: 'string', description: 'create_session: session title (default: from the prompt).' },
+    question_id: { type: 'string', description: 'answer_question: id from pendingQuestions.' },
+    answer: { type: 'string', description: 'answer_question: free-text answer.' },
+    choices: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'answer_question: selected option labels, for questions with options.',
+    },
+    if_busy: {
+      type: 'string',
+      enum: [...REMOTE_RELAY_IF_BUSY],
+      description: 'send: queue (default; steers into a running turn where the remote supports it) or fail when the session is busy.',
+    },
+  },
+  required: ['action'],
+});
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function clampInteger(value, { min, max, fallback }) {
+  if (value === undefined || value === null || toText(value) === '') return fallback;
+  const number = Number(value);
+  if (!Number.isFinite(number)) return null;
+  return Math.min(max, Math.max(min, Math.trunc(number)));
+}
+
+function invalid(error) {
+  return { ok: false, code: REMOTE_RELAY_ERROR_CODES.invalidInput, error };
+}
+
+const SESSION_ACTIONS = new Set(['read_session', 'wait', 'send', 'stop', 'archive']);
+
+/**
+ * Validates and normalises one tool call. Adapters call it for a crisp early
+ * message; the relay calls it again authoritatively. Returns
+ * `{ ok:true, action, args }` with only the fields the action uses, defaults
+ * filled in and numbers clamped, or `{ ok:false, code, error }`.
+ */
+export function validateRemoteRelayToolInput(input = {}) {
+  const action = toText(input?.action).toLowerCase();
+  if (!REMOTE_RELAY_ACTIONS.includes(action)) {
+    return invalid(`action must be one of: ${REMOTE_RELAY_ACTIONS.join(', ')}`);
+  }
+  if (action === 'list_relays') return { ok: true, action, args: {} };
+
+  const args = {};
+  const relay = toText(input?.relay);
+  if (!relay) return invalid(`${action} needs relay (a name from list_relays)`);
+  args.relay = relay;
+
+  if (SESSION_ACTIONS.has(action)) {
+    const session = toText(input?.session);
+    if (!session) return invalid(`${action} needs session (an id from list_sessions)`);
+    args.session = session;
+  }
+
+  const waitSeconds = clampInteger(input?.wait_seconds, {
+    min: 0,
+    max: REMOTE_RELAY_LIMITS.waitMaxSeconds,
+    fallback: REMOTE_RELAY_LIMITS.waitDefaultSeconds,
+  });
+  if (waitSeconds === null) return invalid('wait_seconds must be a number of seconds');
+
+  const optionalEnum = (key, allowed) => {
+    const value = toText(input?.[key]).toLowerCase();
+    if (!value) return { ok: true };
+    if (!allowed.includes(value)) return invalid(`${key} must be one of: ${allowed.join(', ')}`);
+    args[key] = value;
+    return { ok: true };
+  };
+  const optionalText = (key, max = 500) => {
+    const value = toText(input?.[key]);
+    if (value) args[key] = value.slice(0, max);
+  };
+
+  if (action === 'list_sessions') {
+    const scopeCheck = optionalEnum('scope', REMOTE_RELAY_SESSION_SCOPES);
+    if (!scopeCheck.ok) return scopeCheck;
+    args.scope = args.scope || 'recent';
+    const limit = clampInteger(input?.limit, { min: 1, max: REMOTE_RELAY_LIMITS.listMax, fallback: REMOTE_RELAY_LIMITS.listDefault });
+    if (limit === null) return invalid('limit must be a number');
+    args.limit = limit;
+    optionalText('query', 200);
+    optionalText('cursor', 1000);
+  } else if (action === 'read_session') {
+    const last = clampInteger(input?.last, { min: 1, max: REMOTE_RELAY_LIMITS.readMax, fallback: REMOTE_RELAY_LIMITS.readDefault });
+    if (last === null) return invalid('last must be a number');
+    args.last = last;
+    const maxChars = clampInteger(input?.max_chars, { min: 500, max: REMOTE_RELAY_LIMITS.maxCharsMax, fallback: REMOTE_RELAY_LIMITS.maxCharsDefault });
+    if (maxChars === null) return invalid('max_chars must be a number');
+    args.max_chars = maxChars;
+    args.include_activity = input?.include_activity === true || toText(input?.include_activity).toLowerCase() === 'true';
+    optionalText('before', 1000);
+  } else if (action === 'wait') {
+    const messageId = toText(input?.message_id);
+    if (!messageId) return invalid('wait needs message_id (from send or create_session)');
+    args.message_id = messageId;
+    args.wait_seconds = waitSeconds;
+  } else if (action === 'send' || action === 'create_session') {
+    const text = toText(input?.text);
+    if (!text) return invalid(`${action} needs text (the prompt)`);
+    if (text.length > REMOTE_RELAY_LIMITS.textMax) return invalid(`text is longer than ${REMOTE_RELAY_LIMITS.textMax} characters`);
+    args.text = text;
+    args.wait_seconds = waitSeconds;
+    optionalText('model', 200);
+    const modeCheck = optionalEnum('mode', REMOTE_RELAY_MODES);
+    if (!modeCheck.ok) return modeCheck;
+    if (action === 'send') {
+      const busyCheck = optionalEnum('if_busy', REMOTE_RELAY_IF_BUSY);
+      if (!busyCheck.ok) return busyCheck;
+      args.if_busy = args.if_busy || 'queue';
+    } else {
+      const providerCheck = optionalEnum('provider', REMOTE_RELAY_PROVIDERS);
+      if (!providerCheck.ok) return providerCheck;
+      optionalText('cwd', 1000);
+      optionalText('title', 200);
+    }
+  } else if (action === 'answer_question') {
+    const questionId = toText(input?.question_id);
+    if (!questionId) return invalid('answer_question needs question_id (from pendingQuestions)');
+    args.question_id = questionId;
+    const answer = toText(input?.answer);
+    const choices = Array.isArray(input?.choices)
+      ? input.choices.map((choice) => toText(choice)).filter(Boolean).slice(0, 50)
+      : [];
+    if (!answer && choices.length === 0) return invalid('answer_question needs answer or choices');
+    if (answer) args.answer = answer.slice(0, REMOTE_RELAY_LIMITS.textMax);
+    if (choices.length) args.choices = choices;
+  }
+  return { ok: true, action, args };
+}
+
+const PERMISSION_RANK = { read: 1, prompt: 2, full: 3 };
+
+export function normalizeRemoteRelayPermission(value) {
+  const permission = toText(value).toLowerCase();
+  return REMOTE_RELAY_PERMISSIONS.includes(permission) ? permission : REMOTE_RELAY_DEFAULT_PERMISSION;
+}
+
+/** True when a remote with `permission` allows `action`. */
+export function remoteRelayPermissionAllows(permission, action) {
+  if (!Object.prototype.hasOwnProperty.call(REMOTE_RELAY_ACTION_PERMISSION, action)) return false;
+  const needed = REMOTE_RELAY_ACTION_PERMISSION[action];
+  if (needed === null) return true;
+  return (PERMISSION_RANK[normalizeRemoteRelayPermission(permission)] || 0) >= PERMISSION_RANK[needed];
+}
+
+export function isRemoteRelayWriteAction(action) {
+  return REMOTE_RELAY_WRITE_ACTIONS.includes(action);
+}
+
+// ─── Approval cards ──────────────────────────────────────────────────────────
+
+// The Allow / Deny card a relay puts on its own turn before a write action on
+// another relay (ask / plan mode) is an ordinary relay question whose
+// `context.source` is this. Only that relay's user may answer it: its question
+// routes hide the card from other relays' agents and refuse their answers, and
+// a dispatcher never offers one to its agent.
+export const REMOTE_RELAY_APPROVAL_SOURCE = 'remote_relay';
+
+/** True for such a card: a formatted question, or a stored request envelope (both carry `context`). */
+export function isRemoteRelayApprovalQuestion(question) {
+  const context = question && typeof question === 'object' ? question.context : null;
+  return !!context && typeof context === 'object' && toText(context.source) === REMOTE_RELAY_APPROVAL_SOURCE;
+}
+
+// ─── Provenance ──────────────────────────────────────────────────────────────
+
+const ORIGIN_CAPS = {
+  relayId: 100,
+  relayName: 60,
+  relayUrl: 300,
+  conversationId: 100,
+  conversationTitle: 200,
+  provider: 40,
+  model: 100,
+};
+
+/**
+ * Sanitises an `origin` object received on /api/message or bootstrap (or built
+ * locally before forwarding). Returns null when it does not describe an agent
+ * on another relay. Every field is a capped string except `hops`.
+ */
+export function normalizeRemoteRelayOrigin(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const origin = { kind: 'agent' };
+  for (const [key, cap] of Object.entries(ORIGIN_CAPS)) {
+    const value = toText(raw[key]).replace(/[\r\n]+/g, ' ');
+    origin[key] = value ? value.slice(0, cap) : '';
+  }
+  if (!origin.relayId && !origin.relayName) return null;
+  if (origin.relayUrl && !/^https?:\/\//i.test(origin.relayUrl)) origin.relayUrl = '';
+  const hops = Number(raw.hops);
+  origin.hops = Number.isInteger(hops) && hops >= 0 ? Math.min(hops, 10) : 1;
+  return origin;
+}
+
+function quoteForHeader(value) {
+  return toText(value).replace(/["\]\r\n]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * The one line a relay puts at the top of a prompt it forwards, so the remote
+ * AGENT knows another agent is talking to it. The remote UI hides it when the
+ * message carries `origin` (the badge shows the same facts).
+ */
+export function formatRemotePromptHeader(origin) {
+  const parts = [`[Remote prompt from an agent on relay "${quoteForHeader(origin?.relayName) || 'unknown'}"`];
+  const title = quoteForHeader(origin?.conversationTitle);
+  if (title) parts.push(`session "${title}"`);
+  const model = quoteForHeader(origin?.model);
+  if (model) parts.push(model);
+  parts.push('acting for the user]');
+  return parts.join(' · ');
+}
+
+export const REMOTE_PROMPT_HEADER_PATTERN = /^\[Remote prompt from an agent on relay "[^"\r\n]*"[^\r\n]*\](?:\r?\n){1,2}/;
+
+export function withRemotePromptHeader(text, origin) {
+  return `${formatRemotePromptHeader(origin)}\n\n${String(text ?? '')}`;
+}
+
+export function stripRemotePromptHeader(text) {
+  return String(text ?? '').replace(REMOTE_PROMPT_HEADER_PATTERN, '');
+}
+
+// ─── Remote addresses ────────────────────────────────────────────────────────
+
+function ipv4Parts(host) {
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!match) return null;
+  const parts = match.slice(1).map(Number);
+  return parts.every((part) => part <= 255) ? parts : null;
+}
+
+function isLoopbackHost(host) {
+  if (host === 'localhost' || host === '::1' || host === '[::1]') return true;
+  const parts = ipv4Parts(host);
+  return !!parts && parts[0] === 127;
+}
+
+function isPrivateHost(host) {
+  const parts = ipv4Parts(host);
+  if (parts) {
+    const [a, b] = parts;
+    return a === 10
+      || (a === 172 && b >= 16 && b <= 31)
+      || (a === 192 && b === 168)
+      || (a === 100 && b >= 64 && b <= 127);
+  }
+  const bare = host.replace(/^\[|\]$/g, '').toLowerCase();
+  return /^f[cd][0-9a-f]{2}:/.test(bare);
+}
+
+/**
+ * The address policy: https anywhere; plain http only for loopback and private
+ * ranges (the token travels with every call). Returns `{ ok, warning? }` or
+ * `{ ok:false, error }`.
+ */
+export function checkRemoteRelayUrlPolicy(url) {
+  let parsed;
+  try {
+    parsed = url instanceof URL ? url : new URL(String(url));
+  } catch {
+    return { ok: false, error: 'Not a valid URL' };
+  }
+  if (parsed.protocol === 'https:') return { ok: true };
+  if (parsed.protocol !== 'http:') return { ok: false, error: 'Only https:// (or http:// on loopback and private networks) is supported' };
+  const host = parsed.hostname.toLowerCase();
+  if (isLoopbackHost(host)) return { ok: true, warning: 'Plain http on loopback (for example an SSH port forward).' };
+  if (isPrivateHost(host)) return { ok: true, warning: 'Plain http: the token crosses your network unencrypted.' };
+  return { ok: false, error: 'Plain http is only allowed for loopback and private network addresses; use https://' };
+}
+
+/**
+ * Turns whatever the user pasted — a web-client URL, possibly with ?token=,
+ * a #hash, a push_conv/conv deep link or a trailing index.html — into the
+ * relay's base URL (origin + remotePath, no trailing slash) and the token the
+ * link carried, if any.
+ */
+export function normalizeRemoteRelayLink(link) {
+  let raw = toText(link);
+  if (!raw) return { ok: false, error: 'Paste the web address of the other relay' };
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) raw = `https://${raw}`;
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return { ok: false, error: 'Not a valid URL' };
+  }
+  const policy = checkRemoteRelayUrlPolicy(parsed);
+  if (!policy.ok) return policy;
+  const token = toText(parsed.searchParams.get('token')) || null;
+  let pathname = parsed.pathname || '/';
+  const segments = pathname.split('/');
+  const lastSegment = segments[segments.length - 1];
+  if (lastSegment && lastSegment.includes('.')) segments.pop();
+  pathname = segments.join('/').replace(/\/+$/, '');
+  const baseUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
+  return {
+    ok: true,
+    baseUrl,
+    host: parsed.hostname.toLowerCase(),
+    token,
+    ...(policy.warning ? { warning: policy.warning } : {}),
+  };
+}
+
+/** 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}/`;
+}
+
+// ─── Activity line ───────────────────────────────────────────────────────────
+
+function clip(value, max) {
+  const text = toText(value).replace(/\s+/g, ' ');
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** The one-line summary the workers use for the tool's activity line. */
+export function summarizeRemoteRelayCall(input = {}) {
+  const action = toText(input?.action).toLowerCase() || 'call';
+  const relay = toText(input?.relay);
+  const session = toText(input?.session);
+  const target = [relay, session ? `session ${session.slice(0, 8)}` : ''].filter(Boolean).join(' ');
+  const text = input?.text ? `: “${clip(input.text, 60)}”` : '';
+  return target ? `${action} → ${target}${text}` : `${action}${text}`;
+}

package/shared/remote-relay-mentions.mjs

@@ -0,0 +1,129 @@
+// Finds the remote relays a user message mentions.
+//
+// A mention unlocks that relay for the conversation, so the rules are strict
+// about token boundaries: a relay is mentioned by its name or by the DNS host
+// of its URL, as a whole token, case-insensitively, with or without a leading @.
+//
+//   "ask @linux-test to run the suite"      → linux-test
+//   "what is relay-b.example.test doing?"   → the relay whose host that is
+//   "https://relay-b.example.test/x"        → same (URLs count)
+//   "a.relay-b.example.test"                → nothing for a relay named
+//                                             "relay-b.example.test" (a longer host)
+//   "relay-b.example.test.backup"           → nothing (a longer name)
+//   "curl localhost:3000"                   → nothing for a relay at localhost:8123
+//
+// A loopback name or an IP literal says where a relay runs, not which one it
+// is, and turns up in everyday text ("curl localhost:3000", "ping 10.0.0.1")
+// without its port: a URL host like that is no alias, and a relay whose name
+// is one (it gave none, so its host stood in) needs the leading @.
+//
+// Shared by the server (which unlocks) and the browser (which highlights).
+
+const NAME_CHAR = /[a-z0-9._-]/;
+const TAIL_CHAR = /[a-z0-9_-]/;
+const ALNUM = /[a-z0-9]/;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function hostOf(url) {
+  try {
+    return new URL(String(url)).hostname.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+/** 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];
+}
+
+function startsToken(lower, index) {
+  if (index === 0) return true;
+  return !NAME_CHAR.test(lower[index - 1]);
+}
+
+/** An @ right before `index` that starts a token itself ("ask @x", not "mail@x"). */
+function atMention(lower, index) {
+  return index > 0 && lower[index - 1] === '@' && startsToken(lower, index - 1);
+}
+
+function endsToken(lower, end) {
+  if (end >= lower.length) return true;
+  const next = lower[end];
+  if (TAIL_CHAR.test(next)) return false;
+  if (next === '.' && end + 1 < lower.length && ALNUM.test(lower[end + 1])) return false;
+  return true;
+}
+
+/**
+ * Returns `[{ relayId, alias, index }]`, one entry per mentioned relay (the
+ * first occurrence), in order of appearance. `relays` are `{ id, name, url }`.
+ * Aliases equal to one of `selfNames` (this relay's own name) are ignored, and
+ * an alias shared by two relays is ambiguous and ignored too.
+ */
+export function findRemoteRelayMentions(text, relays = [], { selfNames = [] } = {}) {
+  const lower = String(text ?? '').toLowerCase();
+  if (!lower || !Array.isArray(relays) || relays.length === 0) return [];
+  const self = new Set(selfNames.map((name) => toText(name).toLowerCase()).filter(Boolean));
+
+  const owners = new Map();
+  for (const relay of relays) {
+    const id = toText(relay?.id);
+    if (!id) continue;
+    for (const alias of remoteRelayAliases(relay)) {
+      if (self.has(alias)) continue;
+      const owner = owners.get(alias);
+      owners.set(alias, owner && owner !== id ? null : id);
+    }
+  }
+
+  const found = new Map();
+  for (const [alias, relayId] of owners) {
+    if (!relayId) continue;
+    const needsAt = isAddressHost(alias);
+    let from = 0;
+    while (from <= lower.length - alias.length) {
+      const index = lower.indexOf(alias, from);
+      if (index === -1) break;
+      if (startsToken(lower, index) && endsToken(lower, index + alias.length) && (!needsAt || atMention(lower, index))) {
+        const previous = found.get(relayId);
+        if (!previous || index < previous.index) found.set(relayId, { relayId, alias, index });
+        break;
+      }
+      from = index + 1;
+    }
+  }
+  return [...found.values()].sort((a, b) => a.index - b.index);
+}
+
+/**
+ * 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() };
+}