Skip to content

Self-improving AI Employees for everyone

docs(browser): document hiring, help requests and the profiles panel

trohitg7cdc3ef7f248
diff --git a/CLAUDE.md b/CLAUDE.md
index 553ad682..820d77af 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,7 +13,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[UI Migration Plan](./docs-internal/ARCHIVE/ui_migration_plan.md)** | *Archived.* antd → shadcn/ui migration completion log (Waves 1–10). Current state lives in [Frontend Architecture](./docs-internal/frontend_architecture.md) and [Theme System](./docs-internal/theme_system.md). |
| **[Temporal Cleanup & Resilience Plan (Waves 15-18)](./docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md)** | *Archived — all four waves shipped.* 15 dead-code retirement (Redis-Streams branch in event_waiter, APScheduler cron stack, orphaned `connection_status` factory), 16 per-queue task routing (`TemporalWorkerPool`), 17 resilience hardening (cron `catchup_window`, SDK interceptors, `DEPLOYMENT_MODE`, periodic heartbeats; the one-shot LLM-step retry it records was later reverted to unlimited-with-backoff), 18 worker performance tuning. Current settings live in [Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md). |
| **[Node Allowlist](./docs-internal/node_allowlist.md)** | Single-config UI visibility — `server/config/node_allowlist.json` controls which nodes / credential categories / skill folders show in the UI. Five lists with two enforcement tiers (mode-gated allowlist + absolute blocklist). `useNodeAllowlist` hook exposes `isVisible` / `isBlocked` / `isAllowed` / `isCredentialCategoryDisabled` / `isSkillFolderDisabled`. Adding a new disabled domain = single JSON edit, no code change. |
-| **[Normal Mode (Home)](./docs-internal/normal_mode.md)** | The owner-facing landing screen: describe a job, an LLM on the server drafts a setup screen (a JSON UI spec the client parses, normalises and renders from a fixed catalogue), and Hire builds, validates, saves and starts one workflow per AI employee (`services/employees/`, graph built from `config/employee_apps.json` plus the owner's skill library and a Canvas node, and checked against `node_allowlist.json` `enabled_nodes`). Covers the screen switch (`app/`, `shellMode` / `ui_shell_mode`, `VITE_NORMAL_MODE=false` kill switch, Home shows light/dark only), the employee card, the `approvalGate` "ask me before sending" step, run records for "done today" (`machina-run-record-v1`), automatic-pause reasons, Settings (Profile fields; usage-only Billing via `get_employee_usage`; Skills, the user-skills library each new hire copies onto a Skills node; consumer Connectors with `publisher` / `verified`; Plugins, the starter bundles in `hire/starters.json`; the last three share one catalog page), the Workspace dock (an employee's Canvas board, named by the summary's `canvas_node_id`; a live Browser tab with user takeover, shared with Dev mode; Android remains a placeholder), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` broadcasts. |
+| **[Normal Mode (Home)](./docs-internal/normal_mode.md)** | The owner-facing landing screen: describe a job, an LLM on the server drafts a setup screen (a JSON UI spec the client parses, normalises and renders from a fixed catalogue), and Hire builds, validates, saves and starts one workflow per AI employee (`services/employees/`, graph built from `config/employee_apps.json` plus the owner's skill library and a Canvas node, and checked against `node_allowlist.json` `enabled_nodes`). Covers the screen switch (`app/`, `shellMode` / `ui_shell_mode`, `VITE_NORMAL_MODE=false` kill switch, Home shows light/dark only), the employee card, the `approvalGate` "ask me before sending" step, run records for "done today" (`machina-run-record-v1`), automatic-pause reasons, Settings (Profile fields; usage-only Billing via `get_employee_usage`; Skills, the user-skills library each new hire copies onto a Skills node; consumer Connectors with `publisher` / `verified`; Plugins, the starter bundles in `hire/starters.json`; the last three share one catalog page), the Workspace dock (an employee's Canvas board, named by the summary's `canvas_node_id`; a live Browser tab with user takeover, shared with Dev mode; Android remains a placeholder), the "Web browser" app (read-only under "ask me first" through the tool's `ask_first_params`; while the agent waits in `request_user` the summary's `browser_request` shows Needs you and Help in browser), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` broadcasts. |
| **[Theme System](./docs-internal/theme_system.md)** | 12-way visual theme system — 2 base (light, dark) + 5 utopian (renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion) in **hex + `color-mix()`**; `@theme inline` bridge maps `--color-X: var(--X)` (no `hsl()` wrapper); per-theme files own the colour hex, base.css owns the shared `--tint-*` alpha scale; action role tokens (incl. `-ink` readable text), **per-theme `--code-*` syntax tokens** (tier 6 — the code editor, console/output JSON viewers, and chat code blocks paint in each theme's own palette: keyword→trigger, string→success, number→agent, function→model, on an adaptive dark/light code surface; replaced the global dracula `--prism-*` block + dead `getPrismTokenCSS`; the `OutputPanel` JSON viewer reads the same vars), per-theme `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-component decorative ornaments (panel textures + canvas decorations + node pseudo-element overlays + theme-specific keyframes), **canvas-node visual contract via `--node-color` CSS custom property** (no inline `background` / `border` on node components — base.css + per-theme CSS owns visuals; `NodeStyle` helper type at [types/NodeTypes.ts](./client/src/types/NodeTypes.ts) makes the inline custom-prop typecheck-clean), **`--node-pulse-color` separate from `--node-color`** so executing-node glow uses each theme's highest-contrast accent regardless of plugin accent (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine, etc.), **`data-page-hidden` animation pause** (toggled by Dashboard's `visibilitychange` listener; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyph system** (290 inline SVG glyph strings across 29 keys × 10 themes via [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts) + theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **decorative HTML primitives** (`<SvgFilterDefs>` mounting `#ink-blot` / `#noise` / `#crt` filter IDs at app root, `<DropCap>` wrapper for Renaissance ornament rule), **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), **per-theme scrollbar webkit rules** in all 12 themes, 9-event WebAudio sound system (10 packs via `--sound-pack` token + `useSound()` hook + global hover delegate + sonner toast monkey-patch + `withSound()` HOC + `Sounds.unlock()` gesture-unlock for AudioContext autoplay-policy compliance), `@media (prefers-reduced-motion: reduce)` accessibility, 30 ms throttle on `type` / `hover`, migration recipe, anti-patterns. Read this before adding a new theme, migrating a component to the new contract, or adding a canvas-node component. |
| **[Design System Bundle](./docs-internal/design-system/IMPLEMENTATION.md)** | Canonical, vendored design-system reference (extracted from this repo; see its `IMPLEMENTATION.md` for the contract). Tokens are **hex + `color-mix()`** (`tokens/{colors,typography,spacing,motion,fonts,base}.css`) — the format the live codebase standardizes on. Includes 34 reference components (`components/`, inline-style reference only — recreate in Tailwind/shadcn idioms), full-app UI kit (`ui_kits/opencompany/index.html`), 12-theme docs (`guidelines/THEMES.md`), **the merged handoff brief (`HANDOFF.md` — glow-ladder traps, step-edge contract, toolbar layout traps, canvas-layer asymmetries, plus the recorded product amendments)**, and **the panel×theme fidelity target (`reference-mockup/Panel Theme Matrix.dc.html` — 17 panels × 12 themes, open in a browser)**. `reference/themes/` no longer vendors CSS snapshots — it points at the authoritative [client/src/themes/](./client/src/themes/). Copy token values verbatim; do not re-derive by eye. Pairs with [Theme System](./docs-internal/theme_system.md). |
| **[Schema Source of Truth RFC](./docs-internal/ARCHIVE/schema_source_of_truth_rfc.md)** | *Archived — shipped.* Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons; `VITE_NODESPEC_BACKEND` defaults on and the frontend node definitions are gone. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<plugin>/__init__.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. Current reference: [Plugin System](./docs-internal/plugin_system.md). |
@@ -28,8 +28,8 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Pricing Service](./docs-internal/pricing_service.md)** | Centralized cost tracking for LLM tokens and API services (Twitter, Google Maps) with HTTPX event hooks |
| **[Proxy Service](./docs-internal/proxy_service.md)** | Residential proxy provider management with template-based URL formatting, health scoring, and transparent HTTP node injection |
| **[Email Service](./docs-internal/email_service.md)** | IMAP/SMTP integration via Himalaya CLI with EmailService orchestrator, provider presets, custom credential fallback, and polling triggers |
-| **[Browser](./docs-internal/browser.md)** | Current `browser` node: installed Chrome/Edge/Chromium in a dedicated profile rendered inside the workspace by default (`BROWSER_RUNTIME=system`, `BROWSER_HEADLESS=true`) and pinned browser-use CLI. Chrome for Testing requires explicit `BROWSER_RUNTIME=testing`. System mode retains the native user agent and OS password-store/keychain integration; basic/mock keychain flags are restricted to testing mode. Includes persistent employee/shared profiles, session leases, agent/user handoff, network policy, screenshots as workspace FileRefs and authenticated `/ws/browser` live viewing. Plugin-owned installation is lazy (`_install_chrome.py`, `_install_bu.py`); importing or shutting down the plugin never installs it. Replaces the former agent-browser and separate `browserHarness` implementations. |
-| **[Browser Workspace](./docs-internal/browser_workspace.md)** | Home and Dev share `WorkspaceTabs` and `BrowserWorkspace`: Browser / Canvas / Android, capability-based discovery, binary JPEG frames, bounded frame credit and decoding, Take control / Hand back, visibility cleanup and payload-free opt-in diagnostics. Android remains a placeholder. |
+| **[Browser](./docs-internal/browser.md)** | Current `browser` node: installed Chrome/Edge/Chromium in a dedicated profile rendered inside the workspace by default (`BROWSER_RUNTIME=system`, `BROWSER_HEADLESS=true`) and pinned browser-use CLI. Chrome for Testing requires explicit `BROWSER_RUNTIME=testing`. System mode retains the native user agent and OS password-store/keychain integration; basic/mock keychain flags are restricted to testing mode. Includes persistent employee/shared profiles (the Credentials / Connectors "Web browser" panel adds, deletes and imports logins from a session file; the node's profile dropdown lists only the caller's profiles, via `current_load_options_principal()`), session leases, agent/user handoff, network policy, screenshots as workspace FileRefs and authenticated `/ws/browser` live viewing. Plugin-owned installation is lazy (`_install_chrome.py`, `_install_bu.py`); importing or shutting down the plugin never installs it. Replaces the former agent-browser and separate `browserHarness` implementations. |
+| **[Browser Workspace](./docs-internal/browser_workspace.md)** | Home and Dev share `WorkspaceTabs` and `BrowserWorkspace`: Browser / Canvas / Android, capability-based discovery, binary JPEG frames, bounded frame credit and decoding, Take control / Hand back, visibility cleanup and payload-free opt-in diagnostics. The Browser node's parameter panel shows the same viewer, and the Dev dock opens on its Browser tab when an agent in the open workflow asks for help (`browser_updated`). Android remains a placeholder. |
| **[WhatsApp Business Service](./docs-internal/whatsapp_business_service.md)** | Official Meta Cloud API plugin in [`server/nodes/whatsapp_business/`](./server/nodes/whatsapp_business/) — **distinct from `nodes/whatsapp/`**, which is a personal account over an unofficial Go bridge; they share no node type, credential or palette group. Four nodes: `whatsappBusinessSend` (10 ops — Meta models message type as a *field* on one `/messages` endpoint, so text / media / template / interactive are operations, not nodes), `whatsappBusinessMedia` (the one genuinely separate endpoint family), and the `Receive` / `Status` triggers (kept separate because a canary trigger registers exactly one CloudEvents type). `phone_number_id` is deliberately **absent from Params** — on a dual-purpose ActionNode `execute_as_tool` merges `{**node_params, **tool_args}`, so a declared field is model-settable and a prompt injection could choose the sending identity; it comes from the credential only. Webhook via `register_webhook_source` on the shared catch-all, `X-Hub-Signature-256` HMAC failing closed, composite `wamid:status` dedup ids so `sent→delivered→read` don't collapse. |
| **[Stripe Service](./docs-internal/stripe_service.md)** | Stripe CLI integration — `stripeAction` (CLI pass-through) + `stripeReceive` (signed-webhook trigger). Reference plugin for the Wave 12 event framework AND the **CLI-managed-auth pattern**: browser OAuth via `stripe login --non-interactive` + `--complete <url>` (URL extracted from `next_step` shell command via `shlex.split`) + auto-installed binary (`ensure_stripe_cli` from GitHub releases) + marker-token reuse of `auth_service.store_oauth_tokens` + CloudEvents-shaped `broadcast_credential_event("credential.oauth.connected" \| ".disconnected", provider=...)` — zero per-provider hardcoding in the frontend. Daemon stdout/stderr ingested via `ProcessService`'s `line_handler` callback (no log-file tailing); credential gate routed through `await self.has_credential()` so non-api-key auth (`is_logged_in()`) plugs in via subclass override. |
| **[Vercel Service](./docs-internal/vercel_service.md)** | Vercel CLI integration — `vercelAction` (deploy / inspect / list + `custom` CLI passthrough; AI tool `vercel`). Second reference for the CLI-managed-auth pattern: the **device-flow variant** (`vercel login` is one blocking process — no two-step `--complete`; direct `create_subprocess_exec` + chunk-based banner read for the code-embedding URL, pumps drain pipes for the process lifetime, success gate = auth.json mtime advance + sniff). Dual auth: optional `vercel_token` field (injected as `VERCEL_TOKEN` env, never argv) OR CLI login with marker tokens. All invocations pin `--global-config <DATA_DIR>/vercel/` (the `CLAUDE_CONFIG_DIR` isolation idiom). `bun add` into the shared packages tree (pinned version, via `core/js_runtime.add_package`; the CLI runs on bun). First-deploy project guard raises `NodeUserError` instead of letting Vercel derive an invalid name from the workspace dir. Shipped with the generic OAuthConnect change: Login gates on **required** fields only, so optional fields never block CLI login. |
diff --git a/docs-internal/browser.md b/docs-internal/browser.md
index eb68799e..28a4536f 100644
--- a/docs-internal/browser.md
+++ b/docs-internal/browser.md
@@ -95,6 +95,20 @@ directory IDs rather than user-supplied names. A saved `profile_id` selects an
owner-scoped profile; leaving it empty creates/reuses the workflow's profile.
The CLI receives its own per-profile home, runtime and temporary directories.
+The node's profile dropdown (`browserProfiles` option loader) lists the
+caller's own profiles. It reads the caller from
+`services.ws_handler_registry.current_load_options_principal()`, which the
+load-options handlers set from the authenticated socket or HTTP request; a
+`user_id` in the request parameters is never trusted. The **Web browser**
+entry in Credentials and Normal-mode Connectors (panel kind
+`browserProfiles`, `components/credentials/panels/BrowserProfilesPanel.tsx`)
+lists the caller's profiles with their sites as domains and cookie counts,
+adds and deletes shared profiles, and imports logins from a session file:
+Playwright storage state, Cookie-Editor JSON or `cookies.txt`, uploaded to
+`POST /api/browser/profiles/{id}/session-file` and applied with
+`browser_import_commit`. To sign in by hand, use Take control in the
+workspace.
+
The profile version guard checks the browser executable actually selected, not
the testing pin. A browser older than the version that last wrote the profile
is skipped during automatic discovery, or rejected with actionable guidance
@@ -122,6 +136,23 @@ traffic. `allow_private_network` does not permit OpenCompany's protected ports
or cloud metadata endpoints. This network enforcement is separate from the
control lease and from agent read-only behavior.
+## Normal mode
+
+Hire attaches a browser through the **Web browser** app (`web` in
+[`config/employee_apps.json`](../server/config/employee_apps.json)). Its
+catalogue entry, `browser`, has nothing to connect (`connected_check:
+builtin`), so it never blocks Start; a missing installed browser shows up at
+the first browser step instead. With "Ask me before sending anything" on,
+the tool is attached with its `ask_first_params`, `interaction: read_only`:
+the agent reads pages and hands any change to the owner through
+`request_user`. The employee's instructions say when to call it.
+
+While the agent waits in `request_user`, the plugin's node-state source
+(`services/employees/node_signals.py`) reports `awaiting_user`, and the
+employee summary carries `browser_request` (`{node_id, reason, since}`, never
+the agent's message). See [Normal mode](./normal_mode.md) and
+[Browser workspace](./browser_workspace.md#when-the-agent-asks-for-help).
+
## Node contract and compatibility
The tool schema exposes navigation, snapshots, element interaction, screenshots,
diff --git a/docs-internal/browser_workspace.md b/docs-internal/browser_workspace.md
index 7d777351..c96f3fe2 100644
--- a/docs-internal/browser_workspace.md
+++ b/docs-internal/browser_workspace.md
@@ -17,6 +17,8 @@ Canvas boards, push notifications and temporary file previews still use
`canvasDockStore`. Its selected tab is persisted. A Canvas push does not
switch an already-open Browser tab; explicitly opening a file preview does
switch to Canvas. Android currently has an explanatory panel, not a live mirror.
+The Browser node's parameter panel (`MiddleSection`, `isBrowserPanel`) shows
+the same viewer above the node's settings.
## Discovery and identity
@@ -30,6 +32,22 @@ browser calls the authorized `browser_session_open` handler. Unsaved workflows
must be saved first. Adding a node to an existing workflow must also be saved
before the server can authorize it.
+## When the agent asks for help
+
+`request_user` puts the profile's controller in `awaiting_user`. The viewer
+shows the agent's message, which arrives on the live socket's `state`
+message. Elsewhere only identity and the reason travel, because broadcasts
+and employee summaries reach every connected socket:
+
+- **Home:** the employee summary's `browser_request` (`{node_id, reason,
+ since}`) turns the pill to Needs you, the server's task line names the
+ reason, and Watch live becomes Help in browser, which opens the workspace on
+ its Browser tab. The live task overlay stands back meanwhile, since the
+ agent's node is still executing while it waits.
+- **Dev:** a `browser_updated` broadcast for the open workflow in
+ `awaiting_user` opens the dock on its Browser tab
+ (`canvasDockStore.showBrowser`).
+
## Transport and display
The dedicated same-origin `/ws/browser` socket uses the application's auth
@@ -196,6 +214,10 @@ benchmark script: 283e28a5afa86c16370e39b989b8d800462b940d1e81f6755f29bded129a
browser discovery integration, tab changes and hidden dock state.
- `client/src/components/ui/__tests__/WorkspaceDock.test.tsx`: Dev tabs, schema
hydration and viewer unmount on close.
+- `client/src/features/home/__tests__/presentation.test.ts`: Needs you while the
+ agent waits in the browser.
+- `client/src/stores/__tests__/canvasDockStore.test.ts`: a Canvas push never
+ leaves a live browser; `showBrowser` opens the Browser tab.
- `server/tests/nodes/browser/test_browser_stream.py`: fake-CDP startup failure
recovery and cancellation.
- `server/tests/nodes/browser/test_browser_frame_delivery.py`: trailing frames,
@@ -203,4 +225,5 @@ benchmark script: 283e28a5afa86c16370e39b989b8d800462b940d1e81f6755f29bded129a
- `server/tests/nodes/browser/test_browser_live_control.py`: bounded input queues,
responsive receive loop, takeover/release races, held-input cleanup and teardown.
- `server/tests/services/employees/test_list_employees.py`: capability-based
- browser discovery in employee summaries.
+ browser discovery in employee summaries, and the browser request (never the
+ agent's message).
diff --git a/docs-internal/desktop_app.md b/docs-internal/desktop_app.md
index 253bc708..10e3c10d 100644
--- a/docs-internal/desktop_app.md
+++ b/docs-internal/desktop_app.md
@@ -27,7 +27,7 @@ produced this feature. Short form:
`uv.lock` / `pyproject.toml` / the bundled Python changes. OpenCompany
already provisions at first run (`install.js` runs `uv sync`, Temporal and
the plugin CLIs (`bun add` into `~/.opencompany/packages/`) download on
- first use, `browser_harness` needs `uv` at runtime), so uv ships in every
+ first use, the Browser node installs the browser-use CLI with `uv tool install`), so uv ships in every
design.
## Layout
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index f6ebee27..eae822ac 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -246,7 +246,10 @@ contract the frontend sees does not change. Normal mode's two events follow
the same rule: `employee_lifecycle` (`com.opencompany.employee.*`, in
`services/employees/events.py`) and `approval_lifecycle`
(`com.opencompany.approval.*`, in `nodes/workflow/approval_gate/_events.py`,
-identity only). See [normal_mode.md](./normal_mode.md#wire-contract).
+identity only). See [normal_mode.md](./normal_mode.md#wire-contract). So do
+the Browser plugin's `browser_updated`, `browser_profiles_updated` and
+`browser_runtime` (`com.opencompany.browser.*`, in `nodes/browser/_events.py`;
+identity and state only, never a URL, a page title or cookie data).
Rule of thumb: **if no `register_canary_trigger_type` call names your event
type, broadcast it directly.** Reach for `emit` only when a Temporal workflow
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 0f6360cc..ac98c7dd 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -109,6 +109,7 @@ client/src/
│ │ │ ├── OAuthPanel.tsx # Twitter / Google / Telegram
│ │ │ ├── QrPairingPanel.tsx # WhatsApp / Android
│ │ │ ├── EmailPanel.tsx # IMAP/SMTP (RHF + zod)
+│ │ │ ├── BrowserProfilesPanel.tsx # Web browser login profiles: list / add / delete, session-file import
│ │ │ └── schemas/email.ts # Email zod schema w/ superRefine
│ │ ├── sections/
│ │ │ ├── ApiUsageSection.tsx # Per-service usage/cost
@@ -382,7 +383,7 @@ components/credentials/catalogueAdapter.ts (hydrate JSON -> ProviderConfig)
▼
components/credentials/CredentialsModal.tsx
├─ CredentialsPalette.tsx (cmdk + fuzzysort + GroupedVirtuoso)
- └─ PanelRenderer.tsx (lazy: ApiKey/OAuth/QrPairing/Email)
+ └─ PanelRenderer.tsx (lazy: ApiKey/OAuth/QrPairing/Email/BrowserProfiles)
```
**State rules:**
@@ -500,7 +501,7 @@ See [media_transport.md](./media_transport.md).
## Browser workspace live view
-Home and Dev share [WorkspaceTabs](../client/src/components/workspace/WorkspaceTabs.tsx) and [BrowserWorkspace](../client/src/components/browser/BrowserWorkspace.tsx). Browser nodes are discovered through the backend `isBrowserPanel` capability; viewing attaches to a saved workflow/node without launching Chrome. The runtime defaults to installed Chrome/Edge/Chromium with a dedicated profile rendered headless inside the workspace; a separate desktop window and testing-browser mode are explicit server settings. The Browser tab supports server-authorized Take control / Hand back for navigation, mouse, keyboard, paste and login. Canvas retains its renderer; Android remains an explanatory placeholder.
+Home and Dev share [WorkspaceTabs](../client/src/components/workspace/WorkspaceTabs.tsx) and [BrowserWorkspace](../client/src/components/browser/BrowserWorkspace.tsx). Browser nodes are discovered through the backend `isBrowserPanel` capability; viewing attaches to a saved workflow/node without launching Chrome. The runtime defaults to installed Chrome/Edge/Chromium with a dedicated profile rendered headless inside the workspace; a separate desktop window and testing-browser mode are explicit server settings. The Browser tab supports server-authorized Take control / Hand back for navigation, mouse, keyboard, paste and login. The Browser node's parameter panel shows the same viewer above its settings. When an agent in the open workflow calls `request_user`, the `browser_updated` case in `WebSocketContext` opens the Dev dock on its Browser tab (`canvasDockStore.showBrowser`); Home shows Needs you from the employee summary's `browser_request`. Canvas retains its renderer; Android remains an explanatory placeholder.
The viewer uses a separate authenticated same-origin `/ws/browser` socket, not the general `WebSocketContext` frame stream. Binary JPEG envelopes are decoded sequentially with a two-frame local bound; consumed/skipped frames are acknowledged. Canvas dimensions change only when image dimensions change, and input coordinates use the metadata of the frame actually painted. Hidden, disposed or obsolete frames cannot restore a stale picture. Blur, pointer cancellation, hiding and unmount release user control; the server owns the release barrier and lease checks.
@@ -554,6 +555,7 @@ Defined on `INodeTypeDescription.uiHints` ([client/src/types/INodeProperties.ts]
| `isProcessManagerPanel` | `MiddleSection` | Render live managed-process inspection and controls |
| `isGalleryPanel` | `MiddleSection` | Render the workspace file browser (breadcrumbs, grid/list, search, preview, upload, drag-to-parameter) instead of the plain params list. Declared by `gallery`, which pairs it with `hideInputSection` but **keeps** the Output section — unlike `processManager` it produces output worth seeing and dragging. The panel writes back to the node's own `path` / `selection` params, so what you browse is what the node emits. |
| `isCanvasPanel` | `MiddleSection`, `CanvasDock` | Render the pushed-content Canvas board instead of the plain params list. Declared by `canvas`. Double duty: the docked canvas sidebar also uses this flag to FIND Canvas nodes in the graph (`resolveNodeDescription(type)?.uiHints?.isCanvasPanel`) — never the type string. Pairs with an explicit `isConfigNode: False` because the `tool` group would auto-derive `True` while the node's `input-main` is real dataflow. See [canvas_node.md](./canvas_node.md). |
+| `isBrowserPanel` | `MiddleSection`, `CanvasDock` (also the server's `graph_index`) | Show the node's live browser (`BrowserWorkspace`) above its parameters. Declared by `browser`. The Dev dock and Home's employee summary also use it to FIND Browser nodes in a graph, never the type string. See [browser_workspace.md](./browser_workspace.md). |
| `showLocationPanel` | `LocationParameterPanel` | Special-case panel for nodes with map preview |
| `isChatTrigger` | `ConsolePanel` | This node is a chat-message target |
| `isConsoleSink` | `ConsolePanel` | This node consumes console output (filter source) |
diff --git a/docs-internal/node-logic-flows/web_automation/browser.md b/docs-internal/node-logic-flows/web_automation/browser.md
index ea4da6e9..663297db 100644
--- a/docs-internal/node-logic-flows/web_automation/browser.md
+++ b/docs-internal/node-logic-flows/web_automation/browser.md
@@ -55,7 +55,7 @@ The profile is persistent across executions; it is not the old execution-ID-name
## Policy and control
-Operator settings include `profile_id`, `interaction` (`full` or `read_only`), `webmcp_mode` (`disabled`, `read_only`, `all`), `allowed_domains`, `allow_private_network`, `op_timeout_s` (default 45, range 5–300), and `request_user_timeout_s` (default 600, range 60–1800). They are server-controlled for tool calls.
+Operator settings include `profile_id`, `interaction` (`full` or `read_only`), `webmcp_mode` (`disabled`, `read_only`, `all`), `allowed_domains`, `allow_private_network`, `op_timeout_s` (default 45, range 5–300), and `request_user_timeout_s` (default 600, range 60–1800). They are server-controlled for tool calls. The `profile_id` dropdown (`browserProfiles` loader) lists only the caller's own profiles; the loader takes the caller from the authenticated request, never from its parameters.
The current `MUTATING` set is exactly `click`, `type`, `press`, `select`, `back`, `forward`, `reload`, `webmcp_call`, `evaluate`, and `run_python`. `read_only` rejects this set. It does not prohibit navigation, scrolling, hovering or tab operations. In particular, `webmcp_call` is rejected by `interaction=read_only` before its tool-level read-only metadata is considered; `webmcp_mode=read_only` with full interaction is the setting that admits advertised read-only WebMCP tools.
@@ -65,6 +65,10 @@ Control states are `idle`, `agent`, `awaiting_user`, and `user`. `request_user`
The authenticated live viewer attaches through `/ws/browser` to a saved workflow/node or a profile-login session. Watching does not grant control. Takeover, handback, visibility and disconnect are coordinated with the profile controller. Live mouse/keyboard/navigation commands use a bounded ordered queue and direct CDP, independently of the subprocess CLI path used by node operations. Frame acknowledgements and visibility messages remain responsive while commands run. Handback settles dispatched input and releases held keys/buttons before agent work resumes. See [browser workspace](../../browser_workspace.md) for frame delivery and frontend lifecycle.
+## Normal mode
+
+Hire adds this node through the **Web browser** app (`web` in `config/employee_apps.json`, recorded under the employee's `browser` role). With "Ask me before sending anything" on, it is attached with `interaction=read_only`, so the agent reads pages and hands any change to the owner through `request_user`. While the agent waits there, the employee summary's `browser_request` (`{node_id, reason, since}`) makes Home show Needs you and Help in browser; the agent's message itself stays in the live viewer.
+
## Output and failures
Outputs can include `operation`, `session_id`, profile name, `url`, `title`, `tab_id`, `snapshot`, `text`, `truncated`, screenshot FileRef, tabs, WebMCP tools/results, handoff result, `data`, and `notice`. Screenshot bytes are not embedded in node output; saving failure produces a notice. `run_python` may return the final 20,000 characters of captured script output.
diff --git a/docs-internal/normal_mode.md b/docs-internal/normal_mode.md
index e983dbc5..687a75b6 100644
--- a/docs-internal/normal_mode.md
+++ b/docs-internal/normal_mode.md
@@ -130,7 +130,9 @@ the team.
summary. Multiple nodes get a selector. Running sessions appear automatically;
Start browser opens an idle session. The view supports navigation, tabs,
Take control / Hand back, and browser dialogs. Frames use `/ws/browser`,
- not a URL iframe. See [Browser workspace](./browser_workspace.md).
+ not a URL iframe. The card's Help in browser opens the Workspace on this
+ tab while the agent waits for the owner. See
+ [Browser workspace](./browser_workspace.md).
- **Android**: a shared panel explains that live mirroring is not yet available.
Dev mode uses the same three workspace tabs and browser viewer.
- **Size and motion**: 460px wide by default. The left edge drags from
@@ -314,7 +316,8 @@ changing page clears it.
cannot silently miss the page. They are listed in category order, so apps
come before AI models. The catalogue adds `connected`, which differs from
`stored` for providers with a `connected_check` (WhatsApp's live pairing,
- the IMAP/SMTP account's keys).
+ the IMAP/SMTP account's keys; `builtin`, always connected, for the Web
+ browser, whose panel manages optional login profiles).
**The catalog page** ([settings/CatalogLayout.tsx](../client/src/features/home/settings/CatalogLayout.tsx)).
Skills, Connectors and Plugins are built on a shared page:
@@ -338,7 +341,7 @@ WebSocket requests (snake_case; failures come back as `success: false` with an
| Type | Payload | Response |
|---|---|---|
-| `list_employees` | `{}` | `{employees}`; each summary's `canvas_node_id` is its Canvas board: the one it was hired with, else the graph's first Canvas node, else null |
+| `list_employees` | `{}` | `{employees}`; each summary's `canvas_node_id` is its Canvas board: the one it was hired with, else the graph's first Canvas node, else null. `browser_request` is a browser waiting for the owner (`{node_id, reason, since}`), else null |
| `get_employee` | `{workflow_id}` | the summary plus `description`, `job`, `plan`, `rules`, `choices`, `trigger_text`, `last_run`, `latest_report` |
| `get_employee_usage` | `{}` | `{tasks_this_month}` (successful runs since the 1st, owner's timezone, whole team) |
| `generate_employee_setup` | `{job, refine?, history?, draft_token}` | `{draft_token, reply, provider, model, usage, retried, finish_reason, apps}` |
@@ -353,7 +356,7 @@ consumer; see [Event Framework](./event_framework.md#ui-only-lifecycle-events-br
| Wire key | Type | Notes |
|---|---|---|
-| `employee_lifecycle` | `com.opencompany.employee.{hired,updated,removed}` | Subject is the workflow id; `updated` is coalesced to one per second per employee, except control changes, which go out at once |
+| `employee_lifecycle` | `com.opencompany.employee.{hired,updated,removed}` | Subject is the workflow id; `updated` is coalesced to one per second per employee, except control changes and browser control changes (each agent step, and the wait for the owner), which go out at once |
| `approval_lifecycle` | `com.opencompany.approval.{requested,decided,expired,cancelled}` | Identity only, never the message or the recipient |
| `workflow_lifecycle` | gains `created` and `deleted` stages | So open editors refresh their workflow lists |
@@ -390,6 +393,10 @@ history). Client: `features/home/**/__tests__`, `app/__tests__`,
`canvas_node_id` is null. Adding one in Dev mode fills it in.
- The Workspace's Android tab has no live mirror yet. Browser now uses the
shared live viewer described above; timeline and replay are not available.
+- The Web browser app counts as connected even on a machine with no
+ installed Chrome, Edge or Chromium; the employee's first browser step
+ reports it. An employee hired before the app existed has no browser;
+ adding a Browser node in Dev mode gives it one.
- With login on, an agent's Canvas writes land under the default owner:
its tool call carries no user id
([agent_workflow.py](../server/services/temporal/agent_workflow.py)).
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index c0f619b0..df04e998 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -574,7 +574,7 @@ per node type) — same pattern as every other folder.
|---|---|---|
| Credentials-modal WebSocket commands (Connect / Disconnect / Send / Status / etc.) | `services.ws_handler_registry` | `register_ws_handlers({type: handler, ...})` |
| FastAPI HTTP router (OAuth callbacks, webhook receivers, etc.) | `services.ws_handler_registry` | `register_router(router, name='<plugin>')` — Wave 11.I; declare a `_router.py` exposing an `APIRouter` and call from `__init__.py`. Discovered at startup via `services.ws_handler_registry.get_routers()`. |
-| `loadOptionsMethod` async loader for a dynamic dropdown (`json_schema_extra={"loadOptionsMethod": "..."}`) | `services.ws_handler_registry` | `register_option_loader(method_name, fn)` |
+| `loadOptionsMethod` async loader for a dynamic dropdown (`json_schema_extra={"loadOptionsMethod": "..."}`). A loader that lists one user's things reads the caller from `current_load_options_principal()`, never a `user_id` in its params (the client writes those) | `services.ws_handler_registry` | `register_option_loader(method_name, fn)` |
| OAuth callback path (`/api/<provider>/callback`) so `services.oauth_utils.get_redirect_uri` never cross-imports `nodes/<plugin>/_oauth.py` | `services.ws_handler_registry` | `register_oauth_callback_path(provider, path)` |
| Trigger event-filter builder | `services.event_waiter` | `register_filter_builder(node_type, fn)` |
| Trigger pre-execution check (e.g. "bot not connected") | `services.event_waiter` | `register_trigger_precheck(node_type, fn)` |
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index efdf85cd..ca4fc0ad 100644
--- a/docs-internal/release_build_pipeline.md
+++ b/docs-internal/release_build_pipeline.md
@@ -196,7 +196,7 @@ Idempotent on re-runs (compileall only rewrites stale pyc; `bun build` is determ
## Desktop installers
-The Electron shell has its own pipeline (`.github/workflows/desktop-release.yml`) that consumes this one's outputs (`client/dist`, the sidecar bundle) and adds the bundled runtimes; it is documented in [desktop_app.md](./desktop_app.md). Nuitka / PyOxidizer freezing was evaluated and rejected there: `temporalio`'s PyO3 bridge, `dependency-injector` wiring by string, `pkgutil.walk_packages` plugin discovery and `uv tool install browser-harness` at runtime all need a real interpreter on disk.
+The Electron shell has its own pipeline (`.github/workflows/desktop-release.yml`) that consumes this one's outputs (`client/dist`, the sidecar bundle) and adds the bundled runtimes; it is documented in [desktop_app.md](./desktop_app.md). Nuitka / PyOxidizer freezing was evaluated and rejected there: `temporalio`'s PyO3 bridge, `dependency-injector` wiring by string, `pkgutil.walk_packages` plugin discovery and the Browser node's `uv tool install` of the browser-use CLI at runtime all need a real interpreter on disk.
## Out of scope (future work)
diff --git a/docs-internal/status_broadcaster.md b/docs-internal/status_broadcaster.md
index 82c20a94..83e9fd2f 100644
--- a/docs-internal/status_broadcaster.md
+++ b/docs-internal/status_broadcaster.md
@@ -152,6 +152,9 @@ Broadcasts are sent to all connected clients without a request-response correlat
| `compaction_completed` | Memory compaction ends | `{session_id, success, tokens_before, tokens_after}` |
| `context.updated` | A conversation durably saved (`save_conversation` upsert), or cleared from the panel / workflow Reset — emitted from the store's save boundary via `register_conversation_listener`, so every writer (in-process loop, Temporal LLM activity, specialized-provider bridge) is covered without call-site code. Frontend invalidates `['agentContext']`. | `{specversion: "1.0", id, source: "opencompany://nodes/context", type: "com.opencompany.context.updated", subject: agent_node_id, time, data: {workflow_id, generation, agent_node_id, message_count}}` |
| `memory.updated` | A durable Memory mutation (remember / update / forget / clear) from either writer — the agent's tool call or the panel handlers. Frontend invalidates `['memoryItems']` + `['memoryItem']`. | `{specversion: "1.0", id, source: "opencompany://nodes/simple_memory", type: "com.opencompany.memory.updated", subject: memory_node_id, time, data: {workflow_id, memory_node_id, operation}}` |
+| `browser_updated` | A Browser profile's control state changes (`idle` / `agent` / `awaiting_user` / `user`), from `nodes/browser/_session.py`. Identity and state only; the live viewer reads the details over `/ws/browser`. Frontend opens the Dev dock on its Browser tab when the open workflow's browser reaches `awaiting_user`. | `{specversion: "1.0", id, source: "opencompany://nodes/browser", type: "com.opencompany.browser.updated", subject: session_id, time, data: {workflow_id, node_id, session_id, state, revision}}` |
+| `browser_profiles_updated` | A Browser profile is added, renamed, deleted or gets new logins. Frontend invalidates `['browserProfiles']` (the Credentials "Web browser" panel). | `{specversion: "1.0", id, source: "opencompany://nodes/browser", type: "com.opencompany.browser.profiles.updated", subject: "profiles", time, data: {revision}}` |
+| `browser_runtime` | Chrome for Testing download progress (`BROWSER_RUNTIME=testing` only; `_install_chrome.py`). No frontend case; the viewer polls `browser_runtime_status` while it waits. | `{specversion: "1.0", id, source: "opencompany://nodes/browser", type: "com.opencompany.browser.runtime.progress", subject: component, time, data: {component, phase, percent, version, error}}` |
`context.updated` and `memory.updated` call
`get_status_broadcaster().broadcast(...)` directly rather than
diff --git a/server/skills/GUIDE.md b/server/skills/GUIDE.md
index 03401831..cce50c83 100644
--- a/server/skills/GUIDE.md
+++ b/server/skills/GUIDE.md
@@ -42,7 +42,7 @@ server/skills/
├── vercel/ # vercel-skill (Vercel CLI)
├── vertex_agent/ # vertex-agent-skill, vertex-agent-admin-skill
└── web_agent/ # Web automation skills
- browser-skill, browser-harness-skill, http-request-skill, apify-skill,
+ browser-skill, http-request-skill, apify-skill,
crawlee-scraper-skill, tikhub-skill, proxy-config-skill, duckduckgo-search-skill,
brave-search-skill, serper-search-skill, perplexity-search-skill
```