webhelm 0.0.0-stage → 1.0.1

package/PRIVACY.md

@@ -0,0 +1,21 @@
+# Browser Workspace Privacy Policy
+
+Browser Workspace is a Chrome extension that manages named tab-group workspaces and reusable tab pools inside the user's browser.
+
+## Data handling
+
+Browser Workspace does not send, sell, share, or transfer user data to the developer or to third parties.
+
+The extension uses Chrome's local extension storage only to keep workspace configuration and local lease metadata needed to restore and manage workspaces. This information stays in the user's browser profile.
+
+The extension may read tab identifiers, URLs, tab-group membership, navigation-target relationships, and related browser state only as needed to create, group, navigate, reuse, release, or reclaim workspace tabs. This information is processed locally and is not transmitted to an external service.
+
+Browser Workspace does not collect personally identifiable information, authentication information, financial information, health information, personal communications, location data, website content, or user activity for external storage or analytics.
+
+## Remote code
+
+Browser Workspace does not execute remote JavaScript or WebAssembly. All extension code is packaged with the extension.
+
+## Contact
+
+Questions about this privacy policy may be submitted through the Browser Workspace GitHub repository.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# WebHelm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[WebHelm](https://github.com/lalalic/webhelm) is a Node.js CLI and agent Skill for a visible, managed Chrome instance. One Runtime daemon controls CDP, persistent JavaScript browser Sessions, Chrome Tab Groups, and durable ChatGPT FIFO delivery.
+
+## Two repositories, independent releases
+
+| 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-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.
+
+## Install and use
+
+```sh
+npx --yes webhelm@latest setup
+npx --yes webhelm@latest status
+npx --yes webhelm@latest capacity
+npx --yes webhelm@latest platform list
+npx --yes webhelm@latest platform sync
+npx --yes webhelm@latest session start --url https://example.com
+npx --yes webhelm@latest session exec SESSION_ID <<'JS'
+console.log(await snapshot());
+JS
+npx --yes webhelm@latest session stop SESSION_ID
+```
+
+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`.
+
+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.
+
+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.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+```
+
+Keep platform-specific code and tests in `lalalic/webhelm-actions`. Runtime tests should use mock CDP or owned, temporary real Chrome tabs; protect other active Sessions. GitHub Actions runs Runtime/Extension CI. The Skill and Extension remain version-controlled together; npm publishing uses the standalone package at the repository root.
+
+### Adding an unsupported platform
+
+The WebHelm Skill includes [`skills/webhelm/NEW_PLATFORM.md`](skills/webhelm/NEW_PLATFORM.md). All new platform code belongs in **`~/.local/webhelm/platforms/<slug>`**, checked out from `lalalic/webhelm-actions`, including tests and docs. There is no separate `platforms/` directory in the Skill or npm package. Publishing an Action uses Git, not npm.
+
+## npm publishing
+
+`.github/workflows/publish.yml` publishes CLI/Runtime changes on `main` using GitHub Actions and npm OIDC trusted publishing. It reuses Agents Relay's bounded-test and publication-report Actions, as the other repositories do. The CI workflow never stores an npm write token or asks for a local 2FA approval. Configure the **webhelm** npm package's Trusted Publisher once: GitHub user `lalalic`, repository `webhelm`, workflow filename `publish.yml` (no environment), with **Allow npm publish** enabled. New configurations otherwise default to staged-only publishing and require individual approvals. A successful publish is verified against the npm registry and reported to Agents Relay. Skill-only and platform Action changes do not trigger npm publication.

package/bin/webhelm.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../runtime/cli.mjs';

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "webhelm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Agent browser automation in a visible managed Chrome with persistent JavaScript sessions",
+  "type": "module",
+  "bin": {
+    "webhelm": "bin/webhelm.mjs"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "files": [
+    "bin/",
+    "runtime/",
+    "README.md",
+    "PRIVACY.md"
+  ],
+  "scripts": {
+    "test": "node --test test/node/*.test.mjs test/workspace-manager.test.mjs skills/webhelm/tests/*.test.mjs",
+    "test:package": "npm pack --dry-run --json"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lalalic/webhelm.git"
+  },
+  "homepage": "https://github.com/lalalic/webhelm",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  }
+}

