@xnng/browser-relay 1.6.0

package/extension/options.js

@@ -0,0 +1,269 @@
+const DEFAULT_IDLE_DETACH_SECONDS = 600
+const IDLE_DETACH_DEFAULT_MIGRATION_KEY = 'idleDetachDefaultMigratedTo600'
+const DEFAULT_REMOTE_HOST = 'https://relay.linso.ai'
+
+const t = (key) => window.I18N.t(key)
+
+const els = {
+  relayPort: document.getElementById('relayPort'),
+  idleDetachSeconds: document.getElementById('idleDetachSeconds'),
+  uiLang: document.getElementById('uiLang'),
+  save: document.getElementById('save'),
+  status: document.getElementById('status'),
+  remoteToggle: document.getElementById('remoteToggle'),
+  remoteState: document.getElementById('remoteState'),
+  remoteDetails: document.getElementById('remoteDetails'),
+  remoteHost: document.getElementById('remoteHost'),
+  regenerateDevice: document.getElementById('regenerateDevice'),
+  regenRow: document.getElementById('regenRow'),
+  regenConfirm: document.getElementById('regenConfirm'),
+  regenApply: document.getElementById('regenApply'),
+  regenCancel: document.getElementById('regenCancel'),
+  remoteDeviceId: document.getElementById('remoteDeviceId'),
+  copyRemoteDeviceId: document.getElementById('copyRemoteDeviceId'),
+  remoteCommand: document.getElementById('remoteCommand'),
+  copyRemoteCommand: document.getElementById('copyRemoteCommand'),
+  remoteStatus: document.getElementById('remoteStatus'),
+}
+
+function relayPortValue() {
+  return parseInt(els.relayPort.value, 10) || 18795
+}
+
+function normalizeRemoteHost(value) {
+  const trimmed = String(value || '').trim().replace(/\/+$/, '')
+  return trimmed || DEFAULT_REMOTE_HOST
+}
+
+function setStatus(el, kind, message) {
+  if (!message) {
+    el.className = 'status'
+    el.textContent = ''
+    return
+  }
+  el.className = `status ${kind}`
+  el.textContent = message
+}
+
+function setRemoteState(kind, label) {
+  els.remoteState.className = `lbl is-${kind}`
+  els.remoteState.textContent = label
+}
+
+// Compact capability: `br-<secret>`. The routeId is derived from the secret
+// (below) instead of stored in the id, so it never appears. secret = 96-bit.
+function randomBase64Url(bytes) {
+  const arr = new Uint8Array(bytes)
+  crypto.getRandomValues(arr)
+  let bin = ''
+  for (const b of arr) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
+}
+
+// SHA-256(secret) → base64url → first 16 chars. Must match remote-protocol.deriveRouteId.
+async function deriveRouteId(secret) {
+  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret))
+  let bin = ''
+  for (const b of new Uint8Array(buf)) bin += String.fromCharCode(b)
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '').slice(0, 16)
+}
+
+async function newRemoteCapability() {
+  const secret = randomBase64Url(12)
+  const routeId = await deriveRouteId(secret)
+  return { routeId, secret, remoteDeviceId: `br-${secret}` }
+}
+
+function commandFor(remoteDeviceId, remoteHost) {
+  return `browser-relay tabs --remote-device-id ${remoteDeviceId} --remote-host ${remoteHost}`
+}
+
+function renderRemote(config = {}) {
+  const host = normalizeRemoteHost(config.remoteHost)
+  const enabled = !!config.remoteControlEnabled && !!config.remoteDeviceId
+  els.remoteHost.value = host
+  els.remoteToggle.checked = !!config.remoteControlEnabled
+  els.remoteDetails.classList.toggle('hidden', !enabled)
+  showRegenConfirm(false)
+
+  if (enabled) {
+    setRemoteState('on', t('stateOn'))
+    els.remoteDeviceId.textContent = config.remoteDeviceId
+    els.remoteCommand.textContent = commandFor(config.remoteDeviceId, host)
+    return
+  }
+
+  setRemoteState('off', t('stateOff'))
+  els.remoteDeviceId.textContent = ''
+  els.remoteCommand.textContent = ''
+  setStatus(els.remoteStatus, '', '')
+}
+
+async function saveLocalSettings() {
+  const port = relayPortValue()
+  const idleRaw = els.idleDetachSeconds.value
+  let idleDetachSeconds = parseInt(idleRaw, 10)
+  if (!Number.isFinite(idleDetachSeconds) || idleDetachSeconds < 0) idleDetachSeconds = DEFAULT_IDLE_DETACH_SECONDS
+
+  await chrome.storage.local.set({ relayPort: port, idleDetachSeconds, [IDLE_DETACH_DEFAULT_MIGRATION_KEY]: true })
+  return { port, idleDetachSeconds }
+}
+
+els.save.addEventListener('click', async () => {
+  const { port } = await saveLocalSettings()
+
+  const url = `http://127.0.0.1:${port}/`
+  try {
+    const res = await fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(3000) })
+    if (res.ok || res.status === 200) {
+      setStatus(els.status, 'ok', t('statusConnectedLocal'))
+    } else {
+      setStatus(els.status, 'err', `${t('statusRelayStatus')} (${res.status})`)
+    }
+  } catch (err) {
+    setStatus(els.status, 'err', `${t('statusRelayUnreachable')} (${err.message})`)
+  }
+})
+
+// Mint a fresh capability, persist it, and ask the background to connect to the hub.
+// Shared by the toggle (turning on) and the Regenerate button.
+async function enableRemote() {
+  await saveLocalSettings()
+  const remoteHost = normalizeRemoteHost(els.remoteHost.value)
+  const { routeId, secret, remoteDeviceId } = await newRemoteCapability()
+
+  await chrome.storage.local.set({
+    remoteControlEnabled: true,
+    remoteHost,
+    remoteRouteId: routeId,
+    remoteSecret: secret,
+    remoteDeviceId,
+  })
+  renderRemote({ remoteControlEnabled: true, remoteHost, remoteDeviceId })
+  setStatus(els.remoteStatus, 'info', t('statusConnectingHub'))
+
+  try {
+    const data = await chrome.runtime.sendMessage({ type: 'enableRemoteControl', remoteHost, routeId, secret, remoteDeviceId })
+    if (data?.connected) {
+      setRemoteState('on', t('stateOn'))
+      setStatus(els.remoteStatus, 'ok', t('statusRemoteConnected'))
+    } else {
+      setRemoteState('err', t('stateOn'))
+      setStatus(els.remoteStatus, 'err', t('statusRemoteNoHub') + (data?.lastError || 'unknown error'))
+    }
+  } catch (err) {
+    setRemoteState('err', t('stateOn'))
+    setStatus(els.remoteStatus, 'err', t('statusRemoteNoReach') + err.message)
+  }
+}
+
+async function disableRemote() {
+  try {
+    await chrome.runtime.sendMessage({ type: 'disableRemoteControl' })
+  } catch {
+    // Background may be waking up; still clear extension-side state.
+  }
+  const stored = await chrome.storage.local.get(['remoteHost'])
+  await chrome.storage.local.remove(['remoteRouteId', 'remoteSecret', 'remoteDeviceId'])
+  await chrome.storage.local.set({ remoteControlEnabled: false })
+  renderRemote({ remoteControlEnabled: false, remoteHost: stored.remoteHost || DEFAULT_REMOTE_HOST })
+  setStatus(els.remoteStatus, 'info', t('statusRemoteOff'))
+}
+
+els.remoteToggle.addEventListener('change', async () => {
+  els.remoteToggle.disabled = true
+  try {
+    if (els.remoteToggle.checked) await enableRemote()
+    else await disableRemote()
+  } finally {
+    els.remoteToggle.disabled = false
+  }
+})
+
+// Inline (not a browser confirm dialog) two-step confirmation for regenerate.
+function showRegenConfirm(show) {
+  els.regenRow.classList.toggle('hidden', show)
+  els.regenConfirm.classList.toggle('hidden', !show)
+}
+
+els.regenerateDevice.addEventListener('click', () => showRegenConfirm(true))
+els.regenCancel.addEventListener('click', () => showRegenConfirm(false))
+els.regenApply.addEventListener('click', async () => {
+  els.regenApply.disabled = true
+  try {
+    await enableRemote()
+    showRegenConfirm(false)
+  } finally {
+    els.regenApply.disabled = false
+  }
+})
+
+function flashButton(button, text) {
+  const label = text || t('copied')
+  const original = button.textContent
+  button.textContent = label
+  setTimeout(() => { button.textContent = original }, 1200)
+}
+
+function copyText(text, button) {
+  if (!text) return
+  navigator.clipboard.writeText(text).then(() => {
+    if (button) flashButton(button)
+  }).catch(() => {})
+}
+
+els.copyRemoteDeviceId.addEventListener('click', () => copyText(els.remoteDeviceId.textContent.trim(), els.copyRemoteDeviceId))
+els.remoteDeviceId.addEventListener('click', () => copyText(els.remoteDeviceId.textContent.trim(), els.copyRemoteDeviceId))
+els.remoteCommand.addEventListener('click', () => copyText(els.remoteCommand.textContent.trim(), els.copyRemoteCommand))
+els.copyRemoteCommand.addEventListener('click', () => copyText(els.remoteCommand.textContent.trim(), els.copyRemoteCommand))
+
+els.uiLang.addEventListener('change', async () => {
+  await chrome.storage.local.set({ uiLang: els.uiLang.value })
+  await initFromStorage()
+})
+
+async function initFromStorage() {
+  const result = await chrome.storage.local.get([
+    'relayPort',
+    'idleDetachSeconds',
+    IDLE_DETACH_DEFAULT_MIGRATION_KEY,
+    'remoteControlEnabled',
+    'remoteHost',
+    'remoteDeviceId',
+    'uiLang',
+  ])
+
+  window.I18N.setLang(result.uiLang || 'auto')
+  els.uiLang.value = result.uiLang || 'auto'
+  window.I18N.apply()
+
+  if (result.relayPort) els.relayPort.value = result.relayPort
+
+  let idleDetachSeconds = result.idleDetachSeconds
+  if (Number.parseInt(String(idleDetachSeconds), 10) === 30 && !result[IDLE_DETACH_DEFAULT_MIGRATION_KEY]) {
+    idleDetachSeconds = DEFAULT_IDLE_DETACH_SECONDS
+    await chrome.storage.local.set({ idleDetachSeconds, [IDLE_DETACH_DEFAULT_MIGRATION_KEY]: true })
+  }
+  if (result.idleDetachSeconds !== undefined && result.idleDetachSeconds !== null) {
+    els.idleDetachSeconds.value = idleDetachSeconds
+  }
+
+  renderRemote({
+    remoteControlEnabled: !!result.remoteControlEnabled,
+    remoteHost: result.remoteHost || DEFAULT_REMOTE_HOST,
+    remoteDeviceId: result.remoteDeviceId,
+  })
+
+  if (!result.remoteControlEnabled) return
+
+  try {
+    const data = await chrome.runtime.sendMessage({ type: 'getRemoteControlStatus' })
+    setRemoteState(data?.connected ? 'on' : 'err', t('stateOn'))
+    setStatus(els.remoteStatus, data?.connected ? 'ok' : 'err', data?.connected ? t('statusRemoteConnectedShort') : t('statusRemoteDisconnected') + (data?.lastError || 'not connected'))
+  } catch {
+    setRemoteState('err', t('stateOn'))
+    setStatus(els.remoteStatus, 'err', t('statusRemoteBgOffline'))
+  }
+}
+
+initFromStorage()

