webhelm 1.0.7 → 1.0.9

package/README.md

@@ -35,7 +35,7 @@ The daemon-managed Chrome Extension is installed from the npm Runtime and does n
 
 The popup has a confirmation step to stop one Session, clear Sessions in one workspace, or clear Sessions across all workspaces. These actions are executed by the same Node daemon as the CLI, over the existing CDP-backed Extension RPC. No shell access or HTTP listener is granted to the Extension. The persistent ChatGPT queue is not deleted, and queued work may create new Sessions afterward.
 
-New installations use the default Chrome tab group `WebHelm` and the idle page `helm.html`. Legacy `Harness` default groups migrate only when their tabs are idle. Custom workspace names are unchanged; the old `workspace.html` path and lease titles remain readable until their Sessions finish. Closing an allocated Session returns its managed tabs to the idle page, retaining physical Chrome targets, while unleased popup children are closed. Do not manually remove active managed tabs.
+New installations use the default Chrome tab group `WebHelm` and the idle page `helm.html`. Idle URLs use only `workspace` and `role=idle`; Lease URLs use Chrome's actual `tabId` for initial CDP target discovery. There is no separate slot identity. The default `WebHelm` tab group is placed at the first position after pinned tabs when created or restored, while Session allocation does not override later user rearrangement. Chrome-saved tab group shortcuts in the bookmarks bar are separate from active groups and cannot safely be deduplicated through the Extension API. Legacy `Harness` default groups migrate only when their tabs are idle. Custom workspace names are unchanged; the old `workspace.html` path and lease titles remain readable until their Sessions finish. Closing an allocated Session returns its managed tabs to the idle page, retaining physical Chrome targets, while unleased popup children are closed. Do not manually remove active managed tabs.
 
 For a real browser integration check on macOS, run `node test/e2e/extension-control.e2e.mjs`; it creates a temporary isolated Chrome profile and daemon and does not touch the current production Sessions.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webhelm",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Agent browser automation in a visible managed Chrome with persistent JavaScript sessions",
   "type": "module",
   "bin": {

package/runtime/extension/helm.html

@@ -72,7 +72,7 @@
     .description { margin: 16px 0 24px; color: var(--subtle); }
     dl {
       display: grid;
-      grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+      grid-template-columns: minmax(0, 1fr);
       gap: 16px;
       margin: 0;
       padding: 18px 0;
@@ -117,7 +117,6 @@
     <p class="description" id="description">This page belongs to WebHelm's managed browser workspace.</p>
     <dl>
       <div><dt>Workspace</dt><dd id="workspace-name">—</dd></div>
-      <div><dt>Tab slot</dt><dd id="slot-number">—</dd></div>
     </dl>
     <footer id="help-text">Tab status does not indicate whether the daemon is connected.</footer>
   </main>

package/runtime/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "WebHelm",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Own named Chrome tab-group workspaces and lazy reusable tab pools for browser agents.",
   "permissions": [
     "storage",

package/runtime/extension/workspace-manager.mjs

@@ -18,8 +18,8 @@ export function normalizePoolSize(value, fallback = 8) {
   return number;
 }
 
-function queryString(workspace, slot) {
-  return new URLSearchParams({ workspace, role: "idle", slot: String(slot) }).toString();
+function queryString(workspace) {
+  return new URLSearchParams({ workspace, role: "idle" }).toString();
 }
 
 export class WorkspaceManager {
@@ -41,8 +41,8 @@ export class WorkspaceManager {
     if (Number.isInteger(id)) this.ownedTabIds.add(id);
   }
 
-  idleUrl(workspace, slot) {
-    return this.chrome.runtime.getURL(`helm.html?${queryString(workspace, slot)}`);
+  idleUrl(workspace) {
+    return this.chrome.runtime.getURL(`helm.html?${queryString(workspace)}`);
   }
 
   identityTitle(tabId) {
@@ -53,7 +53,7 @@ export class WorkspaceManager {
     const query = new URLSearchParams({
       workspace,
       role: "lease",
-      slot: String(tabId),
+      tabId: String(tabId),
     }).toString();
     return this.chrome.runtime.getURL(`helm.html?${query}`);
   }
@@ -67,7 +67,7 @@ export class WorkspaceManager {
       return {
         workspace: parsed.searchParams.get("workspace") || "",
         role: parsed.searchParams.get("role") || "",
-        slot: parsed.searchParams.get("slot") || "",
+        tabId: parsed.searchParams.get("tabId") || "",
       };
     } catch {
       return null;
@@ -128,6 +128,22 @@ export class WorkspaceManager {
     return await this.chrome.tabs.query({ groupId });
   }
 
+  // Only position the default group when it is created, migrated or restored.
+  // Never move it during routine Session allocation or periodic health checks,
+  // since the user may intentionally reorder the tab strip.
+  async positionDefaultGroupFirst(groupId, name) {
+    if (name !== "WebHelm") return false;
+    const groupTabs = await this.groupTabs(groupId);
+    if (!groupTabs.length) return false;
+    const windowId = groupTabs[0].windowId;
+    const windowTabs = await this.chrome.tabs.query({windowId});
+    const firstUnpinnedIndex = windowTabs.filter(tab => tab.pinned).length;
+    const firstGroupIndex = Math.min(...groupTabs.map(tab => tab.index));
+    if (firstGroupIndex === firstUnpinnedIndex) return false;
+    await this.chrome.tabGroups.move(groupId, {index: firstUnpinnedIndex});
+    return true;
+  }
+
   tabUrl(tab) {
     return String(tab?.pendingUrl || tab?.url || "");
   }
@@ -371,12 +387,13 @@ export class WorkspaceManager {
     // Chrome groups are created by grouping a tab. Keep one seed tab so the
     // workspace has an identity, then grow the physical pool on demand.
     const created = [await this.chrome.tabs.create({
-      url: this.idleUrl(name, 0),
+      url: this.idleUrl(name),
       active: false,
     })];
     for (const tab of created) this.markOwned(tab.id);
     const groupId = await this.chrome.tabs.group({ tabIds: created.map((tab) => tab.id) });
     await this.chrome.tabGroups.update(groupId, { title: name, collapsed: true });
+    await this.positionDefaultGroupFirst(groupId, name);
     for (const tab of created) await this.waitForIdleTab(tab.id, name);
     return await this.status(name);
   }
@@ -455,6 +472,8 @@ export class WorkspaceManager {
     for (const name of Object.keys(config.workspaces || {}).sort()) {
       restored.push(await this.ensureWorkspace(name));
     }
+    const defaultGroup = restored.find(item => item.name === "WebHelm" && item.initialized);
+    if (defaultGroup) await this.positionDefaultGroupFirst(defaultGroup.groupId, "WebHelm");
     return { workspaces: restored };
   }
 
@@ -489,9 +508,12 @@ export class WorkspaceManager {
       for (const tab of tabs) this.markOwned(tab.id);
       if (group) await this.chrome.tabGroups.update(group.id, {title: newName});
       for (const tab of tabs) {
-        await this.chrome.tabs.update(tab.id, {url: this.idleUrl(newName, tab.id), active: false});
+        await this.chrome.tabs.update(tab.id, {url: this.idleUrl(newName), active: false});
         updated.push(tab);
       }
+      // Position before committing the new config so move failures still
+      // unwind the legacy migration coherently in the catch block.
+      if (group) await this.positionDefaultGroupFirst(group.id, newName);
       config.workspaces[newName] = config.workspaces[oldName];
       delete config.workspaces[oldName];
       await this.saveConfig(config);
@@ -538,7 +560,7 @@ export class WorkspaceManager {
     let tab = idle[0];
     if (!tab) {
       tab = await this.chrome.tabs.create({
-        url: this.idleUrl(normalizedName, tabs.length),
+        url: this.idleUrl(normalizedName),
         active: false,
       });
       this.markOwned(tab.id);
@@ -557,7 +579,7 @@ export class WorkspaceManager {
       tabId: updated.id,
       identityTitle,
       identityUrl,
-      idleUrl: this.idleUrl(normalizedName, updated.id),
+      idleUrl: this.idleUrl(normalizedName),
       active: Boolean(updated.active),
     };
   }
@@ -579,7 +601,7 @@ export class WorkspaceManager {
     let tab = idle[0];
     if (!tab) {
       tab = await this.chrome.tabs.create({
-        url: this.idleUrl(normalizedName, tabs.length),
+        url: this.idleUrl(normalizedName),
         active: false,
       });
       // Group reconciliation can fire before the extension idle URL is visible.
@@ -614,7 +636,7 @@ export class WorkspaceManager {
     } else {
       try {
         await this.chrome.tabs.update(wanted, {
-          url: this.idleUrl(normalizedName, wanted),
+          url: this.idleUrl(normalizedName),
           active: false,
         });
         await this.waitForIdleTab(wanted, normalizedName);
@@ -623,7 +645,7 @@ export class WorkspaceManager {
         // the extension idle page. Preserve pool capacity by creating a clean
         // idle replacement in the same group before removing the stale tab.
         const replacement = await this.chrome.tabs.create({
-          url: this.idleUrl(normalizedName, wanted),
+          url: this.idleUrl(normalizedName),
           active: false,
         });
         this.markOwned(replacement.id);

package/runtime/extension/workspace-page.mjs

@@ -1,12 +1,13 @@
 const params = new URLSearchParams(location.search);
 const workspace = params.get("workspace") || "";
 const role = params.get("role") || "";
-const slot = params.get("slot") || "";
-const validSlot = /^\d+$/.test(slot);
+// A lease carries the actual Chrome tabId for one-time CDP target discovery.
+const tabId = params.get("tabId") || "";
+const validTabId = /^\d+$/.test(tabId);
 
 // Keep this exact lease title: WebHelm's tab identity protocol depends on it.
-document.title = role === "lease" && validSlot
-  ? `${location.pathname.endsWith("/workspace.html") ? "__BW_TAB_" : "__WEBHELM_TAB_"}${slot}__`
+document.title = role === "lease" && validTabId
+  ? `${location.pathname.endsWith("/workspace.html") ? "__BW_TAB_" : "__WEBHELM_TAB_"}${tabId}__`
   : role === "idle" && workspace
     ? "WebHelm · Idle"
     : "WebHelm";
@@ -17,13 +18,12 @@ const setText = (id, value) => {
 };
 
 setText("workspace-name", workspace || "Not assigned");
-setText("slot-number", validSlot ? slot : "—");
 
 if (role === "idle" && workspace) {
   setText("status-label", "Idle · Awaiting next task");
   setText("description", "This tab is in the WebHelm pool and will be reused automatically when a task needs it.");
   setText("help-text", "No action required. Leave this tab open. This status describes the tab, not daemon connectivity.");
-} else if (role === "lease" && validSlot && workspace) {
+} else if (role === "lease" && validTabId && workspace) {
   setText("status-label", "Reserved for a task");
   setText("description", "WebHelm has assigned this tab to a browser session.");
 }

package/runtime/node-daemon.mjs

@@ -65,7 +65,7 @@ async function acquireIdentityLease(session) {
       // Do not navigate/release a tab still owned by another Session.
       throw Error('Workspace extension returned a target already owned by another Session');
     }
-    lease.idleUrl ||= idleUrlFromIdentity(lease.identityUrl, lease.tabId);
+    lease.idleUrl ||= idleUrlFromIdentity(lease.identityUrl);
     return {lease,targetId};
   });
 }

package/runtime/session-lifecycle.mjs

@@ -6,13 +6,16 @@ export function staleSession(session, now = Date.now(), ttl = SESSION_IDLE_MS) {
     now - session.last_used_at >= ttl;
 }
 
-export function idleUrlFromIdentity(identityUrl, tabId) {
+export function idleUrlFromIdentity(identityUrl) {
   const url = new URL(identityUrl);
-  if (url.protocol !== 'chrome-extension:' || !['/workspace.html','/helm.html'].includes(url.pathname)) {
+  if (url.protocol !== 'chrome-extension:' || !['/workspace.html', '/helm.html'].includes(url.pathname)) {
     throw new Error('invalid extension identity URL');
   }
-  url.searchParams.set('role', 'idle');
-  url.searchParams.set('slot', String(tabId));
+  const workspace = url.searchParams.get('workspace');
+  if (!workspace) throw new Error('missing workspace in extension identity URL');
+  // Construct the canonical idle URL from scratch. Never copy lease identity
+  // or unrelated query parameters into an idle tab.
+  url.search = new URLSearchParams({workspace, role:'idle'}).toString();
   return url.href;
 }