webhelm 1.0.12 → 1.0.14

package/README.md

@@ -11,6 +11,10 @@
 
 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.
 
+The agent-facing `webhelm` CLI uses only the `WebHelm` Workspace. It intentionally does not accept `--workspace` or expose Workspace management helpers in `session exec`. `session stop --all` only stops WebHelm Sessions. Application services such as Relay provision their own named Workspaces through the daemon IPC `workspace-create`, `workspace-resize`, and `workspace-delete`; they may start Sessions via the daemon `start` operation for those pre-provisioned names. Leasing a missing Workspace fails rather than creating it.
+
+Neo Master development uses the Git checkout directly via local symlinks for the CLI, Skill, and Extension; production nodes use published npm Runtime installations. Set `WEBHELM_SOURCE_MODE=1` when running the checkout directly; this loads the Extension from the repository and creates a LaunchAgent that references the repository's CLI without staging an npm Runtime copy.
+
 ## Install and use
 
 ```sh

package/package.json

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

package/runtime/cli.mjs

@@ -4,13 +4,14 @@ import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { randomUUID } from 'node:crypto';
-import { ensureDaemon, request, handle, SOCKET } from './node-daemon.mjs';
+import { ensureDaemon, request, 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, stageRuntimeForLoginGuard } from './login-guard.mjs';
 
 const ROOT = path.dirname(fileURLToPath(import.meta.url));
+const CLI_WORKSPACE = 'WebHelm';
 const emit = value => console.log(JSON.stringify(value));
 const arg = (items, name) => {
   const i = items.indexOf(name);
@@ -26,8 +27,8 @@ Usage:
   webhelm setup
   webhelm status
   webhelm ensure  # verify/recover managed Chrome and WebHelm group, not just daemon ping
-  webhelm capacity [--workspace NAME]
-  webhelm session start [--workspace NAME] [--url URL]
+  webhelm capacity  # WebHelm workspace only
+  webhelm session start [--url URL]  # WebHelm workspace only
   webhelm session list
   webhelm session heartbeat SESSION_ID  # keep a working Session alive
   webhelm session exec SESSION_ID [--code-file FILE]   # JavaScript
@@ -93,9 +94,26 @@ async function runPlatform(args) {
     };
   }
   if (mode === 'sync' && (!sid || auto)) throw Error('sync new-turn requires a caller-owned --session-id');
+  if (sid) await requireCliSession(sid);
   if (!sid && !auto) throw Error('platform run requires --session-id; use --auto-session only for one-shot actions');
   return request({op:'platform-run', platform, action, config: {...config, ...(mode ? {mode} : {})},
-    session_id:sid, auto_session:auto, url:arg(args, '--url')});
+    session_id:sid, auto_session:auto, url:arg(args, '--url'), workspace:CLI_WORKSPACE});
+}
+
+// The agent CLI is not a Workspace provisioning interface. Other workspaces
+// belong to application code using the explicit daemon IPC API.
+function rejectWorkspaceOverride(args) {
+  if (has(args, '--workspace') || args.some(a=>a.startsWith('--workspace=')))
+    throw Error('CLI is restricted to the WebHelm workspace; applications must provision custom workspaces through the daemon API');
+}
+function onlyCliWorkspace(sessions) {
+  return (sessions || []).filter(item=>item.workspace === CLI_WORKSPACE);
+}
+async function requireCliSession(sessionId) {
+  if (!sessionId) throw Error('session id is required');
+  const listed = await request({op:'list'});
+  if (!onlyCliWorkspace(listed.sessions).some(item=>item.session_id===sessionId))
+    throw Error(`Session ${sessionId} is not owned by the WebHelm CLI workspace`);
 }
 
 async function main(args = process.argv.slice(2)) {
@@ -110,8 +128,11 @@ async function main(args = process.argv.slice(2)) {
   if (group === 'setup') {
     const repo=await ensureActions();
     const chrome=await ensureDaemon();
-    const persisted=stageRuntimeForLoginGuard();
-    const login_guard=installLoginGuard({cliPath:path.join(persisted.path,'bin/webhelm.mjs'),nodePath:process.execPath});
+    const sourceMode=process.env.WEBHELM_SOURCE_MODE==='1';
+    const cliPath=sourceMode
+      ? fileURLToPath(new URL('../bin/webhelm.mjs',import.meta.url))
+      : path.join(stageRuntimeForLoginGuard().path,'bin/webhelm.mjs');
+    const login_guard=installLoginGuard({cliPath,nodePath:process.execPath,sourceMode});
     return emit({status:'ready',...repo,daemon_pid:chrome.pid,managed_chrome:chrome.managed_chrome,login_guard});
   }
   if (group === 'ensure') return emit(await request({op:'guard-check'}));
@@ -124,26 +145,31 @@ async function main(args = process.argv.slice(2)) {
       daemon:{running:true, pid:daemon.pid, session_count:daemon.session_count, queue_paused:daemon.queue_paused, socket:SOCKET}});
   }
   if (group === 'capacity') {
-    const payload={op:'capacity',workspace:arg(args,'--workspace')};
-    try { return emit(await request(payload)); }
-    catch(error) {
-      // Rolling upgrade: query extension metadata directly until a busy old
-      // Node daemon can drain its Sessions and load the new capacity operation.
-      if (!String(error.message).includes('unknown op: capacity')) throw error;
-      emit(await handle(payload));
-      return process.exit(0); // close this CLI's one-off CDP websocket
-    }
+    rejectWorkspaceOverride(args);
+    const payload={op:'capacity',workspace:CLI_WORKSPACE};
+    // Never run a second in-process browser controller as a fallback: it may
+    // reload an older daemon's Extension while its Sessions are still active.
+    return emit(await request(payload));
   }
   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'}));
+    rejectWorkspaceOverride(args);
+    if (command === 'start') return emit(await request({op:'start', workspace:CLI_WORKSPACE, url:arg(args,'--url')}));
+    if (command === 'list') {
+      const result=await request({op:'list'});
+      const sessions=onlyCliWorkspace(result.sessions);
+      return emit({session_count:sessions.length,sessions});
+    }
     if (command === 'heartbeat') {
-      if (!args[2]) throw Error('session heartbeat requires SESSION_ID');
+      await requireCliSession(args[2]);
       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 === 'stop') {
+      if (has(args,'--all')) return emit(await request({op:'stop-workspace',workspace:CLI_WORKSPACE}));
+      await requireCliSession(args[2]);
+      return emit(await request({op:'stop',session_id:args[2]}));
+    }
     if (command === 'exec') {
-      if (!args[2]) throw Error('session exec requires SESSION_ID');
+      await requireCliSession(args[2]);
       const file = arg(args, '--code-file');
       const code = file ? fs.readFileSync(file, 'utf8') : fs.readFileSync(0, 'utf8');
       const result = await request({op:'exec', session_id:args[2], code});
@@ -153,6 +179,7 @@ async function main(args = process.argv.slice(2)) {
     }
   }
   if (group === 'platform') {
+    rejectWorkspaceOverride(args);
     if (command === 'sync') return emit(await syncActions());
     if (command === 'publish') return emit(await publishActions(arg(args, '--message')));
     await ensureActions();

package/runtime/extension/manifest.json

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

package/runtime/extension/service-worker.mjs

@@ -96,7 +96,18 @@ globalThis.browserWorkspaceManagerRpc = async (request) => {
   }
 };
 
+// Only the daemon's direct Service Worker RPC may provision, resize, delete,
+// or restore Workspace identities. A browser Session on an extension page must
+// not gain management rights through chrome.runtime.sendMessage().
+const APPLICATION_ONLY_METHODS = new Set([
+  "workspace.create", "workspace.resize", "workspace.delete",
+  "workspace.ensure", "workspace.migrateDefault",
+]);
 chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
+  if (APPLICATION_ONLY_METHODS.has(request?.method)) {
+    sendResponse({ok:false,error:{message:"Workspace management requires an application daemon API"}});
+    return false;
+  }
   if (request?.method?.startsWith("workspace.control.") &&
       (sender?.url !== chrome.runtime.getURL("popup.html") ||
         !["workspace.control.requestStop", "workspace.control.status"].includes(request.method))) {

package/runtime/extension/workspace-manager.mjs

@@ -550,7 +550,11 @@ export class WorkspaceManager {
 
   async acquireIdentity(name) {
     const normalizedName = normalizeWorkspaceName(name);
-    const ready = await this.ensureWorkspace(normalizedName);
+    // Leasing may allocate a Tab inside an existing Workspace, but must never
+    // provision a new Workspace as a side effect. Only app-owned creation can.
+    const ready = await this.status(normalizedName);
+    if (!ready.initialized)
+      throw new Error(`Workspace ${normalizedName} does not exist; an application must provision it first`);
     const tabs = await this.groupTabs(ready.groupId);
     const { idle, leased } = this.classify(normalizedName, tabs);
     if (!idle.length && leased.length >= ready.poolSize) {
@@ -591,7 +595,11 @@ export class WorkspaceManager {
       throw new Error("Workspace acquire requires an http(s) or chrome-extension URL");
     }
 
-    const ready = await this.ensureWorkspace(normalizedName);
+    // Leasing may allocate a Tab inside an existing Workspace, but must never
+    // provision a new Workspace as a side effect. Only app-owned creation can.
+    const ready = await this.status(normalizedName);
+    if (!ready.initialized)
+      throw new Error(`Workspace ${normalizedName} does not exist; an application must provision it first`);
     const tabs = await this.groupTabs(ready.groupId);
     const { idle, leased } = this.classify(normalizedName, tabs);
     if (!idle.length && leased.length >= ready.poolSize) {

package/runtime/extension-manager.mjs

@@ -6,8 +6,10 @@ import {fileURLToPath} from 'node:url';
 import {LOCAL_ROOT} from './config-paths.mjs';
 
 export const EXTENSION_ID='kkkpgmhpoeceojalkpfdidffdfnlgdog';
-export const EXTENSION_HOME=path.resolve(process.env.WEBHELM_EXTENSION_HOME || path.join(LOCAL_ROOT,'extension'));
 const SOURCE=fileURLToPath(new URL('./extension/',import.meta.url));
+const SOURCE_MODE=process.env.WEBHELM_SOURCE_MODE==='1';
+export const EXTENSION_HOME=path.resolve(process.env.WEBHELM_EXTENSION_HOME ||
+  (SOURCE_MODE ? SOURCE : path.join(LOCAL_ROOT,'extension')));
 const FILES=[
   'manifest.json','service-worker.mjs','workspace-manager.mjs','workspace.html','helm.html','workspace-page.mjs',
   'control-channel.mjs','workspace-summary.mjs','session-badge.mjs','popup.html','popup.mjs',
@@ -50,6 +52,10 @@ function excludeFromActionsGit(dir){
 export function stageExtension(dir=EXTENSION_HOME){
   const target=path.resolve(dir);
   const bundled=manifest(SOURCE);
+  // Neo Master works from its Git checkout. Never stage or overwrite source
+  // files, and never accept arbitrary symlinks as a deployment directory.
+  if(SOURCE_MODE && canonicalPath(target)===canonicalPath(SOURCE))
+    return {path:SOURCE,version:bundled.version,updated:false,sourceMode:true};
   if(fs.existsSync(target)&&fs.lstatSync(target).isSymbolicLink())throw Error('Refusing to replace extension symlink');
   if(fs.existsSync(target)&&identical(target))return {path:target,version:bundled.version,updated:false};
   if(fs.existsSync(target))manifest(target); // Never replace unrelated content.

package/runtime/login-guard.mjs

@@ -36,23 +36,23 @@ export function stageRuntimeForLoginGuard({home=os.homedir(),source=fileURLToPat
 }
 
 const escapeXml=s=>String(s).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&apos;'}[c]));
-export function loginGuardDefinition(home=os.homedir(),{cliPath=path.join(home,'.local/bin/webhelm'),nodePath=null}={}) {
+export function loginGuardDefinition(home=os.homedir(),{cliPath=path.join(home,'.local/bin/webhelm'),nodePath=null,sourceMode=false}={}) {
   const cli=cliPath;
   const program=nodePath||cli;
   const args=nodePath?`<string>${escapeXml(cli)}</string><string>ensure</string>`:'<string>ensure</string>';
   const environment=[path.join(home,'.local/bin'),path.join(home,'.local/opt/node22/bin'),
     '/opt/homebrew/bin','/usr/local/bin','/usr/bin','/bin'].join(':');
-  // Use the cached, tested npm Runtime directly to avoid registry/network
-  // dependency at login or when Chrome has just auto-updated. This must call
+  // Use a pinned local Runtime (or the source checkout on Neo Master), not
+  // npm/network at login or after Chrome updates. This must call
   // 'ensure', not 'status': a live daemon does not imply a live 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(program)}</string>${args}</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>30</integer>\n<key>StandardOutPath</key><string>/dev/null</string>\n<key>StandardErrorPath</key><string>/dev/null</string>\n</dict></plist>\n`;
