Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(browser): complete deployment, credentials and validation guides
trohitg37fe83d798f4
diff --git a/CLAUDE.md b/CLAUDE.mdindex bcd55e04..436b4173 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -46,7 +46,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Media Transport](./docs-internal/media_transport.md)** | How files move through the engine, and why they move as **references rather than bytes**. `services/media/` — `FileRef` (the base; `FileKind = file\|audio\|image\|video\|document`) with `AudioRef(FileRef)` as the probed-container narrowing (~400 B, `extra="forbid"` so adding a bytes field is a `ValidationError` rather than a silent regression), `write_audio` / `resolve_media` / `coerce_file_param` (the one nodes should call — accepts a `FileRef`/`AudioRef`, a bare path, or the legacy base64 envelope), `inspect_audio` (tinytag → stdlib `wave` → PCM arithmetic, **never raises**), `limits.py`, and **`preview.py` — the single owner of the inline-vs-attachment rule**, with two consumers: `routers/workspace.py` picks its `Content-Disposition` from `serves_inline`, and the gallery listing sets each row's `preview` from `preview_kind`, so the panel can never offer a preview the route refuses to serve. Containment runs through `resolve_within`, which closed a live vulnerability: a node joined a user path onto the workspace root unchecked, so `audio_file="../../credentials.db"` read the encrypted credential store and uploaded it. **The id/slug asymmetry is the trap** — workspace dirs are named by the mutable `Workflow.slug` while a ref stores the immutable `workflow_id` so refs survive rename; the lookup lives in [`services/workspace_locator.py`](./server/services/workspace_locator.py) (`resolve_workspace_root(..., allow_default=)`), and **every mutating caller must pass `allow_default=False`** or an unresolvable id silently lands the write in the shared anonymous workspace. HTTP surface in [`routers/workspace.py`](./server/routers/workspace.py): Range support comes free from Starlette's `FileResponse`; `NEVER_INLINE` is `{image/svg+xml, text/html, text/xml, application/xhtml+xml}` because `shell` / `fileDownloader` / `fileModify` can write arbitrary files into a workspace. || **[Data Node & Vision](./docs-internal/data_node.md)** | The `dataSource` agent tool (raw local data over two namespaces: workspace paths + operator-approved `mnt/<name>/...` external mounts with per-mount writable flags; typed bounded read tiers text/csv/json/pdf/html/xlsx/image-metadata/binary; write/append but **no delete**; `copy_to_workspace` imports mount files as real FileRefs), the machine-wide `data_mounts` allowlist (`services/data/mount_store.py` — refuses `DATA_DIR` overlap, drive roots, home dir), the `visionAnalyze` delegate tool (vision for every host model via openai/anthropic/gemini official SDK shapes + the `services/media/image_fit.py` visual-token budget), and the first native-image-blocks increment: `ContentBlock.source` (durable `file_ref` vs transient `bytes` — the wire codec raises on bytes), the `llm_media` tool-result opt-in, capability-gated `hydrate_image_blocks` in `run_native_llm_step`, Anthropic `tool_result` image encoding (openai/gemini encoders pending; their `vision.enabled` stays false until then). || **[Canvas Node](./docs-internal/canvas_node.md)** | The `canvas` node — pushed-content display board (the Claude/ChatGPT-Canvas analog) in [`server/nodes/tool/canvas/`](./server/nodes/tool/canvas/). Dual control: agents call the locked `canvas(...)` tool (paths / url / 64KB-capped markdown notes, append/replace), workflow edges auto-display upstream FileRefs via a structural scan of `connected_outputs` (`tts → canvas` is a zero-config edge; the node is the one addition to `NodeExecutor._NEEDS_CONNECTED_OUTPUTS`). Board = plugin-owned `canvas_boards`/`canvas_items` tables (mount_store mechanism, 200-item FIFO), identity-only `canvas_updated` broadcast (direct, no canary consumer), `canvas_list/remove/clear` WS handlers with the simple_memory security preamble. **Three frontend hosts share one renderer**: the `isCanvasPanel` parameter panel, the docked resizable right sidebar (`CanvasDock` + `canvasDockStore`; auto-open via `notifyPushed`, ephemeral click-to-preview from the gallery dialog, `usePanelResize` extracted from ConsolePanel), and the Canvas tab of Home's Workspace dock (`features/home/workspace/`). Renders media carousel with follow-latest image poll, markdown/code/JSON via the repo's first capped client-side text fetch (`useWorkspaceText`, 512KB), external URLs + workspace HTML in strictly sandboxed iframes (never `allow-same-origin`; `NEVER_INLINE` untouched), and inline PDF via the `INLINE_EXACT` exact-match addition to `preview.py`. The current Browser node persists screenshots as workspace FileRefs through `nodes/browser/_screenshots.py`; live viewing uses the separate Browser workspace stream. Items have versions (the tool's `update_id` saves the next one; `canvas_item_versions` keeps the newest 50 per item; `canvas_version` reads one) and a note shows as a document (`NoteView`: ‹ v2/3 ›, Preview/Markdown, Copy, Download); a note the agent answering the owner writes is named on its reply (`services/chat/parts.show_artifact`) as a card that opens the board at that version (Home: `homeStore.openCanvasItem`; Dev: `canvasDockStore.focusItem`). |-| **[Translate / Transliterate / Detect](./docs-internal/speech_provider_rfc.md#8-what-this-pattern-should-absorb-next)** | The second application of the multi-vendor pattern, and the one that retired `nodes/sarvam/`. Three nodes (`translateText`, `transliterateText`, `detectLanguage`) in [`server/nodes/translate/`](./server/nodes/translate/), backed by **three registries — one per capability**, because the asymmetry is sharper than speech's: DeepL translates and does nothing else, while Sarvam and LLM-backed providers do all three. Membership makes an unsupported selection unrepresentable rather than a runtime failure inside a paid call. Providers: **deepl** (`Authorization: DeepL-Auth-Key`, `text` is an array, free keys ending `:fx` route to a different host, and it returns `billed_characters` so cost is the provider's own figure), **sarvam** (all three over dedicated REST), **openai** (all three via `ChatUnifier` — proves the Protocol does not care what a provider does internally; billing deliberately NOT recorded because that path bills tokens the LLM layer already costs). Capabilities in `server/config/translate_defaults.json`. |+| **[Translate / Transliterate / Detect](./docs-internal/speech_provider_rfc.md#8-the-pattern-generalised-nodestranslate)** | The second application of the multi-vendor pattern, and the one that retired `nodes/sarvam/`. Three nodes (`translateText`, `transliterateText`, `detectLanguage`) in [`server/nodes/translate/`](./server/nodes/translate/), backed by **three registries — one per capability**, because the asymmetry is sharper than speech's: DeepL translates and does nothing else, while Sarvam and LLM-backed providers do all three. Membership makes an unsupported selection unrepresentable rather than a runtime failure inside a paid call. Providers: **deepl** (`Authorization: DeepL-Auth-Key`, `text` is an array, free keys ending `:fx` route to a different host, and it returns `billed_characters` so cost is the provider's own figure), **sarvam** (all three over dedicated REST), **openai** (all three via `ChatUnifier` — proves the Protocol does not care what a provider does internally; billing deliberately NOT recorded because that path bills tokens the LLM layer already costs). Capabilities in `server/config/translate_defaults.json`. || **[Desktop App](./docs-internal/desktop_app.md)** | Electron shell in [`desktop/`](./desktop/) — a standalone bun package (NOT a root workspace member; `cli/tests/test_release_pipeline_config.py` locks `workspaces`). Bundles pinned `uv`, python-build-standalone CPython 3.12 and bun 1.4.0 — the only JavaScript runtime shipped; no Node, no npm (`desktop/runtimes.json`, verified against upstream checksum manifests by `scripts/fetch-runtimes.ts`, which also fetches bun's `LICENSE.md` from the bun repo — the release zip carries none — and prunes stale runtime dirs such as a leftover `node/`), stages the backend sibling layout from `bun pm pack --dry-run` (`scripts/stage.ts`, which runs the sidecar package's own `bun run build` — `bun build --target=bun`, express inlined — and copies `dist/index.js`), sets `OPENCOMPANY_BUN_BIN` / `BUN_INSTALL=<userData>/bun` / `BUN_INSTALL_CACHE_DIR` and prepends the bundled bun dir (then uv) to PATH for the backend (`env.ts`; `OPENCOMPANY_NODE_BIN` no longer exists), provisions the venv into Electron `userData` on first launch with `uv sync --frozen --python <bundled>` (stamp = sha256 of uv.lock + pyproject + Python + uv versions; falls back to `uv python install 3.12`), pre-warms `PYTHONPYCACHEPREFIX` (with a prefix set Python ignores in-tree .pyc — 32 s vs 3 s first boot), spawns uvicorn on `127.0.0.1:5678` (persisted port; attaches to a running `company serve` instead of double-spawning), waits on `/health/ready`, loads the backend-served SPA (zero frontend changes), routes `window.open` / `_blank` to the OS browser. Quit = `POST /api/desktop/shutdown` + stdin EOF, 30 s, then tree-kill. electron-builder: NSIS x64, DMG+zip arm64/x64, AppImage+deb x64, unsigned first (`mac.identity: null`; macOS auto-update notify-only until signed — Squirrel.Mac refuses unsigned). CI: `desktop-release.yml` (tag-triggered: `prepare` drafts the GitHub Release from the annotated tag's message, three legs build and upload version-less OS-named installers such as `OpenCompany-windows-x64.exe` / `OpenCompany-macos-arm64.dmg` / `OpenCompany-linux-x86_64.AppImage` so the README can link `releases/latest/download/<file>`, each leg refuses a desktop version that differs from the tag, `finalize` undrafts) and `desktop-ci.yml` (typecheck/unit/invariants/Playwright smoke). **Gotcha: editor-hosted terminals export `ELECTRON_RUN_AS_NODE=1`, which makes Electron boot as plain Node (`electron.app` undefined) — strip it before launching; the e2e test does.** || **[Desktop Host Contract](./docs-internal/desktop_host_contract.md)** | The backend's side of being owned by a GUI shell. `core/approot.py` is the ONE module that locates the app tree (`OPENCOMPANY_APP_ROOT` / `OPENCOMPANY_CLIENT_DIST` / `OPENCOMPANY_ENV_FILE` / `OPENCOMPANY_ENV_TEMPLATE`); `tests/test_no_root_climb.py` forbids any other `Path(__file__).parents[N]` climb above `server/` and any `"client"/"dist"` / `.env.template` / `package.json` path join. `core/env_defaults.apply_file_defaults_to_environ()` does the CLI's `.env.template < .env < process env` layering at the top of `main.py`, and `Settings.env_file` is the absolute `(template, .env)` tuple — so a shell spawns `python -m uvicorn` from any cwd without the CLI package. Desktop mode (`OPENCOMPANY_DESKTOP=1`, `core/desktop.py`): parent-PID watchdog with create-time PID-reuse guard, stdin-EOF watchdog (polling via `PeekNamedPipe`/`select`, never a blocking read — a daemon thread parked in `ReadFile` at finalisation crashed exit with 0xC0000005), ctypes Job Object so children die with the backend (no pywin32 in the server venv), token-gated `POST /api/desktop/shutdown` (`routers/desktop.py`, public path; raises the signal uvicorn handles so the lifespan reaps Temporal/the bun sidecar/edgymeow), 45 s hard deadline. `GET /health/ready` (public) = DB up AND (Temporal disabled OR worker manager started), with `phase` written by `services/temporal/lifecycle.py` (`installing_temporal` / `starting_temporal` / `connecting` / `starting_workers` / `ready`). Plugin shutdown hooks now run under a 10 s per-hook timeout (`HOOK_TIMEOUT_SECONDS`), and the current browser hook uses `peek_browser_runtime()` so shutdown never constructs or installs the runtime. Historical incident: the retired `get_browser_service()` lazily installed agent-browser at shutdown and wedged graceful exit (masked under the CLI by its 5 s grace + tree-kill). `server/uv.lock` is committed; `predeploy.yml` runs `uv lock --check`. || **[CI/CD Pipeline](./docs-internal/ci_cd.md)** | GitHub Actions workflows, predeploy validation, release publishing, and the composite setup action (bun via SHA-pinned `oven-sh/setup-bun` reading the root `packageManager` pin + Node 22 as a CI-only convenience so bun runs vite / vitest / eslint on it via their node shebangs + Python 3.12 + uv; `bun install --frozen-lockfile` everywhere; publish is `bun publish --access public` after a `bun pm whoami` credential preflight with `~/.npmrc` written from `NPM_TOKEN` — no npm CLI, no `setup-node` step of their own in the publish jobs (they get Node through the composite action), and npm provenance attestation went away with npm). Also **Cutting a release**: the annotated tag is the version and its message is the release notes; `company version sync vX.Y.Z` bumps every version file for the `chore(release)` commit the tag sits on, and `desktop-release.yml` drafts the GitHub Release from the tag message and refuses a version that differs from the tag |@@ -1748,7 +1748,7 @@ Android services use a factory pattern with `createAndroidServiceNode()` for conunder `server/nodes/android/<service>.py`. Each plugin subclasses theshared `AndroidServiceBase` (see `server/nodes/android/_base.py`), whichhandles ADB dispatch via `SERVICE_ID_MAP`. See the-[Android Services Development Guide](./docs-internal/plugin_system.md#android).+[Plugin development guide](./docs-internal/plugin_system.md).Adding a new Android service:diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.mdindex bf17186f..c71dc9c6 100644--- a/docs-internal/SETUP.md+++ b/docs-internal/SETUP.md@@ -167,13 +167,29 @@ the arrangement is [desktop_host_contract.md](./desktop_host_contract.md).[control lifecycle, recovery and verification](temporal-workflow-control.md).- See [Temporal Architecture](./TEMPORAL_ARCHITECTURE.md) and [CLI Services Guide](./cli_services_integration.md)-### Database (SQLite)+### Application database (SQLite locally, PostgreSQL for multiple machines)+- **workflows** - Workflow definitions- **node_parameters** - Node parameter storage- **conversation_messages** - AI conversation history- **cache_entries** - Execution cache (when Redis disabled)- **users** - Authentication (single/multi-user modes)+Local development retains SQLite and embedded Temporal. Multi-machine Browser+execution requires `DISTRIBUTED_MODE=true`, a shared+`postgresql+asyncpg://` `DATABASE_URL`, external Temporal, shared artifact/profile+storage and one registered browser owner per backend process (`WORKERS=1`).+Do not share the SQLite files over NFS/SMB. Use the explicit offline transfer+command when moving existing IDs and graphs. The full configuration, owner+recovery and release checks are in [Browser deployment](browser_agent_deployment.md).++Browser AI Agent direct tasks run independently of workflow Start/Stop/Resume;+Cancel and Reset wait for confirmed browser-owner cleanup. Supported API keys+and configured website logins can use approved [1Password bindings](onepassword_credentials.md).+Local desktop authorization must reach the actual backend user/process.+Distributed mode uses scoped service accounts and rejects local keys and+unsupported OAuth/CLI-managed connections.+## Environment ConfigurationCopy the example environment file:diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.mdindex 9ad0fce5..cef10f8f 100644--- a/docs-internal/agent_architecture.md+++ b/docs-internal/agent_architecture.md@@ -14,7 +14,7 @@ Detailed architecture reference for how AI Agent (`aiAgent`) and Chat Agent (`ch2. [Agent Loop](#agent-loop)3. [Skill Injection Pipeline](#skill-injection-pipeline)4. [Tool Building Pipeline](#tool-building-pipeline)-5. [Tool Execution Flow](#tool-execution-flow)+5. [Tool Execution and Dispatch](./tool_building_pipeline.md)6. [Context and Memory Integration](#context-and-memory-integration)7. [execute_agent vs execute_chat_agent](#execute_agent-vs-execute_chat_agent)diff --git a/docs-internal/browser.md b/docs-internal/browser.mdindex d373734a..672fc9f3 100644--- a/docs-internal/browser.md+++ b/docs-internal/browser.md@@ -231,7 +231,7 @@ origin and current targets before retrieving values. Under Ask first/read-only,the agent requests human login instead.Automatic login supports a configured single username/password form with-saved success origin/path or selector cues. Before private resolution, the+saved success origin/path and optional selector cues. Before private resolution, theruntime persists a nonsecret sensitive-login latch, confirms the browser-usedaemon has stopped, drains and stops live capture, and blocks page text,snapshots, screenshots, vision, WebMCP and page/tab/dialog metadata. Credentials@@ -275,8 +275,8 @@ attempts greater than one retain the refusal to replay an uncertain action.The active task also persists its workflow/Browser-tool association. Viewerrouting uses that frozen profile after current saved-resource authorization,even if profile parameters change mid-task or the local/backend owner restarts.-Matching release clears the-association; an ambiguous active association fails closed. A recovered runtime+Matching release clears the association; an ambiguous active association+fails closed. A recovered runtimerestores the durable task token before later browser or profile effects.Profile files have one writer. CLI homes, temporary files and PID state arediff --git a/docs-internal/browser_agent_deployment.md b/docs-internal/browser_agent_deployment.mdindex fe431860..a7087add 100644--- a/docs-internal/browser_agent_deployment.md+++ b/docs-internal/browser_agent_deployment.md@@ -30,6 +30,14 @@ register Browser ownership. Every participant uses the same PostgreSQLapplication database, external Temporal service/namespace, authenticationkeys, trusted owner-forwarding secret and authorized artifact storage.+Start backend owners before admitting Browser work. Only backend lifecycle+registers and heartbeats runtimes. When preparation allocates a new profile,+it associates it with an existing configured backend registration; it never+registers the preparing orchestration process. Standalone worker configuration+must therefore reference a trusted registered backend for any new dynamic+Browser binding. A missing registration fails admission explicitly; a stale+existing registration retains its profiles and queues work for recovery.+Start from `.env.template`, override these values through deploymentconfiguration, and keep bootstrap secrets out of graph or node parameters:@@ -151,6 +159,10 @@ Profile ownership is permanent for this release. A stable task token holdsthe profile during model reasoning, browser work and human assistance.Competing tasks return `BrowserBusy` before browser effects. Human controlkeeps its separate lease; a stale cancellation cannot release a newer task.+The claim also records its saved workflow/Browser-tool association. Viewer+and manual-help routing use that frozen profile while the task is active,+even after profile edits or an owner restart. Current resource authorization+still applies; matching-token release clears the association.An offline owner's queued Activity remains on that owner's queue withoutconsuming retries or starting another model turn. The UI reports@@ -191,6 +203,37 @@ history has expired. Cancel and historical status remain authorized throughthe workflow after an agent is removed. Completion accounting occurs onceat the invocation parent boundary.+### Browser task API++All routes use application authentication and saved-workflow authorization.++| Route | Accepted request and purpose |+| --- | --- |+| `POST /api/browser/agents` | Saved `workflow_id`, mutation UUID, optional saved `browser_node_id`, position and standard provider/model selection; returns allocated node IDs, graph operations and saved revision |+| `GET /api/browser/tasks/discovery` | `workflow_id` and saved `browser_node_id`; returns associated Browser agents from the server graph |+| `POST /api/browser/tasks` | `workflow_id`, `agent_node_id`, `prompt` and `submission_id` UUID; extra fields are rejected |+| `GET /api/browser/tasks/{submission_id}` | Saved workflow/agent IDs in query parameters; returns current invocation status |+| `DELETE /api/browser/tasks/{submission_id}` | The same authorized identity; requests Cancel and waits for confirmed cleanup |+| `GET /api/browser/tasks/history` | `workflow_id`, optional agent `node_id`, opaque `cursor` and `limit` between 1 and 100 |++Reuse the submission UUID after a lost acknowledgement. A changed prompt or+binding under the same identity fails the fingerprint check. Browser tools+must be saved and connected before admission; clients cannot provide graphs,+credential sources, owner URLs or CDP endpoints. Temporal remains authoritative+while the history projection provides bounded display and durable deduplication.++### Operator-visible states++| State | Required response |+| --- | --- |+| Browser owner is not registered | Start the configured backend before submitting a new profile/task |+| Browser unavailable — waiting for its owner | Restore the original owner and machine identity; keep the same queue/profile |+| `BrowserBusy` | Finish or cancel the active task and confirm its cleanup before starting another |+| Observations paused during protected login | Wait for private confirmation, or use Close browser for manual login, reopen and take control |+| Cancel/Reset remains in progress | Restore the owner so cleanup can settle admitted work and confirm daemon/browser shutdown |+| Uncertain action after recovery | Observe current state and confirm the earlier effect; request human help when it cannot be established |+| Unsupported distributed credential connection | Enroll an audited static 1Password adapter or retain that connection in local mode |+## Acceptance and release gateAutomated checks use controlled fixtures: exact configured form login,@@ -200,6 +243,48 @@ queues, replay/Continue-As-New, PostgreSQL migration/concurrent claims andidentifier-only invalidation. Ordinary Browser/profile/cookie/viewer and oldagent/graph regressions remain required.+### Recorded implementation validation — 2026-10-08++These results were collected during implementation. Focused follow-up checks+overlap the broad suites; do not add their counts into an aggregate total.++| Check | Recorded result and boundary |+| --- | --- |+| Browser regressions | 307 passed; 2 opt-in live cases skipped in the broad run; final owner-allocation follow-up passed 18 tests |+| Controlled live login | 2 passed with real local Chrome/private CDP/browser-use and fake credentials, including exact Unicode/whitespace and normalization refusal |+| Temporal | 497 passed, including old/new SDK replay, native test-server owner queues, Continue-As-New and Cancel/Reset cleanup; browser/model Activities were fixtures |+| Credentials, runtime adapters and employees | 866 passed, 1 skipped; no real vault/provider access |+| LLM, memory, RLM and proxy regressions | 447 passed, 36 live/provider cases deselected |+| Browser Agent creation and employee integration | 76 focused checks passed |+| Client | 113 Browser/creation/credential checks passed; typecheck and production build passed |+| Database foundations | 15 passed using local SQLite and isolated real PostgreSQL 16.15, including import/reseed, concurrent claims, legacy profile ownership and two identifier-only notification listeners |+| Windows CLI provisioning | Official 1Password 2.40.0 archive verified and version/status smoke passed; no authorization or vault access |++The earlier unchanged Browser baseline was 122 passing tests. These newer+results expand coverage; they do not replace the production acceptance gates+below or establish live cross-machine behavior.++From `server/`, with the normal development environment installed:++```powershell+$env:DEBUG='false'+python -m pytest -q -p no:cacheprovider tests/nodes/browser tests/nodes/test_browser_agent_creation.py tests/test_browser_workspace_tasks.py+python -m pytest -q -p no:cacheprovider tests/credentials tests/temporal+# Optional native Temporal gate; use an already provisioned binary.+$env:TEMPORAL_TEST_CLI='C:/tools/temporal/temporal.exe'+python -m pytest -q -p no:cacheprovider tests/temporal/test_browser_workspace_replay.py+# Optional controlled Chrome acceptance; provision browser-use 0.13.10 first.+$env:BROWSER_ACCEPTANCE_LIVE='1'+$env:BROWSER_ACCEPTANCE_CLI='C:/runtime/browser-use/bin/browser-use.exe'+python -m pytest -q -p no:cacheprovider tests/nodes/browser/test_browser_login_acceptance.py+```++Use paths appropriate to the current platform. From `client/`, run the+credential suite with `bun run test:credentials` and Browser component tests+with `bun run test src/components/browser`; run root `bun run typecheck` and+`bun run build` for the shared frontend/build checks. These focused commands+are rerun entry points, not a promise of the exact recorded suite counts.+Run the isolated real-database tests separately from the legacy stubbed`tests/` suite:diff --git a/docs-internal/docker.md b/docs-internal/docker.mdindex 0d9b1a08..d1f55532 100644--- a/docs-internal/docker.md+++ b/docs-internal/docker.md@@ -2,6 +2,15 @@One container runs the whole app. uvicorn serves the API, the WebSocket and the built UI on one port, and the backend spawns the Temporal dev server, the bun code sidecar and plugin daemons itself when it needs them. There is no Redis; the cache falls back to SQLite.+This Compose recipe is a single-machine installation. Multi-machine Browser+AI Agent deployment requires shared PostgreSQL, external Temporal, shared+storage and stable browser-owner routing; adding replicas to this local recipe+does not supply those prerequisites. Follow [Browser deployment and offline+migration](browser_agent_deployment.md) before scaling it. Approved+[1Password credentials](onepassword_credentials.md) also require a verified+CLI and authorization available to the actual container backend. Desktop+authorization from an unrelated host terminal is insufficient.+| File | Role ||---|---|| `docker/Dockerfile` | Two stages. The build stage runs the canonical build, the same two commands CI runs (`bun install --frozen-lockfile`, then `bun run build`). The runtime stage keeps only what the backend reads at run time, and optional tools come back through the `EXTRAS` build argument. |diff --git a/docs-internal/node-logic-flows/web_automation/browser.md b/docs-internal/node-logic-flows/web_automation/browser.mdindex 331facff..7dc2627b 100644--- a/docs-internal/node-logic-flows/web_automation/browser.md+++ b/docs-internal/node-logic-flows/web_automation/browser.md@@ -4,6 +4,12 @@ The Browser node launches installed Chrome/Edge/Chromium in a dedicated OpenCompSee [native browser architecture](../../browser.md) for runtime installation, profile storage, networking and lifecycle, and [browser workspace](../../browser_workspace.md) for the viewer and UI protocol.+The dedicated `browser_agent` composes this tool with OpenCompany's existing+reasoning loop. It is a separate agent node; the Browser tool keeps its viewer,+profile, policy and output contracts. [Node creation](../../node_creation.md#browser-ai-agent-creation)+documents the shared atomic recipe, and [deployment](../../browser_agent_deployment.md)+documents native Workspace tasks and distributed ownership.+## Implementation map| Responsibility | Source |@@ -13,10 +19,12 @@ See [native browser architecture](../../browser.md) for runtime installation, pr| Profile runtime and managed Chrome | [`_runtime.py`](../../../server/nodes/browser/_runtime.py), [`_chrome.py`](../../../server/nodes/browser/_chrome.py) || Agent/workflow CLI calls and generated scripts | [`_cli.py`](../../../server/nodes/browser/_cli.py), [`_scripts.py`](../../../server/nodes/browser/_scripts.py) || Leases and control state | [`_session.py`](../../../server/nodes/browser/_session.py) |+| Private configured login and capture gate | [`_credentials.py`](../../../server/nodes/browser/_credentials.py) |+| Durable owners, task claims and authenticated routing | [`browser_owners.py`](../../../server/services/browser_owners.py), [`_routing.py`](../../../server/nodes/browser/_routing.py) || Direct live viewer capture and input | [`_stream.py`](../../../server/nodes/browser/_stream.py), [`_live_control.py`](../../../server/nodes/browser/_live_control.py) || Saved-workflow compatibility | [`workflow_migrations.py`](../../../server/services/workflow_migrations.py) |-The node has main input/output handles and a tool output handle. Its `ui_hints.isBrowserPanel` flag makes it discoverable as a browser panel. Activities use the `BROWSER` task queue, at most three Temporal attempts, and a 35-minute start-to-close timeout to accommodate human handoff.+The node has main input/output handles and a tool output handle. Its `ui_hints.isBrowserPanel` flag makes it discoverable as a browser panel; the agent does not receive that flag. Its logical Activity queue is `BROWSER`, with at most three Temporal attempts and a 35-minute start-to-close timeout for paths that consume plugin policy. New distributed execution overrides the physical queue with the frozen profile owner's queue, even with worker pools disabled. Generic orchestration workers exclude Browser Activities.## Operations@@ -36,6 +44,8 @@ The agent schema defaults to `snapshot`; saved workflow parameters default to `n| `wait` | `wait_for`: `load`, `network_idle`, `selector`, `text`, or `time`; optional `wait_value`. || `webmcp_list`, `webmcp_call` | Discover page-provided tools or invoke `webmcp_tool` with `webmcp_input` and optional `frame_id`. || `request_user` | Human handoff using `reason` and `message`. |+| `credential_bindings` | Discover authorized opaque login binding IDs and nonsecret field/origin metadata. |+| `credential_fill` | Approved `credential_binding_id` with current `username_ref`, `password_ref` and separately selected `submit_ref`; values resolve privately on the owner. || `diagnose` | Runtime, host and profile diagnostics without starting Chrome. || `evaluate`, `run_python`, `close` | **Workflow-only**: saved `expression`, saved `code`, or stop the profile. Excluded from the agent tool schema and rejected on tool calls. |@@ -43,12 +53,12 @@ Refs resolve against a backend-node-ID map held per target, not against model-pr## Execution flow-1. Read operator configuration. For agent calls, reread the saved node settings so tool arguments cannot override the profile, policy, timeouts or executable code.+1. Read operator configuration. Agent calls use trusted prepared configuration/resource bindings or reread saved settings. Model arguments cannot override profile, policy, timeouts or executable code. Saved policy and trusted restrictions combine monotonically: Ask first or a newly saved read-only restriction can tighten access, never broaden it.2. Reject workflow-only operations from agent calls and operations prohibited by `interaction`. Independently refuse automatic retries of site actions (including navigation and tab changes) when Temporal reports attempt greater than one; the previous action may already have occurred.-3. Resolve the owner's profile: explicit `profile_id`, otherwise the workflow's persistent default profile. Unsaved runs have a separate fallback. Register a session identified by owner, workflow and node, associated with that profile.+3. Resolve the authorized profile: a frozen active-task binding, otherwise saved `profile_id` or the workflow's persistent default. Unsaved local runs have a separate fallback. Distributed execution routes to its permanently registered backend owner; it cannot create a runtime on an orchestration worker or adopt an unavailable owner's profile. Register a session identified by principal, workflow and node, associated with that profile.4. Handle `close` and `diagnose` without opening a new runtime. Other operations open or reuse the profile runtime, discovering the installed browser and installing the pinned CLI on first use if needed. Testing mode may also install pinned Chrome. The actual selected browser version must be compatible with the saved profile; downgrade errors never delete or replace the profile automatically.-5. `request_user` enters the human-handoff flow. Other operations acquire the profile's agent-operation lease/lock; human control blocks agent work.-6. `webmcp_list` reads the native tracker's tool cache; `webmcp_call` invokes through the native CDP integration. Remaining operations use a generated Python script sent to the isolated browser-use CLI, whose daemon persists across calls and connects to managed Chrome.+5. Browser Agent tasks hold a task-lifetime profile claim during model reasoning, browser operations and human assistance. Competing tasks fail with `BrowserBusy` before effects. `request_user` enters human handoff; other operations acquire the existing operation lease/lock. Human control retains its separate lease.+6. `credential_bindings` reads authorized metadata without opening a browser or resolving secrets. `credential_fill` uses the protected private CDP flow below. `webmcp_list` reads the native tracker cache; `webmcp_call` invokes native CDP. Other ordinary operations use generated scripts through the isolated pinned browser-use CLI and its persistent daemon.7. Update active target, URL/title and snapshot refs from the result; invalidate refs on navigation. Map output to the node schema and emit page/session changes. CLI daemon failure permits one retry only for explicit observations, as defined in `_controls.py`. An uncertain site action requires a fresh observation before another action.The profile is persistent across executions; it is not the old execution-ID-named CLI session. Closing it stops the shared profile runtime, so other views of that profile observe the closure.@@ -63,7 +73,7 @@ in-memory ledger shares origin budgets across profiles in the backend;repeat counts are per profile/origin. Observation and human input are exempt.See [Browser controls](../../browser-controls.md) for exact limits and scope.-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.+The current `MUTATING` set is `click`, `type`, `press`, `select`, `back`, `forward`, `reload`, `webmcp_call`, `evaluate`, `run_python` and `credential_fill`. `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.Empty `allowed_domains` allows public destinations. The managed egress proxy checks destinations and resolved addresses for browser traffic; private-network access is disabled by default. Enabling it does not allow cloud metadata or OpenCompany's own protected ports. See the canonical runtime document for policy details.@@ -79,7 +89,31 @@ The authenticated live viewer attaches through `/ws/browser` to a saved workflow## 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.+New employee **Web browser** capabilities use the shared Browser AI Agent+recipe and the existing delegation mechanism. The saved Browser tool remains+the employee's viewer resource. Existing employee graphs are not rewritten+just to add this capability. With "Ask me before sending anything" on, trusted+`interaction=read_only` restrictions reach both execution adapters, so the+agent reads pages and hands changes or login to the owner through+`request_user`. The existing `browser_request` summary (`{node_id, reason,+since}`) continues to show Needs you and Help in browser.++## Protected configured login++Website enrollment is described in [1Password credentials](../../onepassword_credentials.md#website-login-bindings).+Before resolution, the owner validates binding scope, exact origin, current+tab/frame/refs, saved policy and task claim. It persists a sensitive-login+latch, confirms CLI daemon suspension and drains/gates viewer captures and+page metadata. Only the private CDP session receives resolved values. It+validates exact field assignment and submits the selected button once.++Snapshots, text, screenshots, vision, WebMCP and ordinary actions stay blocked+until private success checks confirm saved origin/path/cues, absence of+sensitive fields and no reflected password. Failure or uncertain submission+retains the gate, including after owner restart. **Close browser for manual+login** must confirm shutdown before clearing it; reopen and use takeover.+Ask first/read-only, MFA, passkeys and multi-step sign-in use human help.+Agent arguments never contain credential values or 1Password references.## Output and failuresdiff --git a/docs-internal/node-logic-flows/web_automation/browserHarness.md b/docs-internal/node-logic-flows/web_automation/browserHarness.mdindex 144eea53..0ffe4f6f 100644--- a/docs-internal/node-logic-flows/web_automation/browserHarness.md+++ b/docs-internal/node-logic-flows/web_automation/browserHarness.md@@ -4,6 +4,13 @@The replacement `browser` node launches the installed Chrome, Edge or Chromium (Chrome for Testing only with `BROWSER_RUNTIME=testing`) in persistent OpenCompany-owned profiles. The live viewer and human takeover use the native CDP path. Most agent/workflow operations still use the pinned browser-use CLI and its daemon internally; this dependency does not restore the old node or its real-Chrome attachment model.+The dedicated Browser AI Agent uses that Browser tool through the existing+OpenCompany reasoning runtime. Configured 1Password login uses private CDP+while the CLI and observations are suspended. Follow+[node creation](../../node_creation.md#browser-ai-agent-creation),+[deployment and recovery](../../browser_agent_deployment.md) and+[credential setup](../../onepassword_credentials.md) for these current paths.+[Workflow migration](../../../server/services/workflow_migrations.py) rewrites saved `browserHarness` nodes to `browser`:- `goto` becomes `navigate`; `js` becomes `evaluate`; `doctor` becomes `diagnose`.diff --git a/docs-internal/onepassword_credentials.md b/docs-internal/onepassword_credentials.mdindex df0700e8..f24df957 100644--- a/docs-internal/onepassword_credentials.md+++ b/docs-internal/onepassword_credentials.md@@ -10,6 +10,11 @@ The executable is verified **before execution**. Windows uses valid AuthenticodeSet `ONEPASSWORD_CLI_PATH` to an absolute path when using an operator-provisioned executable. `onepassword_status` verifies signature/integrity and the pinned version only: it does not sign in, enumerate a vault or resolve a field. Installation and status failures expose fixed error messages, without raw command streams.+`ONEPASSWORD_READ_TIMEOUT_SECONDS` defaults to 30 (allowed range 1–300).+Each private stdout/stderr pipe is bounded to 64 KiB. Keep bootstrap tokens+in trusted deployment secret configuration; do not put them in graph JSON,+node parameters, serialized Settings or an exported database manifest.+Local defaults use `ONEPASSWORD_AUTH_MODE=desktop`. Enable CLI integration in the desktop app; optionally select an account with `ONEPASSWORD_ACCOUNT`. Desktop authorization is broader than an individual OpenCompany binding, so application ownership and binding restrictions are checked independently. A backend running under another operating-system user, a headless service, or an expired/denied desktop grant must be authorized appropriately; there is no fallback to a different account or old local key.Distributed mode requires `ONEPASSWORD_AUTH_MODE=service_account`. Supply `OP_SERVICE_ACCOUNT_TOKEN` through trusted deployment configuration, using a dedicated automation vault with read-only field/item access. The private resolver passes it only to its own child process. It deliberately excludes Connect variables, session variables, ambient provider keys and debug options. Ordinary application subprocesses strip every case-insensitive `OP_*` variable after environment merges; browser processes retain their stricter existing allowlists. Never wrap browser-use in `op run` or generate a plaintext `op inject` template.@@ -28,10 +33,29 @@ The private subprocess uses fixed `op read --no-newline` arguments, no shell, clThe **Browser profiles** panel enrolls username/password references with an exact login origin, a success origin/path and optional success selector. A binding may be restricted to a profile, workflow or employee; server resource authorization validates those restrictions. Saving a website binding does not retrieve a password or grant a desktop authorization. Model-visible discovery returns opaque IDs, labels, origins and supported fields, excluding vault/item references and values.+1. Open Credentials → Browser profiles and the website login bindings section.+2. Enter a label, exact login origin and approved ID-based username/password references. Select a profile restriction when the login belongs to one profile.+3. Configure the expected success origin/path and, where appropriate, a stable success selector. Automated login is limited to a single top-frame form with current username, password and submit references.+4. Save the binding, then submit the Browser task. The agent discovers its opaque ID; the owner requests desktop authorization or uses its scoped service account only during private runtime resolution.++Catalogue reads return binding IDs and safe metadata, not saved website secret+references. Replacing a website binding requires fresh references; existing+workflow/employee restrictions are preserved. Deleting or changing enrollment+during an authorization wait invalidates the pending resolution. Use takeover+for an unconfigured form, multi-step login, MFA or passkeys.+The browser owner first reads nonsecret metadata with `get_browser_credential_binding` and enforces policy, Ask first, task ownership and the current login target. It then persists a nonsecret sensitive-login latch, suspends the browser-use daemon and drains/gates captures and page metadata. Only after that can `resolve_browser_credentials` resolve values for the private CDP fill flow. Resolution rechecks ownership, scopes and the current enrollment after authorization waits. The browser revalidates the tab/frame/targets and origin before effects.Passwords are filled through the existing private CDP connection. During this phase snapshots, page text, screenshots, vision, WebMCP and ordinary browser operations remain gated. A configured private success check ends the phase. An uncertain submit, changed target, failed suspension or unconfirmed completion retains the gate and requests human login. Ask first/read-only policies never receive an autofill bypass. Multi-step login, MFA and passkeys use existing human takeover.+Before observations resume, private checks require the configured success+cues, removal of sensitive fields and no reflected password in the URL or+page content. Values are preserved exactly; if the browser normalizes an+input, the runtime refuses submission. If the gate remains, **Close browser+for manual login** confirms shutdown before clearing it. Reopen and take+control. Owner restart restores the nonsecret gate; it does not replay a fill+or assume that prior tab/element references remain valid.+## Verification and limitsAutomated credential tests use fake subprocesses and nonsecret fixtures: no developer vault is read. Canaries cover exact value preservation, CLI argument/environment containment, bounded pipes, cancellation, safe errors, metadata-only reads, per-call rotation, scoped bindings, revoked enrollment during authorization, and absence of cluster fallback. Browser tests separately cover gated captures and private CDP login.diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex d79e916a..cb0651f2 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -527,12 +527,20 @@ activities. The three shown above are the core model/persistence/compactionsteps; the remainder cover payload preparation, progress and outputpersistence, tool/skill refresh, delegation lifecycle, and team finalization.-**Agents that migrate** (15): `aiAgent`, `chatAgent`, 11 specialized-agents (`android_agent`, `coding_agent`, `web_agent`, `task_agent`,+**Native agent types**: `aiAgent`, `chatAgent`, specialized+agents (`android_agent`, `browser_agent`, `coding_agent`, `web_agent`, `task_agent`,`social_agent`, `travel_agent`, `tool_agent`, `productivity_agent`,`payments_agent`, `consumer_agent`, `autonomous_agent`), 2 teamleads (`orchestrator_agent`, `ai_employee`).+`browser_agent` uses this same loop and a saved Browser tool. Its shared+atomic creation recipe, direct Workspace tasks and private credential flow+are described in [node creation](node_creation.md#browser-ai-agent-creation)+and [Browser deployment](browser_agent_deployment.md). Distributed Browser+Activities use their frozen owner's physical queue regardless of the worker+pool switch; generic orchestration workers exclude them. The authoritative+native type set is `AGENT_WORKFLOW_TYPES` in `services/temporal/workflow.py`.+**Agents that stay as single activities**: `rlm_agent`,`claude_code_agent`, and `vertex_managed_agent`. Their internal session state(RLM REPL, Claude CLI `--resume` with stable `cwd`, or Vertex interaction anddiff --git a/server/tests/credentials/README.md b/server/tests/credentials/README.mdindex e86b3cd1..e4dde9be 100644--- a/server/tests/credentials/README.md+++ b/server/tests/credentials/README.md@@ -1,6 +1,9 @@# Credentials Test Suite-Locks in the invariants enumerated in [docs-internal/ARCHIVE/credentials_panel.md §5](../../../docs-internal/ARCHIVE/credentials_panel.md).+Covers local encryption/OAuth behavior and approved 1Password sources.+The current contract is [1Password credentials](../../../docs-internal/onepassword_credentials.md);+the [archived credentials panel](../../../docs-internal/ARCHIVE/credentials_panel.md)+records the original local-store invariants.## Run@@ -27,10 +30,14 @@ uv run pytest tests/credentials/ --cov=core.encryption --cov=core.credentials_da| `test_credential_broadcasts.py` | Credential-change broadcast contract — every credential-mutation handler emits `update_api_key_status` and/or `broadcast_credential_event` || `test_credential_catalogue_shape.py` | `credential_providers.json` top-level shape and provider placement — every provider lives under `providers`, cross-checked against the registered credential classes || `test_openai_compatible_credential.py` | RFC-0003 AG15 — named endpoints against the real encrypted store: add (slug from the label, else the host and port, never userinfo; a duplicate label refused), refresh with the stored URL and key, the catalogue's `endpoints` / `stored` extras, delete of both rows, and `is_configured` for the workflow validator |+| `test_onepassword.py` | Metadata-only forms/catalogues, private CLI argument/output bounds, exact whitespace/Unicode, cancellation, authorization errors, per-call rotation, source ownership/revocation, supported static adapters and cluster fallback refusal |+| `test_onepassword_process_boundaries.py` | Bootstrap token exclusion after subprocess environment merges across CLI, PTY, code, services, events and installers |+| `test_onepassword_runtime_adapters.py` | Activity-local provider resolution and trusted principal propagation through model, employee, speech and other supported static callers |## Fixtures`conftest.py` provides:+- `encryption` / `uninitialized_encryption` — `EncryptionService` instances- `credentials_db` — fresh on-disk SQLite per test in `tmp_path`, real Fernet- `auth_service` — `AuthService` backed by the test DB@@ -42,3 +49,20 @@ uv run pytest tests/credentials/ --cov=core.encryption --cov=core.credentials_da- Native LLM SDK behaviour (covered by `tests/llm/`)- Frontend `CredentialsModal` rendering (covered by `client/src/test/`)- WhatsApp Go RPC binary+- Real 1Password desktop grants, vault reads, service-account permissions or platform installation; subprocess and provider fixtures use nonsecret test values++## Browser and deployment acceptance++Run `tests/nodes/browser/test_browser_credentials.py` for protected-login+targets, capture gates, private success checks and secret canaries. The opt-in+`test_browser_login_acceptance.py` uses installed Chrome and provisioned+browser-use against an isolated local fixture with fake credentials. It never+reads a vault or an external account. Set `BROWSER_ACCEPTANCE_LIVE=1` only+after provisioning the pinned CLI; supply `BROWSER_ACCEPTANCE_CLI` when it is+outside the fixture's default path.++Real PostgreSQL tests live in `integration_tests/`, separately from the+legacy database stubs under `tests/`. Native Temporal owner-routing/replay+fixtures are under `tests/temporal/test_browser_workspace_replay.py` and need+`TEMPORAL_TEST_CLI`. Commands, recorded results and remaining deployment+acceptance are in the [Browser deployment guide](../../../docs-internal/browser_agent_deployment.md#acceptance-and-release-gate).