webhelm 1.0.1 → 1.0.3

package/README.md

@@ -6,10 +6,10 @@
 
 | Repository | Contents | Updates |
 |---|---|---|
-| [`lalalic/webhelm`](https://github.com/lalalic/webhelm) | npm Runtime/CLI, Skill (`skills/webhelm`), Chrome Extension, tests | npm `webhelm@latest`; Skill source separately |
+| [`lalalic/webhelm`](https://github.com/lalalic/webhelm) | npm Runtime/CLI (including the Daemon-managed Chrome Extension), Skill (`skills/webhelm`), tests | npm `webhelm@latest`; Skill source separately |
 | [`lalalic/webhelm-actions`](https://github.com/lalalic/webhelm-actions) | Site manifests, ChatGPT/Z.ai/DeepSeek/XHS/etc. Actions | Git checkout at `~/.local/webhelm` |
 
-The npm package **does not include** the Skill or site Actions. The Skill's executable is a small `npx --yes webhelm@latest` launcher; its contents may update without a Runtime release.
+The npm package **does not include** the Skill or site Actions. The Skill's executable uses `npm exec --yes --package=webhelm@latest -- webhelm` to avoid inherited npm lifecycle variable conflicts; its contents may update without a Runtime release.
 
 ## Install and use
 
@@ -24,15 +24,16 @@ npx --yes webhelm@latest session exec SESSION_ID <<'JS'
 console.log(await snapshot());
 JS
 npx --yes webhelm@latest session stop SESSION_ID
+# Long-running worker managers: session heartbeat SESSION_ID every 60 seconds
 ```
 
-Use `npx skills add lalalic/webhelm --skill webhelm` to install agent guidance and the bundled Extension source. The Skill lives **in this repo** at `skills/webhelm/SKILL.md`.
+Use `npx skills add lalalic/webhelm --skill webhelm` to install agent guidance. The Extension is bundled with the npm Runtime and staged by WebHelm Daemon at `~/.local/webhelm/extension`. The Skill lives **in this repo** at `skills/webhelm/SKILL.md`. No Chrome Web Store publication or manual Extension installation is required.
 
 The Actions checkout is `~/.local/webhelm`, with site modules at `~/.local/webhelm/platforms`. Setup clones if absent, then reuses that checkout without discarding local modifications. Run `platform sync` for new commits. For a verified local Action fix, `platform publish --message "..."` tests, commits and pushes only the action changes to the separate repo.
 
 ## Architecture and compatibility
 
-The Runtime stores its managed Chrome profile, persistent FIFO queue, and IPC socket under `~/.config/webhelm/`. Run `webhelm migrate` with the legacy daemon and Chrome stopped to migrate existing `~/.config/browser-workspace/` data without dropping logins or queued turns. The command leaves a compatibility symlink for legacy maintenance scripts. Only one daemon is permitted to own the queue. A CLI package update does not kill a running daemon or close another agent's tabs; upgrade daemons when idle.
+The Runtime stores its managed Chrome profile, persistent FIFO queue, and IPC socket under `~/.config/webhelm/`. Run `webhelm migrate` with the legacy daemon and Chrome stopped to migrate existing `~/.config/browser-workspace/` data without dropping logins or queued turns. The command leaves a compatibility symlink for legacy maintenance scripts. Session idle GC runs on Node before new Session allocation (5 minutes without operations or explicit heartbeat). Managed tabs are navigated back to their Extension idle URL instead of closing CDP targets; the Extension does not use `tab.lastAccessed` GC. Only one daemon is permitted to own the queue. A CLI package update does not kill a running daemon or close another agent's tabs; upgrade daemons when idle.
 
 NeoY and Relay can continue using `webhelm` session commands, `result.stdout` JSON receipts, and `admin_helper` returned by `status`. An `admin_helper` inside the installed Skill is a stable connector to the same Node IPC socket. `webhelm capacity` replaces the legacy Python capacity probe.
 

package/package.json

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

package/runtime/chrome.mjs

@@ -3,7 +3,8 @@ import path from 'node:path';
 import net from 'node:net';
 import { spawn, execFileSync } from 'node:child_process';
 
-import { CONFIG_ROOT, PROFILE_DIR, requireMigratedConfig } from './config-paths.mjs';
+import { CONFIG_ROOT, PROFILE_DIR, OLD_PROFILE_DIR, requireMigratedConfig } from './config-paths.mjs';
+import { stageExtension } from './extension-manager.mjs';
 const ROOT = CONFIG_ROOT;
 const PROFILE = PROFILE_DIR;
 const STATE = path.join(ROOT, 'managed-chrome.json');
@@ -103,9 +104,12 @@ export async function ensureManagedChrome(){
     if(override)return {mode:'override',reused:true,endpoint:override,profile_dir:PROFILE};
     const port=await choosePort();
     const chrome=browserExecutable();
+    const extension=stageExtension();
     const log=fs.openSync(path.join(ROOT,'managed-chrome.log'),'a');
     fs.mkdirSync(PROFILE,{recursive:true});
     const child=spawn(chrome,[`--user-data-dir=${PROFILE}`,`--remote-debugging-port=${port}`,
+      '--disable-features=DisableLoadExtensionCommandLineSwitch',
+      `--load-extension=${extension.path}`,
       '--no-first-run','--no-default-browser-check','about:blank'],
       {detached:true,stdio:['ignore',log,log]});
     child.unref();

package/runtime/cli.mjs

@@ -7,7 +7,7 @@ import { randomUUID } from 'node:crypto';
 import { ensureDaemon, request, handle, SOCKET } from './node-daemon.mjs';
 import { PLATFORMS, listPlatforms, platformProfile, actionPath, validateConfig } from './platforms.mjs';
 import { ACTIONS_DIR, ensureActions, syncActions, publishActions } from './actions-repo.mjs';
-import { migrateConfig } from './migrate.mjs';
+import { migrateConfig, migrateChromeProfile } from './migrate.mjs';
 
 const ROOT = path.dirname(fileURLToPath(import.meta.url));
 const emit = value => console.log(JSON.stringify(value));
@@ -27,6 +27,7 @@ Usage:
   webhelm capacity [--workspace NAME]
   webhelm session start [--url URL]
   webhelm session list
+  webhelm session heartbeat SESSION_ID  # keep a working Session alive
   webhelm session exec SESSION_ID [--code-file FILE]   # JavaScript
   webhelm session stop SESSION_ID|--all
   webhelm platform list
@@ -98,7 +99,12 @@ async function runPlatform(args) {
 async function main(args = process.argv.slice(2)) {
   const [group, command] = args;
   if (!group || ['--help', '-h', 'help'].includes(group) || has(args, '--help') || has(args, '-h')) return help();
-  if (group === 'migrate') return emit(await migrateConfig());
+  if (group === 'migrate') {
+    await ensureActions(); // ~/.local/webhelm is the Actions Git checkout, never create an empty replacement.
+    const legacy=await migrateConfig();
+    const chrome=await migrateChromeProfile();
+    return emit({legacy,chrome});
+  }
   if (group === 'setup') {
     const repo=await ensureActions();
     const chrome=await ensureDaemon();
@@ -106,7 +112,7 @@ async function main(args = process.argv.slice(2)) {
   }
   if (group === 'status') {
     const daemon = await ensureDaemon();
-    return emit({version:'1.0.1', platform_dir:PLATFORMS, root:ROOT,
+    return emit({version:daemon.version, platform_dir:PLATFORMS, root:ROOT,
       cli:fileURLToPath(import.meta.url),
       admin_helper:process.env.WEBHELM_ADMIN_HELPER || (fs.existsSync(path.join(os.homedir(),'.agents/skills/webhelm/scripts/admin.mjs')) ? path.join(os.homedir(),'.agents/skills/webhelm/scripts/admin.mjs') : path.join(ROOT,'admin.mjs')),
       managed_chrome:daemon.managed_chrome,
@@ -126,6 +132,10 @@ async function main(args = process.argv.slice(2)) {
   if (group === 'session') {
     if (command === 'start') return emit(await request({op:'start', workspace:arg(args,'--workspace'), url:arg(args,'--url')}));
     if (command === 'list') return emit(await request({op:'list'}));
+    if (command === 'heartbeat') {
+      if (!args[2]) throw Error('session heartbeat requires SESSION_ID');
+      return emit(await request({op:'heartbeat',session_id:args[2]}));
+    }
     if (command === 'stop') return emit(await request(has(args,'--all') ? {op:'stop-all'} : {op:'stop',session_id:args[2]}));
     if (command === 'exec') {
       if (!args[2]) throw Error('session exec requires SESSION_ID');

package/runtime/config-paths.mjs

@@ -4,11 +4,18 @@ import fs from 'node:fs';
 
 export const CONFIG_ROOT = path.join(os.homedir(), '.config', 'webhelm');
 export const LEGACY_ROOT = path.join(os.homedir(), '.config', 'browser-workspace');
-export const PROFILE_DIR = path.join(CONFIG_ROOT, 'chrome');
+export const LOCAL_ROOT = path.join(os.homedir(), '.local', 'webhelm');
+export const OLD_PROFILE_DIR = path.join(CONFIG_ROOT, 'chrome');
+export const PROFILE_DIR = path.join(LOCAL_ROOT, 'chrome');
 export const RUNTIME_DIR = path.join(CONFIG_ROOT, 'runtime');
 
 // Avoid starting a second FIFO dispatcher or empty Chrome profile against legacy data.
 export function requireMigratedConfig() {
-  if (fs.existsSync(path.join(LEGACY_ROOT, 'chrome')) && !fs.existsSync(PROFILE_DIR))
+  if (fs.existsSync(path.join(LEGACY_ROOT, 'chrome')) && !fs.existsSync(OLD_PROFILE_DIR) && !fs.existsSync(PROFILE_DIR))
     throw Error(`Legacy Chrome profile exists at ${LEGACY_ROOT}. Stop old Chrome and WebHelm daemon, then run webhelm migrate.`);
+  if (fs.existsSync(OLD_PROFILE_DIR) && !fs.existsSync(PROFILE_DIR))
+    throw Error(`Chrome profile is still at ${OLD_PROFILE_DIR}. Stop active Sessions, WebHelm daemon and managed Chrome, then run webhelm migrate.`);
+  if (fs.existsSync(OLD_PROFILE_DIR) && fs.existsSync(PROFILE_DIR) &&
+      fs.realpathSync(OLD_PROFILE_DIR)!==fs.realpathSync(PROFILE_DIR))
+    throw Error('Two distinct WebHelm Chrome Profiles exist; refusing to use either until reconciled.');
 }

package/runtime/extension/manifest.json

@@ -0,0 +1,25 @@
+{
+  "manifest_version": 3,
+  "name": "Browser Workspace",
+  "version": "0.3.3",
+  "description": "Own named Chrome tab-group workspaces and lazy reusable tab pools for browser agents.",
+  "permissions": [
+    "storage",
+    "tabs",
+    "tabGroups",
+    "webNavigation",
+    "contextMenus"
+  ],
+  "host_permissions": [
+    "http://*/*",
+    "https://*/*"
+  ],
+  "background": {
+    "service_worker": "service-worker.mjs",
+    "type": "module"
+  },
+  "action": {
+    "default_title": "Browser Workspace"
+  },
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtovrqHYRxYDBSofmlykO8RDtsePhg8KV1fmq07nnhtbmYiNXAnIKrgRyLHeZv+cwm9DSgP5Ig7FDJ7Q6XrSi+Z1FpU6Y/SJkX5Rozo0oAJcX1ggoGD3vxpfHZThSSG/vRSnD8pH3XFf2nDUD7QP6GXc8dX9lN5pslRUNh1J4UCAOcu2UpPSsvpA+wPPTZr2JYzm3AevFXkQM6y0B+4exgw/Hy21ULST4nLWZihuCSu+gfWnftiTNzUPHtseRJcrpd0zT0R46d+OC+JRwXMVBpYSksDDtOXgERwMBSZf+vvskrEqYoXKN8Z9+Rrr7y9PTOvlwQioVLEDEjr9e7RIegQIDAQAB"
+}

package/runtime/extension/service-worker.mjs

@@ -0,0 +1,117 @@
+import { WorkspaceManager } from "./workspace-manager.mjs";
+
+const manager = new WorkspaceManager(chrome);
+const closingWindowIds = new Set();
+
+
+manager.restoreConfiguredWorkspaces().catch((error) => {
+  console.warn("Browser Workspace failed to restore configured workspaces", error);
+});
+
+const RELEASE_ALL_MENU_ID = "browser-workspace.release-all";
+
+async function ensureContextMenus() {
+  try {
+    await chrome.contextMenus.remove(RELEASE_ALL_MENU_ID);
+  } catch {
+    // Menu does not exist yet.
+  }
+  chrome.contextMenus.create({
+    id: RELEASE_ALL_MENU_ID,
+    title: "Release all tabs",
+    contexts: ["action"],
+  });
+}
+
+chrome.runtime.onInstalled.addListener(() => {
+  ensureContextMenus().catch((error) => {
+    console.warn("Browser Workspace failed to create extension menu", error);
+  });
+});
+
+chrome.runtime.onStartup.addListener(() => {
+  ensureContextMenus().catch((error) => {
+    console.warn("Browser Workspace failed to create extension menu", error);
+  });
+});
+
+ensureContextMenus().catch((error) => {
+  console.warn("Browser Workspace failed to initialize extension menu", error);
+});
+
+chrome.contextMenus.onClicked.addListener((info) => {
+  if (info.menuItemId !== RELEASE_ALL_MENU_ID) return;
+  manager.releaseAll().catch((error) => {
+    console.warn("Browser Workspace failed to release all tabs", error);
+  });
+});
+
+globalThis.browserWorkspaceManagerRpc = async (request) => {
+  try {
+    return { ok: true, result: await manager.rpc(request) };
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        message: error?.message || String(error),
+        name: error?.name || "Error",
+      },
+    };
+  }
+};
+
+chrome.runtime.onMessage.addListener((request, _sender, sendResponse) => {
+  globalThis.browserWorkspaceManagerRpc(request).then(sendResponse);
+  return true;
+});
+
+chrome.tabs.onCreated.addListener((tab) => {
+  manager.inheritWorkspaceForCreatedTab(tab).catch((error) => {
+    console.warn("Browser Workspace failed to inherit child tab group", error);
+  });
+
+  setTimeout(() => {
+    manager.reconcileCreatedTab(tab.id).catch((error) => {
+      if (!/No tab with id|Invalid tab ID/i.test(String(error?.message || error))) {
+        console.warn("Browser Workspace failed delayed created-tab reconciliation", error);
+      }
+    });
+  }, 150);
+});
+
+chrome.webNavigation.onCreatedNavigationTarget.addListener((details) => {
+  manager.inheritNavigationTarget(details).catch((error) => {
+    console.warn("Browser Workspace failed to inherit navigation target", error);
+  });
+});
+
+chrome.tabs.onUpdated.addListener((_tabId, changeInfo, tab) => {
+  if (!Object.prototype.hasOwnProperty.call(changeInfo, "groupId")) return;
+  manager.inheritWorkspaceForCreatedTab(tab).catch((error) => {
+    console.warn("Browser Workspace failed to reconcile tab group ownership", error);
+  });
+});
+
+chrome.tabs.onActivated.addListener((activeInfo) => {
+  manager.noteActivatedTab(activeInfo).catch((error) => {
+    console.warn("Browser Workspace failed to record active tab context", error);
+  });
+});
+
+chrome.tabs.onRemoved.addListener((_tabId, removeInfo) => {
+  if (!removeInfo?.isWindowClosing) return;
+  closingWindowIds.add(removeInfo.windowId);
+  setTimeout(() => closingWindowIds.delete(removeInfo.windowId), 1000);
+});
+
+chrome.tabGroups.onRemoved.addListener((group) => {
+  // Chrome also emits onRemoved while moving a group between windows, and
+  // while a whole window is closing. Defer one turn so a moved group can
+  // reappear, and preserve persisted workspaces across normal window closes.
+  setTimeout(() => {
+    if (closingWindowIds.has(group.windowId)) return;
+    manager.removeDeletedGroup(group).catch((error) => {
+      console.warn("Browser Workspace failed to remove deleted workspace", error);
+    });
+  }, 100);
+});