package/runtime/actions-repo.mjs

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+
+export const ACTIONS_DIR = path.resolve(process.env.WEBHELM_ACTIONS_HOME || path.join(os.homedir(), '.local', 'webhelm'));
+const REMOTE = process.env.WEBHELM_ACTIONS_REPO || 'https://github.com/lalalic/webhelm-actions.git';
+const options={timeout:90000,maxBuffer:1048576};
+let initialSetup;
+const git=(...args)=>run('git',args,options).then(r=>r.stdout.trim());
+function verifyCheckout(){
+  if (!fs.existsSync(path.join(ACTIONS_DIR,'.git')) || !fs.existsSync(path.join(ACTIONS_DIR,'platforms')))
+    throw new Error(`Existing ${ACTIONS_DIR} is not a complete WebHelm Actions checkout; do not overwrite it`);
+}
+export async function ensureActions(){
+  if(initialSetup)return initialSetup;
+  initialSetup=(async()=>{
+    if(fs.existsSync(ACTIONS_DIR))verifyCheckout();
+    else {
+      fs.mkdirSync(path.dirname(ACTIONS_DIR),{recursive:true});
+      const staging=fs.mkdtempSync(path.join(path.dirname(ACTIONS_DIR),'.webhelm-actions-'));
+      try {
+        await git('clone','--depth','1','--branch','main','--',REMOTE,staging);
+        if(!fs.existsSync(path.join(staging,'platforms')))throw Error('Action repository has no platforms/');
+        fs.renameSync(staging,ACTIONS_DIR);
+      }finally{if(fs.existsSync(staging))fs.rmSync(staging,{recursive:true,force:true});}
+    }
+    return {actions_home:ACTIONS_DIR,platform_dir:path.join(ACTIONS_DIR,'platforms'),revision:await git('-C',ACTIONS_DIR,'rev-parse','--short','HEAD')};
+  })();
+  try{return await initialSetup;}catch(e){initialSetup=undefined;throw e;}
+}
+export async function syncActions(){
+  await ensureActions();
+  const changes=await git('-C',ACTIONS_DIR,'status','--porcelain');
+  if(changes)throw Error('Actions checkout has local changes; refusing to overwrite. Review/publish or commit before sync.');
+  await git('-C',ACTIONS_DIR,'fetch','--prune','origin','main');
+  // Updating is permitted only if current commit is an ancestor of origin/main.
+  await git('-C',ACTIONS_DIR,'merge-base','--is-ancestor','HEAD','origin/main');
+  await git('-C',ACTIONS_DIR,'merge','--ff-only','origin/main');
+  return {status:'synced',...(await ensureActions()),revision:await git('-C',ACTIONS_DIR,'rev-parse','--short','HEAD')};
+}
+export async function publishActions(message){
+  await ensureActions();
+  if(!message || message.trim().length<8 || message.length>250)throw Error('--message must describe the verified action change (8–250 characters)');
+  const staged=await git('-C',ACTIONS_DIR,'diff','--cached','--name-only');
+  if(staged.split('\n').filter(Boolean).some(s=>!s.startsWith('platforms/')))
+    throw Error('Refusing to publish unrelated staged files');
+  await git('-C',ACTIONS_DIR,'diff','--check');
+  const changed=await git('-C',ACTIONS_DIR,'status','--porcelain','--','platforms');
+  if(!changed)throw Error('No platform action changes to publish');
+  // Run repository contract tests before creating a commit. These must not perform live writes.
+  await run('npm',['test'],{cwd:ACTIONS_DIR,...options});
+  await git('-C',ACTIONS_DIR,'add','--','platforms');
+  await git('-C',ACTIONS_DIR,'diff','--cached','--check');
+  await git('-C',ACTIONS_DIR,'commit','-m',message.trim());
+  const revision=await git('-C',ACTIONS_DIR,'rev-parse','HEAD');
+  // Never force-push or overwrite collaborator commits.
+  await git('-C',ACTIONS_DIR,'push','origin','HEAD:refs/heads/main');
+  return {status:'published',revision,repository:REMOTE};
+}

