oharness 0.7.1 → 0.9.0

package/extension/background.js

@@ -0,0 +1,380 @@
+/**
+ * The relay.
+ *
+ * Everything clever about driving a browser lives in the harness; this end only
+ * forwards. It holds a native messaging port to the local host process, turns
+ * the harness's CDP messages into `chrome.debugger` calls, and sends every
+ * debugger event back. The control messages exist because CDP has no
+ * browser-level half here — `chrome.debugger` is scoped to one tab, so listing
+ * tabs and opening one go through `chrome.tabs`.
+ *
+ * Why an extension at all: Chrome has refused remote debugging on the default
+ * profile since 136, so this is the only sanctioned way to reach a browser
+ * somebody is already signed into. Chrome shows its own "being debugged" banner
+ * for as long as anything is attached, which is the disclosure this deserves —
+ * it is not something to suppress.
+ *
+ * The port also keeps the service worker alive: an MV3 worker is shut down when
+ * idle, but not while a port is open. When the port goes — the host crashed, was
+ * rebuilt, or was never registered — it is tried again on a backoff, and an
+ * alarm wakes a worker Chrome has since put to sleep so the retry still happens.
+ */
+
+const HOST_NAME = "ai.oharness.browser";
+const PROTOCOL_VERSION = "1.3";
+const RECONNECT_ALARM = "reconnect";
+/** Seconds between attempts: quick after a restart, patient when nothing is installed. */
+const BACKOFF = [1, 2, 5, 10, 30];
+
+let port = null;
+/** Tabs this extension has attached, so detach is never guessed at. */
+const attached = new Set();
+/** What the popup shows. */
+const status = { connected: false, error: null, clients: 0, servers: [] };
+let attempt = 0;
+let retryTimer = null;
+
+function connect() {
+  if (port) return port;
+  clearTimeout(retryTimer);
+  retryTimer = null;
+  port = chrome.runtime.connectNative(HOST_NAME);
+  status.connected = true;
+  status.error = null;
+
+  port.onMessage.addListener((message) => {
+    // A message means the host really started; connectNative returning does not.
+    attempt = 0;
+    void handle(message);
+  });
+
+  port.onDisconnect.addListener(() => {
+    const error = chrome.runtime.lastError;
+    if (error) console.warn("OHarness host disconnected:", error.message);
+    port = null;
+    status.connected = false;
+    status.clients = 0;
+    status.servers = [];
+    tell({ type: "servers", connected: false, servers: [] });
+    status.error = error?.message ?? "The OHarness host stopped.";
+    // Let go of every tab: a debugger left attached shows the banner forever
+    // and blocks DevTools on that tab.
+    for (const tabId of [...attached]) {
+      chrome.debugger.detach({ tabId }).catch(() => {});
+      attached.delete(tabId);
+    }
+    updateBadge();
+    scheduleReconnect();
+  });
+
+  updateBadge();
+  return port;
+}
+
+function scheduleReconnect() {
+  if (retryTimer) return;
+  const seconds = BACKOFF[Math.min(attempt, BACKOFF.length - 1)];
+  attempt += 1;
+  retryTimer = setTimeout(() => {
+    retryTimer = null;
+    connect();
+  }, seconds * 1000);
+}
+
+/** The toolbar says how many tabs are being driven, or that nothing can be. */
+function updateBadge() {
+  if (!status.connected) {
+    void chrome.action.setBadgeBackgroundColor({ color: "#b45309" });
+    void chrome.action.setBadgeTextColor?.({ color: "#ffffff" });
+    void chrome.action.setBadgeText({ text: "!" });
+    return;
+  }
+  // The brand lime, as the app uses it: the harness is alive and working.
+  void chrome.action.setBadgeBackgroundColor({ color: "#c6f432" });
+  void chrome.action.setBadgeTextColor?.({ color: "#0e1013" });
+  void chrome.action.setBadgeText({ text: attached.size > 0 ? String(attached.size) : "" });
+}
+
+function reply(message) {
+  try {
+    port?.postMessage(message);
+  } catch (error) {
+    console.warn("OHarness could not reply:", error);
+  }
+}
+
+async function handle(message) {
+  if (!message || typeof message !== "object") return;
+
+  if (message.t === "host") {
+    status.clients = Number(message.clients) || 0;
+    // Where each OHarness page is, for the side panel. Kept in memory only:
+    // the tokens in them are this run's and never written anywhere.
+    status.servers = Array.isArray(message.servers) ? message.servers : [];
+    tell({ type: "servers", connected: true, servers: status.servers });
+    return;
+  }
+
+  if (message.t === "cdp") {
+    // No id means the harness sent an event back at us, which it does not.
+    if (typeof message.id !== "number") return;
+    const tabId = Number(message.sessionId);
+    if (!Number.isInteger(tabId)) {
+      reply({ t: "cdp", id: message.id, error: { message: "no tab for this command" } });
+      return;
+    }
+    try {
+      const result = await chrome.debugger.sendCommand(
+        { tabId },
+        message.method,
+        message.params ?? {},
+      );
+      reply({ t: "cdp", id: message.id, result: result ?? {} });
+    } catch (error) {
+      reply({ t: "cdp", id: message.id, error: { message: String(error?.message ?? error) } });
+    }
+    return;
+  }
+
+  if (message.t !== "ctl") return;
+  const { id, op } = message;
+  try {
+    if (op === "tabs") {
+      const tabs = await chrome.tabs.query({});
+      reply({
+        t: "ctl",
+        id,
+        result: tabs
+          // A tab with no id cannot be driven, and chrome:// pages refuse the
+          // debugger, so offering them would only produce failures later.
+          .filter((tab) => typeof tab.id === "number" && !isPrivileged(tab.url) && !isOHarness(tab.url))
+          .map((tab) => ({ tabId: tab.id, url: tab.url, title: tab.title })),
+      });
+      return;
+    }
+    if (op === "info") {
+      reply({ t: "ctl", id, result: browserIdentity() });
+      return;
+    }
+    if (op === "newTab") {
+      const tab = await chrome.tabs.create({ url: message.url || "about:blank", active: false });
+      // A tab that cannot be grouped is still a tab; grouping is for the person's benefit.
+      await placeInGroup(tab.id, message.group).catch((error) => console.warn("OHarness could not group a tab:", error));
+      reply({ t: "ctl", id, result: { tabId: tab.id } });
+      return;
+    }
+    if (op === "attach") {
+      const tabId = Number(message.tabId);
+      if (!attached.has(tabId)) {
+        await chrome.debugger.attach({ tabId }, PROTOCOL_VERSION);
+        attached.add(tabId);
+        updateBadge();
+      }
+      reply({ t: "ctl", id, result: { ok: true } });
+      return;
+    }
+    if (op === "activate") {
+      const tabId = Number(message.tabId);
+      await chrome.tabs.update(tabId, { active: true });
+      reply({ t: "ctl", id, result: { ok: true } });
+      return;
+    }
+    if (op === "closeTab") {
+      const tabId = Number(message.tabId);
+      attached.delete(tabId);
+      updateBadge();
+      await chrome.tabs.remove(tabId);
+      reply({ t: "ctl", id, result: { ok: true } });
+      return;
+    }
+    if (op === "detach") {
+      const tabId = Number(message.tabId);
+      if (attached.has(tabId)) {
+        await chrome.debugger.detach({ tabId }).catch(() => {});
+        attached.delete(tabId);
+        updateBadge();
+      }
+      reply({ t: "ctl", id, result: { ok: true } });
+      return;
+    }
+    reply({ t: "ctl", id, error: `unknown control op "${op}"` });
+  } catch (error) {
+    reply({ t: "ctl", id, error: String(error?.message ?? error) });
+  }
+}
+
+/**
+ * One tab group per conversation, the way several people sharing a desk keep
+ * their papers in separate piles: the person can see which tabs belong to
+ * which piece of work, collapse one, or close it as a whole.
+ *
+ * Only tabs the agent opened are grouped. A tab the person already had open
+ * and the agent was pointed at stays exactly where they put it.
+ *
+ * Which group belongs to which conversation is kept in session storage, so a
+ * worker Chrome restarts in the middle of a conversation keeps using the same
+ * group rather than starting another.
+ *
+ * Every OHarness group is green: Chrome offers nine fixed group colours and no
+ * custom ones, and green is the one that reads as the brand's lime. The
+ * conversation's title, not a colour, is what tells two groups apart.
+ */
+const GROUP_COLOR = "green";
+
+function groupTitle(title) {
+  const text = String(title || "OHarness").replace(/\s+/g, " ").trim();
+  return text.length > 28 ? `${text.slice(0, 27)}…` : text;
+}
+
+async function placeInGroup(tabId, group) {
+  if (!group || typeof group.key !== "string" || !chrome.tabGroups) return;
+  const storageKey = `group:${group.key}`;
+  const stored = (await chrome.storage.session.get(storageKey))[storageKey];
+  const existing = typeof stored === "number" ? await chrome.tabGroups.get(stored).catch(() => null) : null;
+  const title = groupTitle(group.title);
+  if (existing) {
+    await chrome.tabs.group({ groupId: existing.id, tabIds: [tabId] });
+    // A conversation is named by its first message, which may come after its
+    // first tab; the group catches up the next time it gets a tab.
+    const update = {};
+    if (group.title && existing.title !== title) update.title = title;
+    // Groups made before every group was green catch up too.
+    if (existing.color !== GROUP_COLOR) update.color = GROUP_COLOR;
+    if (Object.keys(update).length) await chrome.tabGroups.update(existing.id, update);
+    return;
+  }
+  const groupId = await chrome.tabs.group({ tabIds: [tabId] });
+  await chrome.tabGroups.update(groupId, { title, color: GROUP_COLOR, collapsed: false });
+  // Both ways round: the conversation's group, and — for the side panel,
+  // following the person between groups — the group's conversation.
+  await chrome.storage.session.set({
+    [storageKey]: groupId,
+    [`conversation:${groupId}`]: { id: group.key, ...(typeof group.cwd === "string" ? { cwd: group.cwd } : {}) },
+  });
+}
+
+/** The conversation a tab's group belongs to, if it is one of ours. */
+async function conversationOf(tab) {
+  if (!tab || typeof tab.groupId !== "number" || tab.groupId < 0) return null;
+  const key = `conversation:${tab.groupId}`;
+  return (await chrome.storage.session.get(key))[key] ?? null;
+}
+
+/** Say something to the side panel, if it is open; nobody listening is fine. */
+function tell(message) {
+  chrome.runtime.sendMessage(message).catch(() => {});
+}
+
+/**
+ * The side panel follows the person: moving to a tab in a conversation's
+ * group shows that conversation. Any other tab leaves it where it is.
+ */
+async function followActiveTab(tabId) {
+  const tab = await chrome.tabs.get(tabId).catch(() => null);
+  const conversation = await conversationOf(tab);
+  if (conversation) tell({ type: "focus-session", ...conversation });
+}
+
+chrome.tabs.onActivated.addListener(({ tabId }) => void followActiveTab(tabId));
+chrome.tabs.onUpdated.addListener((tabId, change, tab) => {
+  if ("groupId" in change && tab.active) void followActiveTab(tabId);
+});
+
+/**
+ * OHarness's own pages — the page a web server serves, open in a tab — are
+ * never offered to an agent: driving the thing that drives it is a loop, and
+ * the page holds a token that runs commands on this machine.
+ */
+function isOHarness(url) {
+  return typeof url === "string" && status.servers.some((server) => url.startsWith(server.url));
+}
+
+/**
+ * Which Chromium this is, so the harness can name the browser a sign-in is
+ * imported from. Brands are the honest source; the user-agent string claims to
+ * be Chrome in every one of them.
+ */
+function browserIdentity() {
+  const brands = navigator.userAgentData?.brands ?? [];
+  const named = brands.find((entry) => !/not.?a.?brand|^chromium$/i.test(entry.brand));
+  const brand = named ?? brands.find((entry) => /^chromium$/i.test(entry.brand));
+  return { name: brand?.brand ?? "Chrome", version: brand?.version };
+}
+
+/** Pages Chrome will not let an extension debug. */
+function isPrivileged(url) {
+  return typeof url === "string" && /^(chrome|edge|about|devtools|chrome-extension):/i.test(url);
+}
+
+// Debugger events go back as ordinary CDP messages, tagged with the tab they
+// came from — which is exactly the session id the harness routes on.
+chrome.debugger.onEvent.addListener((source, method, params) => {
+  if (typeof source.tabId !== "number") return;
+  reply({ t: "cdp", method, params: params ?? {}, sessionId: String(source.tabId) });
+});
+
+// Chrome detached on its own: the person pressed Cancel on the banner, closed
+// the tab, or opened DevTools over it. Every harness using the tab is told, in
+// the same words CDP would use, so it attaches again rather than talking to a
+// tab that no longer answers.
+chrome.debugger.onDetach.addListener((source, reason) => {
+  if (typeof source.tabId !== "number" || !attached.delete(source.tabId)) return;
+  updateBadge();
+  reply({ t: "cdp", method: "Inspector.detached", params: { reason }, sessionId: String(source.tabId) });
+});
+
+/** Let go of every tab now. The harness attaches again if it still needs one. */
+async function release() {
+  for (const tabId of [...attached]) {
+    attached.delete(tabId);
+    await chrome.debugger.detach({ tabId }).catch(() => {});
+    reply({ t: "cdp", method: "Inspector.detached", params: { reason: "released_by_user" }, sessionId: String(tabId) });
+  }
+  updateBadge();
+}
+
+async function describe() {
+  const tabs = [];
+  for (const tabId of attached) {
+    const tab = await chrome.tabs.get(tabId).catch(() => null);
+    if (!tab) continue;
+    const group = tab.groupId >= 0 && chrome.tabGroups ? await chrome.tabGroups.get(tab.groupId).catch(() => null) : null;
+    tabs.push({ tabId, title: tab.title ?? "", url: tab.url ?? "", group: group?.title || null, color: group?.color || null });
+  }
+  return { ...status, tabs };
+}
+
+// The popup asks; this answers. Nothing outside the extension can send these.
+chrome.runtime.onMessage.addListener((message, sender, respond) => {
+  if (sender.id !== chrome.runtime.id) return false;
+  if (message?.type === "servers") {
+    respond({ connected: status.connected, servers: status.servers });
+    return false;
+  }
+  if (message?.type === "status") {
+    void describe().then(respond);
+    return true;
+  }
+  if (message?.type === "release") {
+    void release().then(describe).then(respond);
+    return true;
+  }
+  if (message?.type === "reconnect") {
+    attempt = 0;
+    connect();
+    // Give a missing host the moment it takes to fail, so the popup shows why.
+    setTimeout(() => void describe().then(respond), 300);
+    return true;
+  }
+  return false;
+});
+
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === RECONNECT_ALARM && !port) connect();
+});
+chrome.alarms.create(RECONNECT_ALARM, { periodInMinutes: 1 });
+
+// Connect as soon as the worker starts, and again after Chrome restarts it.
+connect();
+chrome.runtime.onStartup.addListener(() => connect());
+chrome.runtime.onInstalled.addListener(() => connect());

