Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: describe the bun-only runtime, install channel and desktop bundle
trohitgd8d0b7417f41
diff --git a/CLAUDE.md b/CLAUDE.mdindex aac27b25..670ac346 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -30,9 +30,9 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Browser Harness](./docs-internal/browser_harness.md)** | Wave 19 — `browserHarness` node integrating browser-use/browser-harness (alpha, raw CDP against the user's REAL Chrome; no Playwright). Primary op `run_python` pipes agent-authored Python to the CLI stdin against ~25 pre-imported helpers (see→act→verify loop: `capture_screenshot` → `click_at_xy` → `wait_for_load` → `js`). uv-tool install under `packages/browser-harness/`; daemon state pinned to `daemons/browser-harness/` via `BH_RUNTIME_DIR`/`BH_TMP_DIR`; Windows OK (token-auth TCP loopback IPC). Sibling of the stable `browser` node (agent-browser `@eN` refs) — NOT a replacement. Chrome must be CDP-reachable (`BU_CDP_URL` / chrome://inspect / `--remote-debugging-port`); `doctor` op diagnoses. Skill: `skills/web_agent/browser-harness-skill/`. || **[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). npm install into the shared packages tree (pinned version). 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. |+| **[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. || **[GitHub Service](./docs-internal/github_service.md)** | GitHub CLI integration — `githubAction` (repo_clone / pr_create / pr_list / pr_merge / issue_create / issue_list + `custom` passthrough; AI tool `github`). **Strict Stripe pattern: the gh CLI owns its own auth** — no token stored/injected by OpenCompany, no auth pre-flight (gh's own error surfaces), marker OAuth row for the modal badge, fieldless catalogue entry. Login = spawned `gh auth login --hostname github.com --git-protocol https --web` — source-verified: headless takes the `isInteractive=false` branch (no Press-Enter), prints one-time code + `github.com/login/device` URL on stderr; the modal shows the code via the generic `verificationCode` plumbing (`useCredentialPanel` → `OAuthConnect`). `login_env()` strips `GH_TOKEN`/`GITHUB_TOKEN` (login aborts otherwise). Success gate = `gh auth status` exit 0, then best-effort **`gh auth setup-git`** (official bridge — the future git node needs zero auth code). gh binary: **project-local, pooch-driven** (temporal `_install.py` idiom) — pinned release under `package_dir("gh")`, system gh never consulted (auth state still shared: gh config paths are user-level). Palette group `vcs`. |-| **[Cloudflare Service](./docs-internal/cloudflare_service.md)** | Cloudflare CLI integration — `cloudflareAction` (whoami / zones_list / dns_records CRUD / `graphql_query` / `custom` passthrough; AI tool `cloudflare`) wrapping the official `cf` CLI (npm `[email protected]`, technical preview — "the next version of Wrangler"). **Two cf-specific variants of the CLI-managed-auth pattern**: (1) the CLI opens the browser ITSELF (loopback PKCE callback on fixed port 8877) so the login handler proxies nothing — single-flight guard (concurrent logins collide on the fixed port) + never-kill-the-shim invariant (killing the npm `.cmd` wrapper orphans the node child holding 8877); success gate = `cf auth whoami` JSON (`authenticated: true` — cf exits 0 in BOTH auth states). (2) **Fixed 86-scope OAuth grant with no `--scopes` flag** — only `dns_analytics:read` for analytics; no RUM/zone-analytics OAuth scope exists anywhere, so the optional `cloudflare_api_token` field (injected as `CLOUDFLARE_API_TOKEN`, cf's documented first-priority credential) is the only path to Web Analytics/RUM + the GraphQL Analytics API. `graphql_query` op POSTs the official `client/v4/graphql` endpoint directly (outside the OpenAPI schema cf/SDKs are generated from) — the replacement for the sunsetted Zone Analytics REST API; needs `Account > Account Analytics > Read`. Pinned npm install into the shared packages tree, system cf never consulted (preview argv surface drifts across versions). Palette group `deployment`. |+| **[Cloudflare Service](./docs-internal/cloudflare_service.md)** | Cloudflare CLI integration — `cloudflareAction` (whoami / zones_list / dns_records CRUD / `graphql_query` / `custom` passthrough; AI tool `cloudflare`) wrapping the official `cf` CLI (npm `[email protected]`, technical preview — "the next version of Wrangler"). **Two cf-specific variants of the CLI-managed-auth pattern**: (1) the CLI opens the browser ITSELF (loopback PKCE callback on fixed port 8877) so the login handler proxies nothing — single-flight guard (concurrent logins collide on the fixed port) + never-kill-the-shim invariant (killing bun's `cf.exe` launcher shim orphans the child bun process holding 8877); success gate = `cf auth whoami` JSON (`authenticated: true` — cf exits 0 in BOTH auth states). (2) **Fixed 86-scope OAuth grant with no `--scopes` flag** — only `dns_analytics:read` for analytics; no RUM/zone-analytics OAuth scope exists anywhere, so the optional `cloudflare_api_token` field (injected as `CLOUDFLARE_API_TOKEN`, cf's documented first-priority credential) is the only path to Web Analytics/RUM + the GraphQL Analytics API. `graphql_query` op POSTs the official `client/v4/graphql` endpoint directly (outside the OpenAPI schema cf/SDKs are generated from) — the replacement for the sunsetted Zone Analytics REST API; needs `Account > Account Analytics > Read`. Pinned `bun add` into the shared packages tree (the CLI declares `engines.node >= 22`, which bun ignores — verified running on bun with no Node on PATH), system cf never consulted (preview argv surface drifts across versions). Palette group `deployment`. || **[Google Cloud Service](./docs-internal/gcloud_service.md)** | Google Cloud CLI integration — `gcloudAction` (auth/config/projects + set_project / Compute Engine instances list-start-stop-describe / Cloud Run deploy-list-describe / Cloud Storage ls-cp-rm / `custom` passthrough; AI tool `gcloud`) wrapping the official gcloud CLI (pinned versioned archive via pooch into `package_dir("gcloud")` — NOT npm; the Windows bundled-python zip keeps the legacy `google-cloud-sdk-` filename prefix, the `-cli-` spelling 404s, locked by test). Cloudflare login variant (CLI opens the browser itself, random loopback port — no fixed-port hazard) + the gh marker-token pattern; success gate = `gcloud auth list --filter=status:ACTIVE --format=json` non-empty (exit codes never trusted). **Config isolation divergence from gh**: every invocation pins `CLOUDSDK_CONFIG=<DATA_DIR>/gcloud/`, so terminal logins against the operator's global gcloud are deliberately NOT visible to the node. ADC note: node login mints gcloud USER creds only (CLI commands never read ADC); client-library code gets ADC via the `custom` op `auth application-default login` (lands isolated in the pinned dir). Cold install ~100 MB → login answers `pending: True` within the 22 s WS budget. Provider id `gcloud` is orthogonal to the Workspace `google` OAuth2 provider. Palette group `deployment`. || **[TikHub Service](./docs-internal/tikhub_service.md)** | TikHub social-scraping integration — `tikhubAction` (`call` / `list_endpoints` / `fetch_url` / `account`; AI tool `tikhub_action`; palette group `scraper`, visible in normal mode) over the **official `tikhub` SDK** (`tikhub>=2.1.2,<3`, auto-generated from TikHub's `openapi.json`; ~1,100 methods across TikTok / Douyin / Instagram / YouTube / Twitter / Xiaohongshu / Bilibili / Kuaishou / Weibo / Reddit / Threads / LinkedIn / Zhihu). **The node is the "flattened CLI"**: one `call` op addressed by the SDK's own `resource.method` id (`douyin_web.fetch_one_video`, also `resource/method` or the `/api/v1/...` path) with **reflective `getattr` dispatch** and `inspect.signature(...).bind` pre-flight so unknown kwargs fail before any paid request; **nothing is vendored** — `endpoint_index()` introspects the installed SDK at runtime (resources = `AsyncResource` instance attrs, params = keyword-only signature, route from the docstring's ``GET /api/v1/...`` literal), cached per process, and feeds both `list_endpoints` and the `platform`-dependent dynamic `endpoint` dropdown (`tikhubEndpoints` loader; `all` returns no options, the LLM path stays free text). `tikhub` is imported lazily inside `_sdk.py` only (plugin imports with `sys.modules["tikhub"] = None`). `TikHubCredential` = bearer `ApiKeyCredential` with a declarative httpx probe against `/api/v1/tikhub/user/get_user_info` (never the unauthenticated health route); runtime key via `TikHubCredential.resolve` so a missing key yields the structured `PermissionDeniedError` envelope. SDK `TikHubError` subclasses map to `NodeUserError` (401 key rejected -> Credentials; 403 scope-or-balance -> `account`; 429 + `retry_after`; 400/422 with TikHub `detail`; 404; 5xx upstream after the SDK's own retries) and HTTP-200-with-in-body-`code >= 400` is raised too. **Flat `$0.001`/request tracking** (`pricing.json: api.tikhub` + `operation_map.tikhub`, `track_tikhub_usage` -> `api_usage_metrics`, only after a 2xx, never for `list_endpoints`). SDK drift is guarded by two contract tests (every `PLATFORMS` value matches a live resource; every backticked id in the skill resolves). || **[Discord Service](./docs-internal/discord_service.md)** | Discord bot integration — `discordSend` / `discordAction` (AI tools) + `discordReceive` / `discordInteraction` triggers. **discord.py owns the gateway, REST is plugin-owned** (nodes must work with no gateway, `discordAction` needs arbitrary routes, and the invalid-request guard is process-wide across accounts). **Multi-account rides the existing `session_id` credential column** — `_accounts.py` is the only file that knows `account_id -> "discord:<app_id>"`, `"default"` is the row the modal already writes, and `credential_customer_id` is deliberately NOT used (it is per-execution-context tenancy, so two nodes in one workflow could never target different bots). **`AccountScopedNode` exists because `server_controlled_fields` is enforced only in `execute_as_tool`'s ToolNode branch** — a dual-purpose ActionNode takes an earlier `{**node_params, **tool_args}` merge with model args winning, so locked fields are stripped before it. Attachments are metadata on the trigger and downloaded by `discordAction` (deployed triggers never run their node body). Interaction tokens never leave the server — the trigger emits an opaque ref. The interactions endpoint is a plugin router, not a `WebhookSource`: Discord's validation probe requires **401** (the generic intake raises 400) and the 3-second ACK deadline precludes awaiting `emit`. Rate limiting is reactive; the invalid-request guard is **process-global** because Cloudflare bans the source IP, not the token. |@@ -42,11 +42,11 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[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. **Two frontend hosts share one renderer**: the `isCanvasPanel` parameter panel and the new docked resizable right sidebar (`CanvasDock` + `canvasDockStore`; auto-open via `notifyPushed`, ephemeral click-to-preview from the gallery dialog, `usePanelResize` extracted from ConsolePanel). 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`. Browser screenshots became displayable in the same change: both browser plugins persist shots as workspace FileRefs via the tolerant `nodes/browser/_screenshots.py`. || **[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`. |-| **[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 Node 22 (`desktop/runtimes.json`, verified against upstream checksum manifests by `scripts/fetch-runtimes.ts`), stages the backend sibling layout from `npm pack --dry-run` (`scripts/stage.ts`, re-bundles the Node sidecar with express inlined because bun's isolated linker leaves a dangling symlink), 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 draft release + finalize) 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/node/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 browser hook reads the module singleton instead of `get_browser_service()`, which lazily ran `npm install agent-browser` AT SHUTDOWN and wedged every 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 + Python 3.12 + uv; `bun install --frozen-lockfile` everywhere, publish stays `npm publish --provenance`) |-| **[Performance](./docs-internal/performance.md)** | Cold-start measurements (Application startup complete 2.90 s warm, 21.5 s cold post-`company clean` — was 71 s before the 2026-07-14 boot-delay fixes; first WS connect 8.29 s) + warm and cold per-phase timelines + optimisation history (lazy LangChain imports, lazy LLM-SDK exception refs, esbuild sidecar bundle, bytecode-at-build, PartySocket reconnect, TanStack Query auth bootstrap, `manualChunks`, Vite dep-cache preservation, off-loop Temporal build-id hash) + bottleneck inventory + reproduction commands + anti-patterns to never reintroduce (incl. eager SDK import at LLM provider registration, unconditional `.vite` wipe, synchronous `Worker()` on the event loop). Pairs with the build-time pipeline doc below. |-| **[Release Build Pipeline](./docs-internal/release_build_pipeline.md)** | npm-distribution build pipeline: `typescript@7` (native Go compiler, exact-pinned in **root** devDependencies — client keeps `typescript@^5.x` because typescript-eslint's peer range excludes 6/7, and one manifest cannot declare `typescript` twice) for type-check, measured 5.9× faster than tsc 5.9.3 (820 ms vs 4830 ms); `bun run --filter react-flow-client typecheck` delegates up to the root gate, Vite `manualChunks` + `target: 'es2022'`, esbuild Node.js sidecar bundle (drops `tsx` interpreter cost), bytecode pre-compile in two halves — `[tool.uv] compile-bytecode = true` (uv sync compiles `.venv/` site-packages) + `python -m compileall` for project source (plain `.pyc`, **no `-O`** — per PEP 488 the non-`-O` runtimes never load `.opt-1.pyc`; excludes `.venv/`, `tests/`). Single source of truth for the bytecode-compile path list: `cli.commands.build.COMPILEALL_SOURCE_DIRS`. Dev PM is **[email protected]** (tracked text `bun.lock`, `bunfig.toml` pins the isolated linker, ranged security pins in top-level `overrides`); `company build` step [1/6] is `bun install`. |+| **[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 draft release + finalize) 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 browser hook reads the module singleton instead of `get_browser_service()`, which lazily ran the `agent-browser` package install (`npm install` at the time; `bun add` via `core/js_runtime.add_package` today) AT SHUTDOWN and wedged every 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` in the publish jobs, and npm provenance attestation went away with npm) |+| **[Performance](./docs-internal/performance.md)** | Cold-start measurements (Application startup complete 2.90 s warm, 21.5 s cold post-`company clean` — was 71 s before the 2026-07-14 boot-delay fixes; first WS connect 8.29 s) + warm and cold per-phase timelines + optimisation history (lazy LangChain imports, lazy LLM-SDK exception refs, pre-bundled sidecar (esbuild at the time, `bun build --target=bun` today), bytecode-at-build, PartySocket reconnect, TanStack Query auth bootstrap, `manualChunks`, Vite dep-cache preservation, off-loop Temporal build-id hash) + bottleneck inventory + reproduction commands + anti-patterns to never reintroduce (incl. eager SDK import at LLM provider registration, unconditional `.vite` wipe, synchronous `Worker()` on the event loop). Pairs with the build-time pipeline doc below. |+| **[Release Build Pipeline](./docs-internal/release_build_pipeline.md)** | Build pipeline for the registry tarball (installed with `bun add -g`; bun is the only JavaScript runtime and package manager anything shipped needs): `typescript@7` (native Go compiler, exact-pinned in **root** devDependencies — client keeps `typescript@^5.x` because typescript-eslint's peer range excludes 6/7, and one manifest cannot declare `typescript` twice) for type-check, measured 5.9× faster than tsc 5.9.3 (820 ms vs 4830 ms); `bun run --filter react-flow-client typecheck` delegates up to the root gate, Vite `manualChunks` + `target: 'es2022'`, `bun build --target=bun` sidecar bundle (self-contained `dist/index.js` with express inlined, run as `bun dist/index.js`; drops the `tsx` interpreter cost and needs no `node_modules` at runtime), bytecode pre-compile in two halves — `[tool.uv] compile-bytecode = true` (uv sync compiles `.venv/` site-packages) + `python -m compileall` for project source (plain `.pyc`, **no `-O`** — per PEP 488 the non-`-O` runtimes never load `.opt-1.pyc`; excludes `.venv/`, `tests/`). Single source of truth for the bytecode-compile path list: `cli.commands.build.COMPILEALL_SOURCE_DIRS`. Dev PM is **[email protected]** (tracked text `bun.lock`, `bunfig.toml` pins the isolated linker, ranged security pins in top-level `overrides`); `company build` step [1/6] is `bun install`. || **[Workflow Schema](./docs-internal/workflow-schema.md)** | JSON schema for workflows, edge handle conventions, config node architecture || **[Execution Engine Design](./docs-internal/DESIGN.md)** | Architecture patterns, design standards, and implementation details for the workflow execution engine || **[Execution Roadmap](./docs-internal/ARCHIVE/ROADMAP.md)** | *Archived* status snapshot; current state is in [Execution Engine Design](./docs-internal/DESIGN.md) and the Temporal docs |@@ -81,7 +81,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire| **[Memory Lifecycle](./docs-internal/ARCHIVE/memory_lifecycle.md)** | *Archived — pre-RFC-0002.* Documented the retired `input-memory` markdown model. See "Context and Memory (RFC-0002)" below, [Agent Context Flow](./docs-internal/agent_context_flow.md) and [Memory Compaction](./docs-internal/memory_compaction.md). || **[Node Parameter Panel](./docs-internal/node_panels.md)** | Three-section node config UI (Input / Parameters / Output) logic-flow reference. || **[Deployment (legacy reference)](./docs-internal/deployment_legacy.md)** | `company deploy` CLI summary + the historical Docker Compose topology. |-| **[GCP VM Deploy Runbook](./docs-internal/gcp_vm_deploy_runbook.md)** | Manual gcloud + Cloudflare runbook for deploying the released npm package (non-Terraform path). |+| **[GCP VM Deploy Runbook](./docs-internal/gcp_vm_deploy_runbook.md)** | Manual gcloud + Cloudflare runbook for deploying the released `@zeenie-ai/opencompany` tarball with `bun add -g` (non-Terraform path). |## Design Principles & Standards@@ -209,7 +209,7 @@ server/core/├── cache.py # CacheService with Redis/SQLite/Memory fallback├── config.py # Application configuration├── logging.py # Logging configuration-├── paths.py # SSOT for on-disk locations (generic helpers only): opencompany_root()/data_path()/workspaces_dir()/workspace_dir()/daemons_dir() + packages_dir()/package_dir(name) all under ~/.opencompany/ (= DATA_DIR); packages/ holds the single shared npm tree + stripe/ + temporal/ binary subdirs; example_workflows_dir() = <repo>/.opencompany/workflows/ (shipped seeds, NOT under DATA_DIR). Plugin-specific subpaths composed inline at the call site, never added here.+├── paths.py # SSOT for on-disk locations (generic helpers only): opencompany_root()/data_path()/workspaces_dir()/workspace_dir()/daemons_dir() + packages_dir()/package_dir(name) all under ~/.opencompany/ (= DATA_DIR); packages/ holds the single shared bun-managed packages tree (core/js_runtime.py) + stripe/ + temporal/ binary subdirs; example_workflows_dir() = <repo>/.opencompany/workflows/ (shipped seeds, NOT under DATA_DIR). Plugin-specific subpaths composed inline at the call site, never added here.├── env_defaults.py # Env accessor backed by .env.template/.env (the SSOT for port numbers; used by entry points that bypass the CLI env push)├── encryption.py # Fernet encryption with PBKDF2 key derivation├── credentials_database.py # Async SQLite for encrypted API keys and OAuth tokens@@ -235,8 +235,8 @@ server/config/# transliterate / detect). Both files are resolved by the shared# services/plugin/capabilities.CapabilityConfig.-server/nodejs/ # Persistent Node.js server for JS/TS execution-├── package.json # Dependencies: express, tsx+server/nodejs/ # JS/TS executor sidecar — Express on bun (the only JS runtime shipped)+├── package.json # Dependency: express (inlined by `bun build --target=bun`); engines.bun >= 1.4.0├── tsconfig.json # TypeScript config (ES2024)└── src/└── index.ts # Express server (/execute, /health, /packages/*)@@ -245,16 +245,16 @@ server/nodejs/ # Persistent Node.js server for JS/TS execution### Polyglot Server Integration (Optional)OpenCompany can optionally integrate with the sibling **polyglot-server** repo (a plugin-registry microservice exposing REST + MCP + WebSocket). NOTE: the OpenCompany-side client/handler (`polyglot_client.py`, `handlers/polyglot.py`) are not currently present in the tree — this is a possible future integration, not wired. See [Polyglot Server](../polyglot-server/ARCHITECTURE.md).-### Node.js Code Executor-Persistent Node.js server for JavaScript/TypeScript code execution, replacing subprocess spawning per execution. **Plugin-owned (July 2026):** the sidecar is supervised by `nodes/code/_runtime.py` (`NodeJSExecutorRuntime`, same `BaseProcessSupervisor` pattern as WhatsApp/Temporal) and spawns on demand from `acquire_client()` on the first JS/TS node execution — in every run mode, with no CLI service wiring. Client + config are plugin-owned too (`nodes/code/_client.py`, `NODEJS_EXECUTOR_*` env vars; core `Settings` carries no executor fields).+### JS/TS Code Executor (bun sidecar)+Persistent Express server for JavaScript/TypeScript code execution, replacing subprocess spawning per execution. It runs on **bun**, the only JavaScript runtime OpenCompany ships — no Node, no npm: `server/nodejs/` is bundled by `bun build src/index.ts --target=bun --outfile=dist/index.js` (self-contained, express inlined; `company build` step [3/6], and the desktop stage script runs the same `bun run build`), and `nodes/code/_runtime.py` spawns `[bun, dist/index.js]`, resolving the binary through `server/core/js_runtime.py` (`OPENCOMPANY_BUN_BIN` override, else `bun` on PATH). Verified on bun 1.4.0 with Node stripped from PATH, including `node:vm` `runInContext` with the timeout. **Plugin-owned (July 2026):** the sidecar is supervised by `nodes/code/_runtime.py` (`NodeJSExecutorRuntime`, same `BaseProcessSupervisor` pattern as WhatsApp/Temporal) and spawns on demand from `acquire_client()` on the first JS/TS node execution — in every run mode, with no CLI service wiring. Client + config are plugin-owned too (`nodes/code/_client.py`, `NODEJS_EXECUTOR_*` env vars; core `Settings` carries no executor fields).**Architecture:**```┌─────────────────────────────────────────────────────────────┐│ Python Backend (PYTHON_BACKEND_PORT) ││ ┌────────────────┐ HTTP/JSON ┌──────────────────┐ │-│ │ NodeJSClient │◄──────────────────►│ Node.js Server │ │-│ │ (aiohttp) │ NODEJS_EXECUTOR_PORT │ (Express + tsx)│ │+│ │ NodeJSClient │◄──────────────────►│ bun sidecar │ │+│ │ (aiohttp) │ NODEJS_EXECUTOR_PORT │ (Express) │ ││ └────────────────┘ └──────────────────┘ ││ ▲ ││ │ │@@ -268,23 +268,25 @@ Persistent Node.js server for JavaScript/TypeScript code execution, replacing su**Files:**```server/nodejs/-├── package.json # Dependencies: express, tsx+├── package.json # Dependency: express (inlined into the bundle). Scripts: build = `bun build src/index.ts --target=bun --outfile=dist/index.js`,+│ # start = `bun dist/index.js`, dev = `bun --watch src/index.ts`; engines = { bun >= 1.4.0 }. No esbuild, no tsx.├── tsconfig.json # TypeScript config (ES2024)+├── dist/index.js # Self-contained bundle (gitignored; built by `company build` / the desktop stage script; ships pre-built in the tarball)└── src/└── index.ts # Express server with /execute, /health, /packages/*-server/services/+server/core/js_runtime.py # How the backend finds bun (OPENCOMPANY_BUN_BIN, else PATH) + the shared packages tree helpers-server/nodes/code/ # Executor plugins (javascript_executor, typescript_executor)+server/nodes/code/ # Executor plugins (javascript_executor, typescript_executor) + _runtime.py (spawns [bun, dist/index.js]) + _client.py```**Endpoints:**| Endpoint | Method | Description ||----------|--------|-------------|-| `/health` | GET | Health check with Node.js version |+| `/health` | GET | Health check: `runtime: "bun"`, `runtime_version`, and still `node_version` (the Node API level bun reports) || `/execute` | POST | Execute JS/TS code with input_data and timeout |-| `/packages/install` | POST | Install npm packages to user-packages |-| `/packages` | GET | List installed packages |+| `/packages/install` | POST | Install npm-registry packages into user-packages via `bun add` (run through `process.execPath`, i.e. the sidecar's own bun) |+| `/packages` | GET | List installed packages from the user-packages dir's `package.json` |**Environment Variables:**| Variable | Default | Description |@@ -526,7 +528,7 @@ class CacheEntry(SQLModel, table=True):- `cleanup_expired_cache()` - Remove expired entries## Codebase Summary-- **Hybrid architecture**: Python (FastAPI + Pydantic plugins) + React/TypeScript frontend + Node.js subprocess for JS/TS code execution.+- **Hybrid architecture**: Python (FastAPI + Pydantic plugins) + React/TypeScript frontend + a bun-hosted Express sidecar for JS/TS code execution (bun is the only JavaScript runtime and package manager anything shipped needs; Node is dev/CI-only).- **Backend NodeSpec is the single source of truth.** Plugins live in [`server/nodes/<group>/<plugin>/__init__.py`](./server/nodes/) (or a single `.py` inside a domain folder) and auto-register via `BaseNode.__init_subclass__`. Authoritative node count is `len(services.node_registry.NODE_METADATA)` after `import nodes`; never a file glob (`**/__init__.py` also matches group packages, and excluding `__init__.py` drops most plugins). Folders cover agent / model / android / google / microsoft / whatsapp / whatsapp_business / twitter / telegram / discord / social / email / search / scraper / document / code / filesystem / proxy / location / chat / text / scheduler / trigger / tool / utility / workflow / skill / context / vision / browser / speech / translate / stripe / vercel / github / cloudflare / gcloud.- **WebSocket-first frontend-backend communication.** Authoritative handler count is the size of the `MESSAGE_HANDLERS` dict in [`server/routers/websocket.py`](./server/routers/websocket.py) plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain the count in this doc — it drifts on every plugin add.- **Plugin-first architecture (Wave 11).** One plugin = one authoring location (a folder rooted at `__init__.py`, or a single `.py` inside a domain folder). `services/handlers/` shrank from 12.8K → 1.1K LOC across 16 → 4 files. Live invariant total via `pytest --collect-only`.@@ -744,7 +746,7 @@ Execution routing falls back Temporal → sequential; the Temporal dev server +## Development Commands-**Package manager: bun** (pinned via `packageManager: [email protected]` in the root package.json). Source checkouts are gated to bun by `scripts/preinstall.js` (keys on `bunfig.toml` + a `bun` user agent) — `npm install` in the repo is rejected with a pointer to https://bun.sh; end-user installs of the published npm package are unaffected. `bunfig.toml` pins the **isolated linker** (pnpm-style symlinked `node_modules` with the store at `node_modules/.bun/`), the lockfile is the tracked text `bun.lock`, and Node remains the runtime (floor Node 18+ per `engines.node` and `bin/cli.js`; CI and the desktop bundle use 22 LTS) — bun only installs and runs scripts, never executes tools with `--bun`. Security pins live in the top-level `overrides` block (version-ranged keys). See [CONTRIBUTING.md](./CONTRIBUTING.md) → "Known differences from pnpm" for the guards that changed in the 2026-08 pnpm→bun migration.+**Package manager and JavaScript runtime: bun** (pinned via `packageManager: [email protected]` in the root package.json; `engines` is `{"bun": ">=1.4.0"}`). Source checkouts are gated to bun by `scripts/preinstall.js` (keys on `bunfig.toml` + a `bun` user agent) — `npm install` in the repo is rejected with a pointer to https://bun.sh. `bunfig.toml` pins the **isolated linker** (pnpm-style symlinked `node_modules` with the store at `node_modules/.bun/`) and the lockfile is the tracked text `bun.lock`. bun is also the only JavaScript runtime anything shipped needs: the `company` shim (`bin/cli.js`, `#!/usr/bin/env bun`), the JS executor sidecar (`bun build --target=bun` bundle run as `bun dist/index.js`) and the plugin CLIs in the shared `~/.opencompany/packages/` tree all run on it (`server/core/js_runtime.py`; `tests/core_config/test_js_runtime.py::test_backend_never_spawns_node_or_npm` forbids `shutil.which("node"|"npm"|"npx")` under `server/`), end users install with `bun add -g @zeenie-ai/opencompany`, and the desktop app bundles bun instead of Node. Node is dev/CI-only: when it is present bun runs vite / vitest / eslint / playwright / electron-builder on it via their node shebangs (vitest and eslint have open bugs on the bun runtime), so `--bun` is never passed; `company build` treats Node as optional and `.github/actions/setup` installs Node 22 for that reason alone. Security pins live in the top-level `overrides` block (version-ranged keys). See [CONTRIBUTING.md](./CONTRIBUTING.md) → "Known differences from pnpm" for the guards that changed in the 2026-08 pnpm→bun migration.### CLI Commands (after the global install)```bash@@ -754,6 +756,7 @@ company dev --force # ...forcing Vite to re-bundle deps (recovers "Outdated Optcompany stop # Stop all servicescompany build # Build for productioncompany clean # Clean build artifacts+company provision # Set up the Python side of a global install (automatic on first use; --force redoes it)company help # Show all commands```@@ -769,7 +772,7 @@ bun run deploy # Self-deploy to a cloud VM (python -m cli deploy)No root script hops through `npm run`; cross-package scripts use `bun --cwd=<dir> run <script>`.### Cross-Platform Scripts-Service orchestration lives in the Python CLI (`company start/dev/stop/build/clean/serve/daemon/deploy/docs/version` — see `cli/`). The `scripts/` directory retains only the npm install lifecycle helpers (`install.js`, `preinstall.js`, `postinstall.js`). `company start` is single-port: uvicorn serves API + WS + built SPA on the backend port (`SERVE_STATIC_CLIENT`, default on); the retired `scripts/serve-client.js` static server and its `:3000` frontend port are gone.+Service orchestration lives in the Python CLI (`company start/dev/stop/build/clean/serve/daemon/deploy/docs/version` — see `cli/`). The `scripts/` directory retains only the install lifecycle helpers (`install.js`, `preinstall.js`, `postinstall.js` — `#!/usr/bin/env bun`; run by `bun install` in a checkout, and eagerly by the installers or lazily by `bin/cli.js` on the first `company` command of a `bun add -g` install, which runs no dependency lifecycle scripts). `company start` is single-port: uvicorn serves API + WS + built SPA on the backend port (`SERVE_STATIC_CLIENT`, default on); the retired `scripts/serve-client.js` static server and its `:3000` frontend port are gone.See **[Scripts Reference](./docs-internal/SCRIPTS.md)** for full documentation.@@ -777,7 +780,7 @@ See **[Scripts Reference](./docs-internal/SCRIPTS.md)** for full documentation.✅ **Plugin-first architecture (Wave 11)**: every plugin is a self-contained folder under `server/nodes/<group>/<plugin>/` rooted at `__init__.py`; backend NodeSpec is the SSOT for icon, colour, handles, params, output schema, uiHints. Frontend renders via `useNodeSpec` + `componentKind` dispatch.✅ **WebSocket-First Architecture**: most frontend-backend RPC goes through WebSocket; live handler set lives in `MESSAGE_HANDLERS` in `server/routers/websocket.py`✅ **Code Editor**: Python, JavaScript, and TypeScript executors with syntax-highlighted editor (react-simple-code-editor + prismjs) and console output-✅ **Node.js Executor**: Persistent Node.js server (Express + tsx) for fast JS/TS execution, replacing subprocess spawning+✅ **JS Executor Sidecar**: Persistent Express server on bun (`bun build --target=bun` bundle, no Node or npm anywhere shipped) for fast JS/TS execution, replacing subprocess spawning✅ **Component Palette**: Emoji icons with distinct dracula-themed category colors, localStorage persistence for collapsed sections✅ **Android Integration**: 16 Android service nodes with ADB automation and remote WebSocket support✅ **Conditional Parameter Display**: Dynamic UI rendering based on parameter values (displayOptions.show)@@ -1179,12 +1182,12 @@ curl -I http://localhost:${PYTHON_BACKEND_PORT:-5678}# TypeScript validation — the gate is TypeScript 7 (native Go) at the REPO ROOT.bun run typecheck # root: tsc --noEmit -p client/tsconfig.jsonbun run --filter react-flow-client typecheck # what CI runs; delegates up to the same gate-# NOT `npx tsc --noEmit` — there is no root tsconfig.json.+# NOT a bare `bun x tsc --noEmit` (or `npx tsc`) — there is no root tsconfig.json.# NOT client's `typecheck:tsc` — that resolves [email protected], kept only because# typescript-eslint's peer range excludes 6/7. It is a second opinion, not the gate.# Build verification-npm run build+bun run build```## Production Deployment@@ -1193,9 +1196,11 @@ npm run buildOne command provisions a login-gated OpenCompany VM on a cloud provider. Two stages: theoperator's **cloud CLI** (gcloud; the AWS Terraform module in `cli/terraform/aws/` is complete and validated on t3.micro, but the `providers/aws.py` CLI adapter is still a stub that exits 1) handles auth + project/region/zone resolution +ADC verification + API enablement, then **Terraform** (`cli/terraform/gcp/`) owns all resources —-VM (new deployments use the `opencompany` resource id), firewall, artifact bucket (local `npm pack` source), service-account, and a cloud-init startup script that installs Node 22 + uv + the package and runs-`company serve` under systemd. Login gate = built-in auth (`VITE_AUTH_ENABLED=true`,+VM (new deployments use the `opencompany` resource id), firewall, artifact bucket (local `bun pm pack --quiet` source), service+account, and a cloud-init startup script that installs bun (`BUN_INSTALL=/usr/local`, official installer) + uv, `bun add -g`s the package,+provisions the Python side with `company provision` (a global add runs no lifecycle scripts; the shim knows its own package root, since where bun keeps global packages varies by platform) and runs+`company serve` under systemd — no Node, no npm on the VM. The AWS template instead delegates to `install.sh` as the login user and+points systemd at `$APP_HOME/.bun/bin/company` with a PATH `Environment=` line. Login gate = built-in auth (`VITE_AUTH_ENABLED=true`,`AUTH_MODE=single`) with the owner credential generated at deploy time and seeded on first boot.`build_app_env` (`cli/commands/deploy/_secrets.py`) also sets `DEPLOYMENT_MODE=cloud` ondeployed VMs and mints fresh `JWT_SECRET_KEY` / `SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` per deploy.@@ -1207,7 +1212,7 @@ company deploy destroy # terraform des```Key files: `cli/commands/serve.py` (single-port runtime: one supervised uvicorn process fronting API + WS + built SPA;-the Node.js code-exec sidecar, WhatsApp and Temporal are backend-spawned on demand), `cli/commands/deploy/` (verbs, secrets, Terraform driver, provider CLI adapters),+the bun-hosted JS code-exec sidecar, WhatsApp and Temporal are backend-spawned on demand), `cli/commands/deploy/` (verbs, secrets, Terraform driver, provider CLI adapters),`cli/terraform/gcp/` (HCL module + `startup.sh.tftpl`). Deployment state lives at`<user-data>/deploy/opencompany/` (preserved by `company clean` — see `_OPENCOMPANY_KEEP`); only`company deploy destroy` removes it. The deploy code is fully delinked from `company build` /@@ -2733,7 +2738,7 @@ This function:- **Skill System Architecture**: Skills organized in `server/skills/<folder>/` subfolders. Each folder appears in Master Skill dropdown. DB/Master Skill customization is authoritative. Standard skills use progressive disclosure without modifying the agent system prompt: the dynamically connected `Skill` tool carries the bounded name/description catalogue, loads instructions, then separately reads/searches declared resources. Personality skills remain eager. Duplicate connected names block with `DUPLICATE_CONNECTED_SKILL_NAME`. Runtime state and sanitized `agent.skill.*` observability live in [`skill_runtime.py`](./server/services/skill_runtime.py); tool results persist in the current conversation while canvas badges clear at turn end. Icon resolution mirrors `BaseNode._metadata_dict`: per-plugin `<plugin>/icon.svg` (served as `/api/schemas/nodes/<type>/icon`) → `visuals.json` (emoji / `lobehub:<brand>`); color: per-plugin `<plugin>/meta.json` → `visuals.json`. Lives in [`skill_loader.py::_parse_skill_metadata`](./server/services/skill_loader.py). Native DOM keydown handler prevents React Flow from intercepting Ctrl shortcuts in skill editor. **Mutation broadcasts use the CloudEvents-typed `skill_lifecycle` wire key** with stages `created` / `updated` / `deleted` / `content_saved` — see "Plugin-folder location for plugin-specific CloudEvents factories" below.- **Example Workflows**: Auto-load example workflow seeds from `<repo>/.opencompany/workflows/` on first use (git-tracked; the only non-ignored content under `<repo>/.opencompany/`). Path resolved by `core.paths.example_workflows_dir()` — fixed, NOT under `DATA_DIR`, preserved by `company clean` via `_OPENCOMPANY_KEEP`. Uses `UserSettings.examples_loaded` flag; supports anonymous users (`user_id="default"`); embedded `nodeParameters` saved to DB on import.- **Onboarding Service**: 4-step welcome wizard (Welcome, How it works, Connect your AI, Try it) using shadcn primitives + lucide icons. Database-backed via `UserSettings.onboarding_completed` + `onboarding_step`. Existing users auto-skip (migration marks `examples_loaded=1` as completed). Replayable from Settings "Help" section. No new WebSocket handlers needed. See [Onboarding Service](./docs-internal/onboarding.md) for details.-- **Node.js Code Executor**: Persistent Node.js server (Express + tsx) at `NODEJS_EXECUTOR_PORT` for JavaScript/TypeScript execution, replacing subprocess spawning per execution. The code executor plugins under `server/nodes/code/` call `NodeJSClient` which makes HTTP requests to the Node.js server. All config via environment variables (`NODEJS_EXECUTOR_URL`, `NODEJS_EXECUTOR_PORT`, etc.).+- **JS/TS Code Executor (bun sidecar)**: Persistent Express server on bun at `NODEJS_EXECUTOR_PORT` for JavaScript/TypeScript execution, replacing subprocess spawning per execution. `server/nodejs/` is bundled by `bun build src/index.ts --target=bun --outfile=dist/index.js` (express inlined) and spawned as `[bun, dist/index.js]` by `nodes/code/_runtime.py`, with bun resolved through `server/core/js_runtime.py` (`OPENCOMPANY_BUN_BIN`, else PATH) — no Node or npm anywhere shipped. The code executor plugins under `server/nodes/code/` call `NodeJSClient` which makes HTTP requests to the sidecar. All config via environment variables (`NODEJS_EXECUTOR_URL`, `NODEJS_EXECUTOR_PORT`, etc. — the names are unchanged).- **writeTodos Tool Node**: Dedicated AI tool for task planning connecting to any agent's `input-tools` handle. `TodoService` singleton (`server/services/todo_service.py`) stores JSON-based per-session todo state keyed by workflow_id. Handler broadcasts `phase: "todo_update"` via WebSocket on each update for real-time UI. (The former checklist rendering — `formatTodoOutput()` — lived only in the legacy `ui/OutputDisplayPanel.tsx`, which was deleted as dead code; the active `components/output/OutputPanel.tsx` shows todo results as regular JSON.) Schema uses `TodoItem`/`TodoStatus` Pydantic enum. Skill at `server/skills/assistant/write-todos-skill/SKILL.md` teaches the plan-work-update loop.- **Temporal Activity Heartbeats**: Activities send `activity.heartbeat()` on every non-matching WebSocket broadcast inside the read loop in `services/temporal/activities.py`. This keeps long-running browser and claude_code_agent operations alive past the 2-minute `heartbeat_timeout`. Start/end heartbeats alone were causing `TIMEOUT_TYPE_HEARTBEAT` failures on ops taking 5-10 minutes. Connection config: `heartbeat=30`, `receive_timeout=None` (each receive is bounded by a 30 s `asyncio.wait_for`; liveness comes from heartbeats, and per-node activities run under a 24 h `start_to_close_timeout`).- **WebSocket `_safe_send` Guard**: `server/routers/websocket.py` checks `websocket.client_state.name != "CONNECTED"` before sending and logs at `debug` level (not `error`) on failure. Prevents "ASGI message after websocket.close" errors when broadcasts race with disconnects.@@ -2745,15 +2750,15 @@ This function:- **Execution correlation IDs**: `handle_execute_node` issues a `uuid4().hex` token at request entry, propagates it through every `node_status` / `node_output` broadcast for the run, and returns it in the response payload as `execution_id`. Frontend `ExecutionResult.executionId` carries it; `OutputSection` dedups runs by it instead of `JSON.stringify(outputs)` (which collapsed distinct executions whose payloads matched). Same trace-id pattern as OpenTelemetry / HTTP request ids.- **`clear_node_status` idle reset**: `StatusBroadcaster.clear_node_status(node_id)` resets the slot to `{status: "idle", data: {}, cleared: true}` instead of `del`'ing it. Deleting created a race window where the in-flight execution's `success` broadcast re-created the entry and stuck the UI on "completed" for a cancelled node. Idle reset preserves entry identity so subsequent broadcasts update normally; the `cleared: true` flag distinguishes "never ran" from "explicitly cleared."- **`get_node_output` race**: in-memory `_outputs` cache re-population after a DB-fallback `await` previously overwrote a fresh in-memory write with a stale DB value. Fix uses nested `dict.setdefault` (atomic at the CPython GIL level -- no lock needed). `store_node_output` and `clear_all_outputs` had no real race because asyncio coroutines do not preempt at synchronous statements. Reference for the Python concurrency model: https://docs.python.org/3/library/asyncio-task.html#asyncio-await-- **`NodeUserError` (services.plugin)**: typed exception for user/LLM-correctable failures (string not found, command not found, bad cwd, missing required field, operator-only Twitter query, Python sandbox `import`, Node.js sidecar down). `BaseNode.execute()` catches it specifically: single WARN line in the operator log (no traceback) + structured `{success: False, error_type: "NodeUserError", error: ...}` envelope. Genuine bugs still flow through the generic `except Exception` branch and keep their full stacktrace via `logger.exception`. Adopted across `fileRead` / `fileModify` / `fsSearch` / `gallery` / `process_manager` / `pythonExecutor` / `javascriptExecutor` / `typescriptExecutor`. **Plugin WS handlers that can fail user-correctably must use `@ws_response` (from `services.plugin.ws`), not `@ws_handler`** — the latter logs every exception at ERROR with a full traceback, which breaks the one-WARN-line `NodeUserError` contract. `gallery/_handlers.py` is the reference. Reach for it whenever the LLM (or user) can fix the input and retry — never for actual server bugs.-- **Process manager Windows shim resolution**: `process_service.start()` resolves `argv[0]` via `shutil.which()` before `asyncio.create_subprocess_exec`. On Windows, `shutil.which` honours `PATHEXT` and returns the absolute `.cmd` path (e.g. `C:\...\npm.cmd`); `CreateProcessW` then launches it directly. No `cmd /c` wrap — same canonical idiom used by `nodes/browser/`, `nodes/agent/claude_code_agent/_pool.py`, `nodes/agent/claude_code_agent/_oauth.py`, `nodes/email/_himalaya.py`. Without this, bare `argv[0]="npm"` raises `WinError 2` because `CreateProcessW` does NOT apply `PATHEXT` to bare names. Missing binary → early `Command not found: '<bin>'. Check spelling or ensure the binary is on PATH.` envelope (no traceback).+- **`NodeUserError` (services.plugin)**: typed exception for user/LLM-correctable failures (string not found, command not found, bad cwd, missing required field, operator-only Twitter query, Python sandbox `import`, JS executor sidecar down). `BaseNode.execute()` catches it specifically: single WARN line in the operator log (no traceback) + structured `{success: False, error_type: "NodeUserError", error: ...}` envelope. Genuine bugs still flow through the generic `except Exception` branch and keep their full stacktrace via `logger.exception`. Adopted across `fileRead` / `fileModify` / `fsSearch` / `gallery` / `process_manager` / `pythonExecutor` / `javascriptExecutor` / `typescriptExecutor`. **Plugin WS handlers that can fail user-correctably must use `@ws_response` (from `services.plugin.ws`), not `@ws_handler`** — the latter logs every exception at ERROR with a full traceback, which breaks the one-WARN-line `NodeUserError` contract. `gallery/_handlers.py` is the reference. Reach for it whenever the LLM (or user) can fix the input and retry — never for actual server bugs.+- **Process manager Windows shim resolution**: `process_service.start()` resolves `argv[0]` via `shutil.which()` before `asyncio.create_subprocess_exec`. On Windows, `shutil.which` honours `PATHEXT` and returns the absolute path including the extension (e.g. a `C:\...\npm.cmd` for a generic `.cmd` shim; the shims bun writes for the plugin CLIs in the shared packages tree are `<name>.exe` launchers plus a `<name>.bunx` file, never `.cmd`); `CreateProcessW` then launches it directly. No `cmd /c` wrap — same canonical idiom used by `nodes/browser/`, `nodes/agent/claude_code_agent/_pool.py`, `nodes/agent/claude_code_agent/_oauth.py`, `nodes/email/_himalaya.py`. Without this, bare `argv[0]="npm"` raises `WinError 2` because `CreateProcessW` does NOT apply `PATHEXT` to bare names. Missing binary → early `Command not found: '<bin>'. Check spelling or ensure the binary is on PATH.` envelope (no traceback).- **Gallery — the workspace file explorer (`gallery`, `nodes/filesystem/gallery/`)**: sibling of the process-manager pattern below — the `isGalleryPanel` uiHint gives it a full-height MiddleSection panel (breadcrumbs, grid/list, image thumbnails, search, preview, upload) instead of the plain params list. It pairs the hint with `hideInputSection` but **keeps** the Output section, because unlike `processManager` it produces output worth seeing and dragging. Four rules worth knowing before touching it: (1) **The panel edits the node's own params** — navigating writes `path`, pinning writes `selection` — so what you browse is what the node emits, rather than a second copy of that state free to drift. (2) **The backend decides; the panel renders.** Each listing row arrives with a finished `ref` (a serialized `FileRef`, `null` for directories) and a `preview` verdict from `services/media/preview.py`; breadcrumbs arrive as `crumbs`; a search term is turned into a glob by `search_to_pattern` server-side. Re-deriving any of these client-side would be a second copy of a server rule — and for `preview` specifically, a second copy of a *security* decision. (3) **Drag uses its own `workspaceFile` discriminator, never the existing `nodeOutput`** — that branch calls `onChange(value)` unconditionally, so reusing it would mean dropping a file into a half-written prompt destroys the prompt. `ParameterRenderer.handleDrop` therefore branches: a `file` param takes the ref whole, everything else appends the path with smart spacing. (4) **`isFileRef` accepts every `FileKind`, not just `audio`** — the gallery emits `kind: "file"` even for a `.wav`, because `kind: "audio"` asserts `inspect_audio` probed the container and a fabricated duration would mis-bill a per-second provider downstream; narrowing the check back would render a dropped file as raw JSON. Listing rides the WebSocket (`list_workspace_files`) because the consumer already holds an authenticated socket with request correlation; `GET /api/workspace/{id}/files/{path}` stays the *content* channel (preview, download, Range). Frontend: [GalleryPanel.tsx](./client/src/components/parameterPanel/GalleryPanel.tsx) + `parameterPanel/gallery/`, [useDragWorkspaceFile.ts](./client/src/hooks/useDragWorkspaceFile.ts), [types/workspaceFiles.ts](./client/src/types/workspaceFiles.ts).- **Canvas — the pushed-content display board (`canvas`, `nodes/tool/canvas/`)**: the third full-height-panel sibling (gallery / processManager / canvas), and the first with a SECOND host — a docked resizable right sidebar ([CanvasDock.tsx](./client/src/components/ui/CanvasDock.tsx) + [canvasDockStore.ts](./client/src/stores/canvasDockStore.ts)) that auto-opens on push and serves ephemeral click-to-preview from the gallery dialog. Both hosts render one shared component ([parameterPanel/canvas/CanvasContent.tsx](./client/src/components/parameterPanel/canvas/CanvasContent.tsx)). Rules worth knowing before touching it: (1) **The broadcast is identity-only** — `canvas_updated` carries `{workflow_id, node_id, revision}`; content flows solely through the authorized `canvas_list` handler (simple_memory security preamble: external socket + owner + graph-ownership, exactly-one-node-of-type check). (2) **The board stores references, never bytes** — `display(paths=…)` builds refs via `resolve_media` + stat (never `coerce_file_param`; don't read content to make a pointer), notes cap at 64KB with a visible marker, the board FIFO-caps at 200, and the op's Output is ids+counts only. (3) **Iframe sandboxes are test-locked security decisions**: external URLs get exactly `sandbox="allow-scripts allow-forms"` + `no-referrer`; workspace HTML renders ONLY as `srcDoc` + `sandbox="allow-scripts"` (opaque origin, no cookies — `NEVER_INLINE` respected, not worked around); PDF is a plain same-origin iframe enabled by the `INLINE_EXACT` exact-match set in `preview.py`. (4) **Never `addEventListener('canvas_updated')`** — the WebSocketContext switch case shadows the default-case fan-out. (5) The `tool` group auto-derives `isConfigNode: True`; canvas declares it `False` because `input-main` is real dataflow. (6) `hooks/useWorkspaceText.ts` is the repo's first client-side file-content fetch (streamed, cancelled at 512KB, key self-busts on `size_bytes`+`modified_at`) — attachment disposition doesn't block `fetch()`. Browser screenshots became its feedstock: both browser plugins persist shots as workspace FileRefs via the tolerant, containment-checked [nodes/browser/_screenshots.py](./server/nodes/browser/_screenshots.py). Full reference: [docs-internal/canvas_node.md](./docs-internal/canvas_node.md).- **Process manager port admission + middle panel**: server commands declare listener `ports` (with compatibility inference for `--port`, `-p`, `PORT`, and `*_PORT`). `ProcessService.start()` serializes admission, checks managed reservations plus OS TCP listeners, and returns structured `PORT_IN_USE` without killing the owner or allowing framework auto-port fallback. Explicit ports/environment survive restart. The `isProcessManagerPanel` UI hint gives only `processManager` a full-height workflow-scoped process table with PID/ports/timestamps/elapsed/output and stop/restart controls. See [docs-internal/process_manager.md](./docs-internal/process_manager.md).- **Telegram message auto-split + caption spill**: the Bot API caps `sendMessage.text` at 4096 and media captions at 1024 (constants `_TG_TEXT_LIMIT` / `_TG_CAPTION_LIMIT` in `nodes/telegram/_service.py`; per https://core.telegram.org/bots/api). **Both limits are measured in UTF-16 code units, not characters** — an emoji costs 2 — so length goes through `_tg_len`, never `len()`. `_split_head` cuts one chunk at the cleanest paragraph → line → sentence → space boundary past the halfway mark, else hard-cuts; `_split_text` loops it. `send_message` chunks long text and threads each part under the previous (`reply_to_message_id` cascade), returning the first message's metadata + `parts` + `message_ids[]`. `_send_captioned_media` (used by `send_photo` / `send_document`) truncates an over-long caption at the cap and sends the remainder as a threaded reply with `disable_notification=True`, reporting `caption_truncated` + `follow_up_message_ids` — previously the whole send just failed with `BadRequest("Message caption is too long")`. **Ordering invariant: split the RAW body before `_resolve_body` runs markdown→HTML.** Splitting after conversion can separate a `<b>` from its closing tag, which Telegram rejects with "can't find end of the entity"; Telegram measures the cap against entity-parsed text, so truncating raw markdown is conservative. Locked by `tests/nodes/test_telegram_service.py`.- **Telegram inbound content types**: `_format_message` extracts detail dicts for all 11 types via the `_CONTENT_PROBES` / `_DETAIL_EXTRACTORS` tables, plus a normalized `media` block (`kind` / `file_id` / `mime_type` / `file_name` / …) that downstream nodes read instead of branching per type; MIME and filename are synthesised where Telegram omits them. **Probe order is load-bearing**: Telegram sets `message.document` on animation messages too, so `animation` and `video_note` must be probed before `document` and `video` or every GIF classifies as a document. The trigger never downloads — media travels as a `file_id`, never bytes or base64, because node results are persisted, broadcast, and replayed into the LLM conversation every turn.- **Google OAuth scope expansion**: Google's authorisation server legitimately returns a wider scope set than requested when the OAuth Client's "Data Access" page lists extra scopes (commonly `cloud-platform`) or when `include_granted_scopes` replays a previously-granted scope. `oauthlib` does strict set-equality and aborts with `Warning: Scope has changed`. As of 2026 (`google-auth-oauthlib` 1.2.4, `oauthlib` upstream issue #562 still open), no constructor flag, context manager, or `expected_scopes` argument exists — the documented relief is the env var. `server/nodes/google/_oauth.py` sets `OAUTHLIB_RELAX_TOKEN_SCOPE=1` via `os.environ.setdefault` BEFORE the `google_auth_oauthlib.flow` import (oauthlib reads it once at parameters-module import; request-time setting races under uvicorn workers), paired with `warnings.filterwarnings(message=r"Scope has changed.*")` to keep the operator log clean. Long-term root cause: audit the Cloud Console Data Access page and remove `cloud-platform` if no handler uses it.-- **Code-executor error mapping** (`pythonExecutor` / `javascriptExecutor` / `typescriptExecutor`): wrap user-code execution and sidecar calls in `try/except`. Python: detect `ImportError("__import__ not found")` (the LLM tried `import X` against the sandboxed builtins) and surface the pre-injected names list (`math, json, datetime, timedelta, re, random, Counter, defaultdict`) plus the suggestion to use `process_manager` for unsupported modules; other exceptions get formatted as `<ErrorName> at line N: <message>` (line N walked from `<string>` frame in the traceback) plus any captured stdout. JS/TS: detect `aiohttp.ClientConnectorError` and surface "JavaScript executor not running on NODEJS_EXECUTOR_PORT. Start the dev runner or fall back to python_executor." All raise `NodeUserError` so the framework logs one WARN line — no aiohttp/CreateProcessW noise in the operator log.+- **Code-executor error mapping** (`pythonExecutor` / `javascriptExecutor` / `typescriptExecutor`): wrap user-code execution and sidecar calls in `try/except`. Python: detect `ImportError("__import__ not found")` (the LLM tried `import X` against the sandboxed builtins) and surface the pre-injected names list (`math, json, datetime, timedelta, re, random, Counter, defaultdict`) plus the suggestion to use `process_manager` for unsupported modules; other exceptions get formatted as `<ErrorName> at line N: <message>` (line N walked from `<string>` frame in the traceback) plus any captured stdout. JS/TS: detect `aiohttp.ClientConnectorError` / the spawn `RuntimeError` (bun missing or `dist/index.js` not built) and surface "JavaScript executor is unavailable (bun sidecar at <NODEJS_EXECUTOR_URL>). Fall back to python_executor for similar logic." All raise `NodeUserError` so the framework logs one WARN line — no aiohttp/CreateProcessW noise in the operator log.- **Workflow-scoped chat + console history**: chat messages persist with `chat_messages.session_id == <workflow_id>` (or `"default"` when no workflow is open); console logs persist with `console_logs.workflow_id`. Backend `database.get_console_logs(limit, workflow_id=None)` and `clear_console_logs(workflow_id=None)` filter by workflow when given. `handle_clear_console_logs` broadcasts `console_logs_cleared` carrying the `workflow_id` so the existing frontend filter in `WebSocketContext` keeps other workflows' panels intact. Frontend reads `currentWorkflow.id` via the documented Zustand escape hatch (`useAppStore.getState().currentWorkflow?.id`) at call time for `clearChatMessages` / `clearConsoleLogs` / `sendChatMessage` so the callbacks don't re-create on every workflow switch. A dedicated `useEffect([currentWorkflowId, isReady])` resets local `chatMessages` / `consoleLogs` and refetches both when the user opens / switches workflow. Incoming `console_log` broadcasts are filtered by `currentWorkflow.id` so a parallel run on another workflow never bleeds into the active panel. Legacy logs without `workflow_id` still surface (transition guard).- **Auto-derived `isConfigNode` uiHint**: `_derive_auto_ui_hints(group)` in `services/plugin/base.py` automatically sets `uiHints.isConfigNode: True` on any plugin whose `group` tuple contains `memory` or `tool` (centralized as `_CONFIG_NODE_GROUPS = frozenset({"memory", "tool"})`). Explicit `cls.ui_hints` always wins (merge order: auto first, then `dict.update`). Frontend `InputSection.tsx` consumes the flag via `definition?.uiHints?.isConfigNode === true` — the old `groups.includes('memory') || groups.includes('tool')` heuristic is gone. Pytest invariant `test_ui_hints_only_carry_known_flags` locks the flag name. Adding a new auxiliary node type costs zero per-plugin code; opting out costs one line (`ui_hints = {"isConfigNode": False}`).- **`isMasterSkillEditor` uiHint replaces `node.type === 'masterSkill'` checks**: 6 frontend callsites (`Dashboard.tsx:139` component dispatch, `useAutoSkillEdges.ts` constant + edge filter, `MiddleSection.tsx` × 3) now read `getCachedNodeSpec(type)?.uiHints?.isMasterSkillEditor === true` instead of comparing the type string. The `MasterSkillNode` plugin already declared the hint — no backend change. Renaming the plugin's `type` is now a single backend edit followed by a NodeSpec deploy; the frontend never needs to know the string.@@ -2769,8 +2774,8 @@ This function:- **Telegram owner detection — three layers** (f746ddf): the bot owner is captured by THREE independent paths so the realistic setup flows all converge to a working state. (1) **Explicit field**: secondary `FieldDef` in the credentials modal lets the user paste their Telegram user ID directly (recommended; works without DM'ing the bot). (2) **Pre-poll peek** in `connect()` via `_capture_owner_from_pending_updates()` — calls `bot.get_updates(timeout=0)` BEFORE `start_polling(drop_pending_updates=True)` discards the queue, scans for any historical private DM, captures + persists atomically. (3) **Atomic write-through in `_on_message_received`** — persists FIRST, sets in-memory ONLY on success. Invariant: "in-memory has owner ⇒ DB has owner" so a process restart can re-capture cleanly. Failure logged at `ERROR` with `exc_info=True` (was `WARNING` previously, masking persist failures). The lazy fallback in `telegram_send.py` (read DB → `service.set_owner`) sits on top of all three.- **Supervisor Job Object loud-failure (cli/tree.py + cli/supervisor.py)** (8a64eb9): the Windows process-tree mechanism depends entirely on a Job Object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` (no fallback — `start_new_session` is POSIX-only). `pywin32>=308` is a hard supervisor dependency on Windows; the declaration in the root `pyproject.toml` (where `opencompany-cli` lives — `cli/pyproject.toml` was removed as a stale duplicate) carries an inline comment so future maintainers don't drop it. `_JobObject.__init__` splits failures into explicit `ImportError` (with reinstall command) and `Exception` (with `repr`) branches — both write to `stderr` instead of swallowing. `_JobObject.add()` verifies enrollment via `win32job.IsProcessInJob(handle, self._handle)` after assignment; on mismatch it queries `IsProcessInJob(handle, None)` so the warning explicitly names the wrapper-job hypothesis (npm / bun / conhost wrappers occasionally place us in their own non-nesting Job). `supervisor._spawn_once` checks `add_to_job` return value and emits a yellow `WARN: pid=N not enrolled in Job Object` per child if False. Without these guards, a stale pywin32 install or a wrapping Job Object silently leaks orphan Python processes on every Ctrl-C and they accumulate to the point of holding SQLite locks that block subsequent backend startup.- **Credentials envelope-shape invariant** (dc94cde): the `useCredentialPanel` query stores `{values: CredentialFormValues, hadStored: boolean}` (an envelope, NOT a flat dict). The earlier `writeValues` called `setQueryData<CredentialFormValues>` with a spread `(prev) => ({...prev, [key]: value})`, which at runtime merged the typed character at the envelope level next to `values` and `hadStored` instead of inside `.values` — the input selector `panel.values[field.key]` re-rendered with the original (server) value on every keystroke and the input felt frozen. Fix: `writeValues` now preserves the envelope shape and updates only the inner `values` dict; `hadStored` is preserved verbatim (it reflects real server state, not local edits). When introducing other queries shaped as `{data, meta}` envelopes, follow the same pattern — never spread `prev` as if it were the inner payload.-- **`core.paths` is the SSOT for on-disk locations**: only generic helpers (`data_path` / `packages_dir` / `package_dir(name)` / `daemons_dir` / `workspaces_dir` / `workspace_dir(workflow_id)` / `example_workflows_dir`). Plugin-specific subpaths are composed inline at the plugin's call site — adding a new package never requires touching `core.paths`. Reference subtree under `opencompany_root()` (= `~/.opencompany/` per default `DATA_DIR`): `workspaces/<slug>/` (per-workflow scratch), `daemons/` (supervised event-source daemon cwds — `stripe listen` etc.; shared root by default, no per-namespace subdir), `claude/` (Claude Code's `CLAUDE_CONFIG_DIR` state — composed as `data_path("claude")` in `nodes/agent/claude_code_agent/_oauth.py`), `packages/` (OpenCompany-managed install root). `packages/` holds a **single shared npm tree** — one `package.json` + `package-lock.json` + `node_modules/` covering every OpenCompany-managed npm package (`@anthropic-ai/claude-code`, `edgymeow`, `agent-browser`). Each plugin's `_install.py` runs `npm install <pkg> --prefix <packages_dir>` which extends the shared tree idempotently; npm manages everything else. Non-npm binaries (Stripe CLI, Temporal CLI) sit under sibling subdirs `packages/stripe/`, `packages/temporal/` via `package_dir(name)`. Also under `<DATA_DIR>/`: `whatsapp/` (WhatsApp session DB), `credentials.db` / `workflow.db` / `temporal.db`. Pre-fix `packages_dir()` routed through `platformdirs.user_cache_path("OpenCompany")` (`~/.cache/OpenCompany/` etc.) and the Temporal CLI sat in its own `pooch.os_cache("opencompany-temporal")` namespace — operators reported both as "not local". The WhatsApp Go bridge (`edgymeow`) used to be a top-level pnpm dep at `<repo>/node_modules/edgymeow/`; now OpenCompany-managed via `nodes/whatsapp/_install.py` like the other CLIs. Daemon cwds used to live under `workspaces/_<namespace>/` and polluted per-workflow scratch with framework state. Out of scope: globally-installed binaries (Himalaya — system package manager). Shipped seed workflows are the lone exception — `example_workflows_dir()` is hardcoded to `<repo>/.opencompany/workflows/` (git-tracked seeds, NOT under `DATA_DIR`) so they survive `company clean` and stay at the same path across `DATA_DIR=~/.opencompany` vs `DATA_DIR=.opencompany` configs.-- **`company clean` preserves `.opencompany/{workflows,deploy,packages}/`**: `cli/commands/clean.py` iterates the canonical `<repo>/.opencompany/` and pre-rebrand `<repo>/.machina/` roots and skips anything in `_OPENCOMPANY_KEEP = frozenset({"workflows", "deploy", "packages"})`. Wipes `claude/`, `workspaces/`, `*.db` as before. `workflows/` holds the shipped seed JSONs (git-tracked); `deploy/` holds Terraform state for LIVE cloud resources (only `company deploy destroy` removes it); `packages/` holds the OpenCompany-managed binaries (Temporal CLI ~114 MB, Stripe CLI, shared npm tree) — re-fetchable but expensive, so clean+build cycles stay offline-safe cache hits. Test `cli/tests/test_clean.py::test_opencompany_keep_preserves_workflows_deploy_and_packages` locks the keep-list.+- **`core.paths` is the SSOT for on-disk locations**: only generic helpers (`data_path` / `packages_dir` / `package_dir(name)` / `daemons_dir` / `workspaces_dir` / `workspace_dir(workflow_id)` / `example_workflows_dir`). Plugin-specific subpaths are composed inline at the plugin's call site — adding a new package never requires touching `core.paths`. Reference subtree under `opencompany_root()` (= `~/.opencompany/` per default `DATA_DIR`): `workspaces/<slug>/` (per-workflow scratch), `daemons/` (supervised event-source daemon cwds — `stripe listen` etc.; shared root by default, no per-namespace subdir), `claude/` (Claude Code's `CLAUDE_CONFIG_DIR` state — composed as `data_path("claude")` in `nodes/agent/claude_code_agent/_oauth.py`), `packages/` (OpenCompany-managed install root). `packages/` holds a **single shared, bun-managed packages tree** — one `package.json` + `bun.lock` + `node_modules/` covering every OpenCompany-managed npm-registry package (`@anthropic-ai/claude-code`, `edgymeow`, `agent-browser`, `cf`, `vercel`). Each plugin's `_install.py` calls `core.js_runtime.add_package(spec, trust=...)`, which runs `bun add --cwd <packages_dir> --no-progress [--trust] <spec>` and extends the shared tree idempotently (`ensure_shared_tree()` writes the minimal private manifest first); `bun_binary()` resolves bun from `OPENCOMPANY_BUN_BIN` or PATH, and `shared_tree_bin(name)` returns the shim at `node_modules/.bin/<name>` on POSIX or `<name>.exe` (plus a `<name>.bunx` file) on Windows. The shims run on the bun runtime — no Node or npm anywhere on this path (bun ignores a package's `engines.node`, and shims `node` for the lifecycle scripts it is allowed to run). bun blocks dependency lifecycle scripts unless trusted, so `trust=True` is passed only where a postinstall materialises something the plugin needs: claude-code (stages its native launcher), edgymeow (downloads the Go binary), agent-browser. Binaries that are not npm-registry packages (Stripe CLI, Temporal CLI) sit under sibling subdirs `packages/stripe/`, `packages/temporal/` via `package_dir(name)`. Also under `<DATA_DIR>/`: `whatsapp/` (WhatsApp session DB), `credentials.db` / `workflow.db` / `temporal.db`. Pre-fix `packages_dir()` routed through `platformdirs.user_cache_path("OpenCompany")` (`~/.cache/OpenCompany/` etc.) and the Temporal CLI sat in its own `pooch.os_cache("opencompany-temporal")` namespace — operators reported both as "not local". The WhatsApp Go bridge (`edgymeow`) used to be a top-level pnpm dep at `<repo>/node_modules/edgymeow/`; now OpenCompany-managed via `nodes/whatsapp/_install.py` like the other CLIs. Daemon cwds used to live under `workspaces/_<namespace>/` and polluted per-workflow scratch with framework state. Out of scope: globally-installed binaries (Himalaya — system package manager). Shipped seed workflows are the lone exception — `example_workflows_dir()` is hardcoded to `<repo>/.opencompany/workflows/` (git-tracked seeds, NOT under `DATA_DIR`) so they survive `company clean` and stay at the same path across `DATA_DIR=~/.opencompany` vs `DATA_DIR=.opencompany` configs.+- **`company clean` preserves `.opencompany/{workflows,deploy,packages}/`**: `cli/commands/clean.py` iterates the canonical `<repo>/.opencompany/` and pre-rebrand `<repo>/.machina/` roots and skips anything in `_OPENCOMPANY_KEEP = frozenset({"workflows", "deploy", "packages"})`. Wipes `claude/`, `workspaces/`, `*.db` as before. `workflows/` holds the shipped seed JSONs (git-tracked); `deploy/` holds Terraform state for LIVE cloud resources (only `company deploy destroy` removes it); `packages/` holds the OpenCompany-managed binaries (Temporal CLI ~114 MB, Stripe CLI, the shared bun packages tree) — re-fetchable but expensive, so clean+build cycles stay offline-safe cache hits. Test `cli/tests/test_clean.py::test_opencompany_keep_preserves_workflows_deploy_and_packages` locks the keep-list.- **No raw `print()` outside three sanctioned helpers**: `main._startup_log` (pre-logger boot markers), `core.container._clog` (DI-bootstrap markers), and `nodes.code.python_executor.captured_print` (the sandbox builtin handed to user code). Everything else goes through `logger = get_logger(__name__)`. The supervisor prefixes every aggregated line with `[HH:MM:SS.fff]` so no inner `TimeStamper` is needed; structlog console mode is deliberately timestamp-less. Test `server/tests/test_no_raw_prints.py` AST-walks the tree and flags any unsanctioned `print(...)` call.- **`configure_logging(settings)` must run BEFORE plugin self-registration imports**: in `main.py`, `Settings()` + `configure_logging(settings)` + `init_tracing()` + `get_logger(__name__)` happen ahead of `from core.container import container` and `from routers import …`. Otherwise plugin folders that register on import call `logger.debug(...)` while structlog is still on its default processor chain (which includes `TimeStamper` + no `filter_by_level`) — symptom is double timestamps + debug records leaking despite `LOG_LEVEL=INFO`.- **Plugin-identifier shape validator (`services/plugin/identifiers.py`)** (`7700f87`): `NODE_TYPE_PATTERN = r"^[A-Za-z_][A-Za-z0-9_]*$"` + `is_valid_node_type(value)`. Single source of truth used by FastAPI URL routes (`Path(pattern=NODE_TYPE_PATTERN)` in `routers/schemas.py`) AND internal helpers (`nodes/_visuals.py::get_plugin_meta` / `get_plugin_icon_path`). Hardens the icon-resolution endpoints: the registry lookup `get_node_class(node_type)` already gates the taint in practice, but CodeQL can't follow registry-mediated sanitization, so `fullmatch` at the function boundary states the constraint explicitly. **It does NOT close the CodeQL `py/path-injection` alerts, despite what this line used to claim.** Verified against the live SARIF (2026-07-26): `_visuals.py:217`, `_visuals.py:239` and `schemas.py:144` are still reported on every scan and were closed by *manual dismissal*, not by the regex. The reason is structural and worth knowing before you attempt a fix: the flagged sink is the path-construction/`resolve()` call itself, so no guard placed after it can clear the taint, and an interprocedural `fullmatch` in a helper is not treated as a barrier either. **`py/path-injection` on a containment helper is dismissed here, not coded around** — see `nodes/filesystem/_backend.py::resolve_within` and alerts #29-33, #39, #140, #142, #154-157. Contract test (`tests/services/test_identifiers.py`, 47 cases) locks the regex against `../etc/passwd`, `..\windows\system32`, `foo\x00bar`, `%2e%2e%2fetc`, `foo;bar`, `${HOME}`, `` foo`bar ``, CRLF, and non-string input.@@ -2779,7 +2784,7 @@ This function:- **Deployment reconcile snapshot on WS connect** (de8df87): a stale FE `deploymentStatus.isRunning=true` used to survive a backend restart because the in-memory `DeploymentManager._deployments` dict was wiped (no recovery wiring — the `RecoverySweeper.set_recovery_callback` extension point exists but is intentionally unwired; see the "workflow status not properly recognized" investigation). The Start button therefore stayed showing "Stop" forever. Fix: new `WorkflowEvent.deployment_snapshot(running_workflow_ids)` typed factory (`source = opencompany://services/workflow`, `type = workflow.deployment.snapshot`) + `broadcaster._send_deployment_snapshot(websocket)` that runs at the tail of `broadcaster.connect()` (single-target, NOT fan-out — only the just-connecting client needs to reconcile). FE `case 'deployment_snapshot'` in `WebSocketContext.tsx` iterates `useAppStore.workflowUIStates` and clears `isExecuting=true` on any workflow NOT in the snapshot's running set (empty list is meaningful — this is the load-bearing reset). Also reconciles `deploymentStatus.isRunning` for the active workflow. Distinct from `workflow_lifecycle("deployment.started")` (state-transition edge event) — the snapshot is an idempotent state dump tied to client connect, not a transition.- **Agent progress badge — defensive status invariant** (15b8d9d): `AIAgentNode`'s "N / max" iteration badge is gated on `isExecuting && typeof iteration === 'number' && typeof maxIterations === 'number'` where `isExecuting = nodeStatus?.status === 'executing'`. The `agent_progress` handler USED to only set `data.iteration` / `data.max_iterations`, relying on a prior `node_status='executing'` broadcast to have already stamped the status. If agent_progress arrived first (race, single-step agent completion, out-of-order Temporal activity delivery), `status` stayed undefined and the badge was hidden even though the iteration data was populated. Fix: the agent_progress handler now defensively sets `status='executing'` on the slot — but preserves `'success'` / `'error'` if a later terminal broadcast already flipped the slot (terminal states win over the resurrection).- **Temporal Worker tuner exclusivity** (Wave 16.4, 190c896): `Worker.__init__` rejects `tuner` alongside ANY of `max_concurrent_workflow_tasks` / `max_concurrent_activities` / `max_concurrent_local_activities` / `max_concurrent_nexus_tasks` — the tuner OWNS every slot supplier via its `WorkerTuner.create_composite(workflow_supplier, activity_supplier, local_activity_supplier, nexus_supplier)` and cannot coexist with the individual max-count kwargs. In `TemporalWorkerPool.start`, ALL FOUR max-count kwargs must be pulled from the base `worker_kwargs` when `tuner=` is added; the ai-heavy / browser queues use the tuner and preserve their 10-workflow-slot ceiling via `_tuner_for -> FixedSizeSlotSupplier(10)` on the workflow_supplier slot. The framework worker at `worker.py:282` does NOT use a tuner, so it keeps the plain `max_concurrent_workflow_tasks=10` + `max_concurrent_activities=self.pool_size` kwargs directly. `TEMPORAL_WORKER_POOL_ENABLED` defaulted to True in the same commit (`test_task_queue_coverage.py::TestWorkerPoolDefaultOn` locks the default via source-introspection so the flip survives a hasty revert).-- **No hardcoded port numbers in code or docs**: `.env.template` is the single place port numbers live (`.env` overrides, process env wins). Python resolves via `core.env_defaults.env_value/env_int` (raises loudly when unconfigured — never a numeric fallback literal); the Vite config and the Node executor sidecar require their env vars the same way; scripts/CI/installers parse the template. Docs reference env var names (`PYTHON_BACKEND_PORT`, `TEMPORAL_UI_PORT`, ...) instead of numerals; user-facing quickstarts may show the default app URL once. See `docs-internal/cli_services_integration.md` for the plugin-daemon recipe.+- **No hardcoded port numbers in code or docs**: `.env.template` is the single place port numbers live (`.env` overrides, process env wins). Python resolves via `core.env_defaults.env_value/env_int` (raises loudly when unconfigured — never a numeric fallback literal); the Vite config and the bun-hosted JS executor sidecar require their env vars the same way; scripts/CI/installers parse the template. Docs reference env var names (`PYTHON_BACKEND_PORT`, `TEMPORAL_UI_PORT`, ...) instead of numerals; user-facing quickstarts may show the default app URL once. See `docs-internal/cli_services_integration.md` for the plugin-daemon recipe.- **Multi-vendor nodes: one node, a `provider` dropdown, two registries.** `nodes/speech/` is the reference and the first multi-credential plugin in the repo (`credentials = (A, B, C)`; `ctx.connection(id)` is a dict lookup over that tuple). Four load-bearing rules. (1) **Imperative `@Operation` only** — the declarative `routing=` path resolves `credentials[0]` (`base.py:769`), so a routed op authenticates every provider with the first key in the tuple and `test_plugin_contract.py` would not catch it. (2) **Registry membership IS the capability** — one registry per direction, the node's provider enum literally *is* `tts_providers()`, so a synthesis-only vendor cannot be selected for transcription and there is no `supports_x` flag to keep honest. (3) **Capabilities live in JSON** (`server/config/speech_defaults.json`), per-model overrides resolved exact -> longest-prefix -> `_default`, boolean flags defaulting **permissive**; no shared code branches on a vendor name. (4) **Vendor divergence stays in the vendor module** — auth scheme, query-vs-body, response shape. The v1 set diverges on all three axes and three of those divergences fail *silently* (ElevenLabs ignores a body-placed `output_format`, Deepgram ignores body options entirely, Sarvam returns a base64 array), so each has a test asserting the outgoing request rather than the parsed result. Full reference: **[Speech Provider RFC](./docs-internal/speech_provider_rfc.md)** + [plugin_system.md -> Multi-credential nodes](./docs-internal/plugin_system.md#multi-credential-nodes).- **Never name a Params field `model` or `api_key` on a node that also has a `provider` field.** An effect at [`ParameterRenderer.tsx:893`](./client/src/components/ParameterRenderer.tsx#L893) keys on those two literal names: with a sibling `provider` field present it overwrites `model` with the *chat-model* list and clears `api_key` — and it never validates that the provider is an LLM provider, so `provider: "elevenlabs"` still triggers it and the field is wiped the moment the user picks a vendor. L982 / L1198 also write options onto the literal string `'model'`, not `parameter.name`. Prefix instead (`tts_model` / `stt_model`), locked by a test in `tests/nodes/test_speech.py`. Other reserved sibling names with name-based magic in that file: `parameters`, `message_type`, `group_id`, `group_name`, `channel_jid`, `sender_number`, `sender_name`, `session_id`, `service_id`, `action`.- **`usable_as_tool = True` auto-hides both canvas handles.** `base.py:243` (inside `__init_subclass__`) sets `hide_input_handle` / `hide_output_handle` to `True` unless the class declares them, so a dual-purpose node that must stay wirable has to declare both `False` explicitly. Symptom: the node works fine as an AI tool but cannot be connected to anything on the canvas.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 94a610ad..dabd3be1 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -57,7 +57,7 @@ Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [nati| `server/config/` | llm_defaults.json, pricing.json, model_registry.json, email_providers.json, google_apis.json, credential_providers.json, ai_cli_providers.json, node_allowlist.json | [pricing_service.md](docs-internal/pricing_service.md), [node_allowlist.md](docs-internal/node_allowlist.md) || `server/tests/` | Contract-test invariants + per-category node tests + `NodeTestHarness` | [tests/nodes/_harness.py](server/tests/nodes/_harness.py), [tests/credentials/README.md](server/tests/credentials/README.md) || `client/src/` (styling + themes) | Tailwind tokens, shadcn primitives, the 12-theme contract | [frontend_architecture.md](docs-internal/frontend_architecture.md), [theme_system.md](docs-internal/theme_system.md) |-| `desktop/` | Electron desktop shell — a standalone bun package (not a root workspace member) that bundles uv + Python + Node, provisions the backend venv on first launch and hosts the backend-served SPA in a native window | [desktop_app.md](docs-internal/desktop_app.md), [desktop_host_contract.md](docs-internal/desktop_host_contract.md) |+| `desktop/` | Electron desktop shell — a standalone bun package (not a root workspace member) that bundles uv + Python + bun (no Node, no npm), provisions the backend venv on first launch and hosts the backend-served SPA in a native window | [desktop_app.md](docs-internal/desktop_app.md), [desktop_host_contract.md](docs-internal/desktop_host_contract.md) || `docs-internal/` | In-repo architecture deep dives (50+ files) | Index below |## How to Contribute Features@@ -127,7 +127,7 @@ The diagram above shows the full lifecycle of a workflow node: one self-containe## Local Dev Quick Reference-Development from source uses **bun** (not npm). The `scripts/preinstall.js` hook enforces this when `bunfig.toml` is present (it keys on the file plus a `bun` user agent; end-user npm tarball installs are unaffected because `bunfig.toml` is not shipped in the package). Install bun once from https://bun.sh — Windows: `powershell -c "irm bun.sh/install.ps1 | iex"`; macOS/Linux: `curl -fsSL https://bun.sh/install | bash`.+Development from source uses **bun** (not npm) — the same bun that end users install with (`bun add -g @zeenie-ai/opencompany`) and that everything shipped runs on. The `scripts/preinstall.js` hook enforces this when `bunfig.toml` is present (it keys on the file plus a `bun` user agent; end-user `bun add -g` installs never trigger it — a global add runs no lifecycle scripts, and `bunfig.toml` is not shipped in the tarball anyway). Install bun once from https://bun.sh — Windows: `powershell -c "irm bun.sh/install.ps1 | iex"`; macOS/Linux: `curl -fsSL https://bun.sh/install | bash`.```bashbun install # install workspace dependencies@@ -147,7 +147,7 @@ The desktop shell has its own package: `cd desktop && bun install && bun run sta- **No strict-peer-dependencies equivalent.** bun never errors on peer conflicts, so the check that kept client `typescript` inside typescript-eslint's peer range is gone from install time — the CLI test locking client `typescript` to `^5` (`cli/tests/test_release_pipeline_config.py`) is now the only guard.- **Dependabot's `bun` ecosystem does version updates only — no security-update PRs.** Alerts still fire; remediation goes through the top-level `overrides` block in the root `package.json` (the pins formerly under `pnpm.overrides`).-- **`--bun` is not enabled anywhere.** Node (18+; CI builds on 22) remains the runtime for vite/vitest/eslint/the sidecar. A trial of `--bun` for `vite dev` only is a documented follow-up once the package-manager migration proves stable — never for vitest/eslint (known bun-runtime breakage: oven-sh/bun#20762, #13346).+- **`--bun` is not enabled anywhere — but Node is dev/CI-only now.** Everything shipped runs on bun: the `company` shim (`bin/cli.js`, `#!/usr/bin/env bun`), the JS executor sidecar (`bun build --target=bun` bundle), the plugin CLIs `bun add`ed into `~/.opencompany/packages/` (`server/core/js_runtime.py`) and the end-user install itself. Node (CI installs 22) is kept only so bun can run vite / vitest / eslint / playwright / electron-builder on it via their node shebangs when it is present — vitest and eslint have open bugs on the bun runtime (oven-sh/bun#20762, #13346) — and `company build` reports Node as optional (bun runs the build tools itself when it is absent). A trial of `--bun` for `vite dev` only remains a documented follow-up; never for vitest/eslint.Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.md](docs-internal/SCRIPTS.md)@@ -199,7 +199,7 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.| [authentication.md](docs-internal/authentication.md) | JWT/cookie auth — modes, middleware, frontend bootstrap || [errors.md](docs-internal/errors.md) | Known errors and troubleshooting || [performance.md](docs-internal/performance.md) | Cold-start measurements, optimisation history, anti-patterns |-| [release_build_pipeline.md](docs-internal/release_build_pipeline.md) | npm-distribution build pipeline (TypeScript 7 native-Go type-check, esbuild sidecar, bytecode) |+| [release_build_pipeline.md](docs-internal/release_build_pipeline.md) | Registry-tarball build pipeline (TypeScript 7 native-Go type-check, `bun build` sidecar, bytecode; bun is the only shipped JS runtime) || [Skill Creation Guide](server/skills/GUIDE.md) | How to create new skills |## Communitydiff --git a/README.md b/README.mdindex dece64c4..130c5f86 100644--- a/README.md+++ b/README.md@@ -19,16 +19,18 @@ Bring your own API keys, or run models locally for free. No subscription. No usa## Quick Start-**Prerequisites:** Node.js 18+, Python 3.12+**Prerequisites:** [bun](https://bun.sh) 1.4+, Python 3.12 (no Node.js, no npm)```bash-npm install -g @zeenie-ai/opencompany+bun add -g @zeenie-ai/opencompanycompany start```+The first `company` command sets up the Python side (uv, the virtual environments; a minute or two), or run `company provision` to do that up front. The installer scripts do all of it for you, bun included: `curl -fsSL https://opencompany.sh/install.sh | bash` on macOS/Linux, `iwr -useb https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/install.ps1 | iex` on Windows.+Open http://localhost:5678 (default `PYTHON_BACKEND_PORT`), click the key icon in the toolbar, and connect your first AI provider. Three example employees are already on the canvas; open one to see how it is put together.-**Prefer a desktop app?** Installers for Windows (`.exe`), macOS (`.dmg`, Apple Silicon and Intel) and Linux (`.AppImage` / `.deb`) are attached to every [GitHub Release](https://github.com/zeenie-ai/OpenCompany/releases). They need no Python or Node on the machine: the app bundles them, sets up the backend on first launch (one-time download, a minute or two), and shares its data with a CLI install in `~/.opencompany`. The first releases are unsigned, so macOS asks you to allow the app under System Settings > Privacy & Security and Windows SmartScreen needs "More info > Run anyway". Details in [docs-internal/desktop_app.md](docs-internal/desktop_app.md).+**Prefer a desktop app?** Installers for Windows (`.exe`), macOS (`.dmg`, Apple Silicon and Intel) and Linux (`.AppImage` / `.deb`) are attached to every [GitHub Release](https://github.com/zeenie-ai/OpenCompany/releases). They need no Python, bun or Node on the machine: the app bundles uv, Python and bun, sets up the backend on first launch (one-time download, a minute or two), and shares its data with a CLI install in `~/.opencompany`. The first releases are unsigned, so macOS asks you to allow the app under System Settings > Privacy & Security and Windows SmartScreen needs "More info > Run anyway". Details in [docs-internal/desktop_app.md](docs-internal/desktop_app.md).<details><summary><b>Run from source (for contributors)</b></summary>@@ -36,7 +38,7 @@ Open http://localhost:5678 (default `PYTHON_BACKEND_PORT`), click the key icon i```bashgit clone https://github.com/zeenie-ai/OpenCompany.git OpenCompanycd OpenCompany-npm install -g bun+# bun once, from https://bun.sh: `curl -fsSL https://bun.sh/install | bash` (or `irm bun.sh/install.ps1 | iex` on Windows)bun run buildbun run dev```diff --git a/cli/terraform/aws/README.md b/cli/terraform/aws/README.mdindex 946081b7..f61a309b 100644--- a/cli/terraform/aws/README.md+++ b/cli/terraform/aws/README.md@@ -14,7 +14,7 @@ Settings are the ones validated on a live t3.micro in September 2026:| Credit mode | `standard` | Caps compute at the hourly rate under continuous CPU load. || Root disk | 10 GiB gp3, deleted with the instance | A fresh install uses ~4.5 GiB. || Image | Ubuntu 24.04 LTS (Canonical) | Python 3.12 inside the server's `<3.13` pin. |-| Node | current LTS from NodeSource when none is present; an existing 18+ is kept | The published package runs on Node 18+; only the Cloudflare node's `cf` CLI needs 22+. |+| bun | installed by `install.sh` (the official bun installer, into `~ubuntu/.bun`) when none is present; no Node, no npm | The published package runs on bun: the `company` shim, the JS executor sidecar and the plugin CLIs (including the Cloudflare `cf` CLI, whose `engines.node >= 22` bun ignores). systemd gets `$APP_HOME/.bun/bin` on PATH and `ExecStart=$APP_HOME/.bun/bin/company serve`. || Install | `install.sh` as `ubuntu`, no sudo | Root installs leave the venvs unusable by the login user (errors.md #16). || Runtime | `company serve` under systemd as `ubuntu` on port 5678 | The server rejects ports below 1024; 80/443 stay free for a TLS front door. || Security group | 22, 80, 443 and the app port from `allow_cidr` | Same shape as the gcp module. |diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.mdindex d83fc628..b172866e 100644--- a/docs-internal/SCRIPTS.md+++ b/docs-internal/SCRIPTS.md@@ -3,10 +3,18 @@## Quick Start```bash-npm install -g @zeenie-ai/opencompany+bun add -g @zeenie-ai/opencompanycompany start```+bun (https://bun.sh) is the only JavaScript runtime and package manager+involved — no Node.js, no npm. `bun add -g` runs no lifecycle scripts, so the+first `company` command provisions the Python side (`bin/cli.js` runs+`scripts/install.js` when `.cli-venv` is missing); `install.sh` / `install.ps1`+install bun, Python and uv first and run `company provision` eagerly. Nothing+spells bun's global package directory (it varies by platform and+configuration): the shim knows its own package root.+Open the app URL — `http://localhost:${PYTHON_BACKEND_PORT}` (the portis declared once in `.env.template`; see [SETUP.md](./SETUP.md) for thedefault).@@ -24,7 +32,7 @@ deprecation warning; kept for upgrade compatibility).|---------|-------------|| `company start` | Production mode, single port: uvicorn serves API + WS + built SPA on `PYTHON_BACKEND_PORT`. Optional daemons (Temporal dev server, WhatsApp) are backend-owned, started from the lifespan when enabled || `company dev` | Start in dev mode (Vite HMR + uvicorn). `--force` re-bundles Vite deps (recovers "Outdated Optimize Dep"); `--daemon` binds backend to 0.0.0.0 |-| `company serve` | Single-port production runtime (uvicorn serves API + WS + built SPA; optional daemons incl. the Node.js executor are backend-spawned on demand) — the systemd `ExecStart` on deployed VMs |+| `company serve` | Single-port production runtime (uvicorn serves API + WS + built SPA; optional daemons incl. the JS executor sidecar (bun) are backend-spawned on demand) — the systemd `ExecStart` on deployed VMs || `company stop` | Stop all services and free configured ports || `company build` | Full production build (bun install → client → sidecar → uv sync → bytecode → temporal binary). Step [0/6] scaffolds `.env` from `.env.template` when missing, generating fresh random secrets (`secrets.token_hex(24)`) for `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` instead of the dev placeholders; an existing `.env` is untouched || `company clean` | Stop services, then remove build artifacts, node_modules, `.venv`, repo-local state (preserves `.opencompany/{workflows,deploy,packages}`) |@@ -42,8 +50,8 @@ The Electron shell is its own bun package with its own lockfile; root `bun run`| Command | Description ||---------|-------------|-| `bun run stage` | Assemble `stage/`: the backend sibling layout from `npm pack --dry-run` (CLI, install scripts, client sources and backend tests dropped; `server/uv.lock` force-included; Node sidecar re-bundled with express inlined) plus the pinned runtimes for this host. `--target mac-arm64,mac-x64` stages other targets; `--skip-runtimes` stages app-root only |-| `bun run fetch-runtimes` | Just the runtimes: download uv / python-build-standalone / Node pinned in `runtimes.json`, verify against the upstream checksum manifests, cache in `vendor/`, extract into `stage/runtime/<os>-<arch>/` |+| `bun run stage` | Assemble `stage/`: the backend sibling layout from `bun pm pack --dry-run` (CLI, install scripts, client sources and backend tests dropped; `server/uv.lock` force-included; the JS executor sidecar built with its package's own `bun run build` — `bun build --target=bun`, express inlined — and `dist/index.js` copied) plus the pinned runtimes for this host. `--target mac-arm64,mac-x64` stages other targets; `--skip-runtimes` stages app-root only |+| `bun run fetch-runtimes` | Just the runtimes: download uv / python-build-standalone / bun pinned in `runtimes.json`, verify against the upstream checksum manifests (bun's `SHASUMS256.txt`; its `LICENSE.md` is fetched from the bun repo since the zip carries none), cache in `vendor/`, prune stale runtime dirs (a leftover `node/`), extract into `stage/runtime/<os>-<arch>/` || `bun run dev` | electron-vite dev against `stage/` (`OPENCOMPANY_DESKTOP_APP_ROOT=..` and `OPENCOMPANY_DESKTOP_VENV_PYTHON=../server/.venv/...` run against the checkout without staging or provisioning) || `bun run build` | electron-vite build of main / preload / setup renderer into `out/` || `bun run typecheck` / `bun run test` / `bun run test:invariants` / `bun run test:e2e` | TS7 gate; vitest unit tests; staged-tree invariants (after `stage`); Playwright Electron smoke (after `build`) |@@ -53,10 +61,11 @@ The Electron shell is its own bun package with its own lockfile; root `bun run`### Dependency checks-`build` requires Node.js (the runtime under vite/esbuild; no version floor beyond-the package's 18+) and bun (installs the workspace and runs every JS build step),-reports npm as informational only (runtime plugins use it, the build does not),-verifies Python 3.12+ (`_check_python`), and installs `uv` via pip if missing. `start` runs+`build` requires bun (installs the workspace and runs every JS build step — a+missing bun is fatal) and reports Node.js as optional (when present, bun runs+vite / vitest / eslint on it via their node shebangs; when absent, bun runs the+build tools itself — nothing shipped needs Node), verifies Python 3.12++(`_check_python`), and installs `uv` via pip if missing. `start` runsno toolchain check, only the `_sqlalchemy_preflight` venv-health probe.---@@ -69,7 +78,8 @@ the source of truth). The dev package manager is [email protected] —The commands below are quoted verbatim from `package.json`. No scripthops through `npm run` any more: cross-package scripts use`bun --cwd=<dir> run <script>` (the `=` form is mandatory on bun 1.4),-and the tools they reach (vite, vitest) still execute on Node.+and the tools they reach (vite, vitest) execute on Node when it is present+(dev/CI only — their bins carry node shebangs, which bun respects).### CLI wrappers@@ -81,6 +91,12 @@ and the tools they reach (vite, vitest) still execute on Node.| `version:sync` | `python -m cli version sync` || `docs:nodes` / `docs:nodes:check` | `python -m cli docs nodes [--check]` |+Two `company` verbs live in the launcher itself (`bin/cli.js`) with no+`python -m cli` counterpart: `company doctor` (environment report) and+`company provision [--force]` (the Python-side setup of a global install —+uv, the venvs, bytecode, the Temporal binary; automatic on the first+`company` command, explicit here for the installers and for repairs).+### Service scripts| Script | Command | Description |@@ -106,7 +122,7 @@ The Temporal dev server is backend-owned: the FastAPI lifespan starts it via `Te| Script | File | Purpose ||--------|------|---------|| `preinstall` / `preuninstall` | `scripts/preinstall.js` | Removes the legacy `machinaos` global package / stale temp dirs before (un)install |-| `postinstall` | `scripts/postinstall.js` | End-user install pipeline for the npm tarball (delegates to `scripts/install.js`) |+| `postinstall` | `scripts/postinstall.js` | Install pipeline entry (delegates to `scripts/install.js`). Reached from `bun install` in a checkout; a global `bun add -g` runs no dependency lifecycle scripts, so `bin/cli.js` provisions on the first `company` command instead |---@@ -114,9 +130,9 @@ The Temporal dev server is backend-owned: the FastAPI lifespan starts it via `Te| File | Purpose ||------|---------|-| `install.js` | npm-tarball install pipeline (npm/uv install for end users — dev workspaces use bun; client build only when `client/dist` is missing from the tarball, `uv sync`, bytecode compile, CLI runtime venv, non-fatal Temporal binary fetch; the Node.js sidecar `dist/index.js` ships pre-built in the tarball) — mirrors `company build`; the compileall command shape is locked in sync by `cli/tests/test_release_pipeline_config.py` |-| `preinstall.js` | Legacy-package/temp cleanup (also runs on uninstall) |-| `postinstall.js` | npm lifecycle entry that guards recursion and invokes install.js |+| `install.js` | End-user provisioning pipeline (`#!/usr/bin/env bun`; run by `company provision` — eagerly from `install.sh` / `install.ps1` / the cloud-init templates, or lazily by `bin/cli.js` on the first `company` command when `.cli-venv` is missing and the tree is not a source checkout; client build only when `client/dist` is missing from the tarball, `uv sync`, bytecode compile, CLI runtime venv, non-fatal Temporal binary fetch; the JS executor sidecar `dist/index.js` ships pre-built in the tarball) — mirrors `company build`; the compileall command shape is locked in sync by `cli/tests/test_release_pipeline_config.py` |+| `preinstall.js` | Gates source checkouts to bun; legacy-package/temp cleanup (also runs on uninstall) |+| `postinstall.js` | Lifecycle entry (`bun install` in a checkout) that guards recursion and invokes install.js || `migrate_icons.py`, `migrate_skill_icons.py` | One-off icon-migration utilities (historical) |(`serve-client.js` was retired July 2026: `company start` is single-port —@@ -139,7 +155,7 @@ Key variables in `.env` (see `.env.template` for the full list):| `VITE_CLIENT_PORT` | `.env.template` | App port (Vite dev server; proxies backend prefixes). Equal to `PYTHON_BACKEND_PORT` in production || `PYTHON_BACKEND_PORT` | `.env.template` | Backend port (`.env.dev` moves it one up in dev, behind the Vite proxy) || `WHATSAPP_RPC_PORT` | `.env.template` | WhatsApp API port (plugin-owned) |-| `NODEJS_EXECUTOR_PORT` | `.env.template` | Node.js code-executor sidecar (plugin-owned) |+| `NODEJS_EXECUTOR_PORT` | `.env.template` | JS code-executor sidecar, runs on bun (plugin-owned; the env var name is unchanged) || `TEMPORAL_FRONTEND_GRPC_PORT` / `TEMPORAL_UI_PORT` | `.env.template` | Temporal gRPC / Temporal Web UI |All values live in the serial block declared at the top of `.env.template`; no@@ -157,10 +173,10 @@ code or doc should carry the numerals.| Dependency | Version | Install ||------------|---------|---------|-| Node.js | 18+ (22 LTS recommended; CI and the desktop bundle use 22; only the Cloudflare node's `cf` CLI needs 22+) | https://nodejs.org/ |+| bun | 1.4+ — the only JavaScript runtime and package manager anything shipped needs: it runs the `company` shim, the JS executor sidecar and the plugin CLIs (incl. the Cloudflare `cf` CLI, whose `engines.node >= 22` bun ignores) and installs the package (`bun add -g`) | official installer (https://bun.sh; `install.sh` / `install.ps1` run it); root `packageManager` pin read by `oven-sh/setup-bun` in CI; the desktop app bundles it || Python | 3.12+ (CLI); server venv accepts 3.11–3.12 | https://python.org/ || uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |-| bun | 1.4.x | official installer (https://bun.sh); root `packageManager` pin read by `oven-sh/setup-bun` in CI |+| Node.js | optional, dev/CI only — when present, bun runs vite / vitest / eslint on it via their node shebangs (CI installs 22 for that reason); `company build` reports it as optional | https://nodejs.org/ |---diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.mdindex 086f90af..51527185 100644--- a/docs-internal/SETUP.md+++ b/docs-internal/SETUP.md@@ -13,19 +13,25 @@ OpenCompany/│ ├── core/ # DI container, database, cache│ ├── models/ # SQLModel definitions│ ├── nodes/ # Plugin folders (one per node; the WhatsApp bridge is the-│ │ # `edgymeow` npm package installed under DATA_DIR/packages/, not in-tree)+│ │ # `edgymeow` package `bun add`ed under DATA_DIR/packages/, not in-tree)│ └── requirements.txt-├── scripts/ # npm-tarball install lifecycle helpers (install/preinstall/postinstall)+├── scripts/ # Install lifecycle helpers, run by bun (install/preinstall/postinstall)└── package.json # Workspace root; [email protected] scripts wrapping `python -m cli````## Quick Start```bash-npm install -g @zeenie-ai/opencompany+bun add -g @zeenie-ai/opencompanycompany start```+bun (https://bun.sh, 1.4+) and Python 3.12 are the only prerequisites — no+Node.js, no npm. `bun add -g` runs no lifecycle scripts, so the first `company`+command provisions the Python side (uv, the venvs, bytecode; a minute or two).+`curl -fsSL https://opencompany.sh/install.sh | bash` (or `install.ps1` on+Windows) installs bun, Python and uv first and provisions eagerly.+Open `http://localhost:$PYTHON_BACKEND_PORT` — `company start` is single-port (API +WebSocket + built SPA on the backend port).@@ -34,19 +40,24 @@ Notes for Linux servers:- **Memory**: plan on at least 1 GB of RAM. The backend plus the Temporal devserver it spawns idle at about 350 MB; a 512 MB VM is OOM-killed in a loop(see [errors.md #17](./errors.md#17-backend-oom-killed-in-a-loop-on-small-vms-512-mb)).-- **uv** is installed by the postinstall: via pip where allowed, otherwise via- uv's official installer (PEP 668 distros such as Ubuntu 24.04, see+- **uv** is installed by the provisioning step (`scripts/install.js`, run by+ `company provision` on the first `company` command or eagerly by+ `install.sh`): via pip where allowed,+ otherwise via uv's official installer (PEP 668 distros such as Ubuntu 24.04, see[errors.md #15](./errors.md#15-npm-install--g-fails-with-externally-managed-environment-ubuntu-2404)).-- **No `sudo`**: install with a user-writable npm prefix- (`npm config set prefix ~/.npm-global`, add `~/.npm-global/bin` to `PATH`)- so the venvs, the uv-managed Python and `~/.opencompany` all belong to the- login user. A `sudo npm install -g` leaves the venvs pointing into `/root`- and `company start` fails with `python: not found` (see- [errors.md #16](./errors.md#16-company-start-says-python-not-found-after-a-sudo-npm-install--g)).+- **No `sudo`**: `bun add -g` installs as the login user (shim+ `~/.bun/bin/company`; the package itself lands wherever bun keeps its+ global packages, which nothing needs to know because `company provision`+ runs from the shim's own root), so the venvs, the uv-managed Python and+ `~/.opencompany` all belong to the login user with no prefix to configure.+ The root-owned-venv failure of the npm era (see+ [errors.md #16](./errors.md#16-company-start-says-python-not-found-after-a-sudo-npm-install--g))+ cannot recur; `install.sh` evicts a legacy `npm install -g` copy when npm+ happens to be present.### Local Development (from source)-**Prerequisites:** Node.js 18+ (22 recommended; CI builds on 22), Python 3.12 (CLI needs >=3.12, server venv pins >=3.11,<3.13), uv, bun 1.4+ (https://bun.sh)+**Prerequisites:** bun 1.4+ (https://bun.sh — the package manager and the only JavaScript runtime anything shipped needs), Python 3.12 (CLI needs >=3.12, server venv pins >=3.11,<3.13), uv. Node.js is optional: when present, bun runs vite / vitest / eslint on it via their node shebangs (CI installs 22 for that reason); `company build` treats it as optional.```bashgit clone https://github.com/zeenie-ai/OpenCompany.git OpenCompany@@ -74,8 +85,9 @@ Services (production `company start`; every port is declared once in `.env.templ### Desktop app (Electron shell)-End users can skip Python and Node entirely: the installers attached to each-GitHub Release bundle `uv`, a standalone CPython 3.12 and Node 22, provision+End users can skip Python, bun and Node entirely: the installers attached to each+GitHub Release bundle `uv`, a standalone CPython 3.12 and bun 1.4 (the only JS+runtime the backend needs — no Node, no npm), provisionthe backend's virtual environment into the app's data directory on firstlaunch (one-time download of the Python wheels, plus the Temporal binary theCLI also downloads), and host the same backend-served UI in a native window.diff --git a/docs-internal/browser_harness.md b/docs-internal/browser_harness.mdindex 016f99fa..e08d5347 100644--- a/docs-internal/browser_harness.md+++ b/docs-internal/browser_harness.md@@ -35,7 +35,7 @@ The node's `doctor` operation runs `browser-harness doctor` and returns the full| | `browser` (agent-browser) | `browserHarness` ||---|---|---|-| Engine | npm CLI + bundled Chrome-for-Testing (or system browser) | user's real Chrome over raw CDP |+| Engine | npm-registry CLI (`agent-browser`, `bun add`ed into the shared packages tree and run on bun) + bundled Chrome-for-Testing (or system browser) | user's real Chrome over raw CDP || Interaction | accessibility tree, `@eN` refs | screenshots + coordinate clicks + `js()` || Sessions | named sessions, instance cap, idle timeout | one shared browser (daemon-held CDP socket) || Agent surface | 15 structured operations | freeform Python against helpers |diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.mdindex b48aecac..511df529 100644--- a/docs-internal/ci_cd.md+++ b/docs-internal/ci_cd.md@@ -41,7 +41,7 @@ The repo currently ships **three workflows** plus one composite action. A number| Release | `.github/workflows/release.yml` | `v*.*.*` tag, `workflow_dispatch` | predeploy gate → publish (npm + GitHub Packages) || Desktop CI | `.github/workflows/desktop-ci.yml` | PR touching `desktop/**` or the backend host-contract files; push to main touching `desktop/**` | typecheck + unit + staged-tree invariants + `electron-vite build` + Playwright Electron smoke on ubuntu-22.04 (xvfb) and windows-latest || Desktop release | `.github/workflows/desktop-release.yml` | `v*.*.*` tag, `workflow_dispatch` | 3-runner matrix (windows-latest x64, macos-14 arm64+x64, ubuntu-22.04 x64) builds installers with electron-builder into one **draft** GitHub Release; `finalize` undrafts once every leg is green. Artifacts-only on dispatch unless `publish` is ticked |-| Setup | `.github/actions/setup/action.yml` | (composite) | bun 1.4 + Node 22 + Python 3.12 + uv v8 + editable CLI install |+| Setup | `.github/actions/setup/action.yml` | (composite) | bun 1.4 + Node 22 (CI-only: bun runs vite / vitest / eslint on it) + Python 3.12 + uv v8 + editable CLI install |### Toolchain pin@@ -72,7 +72,7 @@ Desktop code signing is deliberately absent for the first releases: `CSC_IDENTIT| Tool | Version source | Action ||------|---------------|--------|| bun | `oven-sh/setup-bun` v2.2.0 — reads the root `packageManager` pin (`[email protected]`) | Immutable commit SHA |-| Node.js | `node-version` input, default `22` | `actions/setup-node` v6.5.0, immutable commit SHA; package cache disabled |+| Node.js | `node-version` input, default `22` — a CI-only convenience: bun runs vite / vitest / eslint on it via their node shebangs (open bun-runtime bugs in vitest and eslint); nothing shipped needs Node | `actions/setup-node` v6.5.0, immutable commit SHA; package cache disabled || Python | hard-coded `3.12` (matches `.python-version`) | `actions/setup-python` v5.6.0, immutable commit SHA || uv | `astral-sh/setup-uv` v8.1.0, cache disabled | Immutable commit SHA |@@ -106,7 +106,7 @@ Reusable `workflow_call` workflow with four independent jobs (no plan/change-det| Push of `v*.*.*` tag | predeploy gate, then publish to npm + GitHub Packages || `workflow_dispatch` | Same job graph (manual run; there is no dry-run switch) |-The workflow default is `contents: read`. Publishing permissions are scoped to the job that needs them: npm receives `id-token: write` for provenance, while GitHub Packages receives `packages: write`. Checkout credentials are not persisted in either publishing job.+The workflow default is `contents: read`. Publishing permissions are scoped to the job that needs them: the npmjs job needs nothing beyond `contents: read` (bun authenticates with the `NPM_TOKEN` it writes to `~/.npmrc`; npm provenance attestation, and the `id-token: write` it needed, went away with the npm CLI), while GitHub Packages receives `packages: write`. Checkout credentials are not persisted in either publishing job.### Job graph@@ -119,15 +119,15 @@ publish-npm publish-github-packages| |+- build +- build+- cli version sync +- cli version sync- +- verify npm auth +- rewrite package name+ +- write ~/.npmrc + bun pm whoami +- rewrite package name (bun -e)+- publish canonical package +- publish mirror package@zeenie-ai/opencompany @zeenie-ai/opencompany- npmjs, public + provenance npm.pkg.github.com+ npmjs, bun publish --access public npm.pkg.github.com, bun publish```-- Both publish jobs `needs: predeploy`, run on `ubuntu-latest`, and share the same prefix: immutable `actions/checkout` with `persist-credentials: false` → composite setup → immutable `actions/setup-node` (with the target `registry-url`) → `bun install --frozen-lockfile` → `bun run build` → `python -m cli version sync`.-- `publish-npm` — validates the token with `npm whoami`, then publishes the canonical public npmjs package `@zeenie-ai/opencompany` via `npm publish --access public --provenance` with `NODE_AUTH_TOKEN=secrets.NPM_TOKEN`. The `--provenance` flag emits an npm provenance attestation (backed by the workflow's `id-token: write`).-- `publish-github-packages` — rewrites `package.json` `name` to `@zeenie-ai/opencompany` and sets `publishConfig.registry = https://npm.pkg.github.com`, then `npm publish` with `NODE_AUTH_TOKEN=secrets.GITHUB_TOKEN`.+- Both publish jobs `needs: predeploy`, run on `ubuntu-latest`, and share the same prefix: immutable `actions/checkout` with `persist-credentials: false` → composite setup → `bun install --frozen-lockfile` → `bun run build` → `python -m cli version sync`. There is no `setup-node` step and no npm CLI anywhere in the release: bun packs, authenticates and publishes.+- `publish-npm` — writes `//registry.npmjs.org/:_authToken=<NPM_TOKEN>` to `~/.npmrc`, validates it with `bun pm whoami`, then publishes the canonical public npmjs package `@zeenie-ai/opencompany` via `bun publish --access public`. npm provenance attestation was an npm-CLI feature and is gone with it.+- `publish-github-packages` — rewrites `package.json` `name` to `@zeenie-ai/opencompany` and sets `publishConfig.registry = https://npm.pkg.github.com` (a `bun -e` one-liner), writes the `//npm.pkg.github.com/:_authToken=<GITHUB_TOKEN>` line to `~/.npmrc`, then `bun publish`.Both registries use `@zeenie-ai/opencompany`, matching the npm and GitHuborganization owned by the project.@@ -202,8 +202,8 @@ The following existed in earlier drafts of this doc but are **not present in the- **`predeploy.yml` change-detection + aggregator** — a `plan` job (`dorny/paths-filter`) gating downstream jobs, a `pre-commit` job, pytest sharding by domain, and a `ci-passed` aggregator (`re-actors/alls-green`) as the single branch-protection target. Today every predeploy job runs unconditionally and there is no aggregator job.- **`release.yml` hardening** — `workflow_dispatch` dry-run default, a once-per-release `build-for-publish` artifact, `actions/attest-build-provenance` SLSA attestations, and a `create-github-release` job. (An earlier draft also planned a blocking `pnpm audit`; bun has no audit-equivalent gate, so the top-level `overrides` block + Dependabot alerts are the vulnerability-remediation channel instead.)- **`publish-pypi.yml`** — reusable PyPI publish (OIDC trusted publishing, `uv build --no-sources`, `pypa/gh-action-pypi-publish`). No PyPI distribution is published today.-- **`test-install.yml`** — cross-platform end-user install smoke (npm install, git clone, install script) across 3 OS.-- **`rollback.yml`** — manual `npm deprecate` + optional revert PR.+- **`test-install.yml`** — cross-platform end-user install smoke (`bun add -g`, git clone, install script) across 3 OS.+- **`rollback.yml`** — manual registry deprecate (`npm deprecate` has no bun equivalent, so this would be the one place the npm CLI reappears) + optional revert PR.- **`codeql.yml`** — Python + JS/TS SAST (`security-extended`).- **`check-zizmor.yml`** — workflow-security linter (SARIF to the Security tab).- **`.pre-commit-config.yaml`** — ruff / prettier / eslint / actionlint hooks (note: the project rule is to verify with pytest + the root `typecheck` gate + eslint, not ruff). This file is **not currently present in the tree**; the entry describes intent, not a live hook.diff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.mdindex 80d3d4ed..ce45f7a2 100644--- a/docs-internal/cli_agent_framework.md+++ b/docs-internal/cli_agent_framework.md@@ -50,7 +50,7 @@ Reuses (do not duplicate):- `services/skill_loader.py` — `scan_skills` / `load_skill` consumed by MCP `listSkills` / `getSkill`- `services/auth.py` — `AuthService.get_api_key` consumed by MCP `getCredential`- `services/credential_registry.py` — deep-merge `extends` for `_cli_base` entry-- `nodes/agent/claude_code_agent/_oauth.py` — Claude `auth login` / `auth status` / `auth logout` wrappers, npm install into the shared OpenCompany tree at `<DATA_DIR>/packages/` (binary resolves to `<DATA_DIR>/packages/node_modules/.bin/claude[.cmd]`), `CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/`. The `login` spawn passes `stdin=PIPE` (un-written) so the native CLI's stdin reader blocks instead of EOFing — keeps its localhost OAuth callback server alive until the browser flow completes+- `nodes/agent/claude_code_agent/_oauth.py` — Claude `auth login` / `auth status` / `auth logout` wrappers, `bun add` (via `core/js_runtime.add_package`, `trust=True`) into the shared OpenCompany packages tree at `<DATA_DIR>/packages/` (binary resolves to `<DATA_DIR>/packages/node_modules/.bin/claude[.exe]` and runs on bun), `CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/`. The `login` spawn passes `stdin=PIPE` (un-written) so the native CLI's stdin reader blocks instead of EOFing — keeps its localhost OAuth callback server alive until the browser flow completes- `nodes/stripe/_handlers.py` — pattern reference for marker-token + catalogue broadcast## Provider abstraction (mirrors `services/llm/`)@@ -99,7 +99,7 @@ the interactive billing bucket (entrypoint `claude-vscode`, NOT`sdk-cli`) since `-p` / `--print` is never emitted.```-~/.opencompany/packages/node_modules/.bin/claude[.cmd]+~/.opencompany/packages/node_modules/.bin/claude[.exe] # bun's bin shim; runs on bun--output-format stream-json # events on stdout--input-format stream-json # user turns to stdin as JSON--verbose # required with stream-json for full event detail@@ -236,13 +236,13 @@ Steps:1. Run `claude auth status`. If it exits 0, write the marker + broadcast and return immediately (idempotent re-click).2. Otherwise schedule `_finalize_claude_login()` (in `nodes/agent/claude_code_agent/_handlers.py`), which calls `run_claude_login()` from `_oauth.py`:- - OpenCompany-managed install of `@anthropic-ai/claude-code` into the shared npm tree at `<DATA_DIR>/packages/` via `npm install <package_name>@<package_version> --prefix <packages_dir>` (same tree as `edgymeow` / `agent-browser`; skipped if already installed). The exact version is pinned in `server/config/ai_cli_providers.json` (`package_version`, the vercel / cloudflare idiom) because the stream-json contract and flag surface are verified against that version only. Binary resolves to `<DATA_DIR>/packages/node_modules/.bin/claude[.cmd]`.+ - OpenCompany-managed install of `@anthropic-ai/claude-code` into the shared packages tree at `<DATA_DIR>/packages/` via `core.js_runtime.add_package("<package_name>@<package_version>", trust=True)` — `bun add --cwd <packages_dir> --no-progress --trust <spec>` (same tree as `edgymeow` / `agent-browser` / `cf` / `vercel`; skipped if already installed; `--trust` because the package's postinstall stages its native launcher, which bun otherwise blocks). The exact version is pinned in `server/config/ai_cli_providers.json` (`package_version`, the vercel / cloudflare idiom) because the stream-json contract and flag surface are verified against that version only. Binary resolves to `<DATA_DIR>/packages/node_modules/.bin/claude[.exe]` and runs on bun — no Node or npm involved (claude-code 2.1.258 verified on bun with no Node on PATH).- `claude auth login` via `run_cli_command(..., env={..., CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/}, stdin=asyncio.subprocess.PIPE)` — same way the VSCode Claude Code extension delegates to the binary. Anthropic doesn't expose `--print-url` or a programmatic OAuth helper (issue [anthropics/claude-code#7100](https://github.com/anthropics/claude-code/issues/7100), closed "not planned"), so we let the CLI open the user's browser via its own OS-level call. `stdin=PIPE` is **load-bearing** for claude-code >= 2.1.162's native binary: it reads stdin while waiting for the browser callback, and an inherited (closed) stdin EOFs it into an early exit that kills the localhost callback server before the redirect arrives — `stdin=PIPE` (never written) makes the read block so the server stays up.3. Schedule a background task that polls `claude auth status` every 2s up to 600s. On exit-0, write the synthetic `"cli-managed"` marker via `auth_service.store_oauth_tokens("claude_code", ...)` and broadcast `credential_catalogue_updated`. The catalogue's `stored` flag flips and the existing `OAuthConnect.tsx` primitive renders the modal as Connected.**Logout**: runs `claude auth logout`, drops the marker via `auth_service.remove_oauth_tokens()`, and broadcasts.-**Codex login**: not yet wired. The handler returns a graceful error pointing the user at `npm install -g @openai/codex` + `codex login` manual flow. Follow-up: mirror `nodes/agent/claude_code_agent/_oauth.py` for codex with a `HOME=<DATA_DIR>/codex/` env redirect (Codex has no `CONFIG_DIR` equivalent).+**Codex login**: not yet wired. The handler returns a graceful error pointing the user at `bun add -g @openai/codex` + `codex login` manual flow (the provider itself falls back to `bun x @openai/codex` when no system `codex` is on PATH). Follow-up: mirror `nodes/agent/claude_code_agent/_oauth.py` for codex with a `HOME=<DATA_DIR>/codex/` env redirect (Codex has no `CONFIG_DIR` equivalent).**Frontend**: no changes. The existing `client/src/components/credentials/primitives/OAuthConnect.tsx:42-44` already documents and supports the Stripe-style fieldless-CLI case (`config.fields = []`, `kind: "oauth"`, `stored` flag drives Connected state).@@ -585,7 +585,7 @@ Plugin contract: `tests/test_plugin_contract.py` + `tests/test_node_spec.py` —Live verification (needs a real Claude install + auth):-1. Empty `~/.opencompany/claude/` + `~/.opencompany/packages/`. Open Credentials Modal → click "Login with Claude Code CLI". Confirm the npm install runs (visible in backend logs), `~/.opencompany/packages/node_modules/.bin/claude[.cmd]` appears, browser opens for Anthropic OAuth. Modal flips Connected within ~2s of CLI exit (background `claude auth status` poll detects success). The browser tab should render the CLI's own "Signed in" success page (this needs the `stdin=PIPE` spawn — without it the native binary exits early and the tab is left on the bare `localhost/callback` URL).+1. Empty `~/.opencompany/claude/` + `~/.opencompany/packages/`. Open Credentials Modal → click "Login with Claude Code CLI". Confirm the `bun add` runs (visible in backend logs), `~/.opencompany/packages/node_modules/.bin/claude[.exe]` appears, browser opens for Anthropic OAuth. Modal flips Connected within ~2s of CLI exit (background `claude auth status` poll detects success). The browser tab should render the CLI's own "Signed in" success page (this needs the `stdin=PIPE` spawn — without it the native binary exits early and the tab is left on the bare `localhost/callback` URL).2. Refresh the page. Modal stays Connected (`auth_service.get_oauth_tokens("claude_code")` still returns the marker; idempotent re-click also stays Connected).3. Click Disconnect. Modal flips Disconnected (`claude auth logout` clears CLI creds + marker dropped).4. Add a `claude_code_agent` node, set `tasks=[{prompt:"echo A"},{prompt:"echo B"},{prompt:"echo C"}]`, run. Three distinct `claude:<task_id>` Terminal streams interleaved. Three distinct session_ids. Three worktrees created and removed. `summary.wall_clock_ms < sum(duration_ms)` (proves parallelism).@@ -594,11 +594,11 @@ Live verification (needs a real Claude install + auth):## Risks / open considerations-- **Codex login not yet wired.** v1 returns a graceful error directing the user to `npm install -g @openai/codex` + `codex login`. Follow-up: a codex `_oauth.py` mirroring `nodes/agent/claude_code_agent/_oauth.py` with a `HOME=<DATA_DIR>/codex/` env redirect (Codex has no `CONFIG_DIR` env; `HOME` redirect is risky on Windows, so Windows may need a different strategy or accept user-global Codex auth).+- **Codex login not yet wired.** v1 returns a graceful error directing the user to `bun add -g @openai/codex` + `codex login`. Follow-up: a codex `_oauth.py` mirroring `nodes/agent/claude_code_agent/_oauth.py` with a `HOME=<DATA_DIR>/codex/` env redirect (Codex has no `CONFIG_DIR` env; `HOME` redirect is risky on Windows, so Windows may need a different strategy or accept user-global Codex auth).- **Gemini deferred.** `factory.create_cli_provider("gemini")` raises `NotImplementedError` (the one name-specific branch left in the factory, kept so the dropdown can grey it out). v2 work: implement the provider, register it from a `nodes/agent/gemini_cli_agent/` plugin folder, and drop that branch. ~430 LoC. No abstraction changes needed.- **`--include-partial-messages`** assumes a recent Claude CLI; older versions fall back gracefully via the parser's `parse_event` returning `None` for unknown shapes.- **Native-binary stdin sensitivity.** claude-code >= 2.1.162 ships a native binary that reads stdin during `auth login`. We spawn it with `stdin=asyncio.subprocess.PIPE` (never written) so the read blocks and the OAuth callback server stays alive; an inherited/closed stdin EOFs the binary into an early exit that drops the browser callback. If a future CLI version changes its stdin contract this is the spot to revisit.- **Marker token written without verifying CLI is actually functional** — we trust `claude auth status`'s exit code. If Anthropic invalidates the token server-side and the CLI hasn't re-checked, the modal still shows Connected until the next session attempt's `detect_auth_error` catches it.- **MCP SDK is pre-1.0-stable.** Pinned at `mcp>=1.0.0`. The surface is isolated in `mcp_server.py` so an SDK breaking change touches one file.-- **Concurrent install safety.** `_oauth.py:claude_binary_path` doesn't currently use a lock — two simultaneous login clicks within 2s could race the npm install into the shared tree. Low-risk in practice (modal debounces clicks); a follow-up could add an `asyncio.Lock`.+- **Concurrent install safety.** `_oauth.py:claude_binary_path` doesn't currently use a lock — two simultaneous login clicks within 2s could race the `bun add` into the shared tree. Low-risk in practice (modal debounces clicks); a follow-up could add an `asyncio.Lock`.- **Worktree leak on hard crash.** Out-of-scope cleanup pass; document.diff --git a/docs-internal/cli_services_integration.md b/docs-internal/cli_services_integration.mdindex 4f5007da..8bfe45f1 100644--- a/docs-internal/cli_services_integration.md+++ b/docs-internal/cli_services_integration.md@@ -4,7 +4,7 @@ OpenCompany integrates external services that manage their own lifecycle via CLI## Principles-1. **Plugin-owned binaries** -- OpenCompany-managed CLIs/binaries install into `<DATA_DIR>/packages/` from the plugin's own `_install.py` (pooch or the shared npm tree); truly external tools stay system-installed.+1. **Plugin-owned binaries** -- OpenCompany-managed CLIs/binaries install into `<DATA_DIR>/packages/` from the plugin's own `_install.py` (pooch for release archives, or `core.js_runtime.add_package` — `bun add` into the shared bun-managed packages tree — for npm-registry packages; no Node, no npm); truly external tools stay system-installed.2. **Backend-owned lifecycle** -- long-lived daemons are `BaseProcessSupervisor` subclasses in the plugin folder, spawned on demand and stopped by `shutdown_all_supervisors()` at lifespan shutdown.3. **Ports are declared in `.env.template`** -- the single place port numbers live. The CLI frees only the ports in `cli.config.Config.all_ports`; plugin daemons own theirs.4. **Status is passive** -- status refreshes and WS status commands consult the supervisor (`is_running()`), never spawn.@@ -45,8 +45,9 @@ Follow the plugin-runtime pattern (references: `nodes/whatsapp/_runtime.py`,`nodes/code/_runtime.py`, `services/temporal/_runtime.py`):1. **Install** — plugin-owned `_install.py` that materialises the binary- under `<DATA_DIR>/packages/<name>/` (pooch for release archives, the- shared npm tree for npm packages). Idempotent; callable one-shot from+ under `<DATA_DIR>/packages/<name>/` (pooch for release archives; the+ shared bun-managed packages tree via `core.js_runtime.add_package` for+ npm-registry packages, whose bin shims then run on bun). Idempotent; callable one-shot from`company build` when pre-caching is worth it.2. **Supervise** — a `BaseProcessSupervisor` subclass in the plugin folder(`_runtime.py`) owning argv/cwd/env, with `ensure_started()`diff --git a/docs-internal/cloudflare_service.md b/docs-internal/cloudflare_service.mdindex 5fc6689b..708034c8 100644--- a/docs-internal/cloudflare_service.md+++ b/docs-internal/cloudflare_service.md@@ -13,7 +13,7 @@ grant** that makes the optional API token the only path to analytics.|---|---|| Node type | `cloudflareAction` (palette group `deployment`, dual-purpose AI tool `cloudflare`) || Operations | `whoami` / `zones_list` / `dns_records_list` / `dns_record_create` / `dns_record_delete` / `graphql_query` / `custom` |-| CLI pin | `[email protected]` (`_NPM_SPEC` in `_install.py`), npm-installed into the shared `packages_dir()` tree; cf declares `engines.node >= 22`, above OpenCompany's 18+ floor (this is the only node that needs 22) |+| CLI pin | `[email protected]` (`_NPM_SPEC` in `_install.py`), `bun add`ed into the shared `packages_dir()` tree via `core/js_runtime.add_package` and run on bun; cf declares `engines.node >= 22`, which bun ignores — verified on bun 1.4 with no Node on PATH, including `cf auth whoami` || Auth | Dual-path: cf-owned OAuth login OR optional canonical `apiKey` field (stored under the provider id `cloudflare`) -> `CLOUDFLARE_API_TOKEN` env || Task queue | `TaskQueue.REST_API` || Output | `ui_hints = {"outputMode": "terminal"}`; `_shape` contract (parsed JSON -> `result`, text -> `stdout`, never both) + NDJSON recovery |@@ -28,7 +28,7 @@ server/nodes/cloudflare/├── cloudflare_action.py # CloudflareActionNode + Params/Output + _run/_shape + _graphql_post├── _credentials.py # CloudflareCredential — resolve() returns the optional token row├── _handlers.py # cloudflare_login / cloudflare_logout / cloudflare_status-├── _install.py # ensure_cf_cli() — pinned npm install, system cf NEVER consulted+├── _install.py # ensure_cf_cli() — pinned `bun add` (core/js_runtime), system cf NEVER consulted├── _service.py # cf_env(token, email) / api_auth_headers() / login_env() / whoami_snapshot() / stored_token() / stored_email() / resolve_cf_light()└── meta.json # {"color": "#F38020"}```@@ -40,9 +40,11 @@ dual-path shape: one optional field, never gating the Login button).## Install — pinned, never the system PATH-`_install.py` uses vercel's npm **mechanism** (install into the shared-`packages_dir()` tree, `.bin` shim, `asyncio.to_thread`, double-checked-lock) but github's **resolution philosophy**: `shutil.which("cf")` is+`_install.py` uses vercel's install **mechanism** (`core.js_runtime.add_package`+— `bun add --cwd <packages_dir> <spec>` into the shared tree, the+`node_modules/.bin` shim via `shared_tree_bin("cf")`, `asyncio.to_thread`,+double-checked lock; the CLI runs on bun, no Node or npm involved) but+github's **resolution philosophy**: `shutil.which("cf")` isnever consulted. The preview CLI's command tree is schema-generated anddrifts between versions — between 0.0.5 and 0.2.0, `--ndjson`/`--fields`were removed (JSON became the default output), `dns records create`@@ -72,9 +74,10 @@ Two hazards drove the handler's shape (both observed live):collide on 8877; the second exits instantly with "Port already inuse". A module-level **single-flight guard** (`_active_login` task +proc) makes repeat Login clicks return "already in progress".-2. **Windows shim orphaning** — the installed binary is an npm `.cmd`- shim; killing it terminates only the cmd.exe wrapper and orphans the- node child, which keeps holding 8877 and breaks every later login.+2. **Windows shim orphaning** — the installed binary is bun's `cf.exe`+ launcher shim (plus a `cf.bunx` file, never `.cmd`); killing it+ terminates only the launcher and orphans the child bun process running+ the CLI, which keeps holding 8877 and breaks every later login.The completion watcher **never kills the process** (test-locked) —cf enforces its own login timeout and exits by itself.diff --git a/docs-internal/desktop_app.md b/docs-internal/desktop_app.mdindex 470e1f41..82ec401c 100644--- a/docs-internal/desktop_app.md+++ b/docs-internal/desktop_app.md@@ -1,7 +1,8 @@# Desktop AppThe OpenCompany desktop app is an Electron shell in [`desktop/`](../desktop/)-that bundles `uv`, a standalone CPython and Node, provisions the backend's+that bundles `uv`, a standalone CPython and bun (the only JavaScript runtime the+backend needs — no Node, no npm), provisions the backend'svirtual environment on first launch, runs the same uvicorn backend the CLIruns, and shows the backend-served SPA in a native window. Nothing in`client/` changes: every URL in the SPA is relative and the WebSocket URL is@@ -22,11 +23,12 @@ produced this feature. Short form:- **Bundle uv + Python, `uv sync` at first run** (over a pre-built venv inthe installer). The venv is built at its final path, so nothing has to bemade relocatable; the macOS signing scope (later) is a fixed set of- ~60 CPython Mach-O files plus uv and Node; updates re-sync only when+ ~60 CPython Mach-O files plus uv and bun; updates re-sync only when`uv.lock` / `pyproject.toml` / the bundled Python changes. OpenCompanyalready provisions at first run (`install.js` runs `uv sync`, Temporal and- the npm CLIs download on first use, `browser_harness` needs `uv` at- runtime), so uv ships in every design.+ the plugin CLIs (`bun add` into `~/.opencompany/packages/`) download on+ first use, `browser_harness` needs `uv` at runtime), so uv ships in every+ design.## Layout@@ -38,17 +40,20 @@ OpenCompany.app / OpenCompany/ / AppImagepackage.json package.json, .opencompany/workflows/,.opencompany/workflows/ server/uv.lock, server/pyproject.tomlclient/dist/- server/ (+ nodejs/dist/index.js re-bundled with express inlined)+ server/ (+ nodejs/dist/index.js — the sidecar's own `bun build --target=bun`, express inlined)runtime/uv/uv[.exe] pinned uv (runtimes.json)python/ python-build-standalone install_only_stripped- node/ official Node LTS dist incl. npm- licenses/+ bun/bun[.exe] official bun release zip (runtimes.json): the JS executor runtime+ and the installer for the plugin CLIs; LICENSE.md fetched from the bun repo+ licenses/ OpenCompany-LICENSE, Bun-LICENSE.md, Python-LICENSE.txt<userData> %APPDATA%/OpenCompany | ~/Library/Application Support/OpenCompany | ~/.config/OpenCompanypyenv/venv/ UV_PROJECT_ENVIRONMENT (+ .provision.json stamp)pyenv/python/ UV_PYTHON_INSTALL_DIR (fallback path only)pyenv/cache/ pyenv/tools/ UV_CACHE_DIR, UV_TOOL_DIR / UV_TOOL_BIN_DIR+ bun/ BUN_INSTALL (+ bun/install/cache = BUN_INSTALL_CACHE_DIR): bun's package+ cache and global state, kept out of a dev install's ~/.bunpycache/ PYTHONPYCACHEPREFIX (bundle is read-only)logs/main.log, backend.log, backend.stdout.logdesktop-state.json persisted port@@ -105,21 +110,28 @@ modules, so both macOS architectures build on one arm64 runner.```bashcd desktopbun install-bun run stage # app-root from `npm pack --dry-run` + runtimes for this host+bun run stage # app-root from `bun pm pack --dry-run` + runtimes for this hostbun run typecheck && bun run test && bun run test:invariantsbun run build && bun run test:e2ebun run gen-icons && bun run dist```-`desktop/scripts/stage.ts` takes the file list from `npm pack --dry-run --json` (the-root `files` allowlist, i.e. what the npm package ships), drops what a bundle+`desktop/scripts/stage.ts` takes the file list from `bun pm pack --dry-run` (the+root `files` allowlist, i.e. what the published tarball ships), drops what a bundlenever needs (CLI, install scripts, client sources, backend tests) and-force-includes `server/uv.lock`. It re-bundles the Node sidecar with-`express` inlined. `desktop/scripts/fetch-runtimes.ts` downloads the versions pinned+force-includes `server/uv.lock`. It builds the JS executor sidecar with the+sidecar package's own `bun run build` (`bun build --target=bun`, a self-contained+bundle with `express` inlined) and copies `dist/index.js` — no re-bundle of its+own. `desktop/scripts/fetch-runtimes.ts` downloads the versions pinnedin `runtimes.json`, verifies each against the upstream checksum manifest(`.sha256` sidecars for uv, `SHA256SUMS` for python-build-standalone,-`SHASUMS256.txt` for Node), caches in `vendor/`, and extracts into-`stage/runtime/<os>-<arch>/`. Extraction uses the platform `tar`; on Windows+`SHASUMS256.txt` for bun), fetches bun's `LICENSE.md` from the bun repo (the+release zip carries no license file; electron-builder ships it as+`licenses/Bun-LICENSE.md`), caches in `vendor/`, prunes stale runtime dirs (a+leftover `node/` from an older stage), and extracts into+`stage/runtime/<os>-<arch>/`. The staged-tree invariants assert bun is present,+no `node/` dir exists, and the sidecar boots on the bundled bun with Node+stripped from PATH. Extraction uses the platform `tar`; on Windowsthe System32 bsdtar is used explicitly because Git's GNU tar cannot readzips.@@ -162,8 +174,8 @@ bundled Python. Then remove the macOS notify-only branch inwindows-latest / macos-14 / ubuntu-22.04; builds the client and sidecarwith the repo toolchain, stages, runs typecheck + unit + invariant tests,`electron-builder --publish always` into one draft release; a `finalize`- job undrafts it once all legs pass. Separate from `release.yml` so npm- publish is never blocked and its locked strings are untouched.+ job undrafts it once all legs pass. Separate from `release.yml` so the+ registry publish (`bun publish`) is never blocked and its locked strings are untouched.- `desktop-ci.yml` on PRs touching `desktop/**` or the backend contractfiles: typecheck, unit, invariants, build, and the Playwright Electronsmoke (xvfb on Linux) against a `uv sync`ed checkout venv.@@ -173,7 +185,7 @@ bundled Python. Then remove the macOS notify-only branch in| Env var | Effect ||---|---|| `OPENCOMPANY_DESKTOP_APP_ROOT` | serve this app-root instead of `stage/app-root` (e.g. the repo checkout) |-| `OPENCOMPANY_DESKTOP_RUNTIME_DIR` | use these `uv/python/node` dirs |+| `OPENCOMPANY_DESKTOP_RUNTIME_DIR` | use these `uv/python/bun` dirs || `OPENCOMPANY_DESKTOP_VENV_PYTHON` | use this interpreter and skip provisioning || `OPENCOMPANY_DESKTOP_SKIP_PROVISION=1` | trust the existing venv even if the stamp differs || `OPENCOMPANY_DESKTOP_NO_ATTACH=1` | never attach to a running backend (tests) |diff --git a/docs-internal/desktop_host_contract.md b/docs-internal/desktop_host_contract.mdindex 7e198fd4..dc39f128 100644--- a/docs-internal/desktop_host_contract.md+++ b/docs-internal/desktop_host_contract.md@@ -20,8 +20,8 @@ be force-quit without running any of its own shutdown code.## 1. Relocatable tree: `core.approot`-The backend ships as a sibling layout that a checkout, the npm tarball, and-the bundle share:+The backend ships as a sibling layout that a checkout, the published tarball+(`bun add -g`), and the bundle share:```<app root>/@@ -71,7 +71,7 @@ cwd: <app root>/serveropen connections and in-flight handler tasks before it runs the lifespanshutdown. A renderer that disappears with a TCP reset (the window closing)can leave its WebSocket handler task lingering, and without the bound the-backend never reaches the teardown that reaps Temporal / node / edgymeow.+backend never reaches the teardown that reaps Temporal / the bun sidecar / edgymeow.`company serve` / `company start` pass the same bound(`cli/_common.py::UVICORN_GRACEFUL_SHUTDOWN_SECONDS`).@@ -84,14 +84,16 @@ OPENCOMPANY_DESKTOP_TOKEN=<random per launch>OPENCOMPANY_DESKTOP_STDIN=1 # shell keeps stdin as an open pipeOPENCOMPANY_APP_ROOT=<bundle>/app-rootOPENCOMPANY_ENV_FILE=<data dir>/desktop.env-OPENCOMPANY_NODE_BIN=<bundle>/node/bin/node # optional; PATH prefix also works+OPENCOMPANY_BUN_BIN=<bundle>/bun/bun[.exe] # the bundled bun (core/js_runtime.py); PATH prefix also works+BUN_INSTALL=<data dir>/bun # bun's global state, kept out of a dev install's ~/.bun+BUN_INSTALL_CACHE_DIR=<data dir>/bun/install/cacheOPENCOMPANY_UV_BIN=<bundle>/uv/uv # optional; PATH prefix also worksPORT=<PORT> PYTHON_BACKEND_PORT=<PORT> HOST=127.0.0.1SERVE_STATIC_CLIENT=1 PYTHONUTF8=1 PYTHONUNBUFFERED=1PYTHONPYCACHEPREFIX=<data dir>/pycache # bundle is read-onlyLOG_FILE=<data dir>/logs/backend.log LOG_FORMAT=jsonTEMPORAL_GRACEFUL_SHUTDOWN_SECONDS=10-PATH=<bundle>/node[/bin]:<bundle>/uv:$PATH # node, npm, uv for runtime installs+PATH=<bundle>/bun:<bundle>/uv:$PATH # bun (JS runtime + package installs), uv; no Node, no npm````DATA_DIR` is left at its default (`~/.opencompany`) so the desktop app and@@ -123,8 +125,8 @@ Primary: `POST /api/desktop/shutdown` with header `X-Desktop-Token:<OPENCOMPANY_DESKTOP_TOKEN>`. Returns 202, then after 0.2 s the backendraises the signal uvicorn already handles (SIGINT on Windows, SIGTERMelsewhere). The lifespan teardown then runs: plugin shutdown hooks, the-process manager, every registered supervisor (Temporal dev server, Node-sidecar, WhatsApp bridge) through `terminate_then_kill`, then database+process manager, every registered supervisor (Temporal dev server, the JS+executor sidecar on bun, WhatsApp bridge) through `terminate_then_kill`, then databaseclose. The route exists only under `OPENCOMPANY_DESKTOP=1` and refuses everyrequest when the token is unset. Locked by`tests/test_desktop_shutdown_endpoint.py`.@@ -150,7 +152,7 @@ Armed by `start_desktop_mode()` at lifespan start:our children and `os._exit(1)`s if the graceful path wedges.- **Windows Job Object**: the backend enrolls itself in a kill-on-close job(ctypes, no pywin32). Children inherit membership, so if the backend is- terminated by any means the kernel kills Temporal / node / edgymeow with+ terminated by any means the kernel kills Temporal / the bun sidecar / edgymeow withit. Locked by `tests/test_job_object.py` (Windows only).`tests/test_desktop_watchdog.py` covers the watchdogs and the single@@ -158,14 +160,22 @@ shutdown funnel.## 7. Runtime binaries-Plugins resolve `node`, `npm`, `npx`, `uv` through `shutil.which`, so a-bundled `bin/` prepended to PATH satisfies the JS executor sidecar-(`nodes/code/_runtime.py`), the five `npm install --prefix` plugins-(claude-code, edgymeow, agent-browser, cf, vercel), the codex provider, and-`uv tool install browser-harness`. `OPENCOMPANY_NODE_BIN` and-`OPENCOMPANY_UV_BIN` are explicit overrides for the two the backend spawns-directly. Do not put the bundled bare Python on PATH: plugins must never-pick it up instead of the venv interpreter.+The backend spawns exactly one JavaScript runtime, bun, and resolves it in one+place: `core/js_runtime.py` (`OPENCOMPANY_BUN_BIN`, else `bun` on PATH). `uv`+is resolved through `OPENCOMPANY_UV_BIN` / `shutil.which`. So the bundled+runtime dirs prepended to PATH (plus the two overrides) satisfy the JS+executor sidecar (`nodes/code/_runtime.py`, `[bun, dist/index.js]`), the five+plugin installers that `bun add` into the shared `<DATA_DIR>/packages/` tree+(claude-code, edgymeow, agent-browser, cf, vercel — `core.js_runtime.add_package`),+the codex provider (`bun x @openai/codex` when no system `codex` exists), and+`uv tool install browser-harness`. `BUN_INSTALL` / `BUN_INSTALL_CACHE_DIR`+keep bun's own cache and global state under the app's data dir rather than a+dev install's `~/.bun`. There is no Node in the bundle and nothing looks for+one — `tests/core_config/test_js_runtime.py::test_backend_never_spawns_node_or_npm`+forbids `shutil.which("node"|"npm"|"npx")` anywhere under `server/`, and the+desktop staged-tree invariants boot the sidecar on the bundled bun with Node+stripped from PATH. Do not put the bundled bare Python on PATH: plugins must+never pick it up instead of the venv interpreter.## 8. Loggingdiff --git a/docs-internal/errors.md b/docs-internal/errors.mdindex 87f06949..9c83bd5f 100644--- a/docs-internal/errors.md+++ b/docs-internal/errors.md@@ -337,7 +337,7 @@ with no "Signed in" page — yet the backend log shows the login succeeded and c**Fix** (landed at tag v0.0.88): `services/events/cli.py::run_cli_command()` gained an optional `stdin` parameter (default `None` = inherit, unchanged for every existing caller). `nodes/agent/claude_code_agent/_oauth.py::_run_auth` passes `stdin=asyncio.subprocess.PIPE` **for the `login` subcommand only** so the CLI's stdin read blocks instead of EOFing, keeping the callback server alive until the flow completes naturally. `status` / `logout` stay on inherit-stdin (one-shot, no stdin read).-Note the binary install path also moved this release: the claude CLI now lives in the shared OpenCompany npm tree at `<DATA_DIR>/packages/node_modules/.bin/claude[.cmd]` (was `<DATA_DIR>/claude/npm/...`). The fresh `npm install` triggered by that move is what pulled the 2.1.162 native binary that surfaced this bug — the path change was the trigger, the `stdin=PIPE` is the actual fix.+Note the binary install path also moved this release: the claude CLI now lives in the shared OpenCompany packages tree at `<DATA_DIR>/packages/node_modules/.bin/claude` (was `<DATA_DIR>/claude/npm/...`; the Windows shim was `claude.cmd` under npm at the time and is bun's `claude.exe` + `claude.bunx` since the tree moved to `bun add`). The fresh install triggered by that move is what pulled the 2.1.162 native binary that surfaced this bug — the path change was the trigger, the `stdin=PIPE` is the actual fix.---@@ -409,7 +409,9 @@ python -c "import ntpath; print(ntpath.join(r'D:\ws\AI_Employee_1', '2:processMa## 15. `npm install -g` Fails With `externally-managed-environment` (Ubuntu 24.04+)-**Symptom**: `npm install -g @zeenie-ai/opencompany` aborts inside the postinstall with:+**Historical note (bun channel)**: the install channel is now `bun add -g @zeenie-ai/opencompany`, which runs no lifecycle scripts; the same provisioning (`scripts/install.js`) runs on the first `company` command instead, or eagerly from `install.sh` / `install.ps1`, so this failure would surface there rather than in an npm postinstall. The fix below still applies unchanged, and the installer scripts install uv themselves before provisioning.++**Symptom**: `npm install -g @zeenie-ai/opencompany` (the install channel at the time) aborted inside the postinstall with:```Installing uv via pip...error: externally-managed-environment@@ -418,7 +420,7 @@ Seen on Ubuntu 24.04 (EC2 `ubuntu-noble` AMI). `python3 -m ensurepip` also fails**Root cause**: `scripts/install.js` installed uv with `python3 -m pip install uv` and had no other path. PEP 668 marks the distro Python as externally managed, so the system pip refuses every install outside a venv.-**Fix** (shipped after 0.1.1): `installUv` tries pip first and, on failure, runs uv's official standalone installer (`curl -LsSf https://astral.sh/uv/install.sh | sh`, `irm https://astral.sh/uv/install.ps1 | iex` on Windows) and prepends `~/.local/bin` to `PATH` for the rest of the install. On a 0.1.1 install, run that installer yourself first; the postinstall then finds `uv` and continues.+**Fix** (shipped after 0.1.1): `installUv` tries pip first and, on failure, runs uv's official standalone installer (`curl -LsSf https://astral.sh/uv/install.sh | sh`, `irm https://astral.sh/uv/install.ps1 | iex` on Windows) and prepends `~/.local/bin` to `PATH` for the rest of the install. On a 0.1.1 install, run that installer yourself first; the provisioning step then finds `uv` and continues.---@@ -432,16 +434,18 @@ sh: 1: python: not found```Seen on Ubuntu 26.04 (system Python 3.14).-**Root cause**: `server/pyproject.toml` pins `requires-python = ">=3.11,<3.13"`. When the system Python falls outside that range, `uv sync` downloads a managed CPython 3.12 into the invoking user's `~/.local/share/uv/python/` and both `server/.venv` and `.cli-venv` symlink into it. With `sudo npm install -g` that user is root, and `/root` is mode 700, so the venv interpreters are unusable by anyone else. `bin/cli.js` then falls back to `npm run start`, which needs a bare `python` on `PATH`; Ubuntu has only `python3`.+**Historical note (bun channel)**: this failure mode belonged to the npm channel. `bun add -g` installs as the login user (shim `~/.bun/bin/company`; the package itself sits wherever bun keeps its global packages, which `company provision` never needs to know) — there is no global prefix to make writable and no reason to reach for `sudo`, so the venvs, the uv-managed Python and `~/.opencompany` belong to the login user by construction. `install.sh` / `install.ps1` run `bun add -g` as the invoking user and, when npm happens to be present, evict a legacy npm install of the scoped package or `machinaos` (the shims would otherwise shadow the bun one). A leftover root install from the npm era is still removed with `sudo npm uninstall -g @zeenie-ai/opencompany && sudo rm -rf /root/.opencompany`.++**Root cause** (npm era): `server/pyproject.toml` pins `requires-python = ">=3.11,<3.13"`. When the system Python falls outside that range, `uv sync` downloads a managed CPython 3.12 into the invoking user's `~/.local/share/uv/python/` and both `server/.venv` and `.cli-venv` symlink into it. With `sudo npm install -g` that user was root, and `/root` is mode 700, so the venv interpreters were unusable by anyone else. `bin/cli.js` then fell back to the script-runner path, which needs a bare `python` on `PATH`; Ubuntu has only `python3`.-**Fix**: do the global install without `sudo`, using a user-writable npm prefix (the npm-documented way; Ubuntu 26.04 has no `python3.12` apt package to fall back on):+**Fix** (npm era): do the global install without `sudo`, using a user-writable npm prefix (Ubuntu 26.04 has no `python3.12` apt package to fall back on):```bash-npm config set prefix ~/.npm-global+npm config set prefix ~/.npm-global # npm era only; bun add -g is user-owned under ~/.bunecho 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc && source ~/.bashrcnpm install -g @zeenie-ai/opencompanycompany start```-uv then downloads its 3.12 into `~/.local/share/uv`, the venvs are usable by the login user, and data lands in `~/.opencompany`. If a root install already exists, remove it first: `sudo npm uninstall -g @zeenie-ai/opencompany && sudo rm -rf /root/.opencompany`. Verified on an EC2 t3a.small running Ubuntu 26.04. `install.sh` (the `curl | bash` installer) now does this itself whenever the global prefix is not writable, instead of retrying with `sudo`; verified end to end on a fresh Ubuntu 24.04 t3.micro.+uv then downloads its 3.12 into `~/.local/share/uv`, the venvs are usable by the login user, and data lands in `~/.opencompany`. Verified on an EC2 t3a.small running Ubuntu 26.04, and end to end on a fresh Ubuntu 24.04 t3.micro through `install.sh`. The bun channel keeps the same rule — install as the login user, never `sudo` — and gets the user-owned layout for free.---@@ -467,11 +471,13 @@ uv then downloads its 3.12 into `~/.local/share/uv`, the venvs are usable by the## 19. JS/TS Executor Fails on a Fresh npm Install: `Cannot find package 'express'`-**Symptom**: On a machine set up with `npm install -g @zeenie-ai/opencompany`, the first JavaScript or TypeScript executor node run fails with `Node.js executor did not become ready`, and the sidecar log shows `Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from .../server/nodejs/dist/index.js`.+**Historical note (moot on the bun channel)**: the sidecar is now built with `bun build src/index.ts --target=bun --outfile=dist/index.js`, a self-contained bundle with `express` inlined, and runs as `bun dist/index.js` (`nodes/code/_runtime.py` via `core/js_runtime.py`). There is no runtime dependency left to resolve, so the root `express` dependency this fix added has been removed again. Kept for the record.++**Symptom** (npm era): On a machine set up with `npm install -g @zeenie-ai/opencompany`, the first JavaScript or TypeScript executor node run failed with `Node.js executor did not become ready`, and the sidecar log showed `Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'express' imported from .../server/nodejs/dist/index.js`.-**Root cause**: The sidecar bundle is built with `--packages=external`, so Express stays a runtime dependency, but it was declared only in `server/nodejs/package.json`. The npm package excludes every `node_modules`, and `nodes/code/_runtime.py` only checks that `dist/index.js` exists, so nothing ever installed Express on an npm-installed copy. Source checkouts never saw it because `bun install` provisions the workspace.+**Root cause** (npm era): The sidecar bundle was built with esbuild's `--packages=external`, so Express stayed a runtime dependency, but it was declared only in `server/nodejs/package.json`. The package excludes every `node_modules`, and `nodes/code/_runtime.py` only checks that `dist/index.js` exists, so nothing ever installed Express on an npm-installed copy. Source checkouts never saw it because `bun install` provisions the workspace.-**Fix**: `express` is declared in the root `package.json` `dependencies`, so npm installs it beside the package and Node resolves it from `server/nodejs/dist` by walking up to the package root. Nothing else changed; the sidecar still runs under whichever `node` is on `PATH` (18+ verified on Ubuntu 24.04's distro package).+**Fix** (npm era): `express` was declared in the root `package.json` `dependencies`, so npm installed it beside the package and Node resolved it from `server/nodejs/dist` by walking up to the package root. Superseded by the `--target=bun` bundle above.## 20. Graceful backend shutdown hangs, then the supervisor tree-kills it (Temporal / node / edgymeow orphaned)@@ -479,7 +485,7 @@ uv then downloads its 3.12 into `~/.local/share/uv`, the venvs are usable by the**Root causes** (two, found while building the desktop shell; the CLI's 5 s grace + tree-kill had masked both):-1. `nodes/browser/_service.py::shutdown_browser_service` called `get_browser_service()`, which lazily runs `npm install agent-browser@latest` on first call — so a process that never used the browser ran a network install *at teardown*, synchronously on the event loop, and every graceful exit wedged there.+1. `nodes/browser/_service.py::shutdown_browser_service` called `get_browser_service()`, which lazily runs the `agent-browser@latest` install on first call (`npm install` at the time; `bun add` via `core/js_runtime.add_package` today) — so a process that never used the browser ran a network install *at teardown*, synchronously on the event loop, and every graceful exit wedged there.2. uvicorn's `timeout_graceful_shutdown` defaults to `None`: it waits forever for open connections and in-flight handler tasks before sending the lifespan shutdown. A browser WebSocket that disappears with a TCP reset (the tab or window closing) can leave its handler task lingering, and the lifespan teardown — the part that reaps the child daemons — is never reached.**Fix**: the browser hook reads its module singleton and closes only a service that was actually created; every plugin shutdown hook now runs under `HOOK_TIMEOUT_SECONDS` (10 s, `services/plugin/shutdown_hooks.py`) and names the offender at WARNING; `company serve` / `company start` and the desktop shell pass `--timeout-graceful-shutdown 5` (`cli/_common.py::UVICORN_GRACEFUL_SHUTDOWN_SECONDS`). Note that the hook timeout cannot interrupt a hook that blocks the loop synchronously — keep hooks async.diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.mdindex 5df4f716..670df6a7 100644--- a/docs-internal/frontend_architecture.md+++ b/docs-internal/frontend_architecture.md@@ -8,7 +8,7 @@ Post-migration (2026-04-14). Single source of truth for the current frontend.- **React 19 + Vite 7**, type-checked by **TypeScript 7** (the native Go compiler, exact-pinned `7.0.2` in the **root** `devDependencies`). The client keeps `typescript@^5.9.3` only because typescript-eslint's peer range excludes 6/7 — it is not the gate. With the **React Compiler** (`[email protected]`, `target: '19'`, scoped to all of `src/` except `components/ui/`).- **Tailwind v4** via `@tailwindcss/vite` + `@import "tailwindcss"` in [src/index.css](../client/src/index.css). Tokens defined in the same CSS file via `@theme inline` (no `tailwind.config.js` colors block).-- **shadcn/ui** via the canonical CLI (`npx shadcn@latest add`). All primitives live under [client/src/components/ui/](../client/src/components/ui/) as first-class repo files we can edit.+- **shadcn/ui** via the canonical CLI (`bun x shadcn@latest add` — bun's `npx` equivalent; npm is not part of the toolchain). All primitives live under [client/src/components/ui/](../client/src/components/ui/) as first-class repo files we can edit.- **Radix UI** is the primitive engine shadcn uses (Dialog, Accordion, Select, Switch, Tabs, Tooltip, Popover, Dropdown, AlertDialog, Collapsible, Progress, Slider, Label, Checkbox).- **Forms**: react-hook-form + zod via shadcn's `Form` composition. Per-form schemas live colocated with the form (e.g. `credentials/panels/schemas/email.ts`); tiny forms use inline zod.- **Toasts**: `sonner` imported directly at call-sites. The shadcn `<Toaster />` wrapper (at [components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx)) is patched to read our `ThemeContext` instead of `next-themes`.@@ -26,7 +26,7 @@ Post-migration (2026-04-14). Single source of truth for the current frontend.| Type checker (second opinion) | `typescript@^5.9.3` in **client** `dependencies` | Kept for typescript-eslint's peer range (`>=4.8.4 <6.1.0`). Two `typescript` entries cannot live in one manifest, and both 5.x and 7.x expose a `tsc` bin — hence the root/client split. `bun run typecheck:tsc` runs it for triage only. || Compiler | `[email protected]` (exact-pinned; `target: '19'` = the React version, not the plugin version) | [vite.config.js](../client/vite.config.js) (scoped: all of `/src/` except `components/ui/`). Pin is exact because semver sorts the old `19.1.0-rc.3` **above** `1.0.0`, so a range would silently reinstall the release candidate — which lacks the incompatible-library skip list. || Styling | Tailwind v4 + `@tailwindcss/vite` | [index.css](../client/src/index.css) + [tailwind.config.js](../client/tailwind.config.js) |-| Component library | shadcn/ui (CLI `npx shadcn@latest add`) | [components/ui/](../client/src/components/ui/) |+| Component library | shadcn/ui (CLI `bun x shadcn@latest add`) | [components/ui/](../client/src/components/ui/) || Primitives | Radix UI | Pulled as transitive deps by shadcn || Icons | `lucide-react` | Everywhere. No more `@ant-design/icons`. Backend-declared node / provider icons go through `<NodeIcon size={token}>` — `theme.nodeSize.squareIcon` on canvas nodes, `theme.iconSize.*` elsewhere; the token is applied as width, height and emoji font size, so never size an icon with `h-*` / `text-*` classes. || Typography | `@tailwindcss/typography` (`prose`) | Activated via `@plugin` in index.css |@@ -289,7 +289,7 @@ All under [components/ui/](../client/src/components/ui/). Editable — add varia| Toast | `Sonner` `<Toaster />` | Patched for our ThemeContext |**Rules for adding primitives:**-- Always use the CLI: `OPENCOMPANY_INSTALLING=true npx shadcn@latest add <name>` from `client/` (the env var suppresses the project's recursive postinstall hook).+- Always use the CLI: `OPENCOMPANY_INSTALLING=true bun x shadcn@latest add <name>` from `client/` (the env var suppresses the project's recursive postinstall hook).- New variants go inside the generated file (we own it).- Don't wrap primitives in `<Stack>`/`<Inline>`/`<Text>`/`<Heading>`. Use raw Tailwind classes. The Tailwind utility API IS the design system for layout/typography.@@ -628,7 +628,7 @@ bun run typecheck:tsc # second opinion under client's tsc 5.9.3 (triage only,**Adding shadcn components:**```bashcd client-OPENCOMPANY_INSTALLING=true npx shadcn@latest add <name>+OPENCOMPANY_INSTALLING=true bun x shadcn@latest add <name>```The `OPENCOMPANY_INSTALLING=true` env var suppresses the recursive project postinstall hook during shadcn's internal package-manager install. Without it the hook's `company build` run fails and shadcn aborts before writing the component file.diff --git a/docs-internal/gcp_vm_deploy_runbook.md b/docs-internal/gcp_vm_deploy_runbook.mdindex 3863db0c..5eb11560 100644--- a/docs-internal/gcp_vm_deploy_runbook.md+++ b/docs-internal/gcp_vm_deploy_runbook.md@@ -1,6 +1,6 @@-# GCP VM Deploy Runbook (released npm package, manual gcloud + cf)+# GCP VM Deploy Runbook (released package via `bun add -g`, manual gcloud + cf)-Step-by-step runbook for deploying the **released** `@zeenie-ai/opencompany` npm package on a fresh+Step-by-step runbook for deploying the **released** `@zeenie-ai/opencompany` package (from the npm registry, installed with `bun add -g` — no Node, no npm on the VM) on a freshGCP VM behind a Cloudflare-proxied domain, with the single-owner login gate enabled.Written to be executable by an AI agent (or a human) with no other context.@@ -52,8 +52,9 @@ print('ENC='+secrets.token_hex(24))"## Known pitfalls (read first — these each cost a redeploy or a debugging loop)-1. **Debian 12 fails.** The npm package's `postinstall` hard-requires Python 3.12+;- Debian 12 ships 3.11 and `npm install -g @zeenie-ai/opencompany` exits 1+1. **Debian 12 fails.** The package's provisioning step (`scripts/install.js`, run+ after `bun add -g`; it was the npm `postinstall` when this was first hit)+ hard-requires Python 3.12+; Debian 12 ships 3.11 and it exits 1(`ERROR: Python 3.12+ is required.`). Use **Ubuntu 24.04** (`ubuntu-2404-lts-amd64`in `ubuntu-os-cloud`), which ships Python 3.12.2. **`company serve` exists only in `>= 0.0.95`.** Releases up to 0.0.88 shipped only@@ -135,20 +136,28 @@ systemd):```bash#!/bin/bash-# OpenCompany VM startup script: released npm package via `company start`,+# OpenCompany VM startup script: released package via `company start`,# nginx on :80/:443 (self-signed TLS for Cloudflare Full mode), login gate on.+# Toolchain block mirrors cli/terraform/gcp/startup.sh.tftpl (the bun channel):+# bun + uv, no Node, no npm.set -euo pipefailexport DEBIAN_FRONTEND=noninteractiveecho "[opencompany] installing toolchain..."apt-get update-apt-get install -y curl ca-certificates git build-essential pkg-config libffi-dev libssl-dev nginx-curl -fsSL https://deb.nodesource.com/setup_22.x | bash --apt-get install -y nodejs+apt-get install -y curl ca-certificates git unzip build-essential pkg-config libffi-dev libssl-dev nginx+# bun on a stable system path: the runtime for the `company` shim, the JS+# executor sidecar and the plugin CLIs, and the installer for the package.+export BUN_INSTALL=/usr/local+curl -fsSL https://bun.sh/install | bashcurl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin shecho "[opencompany] installing OpenCompany released package..."-npm install -g @zeenie-ai/opencompany@latest+bun add -g @zeenie-ai/opencompany@latest+# bun runs no lifecycle scripts for a global package; provision the Python+# side now so the service's first start is warm. The shim lives in bun's+# global bin dir ($BUN_INSTALL/bin) and knows its own package root.+"$BUN_INSTALL/bin/company" provisionecho "[opencompany] writing login-gate env..."mkdir -p /etc/opencompany@@ -238,8 +247,10 @@ systemctl reload nginxecho "[opencompany] installing systemd service (README usage: company start)..."OPENCOMPANY_BIN=$(command -v company)-OPENCOMPANY_PACKAGE_DIR="$(npm root -g)/@zeenie-ai/opencompany"-test -d "$OPENCOMPANY_PACKAGE_DIR"+# The shim is a symlink into the package (bun keeps global packages wherever it+# likes); resolve it rather than spelling that directory.+OPENCOMPANY_PACKAGE_DIR="$(cd "$(dirname "$(readlink -f "$OPENCOMPANY_BIN")")/.." && pwd)"+test -f "$OPENCOMPANY_PACKAGE_DIR/package.json"cat > /etc/systemd/system/opencompany.service <<SERVICE_EOF[Unit]Description=OpenCompany (released, company start)@@ -318,7 +329,7 @@ and (in Full SSL mode) connects to the origin's self-signed :443.## Step 5 — Wait for provisioning-Provisioning takes ~5-8 minutes (apt + Node 22 + npm install with Python dep sync).+Provisioning takes ~5-8 minutes (apt + bun + `bun add -g` + the Python dep sync in `install.js`).Poll until healthy:```bash@@ -411,7 +422,7 @@ gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo journalctl -u# restart app:gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo systemctl restart opencompany"# upgrade to a new release:-gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo npm install -g @zeenie-ai/opencompany@latest && sudo systemctl restart opencompany"+gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo env BUN_INSTALL=/usr/local bun add -g @zeenie-ai/opencompany@latest && sudo env BUN_INSTALL=/usr/local /usr/local/bin/company provision && sudo systemctl restart opencompany"# flip an env toggle (sudo on EVERY command touching the 600 env file - pitfall 13c):gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo sed -i 's/TEMPORAL_ENABLED=false/TEMPORAL_ENABLED=true/' /etc/opencompany/opencompany.env; sudo systemctl restart opencompany"# Temporal Web UI (localhost-bound on the VM; gRPC :7233 / UI :8080 are thediff --git a/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md b/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.mdindex 23dfc683..855ed137 100644--- a/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md+++ b/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md@@ -125,7 +125,7 @@ flowchart TDGraphQL POST. `run_cli_command` kills the process tree on timeout andreturns `success: False` with `error: "<binary> timed out (Ns)"`, which thefailure wrap turns into a `NodeUserError`.-- **Error paths**: `ensure_cf_cli()` raising (npm missing, npm install+- **Error paths**: `ensure_cf_cli()` raising (bun missing, `bun add`failing) -> `RuntimeError("cf CLI install failed: ...")`, which is NOT a`NodeUserError` and therefore takes `BaseNode.execute`'s generic exceptionbranch (full traceback). Non-zero exit -> `NodeUserError("cf <argv0>@@ -135,13 +135,15 @@ flowchart TD## Side Effects- **Subprocess**: one `cf` process per operation from the project-local- shim `<DATA_DIR>/packages/node_modules/.bin/cf` (`cf.cmd` on Windows).+ shim `<DATA_DIR>/packages/node_modules/.bin/cf` (`cf.exe` plus a `cf.bunx`+ file on Windows — bun's shims, never `.cmd`), which runs the CLI on bun.The system-global `cf` is never consulted. Child env is a copy of theserver env plus `NO_COLOR=1` and the credential vars above; no `cwd` ispassed (the process inherits the server's cwd - the workflow workspace isnot used).-- **Install**: on first use `npm install [email protected] --prefix <DATA_DIR>/packages- --no-audit --no-fund` runs in a worker thread under an install lock.+- **Install**: on first use `core.js_runtime.add_package("[email protected]")` — `bun add+ --cwd <DATA_DIR>/packages --no-progress [email protected]` — runs in a worker thread+ under an install lock.- **External API calls**: `POST https://api.cloudflare.com/client/v4/graphql`with `{query, variables}` (`graphql_query` only).- **Credential reads**: `auth_service.get_api_key("cloudflare")` and@@ -163,8 +165,9 @@ flowchart TDsession created by `cf auth login` lives in cf's own user-level config andis never read by OpenCompany; the modal badge is a synthetic `cli-managed`marker OAuth row written by `_handlers.py`.-- **Services**: the `cf` CLI (declares `engines.node >= 22`, above OpenCompany's- 18+ floor — the only node with that requirement; `npm` on PATH for the install);+- **Services**: the `cf` CLI (declares `engines.node >= 22`, which bun ignores —+ it runs on bun with no Node on PATH; `bun` on PATH or `OPENCOMPANY_BUN_BIN`+ for the install);Cloudflare's dashboard OAuth for login (cf opens the browser itself andlistens on a fixed loopback port it owns - see `_handlers.py` for thesingle-flight guard and the never-kill rule).diff --git a/docs-internal/node-logic-flows/cli_integrations/vercelAction.md b/docs-internal/node-logic-flows/cli_integrations/vercelAction.mdindex a9713d11..833bb377 100644--- a/docs-internal/node-logic-flows/cli_integrations/vercelAction.md+++ b/docs-internal/node-logic-flows/cli_integrations/vercelAction.md@@ -117,8 +117,9 @@ flowchart TD- **Subprocess**: one `vercel` process per op. Binary resolution order:in-process cache, `shutil.which("vercel")` (a system install is PREFERRED,unlike cf / gh / gcloud), the shared-tree shim- `<DATA_DIR>/packages/node_modules/.bin/vercel(.cmd)`, then- `npm install [email protected] --prefix <DATA_DIR>/packages` in a worker+ `<DATA_DIR>/packages/node_modules/.bin/vercel(.exe)` (bun's shim; runs the+ CLI on bun), then `core.js_runtime.add_package("[email protected]")` — `bun add+ --cwd <DATA_DIR>/packages --no-progress [email protected]` — in a workerthread under a lock followed by a best-effort `vercel telemetry disable`.Every invocation appends `--global-config <DATA_DIR>/vercel/ --no-color`;env = server env plus `NO_COLOR=1` and `VERCEL_TOKEN` when a token isdiff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.mdindex 7215070d..6f0255e3 100644--- a/docs-internal/node_creation.md+++ b/docs-internal/node_creation.md@@ -188,9 +188,10 @@ background task awaits exit. Success gate is the same mtime-advance +sniff pair, against a **pinned config dir**: every invocation passes`--global-config <DATA_DIR>/vercel/` (the `CLAUDE_CONFIG_DIR`isolation idiom) so the auth-file path is deterministic across-platforms. The installer is `npm install <pkg> --prefix-<packages_dir()>` into the shared npm tree instead of a GitHub-release-download. Reference: [`server/nodes/vercel/`](../server/nodes/vercel/)+platforms. The installer is `core.js_runtime.add_package(<spec>)` —+`bun add --cwd <packages_dir()> <spec>` into the shared bun-managed+packages tree, the bin shim then running on bun — instead of a+GitHub-release download. Reference: [`server/nodes/vercel/`](../server/nodes/vercel/)+ [vercel_service.md](./vercel_service.md).**CLI-opens-the-browser variant (Cloudflare).** Some CLIs run the@@ -201,8 +202,8 @@ browser directly. The login handler then proxies NOTHING to the modalflips when the background completion broadcasts. Two hazards force thehandler's shape: concurrent logins collide on the fixed port(single-flight guard: repeat clicks return "already in progress"), and-on Windows killing the npm `.cmd` shim orphans the node child still-holding the port (the completion watcher never kills — the CLI's own+on Windows killing bun's `.exe` launcher shim orphans the child bun+process still holding the port (the completion watcher never kills — the CLI's ownlogin timeout ends it). Success gate = a CLI status probe that parsesJSON, never exit codes (`cf auth whoami` exits 0 in both auth states).When the CLI's OAuth grant is a fixed scope set (cf: 86 scopes, nodiff --git a/docs-internal/performance.md b/docs-internal/performance.mdindex e2b482c8..b634beb6 100644--- a/docs-internal/performance.md+++ b/docs-internal/performance.md@@ -93,7 +93,7 @@ corresponding `start.log` measurement.| 2026-05-04 | Lazy LangChain imports in `services/ai.py` (BaseMessage stays eager; everything else moves into local imports) | **~30 s** AIService cold import | `74b75b6` | inline plan || 2026-05-05 | `tsgo` for client `--noEmit` typecheck | ~6 s in CI gate | `0b45fb1` | [release_build_pipeline.md](release_build_pipeline.md) || 2026-05-05 | Vite `manualChunks` (split reactflow / radix / lobehub-icons / TanStack Query / markdown stack) + `target: 'es2022'` | main bundle 232 KB gz, 7 vendor chunks separately cached | `0b45fb1` | same |-| 2026-05-05 | Pre-bundle Node.js sidecar with esbuild (`tsx src/index.ts` → `node dist/index.js`) | ~500 ms-1 s of tsx startup per server boot | `0b45fb1` | same |+| 2026-05-05 | Pre-bundle the JS executor sidecar with esbuild (`tsx src/index.ts` → `node dist/index.js`); since superseded by `bun build --target=bun` → `bun dist/index.js` when bun became the only shipped JS runtime | ~500 ms-1 s of tsx startup per server boot | `0b45fb1` | same || 2026-05-05 | Scoped `python -O -m compileall` over project source dirs (excludes `.venv/`, `tests/`) | 3-5 s on warm-disk imports | `0b45fb1` | same || 2026-05-05 | Test coverage: 12 build-orchestrator + 32 config-contract tests under `cli/tests/` | n/a (regression guard) | `0f1e55e` | same || 2026-05-06 | Frontend WS reconnect → PartySocket; auth bootstrap → TanStack Query; CloudEvents envelope typed | **~20 s** (eliminates +12 s WS drop + +7 s reconnect cycle on cold start) | `e77215c` | inline plan |diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex 56ef9a4d..77d5224b 100644--- a/docs-internal/plugin_system.md+++ b/docs-internal/plugin_system.md@@ -588,7 +588,7 @@ per node type) — same pattern as every other folder.| Service factory for the DI container (`container.<name>()` resolves to a plugin-owned service) | `services.plugin.service_factories` | `register_service_factory(name, factory)` || Short Terminal-UI log tag for a logger-name prefix (only when the `nodes.<plugin>` auto-rule yields an unwanted tag) | `core.logging` | `register_log_source_tag(prefix, tag)` || Callback fired after a conversation durably saves (RFC-0002 Context live-view) | `services.agent_context.listeners` | `register_conversation_listener(listener)` — keyword-args only; a listener can never fail a save. |-| Long-lived process supervisor (WhatsApp bridge, Node sidecar, Discord gateway) | `services._supervisor` | `register_supervisor(supervisor)` — idempotent per `supervisor.label`; a label collision raises `ValueError`. |+| Long-lived process supervisor (WhatsApp bridge, the JS executor sidecar on bun, Discord gateway) | `services._supervisor` | `register_supervisor(supervisor)` — idempotent per `supervisor.label`; a label collision raises `ValueError`. |All accept idempotent re-imports (same callable / class for thesame key is a no-op; conflicts raise `ValueError`).diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.mdindex bd1e1cdd..56fc1b0a 100644--- a/docs-internal/release_build_pipeline.md+++ b/docs-internal/release_build_pipeline.md@@ -1,8 +1,8 @@# Release Build Pipeline-Compile-step plan for the npm distribution `@zeenie-ai/opencompany`. Goal: cut cold-start ~20s further on top of the lazy-LangChain fix already in v0.0.76, shrink the Vite main bundle below 200 KB gz, and drop the `tsx` interpreter cost from the Node.js sidecar.+Compile-step plan for the registry tarball `@zeenie-ai/opencompany` (published to npmjs and GitHub Packages, installed with `bun add -g`). Goal: cut cold-start ~20s further on top of the lazy-LangChain fix already in v0.0.76, shrink the Vite main bundle below 200 KB gz, and drop the `tsx` interpreter cost from the JS executor sidecar.-User scope (confirmed before this work): stay on npm distribution; **no** Nuitka/PyOxidizer standalone binary channel; optimize Vite output too; **skip** the plugin-walker (~11s) and service-status-refresh (~20s) hotspots — those are runtime concerns, not compile-time.+User scope (confirmed before this work): stay on the registry-tarball distribution; **no** Nuitka/PyOxidizer standalone binary channel; optimize Vite output too; **skip** the plugin-walker (~11s) and service-status-refresh (~20s) hotspots — those are runtime concerns, not compile-time.## Tooling@@ -10,7 +10,7 @@ User scope (confirmed before this work): stay on npm distribution; **no** Nuitka|---|---|---|| TypeScript type-check | `typescript@7` (the native Go compiler) at the **repo root** | **5.9× faster** on `--noEmit` — measured 2026-07-26 on this codebase, 3 warm runs each: **~820 ms** vs **~4830 ms** under `tsc` 5.9.3. Type-check only; Vite/esbuild keep producing the actual JS bundles. Lives in root `devDependencies`, exact-pinned, never ships to users. || Vite output | `manualChunks` + `target: 'es2022'` | Split heavy libs (reactflow, radix-ui, lobehub, react-markdown stack) so the main bundle no longer hits the 1500KB warning ceiling. ES2022 unlocks `findLast` / optional-chaining-assignment without polyfills (Chrome 94+, FF 93+, Safari 15.4+ — within React 19 / Tailwind 4 baseline). |-| Node sidecar | `esbuild` bundle to `dist/index.js`, run via `node` | Drops tsx interpreter startup (~500ms-1s every server boot). `--packages=external` keeps Express in `node_modules/` for patch flow. |+| JS executor sidecar | `bun build src/index.ts --target=bun --outfile=dist/index.js`, run via `bun dist/index.js` | Drops tsx interpreter startup (~500ms-1s every server boot). `--target=bun` yields a self-contained bundle with Express inlined — no `node_modules` at runtime, which is what lets the desktop bundle copy one file. (The first cut was an esbuild bundle with `--packages=external` run on Node; superseded when bun became the only shipped JavaScript runtime.) || Python | `python -m compileall -q -j 0 <project dirs>` + `[tool.uv] compile-bytecode = true` | Pre-compile bytecode. Implemented as step `[5/6]` in [`cli/commands/build.py`](../cli/commands/build.py) (`COMPILEALL_SOURCE_DIRS` constant lists the dirs); `server/pyproject.toml`'s `compile-bytecode = true` makes `uv sync` (step `[4/6]`) compile `.venv/` site-packages too. No `-O`: every runtime launches python without `-O`, and per PEP 488 a non-optimized interpreter only loads plain `.pyc` — the earlier `-O` invocation produced `.opt-1.pyc` that nothing ever loaded (fixed 2026-07-14; ~30-50s cold-start gain, see [performance.md](performance.md)). |## Package manager (bun)@@ -19,17 +19,21 @@ The dev workspace runs on **bun** (migrated from [email protected], 2026-08; pinnedvia `"packageManager": "[email protected]"` — CI's `oven-sh/setup-bun` reads that pin).Facts that are load-bearing, each verified during the migration:-- **Scope**: bun installs the workspace and runs scripts; **Node stays the- runtime** — the floor is Node 18+ (`engines.node`, `bin/cli.js`, the- installers); CI and the desktop bundle happen to use 22 LTS- (vite/vitest/eslint/the sidecar run on node via shebang — never- pass `--bun`). Everything npm-facing is deliberately untouched: end-user- `npm install -g @zeenie-ai/opencompany`, the backend's- `npm install --prefix <DATA_DIR>/packages/` shared tree, the sidecar's- user-package endpoints, and `npm publish --provenance` in release.yml.+- **Scope**: bun installs the workspace, runs scripts, and is **the only+ JavaScript runtime anything shipped needs** — the `company` shim+ (`bin/cli.js`, `#!/usr/bin/env bun`), the JS executor sidecar+ (`bun dist/index.js`), the plugin CLIs in the shared `<DATA_DIR>/packages/`+ tree (`server/core/js_runtime.py`, `bun add --cwd`), the sidecar's+ user-package endpoints (`bun add`), and `bun publish --access public` in+ release.yml. `engines` is `{"bun": ">=1.4.0"}`; end users install with+ `bun add -g @zeenie-ai/opencompany`; the desktop app bundles bun. Node is+ dev/CI-only: when present, bun runs vite / vitest / eslint on it via their+ node shebangs (never pass `--bun` — vitest and eslint have open bun-runtime+ bugs), and `company build` reports it as optional.- **Gate**: `scripts/preinstall.js` rejects non-bun installs in a sourcecheckout. It keys on `bunfig.toml` existing (committed, excluded from the- tarball by the `files` allowlist, so end-user npm installs never trigger it)+ tarball by the `files` allowlist, so end-user `bun add -g` installs never+ trigger it — a global add runs no lifecycle scripts anyway)and on `npm_config_user_agent` **starting with** `bun` — bun's UA is`bun/x.y.z npm/? node/...`, so a substring match on "npm" would misfire.- **Layout**: `bunfig.toml` pins `linker = "isolated"` — pnpm-style symlinked@@ -108,12 +112,14 @@ named `tsgo` — stopped publishing the day before and must not come back.Keep `sourcemap: analyze` (already correct), keep React Compiler config.-### 3. Node sidecar esbuild bundle+### 3. JS executor sidecar bundle (`bun build`)-- `server/nodejs/package.json` → add `esbuild` devDep; replace scripts:- - `"build": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --packages=external --outfile=dist/index.js"` (kept in sync with `engines.node` by `test_sidecar_engines_match_esbuild_target`)- - `"start": "node dist/index.js"` (was `tsx src/index.ts`)- - keep `"dev": "tsx watch src/index.ts"`+- `server/nodejs/package.json` scripts (no esbuild, no tsx — bun bundles and runs TypeScript natively):+ - `"build": "bun build src/index.ts --target=bun --outfile=dist/index.js"` — `--target=bun` inlines `express` into one self-contained file (locked flag-by-flag by `test_sidecar_build_script_carries_required_bun_build_flag`, which also asserts no `esbuild` / `--packages=external`)+ - `"start": "bun dist/index.js"` (was `tsx src/index.ts`, then `node dist/index.js`; `test_sidecar_start_runs_compiled_bundle_on_bun`)+ - `"dev": "bun --watch src/index.ts"` (`test_sidecar_dev_uses_bun_watch`)+ - `"engines": {"bun": ">=1.4.0"}` — no Node floor (`test_sidecar_engines_declare_bun_not_node`)+- At runtime `nodes/code/_runtime.py` spawns `[bun, dist/index.js]`, resolving bun through `server/core/js_runtime.py` (`OPENCOMPANY_BUN_BIN`, else PATH). Verified on bun 1.4.0 with Node stripped from PATH, including `node:vm` `runInContext` with the timeout.- `server/nodejs/.gitignore` → new file: `dist/`### 4. Python bytecode pre-compile@@ -139,7 +145,7 @@ Two halves (both required; see [performance.md](performance.md) for thedirs is the public `cli.commands.build.COMPILEALL_SOURCE_DIRS`constant — `scripts/install.js` mirrors it.-The npm tarball still excludes `__pycache__/` per `package.json` `files` (cross-Python-minor pyc fragility) — `compileall` runs on the user's machine via `company build` or `scripts/install.js` post-install.+The tarball still excludes `__pycache__/` per `package.json` `files` (cross-Python-minor pyc fragility) — `compileall` runs on the user's machine via `company build` or `scripts/install.js` (run by `company provision`: eagerly from the installer scripts, or on the first `company` command of a `bun add -g` install, which runs no lifecycle scripts).### 4a-bis. `.env` scaffolding with fresh secrets (step `[0/6]`)@@ -149,20 +155,20 @@ The npm tarball still excludes `__pycache__/` per `package.json` `files` (cross-- Step `[6/6]` runs `uv run python -m services.temporal._install`, which pooch-downloads the official `temporal` CLI into `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default). Pre-fetching at build time turns the ~114 MB download into a sub-second cache hit on first `company start`. The download uses an explicit `HTTPDownloader(timeout=300)` (per-socket-read timeout — slow links can finish; pooch's 30 s default aborted them). Fatality differs by entry point: `company build` keeps the step **fatal** (locked by `test_temporal_install_is_fatal_on_failure`), while npm postinstall (`scripts/install.js`) wraps it in a **non-fatal** try/catch because `TemporalServerRuntime._pre_spawn()` re-downloads lazily on first `company start`. The cache survives `company clean` (`packages` ∈ `_OPENCOMPANY_KEEP`), so clean+build cycles don't re-download.- **`company build` layers `.env.dev` first.** `build_command()` calls `cli.config.load_dev_overrides(root)` before the install steps, so the build's `DATA_DIR` matches what the runtime sees. Without it, a repo checkout's `company build` read `DATA_DIR=~/.opencompany` from `.env.template` and installed Temporal under user home, but `company dev` then read `DATA_DIR=.opencompany` from `.env.dev` and re-downloaded into `<repo>/.opencompany/` — a redundant ~114 MB fetch on every fresh clone.-- **Safe for global installs.** `.env.dev` is git-committed for contributors but is NOT in the npm `files` list, so an npm-distributed copy has no `.env.dev` — `load_dev_overrides` is a no-op and everything falls through to the `.env.template` default (`DATA_DIR=~/.opencompany`), matching `company start` / `company daemon`.+- **Safe for global installs.** `.env.dev` is git-committed for contributors but is NOT in the `files` list, so an installed (`bun add -g`) copy has no `.env.dev` — `load_dev_overrides` is a no-op and everything falls through to the `.env.template` default (`DATA_DIR=~/.opencompany`), matching `company start` / `company daemon`.### 5. Wire compileall into install.js (the sidecar bundle ships pre-built)- `scripts/install.js` → after `uv sync`:1. `uv run python -m compileall -q -j 0 <COMPILEALL_SOURCE_DIRS>` — same shape as build.py (no `-O`; locked in sync by `cli/tests/test_release_pipeline_config.py`)-- The sidecar is **not** rebuilt at install time: `company build` step `[3/6]` runs `bun run --filter opencompany-nodejs-executor build` before `npm pack`, and `server/nodejs/dist/index.js` rides inside the tarball (the `server/` entry in the root `files` list covers it). Likewise the client is only built by install.js when `client/dist/index.html` is missing.+- The sidecar is **not** rebuilt at install time: `company build` step `[3/6]` runs `bun run --filter opencompany-nodejs-executor build` before `bun pm pack` / `bun publish`, and `server/nodejs/dist/index.js` rides inside the tarball (the `server/` entry in the root `files` list covers it). Likewise the client is only built by install.js when `client/dist/index.html` is missing.-Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is deterministic).+Idempotent on re-runs (compileall only rewrites stale pyc; `bun build` is deterministic).### 6. Tarball verification-- `npm pack --dry-run` after the change. Confirm `server/nodejs/dist/index.js` is included (existing `server/` glob already covers it). Confirm no `__pycache__/` leakage.-- `server/uv.lock` is committed (since the desktop app) and ships in the tarball; `.npmignore` only hides `package-lock.json`. The desktop stage script also reads the `npm pack --dry-run --json` file list as its layout source of truth, so a change to the root `files` allowlist reaches the desktop bundle automatically.+- `bun pm pack --dry-run` after the change. Confirm `server/nodejs/dist/index.js` is included (existing `server/` glob already covers it). Confirm no `__pycache__/` leakage.+- `server/uv.lock` is committed (since the desktop app) and ships in the tarball; `.npmignore` only hides `package-lock.json` (a legacy artefact — the tree is `bun.lock`-only). The desktop stage script also reads the `bun pm pack --dry-run` file list as its layout source of truth, so a change to the root `files` allowlist reaches the desktop bundle automatically.## Critical files@@ -171,7 +177,7 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis| root `package.json` | + `typescript@7` devDep (exact-pinned), + root `typecheck` script || `client/package.json` | `typecheck` delegates to the root gate; keeps `typescript@^5.x` for typescript-eslint || `client/vite.config.js` | + manualChunks, target, lower warning |-| `server/nodejs/package.json` | + esbuild devDep, build script, change start |+| `server/nodejs/package.json` | `bun build --target=bun` build script, `bun dist/index.js` start, `bun --watch` dev, `engines.bun` (no esbuild / tsx deps) || `server/nodejs/.gitignore` | new — ignore `dist/` || `cli/commands/build.py` | + compileall step (`[5/6]`, plain `.pyc` — no `-O`), `COMPILEALL_SOURCE_DIRS` constant || `scripts/install.js` | + compileall call (sidecar bundle arrives pre-built in the tarball) |@@ -182,10 +188,10 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis1. `bun run --filter react-flow-client typecheck` → <5s, zero errors.2. `ANALYZE=1 bun run --filter react-flow-client build` → open `client/dist/stats.html`. Expect: no chunk trips the 850 KB `chunkSizeWarningLimit` (`vendor-icons` is the ~830 KB outlier it is sized for), main < 200 KB gz, `vendor-flow` split.-3. `cd server/nodejs && bun run build && NODEJS_EXECUTOR_PORT=<port> node dist/index.js` → starts on `NODEJS_EXECUTOR_PORT` (required env; no fallback literal) in <100ms.+3. `cd server/nodejs && bun run build && NODEJS_EXECUTOR_PORT=<port> bun dist/index.js` → starts on `NODEJS_EXECUTOR_PORT` (required env; no fallback literal) in <100ms; `GET /health` reports `runtime: "bun"`.4. `cd server && uv run python -m compileall -q -j 0 services` → plain `__pycache__/*.pyc` present (no `.opt-1.pyc` — nothing loads those).5. Cold-start: clean install + `company start > start.log 2>&1` → `Application startup complete` at ≤+50s (was +66.9s).-6. `npm pack --dry-run` → `server/nodejs/dist/index.js` included; no `__pycache__/`; tarball size ≤ v0.0.76.+6. `bun pm pack --dry-run` → `server/nodejs/dist/index.js` included; no `__pycache__/`; tarball size ≤ v0.0.76.7. Smoke: `company start` → load the app URL (`http://localhost:${PYTHON_BACKEND_PORT}`) → run "AI Assistant" example → agent responds.## Desktop installersdiff --git a/docs-internal/vercel_service.md b/docs-internal/vercel_service.mdindex 84ef6293..f4b6af52 100644--- a/docs-internal/vercel_service.md+++ b/docs-internal/vercel_service.md@@ -25,7 +25,7 @@ process rather than Stripe's two-step `--non-interactive` /| `vercel_action.py` | `VercelActionNode(ActionNode)`, `usable_as_tool=True`, `tool_name="vercel"`, gmail-style multi-`@Operation` dispatch on `operation: Literal["deploy","inspect","list","custom"]` || `_handlers.py` | `vercel_login` / `vercel_logout` / `vercel_status` WS handlers; device-flow driver; marker-token write + `broadcast_credential_event` || `_service.py` | Config-dir pinning, `is_logged_in()` sniff, `global_argv()` / `vercel_env()` builders, ANSI-strip + login-URL/code parsers |-| `_install.py` | `ensure_vercel_cli()` — pinned `npm install vercel@<X>` into the shared npm tree (`<DATA_DIR>/packages/`); system PATH preferred; one-shot `telemetry disable` post-install |+| `_install.py` | `ensure_vercel_cli()` — pinned `bun add vercel@<X>` (`core.js_runtime.add_package`) into the shared packages tree (`<DATA_DIR>/packages/`), run on bun (no Node or npm involved; vercel 54.21.1 verified on bun with no Node on PATH); system PATH preferred; one-shot `telemetry disable` post-install || `_credentials.py` | `VercelCredential(Credential)` thin marker (`auth="custom"`); `resolve()` returns the optional `vercel_token` api-key row || `meta.json` | Node color. **No co-located `icon.svg`** — the icon is the official brand glyph via `visuals.json: {"vercelAction": {"icon": "lobehub:Vercel", "skill": "vercel-skill"}}`; a folder SVG would silently override it (first hit in `get_plugin_icon_path`), and its absence is locked by `test_vercel_plugin.py::test_plugin_folder_assets`. A lowercase `"vercel"` alias entry (icon + color) also exists because the skill's `allowed-tools` token is the tool name `vercel`, not the node type's snake_case — without the alias, `skill_loader._parse_skill_metadata` resolves an empty icon/color and the Master Skill row renders blank (the naming-contract escape hatch documented in plugin_system.md). |diff --git a/docs-internal/workflow-schema.md b/docs-internal/workflow-schema.mdindex e35bdf68..799cac4f 100644--- a/docs-internal/workflow-schema.md+++ b/docs-internal/workflow-schema.md@@ -224,8 +224,8 @@ Unified multi-platform messaging (WhatsApp, Telegram, Discord, Slack, SMS, Email### Code Nodes (4 nodes)All dual-purpose (workflow node + AI tool):- `pythonExecutor` - Python code execution (in-process)-- `javascriptExecutor` - JavaScript execution via persistent Node.js server-- `typescriptExecutor` - TypeScript execution via persistent Node.js server (tsx)+- `javascriptExecutor` - JavaScript execution via the persistent JS executor sidecar (Express on bun; `server/nodejs/`)+- `typescriptExecutor` - TypeScript execution via the same sidecar (bun transpiles TypeScript natively; no tsx)- `montyExecutor` - Sandboxed Python via the Monty interpreter### Chat Nodes (2 nodes)