package/runtime/admin.mjs

@@ -0,0 +1,7 @@
+import net from 'node:net';
+import { RUNTIME_DIR } from './config-paths.mjs';
+import path from 'node:path';
+const socketPath=()=>process.env.WEBHELM_SOCKET||path.join(process.env.WEBHELM_RUNTIME_DIR||RUNTIME_DIR,'session-node.sock');
+function request(payload){return new Promise((resolve,reject)=>{const s=net.createConnection(socketPath());let buf='';s.setEncoding('utf8');s.on('connect',()=>s.write(JSON.stringify(payload)+'\n'));s.on('data',d=>{buf+=d;if(!buf.includes('\n'))return;s.end();try{const v=JSON.parse(buf);v.error?reject(Error(v.error)):resolve(v)}catch(e){reject(e)}});s.on('error',reject)})}
+export async function ensureWorkspace(name,size=5){if(typeof name!=='string'||!name.trim())throw TypeError('workspace name must be a non-empty string');if(!Number.isInteger(size)||size<1)throw TypeError('workspace size must be a positive integer');return request({op:'workspace-create',name:name.trim(),pool_size:size})}
+export async function deleteWorkspace(name,{force=false}={}){if(typeof name!=='string'||!name.trim())throw TypeError('workspace name must be a non-empty string');return request({op:'workspace-delete',name:name.trim(),force:Boolean(force)})}

package/runtime/chatgpt/chatgpt-delivery-errors.mjs

@@ -0,0 +1,94 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+const patterns = [
+  [
+    "conversation_too_long",
+    /conversation_too_long|conversation is too long to continue|conversation too long/i,
+  ],
+  [
+    "thread_load_failed",
+    /thread_load_failed|could not load this chatgpt conversation|failed to load conversation/i,
+  ],
+  [
+    "authentication_required",
+    /login required|log in to chatgpt|session expired|sign in to chatgpt/i,
+  ],
+  ["rate_limited", /rate.limit|too many requests|http 429|usage limit/i],
+  [
+    "invalid_thread_id",
+    /invalid thread.id|thread.id is required|malformed thread/i,
+  ],
+  ["thread_redirect_mismatch", /thread redirect mismatch/i],
+  [
+    "conversation_busy",
+    /conversation is busy|turn completion.*not observed ready/i,
+  ],
+  [
+    "send_not_ready",
+    /lifecycle continuation readiness was not observed ready|send button.*disabled/i,
+  ],
+  ["composer_not_found", /composer.*not observed ready|composer.*not found/i],
+  ["composer_input_failed", /composer rejected|input failed|prompt.*mismatch/i],
+  ["send_click_failed", /send button changed before|send button.*click/i],
+  [
+    "submission_unverified",
+    /submission.*not observed|post.submit.*unverified|cleared composer/i,
+  ],
+  ["thread_creation_failed", /did not assign a durable thread id/i],
+  ["project_not_found", /project not found/i],
+  ["project_access_denied", /project.*access denied|permission.*project/i],
+  ["attachment_failed", /attachment.*failed|upload.*failed/i],
+  [
+    "attachment_processing_timeout",
+    /attachment.*timeout|attachment.*not observed ready/i,
+  ],
+  ["session_unavailable", /unknown session|session not found|session.*closed/i],
+  [
+    "browser_unavailable",
+    /chrome.*unavailable|cdp.*disconnect|daemon.*unreachable/i,
+  ],
+  ["execution_timeout", /timed out|timeout|runtime.evaluate/i],
+];
+export function classify(error) {
+  const raw = String(error || "");
+  const code = patterns.find(([, re]) => re.test(raw))?.[0] ||
+    "delivery_failed";
+  const messages = {
+    send_not_ready: "Prompt entered, but Send button did not become ready",
+    thread_load_failed: "ChatGPT conversation could not be loaded",
+    conversation_too_long: "Conversation is too long to continue",
+    submission_unverified: "Submission could not be confirmed",
+  };
+  return {
+    ok: false,
+    code,
+    message: messages[code] ||
+      code.replaceAll("_", " ").replace(/^./, (c) => c.toUpperCase()),
+  };
+}
+export async function normalizeFailure(
+  result,
+  action,
+  {
+    logPath = join(
+      homedir(),
+      ".config/webhelm/runtime/chatgpt-delivery-errors.jsonl",
+    ),
+  } = {},
+) {
+  if (result?.ok !== false) return result;
+  const raw = String(result.stderr || result.error || "");
+  const diagnostic_id = randomUUID().replaceAll("-", "");
+  try {
+    await mkdir(dirname(logPath), { recursive: true });
+    await appendFile(
+      logPath,
+      JSON.stringify({ diagnostic_id, action, error: raw }) + "\n",
+    );
+  } catch {}
+  const normalized = classify(raw);
+  if ("cleanup" in result) normalized.cleanup = result.cleanup;
+  return normalized;
+}