package/extension/manifest.json

@@ -0,0 +1,39 @@
+{
+  "manifest_version": 3,
+  "name": "OHarness Browser Bridge",
+  "version": "0.5.0",
+  "description": "__MSG_extDescription__",
+  "default_locale": "en",
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7PX0T9J5HEXEmUKxtaNiqOTOXuwzCEq7EhsBuC4khICmOUKCN5Df+9WTMl/8jnGHeHtUPJRX/APQfrUfJqHCgENMhTv1IlAiQBHlAdsIXad4mjZ3VRz7KpFdajMNvZsGBeSjDU6hiOGngWxNiTztKyrBKMyS0yrmcUaGPl9Ji9QWgdV5VzdUz2xgFX57kFxYFHJmZ2K9HmqQ6n1ZFpTlGuziiFDEY94i2bIq0DOAozSsyUjBXxY2mJhAEcaWs2sG1Q+J6sNiQEdrYn3tNO9MZeWaXaTH0VfQeeXuBd98gHj7X4vCMd6MPFiPhDM0rDqBzvgZK/BvnOJTfAiC8sp/uQIDAQAB",
+  "permissions": [
+    "debugger",
+    "tabs",
+    "tabGroups",
+    "nativeMessaging",
+    "storage",
+    "alarms",
+    "sidePanel"
+  ],
+  "background": {
+    "service_worker": "background.js"
+  },
+  "action": {
+    "default_title": "OHarness Browser Bridge",
+    "default_popup": "popup.html",
+    "default_icon": {
+      "16": "icons/icon-16.png",
+      "32": "icons/icon-32.png",
+      "48": "icons/icon-48.png",
+      "128": "icons/icon-128.png"
+    }
+  },
+  "icons": {
+    "16": "icons/icon-16.png",
+    "32": "icons/icon-32.png",
+    "48": "icons/icon-48.png",
+    "128": "icons/icon-128.png"
+  },
+  "side_panel": {
+    "default_path": "sidepanel.html"
+  }
+}

