Skip to content

Self-improving AI Employees for everyone

docs: record boot-delay fixes and measured cold-start numbers

trohitg15640466cc1f
diff --git a/CLAUDE.md b/CLAUDE.md
index 4858b0be..a212e0d8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,8 +31,8 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[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. |
| **[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`. |
| **[CI/CD Pipeline](./docs-internal/ci_cd.md)** | GitHub Actions workflows, predeploy validation, release publishing, and composite setup action |
-| **[Performance](./docs-internal/performance.md)** | Cold-start measurements (Application startup complete 2.90 s warm, first WS connect 8.29 s) + per-phase timeline + optimisation history (lazy LangChain imports, esbuild sidecar bundle, scoped `compileall`, PartySocket reconnect, TanStack Query auth bootstrap, `manualChunks`) + bottleneck inventory + reproduction commands + anti-patterns to never reintroduce. Pairs with the build-time pipeline doc below. |
-| **[Release Build Pipeline](./docs-internal/release_build_pipeline.md)** | npm-distribution build pipeline: `tsgo` for type-check (5× faster than tsc), Vite `manualChunks` + `target: 'es2022'`, esbuild Node.js sidecar bundle (drops `tsx` interpreter cost), `python -O -m compileall` for project-source bytecode (excludes `.venv/`, `tests/`). Single source of truth for the bytecode-compile path list: `cli.commands.build.COMPILEALL_SOURCE_DIRS`. |
+| **[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: `tsgo` for type-check (5× faster than tsc), 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`. |
| **[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/ROADMAP.md)** | Implementation status, completed phases, and pending features |
@@ -138,13 +138,16 @@ server/services/
│ ├── triggers.py # Generic event-trigger handler
│ ├── todo.py # writeTodos execution shim (used by every agent)
│ └── __init__.py # Docstring only (google_auth.py retired into nodes/google/_auth_helper.py)
-├── llm/ # Native LLM provider SDKs (replaces LangChain for chat)
+├── llm/ # Native LLM provider SDKs (chat path; the agent loop in ai.py is still LangChain)
│ ├── __init__.py # Public API exports
│ ├── protocol.py # ThinkingConfig, Message, LLMResponse, LLMProvider Protocol
│ ├── config.py # ProviderConfig, resolve_max_tokens, resolve_temperature
│ ├── factory.py # create_provider() lazy-import factory
+│ ├── registry.py # ProviderSpec + register_provider — sdk_exception_refs are LAZY "module:Class" strings resolved via pkgutil.resolve_name at except/read time; NEVER import an SDK at registration (locked by tests/llm/test_lazy_sdk_imports.py)
+│ ├── unifier.py # ChatUnifier facade — routes chat/fetch_models, translates typed SDK errors → NodeUserError, applies incompatible_models filter
+│ ├── vertex.py # Vertex / Agent-Platform key handling
│ ├── messages.py # filter_empty_messages, is_valid_message_content
-│ └── providers/ # Per-provider implementations
+│ └── providers/ # Per-provider implementations (+ _compat.py for the 8 OpenAI-compatible providers)
│ ├── anthropic.py # AnthropicProvider (anthropic SDK)
│ ├── openai.py # OpenAIProvider (openai SDK)
│ ├── gemini.py # GeminiProvider (google-genai SDK)
@@ -690,12 +693,13 @@ Workflows execute via Temporal for durability and horizontal scaling, gated by `
### CLI Commands (after the global install)
```bash
-company start # Start all services
-company stop # Stop all services
-company build # Build for production
-company clean # Clean build artifacts
-company docker:up # Start with Docker
-company help # Show all commands
+company start # Start all services (production mode)
+company dev # Start all services in dev mode (Vite HMR)
+company dev --force # ...forcing Vite to re-bundle deps (recovers "Outdated Optimize Dep"; sets VITE_FORCE -> optimizeDeps.force — the dep cache is otherwise preserved across boots)
+company stop # Stop all services
+company build # Build for production
+company clean # Clean build artifacts
+company help # Show all commands
```
### npm Scripts
diff --git a/docs-internal/litellm_router_migration_rfc.md b/docs-internal/litellm_router_migration_rfc.md
index 3dd21bbc..77750027 100644
--- a/docs-internal/litellm_router_migration_rfc.md
+++ b/docs-internal/litellm_router_migration_rfc.md
@@ -332,7 +332,9 @@ credential lookup — plus ~420 LOC of contract tests that pass unchanged if it
NodeUserError-on-unknown-provider). Under the flag, registration becomes one
data-driven loop over `LLM_DEFAULTS["providers"]` registering
`ProviderSpec(name=n, factory=partial(LiteLLMAdapter, provider=n),
- sdk_exception_types=(openai.OpenAIError,), client_kwargs={})`.
+ sdk_exception_refs=("openai:OpenAIError",), client_kwargs={})`.
+ (Since 2026-07-14 the spec takes lazy `"module:Class"` refs — the
+ resolved-classes surface remains the `sdk_exception_types` property.)
- **`unifier.py` changes ~15 lines**: a flag branch in `_build_client`
(unifier.py:114) plus `fetch_models` delegation to the retained HTTP lister
(section 6.7). Public signatures unchanged — `test_wiring.py`,
@@ -442,8 +444,10 @@ def _litellm():
```
Nothing at `services.llm` import time may touch litellm — `core/container.py` imports
-`services.llm` during container boot. `sdk_exception_types=(openai.OpenAIError,)`
-deliberately avoids importing litellm at registration. New guard test
+`services.llm` during container boot. `sdk_exception_refs=("openai:OpenAIError",)`
+deliberately avoids importing litellm (or any SDK) at registration — the same lazy-ref
+contract `tests/llm/test_lazy_sdk_imports.py` already enforces for openai/anthropic/
+google-genai. New guard test
`tests/llm/test_lazy_litellm.py`: import `services.llm`, construct `ChatUnifier`, assert
`"litellm" not in sys.modules`. Phase 0 asserts the three module-setting attribute names
on the pinned version so a rename fails in CI, not production.
diff --git a/docs-internal/performance.md b/docs-internal/performance.md
index c67baf3e..666e071f 100644
--- a/docs-internal/performance.md
+++ b/docs-internal/performance.md
@@ -18,13 +18,21 @@ warm OS file cache, with bytecode pre-compile applied:
| First WebSocket client connected | **8.29 s** | same |
| Status broadcasters fully settled | **12.27 s** | same |
| AIService import (warm) | **703 ms** | same — was ~31 s on v0.0.75 |
+| Application startup complete (cold, post-`company clean` first launch) | **21.5 s** | `cold.txt` 18:44 (2026-07-14, post boot-delay fixes; was **71 s** the same day pre-fix) |
+| LLM provider registration (all 12, cold) | **17 ms** | same — was 44.6 s pre-fix (eager SDK imports) |
| Vite production build | **~16 s** | last `vite build` run |
| Vite main bundle | **234 KB gz** | `client/dist/assets/index-*.js` |
-The cold-disk first launch on the same code is ~2× slower because the
-Python interpreter regenerates `.pyc` files on the fly. Run
-`company build` once to pre-compile (see ["Pre-compile Python bytecode"]
-below) and subsequent launches hit the warm number.
+The cold-disk first launch on the same code is slower because Windows
+Defender first-touch-scans freshly written files (the rebuilt `.venv`
+is ~389 MB / 18,300 files) and fresh DBs/salt are created. Before the
+2026-07-14 boot-delay fixes a post-`company clean` boot measured
+**71 s** (5.2× the warm boot / 24× the baseline; `cold.txt` 12:55);
+after the fixes the same cycle measures **21.5 s** (`cold.txt` 18:44).
+The remaining cold gap over the 2.90 s warm number is Defender/disk
+I/O plus the items in "Open follow-ups" — not bytecode compilation,
+which now happens at build time (`[tool.uv] compile-bytecode = true`
++ the `-O`-less compileall step below).
## Optimisation history
@@ -40,6 +48,7 @@ corresponding `start.log` measurement.
| 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 |
+| 2026-07-14 | Boot-delay fix set: (1) lazy `"module:Class"` SDK exception refs on `ProviderSpec` (no SDK import at provider registration); (2) `[tool.uv] compile-bytecode = true` + `-O`-less compileall (bytecode compiled at build for the interpreter that actually runs); (3) Vite dep cache preserved across `company dev` boots (`--force` → `VITE_FORCE` → `optimizeDeps.force`) + `optimizeDeps.include` for heavy lazily-reached deps; (4) temporalio build-id hash pre-warmed off-loop via `asyncio.to_thread` | **~50 s** on post-clean cold boot (71 s → 21.5 s); ~7 s on warm boot (AIService import back to baseline); ~2 min of Vite re-optimize per warm dev boot; event loop no longer frozen ~3 s during Temporal worker start | this change | plan file `analyze-the-log-txt-file-eager-locket.md`; log evidence `log.txt` / `cold.txt` (2026-07-14) |
## Where launch time is spent today (post `e77215c`, warm cache)
@@ -70,6 +79,31 @@ T+8.29 — First WebSocket client connected ◀ UI-interactive point
T+12.27 — Status broadcasters settled ◀ "everything green"
```
+## Cold post-clean boot (2026-07-14, `cold.txt` 18:44, post-fix)
+
+First launch after `company clean` → `company build` (fresh `.venv`,
+fresh DATA_DIR: new salt + example import). Segment deltas vs the
+same-day pre-fix cold boot in parentheses:
+
+```
+T+0.00 — port-free begin
+T+2.6 — container: core imports done (was 10.2 s → 1.2 s segment)
+T+3.2 — AIService imported, 12 providers in 17 ms (was 44.6 s segment)
+T+8.7 — 152 node plugins loaded (was 10.8 s → 4.7 s segment)
+T+11.9 — Lifespan startup begin (3.2 s gap: CLI-agent MCP mount)
+T+21.5 — Application startup complete (lifespan 9.6 s: fresh-DB init 4.4 s,
+ salt/PBKDF2 + encryption ~3 s — see follow-ups)
+T+22.2 — ready on port 3010 (pre-fix: probe timed out at 30 s,
+ line never printed)
+T+27 — Temporal worker registered; worker_start span 7.6 s wall but OFF-LOOP:
+ broadcaster refreshes + WhatsApp RPC handshake interleave mid-hash
+ (pre-fix: 3.1 s synchronous loop freeze)
+T+44 — browser connects once, full init burst answered in <0.6 s
+ (pre-fix: insta-disconnect + reload churn + 8 s starved gap;
+ ~40 s here is post-clean one-time Vite dep optimize + human open)
+T+51 — example workflows imported (still inline — see follow-ups)
+```
+
## The remaining +5 s gap (HTTP-ready → first WS connect)
`ready on port 3010` at +3.17 s, first WS connect at +8.29 s. Backend
@@ -110,7 +144,7 @@ optimisations above; sum is what hurts.
| # | Bottleneck | Cost | Class | Notes |
|---|---|---|---|---|
-| 1 | Plugin walker on lifespan (137 modules under `server/nodes/`) | ~0.8 s | Backend | Out-of-scope per user direction; `_HANDLER_REGISTRY` populates via `BaseNode.__init_subclass__`. Lazy-load would shave another ~0.5 s. |
+| 1 | Plugin walker at import time (152 modules under `server/nodes/`; ~2 s warm / ~4.7 s cold, dominated by `nodes/google`'s eager `googleapiclient` import) | ~2 s | Backend | `_HANDLER_REGISTRY` populates via `BaseNode.__init_subclass__` at import. Lazy `googleapiclient` is the cheap win (see follow-ups); full lazy-loading of the walker is the big-blast-radius option. |
| 2 | TanStack Query auth bootstrap retry window | ~3-5 s | Frontend | See "remaining +5 s gap" above. |
| 3 | LangChain ecosystem imports inside `services/ai.py` | ~0.7 s | Backend | Already lazied; further wins require refactoring `AgentState`'s `Annotated[Sequence[BaseMessage], ...]` to defer `BaseMessage` resolution. |
| 4 | Status-broadcaster refresh (`refresh_all_services`, 2.6 s) | ~2.6 s | Backend | Runs after `Application startup complete`, doesn't block server-ready. WhatsApp + Telegram are the long tails. |
@@ -118,25 +152,38 @@ optimisations above; sum is what hurts.
## Pre-compile Python bytecode
-The build-pipeline step that produces `.opt-1.pyc` files for the
-project's own modules (excludes `.venv/`, `tests/`):
+Two halves, both required — measured on a post-`company clean` cold
+boot (2026-07-14, `cold.txt`): without them the boot hit **71 s** to
+"Application startup complete" (5.2× the warm boot, 24× the 2.90 s
+baseline), not the "~2×" this doc previously claimed.
+
+**1. Site-packages** — `server/pyproject.toml` sets
+`[tool.uv] compile-bytecode = true` so `uv sync` compiles the ~9,700
+dependency `.py` files at install time. uv's default is **false**;
+without it every dependency compiles lazily on the FIRST import after
+a fresh sync — tens of seconds on Windows where Defender also
+first-touch-scans each newly written file.
+
+**2. Project source** — the build-pipeline step (excludes `.venv/`,
+`tests/`):
```bash
cd server
-uv run python -O -m compileall -q -j 0 services core nodes routers models middleware main.py constants.py
+uv run python -m compileall -q -j 0 services core nodes routers models middleware main.py constants.py
```
+No `-O`: every runtime launches python without `-O`, and per PEP 488 a
+non-optimized interpreter only loads plain `.pyc` — the previous `-O`
+invocation produced `.opt-1.pyc` files that nothing ever loaded.
+
`company build` runs this as step `[5/6]`. The path list lives in
[cli/commands/build.py](../cli/commands/build.py)'s
`COMPILEALL_SOURCE_DIRS` constant; install.js mirrors the same list.
Tests at
[cli/tests/test_build_compile_pipeline.py](../cli/tests/test_build_compile_pipeline.py)
-lock the contract.
-
-Without this step on first launch, every `.py` import compiles
-on-the-fly and the first launch is ~2× slower. Repeated launches use
-the OS file cache anyway, so the steady-state difference is small —
-but the user-visible "first run after `git pull`" is dominated by it.
+and
+[cli/tests/test_release_pipeline_config.py](../cli/tests/test_release_pipeline_config.py)
+lock the contract (including the `compile-bytecode = true` setting).
## How to reproduce a measurement
@@ -182,6 +229,9 @@ formula bound check across 100 × MAX_ATTEMPTS draws.
These were observed and fixed; the lessons are durable.
- **Eager `from langchain_openai import ChatOpenAI` at module top.** Cost ~21 s cold on Windows because it transitively pulls openai SDK + tiktoken + httpx wrappers. With `from __future__ import annotations` already in place, all type hints become strings; no eager import was structurally required. Lazy via per-function local imports + a small `BaseMessage`-only eager hold-out.
+- **Eager SDK import at LLM provider registration, just to reference typed exception classes.** The `services/llm/providers/*` registration blocks did `import anthropic` / `import openai` / `from google.genai import errors` at module bottom solely to populate `ProviderSpec.sdk_exception_types` — re-creating the anti-pattern above through the raw SDKs (~7.6 s warm / ~45 s cold for the AIService import vs the 703 ms baseline; google.genai alone was ~4 s warm / ~15 s cold). Fixed with lazy `"module:ClassName"` refs (`ProviderSpec.sdk_exception_refs`) resolved via `pkgutil.resolve_name` at except/read time — by then the provider factory has already imported the SDK, so resolution is a `sys.modules` cache hit. Locked by [server/tests/llm/test_lazy_sdk_imports.py](../server/tests/llm/test_lazy_sdk_imports.py) (subprocess purity probe). When adding a provider: pass a string ref, never import the SDK at module level.
+- **Unconditional `client/node_modules/.vite` wipe on every `company dev`.** Forced a full esbuild dependency re-optimization (1-2 minutes on Windows) on every first page load. Vite self-invalidates the dep cache via lockfile/config/NODE_ENV hashes in `.vite/deps/_metadata.json`; the wipe was pure waste on a stable lockfile. Replaced with `company dev --force` → `VITE_FORCE=1` → `optimizeDeps.force` (Vite's own re-bundle mechanism), plus `optimizeDeps.include` for the heavy lazily-reached deps so late discovery can't trigger the mid-session re-optimization behind the "Outdated Optimize Dep" 504 (vitejs/vite#14284).
+- **Synchronous temporalio `Worker()` construction on the event loop.** The constructor derives a default build id by MD5-hashing the bytecode of every module in `sys.modules` (disk reads included) — ~3.1 s at our module count, freezing the loop and inflating concurrent boot work (`broadcaster.refresh_whatsapp` measured 4.2 s vs its ~0.4 s siblings). The value is memoized SDK-globally, so `TemporalWorkerManager.start()` pre-warms it once via `asyncio.to_thread(load_default_build_id)` before constructing the manager worker; all pool workers then construct cheaply. Any new long synchronous call in an async startup path should get the same `to_thread` treatment.
- **Recursive `setTimeout` retry chain in `useEffect` without `AbortController`.** Survived unmount, leaked timers, called `setState` on stale closures. The React docs explicitly flag this in [https://react.dev/reference/react/useEffect](https://react.dev/reference/react/useEffect). Replaced with TanStack Query's `signal`-aware `queryFn`.
- **Flat `setTimeout(connect, 3000)` reconnect loop.** No exponential backoff, no jitter, no `code === 1000` honouring, no message replay. Replaced with PartySocket — see [client/src/contexts/WebSocketContext.tsx](../client/src/contexts/WebSocketContext.tsx).
- **`if (event.code !== 1000)` magic numbers** scattered through the WS lifecycle. Replaced with `WS_CLOSE.NORMAL_CLOSURE` from [connectionConfig.ts](../client/src/lib/connectionConfig.ts) per RFC 6455 §7.4.1.
@@ -193,9 +243,13 @@ Tracked but explicitly **not** in any active plan.
| Item | Estimated saving | Notes |
|---|---|---|
+| Lazy `googleapiclient` import in `nodes/google` (`_option_loaders.py` / `_oauth.py` / `_base.py` import `googleapiclient.discovery` at module top) | ~2-4 s of the cold plugin walk | googleapiclient is 98 MB / 612 files on disk; now the single biggest import cost left on the cold boot path. Move `from googleapiclient.discovery import build` into function bodies (same idiom as `services/plugin/credential.py`). `nodes/telegram/_service.py`'s top-level `telegram` imports are the smaller sibling. |
+| Defer first-launch example import off the workflows REST request | ~8-10 s of first-launch first paint | `routers/database.py:get_all_workflows` awaits `import_examples_for_user` inline, holding the HTTP response. Move to a lifespan background task (pattern: `_refresh_registry` / `_refresh_all_services` / Temporal init in `main.py`) + emit `workflow_lifecycle("imported")` per example so the sidebar refreshes. Secondary: negative cache in `AuthService.has_valid_key` (validation does one credentials-DB read per declared credential per node). |
+| Cold-boot lifespan I/O (9.6 s measured 2026-07-14 vs 1.5 s pre-fix cold boot) | unclear — needs a re-run | Fresh-DB creation 4.4 s + salt/PBKDF2 + encryption ~3 s under Defender/disk contention now that the whole boot compresses into ~20 s. May be noise; measure before optimising. |
| Plugin walker lazy-loading | ~0.5-0.8 s on server-ready | Would need to defer registration until first NodeSpec request rather than at module-import time. Touches every `BaseNode` subclass — biggest blast radius of the candidates. |
| `BaseMessage`-free agent loop (drop the only eager `langchain_core.messages` import in `services/ai.py`) | ~0.3-0.5 s | Native-SDK provider classes already use their own message types; `_run_agent_loop` could be retyped against them and the eager import dropped. |
| `+5 s` HTTP-ready → first-WS-connect gap | up to 5 s | Diagnostics needed (see "remaining +5 s gap"). May reveal nothing actionable. |
+| Supervisor backend `ready_timeout` (default 30 s, shortest of the three services) | cosmetic | The probe is inert (one-shot, no restart/gating) but a >30 s boot prints an alarming "timed out waiting for port 3010" and skips the ready line. Post-fix boots fit the window; revisit only if cold boots regress past 30 s. |
| Standalone Nuitka / PyOxidizer release binary | full Python interpreter init (~0.4 s) + `.pyc` regeneration on cold disk | User explicitly declined when scoping the build pipeline; revisit if "ship a single binary" becomes a product requirement. |
## References
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index 1d4c10ee..76b8fe32 100644
--- a/docs-internal/release_build_pipeline.md
+++ b/docs-internal/release_build_pipeline.md
@@ -11,7 +11,7 @@ User scope (confirmed before this work): stay on npm distribution; **no** Nuitka
| TypeScript type-check | `@typescript/native-preview` (tsgo) | Microsoft's Go-port of `tsc`, ~10x faster on `--noEmit`. Type-check only — JS emit in tsgo is still preview. Vite/esbuild keep producing the actual JS bundles. Stays in `devDependencies`, 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. |
-| Python | `python -O -m compileall -q -j 0 server/` | Pre-compile bytecode. Implemented as step `[5/6]` in [`cli/commands/build.py`](../cli/commands/build.py) (`COMPILEALL_SOURCE_DIRS` constant lists the dirs). ~5-10s cold-start gain. `-O` strips asserts + `__debug__` branches. |
+| 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)). |
## Implementation steps
@@ -48,15 +48,26 @@ Keep `sourcemap: analyze` (already correct), keep React Compiler config.
### 4. Python bytecode pre-compile
-- [`cli/commands/build.py`](../cli/commands/build.py) → after `uv sync` (step `[4/6]`), step `[5/6]` runs:
+Two halves (both required; see [performance.md](performance.md) for the
+2026-07-14 cold-boot measurements that motivated the split):
+
+- `server/pyproject.toml` → `[tool.uv] compile-bytecode = true` makes
+ `uv sync` (step `[4/6]`) compile all `.venv/` site-packages at install
+ time. uv's default is **false** — without this, every dependency `.py`
+ compiles lazily on the first import after a fresh sync.
+- [`cli/commands/build.py`](../cli/commands/build.py) → step `[5/6]`
+ covers the project's own source:
```python
run(
- uv_run("python", "-O", "-m", "compileall", "-q", "-j", "0", *COMPILEALL_SOURCE_DIRS),
+ uv_run("python", "-m", "compileall", "-q", "-j", "0", *COMPILEALL_SOURCE_DIRS),
cwd=server_cwd,
check=False, # missing pyc is non-fatal — runtime regenerates as needed
)
```
- The list of source dirs is the public `cli.commands.build.COMPILEALL_SOURCE_DIRS` constant — `scripts/install.js` mirrors it.
+ No `-O`: runtimes never launch python with `-O`, so plain `.pyc` is the
+ only bytecode flavor that gets loaded (PEP 488). The list of source
+ dirs 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.
@@ -70,7 +81,7 @@ The npm tarball still excludes `__pycache__/` per `package.json` `files` (cross-
- `scripts/install.js` → after `uv sync`:
1. `npm --prefix server/nodejs run build` — produce `dist/index.js`
- 2. `python -O -m compileall -q -j 0 server/` — same as build.py
+ 2. `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`)
Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is deterministic).
@@ -86,8 +97,9 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis
| `client/vite.config.js` | + manualChunks, target, lower warning |
| `server/nodejs/package.json` | + esbuild devDep, build script, change start |
| `server/nodejs/.gitignore` | new — ignore `dist/` |
-| `cli/commands/build.py` | + compileall step (`[5/6]`), `COMPILEALL_SOURCE_DIRS` constant |
+| `cli/commands/build.py` | + compileall step (`[5/6]`, plain `.pyc` — no `-O`), `COMPILEALL_SOURCE_DIRS` constant |
| `scripts/install.js` | + sidecar bundle + compileall calls |
+| `server/pyproject.toml` | `[tool.uv] compile-bytecode = true` — `uv sync` compiles `.venv/` site-packages |
| `.github/workflows/release.yml` | + typecheck gate before build |
## Verification
@@ -95,7 +107,7 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis
1. `pnpm --filter react-flow-client run typecheck` → <5s, zero errors.
2. `ANALYZE=1 pnpm --filter react-flow-client run build` → open `client/dist/stats.html`. Expect: no chunk above 600 KB gz, main < 200 KB gz, `vendor-flow` split.
3. `cd server/nodejs && npm run build && node dist/index.js` → starts on :3020 in <100ms.
-4. `cd server && uv run python -O -m compileall -q -j 0 .` → `__pycache__/*.opt-1.pyc` present.
+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.
7. Smoke: `company start` → load http://localhost:3000 → run "AI Assistant" example → agent responds.