webhelm 1.0.3 → 1.0.5

package/package.json

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

package/runtime/chrome.mjs

@@ -23,10 +23,19 @@ function alive(pid) {
   try { if(!pid) return false;process.kill(Number(pid), 0);return true; }
   catch {return false;}
 }
+function matchesManagedChromeProcess(pid,port) {
+  if(process.platform==='win32')return alive(pid); // Windows command-line discovery needs a separate provider.
+  try {
+    const command=execFileSync('ps',['-p',String(pid),'-o','command='],{encoding:'utf8',timeout:2500});
+    return command.includes(`--user-data-dir=${PROFILE}`) &&
+      command.includes(`--remote-debugging-port=${port}`) &&
+      !command.includes('--type=');
+  } catch{return false;}
+}
 async function fromState() {
   let state;
   try { state=JSON.parse(fs.readFileSync(STATE, 'utf8')); } catch { return null; }
-  if (state?.pid && Number.isInteger(state.port) && alive(state.pid) && await endpointLive(state.port)) return state;
+  if (state?.pid && Number.isInteger(state.port) && matchesManagedChromeProcess(state.pid,state.port) && await endpointLive(state.port)) return state;
   return null;
 }
 async function discover() {
@@ -39,7 +48,7 @@ async function discover() {
     const match=line.match(/^\s*(\d+)\s+.*?--remote-debugging-port=(\d+)/);
     if (!match) continue;
     const [pid,port]=match.slice(1).map(Number);
-    if (!alive(pid) || !await endpointLive(port)) continue;
+    if (!matchesManagedChromeProcess(pid,port) || !await endpointLive(port)) continue;
     const state={pid,port,profile_dir:PROFILE,chrome_path:line.slice(line.search(/\S/)).replace(/^\d+\s*/, '').split(' --user-data-dir=')[0]};
     fs.writeFileSync(STATE,JSON.stringify(state,null,2));
     return state;
@@ -91,6 +100,24 @@ async function lockOwnership(fn) {
   try {return await fn();}
   finally {fs.closeSync(fd);try {fs.unlinkSync(LOCK);}catch{}}
 }
+export function chromeMajorFromVersion(versionText){
+  const match=String(versionText).match(/(?:Chrome|Chromium)\s+(?:for Testing\s+)?(\d+)\./);
+  const major=match?Number(match[1]):NaN;
+  if(!Number.isSafeInteger(major)||major<50)throw Error(`Cannot determine managed Chrome version: ${versionText}`);
+  return major;
+}
+function chromeMajor(chromePath){
+  return chromeMajorFromVersion(execFileSync(chromePath,['--version'],{encoding:'utf8',timeout:5000}).trim());
+}
+export function chromeLaunchArgs(profile,port,extensionPath,major){
+  const args=[`--user-data-dir=${profile}`,`--remote-debugging-port=${port}`];
+  // Chrome 138 can load unpacked extensions with a compatibility flag.
+  // Chrome 139+ must rely on Extensions.loadUnpacked through CDP instead:
+  // passing --load-extension can leave a stale, non-running extension entry.
+  if(major<=138)args.push('--disable-features=DisableLoadExtensionCommandLineSwitch',`--load-extension=${extensionPath}`);
+  args.push('--no-first-run','--no-default-browser-check','about:blank');
+  return args;
+}
 export async function ensureManagedChrome(){
   // Explicit CDP endpoints also support hermetic mock-browser tests.
   const specified=process.env.WEBHELM_CDP_URL;
@@ -107,10 +134,7 @@ export async function ensureManagedChrome(){
     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'],
+    const child=spawn(chrome,chromeLaunchArgs(PROFILE,port,extension.path,chromeMajor(chrome)),
       {detached:true,stdio:['ignore',log,log]});
     child.unref();
     fs.closeSync(log);

package/runtime/cli.mjs

@@ -8,6 +8,7 @@ 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, migrateChromeProfile } from './migrate.mjs';
+import { installLoginGuard } from './login-guard.mjs';
 
 const ROOT = path.dirname(fileURLToPath(import.meta.url));
 const emit = value => console.log(JSON.stringify(value));
@@ -108,14 +109,15 @@ async function main(args = process.argv.slice(2)) {
   if (group === 'setup') {
     const repo=await ensureActions();
     const chrome=await ensureDaemon();
-    return emit({status:'ready',...repo,daemon_pid:chrome.pid,managed_chrome:chrome.managed_chrome});
+    const login_guard=installLoginGuard();
+    return emit({status:'ready',...repo,daemon_pid:chrome.pid,managed_chrome:chrome.managed_chrome,login_guard});
   }
   if (group === 'status') {
     const daemon = await ensureDaemon();
     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,
+      managed_chrome:daemon.managed_chrome, chrome_guard:daemon.chrome_guard,
       daemon:{running:true, pid:daemon.pid, session_count:daemon.session_count, queue_paused:daemon.queue_paused, socket:SOCKET}});
   }
   if (group === 'capacity') {

package/runtime/login-guard.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+
+const LABEL='com.lalalic.webhelm.keepalive';
+const escapeXml=s=>String(s).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;'}[c]));
+export function loginGuardDefinition(home=os.homedir()) {
+  const cli=path.join(home,'.local/bin/webhelm');
+  const environment=[path.join(home,'.local/bin'),path.join(home,'.local/opt/node22/bin'),
+    '/opt/homebrew/bin','/usr/local/bin','/usr/bin','/bin'].join(':');
+  // The short-lived status check starts a missing daemon, and is a no-op if
+  // it already owns the IPC socket. Node daemon independently repairs Chrome.
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${LABEL}</string>\n<key>ProgramArguments</key><array><string>${escapeXml(cli)}</string><string>status</string></array>\n<key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(environment)}</string><key>HOME</key><string>${escapeXml(home)}</string></dict>\n<key>RunAtLoad</key><true/>\n<key>StartInterval</key><integer>300</integer>\n<key>StandardOutPath</key><string>/dev/null</string>\n<key>StandardErrorPath</key><string>/dev/null</string>\n</dict></plist>\n`;
+}
+export function installLoginGuard({home=os.homedir(), platform=process.platform, apply=true}={}){
+  if(platform!=='darwin')return {status:'unsupported',label:LABEL};
+  const cli=path.join(home,'.local/bin/webhelm');
+  if(!fs.existsSync(cli))return {status:'skipped',reason:'webhelm Skill launcher missing',label:LABEL};
+  const dest=path.join(home,'Library/LaunchAgents',`${LABEL}.plist`);
+  const content=loginGuardDefinition(home);
+  fs.mkdirSync(path.dirname(dest),{recursive:true});
+  if(fs.existsSync(dest)){
+    const old=fs.readFileSync(dest,'utf8');
+    if(!old.includes(`<string>${LABEL}</string>`))throw Error(`Refusing to replace unrelated LaunchAgent: ${dest}`);
+  }
+  const updated=!fs.existsSync(dest)||fs.readFileSync(dest,'utf8')!==content;
+  if(updated){
+    const staging=dest+`.${process.pid}.tmp`;
+    fs.writeFileSync(staging,content,{mode:0o600});fs.renameSync(staging,dest);
+  }
+  const service=`gui/${process.getuid()}/${LABEL}`;
+  if(!apply)return {status:'staged',path:dest,updated,label:LABEL};
+  try {
+    execFileSync('launchctl',['print',service],{timeout:5000,stdio:'ignore'});
+    if(updated){
+      execFileSync('launchctl',['bootout',service],{timeout:5000,stdio:'ignore'});
+      execFileSync('launchctl',['bootstrap',`gui/${process.getuid()}`,dest],{timeout:5000,stdio:'ignore'});
+    }
+    return {status:'active',path:dest,updated,label:LABEL};
+  } catch(error){
+    try{
+      execFileSync('launchctl',['bootstrap',`gui/${process.getuid()}`,dest],{timeout:5000,stdio:'ignore'});
+      return {status:'active',path:dest,updated,label:LABEL};
+    }catch(e){return {status:'staged_not_loaded',path:dest,label:LABEL,reason:e.message};}
+  }
+}

package/runtime/managed-chrome-guard.mjs

@@ -0,0 +1,21 @@
+// A daemon-owned, non-overlapping health loop. Do not use a separate worker or
+// close a user's Chrome windows to recover the managed browser.
+export function createManagedChromeGuard(check, {intervalMs=15000, onError=()=>{}}={}) {
+  if(typeof check!=='function')throw TypeError('health check must be a function');
+  let timer=null, running=false, stopped=false;
+  let last={status:'not_checked'};
+  const tick=async()=>{
+    if(running||stopped)return last;
+    running=true;
+    try{last={status:'healthy',...(await check())};}
+    catch(error){last={status:'degraded',error:String(error?.message||error)};onError(error);}
+    finally{running=false;}
+    return last;
+  };
+  return {
+    tick,
+    start(){if(timer)return;stopped=false;timer=setInterval(()=>{void tick()},intervalMs);timer.unref?.();void tick()},
+    stop(){stopped=true;if(timer)clearInterval(timer);timer=null},
+    status(){return {...last}}
+  };
+}

package/runtime/node-daemon.mjs

@@ -11,6 +11,7 @@ import { ChatGPTQueue } from './chatgpt/chatgpt-queue.mjs';
 import { idleUrlFromIdentity, sameIdleUrl, staleSession } from './session-lifecycle.mjs';
 import { ensureManagedChrome } from './chrome.mjs';
 import { ensureExtensionLoaded } from './extension-manager.mjs';
+import { createManagedChromeGuard } from './managed-chrome-guard.mjs';
 import { PROFILE_DIR, RUNTIME_DIR, requireMigratedConfig } from './config-paths.mjs';
 
 const ROOT = path.dirname(fileURLToPath(import.meta.url));
@@ -121,6 +122,42 @@ async function connectBrowser() {
   finally{connectingBrowser=null;}
 }
 
+// The daemon owns both the managed Chrome process and the default Harness
+// group. Chrome auto-updates can terminate the browser while the Node daemon
+// survives; an RPC-only health check cannot recover that loss.
+async function guardManagedChrome(){
+  if(shuttingDown || process.env.WEBHELM_CDP_URL || process.env.WEBHELM_NO_PROFILE_EXTENSION_PROBE==='1')
+    return {skipped:true};
+  const actual=await ensureManagedChrome();
+  if(!browserWs || browserWs.closed || managedChrome?.pid!==actual.pid || managedChrome?.endpoint!==actual.endpoint){
+    const old=browserWs;
+    browserWs=null;connected=false;debuggerSession=null;
+    if(old && !old.closed)old.ws?.close();
+    await connectBrowser();
+  }
+  managedChrome=actual;
+  // Session leasing also creates missing workspaces. Serialize this short
+  // identity transaction with session start so one group is created, not two.
+  const state=await leaseMutex('Harness').run(async()=>{
+    let current;
+    try {current=await extensionCall(null,'workspace.status',{name:'Harness'});}
+    catch(error){
+      if(sessions.size)throw error; // Never hot reload an Extension used by active Sessions.
+      const browser=await connectBrowser();
+      await ensureExtensionLoaded(browser);
+      current=await extensionCall(null,'workspace.status',{name:'Harness'});
+    }
+    if(!current?.initialized || !Number.isInteger(current.physicalTabs) || current.physicalTabs<1)
+      current=await extensionCall(null,'workspace.ensure',{name:'Harness'});
+    return current;
+  });
+  return {managed_chrome_pid:actual.pid,group_id:state.groupId,physical_tabs:state.physicalTabs};
+}
+const managedChromeGuard=createManagedChromeGuard(guardManagedChrome,{
+  intervalMs:Number(process.env.WEBHELM_CHROME_GUARD_INTERVAL_MS||15000),
+  onError:error=>console.warn(`WebHelm managed Chrome health check: ${error.message}`),
+});
+
 function adoptPopup(info){if(info?.type!=='page'||!info.openerId)return;const owner=targets.get(info.openerId);if(owner){owner.targets.add(info.targetId);targets.set(info.targetId,owner)}}
 async function attach(s,targetId,b=null){b ||= await connectBrowser();const {sessionId}=await b.send('Target.attachToTarget',{targetId,flatten:true});s.targets.add(targetId);s.attachments.set(targetId,sessionId);targets.set(targetId,s);for(const d of ['Page','DOM','Runtime','Network'])await b.send(`${d}.enable`,{},sessionId);for(const dispose of s.eventDisposers?.get(targetId)||[])dispose();const removers=[];for(const method of ['Page.loadEventFired','Page.domContentEventFired','Page.javascriptDialogOpening','Page.javascriptDialogClosed','Runtime.exceptionThrown','Network.requestWillBeSent','Network.responseReceived'])removers.push(b.on(method,(params,owner)=>{if(owner===sessionId){if(s.events.length>=500)s.events.shift();s.events.push({method,params,session_id:sessionId,target_id:targetId})}}));s.eventDisposers?.set(targetId,removers);return sessionId}
 function sidFor(s,targetId=s.targetId){const sid=s.attachments.get(targetId);if(!sid)throw new Error(`target ${targetId} is not attached to this session`);return sid}
@@ -538,7 +575,7 @@ async function runPlatform(req) {
     self_heal_capable:!auto,result};
 }
 
-export async function handle(req){switch(req.op){case'ping':return {ok:true,pid:process.pid,version:PACKAGE_VERSION,queue_paused:process.env.WEBHELM_CHATGPT_QUEUE_PAUSED==='1',session_count:sessions.size,managed_chrome:managedChrome||{profile_dir:PROFILE_DIR, endpoint:process.env.WEBHELM_CDP_URL||'http://127.0.0.1:9222',reused:true}};case'heartbeat':return heartbeatSession(req.session_id);case'list':return {session_count:sessions.size,sessions:[...sessions.values()].map(s=>({session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,last_used_at:s.last_used_at}))};case'start':return createSession(req);case'exec':return execute(req);case'stop':return stopSession(req.session_id);case'stop-all':{const stopped=[];for(const id of [...sessions.keys()])stopped.push(await stopSession(id));return {stopped_count:stopped.length,error_count:0,stopped,errors:[]}}case'capacity':return workspaceCapacity(req);case'workspace-create':case'workspace-delete':return workspaceOp(req);case'chatgpt-new-turn-enqueue':return getChatGPTQueue().enqueue(req.config);case'platform-run':return runPlatform(req);default:throw Error(`unknown op: ${req.op}`)}}
+export async function handle(req){switch(req.op){case'ping':return {ok:true,pid:process.pid,version:PACKAGE_VERSION,queue_paused:process.env.WEBHELM_CHATGPT_QUEUE_PAUSED==='1',session_count:sessions.size,managed_chrome:managedChrome||{profile_dir:PROFILE_DIR, endpoint:process.env.WEBHELM_CDP_URL||'http://127.0.0.1:9222',reused:true},chrome_guard:managedChromeGuard.status()};case'heartbeat':return heartbeatSession(req.session_id);case'list':return {session_count:sessions.size,sessions:[...sessions.values()].map(s=>({session_id:s.session_id,workspace:s.workspace,target_id:s.targetId,last_used_at:s.last_used_at}))};case'start':return createSession(req);case'exec':return execute(req);case'stop':return stopSession(req.session_id);case'stop-all':{const stopped=[];for(const id of [...sessions.keys()])stopped.push(await stopSession(id));return {stopped_count:stopped.length,error_count:0,stopped,errors:[]}}case'capacity':return workspaceCapacity(req);case'workspace-create':case'workspace-delete':return workspaceOp(req);case'chatgpt-new-turn-enqueue':return getChatGPTQueue().enqueue(req.config);case'platform-run':return runPlatform(req);default:throw Error(`unknown op: ${req.op}`)}}
 function serve(conn) {
   let buffer = '';
   conn.setEncoding('utf8');
@@ -556,7 +593,7 @@ function serve(conn) {
   });
 }
 
-async function main(){fs.mkdirSync(RUNTIME,{recursive:true,mode:0o700});let lockfd;try{lockfd=fs.openSync(LOCK,'wx',0o600);fs.writeFileSync(lockfd,String(process.pid))}catch{throw Error(`Node pilot lock exists: ${LOCK}`)}if(fs.existsSync(SOCKET)){try{const c=net.createConnection(SOCKET);await new Promise((res,rej)=>{c.once('connect',res);c.once('error',rej)});c.destroy();fs.closeSync(lockfd);fs.unlinkSync(LOCK);throw Error(`Node daemon socket already active: ${SOCKET}`)}catch(e){if(e.message.includes('already active'))throw e;fs.unlinkSync(SOCKET)}}socket=net.createServer(serve);await new Promise((res,rej)=>socket.listen(SOCKET,res).once('error',rej));fs.chmodSync(SOCKET,0o600);connectBrowser().catch(()=>{});getChatGPTQueue();const cleanup=async()=>{if(shuttingDown)return;shuttingDown=true;if(chatgptQueue)await chatgptQueue.shutdown().catch(()=>{});await handle({op:'stop-all'}).catch(()=>{});socket?.close();try{if(fs.existsSync(SOCKET))fs.unlinkSync(SOCKET)}catch{}try{fs.closeSync(lockfd);fs.unlinkSync(LOCK)}catch{}process.exit(0)};process.on('SIGTERM',cleanup);process.on('SIGINT',cleanup)}
+async function main(){fs.mkdirSync(RUNTIME,{recursive:true,mode:0o700});let lockfd;try{lockfd=fs.openSync(LOCK,'wx',0o600);fs.writeFileSync(lockfd,String(process.pid))}catch{throw Error(`Node pilot lock exists: ${LOCK}`)}if(fs.existsSync(SOCKET)){try{const c=net.createConnection(SOCKET);await new Promise((res,rej)=>{c.once('connect',res);c.once('error',rej)});c.destroy();fs.closeSync(lockfd);fs.unlinkSync(LOCK);throw Error(`Node daemon socket already active: ${SOCKET}`)}catch(e){if(e.message.includes('already active'))throw e;fs.unlinkSync(SOCKET)}}socket=net.createServer(serve);await new Promise((res,rej)=>socket.listen(SOCKET,res).once('error',rej));fs.chmodSync(SOCKET,0o600);connectBrowser().catch(()=>{});managedChromeGuard.start();getChatGPTQueue();const cleanup=async()=>{if(shuttingDown)return;shuttingDown=true;managedChromeGuard.stop();if(chatgptQueue)await chatgptQueue.shutdown().catch(()=>{});await handle({op:'stop-all'}).catch(()=>{});socket?.close();try{if(fs.existsSync(SOCKET))fs.unlinkSync(SOCKET)}catch{}try{fs.closeSync(lockfd);fs.unlinkSync(LOCK)}catch{}process.exit(0)};process.on('SIGTERM',cleanup);process.on('SIGINT',cleanup)}
 async function request(payload,ensure=true){if(ensure)await ensureDaemon();return new Promise((resolve,reject)=>{const c=net.createConnection(SOCKET);let data='';c.setEncoding('utf8');c.on('connect',()=>c.write(JSON.stringify(payload)+'\n'));c.on('data',x=>{data+=x;if(!data.includes('\n'))return;c.end();try{const r=JSON.parse(data);r.error?reject(Error(r.error)):resolve(r)}catch(e){reject(e)}});c.on('error',reject)})}
 export async function ensureDaemon(){try{const p=await request({op:'ping'},false);if(p.ok)return p}catch{}if(!process.env.WEBHELM_CDP_URL)requireMigratedConfig();fs.mkdirSync(RUNTIME,{recursive:true,mode:0o700});if(fs.existsSync(LOCK)){let owner=0;try{owner=Number(fs.readFileSync(LOCK,'utf8').trim())}catch{};let alive=false;if(owner>0)try{process.kill(owner,0);alive=true}catch{};if(alive)throw Error(`daemon owner lock exists but socket is unreachable; refusing duplicate startup (${LOCK})`);fs.unlinkSync(LOCK)}const child=await import('node:child_process');const log=fs.openSync(path.join(RUNTIME,'session-node.log'),'a');child.spawn(process.execPath,[fileURLToPath(import.meta.url),'daemon'],{detached:true,stdio:['ignore',log,log],env:process.env}).unref();for(let i=0;i<100;i++){await delay(100);try{const p=await request({op:'ping'},false);if(p.ok)return p}catch{}}throw Error(`WebHelm Node daemon did not start; see ${path.join(RUNTIME,'session-node.log')}`)}
 if(process.argv[2]==='daemon')main().catch(e=>{console.error(e);process.exit(1)});