+  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(program)}</string>${args}</array>\n<key>EnvironmentVariables</key><dict><key>PATH</key><string>${escapeXml(environment)}</string><key>HOME</key><string>${escapeXml(home)}</string>${sourceMode?'<key>WEBHELM_SOURCE_MODE</key><string>1</string>':''}</dict>\n<key>RunAtLoad</key><true/>\n<key>StartInterval</key><integer>30</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,cliPath,nodePath}={}){
+export function installLoginGuard({home=os.homedir(), platform=process.platform, apply=true,cliPath,nodePath,sourceMode=false}={}){
   if(platform!=='darwin')return {status:'unsupported',label:LABEL};
   const cli=cliPath||path.join(home,'.local/bin/webhelm');
   if(!fs.existsSync(cli))return {status:'skipped',reason:'WebHelm runtime launcher missing',label:LABEL};
   const dest=path.join(home,'Library/LaunchAgents',`${LABEL}.plist`);
-  const content=loginGuardDefinition(home,{cliPath,nodePath});
+  const content=loginGuardDefinition(home,{cliPath,nodePath,sourceMode});
   fs.mkdirSync(path.dirname(dest),{recursive:true});
   if(fs.existsSync(dest)){
     const old=fs.readFileSync(dest,'utf8');

package/runtime/node-daemon.mjs

@@ -232,9 +232,6 @@ function makeHelpers(s){
   async workspace_status(){return extensionCall(s,'workspace.status',{name:s.workspace})},
   async workspace_capacity(){const r=await h.workspace_status();const idle=Array.isArray(r.idleTabIds)?r.idleTabIds.length:null,leased=Array.isArray(r.leasedTabIds)?r.leasedTabIds.length:null;return {name:r.name,poolSize:r.poolSize??null,maxCapacity:r.maxCapacity??r.poolSize??null,physicalTabs:r.physicalTabs??(idle!==null&&leased!==null?idle+leased:null),idle,leased,available:Number.isInteger(r.maxCapacity??r.poolSize)&&leased!==null?Math.max(0,(r.maxCapacity??r.poolSize)-leased):null}} ,
   async workspace_list(){return extensionCall(s,'workspace.list')},
-  async workspace_create(name,poolSize=5){return extensionCall(s,'workspace.create',{name,poolSize})},
-  async workspace_resize(name,poolSize){return extensionCall(s,'workspace.resize',{name,poolSize})},
-  async workspace_delete(name,force=false){return extensionCall(s,'workspace.delete',{name,force})},
   async wait(seconds){return delay(seconds*1000)},
   async sleep(milliseconds){return delay(milliseconds)},
   async type_text(text){return cdp(s,'Input.insertText',{text:String(text)})},
@@ -507,7 +504,18 @@ function heartbeatSession(sid){
   return {session_id:sid,alive:true,last_used_at:s.last_used_at};
 }
 
-async function workspaceOp(req){const h=makeHelpers({workspace:req.name||await defaultWorkspaceName(),targetId:'',targets:new Set(),attachments:new Map()});if(req.op==='workspace-create')return h.workspace_create(req.name,req.pool_size);if(req.op==='workspace-delete')return h.workspace_delete(req.name,req.force);throw Error(`unknown op: ${req.op}`)}
+// Applications (Relay, Neo, etc.) provision Workspaces through the daemon IPC,
+// never through the agent-facing CLI or its session JavaScript namespace.
+async function workspaceOp(req) {
+  if (typeof req.name !== 'string' || !req.name.trim()) throw Error('workspace name required');
+  if (req.op === 'workspace-create')
+    return extensionCall(null,'workspace.create',{name:req.name,poolSize:req.pool_size ?? 8});
+  if (req.op === 'workspace-resize')
+    return extensionCall(null,'workspace.resize',{name:req.name,poolSize:req.pool_size});
+  if (req.op === 'workspace-delete')
+    return extensionCall(null,'workspace.delete',{name:req.name,force:Boolean(req.force)});
+  throw Error(`unknown workspace operation: ${req.op}`);
+}
 function getChatGPTQueue() {
   if (chatgptQueue) return chatgptQueue;
   chatgptQueue = new ChatGPTQueue({
@@ -605,7 +613,7 @@ export function actionOutput(logs, value) {
 async function runPlatform(req) {
   const platform=req.platform, action=req.action, config=req.config || {};
   const auto=Boolean(req.auto_session);
-  const started=auto ? await createSession({url:req.url}) : {session_id:req.session_id};
+  const started=auto ? await createSession({url:req.url,workspace:req.workspace}) : {session_id:req.session_id};
   const sid=started.session_id;
   if (!sid) throw Error('platform run requires a session_id or auto_session');
   const session=sessions.get(sid);
@@ -646,7 +654,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},chrome_guard:managedChromeGuard.status()};case'guard-check':{let status=await managedChromeGuard.tick();for(let retry=0;retry<6 && status.status!=='healthy' && !status.skipped;retry++){await delay(800);status=await managedChromeGuard.tick();}if(status.status!=='healthy' && !status.skipped)throw Error(`WebHelm Chrome health degraded: ${status.error||status.status}`);return {ok:true,chrome_guard: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':return stopAllSessions();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'guard-check':{let status=await managedChromeGuard.tick();for(let retry=0;retry<6 && status.status!=='healthy' && !status.skipped;retry++){await delay(800);status=await managedChromeGuard.tick();}if(status.status!=='healthy' && !status.skipped)throw Error(`WebHelm Chrome health degraded: ${status.error||status.status}`);return {ok:true,chrome_guard: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':return stopAllSessions();case'stop-workspace':{if(typeof req.workspace!=='string'||!req.workspace.trim())throw Error('workspace required');return stopWorkspaceSessions(req.workspace)}case'capacity':return workspaceCapacity(req);case'workspace-create':case'workspace-resize':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');