package/extension/popup.css

@@ -0,0 +1,142 @@
+:root {
+  /* The app's own palette (packages/server/src/theme.ts), so the popup reads as
+     part of OHarness: ink for the button that does something, the brand lime
+     only for the harness being alive — here, driving tabs. */
+  --bg: #ffffff;
+  --fill: #f7f7f8;
+  --fill-strong: #00000012;
+  --text: #1a1a1a;
+  --muted: #6b7280;
+  --accent: #111827;
+  --accent-text: #ffffff;
+  --brand: #5e8c00;
+  --ok: #15803d;
+  --warn: #b45309;
+  --idle: #9ca3af;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0e1013;
+    --fill: #15171c;
+    --fill-strong: #ffffff1a;
+    --text: #e6e6e6;
+    --muted: #8b93a1;
+    --accent: #e5e7eb;
+    --accent-text: #0e1013;
+    --brand: #c6f432;
+    --ok: #4ade80;
+    --warn: #fbbf24;
+    --idle: #6b7280;
+  }
+}
+
+* { box-sizing: border-box; }
+
+body {
+  width: 320px;
+  margin: 0;
+  padding: 14px;
+  background: var(--bg);
+  color: var(--text);
+  font: 13px/1.45 system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+
+header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+
+h1 { margin: 0; font-size: 14px; font-weight: 600; }
+h2 { margin: 14px 0 6px; font-size: 12px; font-weight: 600; color: var(--muted); }
+p { margin: 0; }
+
+.status {
+  display: flex;
+  gap: 10px;
+  align-items: flex-start;
+  padding: 10px 12px;
+  border-radius: 10px;
+  background: var(--fill);
+}
+
+.dot {
+  flex: none;
+  width: 8px;
+  height: 8px;
+  margin-top: 6px;
+  border-radius: 50%;
+  background: var(--idle);
+}
+.status[data-state="driving"] .dot { background: var(--brand); }
+.status[data-state="ready"] .dot { background: var(--ok); }
+.status[data-state="waiting"] .dot { background: var(--idle); }
+.status[data-state="missing"] .dot { background: var(--warn); }
+
+.headline { font-weight: 600; }
+.detail { color: var(--muted); }
+
+.setup { margin-top: 12px; }
+.setup ol { margin: 6px 0 8px; padding-left: 18px; }
+.setup li { margin-bottom: 4px; }
+.error { color: var(--muted); font-size: 12px; word-break: break-word; margin-bottom: 8px; }
+
+code {
+  display: inline-block;
+  white-space: nowrap;
+  padding: 1px 5px;
+  border-radius: 5px;
+  background: var(--fill-strong);
+  font: 12px ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+ul { list-style: none; margin: 0; padding: 0; }
+
+.group {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin: 10px 0 4px;
+  font-size: 12px;
+  font-weight: 600;
+}
+.group:first-child { margin-top: 0; }
+.swatch { flex: none; width: 8px; height: 8px; border-radius: 3px; }
+
+.tab {
+  display: block;
+  width: 100%;
+  margin-bottom: 4px;
+  padding: 8px 10px;
+  border: 0;
+  border-radius: 8px;
+  background: var(--fill);
+  color: inherit;
+  text-align: left;
+  cursor: pointer;
+  font: inherit;
+}
+.tab:hover { background: var(--fill-strong); }
+.tab span { display: block; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+.tab .url { color: var(--muted); font-size: 11px; }
+
+button.primary,
+button.secondary {
+  width: 100%;
+  margin-top: 6px;
+  padding: 8px 10px;
+  border: 0;
+  border-radius: 8px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+}
+button.primary { background: var(--accent); color: var(--accent-text); }
+button.secondary { background: var(--fill-strong); color: var(--text); }
+button:focus-visible { outline: none; filter: brightness(1.08); }
+.tab:focus-visible { outline: none; background: var(--fill-strong); }
+
+.note { margin-top: 12px; color: var(--muted); font-size: 11px; }

package/extension/popup.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <link rel="stylesheet" href="popup.css">
+</head>
+<body>
+  <header>
+    <img src="icons/icon-32.png" width="24" height="24" alt="">
+    <h1 data-i18n="popupTitle"></h1>
+  </header>
+
+  <section class="status" id="status">
+    <span class="dot"></span>
+    <div>
+      <p class="headline" id="headline"></p>
+      <p class="detail" id="detail"></p>
+    </div>
+  </section>
+
+  <section id="setup" class="setup" hidden>
+    <p data-i18n="setupIntro"></p>
+    <ol>
+      <li data-i18n="setupDesktop"></li>
+      <li><span data-i18n="setupCli"></span> <code>oharness-browser-host install</code></li>
+    </ol>
+    <p class="error" id="error"></p>
+    <button id="retry" class="secondary" data-i18n="retry"></button>
+  </section>
+
+  <section id="driving" hidden>
+    <h2 data-i18n="controlledTabs"></h2>
+    <ul id="tabs"></ul>
+    <button id="release" class="primary" data-i18n="release"></button>
+  </section>
+
+  <button id="panel" class="secondary" type="button" data-i18n="openPanel"></button>
+
+  <p class="note" data-i18n="bannerNote"></p>
+
+  <script src="popup.js"></script>
+</body>
+</html>