package/extension/popup.html

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <style>
+    :root { color-scheme: light; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; width: 320px; margin: 0; padding: 14px 16px; color: #0f172a; background: #fff; }
+    .row { display: flex; align-items: center; gap: 10px; }
+    .dot { width: 10px; height: 10px; border-radius: 50%; flex-shrink: 0; }
+    .dot.on { background: #22c55e; box-shadow: 0 0 0 3px rgba(34,197,94,0.15); }
+    .dot.off { background: #94a3b8; }
+    .dot.err { background: #ef4444; box-shadow: 0 0 0 3px rgba(239,68,68,0.15); }
+    .dot.connecting { background: #f59e0b; animation: pulse 1.2s infinite; }
+    @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }
+    .label { font-weight: 600; font-size: 14px; line-height: 1.2; }
+    .meta { font-size: 12px; color: #64748b; margin-top: 3px; }
+    .actions { display: flex; gap: 8px; margin-top: 14px; }
+    button { flex: 1; padding: 8px 10px; font-size: 13px; border: 1px solid #e2e8f0; background: white; border-radius: 6px; cursor: pointer; color: #0f172a; font-family: inherit; }
+    button.primary { background: #22c55e; color: white; border-color: #22c55e; font-weight: 500; }
+    button:hover { filter: brightness(0.97); }
+    button.primary:hover { filter: brightness(0.95); }
+    .install { margin-top: 12px; padding: 10px 12px; background: #fff7ed; border: 1px solid #fed7aa; border-radius: 6px; font-size: 12px; display: none; }
+    .install.show { display: block; }
+    .install-title { font-weight: 600; color: #9a3412; margin-bottom: 8px; font-size: 12px; }
+    code { display: block; padding: 6px 10px; background: #1e293b; color: #f1f5f9; border-radius: 4px; font-family: ui-monospace, 'SF Mono', Menlo, monospace; font-size: 11px; margin-bottom: 5px; cursor: pointer; position: relative; user-select: all; }
+    code::after { content: 'copy'; position: absolute; right: 8px; top: 50%; transform: translateY(-50%); font-size: 10px; opacity: 0.5; }
+    code.copied::after { content: 'copied ✓'; opacity: 1; color: #86efac; }
+    .hint { font-size: 11px; color: #78716c; margin-top: 6px; }
+    .session { display:flex; align-items:center; gap:8px; margin-top:8px; }
+    .session span { flex:1; min-width:0; font-size:12px; overflow-wrap:anywhere; }
+    .session button { flex:0 0 auto; }
+    #session-list { max-height:190px; overflow:auto; }
+    footer { margin-top: 14px; padding-top: 10px; border-top: 1px solid #e2e8f0; display: flex; justify-content: space-between; font-size: 11px; color: #94a3b8; }
+    footer a { color: #64748b; text-decoration: none; cursor: pointer; }
+    footer a:hover { color: #0f172a; }
+  </style>
+</head>
+<body>
+  <div class="row">
+    <div class="dot" id="dot"></div>
+    <div style="flex:1">
+      <div class="label" id="label" data-i18n="popupLoading">Loading…</div>
+      <div class="meta" id="meta"></div>
+    </div>
+  </div>
+
+  <div class="actions">
+    <button id="reconnect" class="primary" data-i18n="popupReconnect">Reconnect</button>
+    <button id="options" data-i18n="popupOptions">Options</button>
+  </div>
+
+  <div class="install" id="install">
+    <div class="install-title" data-i18n="popupInstallTitle">Relay server not running — install and check it:</div>
+    <code id="cmd1">npm install -g @xnng/browser-relay</code>
+    <code id="cmd2">browser-relay status</code>
+    <div class="hint" data-i18n-html="popupInstallHint">Already installed? Check with <code style="display:inline; padding:1px 5px; cursor:text; font-size:11px">browser-relay status</code></div>
+  </div>
+
+  <div id="task-controls" hidden>
+    <p class="meta" id="task-status" role="status"></p>
+    <button id="cancel-tasks" data-i18n="popupCancelTasks">Cancel current tasks</button>
+  </div>
+
+  <section id="sessions" hidden><p class="meta" data-i18n="popupSessions">Active sessions</p><div id="session-list"></div></section>
+
+  <footer>
+    <span id="version">—</span>
+    <a id="docs" data-i18n="popupDocs">Docs</a>
+  </footer>
+
+  <script src="i18n.js"></script>
+  <script src="popup.js"></script>
+</body>
+</html>

package/extension/popup.js

@@ -0,0 +1,105 @@
+const t = (key) => window.I18N.t(key)
+
+const els = {
+  dot: document.getElementById('dot'),
+  label: document.getElementById('label'),
+  meta: document.getElementById('meta'),
+  reconnect: document.getElementById('reconnect'),
+  options: document.getElementById('options'),
+  install: document.getElementById('install'),
+  version: document.getElementById('version'),
+  docs: document.getElementById('docs'),
+  cmd1: document.getElementById('cmd1'),
+  cmd2: document.getElementById('cmd2'),
+}
+
+function render(state) {
+  const { connected, connecting, port, attachedCount, lastError, version } = state
+  const host = `127.0.0.1:${port}`
+
+  if (connected) {
+    els.dot.className = 'dot on'
+    els.label.textContent = t('popupConnected')
+    els.meta.textContent = `${host} · ${attachedCount} ${t('popupTabsAttached')}`
+    els.install.classList.remove('show')
+    els.reconnect.textContent = t('popupReattach')
+  } else if (connecting) {
+    els.dot.className = 'dot connecting'
+    els.label.textContent = t('popupConnecting')
+    els.meta.textContent = t('popupTrying') + host
+    els.install.classList.remove('show')
+    els.reconnect.textContent = t('popupRetry')
+  } else {
+    els.dot.className = 'dot err'
+    els.label.textContent = t('popupNotConnected')
+    els.meta.textContent = lastError || (t('popupNoRelay') + host)
+    els.install.classList.add('show')
+    els.reconnect.textContent = t('popupRetry')
+  }
+
+  els.version.textContent = version ? `v${version}` : ''
+}
+
+async function fetchStatus() {
+  try {
+    const res = await chrome.runtime.sendMessage({ type: 'getStatus' })
+    if (res) render(res)
+    const {tasks=[],claims=[]} = await chrome.runtime.sendMessage({type:'getAutomationTasks'})
+    document.getElementById('sessions').hidden=claims.length===0
+    const owners=new Map()
+    for(const claim of claims){const group=owners.get(claim.sessionId)||{label:claim.label||claim.sessionId,count:0};group.count++;owners.set(claim.sessionId,group)}
+    const list=document.getElementById('session-list');list.replaceChildren()
+    for(const [sessionId,group] of owners){
+      const row=document.createElement('div');row.className='session'
+      const label=document.createElement('span');label.textContent=`${group.label} · ${group.count} ${t('popupTabsAttached')}`
+      const stop=document.createElement('button');stop.textContent=t('popupStopSession');stop.addEventListener('click',async()=>{stop.disabled=true;await chrome.runtime.sendMessage({type:'stopAutomationSession',sessionId});await fetchStatus()})
+      row.append(label,stop);list.append(row)
+    }
+    document.getElementById('task-controls').hidden = tasks.length === 0
+    document.getElementById('task-status').textContent = `${tasks.length} ${t('popupActiveTasks')}`
+  } catch {
+    // background may be waking up
+  }
+}
+
+els.reconnect.addEventListener('click', async () => {
+  els.dot.className = 'dot connecting'
+  els.label.textContent = t('popupConnecting')
+  els.meta.textContent = ''
+  try { await chrome.runtime.sendMessage({ type: 'reconnect' }) } catch {}
+  setTimeout(fetchStatus, 500)
+  setTimeout(fetchStatus, 1500)
+})
+
+els.options.addEventListener('click', () => {
+  chrome.runtime.openOptionsPage()
+})
+
+document.getElementById('cancel-tasks').addEventListener('click',async()=>{
+  await chrome.runtime.sendMessage({type:'cancelAutomationTasks'})
+  document.getElementById('task-status').textContent=t('popupCancellingTasks')
+})
+
+els.docs.addEventListener('click', (e) => {
+  e.preventDefault()
+  chrome.tabs.create({ url: 'https://www.npmjs.com/package/@xnng/browser-relay' })
+})
+
+function copyCmd(el) {
+  navigator.clipboard.writeText(el.textContent.trim()).then(() => {
+    el.classList.add('copied')
+    setTimeout(() => el.classList.remove('copied'), 1200)
+  }).catch(() => {})
+}
+
+els.cmd1.addEventListener('click', () => copyCmd(els.cmd1))
+els.cmd2.addEventListener('click', () => copyCmd(els.cmd2))
+
+;(async () => {
+  const { uiLang } = await chrome.storage.local.get(['uiLang'])
+  window.I18N.setLang(uiLang || 'auto')
+  window.I18N.apply()
+  fetchStatus()
+})()
+const pollTimer = setInterval(fetchStatus, 1500)
+window.addEventListener('unload', () => clearInterval(pollTimer))

package/extension/protocol.js

@@ -0,0 +1,45 @@
+export const PROTOCOL_VERSION = 2;
+export const isTaskRequest = (method, path) =>
+  ["/api/read", "/api/observe"].includes(path) ||
+  (method === "POST" && ["/api/actions", "/api/evaluate", "/api/tabs/focus"].includes(path));
+export const FEATURES = [
+  "observe",
+  "read",
+  "ax",
+  "refs",
+  "frames",
+  "shadow-dom",
+  "diff",
+  "actions",
+  "tasks",
+  "coordinates",
+  "drag",
+  "hover",
+  "screenshot-mapping",
+  "scoped-targets",
+  "action-readiness-wait",
+  "aria-check",
+  "tabs",
+  "observation-pages",
+  "full-links",
+  "sessions",
+  "task-groups",
+  "handoff",
+  "focus",
+];
+export const isAutomationPath = (path) =>
+  [
+    "/api/observe",
+    "/api/read",
+    "/api/actions",
+    "/api/capabilities",
+    "/api/sessions",
+    "/api/session/check",
+    "/api/evaluate",
+    "/api/tabs/create",
+    "/api/tabs/close",
+    "/api/tabs/focus",
+    "/api/tabs/claim",
+    "/api/tabs/release",
+    "/api/tabs/handoff",
+  ].includes(path) || path.startsWith("/api/tasks/");

package/extension/remote-auth.js

@@ -0,0 +1,18 @@
+export function createRemoteAuthMessageHandler({ onAuthenticated, onMessage }) {
+  let authenticated = false
+
+  return (text) => {
+    let msg
+    try { msg = JSON.parse(String(text || '')) } catch { return }
+
+    if (!authenticated) {
+      if (msg?.type !== 'device.authenticated') return
+      authenticated = true
+      onAuthenticated()
+      return
+    }
+
+    if (msg?.type === 'device.authenticated') return
+    onMessage(String(text || ''), msg)
+  }
+}

package/extension/sessions.js

@@ -0,0 +1,134 @@
+import { TaskError } from "./tasks.js";
+
+// Leases coordinate trusted clients sharing Chrome. They are not an access
+// control sandbox against another local debugger or the user themselves.
+export function createSessions({
+  now = Date.now,
+  ttlMs = 120000,
+  cancelTab = () => {},
+  cancelSession = () => {},
+  active = () => [],
+} = {}) {
+  const sessions = new Map(),
+    claims = new Map(),
+    stopped = new Map();
+  const valid = (id) => {
+    if (typeof id !== "string" || !/^[\w.-]{1,128}$/.test(id))
+      throw new TaskError(
+        "invalid_session",
+        "Use a sessionId with 1–128 letters, digits, dots, dashes or underscores",
+      );
+    return id;
+  };
+  const publicClaim = (claim) => claim && { ...claim };
+  function stop(id, reason = "session_stopped") {
+    valid(id);
+    cancelSession(id, reason);
+    const released = [];
+    for (const [tabId, claim] of claims)
+      if (claim.sessionId === id) {
+        cancelTab(tabId, reason);
+        released.push(publicClaim(claim));
+        claims.delete(tabId);
+      }
+    sessions.delete(id);
+    stopped.set(id, reason);
+    if (stopped.size > 500) stopped.delete(stopped.keys().next().value);
+    return released;
+  }
+  function sweep() {
+    for (const [id, session] of sessions)
+      if (session.expiresAt <= now()) stop(id, "session_expired");
+  }
+  function touch(id) {
+    valid(id);
+    sweep();
+    if (stopped.has(id))
+      throw new TaskError(
+        stopped.get(id),
+        "Session ended; start a new session explicitly",
+        409,
+      );
+    if (!sessions.has(id) && sessions.size >= 100)
+      throw new TaskError("session_limit", "Too many active sessions", 429);
+    const session = { sessionId: id, expiresAt: now() + ttlMs };
+    sessions.set(id, session);
+    return session;
+  }
+  function check(tabId, id) {
+    sweep();
+    const claim = claims.get(tabId);
+    if (claim && claim.sessionId !== id)
+      throw new TaskError(
+        "tab_claimed",
+        `Tab is owned by session ${claim.sessionId}; request a handoff or wait for release`,
+        409,
+      );
+    if (id) touch(id);
+    return claim;
+  }
+  function claim(tabId, id, { created = false, label = "" } = {}) {
+    valid(id);
+    check(tabId, id);
+    if (!claims.has(tabId))
+      claims.set(tabId, {
+        tabId,
+        sessionId: id,
+        created,
+        label: String(label).slice(0, 100),
+        claimedAt: now(),
+      });
+    if (created) claims.get(tabId).created = true;
+    if (label) claims.get(tabId).label = String(label).slice(0, 100);
+    return {
+      ...publicClaim(claims.get(tabId)),
+      expiresAt: sessions.get(id).expiresAt,
+    };
+  }
+  function release(tabId, id) {
+    check(tabId, id);
+    if (active().some((job) => job.tabId === tabId))
+      throw new TaskError(
+        "tab_busy",
+        "Cancel and await pending tasks before releasing this tab",
+        409,
+      );
+    const result = publicClaim(claims.get(tabId));
+    claims.delete(tabId);
+    return result;
+  }
+  function handoff(tabId, id, toSessionId) {
+    valid(toSessionId);
+    check(tabId, id);
+    if (!claims.has(tabId))
+      throw new TaskError(
+        "tab_unclaimed",
+        "Claim the tab before handing it off",
+        409,
+      );
+    // Validate the receiver before releasing the owner.
+    touch(toSessionId);
+    const previous = release(tabId, id);
+    return claim(tabId, toSessionId, previous);
+  }
+  return {
+    claim,
+    check,
+    release,
+    handoff,
+    touch,
+    stop,
+    sweep,
+    forget: (tabId) => claims.delete(tabId),
+    list: () => {
+      sweep();
+      return [...claims.values()].map((c) => ({
+        ...c,
+        expiresAt: sessions.get(c.sessionId)?.expiresAt,
+      }));
+    },
+    stopAll: (reason) => {
+      for (const id of [...sessions.keys()]) stop(id, reason);
+    },
+  };
+}