package/runtime/chatgpt/chatgpt-probe.mjs

@@ -0,0 +1,23 @@
+export function targetUrl(projectId, threadId, message) {
+  if (!threadId || !message) {
+    throw new Error("thread_id and message are required");
+  }
+  const prefix = projectId ? `/g/${encodeURIComponent(projectId)}` : "";
+  return `https://chatgpt.com${prefix}/c/${
+    encodeURIComponent(threadId)
+  }?${new URLSearchParams({ prompt: message })}`;
+}
+export const PROBE_JS =
+  `(() => { const visible=e=>!!e&&!!e.getClientRects().length&&getComputedStyle(e).visibility!=='hidden'; const body=(document.body?.innerText||'').toLowerCase(); if(body.includes('could not load this chatgpt conversation'))return {state:'BLOCKED',error:'thread_load_failed'}; if(body.includes('log in to chatgpt')||body.includes('sign in to chatgpt'))return {state:'BLOCKED',error:'authentication_required'}; const stop=[...document.querySelectorAll('button')].some(b=>{if(!visible(b))return false;const l=(b.getAttribute('aria-label')||'').trim().toLowerCase(),t=(b.getAttribute('title')||'').trim().toLowerCase(),d=(b.getAttribute('data-testid')||'').trim().toLowerCase();return ['stop generating','stop answering','stop response','stop'].includes(l)||['stop generating','stop answering'].includes(t)||['stop-button','stop-generating-button'].includes(d)}); if(stop)return {state:'RUNNING',stop_visible:true}; const e=document.querySelector('#prompt-textarea,[contenteditable="true"][data-lexical-editor="true"],[role="textbox"][contenteditable="true"],textarea'); const editable=e?.getAttribute?.('contenteditable')==='true'; return {state:visible(e)?'READY':'NOT_READY',stop_visible:false,composer_text:e?(editable?(e.textContent||''):(e.value||e.textContent||e.innerText||'')):''}; })()`;
+export function classifyProbe(observedUrl, expectedUrl, state) {
+  const actual = new URL(observedUrl), expected = new URL(expectedUrl);
+  if (
+    actual.protocol !== "https:" || actual.host !== "chatgpt.com" ||
+    actual.pathname.replace(/\/$/, "") !== expected.pathname.replace(/\/$/, "")
+  ) return "BLOCKED";
+  if (["RUNNING", "BLOCKED"].includes(state?.state)) return state.state;
+  if (actual.search) return "NOT_READY";
+  return state?.state === "READY" && String(state.composer_text || "").trim()
+    ? "READY"
+    : "NOT_READY";
+}