Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
test+perf: unblock 1,142 tests + add performance reference doc
trohitg50ef5bd26418
diff --git a/client/src/components/__tests__/CredentialsModal.test.tsx b/client/src/components/__tests__/CredentialsModal.test.tsxindex 52b164ad..4fcb6a94 100644--- a/client/src/components/__tests__/CredentialsModal.test.tsx+++ b/client/src/components/__tests__/CredentialsModal.test.tsx@@ -78,51 +78,55 @@ const wsMock = {// status getters aren't actually used here -- they're consumed via the dedicated hooks below};-vi.mock('../../contexts/WebSocketContext', async () => {- const actual = await vi.importActual<any>('../../contexts/WebSocketContext');- return {- ...actual,- useWebSocket: () => wsMock,- useWhatsAppStatus: () => ({- connected: false,- has_session: false,- running: false,- pairing: false,- device_id: null,- connected_phone: null,- qr: null,- }),- useAndroidStatus: () => ({- connected: false,- paired: false,- device_id: null,- device_name: null,- connected_devices: [],- qr_data: null,- session_token: null,- }),- useTwitterStatus: () => ({- connected: false,- username: null,- user_id: null,- name: null,- profile_image_url: null,- }),- useGoogleStatus: () => ({- connected: false,- email: null,- name: null,- profile_image_url: null,- }),- useTelegramStatus: () => ({- connected: false,- bot_username: null,- bot_name: null,- bot_id: null,- owner_chat_id: null,- }),- };-});+// Replace the entire WebSocketContext module with stub exports. The+// `vi.importActual` + spread pattern was previously used here but failed+// to override `useWebSocket` reliably under React 19 — the real+// implementation's `useContext(WebSocketContext)` check fired against the+// undefined provider, throwing the "must be used within a WebSocketProvider"+// error before the mocked override could intercept. The full-replace style+// matches what useApiKeys.test.ts does and works in both vitest 1 and 2.+vi.mock('../../contexts/WebSocketContext', () => ({+ useWebSocket: () => wsMock,+ useWhatsAppStatus: () => ({+ connected: false,+ has_session: false,+ running: false,+ pairing: false,+ device_id: null,+ connected_phone: null,+ qr: null,+ }),+ useAndroidStatus: () => ({+ connected: false,+ paired: false,+ device_id: null,+ device_name: null,+ connected_devices: [],+ qr_data: null,+ session_token: null,+ }),+ useTwitterStatus: () => ({+ connected: false,+ username: null,+ user_id: null,+ name: null,+ profile_image_url: null,+ }),+ useGoogleStatus: () => ({+ connected: false,+ email: null,+ name: null,+ profile_image_url: null,+ }),+ useTelegramStatus: () => ({+ connected: false,+ bot_username: null,+ bot_name: null,+ bot_id: null,+ owner_chat_id: null,+ }),+ useNodeStatus: () => ({ status: 'idle', data: {} }),+}));vi.mock('../../hooks/useWhatsApp', () => ({useWhatsApp: () => ({diff --git a/client/src/components/parameterPanel/__tests__/InputSection.test.tsx b/client/src/components/parameterPanel/__tests__/InputSection.test.tsxindex 4f6fa4d0..571a772b 100644--- a/client/src/components/parameterPanel/__tests__/InputSection.test.tsx+++ b/client/src/components/parameterPanel/__tests__/InputSection.test.tsx@@ -16,8 +16,12 @@ import { render, screen, waitFor } from '@testing-library/react';// --- Mocks -----------------------------------------------------------------const storeState: { currentWorkflow: any } = { currentWorkflow: null };+// Threads the slice selector so `useAppStore((s) => s.currentWorkflow)`+// returns the right slice. A no-arg `useAppStore()` returns the whole+// state for legacy whole-store consumers.vi.mock('../../../store/useAppStore', () => ({- useAppStore: () => storeState,+ useAppStore: <T,>(selector?: (state: typeof storeState) => T): T | typeof storeState =>+ selector ? selector(storeState) : storeState,}));const wsMock = {diff --git a/client/src/hooks/__tests__/useDragVariable.test.ts b/client/src/hooks/__tests__/useDragVariable.test.tsindex fda966cd..f5df73e6 100644--- a/client/src/hooks/__tests__/useDragVariable.test.ts+++ b/client/src/hooks/__tests__/useDragVariable.test.ts@@ -18,8 +18,14 @@ const storeState: { currentWorkflow: any } = {currentWorkflow: null,};+// `useAppStore` is consumed via the documented Zustand slice-selector+// pattern: `useAppStore((s) => s.currentWorkflow)`. The mock has to+// thread the selector through so it returns the right slice — calling+// `useAppStore()` without a selector inside the hook would have given us+// the whole store object and `currentWorkflow.nodes` would be undefined.vi.mock('../../store/useAppStore', () => ({- useAppStore: () => storeState,+ useAppStore: <T,>(selector?: (state: typeof storeState) => T): T | typeof storeState =>+ selector ? selector(storeState) : storeState,}));// nodeDefinitions/ was deleted in commit fc10fd3 — the hook nowdiff --git a/docs-internal/performance.md b/docs-internal/performance.mdnew file mode 100644index 00000000..16203f54--- /dev/null+++ b/docs-internal/performance.md@@ -0,0 +1,209 @@+# Performance — Cold-Start, Bundle, Runtime Latency++Living record of MachinaOs's performance posture: where launch time is+spent, what each optimisation cost / saved, and how to reproduce the+measurements. Update this file when you ship a perf-affecting change+or take a new measurement; numbers without timestamps and a commit+reference rot fast.++## Headline numbers (current baseline)++Measured on Windows, dev mode (`pnpm run dev` → `python -m machina dev`),+warm OS file cache, with bytecode pre-compile applied:++| Metric | Value | Source |+|---|---|---|+| Application startup complete | **2.90 s** | `start.log` 14:38 (post-`e77215c`, May 6 2026) |+| HTTP `ready on port 3010` | **3.17 s** | same |+| 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 |+| 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+`machina build` once to pre-compile (see ["Pre-compile Python bytecode"]+below) and subsequent launches hit the warm number.++## Optimisation history++In chronological order. Each row links to the commit and the+corresponding `start.log` measurement.++| Date | Change | Saved | Commit | Plan / RFC |+|---|---|---|---|---|+| 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 (5× faster than `tsc`) | ~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 | 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 `machina/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 |++## Where launch time is spent today (post `e77215c`, warm cache)++```+T+0.00 — port-free begin+ ├── client / server / temporal processes spawn (0.06 s)+ ├── Vite dev ready (0.90 s) ────── (frontend cheap)+ └── Server import phase+ ├── FastAPI base imports (0.27 s)+ ├── DI container (0.42 s)+ ├── Core service imports (0.36 s)+ ├── AIService import (0.70 s) ← lazy LangChain payoff+ ├── Routers + plugin walker (0.84 s, 137 plugins)+ └── All imports complete (1.98 s)+T+2.25 — Lifespan startup+ ├── DB + cache (0.04 s)+ ├── Credentials + encryption (0.10 s)+ ├── Compaction service (0.12 s)+ └── All services initialized (2.63 s)+T+2.90 — Application startup complete ◀ HTTP-ready point+T+3.17 — `ready on port 3010` (uvicorn accepting)+T+3.85 — Temporal worker started (background)+ ├── ... (auth state propagates to FE; React mounts; queries fire)+T+8.29 — First WebSocket client connected ◀ UI-interactive point+ ├── Stripe daemon spawned + clean exit (0)+ ├── Telegram bot validated + polling started+ └── WhatsApp RPC connected (10.93 s)+T+12.27 — Status broadcasters settled ◀ "everything green"+```++## 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+is idle in this window; the cost lives on the frontend. Likely+contributors:++1. **TanStack Query auth-bootstrap retry budget** ([client/src/contexts/AuthContext.tsx](client/src/contexts/AuthContext.tsx) + [client/src/lib/connectionConfig.ts](client/src/lib/connectionConfig.ts)). The `AUTH_RETRY` envelope (BASE 50 ms, CAP 4000 ms, MAX_ATTEMPTS 7) covers the typical 4 s backend cold-start window in 4-5 attempts. If the backend finishes mid-retry-cycle, the next jittered draw can land 1-3 s after readiness.+2. **React Strict Mode dual-mount** in dev. The 100 ms guard in [WebSocketContext.tsx:2554](client/src/contexts/WebSocketContext.tsx#L2554) absorbs the bulk; remaining cost is React reconciliation + babel-plugin-react-compiler overhead on first render.+3. **PartySocket upgrade handshake**. Sub-100 ms in normal cases; would only matter on slow networks.++To attribute definitively: add `console.time('auth.queryFn')` / `console.timeLog('auth.queryFn')` markers and a corresponding pair around `connect()`. Not blocking — the contract this layer was meant to fix (the +12 s disconnect-reconnect cycle) is resolved.++## Frontend retry / reconnect envelope++Single source of truth: [client/src/lib/connectionConfig.ts](client/src/lib/connectionConfig.ts).++| Constant | Value | Notes |+|---|---|---|+| `AUTH_RETRY.BASE_MS` | 50 ms | Full-jitter base; first failure waits up to 50 ms vs. 1 s previously |+| `AUTH_RETRY.CAP_MS` | 4000 ms | Cap on per-retry delay |+| `AUTH_RETRY.MAX_ATTEMPTS` | 7 | Cumulative upper bound ~10 s (vs. 31 s on the old recursive `setTimeout`) |+| `WS_RECONNECT.MIN_DELAY_MS` | 250 ms | First reconnect attempt |+| `WS_RECONNECT.MAX_DELAY_MS` | 8000 ms | Cap on any single reconnect delay |+| `WS_RECONNECT.GROW_FACTOR` | 1.3 | Multiplier per attempt |+| `WS_RECONNECT.MAX_ENQUEUED_MESSAGES` | 200 | PartySocket send-while-disconnected buffer |+| `WS_CLOSE.NORMAL_CLOSURE` | 1000 | RFC 6455 §7.4.1; PartySocket skips reconnect for this code |++Backoff formula (AWS Architecture Blog "full jitter" pattern):++ sleep = random(0, min(CAP_MS, BASE_MS * 2^attempt))++Lock-in tests: [client/src/lib/__tests__/connectionConfig.test.ts](client/src/lib/__tests__/connectionConfig.test.ts).++## Bottleneck inventory (cold-start, warm cache)++Ranked by absolute cost. None are individually large after the+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. |+| 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. |+| 5 | Process spawn + Python interpreter init | ~0.4 s | Platform | Unavoidable without compiling Python to a binary (Nuitka / PyOxidizer — explicitly out of scope). |++## Pre-compile Python bytecode++The build-pipeline step that produces `.opt-1.pyc` files for the+project's own modules (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+```++`machina build` runs this as step `[5/6]`. The path list lives in+[machina/commands/build.py](../machina/commands/build.py)'s+`COMPILEALL_SOURCE_DIRS` constant; install.js mirrors the same list.+Tests at+[machina/tests/test_build_compile_pipeline.py](../machina/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.++## How to reproduce a measurement++### Cold-start timeline++```bash+# Warm path (typical dev iteration):+machina start > start.log 2>&1+# In another shell, wait for "Status broadcasters settled" then Ctrl-C the first.+```++Then extract phase markers:++```bash+grep -E "Freeing ports|Importing FastAPI|AIService imported|All imports complete|Lifespan startup begin|Application startup complete|ready on port 3010|StatusBroadcaster\] Client connected|broadcaster.refresh_all_services" start.log+```++### Bundle size + chunk shape++```bash+cd client+ANALYZE=1 pnpm exec vite build+# open client/dist/stats.html in a browser → treemap with gzip sizes+```++The `850 KB` chunk-size warning ceiling lives in+[client/vite.config.js](../client/vite.config.js). `vendor-icons` is+~830 KB (lucide + lobehub brand SVGs); the limit is set just above so+real regressions in other chunks fire while the icons baseline doesn't.++### Frontend retry envelope sanity++```bash+cd client+pnpm exec vitest run src/lib/__tests__/connectionConfig.test.ts+```++10 tests, locks RFC 6455 close code, AUTH_RETRY envelope, full-jitter+formula bound check across 100 × MAX_ATTEMPTS draws.++## Anti-patterns we've removed (don't reintroduce)++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.+- **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.+- **Inline `chunkSizeWarningLimit: 1500`** silently masking bundle bloat. Lowered to 850 KB so future regressions surface at `vite build` time.++## Open follow-ups++Tracked but explicitly **not** in any active plan.++| Item | Estimated saving | Notes |+|---|---|---|+| 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 `AgentState` (move LangGraph state schema off the `Annotated` form) | ~0.3-0.5 s | Removes the only remaining eager LangChain import in `services/ai.py`. Requires understanding how LangGraph resolves `Annotated[Sequence[BaseMessage], operator.add]` reducers. |+| `+5 s` HTTP-ready → first-WS-connect gap | up to 5 s | Diagnostics needed (see "remaining +5 s gap"). May reveal nothing actionable. |+| 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++- AWS Architecture Blog, ["Exponential Backoff and Jitter"](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) — full-jitter formula used by `AUTH_RETRY`.+- RFC 6455 §7.4.1 — WebSocket close codes ([https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1](https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1)).+- TanStack Query v5 retry guide — [https://tanstack.com/query/v5/docs/framework/react/guides/query-retries](https://tanstack.com/query/v5/docs/framework/react/guides/query-retries).+- PartySocket API — [https://docs.partykit.io/reference/partysocket-api/](https://docs.partykit.io/reference/partysocket-api/).+- React `useEffect` cleanup pattern — [https://react.dev/reference/react/useEffect](https://react.dev/reference/react/useEffect).+- CloudEvents v1.0 spec — [https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md). Mirrored in [client/src/types/cloudEvents.ts](../client/src/types/cloudEvents.ts) and [server/services/events/envelope.py](../server/services/events/envelope.py).+- Companion docs: [release_build_pipeline.md](release_build_pipeline.md) for the build-time wins, [frontend_architecture.md](frontend_architecture.md) for the cache + slice-subscription model that bounds runtime latency.diff --git a/server/pyproject.toml b/server/pyproject.tomlindex cd5bac6e..e3420f99 100644--- a/server/pyproject.toml+++ b/server/pyproject.toml@@ -56,6 +56,11 @@ dependencies = ["google-genai==1.72.0","langchain-groq==1.1.2","langchain-cerebras==0.8.2",+ # textChunker plugin (recursive / markdown / token strategies). Pinned to+ # 1.0.0 — the only release in the 1.x line whose `langchain-core` floor+ # (>=0.3.72,<2.0.0) is compatible with our pinned `langchain-core==1.2.28`.+ # Bumping to 1.1+ pulls langchain-core>=1.3 and breaks the lockstep.+ "langchain-text-splitters==1.0.0","langgraph==1.1.6","deepagents==0.5.2",@@ -130,7 +135,8 @@ dev = [docs = ["beautifulsoup4>=4.12.0","pypdf>=5.0.0",- "langchain-text-splitters>=0.3.0",+ # `langchain-text-splitters` moved to top-level dependencies (above) —+ # the textChunker plugin is part of the runtime, not optional.]keyring = ["keyring>=25.0.0", # OS-native credential storage (Windows/macOS/Linux)diff --git a/server/tests/llm/test_wiring.py b/server/tests/llm/test_wiring.pyindex 5b092e5a..4c12bce0 100644--- a/server/tests/llm/test_wiring.py+++ b/server/tests/llm/test_wiring.py@@ -107,7 +107,11 @@ async def test_fetch_models_uses_native_for_anthropic(ai_service):models = await ai_service.fetch_models("anthropic", "sk-ant-test")assert models == expected_models- mock_factory.assert_called_once_with("anthropic", "sk-ant-test")+ # ai.fetch_models forwards `proxy_url` (defaulting to None) to the native+ # factory so the Ollama-pattern proxy override path stays uniform with+ # execute_chat. Asserting the full call signature including the explicit+ # `None` kwarg ensures the proxy path is not silently dropped.+ mock_factory.assert_called_once_with("anthropic", "sk-ant-test", proxy_url=None)@pytest.mark.asyncio