Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
{"version":1,"documents":{"doc:CLAUDE.md":{"id":"doc:CLAUDE.md","path":"CLAUDE.md","title":"OpenCompany - Claude Documentation","content":"# OpenCompany - Claude Documentation\n\n## Project Overview\nThis is a React Flow-based workflow automation platform implementing n8n-inspired architectural patterns. The project has undergone a comprehensive refactoring to implement modern INodeProperties interface system with full TypeScript compliance and code cleanup.\n\n## Documentation Reference\n\n**Always refer to these documentation files for detailed guides:**\n\n| Document | Description |\n|----------|-------------|\n| **[Browser AI Agent deployment](./docs-internal/browser_agent_deployment.md)** | Shared creation recipe, local/distributed prerequisites, PostgreSQL offline transfer, exclusive browser ownership, owner recovery, direct task history and release gates. Browser effects route to owner queues even with worker pools disabled. Direct tasks use the existing native agent/Workspace path and remain separate from deployment Start/Stop/Resume. |\n| **[1Password credentials](./docs-internal/onepassword_credentials.md)** | CLI-first approved API/login bindings, pinned executable verification, desktop/service-account authorization, metadata-only catalogues, Activity-local resolution, protected CDP login and the local-only OAuth/CLI compatibility boundary. No resolved values in models, Temporal inputs, viewer captures or task history. |\n| **[Frontend Architecture](./docs-internal/frontend_architecture.md)** | Current frontend stack (React 19 + Vite + Tailwind v4 + shadcn/ui + Radix + RHF/zod + TanStack Query + Zustand). Tokens, primitives, forms, credentials exemplar, ownership boundary, `uiHints` catalogue. Brand: the Open Council mark and the outlined Newsreader wordmark are SVG paths in `client/src/components/brand/geometry.ts`, drawn in the text colour by `brand/Logo.tsx`; the favicon (`client/public/opencompany-icon.svg`), the desktop icon (`desktop/build/icon.svg`) and the icon-only logo SVGs in `media/brand/` embed its `MARK_PATH` verbatim (`brand/__tests__/appIcons.test.ts`), so change the mark there, paste the new path into each, and render the square PNGs beside those SVGs again (`media/brand/README.md` says how). |\n| **[UI Migration Plan](./docs-internal/ARCHIVE/ui_migration_plan.md)** | *Archived.* antd → shadcn/ui migration completion log (Waves 1–10). Current state lives in [Frontend Architecture](./docs-internal/frontend_architecture.md) and [Theme System](./docs-internal/theme_system.md). |\n| **[Temporal Cleanup & Resilience Plan (Waves 15-18)](./docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md)** | *Archived — all four waves shipped.* 15 dead-code retirement (Redis-Streams branch in event_waiter, APScheduler cron stack, orphaned `connection_status` factory), 16 per-queue task routing (`TemporalWorkerPool`), 17 resilience hardening (cron `catchup_window`, SDK interceptors, `DEPLOYMENT_MODE`, periodic heartbeats; the one-shot LLM-step retry it records was later reverted to unlimited-with-backoff), 18 worker performance tuning. Current settings live in [Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md). |\n| **[Node Allowlist](./docs-internal/node_allowlist.md)** | Single-config UI visibility — `server/config/node_allowlist.json` controls which nodes / credential categories / skill folders show in the UI. Five lists with two enforcement tiers (mode-gated allowlist + absolute blocklist). `useNodeAllowlist` hook exposes `isVisible` / `isBlocked` / `isAllowed` / `isCredentialCategoryDisabled` / `isSkillFolderDisabled`. Adding a new disabled domain = single JSON edit, no code change. |\n| **[Normal Mode (Home)](./docs-internal/normal_mode.md)** | The owner-facing landing screen: describe a job, an LLM on the server drafts a setup screen (a JSON UI spec the client parses, normalises and renders from a fixed catalogue), and Hire builds, validates, saves and starts one workflow per AI employee (`services/employees/`, graph built from `config/employee_apps.json` plus the owner's skill library and a Canvas node, and checked against `node_allowlist.json` `enabled_nodes`). Covers the screen switch (`app/`, `shellMode` / `ui_shell_mode`, `VITE_NORMAL_MODE=false` kill switch, the same three themes and theme button as the editor), the employee page (the shared chat, `features/chat`, with the employee named in the header beside New conversation; Stop is in the Workspace header), deleting an employee from the team sidebar (stopped through Reset first, then gone from every tab), the live Ask first rule (`workflow_rules`, the chat's Ask first chip via `set_ask_first`; app replies wait in `approvalGate`, sending tool calls are held as drafts by `services/approvals/tool_calls.py` and sent after a 5 s Undo window by `ApprovedToolCallWorkflow`; cards in the chat; builder v3 gates every app reply, attaches every app tool and gives the talk agent `chatUi` and the registry's `talk_send` tools, with instructions identical whatever the rule; older employees are upgraded on Apply / Turn on Talk / Start by `services/employees/upgrade.py`), run records for \"done today\" (`machina-run-record-v1`), automatic-pause reasons, Settings (Profile fields; usage-only Billing via `get_employee_usage`; Skills, the user-skills library each new hire copies onto a Skills node; consumer Connectors with `publisher` / `verified`; Plugins, the starter bundles in `hire/starters.json`; the last three share one catalog page), the Workspace dock (an employee's Canvas board, named by the summary's `canvas_node_id`; a live Browser tab with user takeover, shared with Dev mode; Mobile shows the managed local Android phone; a footer timeline of the employee's steps from the step log `services/workspace_steps.py`, read with `workspace_steps_list` and again on `workspace_step`, and Take over, which takes the screen and stops the employee until Hand back), the \"Web browser\" app (attached whole, each call read-only while the owner asks first through its approval spec's `restrict_while_asking`; while the agent waits in `request_user` the summary's `browser_request` shows Needs you and Help in browser), Talk on the employee page (a thread over the chat session whose id is the workflow id, rows written through `services/chat_thread.py` and, for the owner's messages and their chat runs, `services/chat/ledger.py` (see [Chat Protocol](./docs-internal/chat_protocol.md)); the talk line is chatTrigger → an agent → `chatReply` \"Reply in Chat\": a chat hire's own agent is its talk agent, other hires get a \"Talk with {name}\" agent sharing the worker's tools and skills with its own Context, and schedule hires also \"Post to Talk\"), Turn on Talk (for talk `off`) and Apply (while the summary's `pending_changes` is true) via `enable_employee_talk` / `apply_employee_changes`, each a restart on the saved graph through `services/deployment/restart.py`, self-extension from Talk through the Agent Builder within the Hire rule (`services/employees/policy.py`), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` / `chat.updated` / `workspace_step` broadcasts. |\n| **[Chat Protocol](./docs-internal/chat_protocol.md)** | The wire contract between the chat runtime (`server/services/chat/`) and the shared chat UI: AG-UI's event model on the existing WebSocket, snake_case, in the CloudEvents envelope. A message a deployed chat trigger will answer starts a **chat run** admitted with it in one reserved write transaction (`Database.reserved_session`, SQLite `BEGIN IMMEDIATE`): one live run per session (the lane, also a partial unique index; a second send answers `run_in_progress`), idempotent `client_message_id`, claimed and finished by the MachinaWorkflow that answers it behind `machina-chat-run-v1` (the run id is trusted only from an event whose source is `opencompany://services/chat`; `run_scope` rides every node context; only the claimant finishes), the reply saved as `a_<run id>` by `chatReply`, every message appended after the session's active leaf (`chat_threads`) so concurrent writes never fork the thread. `chat_run_event` frames reach only sockets that passed `chat_subscribe`'s owner check (`services/chat/hub.py`: per-run `seq`, `hub_epoch`, bounded per-socket queues with a resync), never the status broadcast; a standalone worker sends its run events, `chat.updated` and `approval_lifecycle` to the backend over `/ws/internal` (`services/chat/relay.py`, `chat_run_publish`, ordered, dropped events resynced). A watchdog (`services/chat/watchdog.py`, started by `main.py`) ends runs nothing will finish (`not_delivered`, `timed_out`, `interrupted`). The agent wired into Reply in Chat (`answers_chat_run`) streams its answer as `text.*` events (`services/chat/stream.py`, activity input only, no workflow patch), its tool calls show as steps (`services/chat/steps.py`; label from the plugin's `chat_step`), and `stop_chat_run` stops a run cooperatively: its LLM step polls the run and returns what was shown, unstarted tools are skipped, the reply is saved `stopped`, and the watchdog cancels a run still stopping after `runs.stop_grace_s`. Generated UI: the `show_ui` tool (`chatUi`) is checked against `config/chat_genui_catalog.json` (`services/genui/spec.py`; refused with every reason so the model retries), saved as a run part, streamed as `activity.*` RFC 6902 patches and sealed into the reply (`services/chat/parts.py`); `chat_ui_state` keeps what the owner set, and a button press comes back as `send_chat_message{ui_event}` -> a `[ui-event]` turn. The answering agent's system prompt ends with a fixed guide (`services/chat/guide.py`), what the owner set reaches its next turn as a `[ui-state]` note (`chat_notes`, `services/chat/notes.py`: claimed by the payload, told when the run answered), a trailing `<followups>` block becomes `parts.followups`, and a `chat_sources` tool's results are numbered per conversation for `[n]` citations (`services/chat/sources.py`). Approvals (`services/approvals/`, its own section): a plugin's `approval` spec marks a tool call that sends; while the workflow asks first it is held as a `tool_call` draft, shown as a card on the reply that made it, sent once after the Undo window by `ApprovedToolCallWorkflow`, with the outcome told to the employee as an `[update]` note. Branches (`services/chat/branches.py`): `get_chat_messages` returns the path to the thread's active leaf, each message with its versions (`siblings`), `editable` and the owner's rating; `edit_chat_message` / `regenerate_chat_reply` / `switch_chat_branch` move the path in one reserved transaction under the conversation store's lock, taking each agent's stored conversation back to the cursor its run recorded at `prepare_payload` (`chat_runs.context_cursors`) or restoring the branch's kept copy (`chat_branch_snapshots`), refused on `revision_conflict`, `run_in_progress`, `cannot_rewind`, `branch_unavailable` or `older_generation`; `set_chat_feedback` keeps a rating and tells the next turn (`[feedback]` note). Attachments (`services/chat/attachments.py`): the chat uploads files under `uploads/` and sends only their paths, the server rebuilds each reference from the file (refusing anything else, at most six), the answering agent reads an `[attachments]` line and images ride the opening user message for a provider with `vision.user_images`; `options.web: false` drops the `search` tools for that run; Home's model picker (`services/chat/choice.py`, `get_chat_models`) sends `options.model` / `options.effort`, resolved at admission (Auto = the owner's default model; refused with `model_unavailable`, never swapped) and applied only to the answering agent, effort only to a provider's `effort_models`; `get_chat_context` gives slash commands (generic plus the apps' `commands`) and capabilities; dictation is the speech plugin's `dictation_status` / `transcribe_audio`. Lists every event, handler, part and error code (among them `engine_unavailable`: with Temporal not connected a workflow's chat saves nothing, since nothing could deliver it). |\n| **[Theme System](./docs-internal/theme_system.md)** | Three themes — the base `light` and `dark` plus one stylized skin, `atomic` (the design handoff's nine other skins were removed on 2026-10-12) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Home, the editor and the sign-in screen all show the chosen theme, and one theme button ([components/ui/ThemeButton.tsx](./client/src/components/ui/ThemeButton.tsx)) in the Home header, the editor's toolbar and the sign-in screen steps Light → Dark → Atomic (`cycleTheme`; every theme name comes from `THEME_LABEL` in `ThemeContext.tsx`). Token taxonomy (surface / fg / border / accent / typography / motion) in **hex + `color-mix()`**; `@theme inline` bridge maps `--color-X: var(--X)` (no `hsl()` wrapper); per-theme files own the colour hex, base.css owns the shared `--tint-*` alpha scale; action role tokens (incl. `-ink` readable text), **per-theme `--code-*` syntax tokens** (tier 6 — the code editor, console/output JSON viewers, and chat code blocks paint in each theme's own palette: keyword→trigger, string→success, number→agent, function→model, on an adaptive dark/light code surface; replaced the global dracula `--prism-*` block + dead `getPrismTokenCSS`; the `OutputPanel` JSON viewer reads the same vars), the `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, per-component decoration hooks (`.canvas-host`, `.toolbar`, `.sq-node`, …; Atomic's panel edges, starburst canvas and node styling), **canvas-node visual contract via `--node-color` CSS custom property** (no inline `background` / `border` on node components — base.css + per-theme CSS owns visuals; `NodeStyle` helper type at [types/NodeTypes.ts](./client/src/types/NodeTypes.ts) makes the inline custom-prop typecheck-clean), **`--node-pulse-color` separate from `--node-color`** so executing-node glow uses each theme's highest-contrast accent regardless of plugin accent, **`data-page-hidden` animation pause** (set by `app/usePageActivitySync.ts`, mounted in `App.tsx` above the sign-in gate so it covers every screen, while the page is hidden per the Page Visibility API, never merely because the window lost focus; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyphs** (Atomic's 29 inline SVG glyphs in [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts), read by theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), scrollbars from the global token rules plus Atomic's own, 9-event WebAudio sound system (3 packs — parchment, terminal, vibraphone — via `--sound-pack` token + `useSound()` hook + global hover delegate + sonner toast monkey-patch + `withSound()` HOC + `Sounds.unlock()` gesture-unlock for AudioContext autoplay-policy compliance), `@media (prefers-reduced-motion: reduce)` accessibility, 30 ms throttle on `type` / `hover`, migration recipe, anti-patterns. Read this before adding a new theme, migrating a component to the new contract, or adding a canvas-node component. |\n| **[Design System Bundle](./docs-internal/design-system/IMPLEMENTATION.md)** | Canonical, vendored design-system reference (extracted from this repo; see its `IMPLEMENTATION.md` for the contract). Tokens are **hex + `color-mix()`** (`tokens/{colors,typography,spacing,motion,fonts,base}.css`) — the format the live codebase standardizes on. Includes 34 reference components (`components/`, inline-style reference only — recreate in Tailwind/shadcn idioms), full-app UI kit (`ui_kits/opencompany/index.html`), theme docs (`guidelines/THEMES.md`), **the merged handoff brief (`HANDOFF.md` — glow-ladder traps, step-edge contract, toolbar layout traps, canvas-layer asymmetries, plus the recorded product amendments)**, and **the panel×theme fidelity target (`reference-mockup/Panel Theme Matrix.dc.html` — 17 panels × 3 themes, open in a browser)**. `reference/themes/` no longer vendors CSS snapshots — it points at the authoritative [client/src/themes/](./client/src/themes/). Copy token values verbatim; do not re-derive by eye. Pairs with [Theme System](./docs-internal/theme_system.md). |\n| **[Schema Source of Truth RFC](./docs-internal/ARCHIVE/schema_source_of_truth_rfc.md)** | *Archived — shipped.* Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons; `VITE_NODESPEC_BACKEND` defaults on and the frontend node definitions are gone. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<plugin>/__init__.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. Current reference: [Plugin System](./docs-internal/plugin_system.md). |\n| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern; `request()` supports `json` / `data` / `files` — the last for multipart uploads, threaded through the auth-retry rebuild). `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use); live count via `len(services.plugin.credential.CREDENTIAL_REGISTRY)` — do not hand-maintain a number here. `TaskQueue` constants route to Temporal worker pools. Plugins live across 9 queues (live plugin count via `len(services.node_registry.NODE_METADATA)`; a bare `__init__.py` glob overcounts by also matching group packages); handler bodies fully inlined (`services/handlers/` shrank 12.8K → 1.1K LOC across 16 → 4 files; only cross-cutting orchestration remains: `tools.py` AI-tool dispatch + agent delegation, `triggers.py` generic trigger-node handler, `todo.py` writeTodos shim — `google_auth.py` was retired into `nodes/google/_auth_helper.py`). **Wave 11.H added \"self-contained plugin folders\"** — generic registries (live list via `grep -rn '^def register_' server/services server/core`; the plugin-facing ones are `ws_handler_registry.{register_ws_handlers,register_router,register_option_loader,register_oauth_callback_path}`, `event_waiter.{register_filter_builder,register_trigger_precheck}`, `status_broadcaster.register_service_refresh`, `node_output_schemas.register_output_schema`, `edge_walker.{register_agent_context_builder,register_master_skill_expander}`, `register_webhook_source`, `register_canary_trigger_type`, `register_poll_coroutine_factory`, `register_social_send_handler`, `register_shutdown_hook`, `register_service_factory`, `register_log_source_tag`, `register_conversation_listener`) so rich plugins like telegram own their entire surface area without core-services edits. |\n| **[Nodes Cookbook](./server/nodes/README.md)** | 5-minute recipe + folder map + shared helpers (`_base.py` / `_inline.py` per domain) + shared credentials + **canonical folder-per-plugin shape (telegram is the reference implementation)** + contract invariants + common pitfalls. Lives next to the plugin files. |\n| **[Node Creation Guide](./docs-internal/node_creation.md)** | Canonical plugin recipe — one self-contained folder per plugin under `server/nodes/<group>/<plugin>/`, rooted at `__init__.py`. Multi-file split (`_service.py` / `_handlers.py` / etc.) when the plugin owns long-lived state. Zero frontend edits, zero core-services edits. Auto-registers via `BaseNode.__init_subclass__` + the generic `register_*` hooks (see the Plugin System row). Covers tool nodes, dual-purpose nodes (workflow + AI tool), and specialized agents as variations of the same recipe. |\n| **[Agent Architecture](./docs-internal/agent_architecture.md)** | How AI Agent and Chat Agent discover skills/tools, inject them into LLM prompts, and execute through the provider-neutral `run_native_agent_loop` |\n| **[Agent Delegation](./docs-internal/agent_delegation.md)** | How memory, parameters, and execution context flow when one AI agent delegates work to another agent connected as a tool |\n| **[Agent Teams](./docs-internal/agent_teams.md)** | Claude SDK Agent Teams pattern - AI Employee and Orchestrator nodes with input-teammates handle for multi-agent coordination |\n| **[Agent Context Flow](./docs-internal/agent_context_flow.md)** | Normative continuity reference — how a conversation survives firings, delegations, and rollovers on both paths. Plain conversation store: one `agent_conversations` row per `(workflow_id, generation, agent_node_id)` → messages JSON, loaded at run start and saved per turn (LangGraph thread_id / OpenAI conversation_id pattern; the journal/thread/epoch machinery is gone). Seeding precedence (carried rollover transcript > stored conversation > bare build, 1 MB guards), LOUD load failures (`ConversationLoadFailed` / `ConversationTooLarge`) vs best-effort saves, transcript size bounds (per-call tool-result cap, byte budget that clears old results, `context_pressure_version` replay contract), the specialized-provider bridge, and the August 2026 \"lead forgot its plan\" regression. Read before touching `services/agent_context/`, `nodes/context/`, `services/cli_agent/context_bridge.py`, `services/tool_output.py`, `agent.prepare_payload`, or the team-completion event chain. |\n| **[Memory Compaction](./docs-internal/memory_compaction.md)** | Native usage aggregation plus shared client-side summarization through `ChatUnifier` for memory-connected agents. Threshold = `Settings.compaction_ratio` (env `COMPACTION_RATIO`, default 0.8) × model context length; see the document for the per-session override limitation on Temporal runs. |\n| **[Pricing Service](./docs-internal/pricing_service.md)** | Centralized cost tracking for LLM tokens and API services (Twitter, Google Maps) with HTTPX event hooks |\n| **[Proxy Service](./docs-internal/proxy_service.md)** | Residential proxy provider management with template-based URL formatting, health scoring, and transparent HTTP node injection |\n| **[Email Service](./docs-internal/email_service.md)** | IMAP/SMTP integration via Himalaya CLI with EmailService orchestrator, provider presets, custom credential fallback, and polling triggers |\n| **[Browser](./docs-internal/browser.md)** | Current `browser` node: installed Chrome/Edge/Chromium in a dedicated profile rendered inside the workspace by default (`BROWSER_RUNTIME=system`, `BROWSER_HEADLESS=true`) and pinned browser-use CLI. Chrome for Testing requires explicit `BROWSER_RUNTIME=testing`. System mode retains the native user agent and OS password-store/keychain integration; basic/mock keychain flags are restricted to testing mode. Includes persistent employee/shared profiles (the Credentials / Connectors \"Web browser\" panel adds, deletes and imports logins from a session file; the node's profile dropdown lists only the caller's profiles, via `current_load_options_principal()`), session leases, agent/user handoff, network policy, screenshots as workspace FileRefs and authenticated `/ws/browser` live viewing. Plugin-owned installation is lazy (`_install_chrome.py`, `_install_bu.py`); importing or shutting down the plugin never installs it. Replaces the former agent-browser and separate `browserHarness` implementations. |\n| **[Browser Workspace](./docs-internal/browser_workspace.md)** | Home and Dev share `WorkspaceTabs` and `BrowserWorkspace`: Browser / Canvas / Mobile, capability-based discovery, binary JPEG frames, bounded frame credit and decoding, Take control / Hand back, the agent's cursor (`agent_action`: where each click, hover, type or select happened, beside the agent's result and never during a protected login), visibility cleanup and payload-free opt-in diagnostics. The Browser node's parameter panel shows the same viewer, and the Dev dock opens on its Browser tab when an agent in the open workflow asks for help (`browser_updated`). Mobile shows the managed local Android phone. |\n| **[MCP Connectors](./docs-internal/mcp_connectors.md)** | Custom connectors: the owner adds an outside MCP server from Connectors → Add, or the MCP server card in the Custom category (`mcp`, kind `mcpAdd`, never connected; its page `panels/McpAddPanel.tsx` is the same form) (URL, name, sign-in: none, bearer, one header, or OAuth), and OpenCompany is its MCP *client* (`server/nodes/mcp/`, official `mcp` SDK; unrelated to the CLI agents' `/mcp/ide` server). The server reads the tools before keeping anything: streamable HTTP, then SSE; our own httpx client with redirects off; host and resolved addresses of every request (an OAuth sign-in's to its authorization server too) checked against `services/netpolicy.py` (shared with the Browser node: never cloud metadata or OpenCompany's own ports, plain http only on the owner's network), within `DISCOVER_S` (45 s, under the app's 60 s probe wait). Kept as `mcp:<slug>` (sign-in, encrypted; plain `model_params._mcp`: tools as accepted, per-tool `{enabled, ask}`, a waiting refresh) and `mcp:<slug>_proxy` (URL). A tool no model could call is kept with the reason, never renamed. Each connector is its own card through the generic `Credential.catalogue_entries` hook and the `_mcp_connector` template. Commands `mcp_connector_add` / `_sign_in` / `_test` / `_refresh` / `_review` / `_set_tool` / `_remove`; Refresh holds every change for Accept. Client: `AddConnectorForm.tsx` and `panels/McpConnectorPanel.tsx`. The `mcpConnector` node on an agent's Tools gives one tool per tool that is on (`ToolNode.tool_bindings`, named `<slug>__<tool>`, run with its binding's locked `mcp_tool` / `mcp_ask` / labels; arguments checked with jsonschema, a `$ref` followed only inside its schema: a tool whose inputs refer to another document is unusable, and a call goes as a plain `tools/call`, so the SDK never checks a result against an output schema the server sends; Ask first per tool through the node's `approval` spec); CLI agents leave it out and RLM refuses it. OAuth (`_oauth.py`) is the SDK's `OAuthClientProvider`: Add or Sign in again answers `sign_in_url`, the sign-in finishes in the background through `/api/mcp/oauth/callback`, tokens go to the OAuth token store under `mcp:<slug>` with their expiry (`store_oauth_tokens(..., expiry=)`), and each connection restores the expiry (read uncached with `get_stored_oauth_tokens`) and the endpoints before first use, so the SDK refreshes instead of opening a sign-in; a token issued without an expiry is renewed once the server refuses it (`_oauth.connect`); a refused refresh says Sign in again. Each connector is also an app a hire can use: `connector_apps`, registered with `services/employees/apps.register_app_source`, is read by `Connections.apps` with `employee_apps.json`'s apps (a saved one counts as connected), `mcpConnector` is on the hire allowlist, and the employee's card reads the connector from the node's `app_field` (`mcp_connector`). |\n| **[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** and comes from the credential only, because it selects the sending identity — `server_controlled_fields` would keep a model-set value out on every tool path, but an ActionNode's tool schema is its whole `Params` (`ToolInput` is ToolNode-only), so a declared field would still appear in the schema the model sees. 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. |\n| **[Stripe Service](./docs-internal/stripe_service.md)** | Stripe CLI integration — `stripeAction` (CLI pass-through) + `stripeReceive` (signed-webhook trigger, on a canvas Run and deployed: every Stripe event travels under one CloudEvents type, `com.opencompany.stripe.event.received`, with the Stripe type in `subject` and `data.event_type`, where the node's own `build_filter` reads it; the source shapes the payload once, wakes the in-process waiter through `WebhookSource.handle` and reaches deployed listeners through `dispatch.emit`; deploying starts `stripe listen` through the generic `TriggerNode.prepare_deployment` hook, at Start and at the boot re-arm). 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. |\n| **[Dodo Payments Service](./docs-internal/dodo_payments_service.md)** | Dodo Payments integration over the official SDK (`dodopayments`, Stainless-generated, capped `<2`) — `dodoPaymentsAction` (list / get payments, subscriptions, customers, products; list refunds and disputes; `create_checkout_session` (returns `checkout_url`), `create_customer`, `create_customer_portal_link` (`send_email` off), `create_refund` (whole payment, one item, or part of it), `cancel_subscription` (`subscriptions.update`: the SDK has no cancel method), `change_subscription_plan`; `call` for any SDK method by its dotted name and `list_operations`; AI tool `dodo_payments_action`; `dodoPaymentsEndpoints` loader) + `dodoPaymentsReceive` (Standard Webhooks trigger at `/webhook/dodo-payments`). **A Dodo key works only in its own mode and carries no marker**: `DodoPaymentsCredential` (`ApiKeyCredential`, id `dodo_payments`) validates with `GET /brands` in test mode, then live mode, and its `validate` override saves the mode that accepted the key (`dodo_payments_mode`); every call goes to that mode's base URL from the SDK's `ENVIRONMENTS`, key and URL passed explicitly so no `DODO_PAYMENTS_*` variable authenticates or redirects a node. **Writes run with the SDK's retries off** (it retries POSTs and the API takes no idempotency key, so a retried refund could be paid twice); a write that times out or meets a 5xx says its outcome is unknown. **Nothing vendored**: `_sdk.endpoint_index()` reflects the installed SDK (`cached_property` resources, routes from the generated `self._get(path_template(...` source, parameters from signatures minus the SDK's per-call keywords, which `call` refuses since `extra_headers` could replace auth); the `webhooks` resource is left out (signing secrets have no use in an agent's hands); a test fails if any other method's route is missed. Lists are one page each (the SDK's auto-pagination asks for page 2 after page 0). Approval per operation: refunds, cancellations, plan changes and a `call` on a non-GET endpoint are held under Ask first (`ApprovalSpec` `operations` + a `when` on the endpoint's verb); reads and checkout links run. The trigger follows Stripe's fixed pattern (one CloudEvents type `com.opencompany.dodo_payments.event.received` with Dodo's type in `subject` / `data.event_type`, `event_type` and `build_filter` on the node, envelope id = `webhook-id` so a retried delivery is a duplicate, `emit` from the source's `handle`, both trigger sets in `constants.py`) but emits with `broadcast=False` (customer details, no client reads them); `StandardWebhooksVerifier` refuses timestamps outside the spec's five-minute window. SDK imported only inside `_sdk.py` (clean-interpreter test); tests run the real SDK under respx. Palette group `payments`; hire app with `side_effects: \"money\"`. |\n| **[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. |\n| **[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`. |\n| **[Cloudflare Service](./docs-internal/cloudflare_service.md)** | Cloudflare CLI integration — `cloudflareAction` (whoami / `search_commands` (`cf cli search`) / zones_list / DNS records list-create-edit-delete / `graphql_query` / `custom` passthrough; AI tool `cloudflare`) wrapping the official `cf` CLI (npm `[email protected]`, open beta — \"the next version of Wrangler\"). **Pin enforced, not just installed once**: `ensure_cf_cli` compares `core.js_runtime.installed_version(\"cf\")` with the pin and re-runs `bun add` on a mismatch (clearing the login marker, since a new version may not see the old login). **Login = gh's device-flow shape**: `cf auth login --force --device --no-browser` prints a URL + one-time code on stderr that the handler relays to the modal (works from any machine; the old fixed-port-8877 loopback flow is `--no-device` only) — single flight (a repeat click returns the same code), install before any login (no invisible codes), never-kill-the-shim (killing bun's `cf.exe` launcher orphans the child), success gate = `cf auth whoami` JSON (`authenticated: true` — cf exits 0 in BOTH auth states). **cf contract traps**: destructive commands without `--force` print \"Aborted.\" and **exit 0** (delete always passes it; `custom` turns it into an error); no `--account-id` flag on most commands (account = `CLOUDFLARE_ACCOUNT_ID`, from the `account_id` param — several accounts fail non-interactively without it); cf resolves a domain `--zone` only in the first page of the selected account, so the node resolves domains itself via `zones list --name`; no output-format flag (unknown flags rejected); cf reads `.env` files from its working directory and fails under bun on a `cloudflare.config.ts` found above it, so typed ops run from a neutral `<DATA_DIR>/cloudflare` (`custom` from the workspace) with `CF_DELEGATION=1` (otherwise bun lets cf hand off to another cached cf copy) and telemetry off. The optional `apiKey` field (an API token) rides `CLOUDFLARE_API_TOKEN` and beats the login; cf does NOT accept a Global API Key, so a `cfk_` key (with `cloudflare_email`) serves only `graphql_query`, which POSTs the official `client/v4/graphql` endpoint directly (no cf GraphQL command; the cf login's token never leaves the CLI) — needs `Account > Account Analytics > Read`. System cf never consulted. Palette group `deployment`. |\n| **[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). CLI-opens-the-browser login variant (the pre-1.0 Cloudflare flow; gcloud picks a 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`. |\n| **[AWS Service](./docs-internal/aws_service.md)** | AWS integration over the official SDK — `awsAction` (whoami / EC2 instances list-describe-start-stop / S3 list-upload-download-delete / `call` for any operation of any AWS service by its boto3 method or API name / `list_operations` from the SDK's bundled models, with no credentials or network; AI tool `aws_action`; `awsServices` / `awsOperations` dropdown loaders). **The SDK, not the AWS CLI**: CLI v2 ships as an MSI / `.pkg` with no portable archive to pin on Windows or macOS, and its browser login (`aws login`) cannot run on a hosted server. `boto3` is a main server dependency imported only inside `nodes/aws/_sdk.py` (a clean-interpreter test locks that importing the plugin never loads it). Auth = an IAM access key pair in the encrypted store: `AwsCredential` (`ApiKeyCredential`, id `aws`) keeps the secret under the provider id plus `extra_fields` `aws_access_key_id` / `aws_region` (the Cloudflare companion-field pattern); `resolve()` also requires the ID, and the modal probe signs `sts:GetCallerIdentity`, so the ID must be saved before the secret validates. **No ambient credentials**: the pair is passed to every client explicitly, so environment variables, `~/.aws` and an instance profile on the server never authenticate a node. One cached, credential-free botocore session; client creation runs under a lock (botocore sessions are not thread-safe; ~5 ms per client once a service's model is loaded) and calls run in `asyncio.to_thread` with 10 s / 60 s timeouts and `standard` retries. `call` resolves the operation (with `difflib` suggestions) before any credential use and returns one page; responses are shaped the way the CLI prints them (no `ResponseMetadata`, ISO timestamps, base64 blobs, streaming bodies inline up to 1 MB). S3 transfers go through `coerce_file_param` / `write_media` and stop at `MEDIA_MAX_READ_BYTES` (25 MB); AWS errors become `NodeUserError` with code, message, request id and a hint. Tests run real botocore clients under `Stubber`. Unrelated to `company deploy --provider aws`, which drives the operator's own aws CLI. Palette group `deployment`. |\n| **[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). |\n| **[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). **`account_id` is in `server_controlled_fields`, which the framework enforces on every tool path** (`BaseNode.execute_as_tool` strips it in process, `NodeExecutor` restores the saved value on Temporal); `AccountScopedNode` strips it again as defence in depth, and only runs in process, since the per-type activity calls `execute` for an ActionNode. 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. |\n| **[Sarvam AI Service](./docs-internal/sarvam_service.md)** | Sarvam AI (Indic-first). **`nodes/sarvam/` no longer exists** — every capability it served is now a *provider* inside an abstracted node: speech in `nodes/speech/`, and translate / transliterate / detect-language in `nodes/translate/`. What remains Sarvam-specific is `sarvamChatModel` (an **OpenAI-compat provider**: one `_COMPAT_PROVIDERS` entry + a JSON block, no provider subclass) under `nodes/model/`. **One stored key spans two auth styles** — the chat route takes `Authorization: Bearer` (what the openai SDK sends) while every other endpoint takes only `api-subscription-key`, so `SarvamCredential` declares the native header and every surface shares it. Introduces the generic **`supports_model_listing: false`** flag: Sarvam ships no `/v1/models` route, and unhandled that 404 becomes a `NodeUserError` that `AIService.fetch_models` re-raises *before* its curated fallback, breaking key validation and the model dropdown — so `OpenAIProvider.fetch_models` serves the curated list and probes with a one-token completion instead (defaults `true`; every other provider is untouched, locked by test). Also added generic **`Connection.request(files=)`** multipart support. |\n| **[Speech Provider RFC](./docs-internal/speech_provider_rfc.md)** | Provider-abstracted speech — two nodes (`textToSpeech`, `speechToText`) with a `provider` dropdown, backed by **two registries, one per direction** (registry membership IS the capability: a synthesis-only vendor simply never appears in the transcription enum). Everything vendor-specific lives in the plugin folder [`server/nodes/speech/`](./server/nodes/speech/) — protocol, registries, dispatch, per-vendor modules; only the generic `services/provider_registry.py` and the vendor-neutral `services/media/` are shared. v1 providers: OpenAI (both directions), ElevenLabs (TTS), Deepgram + Groq (STT), Sarvam (both). Capabilities are JSON (`server/config/speech_defaults.json`) with per-model overrides, so no shared code branches on a provider name. **Audio never travels as bytes** — nodes return an `AudioRef` (a ~400 B reference) because a 12 MB base64 result blows Temporal's 2 MiB blob limit and retries 3× re-billing the provider each time. Backing routes: `GET/POST /api/workspace/{workflow_id}/…` in [`routers/workspace.py`](./server/routers/workspace.py). |\n| **[Media Transport](./docs-internal/media_transport.md)** | How files move through the engine, and why they move as **references rather than bytes**. `services/media/` — `FileRef` (the base; `FileKind = file\\|audio\\|image\\|video\\|document`) with `AudioRef(FileRef)` as the probed-container narrowing (~400 B, `extra=\"forbid\"` so adding a bytes field is a `ValidationError` rather than a silent regression), `write_audio` / `resolve_media` / `coerce_file_param` (the one nodes should call — accepts a `FileRef`/`AudioRef`, a bare path, or the legacy base64 envelope), `inspect_audio` (tinytag → stdlib `wave` → PCM arithmetic, **never raises**), `limits.py`, and **`preview.py` — the single owner of the inline-vs-attachment rule**, with two consumers: `routers/workspace.py` picks its `Content-Disposition` from `serves_inline`, and the gallery listing sets each row's `preview` from `preview_kind`, so the panel can never offer a preview the route refuses to serve. Containment runs through `resolve_within`, which closed a live vulnerability: a node joined a user path onto the workspace root unchecked, so `audio_file=\"../../credentials.db\"` read the encrypted credential store and uploaded it. **The id/slug asymmetry is the trap** — workspace dirs are named by the mutable `Workflow.slug` while a ref stores the immutable `workflow_id` so refs survive rename; the lookup lives in [`services/workspace_locator.py`](./server/services/workspace_locator.py) (`resolve_workspace_root(..., allow_default=)`), and **every mutating caller must pass `allow_default=False`** or an unresolvable id silently lands the write in the shared anonymous workspace. HTTP surface in [`routers/workspace.py`](./server/routers/workspace.py): Range support comes free from Starlette's `FileResponse`; `NEVER_INLINE` is `{image/svg+xml, text/html, text/xml, application/xhtml+xml}` because `shell` / `fileDownloader` / `fileModify` can write arbitrary files into a workspace. |\n| **[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). |\n| **[Canvas Node](./docs-internal/canvas_node.md)** | The `canvas` node — pushed-content display board (the Claude/ChatGPT-Canvas analog) in [`server/nodes/tool/canvas/`](./server/nodes/tool/canvas/). Dual control: agents call the locked `canvas(...)` tool (paths / url / 64KB-capped markdown notes, append/replace), workflow edges auto-display upstream FileRefs via a structural scan of `connected_outputs` (`tts → canvas` is a zero-config edge; the node is the one addition to `NodeExecutor._NEEDS_CONNECTED_OUTPUTS`). Board = plugin-owned `canvas_boards`/`canvas_items` tables (mount_store mechanism, 200-item FIFO), identity-only `canvas_updated` broadcast (direct, no canary consumer), `canvas_list/remove/clear` WS handlers with the simple_memory security preamble. **Three frontend hosts share one renderer**: the `isCanvasPanel` parameter panel, the docked resizable right sidebar (`CanvasDock` + `canvasDockStore`; auto-open via `notifyPushed`, ephemeral click-to-preview from the gallery dialog, `usePanelResize` extracted from ConsolePanel), and the Canvas tab of Home's Workspace dock (`features/home/workspace/`). Renders media carousel with follow-latest image poll, markdown/code/JSON via the repo's first capped client-side text fetch (`useWorkspaceText`, 512KB), external URLs + workspace HTML in strictly sandboxed iframes (never `allow-same-origin`; `NEVER_INLINE` untouched), and inline PDF via the `INLINE_EXACT` exact-match addition to `preview.py`. The current Browser node persists screenshots as workspace FileRefs through `nodes/browser/_screenshots.py`; live viewing uses the separate Browser workspace stream. Items have versions (the tool's `update_id` saves the next one; `canvas_item_versions` keeps the newest 50 per item; `canvas_version` reads one) and a note shows as a document (`NoteView`: ‹ v2/3 ›, Preview/Markdown, Copy, Download); a note the agent answering the owner writes is named on its reply (`services/chat/parts.show_artifact`) as a card that opens the board at that version (Home: `homeStore.openCanvasItem`; Dev: `canvasDockStore.focusItem`). |\n| **[Translate / Transliterate / Detect](./docs-internal/speech_provider_rfc.md#8-the-pattern-generalised-nodestranslate)** | The second application of the multi-vendor pattern, and the one that retired `nodes/sarvam/`. Three nodes (`translateText`, `transliterateText`, `detectLanguage`) in [`server/nodes/translate/`](./server/nodes/translate/), backed by **three registries — one per capability**, because the asymmetry is sharper than speech's: DeepL translates and does nothing else, while Sarvam and LLM-backed providers do all three. Membership makes an unsupported selection unrepresentable rather than a runtime failure inside a paid call. Providers: **deepl** (`Authorization: DeepL-Auth-Key`, `text` is an array, free keys ending `:fx` route to a different host, and it returns `billed_characters` so cost is the provider's own figure), **sarvam** (all three over dedicated REST), **openai** (all three via `ChatUnifier` — proves the Protocol does not care what a provider does internally; billing deliberately NOT recorded because that path bills tokens the LLM layer already costs). Capabilities in `server/config/translate_defaults.json`. |\n| **[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 only (no Intel Mac build: cryptography 49+ and dependency-injector publish no Intel macOS wheels, so the first-launch `uv sync` would need Rust and a C compiler), AppImage+deb x64, unsigned first (`mac.identity: null`; macOS auto-update notify-only until signed — Squirrel.Mac refuses unsigned). CI: `desktop-release.yml` (tag-triggered: `prepare` drafts the GitHub Release from the annotated tag's message, three legs build and upload version-less OS-named installers such as `OpenCompany-windows-x64.exe` / `OpenCompany-macos-arm64.dmg` / `OpenCompany-linux-x86_64.AppImage` so the README can link `releases/latest/download/<file>`, each leg refuses a desktop version that differs from the tag, `finalize` undrafts once the legs and the predeploy checks pass) 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.** |\n| **[Desktop Host Contract](./docs-internal/desktop_host_contract.md)** | The backend's side of being owned by a GUI shell. `core/approot.py` is the ONE module that locates the app tree (`OPENCOMPANY_APP_ROOT` / `OPENCOMPANY_CLIENT_DIST` / `OPENCOMPANY_ENV_FILE` / `OPENCOMPANY_ENV_TEMPLATE`); `tests/test_no_root_climb.py` forbids any other `Path(__file__).parents[N]` climb above `server/` and any `\"client\"/\"dist\"` / `.env.template` / `package.json` path join. `core/env_defaults.apply_file_defaults_to_environ()` does the CLI's `.env.template < .env < process env` layering at the top of `main.py`, and `Settings.env_file` is the absolute `(template, .env)` tuple — so a shell spawns `python -m uvicorn` from any cwd without the CLI package. Desktop mode (`OPENCOMPANY_DESKTOP=1`, `core/desktop.py`): parent-PID watchdog with create-time PID-reuse guard, stdin-EOF watchdog (polling via `PeekNamedPipe`/`select`, never a blocking read — a daemon thread parked in `ReadFile` at finalisation crashed exit with 0xC0000005), ctypes Job Object so children die with the backend (no pywin32 in the server venv), token-gated `POST /api/desktop/shutdown` (`routers/desktop.py`, public path; raises the signal uvicorn handles so the lifespan reaps Temporal/the bun sidecar/edgymeow), 45 s hard deadline. `GET /health/ready` (public) = DB up AND (Temporal disabled OR worker manager started), with `phase` written by `services/temporal/lifecycle.py` (`installing_temporal` / `starting_temporal` / `connecting` / `starting_workers` / `ready`). Plugin shutdown hooks now run under a 10 s per-hook timeout (`HOOK_TIMEOUT_SECONDS`), and the current browser hook uses `peek_browser_runtime()` so shutdown never constructs or installs the runtime. Historical incident: the retired `get_browser_service()` lazily installed agent-browser at shutdown and wedged graceful exit (masked under the CLI by its 5 s grace + tree-kill). `server/uv.lock` is committed; `predeploy.yml` runs `uv lock --check`. |\n| **[LLM Gateway](./docs-internal/llm_gateway.md)** | Hosted LiteLLM Proxy in `gateway/` (official AWS module, mock-model local stack, contract and pin tests, `gateway-ci.yml`): pinned LiteLLM 1.103.4 and price list, served providers (Gemini on Vertex AI express mode with a Google Cloud Agent Platform key, `GOOGLE_AGENT_API_KEY`), and the contract OpenCompany relies on (wire model names, `budget_exceeded` refusals, `/user/info` allowance with Default keys, attribution headers, cache replay). Operator runbook: `gateway/README.md`. OpenCompany's side, `server/services/gateway/`: the Connectors card (`OPENCOMPANY_GATEWAY_ENABLED`), own-keys-first routing in ChatUnifier from `\"gateway\"` blocks in `llm_defaults.json`; the gateway's default model where the owner has set no global model (`gateway_default`, Gemini 3.8 Flash: chat Auto, employee setup, the editor's global model); and for embeddings, OpenAI speech (`\"gateway\": true` in `speech_defaults.json`) and vision through `key_or_route`; the RLM agent on OpenAI-format routes (`openai_prefix`); Claude Code after its login and the install's Anthropic key (`api_access`, no warm reuse); attribution from the log context, gateway error wording. |\n| **[CI/CD Pipeline](./docs-internal/ci_cd.md)** | GitHub Actions workflows, predeploy validation, release publishing, and the composite setup action (bun via SHA-pinned `oven-sh/setup-bun` reading the root `packageManager` pin + Node 22 as a CI-only convenience so bun runs vite / vitest / eslint on it via their node shebangs + Python 3.12 + uv; `bun install --frozen-lockfile` everywhere; publish is `bun publish --access public` after a `bun pm whoami` credential preflight with `~/.npmrc` written from `NPM_TOKEN` — no npm CLI, no `setup-node` step of their own in the publish jobs (they get Node through the composite action), and npm provenance attestation went away with npm). Also **Cutting a release**: the annotated tag is the version and its message is the release notes; `company version sync vX.Y.Z` bumps every version file for the `chore(release)` commit the tag sits on, and `desktop-release.yml` drafts the GitHub Release from the tag message and refuses a version that differs from the tag |\n| **[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. |\n| **[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`. |\n| **[Workflow Schema](./docs-internal/workflow-schema.md)** | JSON schema for workflows, edge handle conventions, config node architecture |\n| **[Execution Engine Design](./docs-internal/DESIGN.md)** | Architecture patterns, design standards, and implementation details for the workflow execution engine |\n| **[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 |\n| **[Setup Guide](./docs-internal/SETUP.md)** | Development environment setup and installation instructions |\n| **[Scripts Reference](./docs-internal/SCRIPTS.md)** | `bun run` scripts, `company` CLI verbs, and their usage |\n| **[Server Documentation](./docs-internal/ARCHIVE/server-readme.md)** | *Archived* at [ARCHIVE/server-readme.md](./docs-internal/ARCHIVE/server-readme.md); see [Setup Guide](./docs-internal/SETUP.md), [Authentication](./docs-internal/authentication.md), [Plugin System](./docs-internal/plugin_system.md) |\n| **[Skill Creation Guide](./server/skills/GUIDE.md)** | How to create new skills (folder structure, SKILL.md format, metadata, supporting files) |\n| **[Known Errors & Troubleshooting](./docs-internal/errors.md)** | Documented root causes and fixes for common errors (SQLAlchemy Windows hang, Temporal issues, WhatsApp timeouts) |\n| **[New Service Integration](./docs-internal/ARCHIVE/new_service_integration.md)** | *Archived* pre-Wave-11 guide; integrate a service as one plugin folder per [Node Creation Guide](./docs-internal/node_creation.md), with [server/nodes/google/](./server/nodes/google/) as the OAuth reference |\n| **[Onboarding Service](./docs-internal/onboarding.md)** | The Welcome guide on Home (`features/home/onboarding/`): three steps (Welcome, Connect an AI model, Your first hire), opened on first launch and again from the header's Guide button or Settings → Help; progress saved on `UserSettings.onboarding_completed` / `onboarding_step`; the open state lives in `homeStore.guide`, so a remount never reopens it |\n| **[CLI Services Integration](./docs-internal/cli_services_integration.md)** | Guide for integrating CLI-based services (Temporal, etc.) with proper lifecycle management |\n| **[Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md)** | Distributed workflow execution: activities, FIRST_COMPLETED scheduling, horizontal scaling |\n| **[Native LLM SDK](./docs-internal/native_llm_sdk.md)** | Native SDK layer in `services/llm/`: protocol-based providers, config-driven base URLs, and 14 registered providers (11 cloud, Ollama / LM Studio, and `openai_compatible`, which serves any number of user-named endpoints — llama.cpp, vLLM, a LiteLLM proxy — added in the Credentials Modal with no code; xAI is agent-selectable without a standalone chat-model node). A JSON-driven `supports_model_listing: false` flag covers endpoints that speak the OpenAI chat wire format but ship no `/v1/models` route (Sarvam) — `OpenAIProvider.fetch_models` then serves the curated list and probes the key with a one-token completion. `chat(on_event=...)` streams `StreamEvent`s only for providers whose block declares `\"streaming\": true` (Anthropic, OpenAI); the unifier replays the finished response into the sink for the rest, and the returned response never changes (`tests/llm/test_streaming.py`). Every provider is native; `tests/llm/test_langchain_removed.py` locks the retired-dependency end state. |\n| **[RFC-0003 — OpenAI-Compatible Provider Contract](./RFC-0003-OPENAI-COMPATIBLE-PROVIDER-CONTRACT.md)** | Accepted, implemented. \"OpenAI-compatible\" is a family of divergent shapes with no spec behind it, so per-provider facts are **resolved at save time or declared**, never guessed. A configured `base_url` is copied **verbatim** from vendor docs and never rewritten (`/v1` is neither universal nor positionally predictable — DeepSeek is root-mounted, Groq is `/openai/v1`); a **user-supplied** URL is rooted by `services/llm/endpoints.py::resolve_base_url`, which sends the SDK's own `models.list()` to the URL then to it plus `/v1` and adopts only a body that **is an OpenAI list** — a status alone proves nothing, because LM Studio answers HTTP 200 to routes it does not serve. A failed save writes and broadcasts nothing. One `resolve_credential` sends the stored key or the vendor-documented placeholder (`auth.placeholder_key`) and never `None` (which would make the SDK read `OPENAI_API_KEY` and ship it to a third-party URL); no provider rewrites a key. A 2xx with no `choices` and an error body raises `PROTOCOL` naming the redacted URL. **Named endpoints (D13–D17)**: any server is a provider reference `openai_compatible:<slug>` stored exactly like Ollama (`{ref}` + `{ref}_proxy`), selectable from every agent (the `provider` field is a loader-driven `ProviderRef`, not a `Literal`), from the `openaiCompatibleChatModel` node (its field is `endpoint`, not `provider`, to dodge the panel's stored-key effect) and the global default picker; kind detected once from native routes by body shape; context and price from the server first (Ollama/LM Studio SDK probes, llama.cpp `/props`, vLLM `max_model_len`), then LiteLLM's table for generic servers only, then conservative defaults; local-model entries and the LiteLLM cache live under DATA_DIR, never in the tracked `config/model_registry.json`. RLM cannot route an endpoint and refuses one loudly. Gates AG1–AG20 (AG5 retired), `ProviderSpec` gains no field. |\n| **[Event Waiter System](./docs-internal/event_waiter_system.md)** | In-memory asyncio.Future waiter for push-based trigger nodes on the canvas-Run path (WhatsApp, Telegram, Webhook, Chat, Task completion). Deployed triggers ride the Temporal canary path; the Redis-Streams backend was retired in Wave 15.3 |\n| **[Credentials Encryption](./docs-internal/credentials_encryption.md)** | Fernet + PBKDF2 encryption pipeline, separate credentials.db, two credential systems (OAuth vs API keys), multi-backend abstraction |\n| **[Status Broadcaster](./docs-internal/status_broadcaster.md)** | WebSocket-first communication: StatusBroadcaster singleton, live count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`, broadcast message types, Android two-state model |\n| **[RLM Service](./docs-internal/rlm_service.md)** | Recursive Language Model agent with REPL-based execution (llm_query, rlm_query, FINAL) |\n| **[Claude Code Agent](./docs-internal/claude_code_agent.md)** | Hub for the Claude Code agent — routes to architecture, interactive mode, CLI framework, canonical-patterns RFC, and the 5 CLI snapshot references. |\n| **[CLI Agent Framework](./docs-internal/cli_agent_framework.md)** | Multi-provider CLI runtime (Claude Code / Codex / Gemini): `AICliService.run_batch`, per-task worktree isolation, FastMCP bridge, **memory bridge** (host-minted `--session-id` on cold spawn + intra-process stream-json multi-turn + `--resume <last_session_id>` for memory-bound runs and crash recovery — never `--continue`, which the CLI resolves only against interactive sessions — all in a stable per-workflow git worktree `<workspace>/<node>/wt_session` branched off the enclosing repo, never the repo root itself; `node_parameters_updated` broadcast on every successful turn). **Plugin-folder layout** (post-cutover): all claude-specific code lives in [`server/nodes/agent/claude_code_agent/`](./server/nodes/agent/claude_code_agent/) — `_provider.py`, `_pool.py`, `_skills.py`, `_oauth.py`, `_handlers.py` — and self-registers via three `factory.py` registries (`register_provider` / `register_session_pool` / `register_skill_materialiser`) plus `register_ws_handlers`. The generic framework at `services/cli_agent/` imports nothing from `nodes/`. |\n| **[Claude Code Interactive Mode](./docs-internal/claude_code_interactive_mode.md)** | The interactive-mode cutover: OpenCompany no longer uses `claude -p` headless. `ClaudeSessionPool` (keyed by the RFC-0002 conversation key `context_bridge.pool_key`, legacy fallback `simpleMemory.node_id`) spawns `claude` as a plain subprocess with stdio pipes — **no PTY** — and drives it over the VSCode-extension protocol: `--output-format stream-json --input-format stream-json --verbose --ide`. User prompts written as JSON to `proc.stdin` (`{\"type\":\"user\",\"message\":{\"role\":\"user\",\"content\":\"...\"}}\\n`); `system/init` / `assistant` / `result` / `system/compact_boundary` events stream back on `proc.stdout` (parsed by a background `stdout_reader_task` — the on-disk JSONL is persistence-only, not the runtime contract, because `result` events are stdout-only in stream-json mode). Cross-platform via plain pipes (the earlier PTY pattern was broken on Windows because pywinpty/ConPTY's emulated stdin never reached claude's Ink TUI keystroke handler). Stays in interactive billing — entrypoint `claude-vscode`, NOT `sdk-cli`. Multi-turn within one warm subprocess preserves the session UUID (verified end-to-end); cross-batch continuity via a host-minted `--session-id <uuid4>` on the first cold spawn and `--resume <UUID>` afterwards (never `--continue`, which the CLI resolves only against interactive sessions). Four typed CloudEvents (`claude.session.{spawned,cleared,terminated,usage}`) fire from the pool. `/compact` events forward to `CompactionService`. Every Claude run routes through the pool (unbound runs get an ephemeral session per task, terminated after the batch); `AICliSession` (PTY + JSONL watcher) is no longer used for Claude because a PTY stdin makes the CLI reject stream-json input and that path never delivered the prompt (GitHub #133 / #134). A child exiting without a `result` wakes `send_turn` on stdout EOF with the exit code instead of burning the turn timeout. The CLI version is pinned via `package_version` in `config/ai_cli_providers.json`. |\n| **[CLI Agent Canonical Patterns RFC](./docs-internal/cli_agent_canonical_patterns_rfc.md)** | Audit of OpenCompany's `services/cli_agent` against the official Claude Code spec — six invariants (skills-as-files, MCP-only transport, `list_changed`, deferral, visible-tool filtering, native-session-continuity-via-stable-cwd) with current implementation status. |\n| **[Claude Code CLI Reference (snapshot)](./docs-internal/claude_code_cli_reference.md)** | Verbatim snapshot of [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference) — every CLI subcommand + flag + system-prompt-flag matrix + the subset we emit from `nodes/agent/claude_code_agent/_provider.py`. Fetched 2026-05-11. |\n| **[Claude Code Env Vars (snapshot)](./docs-internal/claude_code_env_vars_reference.md)** | Categorised [code.claude.com/docs/en/env-vars](https://code.claude.com/docs/en/env-vars) snapshot — auth, Bedrock/Vertex, model, bash, MCP, telemetry, session/debug, paths. Documents `CLAUDE_CONFIG_DIR`, `MAX_MCP_OUTPUT_TOKENS`, `ENABLE_TOOL_SEARCH` which we touch directly. |\n| **[Claude Code Permission Modes (snapshot)](./docs-internal/claude_code_permission_modes_reference.md)** | Verbatim [code.claude.com/docs/en/permission-modes](https://code.claude.com/docs/en/permission-modes) — `default` / `acceptEdits` / `plan` / `auto` / `dontAsk` / `bypassPermissions` semantics, Shift+Tab cycle, protected paths. OpenCompany's default is `dontAsk` (`default_permission_mode` in `server/config/ai_cli_providers.json`). |\n| **[Claude Code Headless / Print Mode (snapshot)](./docs-internal/claude_code_headless_reference.md)** | Verbatim [code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless) — `claude -p`, `--output-format` (`text` / `json` / `stream-json`), `--input-format`, `--bare`, stream-json event schema (`system/init`, `system/api_retry`, `system/plugin_install`). OpenCompany no longer uses `-p`; the pool path emits `--output-format stream-json --input-format stream-json --verbose --ide` over stdio pipes (interactive billing). The event schema is the contract `nodes/agent/claude_code_agent/_pool.py` parses off `proc.stdout`. |\n| **[Claude Code Skills (snapshot)](./docs-internal/claude_code_skills_reference.md)** | Verbatim [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) — `SKILL.md` frontmatter spec, discovery paths, content lifecycle, `context: fork`, dynamic context injection via `` !`<command>` ``. The spec OpenCompany materialises connected skills against in `_pre_spawn`. |\n| **[Autonomous Agent Creation](./docs-internal/ARCHIVE/autonomous_agent_creation.md)** | *Archived* external research notes on Code Mode agents; the shipped plugin is [server/nodes/agent/autonomous_agent/](./server/nodes/agent/autonomous_agent/) |\n| **[Polyglot Server](../polyglot-server/ARCHITECTURE.md)** | Plugin registry microservice with MCP gateway (optional integration) |\n| **[Authentication](./docs-internal/authentication.md)** | JWT/cookie auth: toggle, single/multi mode, backend + frontend, middleware, startup retry. |\n| **[Credentials Panel](./docs-internal/ARCHIVE/credentials_panel.md)** | *Archived* pre-refactor modal reference; its §5 invariants are still what `server/tests/credentials/` and `client/src/test/` lock. The live, config-driven modal is described in [Frontend Architecture → Credentials](./docs-internal/frontend_architecture.md). |\n| **[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). |\n| **[Node Parameter Panel](./docs-internal/node_panels.md)** | Three-section node config UI (Input / Parameters / Output) logic-flow reference. |\n| **[Deployment (legacy reference)](./docs-internal/deployment_legacy.md)** | `company deploy` CLI summary + the historical Docker Compose topology. |\n| **[Docker (self-hosting)](./docs-internal/docker.md)** | One-container image built from source (`docker/Dockerfile`, `docker-compose.yml`). The build stage runs the canonical `bun install --frozen-lockfile` + `bun run build` (then `uv sync --frozen --no-dev --extra docs`); the runtime stage keeps only what `core/approot.py` reads. uvicorn runs directly, the way the desktop shell runs it (never `company serve`, whose supervisor would add a second tree-kill deadline, `backend_shutdown_grace_seconds` in `cli/_common.py`, independent of compose's `stop_grace_period`). All state on one `/data` volume; secrets minted on first start into `OPENCOMPANY_ENV_FILE=/data/opencompany.env`; Temporal embedded (CLI pre-seeded through named-volume copy-up); no Redis; no Node (`/usr/local/bin/node` links to bun). Optional system tools come only through the `EXTRAS` build arg (`browser`: Chromium + Xvfb + uv; `git`). Compose publishes the port on `127.0.0.1` only, because login is off until the operator turns it on. `/ws/internal` (where workers call back and `execute_node` runs any node) requires the `SECRET_KEY`-derived `X-OpenCompany-Internal-Token`, and every WebSocket handshake refuses a foreign `Origin` (`services/authz/ws_session.py`; see [Authentication](./docs-internal/authentication.md)). |\n| **[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). |\n\n## Design Principles & Standards\n\n**CRITICAL: Always follow these principles when modifying backend execution code:**\n\n### 0. Adding a new node — the canonical recipe (Wave 11.H)\n\nEvery plugin is a self-contained folder under `server/nodes/<group>/<plugin>/` rooted at `__init__.py`. `BaseNode.__init_subclass__` auto-registers metadata, schemas, handlers, and Temporal activity on import — zero edits anywhere else.\n\n**Where to look:**\n- [server/nodes/README.md](./server/nodes/README.md) — 5-minute walkthrough with the canonical folder template\n- [docs-internal/plugin_system.md → Self-contained plugin folders](./docs-internal/plugin_system.md#self-contained-plugin-folders) — full reference, plus the **generic registries** plugins self-wire into (`grep -rn '^def register_' server/services server/core` for the live list)\n- [docs-internal/node_creation.md](./docs-internal/node_creation.md) — decision tree for action / trigger / tool / dual-purpose / specialized-agent nodes\n- [server/nodes/telegram/](./server/nodes/telegram/) — reference implementation of the multi-file split (`_service.py` / `_handlers.py` / `_filters.py` / `_refresh.py` / `_credentials.py` / `_events.py` / two node files)\n\n**Wire format is the contract — not module paths.** The frontend identifies plugin commands by WebSocket message-type strings (`telegram_connect`, `telegram_status`, …). Moving handler bodies between Python files is invisible to the frontend so long as the registered keys stay the same.\n\n**Don't** import the plugin folder from `routers/` / `services/` / another `nodes/` subfolder. **Don't** edit `event_waiter.py` / `status_broadcaster.py` / `routers/websocket.py` to add a plugin's handler / filter / refresh — register from the plugin's `__init__.py` instead.\n\n### 1. Use Existing Patterns - No Tribal Code\n- **Never add ad-hoc workarounds** - Use the established patterns documented in DESIGN.md\n- **Conductor Decide Pattern** - All orchestration goes through `_workflow_decide()` loop\n- **Continuous Scheduling** - Dependent nodes start immediately via `asyncio.wait(FIRST_COMPLETED)`; the layer-barrier Fork/Join helper (`_execute_parallel_nodes`) was removed\n- **Prefect Task Caching** - Cache results via `hash_inputs()` and `generate_cache_key()`\n- **Distributed Locking** - Redis SETNX, used only on the default-off `REDIS_ENABLED=true` parallel branch (`services/workflow.py::_execute_parallel`); Temporal owns concurrency on the shipped path\n\n### 2. State Management\n- **Isolated Execution Contexts** - Each workflow run has its own `ExecutionContext`\n- **No Global State** - Never use module-level variables for execution state\n- **Cache Persistence** - Execution state persists to SQLite by default; Redis only when `REDIS_ENABLED=true` (`core/config.py`, default `False`; no shipped configuration enables it)\n- **Explicit State Machines** - Tasks follow `TaskStatus` enum, workflows follow `WorkflowStatus`\n\n### 3. Separation of Concerns\n- **Models** (`models.py`) - Pure data structures, JSON-serializable, no business logic\n- **Cache** (`cache.py`) - Redis persistence abstraction only\n- **Executor** (`executor.py`) - Orchestration logic, decide pattern implementation\n- **Recovery** (`recovery.py`) - Heartbeat and crash recovery only\n- **Conditions** (`conditions.py`) - Edge condition evaluation for runtime branching\n\n### Backend Service Architecture (n8n-inspired)\nThe workflow backend follows modular architecture patterns from n8n, Temporal, and Conductor:\n\n(abbreviated: only the modules discussed in this file; see the directory for the full set)\n\n```\nserver/services/\n├── workflow.py # Facade (~840 lines) - thin coordinator\n├── node_executor.py # Single node execution with registry pattern\n├── parameter_resolver.py # Template variable resolution\n├── agent_team.py # AgentTeamService for multi-agent coordination\n├── model_registry.py # ModelRegistryService - model constraints from OpenRouter + llm_defaults\n├── pricing.py # LLM and API cost calculation (loads config/pricing.json)\n├── markdown_formatter.py # GFM markdown to platform-specific formatting (Telegram HTML, WhatsApp, plain)\n├── ws_handler_registry.py # Plugin-owned WS commands self-register here (Wave 11.H)\n├── todo_service.py # TodoService singleton for writeTodos tool (JSON per-session state)\n├── media/ # Media transport — vendor-neutral, kind-agnostic (see media_transport.md)\n│ ├── refs.py # FileRef (base; FileKind = file|audio|image|video|document)\n│ │ # + AudioRef(FileRef), the probed-container narrowing.\n│ │ # A reference, never bytes; extra=\"forbid\" makes that structural.\n│ │ # kind=\"audio\" ASSERTS inspect_audio ran — never guess it.\n│ ├── preview.py # Single owner of the inline-vs-attachment rule (serves_inline /\n│ │ # preview_kind). TWO consumers: routers/workspace.py picks the\n│ │ # Content-Disposition, the gallery listing sets each row's\n│ │ # `preview`. One function, so the panel can never offer a preview\n│ │ # the route refuses to serve inline.\n│ ├── workspace.py # write_audio / resolve_media / read_media_bytes / coerce_file_param\n│ ├── inspect.py # tinytag -> wave -> PCM arithmetic; NEVER raises\n│ └── limits.py # every size constant, each annotated with what it defends against\n├── provider_registry.py # Generic ProviderSpec + ProviderRegistry + lazy exception refs.\n│ # Shared by services/llm and nodes/speech (which owns two, one per\n│ # direction). Registration must never import a provider SDK.\n├── memory/ # Native Markdown/JSONL/runtime/vector-store helpers\n├── memory_store.py # In-memory conversation sessions using native Message values\n├── skill_prompt.py # Skill system prompt builder (injects SKILL.md for personality skills)\n├── text.py # TextService (text generation nodes)\n├── chat_client.py # JSON-RPC 2.0 WebSocket client for chat backend\n│ # (Claude Code CLI wrapper + isolated OAuth moved to\n│ # nodes/agent/claude_code_agent/_oauth.py — CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/)\n├── tracked_http.py # HTTPX event hooks for automatic API cost tracking\n├── handlers/ # Cross-cutting orchestration only (Wave 11: 16 → 4 files, 12.8K → 1.1K LOC)\n│ ├── tools.py # AI-tool dispatch + agent delegation (~1,020 LOC)\n│ ├── triggers.py # Generic event-trigger handler\n│ ├── todo.py # writeTodos execution shim (used by every agent)\n│ └── __init__.py # Docstring only (google_auth.py retired into nodes/google/_auth_helper.py)\n├── llm/ # Native LLM provider SDKs for chat and every new agent execution\n│ ├── __init__.py # Public API exports\n│ ├── protocol.py # ThinkingConfig, Message, LLMResponse, LLMProvider Protocol\n│ ├── config.py # ProviderConfig, resolve_max_tokens, resolve_temperature, split_provider_ref, resolve_credential\n│ ├── endpoints.py # RFC-0003 save-time half: resolve_base_url roots a user-supplied URL, redact_url, endpoint listing, unconfigured_endpoint_message\n│ ├── media.py # Tool-result images: refs in durable state, bytes only at the provider boundary (hydrate_image_blocks)\n│ ├── schema.py # JSON-schema preparation for native provider tool APIs (compile_tool_schema)\n│ ├── 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)\n│ ├── unifier.py # ChatUnifier facade — routes chat/fetch_models, translates typed SDK errors → NodeUserError, applies incompatible_models filter\n│ ├── vertex.py # Vertex / Agent-Platform key handling\n│ ├── messages.py # filter_empty_messages, is_valid_message_content\n│ └── providers/ # Per-provider implementations (+ _compat.py: every name in _COMPAT_PROVIDERS, plus the base-URL-less openai_compatible registration that serves named endpoints)\n│ ├── anthropic.py # AnthropicProvider (anthropic SDK)\n│ ├── openai.py # OpenAIProvider (openai SDK)\n│ ├── gemini.py # GeminiProvider (google-genai SDK)\n│ └── openrouter.py # OpenRouterProvider (extends OpenAIProvider)\n├── proxy/ # Residential proxy provider management\n│ ├── __init__.py # Exports get_proxy_service, ProxyService\n│ ├── service.py # ProxyService singleton - provider selection, URL generation\n│ ├── providers.py # TemplateProxyProvider - JSON url_template formatting\n│ └── models.py # ProxyProvider, RoutingRule, SessionType enums\n├── deployment/ # Event-driven deployment lifecycle\n│ ├── __init__.py\n│ ├── state.py # DeploymentState, TriggerInfo dataclasses\n│ ├── triggers.py # TriggerManager (cron, event triggers)\n│ └── manager.py # DeploymentManager (deploy, cancel, status)\n├── execution/ # Parallel workflow orchestration\n│ ├── models.py # ExecutionContext, TaskStatus\n│ ├── executor.py # WorkflowExecutor with decide pattern\n│ ├── cache.py # Cache persistence (Redis/SQLite)\n│ └── recovery.py # Crash recovery\n└── temporal/ # Distributed workflow execution (optional)\n ├── __init__.py # Exports TemporalExecutor, TemporalClientWrapper\n ├── workflow.py # MachinaWorkflow orchestrator\n ├── activities.py # Class-based activities with connection pooling\n ├── worker.py # TemporalWorkerManager + run_standalone_worker()\n ├── executor.py # TemporalExecutor interface\n ├── client.py # Temporal client wrapper\n └── ws_client.py # WebSocket connection pool\n\nserver/core/\n├── container.py # Dependency injection container\n├── database.py # SQLite database with cache CRUD methods\n├── cache.py # CacheService with Redis/SQLite/Memory fallback\n├── config.py # Application configuration\n├── logging.py # Logging configuration\n├── 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.\n├── 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)\n├── encryption.py # Fernet encryption with PBKDF2 key derivation\n├── credentials_database.py # Async SQLite for encrypted API keys and OAuth tokens\n└── credential_backends.py # Multi-backend abstraction (Fernet, Keyring, AWS)\n\nserver/models/\n├── cache.py # CacheEntry SQLModel for SQLite cache\n├── auth.py # User model with bcrypt\n└── database.py # ConversationMessage, NodeParameter, ToolSchema, ChatMessage, TokenUsageMetric, APIUsageMetric, CompactionEvent, SessionTokenState, UserSettings, ProviderDefaults, AgentTeam, TeamMember, TeamTask, AgentMessage tables\n\nserver/config/\n├── llm_defaults.json # Per-provider defaults (model, base_url, max_output_tokens, context_length, temperature_range, reasoning_models, thinking_type, ...) AND a top-level `agent` block (recursion_limit, default_temperature, compaction.ratio) that drives the agent loop and CompactionService. recursion_limit and compaction.ratio are last-resort fallbacks: AGENT_RECURSION_LIMIT / COMPACTION_RATIO via core.config.Settings win (ModelRegistryService.get_agent_defaults); default_temperature is JSON-only.\n├── model_registry.json # Cached model data from OpenRouter (auto-refreshed). Models from the user's own servers and LiteLLM's table are cached under DATA_DIR instead (local_models.json, litellm_models.json), never here.\n├── pricing.json # LLM and API pricing config\n├── google_apis.json # Google Workspace API endpoints, scopes, OAuth callback paths\n├── email_providers.json # IMAP/SMTP provider presets (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, custom)\n├── speech_defaults.json # Per-provider TTS/STT capabilities, per-direction, with per-model overrides\n # ({\"whisper-1\": [...], \"_default\": [...]} resolved exact -> longest-prefix ->\n # _default). Drives the provider dropdowns, voice/model loaders and validation.\n # Boolean flags default PERMISSIVE so a missing declaration never silently\n # disables a working feature. Read by nodes/speech/_config.py.\n└── translate_defaults.json # Same shape, three capability blocks per provider (translate /\n # transliterate / detect). Both files are resolved by the shared\n # services/plugin/capabilities.CapabilityConfig.\n\nserver/nodejs/ # JS/TS executor sidecar — Express on bun (the only JS runtime shipped)\n├── package.json # Dependencies: express + express-rate-limit (both inlined by `bun build --target=bun`); engines.bun >= 1.4.0\n├── tsconfig.json # TypeScript config (ES2024)\n└── src/\n └── index.ts # Express server (/execute, /health, /packages/*)\n```\n\n### Polyglot Server Integration (Optional)\nOpenCompany 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).\n\n### JS/TS Code Executor (bun sidecar)\nPersistent 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).\n\n**Architecture:**\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Python Backend (PYTHON_BACKEND_PORT) │\n│ ┌────────────────┐ HTTP/JSON ┌──────────────────┐ │\n│ │ NodeJSClient │◄──────────────────►│ bun sidecar │ │\n│ │ (aiohttp) │ NODEJS_EXECUTOR_PORT │ (Express) │ │\n│ └────────────────┘ └──────────────────┘ │\n│ ▲ │\n│ │ │\n│ ┌──────┴─────────┐ │\n│ │ nodes/code/ │ │\n│ │ plugins │ │\n│ └────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n**Files:**\n```\nserver/nodejs/\n├── package.json # Dependencies: express + express-rate-limit (both inlined into the bundle; the limiter guards the /packages routes). Scripts: build = `bun build src/index.ts --target=bun --outfile=dist/index.js`,\n│ # start = `bun dist/index.js`, dev = `bun --watch src/index.ts`; engines = { bun >= 1.4.0 }. No esbuild, no tsx.\n├── tsconfig.json # TypeScript config (ES2024)\n├── dist/index.js # Self-contained bundle (gitignored; built by `company build` / the desktop stage script; missing from the 0.2.x registry tarball, see errors.md #26)\n└── src/\n └── index.ts # Express server with /execute, /health, /packages/*\n\nserver/core/js_runtime.py # How the backend finds bun (OPENCOMPANY_BUN_BIN, else PATH) + the shared packages tree helpers\n\nserver/nodes/code/ # Executor plugins (javascript_executor, typescript_executor) + _runtime.py (spawns [bun, dist/index.js]) + _client.py\n```\n\n**Endpoints:**\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/health` | GET | Health check: `runtime: \"bun\"`, `runtime_version`, and still `node_version` (the Node API level bun reports) |\n| `/execute` | POST | Execute JS/TS code with input_data and timeout (`language: \"typescript\"` is type-stripped by `Bun.Transpiler` first, then both run in a `node:vm` context) |\n| `/packages/install` | POST | Install npm-registry packages into user-packages via `bun add` (run through `process.execPath`, i.e. the sidecar's own bun). Rate-limited to 120 req/min |\n| `/packages` | GET | List installed packages from the user-packages dir's `package.json`. Rate-limited to 120 req/min, sharing the window with `/packages/install` |\n\n**Environment Variables:**\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `NODEJS_EXECUTOR_URL` | `http://localhost:${NODEJS_EXECUTOR_PORT}` | Server URL for Python client |\n| `NODEJS_EXECUTOR_TIMEOUT` | `30` | Request timeout in seconds |\n| `NODEJS_EXECUTOR_PORT` | see `.env.template` | Server port |\n| `NODEJS_EXECUTOR_HOST` | `localhost` | Server host |\n| `NODEJS_EXECUTOR_BODY_LIMIT` | `10mb` | Max request body size |\n\n**Key Modules:**\n\n| Module | Responsibility | Pattern |\n|--------|---------------|---------|\n| `workflow.py` | Facade delegating to specialized modules | Facade Pattern |\n| `node_executor.py` | Execute single node via handler registry | Registry + functools.partial |\n| `parameter_resolver.py` | Resolve `{{node.field}}` templates | Compiled regex |\n| `deployment/manager.py` | Deploy/cancel workflows, spawn runs | n8n Deployment |\n| `deployment/triggers.py` | Setup cron/event triggers | Event-driven |\n| `deployment/state.py` | Immutable state dataclasses | Dataclass |\n| `temporal/executor.py` | Temporal-based distributed execution | Per-node Activities |\n| `temporal/workflow.py` | Pure orchestrator (no business logic) | FIRST_COMPLETED |\n| `temporal/worker.py` | Worker lifecycle + horizontal scaling | Connection Pooling |\n\n**NodeExecutor Registry Pattern:**\n```python\nclass NodeExecutor:\n def _build_handler_registry(self) -> Dict[str, Callable]:\n return {\n 'start': handle_start,\n 'aiAgent': _dispatch_plugin_node, # Wave 11: routes via BaseNode.execute()\n # ... registry-based dispatch instead of if-else chains\n }\n```\n\n### 4. Dependency Injection\n```python\n# Correct: Receive dependencies via constructor\nclass WorkflowExecutor:\n def __init__(self, cache: ExecutionCache, node_executor: Callable):\n self.cache = cache\n self.node_executor = node_executor\n\n# Wrong: Import and use global singletons\nfrom services.some_service import global_instance\n```\n\n### 5. Error Handling & Logging\n- **Log at appropriate levels**: DEBUG for routine operations, INFO for significant events, ERROR for failures\n- **Never suppress errors silently** - Always log or propagate\n- **Use structured logging** - Include context (node_id, execution_id, etc.)\n- **Configurable via `.env`**: Set `LOG_LEVEL=DEBUG` for verbose output, `LOG_LEVEL=INFO` for production\n\n#### Logging Configuration\n```bash\n# In server/.env\nLOG_LEVEL=INFO # Default: INFO, DEBUG for verbose\nLOG_FORMAT=json # 'json' (default) or 'text' for console\nLOG_FILE= # Optional rotating-file destination\nLOG_FILE_MAX_BYTES=10485760 # 10 MiB ceiling per file\nLOG_FILE_BACKUP_COUNT=5 # Keep 5 backups (50 MiB total cap)\n```\n\n**What logs at each level:**\n- `DEBUG`: Template resolution, parameter resolution, node execution details, event waiter registration, downstream traversal\n- `INFO`: Workflow completion, deployment start/stop, significant state changes\n- `ERROR`: Failures, exceptions, validation errors\n\n#### Logging Infrastructure (canonical patterns)\n\n**Console mode is timestamp-less by design.** The supervisor\n(`cli/colors.py`) prepends `[HH:MM:SS.fff]` to every aggregated\nline, so `configure_logging` does NOT add an inner `TimeStamper` in\nconsole mode. JSON mode keeps ISO timestamps for machine consumers.\nHelpers that print pre-logger init (`_startup_log` in `main.py`,\n`_clog` in `core/container.py`) emit raw `print()` so the CLI prefix\nis the single timing source.\n\n**Context propagation via `structlog.contextvars`.** Bind once at the\nentry point; every log record inside that async context picks the\nfields up automatically. Stdlib `contextvars` rides `asyncio.gather`\nchild tasks.\n\n```python\nfrom core.logging import log_context\n\nasync with log_context(workflow_id=wf_id, node_id=node_id):\n await do_work() # all logs inside carry workflow_id + node_id\n```\n\n`BaseNode.execute()` already wraps its body in\n`log_context(node_id, node_type, workflow_id?)` so plugin operation\nlogs are auto-tagged — don't pass these as kwargs at each call site.\n\n**Per-plugin OpenTelemetry span.** `BaseNode.execute()` opens a\n`node.<type>.execute` span with attributes `node.id` / `node.type` /\n`workflow.id` around the operation body. Single edit instruments every\nplugin — no per-plugin span code needed.\n\n**Source-tag resolver for the Terminal UI panel.** `record.name`\ncollapses to a ≤12-char tag via `_resolve_source_tag` in\n`core/logging.py`:\n\n1. `nodes.<plugin>.*` → `<plugin>` (auto-rule; no per-plugin entry)\n2. `routers.<name>.*` → `<name>` (auto-rule)\n3. Explicit registry `_LOG_SOURCE_TAGS` — only for cross-cutting\n services with long module names (`workflow_validator` → `validator`,\n `status_broadcaster` → `broadcaster`, `user_auth` → `auth`, etc.)\n4. Second-segment fallback (`services.ai` → `ai`)\n\nPlugins that genuinely want a different label from their folder name\ncall `register_log_source_tag(prefix, tag)` from their package\n`__init__.py` — same self-registration pattern as the other generic\nplugin registries (see the Plugin System row at the top of this file).\n\n**RotatingFileHandler** swaps in when `LOG_FILE` is set — no\nunbounded log growth.\n\n**NodeUserError vs Exception contract** (`services/plugin/base.py`):\n- `NodeUserError` → single WARN line, no traceback, structured response\n- `PermissionError` annotated with `.provider` / `.reason` / `.auth` →\n `error_type=\"PermissionDeniedError\"` + `credential` envelope block +\n CloudEvents `credential.{auth}.runtime_failed` broadcast\n- Bare `Exception` → `logger.exception` with full traceback\n\nReach for `NodeUserError` for any user-correctable failure\n(missing required field, unknown enum value, bad regex). Reserve\n`RuntimeError` / `Exception` for genuinely unexpected server bugs.\n\n**Output contract enforcement** (`BaseNode._serialize_result` in\n`services/plugin/base.py`): the declared `Output` Pydantic model is\nenforced at the serialization boundary, FastAPI-`response_model` style.\nDict results validate via `Output.model_validate(...).model_dump(mode=\"json\",\nexclude_unset=True)`; `BaseModel` results dump `mode=\"json\"`; violations\nproduce an `error_type=\"OutputValidationError\"` envelope at the producer.\nRules: prefer returning the `Output` instance; never put raw third-party\nobjects (SDK results, dataclasses) or pre-stringified JSON into result\ndicts — return plain lists/dicts; Params fields that may receive\nLLM-stringified JSON args coerce with `field_validator(mode=\"before\")`\n(canonical: `AndroidServiceParams._coerce_parameters`,\n`WriteTodosParams._coerce_todos`). Below the plugin layer, the SQLAlchemy\nengine sets `json_serializer` backed by `pydantic_core.to_jsonable_python`\n(`core/database.py`) so every JSON column tolerates dataclasses /\ndatetimes / enums / sets. Full spec:\n[docs-internal/plugin_system.md → Output contract enforcement](./docs-internal/plugin_system.md);\nlocked by `server/tests/test_output_contract.py`.\n\n### 6. Cleanup & Lifecycle\n- **Use existing teardown methods** - e.g., `_teardown_all_cron_triggers()` for cron cleanup\n- **Cleanup in finally blocks** - Ensure resources are released even on error\n- **No orphan prevention hacks** - Trust the existing lifecycle management\n\n### 7. Frontend Design + Theme System (strict)\n\n**Always use the existing design and theme systems.** Tribal styling reintroduced anywhere defeats the migration. The following rules are non-negotiable for any new or edited frontend file:\n\n1. **Compose shadcn primitives** from [client/src/components/ui/](./client/src/components/ui/) — `Button`, `Badge`, `Alert`, `AlertDialog`, `Dialog`, `DropdownMenu`, `Popover`, `Command`, `Select`, `Progress`, `Tooltip`, `Tabs`, `Card`, `Input`, `Textarea`, `Switch`, `Checkbox`, `Slider`, `Label`, `Form`, `Collapsible`, `Accordion`, `Skeleton`, `Sonner`. **Do not hand-roll** modals, dropdowns, menus, toasts, dialogs, or buttons when a primitive exists. Add `bun x shadcn@latest add <name>` if the primitive is missing.\n2. **Action buttons → `<ActionButton intent=\"...\">`** ([client/src/components/ui/action-button.tsx](./client/src/components/ui/action-button.tsx)). The `intent` prop is a semantic role (`run | stop | save | config | secret | tools`), never a palette color. Never re-introduce the `actionButtonStyle()` / hand-built colored buttons.\n3. **Style with Tailwind classes**, not `style={{...}}`. Inline `style` is allowed only for genuinely dynamic values (React Flow `<Handle>` positioning, runtime-computed coordinates, dynamic per-definition `nodeColor` on canvas nodes).\n4. **Use the token tier table** in [docs-internal/frontend_architecture.md](./docs-internal/frontend_architecture.md#tokens--theming):\n - Generic chrome / status → shadcn semantic tokens (`bg-card`, `text-muted-foreground`, `border-border`, `text-success`, `bg-destructive`, `text-warning`, `text-info`, `bg-accent`, etc.)\n - Node-type-themed surfaces → `--node-X` role tokens (`bg-node-agent`, `bg-node-model-soft`, `border-node-skill-border`, `text-node-trigger`, `text-node-workflow`, `bg-node-tool-soft`)\n - Toolbar / panel actions → `--action-X` semantic role tokens (`bg-action-run-soft`, `text-action-stop`, `border-action-config-border`, etc.) for icon-only buttons + dropdown items; `<ActionButton intent=\"...\">` for the standard \"soft tinted button\" pill\n - **No palette names in components.** `bg-dracula-green` etc. are forbidden in non-decorative code; always go through `--action-X` or `--node-X`\n5. **No opacity arithmetic at call sites.** `bg-primary/10`, `border-node-agent/30`, `${color}25` template literals are forbidden. If a unique tint is needed, add a new variant to the theme (e.g., `--node-X-soft`, `--node-X-border`) and use it by name.\n6. **No theme-locked names in non-decorative code.** Avoid `bg-dracula-purple`, `text-dracula-cyan`, etc. unless the constant accent is intentional (action-button palette). Prefer the role token (`bg-node-agent`) so future themes redefine without code edits.\n7. **No `useAppTheme()` in new files.** It is grandfathered for the canvas node components, which interpolate per-definition `nodeColor`; `Dashboard.tsx` still reads layout and timing constants from it, and the two panels in `components/maps/` still style inline through it. Every other surface uses Tailwind + the tokens above.\n8. **Icons → `lucide-react`.** Inline SVGs are reserved for non-iconographic graphics (charts, decorative shapes). Replace any `<svg>...</svg>` icon you encounter while editing. **Icon size is a token, never a class**: backend-declared node/provider icons render through `<NodeIcon size={...}>` with `theme.nodeSize.squareIcon` on canvas nodes (36px, the one node-icon size) or a `theme.iconSize.*` step elsewhere, and `NodeIcon` applies that token as width, height AND emoji font size so every icon kind draws at the same edge. Never pass `h-*` / `w-*` / `text-*` sizing to it — the theme type scale maps `text-3xl` to 44px, which is how emoji nodes once painted half again larger than SVG-backed nodes beside them.\n9. **Any `draggable` element that performs a function must ship a pointer-operable, non-drag control reaching the same end state through the same write path.** WCAG 2.2 SC 2.5.7 (Level AA); the sufficient technique is [G219](https://www.w3.org/WAI/WCAG22/Techniques/general/G219), the failure is [F108](https://www.w3.org/WAI/WCAG22/Techniques/failures/F108). Two traps worth stating: **keyboard support does not discharge it** — the Understanding doc is explicit that an equivalent counts only \"*unless that equivalent keyboard operation also provides controls that can be clicked or tapped with a pointer*\", because touchscreen users may have no keyboard. And the alternative must operate *the same function*, so extract the write into a shared helper rather than reimplementing it — see [`lib/workspaceFileAssign.ts`](./client/src/lib/workspaceFileAssign.ts), which both `ParameterRenderer.handleDrop` and `WorkspaceFilePickerDialog` call, with a test asserting the two paths produce deep-equal results.\n\nWhen in doubt, read [docs-internal/frontend_architecture.md](./docs-internal/frontend_architecture.md) before introducing new patterns.\n\n### 8. Naming Conventions (strict)\n\n| Layer | Convention | Examples |\n|---|---|---|\n| Python identifier (function, variable, module, file) | `snake_case` | `get_user_settings`, `auth_service`, `node_allowlist.py` |\n| JSON config key (read by Python) | `snake_case` | `enabled_nodes`, `default_llm_provider`, `compaction_ratio` |\n| WebSocket message type (Python ↔ TS wire) | `snake_case` | `get_node_allowlist`, `save_user_settings`, `validate_api_key` |\n| Database column / SQLModel field | `snake_case` | `created_at`, `auto_save_interval`, `examples_loaded` |\n| Python class | `PascalCase` | `NodeAllowlistService`, `WorkflowExecutor` |\n| TypeScript identifier | `camelCase` | `useNodeAllowlist`, `enabledNodes`, `isVisible` |\n| TypeScript file (React hook) | `camelCase` starting with `use` | `useNodeAllowlist.ts`, `useWebSocket.ts` |\n| Node type identifier | stored verbatim — **do not transform** | `aiAgent`, `httpRequest`, `openaiChatModel` (currently camelCase in this repo) |\n\n**Crossing the wire**: payload keys between Python and TS are always `snake_case` (Python writes the payload). The TS hook receives `snake_case` keys and binds them to local `camelCase` variables; do not auto-transform across languages with a serializer.\n\nDo not invent kebab-case or PascalCase variants for any of the rows above. The existing codebase is internally consistent — match it.\n\n### 9. Cache System Architecture (n8n Pattern)\nThe cache system follows n8n's pattern with automatic fallback:\n\n```\nOpt-in (REDIS_ENABLED=true): Redis → SQLite → Memory\nDefault (shipped): SQLite → Memory\n```\n\n**Configuration** (`server/.env`):\n```bash\nREDIS_ENABLED=false # Local dev: use SQLite\nREDIS_URL=redis://redis:6379 # Read only when REDIS_ENABLED=true; the `redis:` host is from the retired Compose topology (see deployment_legacy.md)\n```\n\n**CacheService** (`server/core/cache.py`):\n```python\nclass CacheService:\n def __init__(self, database: Database, settings: Settings):\n self._database = database\n self._settings = settings\n self._redis: Optional[Redis] = None\n self._memory_cache: Dict[str, Any] = {}\n\n async def get(self, key: str) -> Optional[str]:\n # Try Redis first (if enabled)\n if self._redis:\n value = await self._redis.get(key)\n if value: return value\n # Fall back to SQLite\n entry = await self._database.get_cache_entry(key)\n if entry: return entry.value\n # Fall back to memory\n return self._memory_cache.get(key)\n```\n\n**SQLite Cache Model** (`server/models/cache.py`):\n```python\nclass CacheEntry(SQLModel, table=True):\n __tablename__ = \"cache_entries\"\n key: str = Field(primary_key=True)\n value: str\n expires_at: Optional[float] = Field(default=None, index=True) # Unix timestamp\n created_at: float = Field(default_factory=time.time)\n```\n\n**Key Methods** (`server/core/database.py`):\n- `get_cache_entry(key)` - Get cache entry by key\n- `set_cache_entry(key, value, ttl)` - Set with optional TTL\n- `delete_cache_entry(key)` - Delete by key\n- `cleanup_expired_cache()` - Remove expired entries\n\n## Codebase Summary\n- **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).\n- **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 / dodo_payments / vercel / github / cloudflare / gcloud / aws.\n- **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.\n- **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`.\n\n## Frontend Performance Architecture\n\nThe frontend uses a layered cache + slice-subscription model so cold refreshes are instant and high-frequency status broadcasts do not cascade through the React tree. The patterns below are canonical -- follow them when adding new server-state queries, status broadcasts, or canvas node components.\n\n### TanStack Query persistence ([client/src/lib/queryPersist.ts](./client/src/lib/queryPersist.ts))\n- App is wrapped in `<PersistQueryClientProvider>` ([main.tsx](./client/src/main.tsx)) with a localStorage persister + `__APP_VERSION__` buster + 24h SWR window (RFC 5861).\n- Only queries with key prefixes `nodeSpec` / `nodeGroups` are dehydrated (see `PERSISTED_KEY_PREFIXES` / `shouldPersistQuery`). High-frequency / per-session queries stay in-memory.\n- Hard refresh paints from cached specs **before** the WS connects, so canvas nodes never flash placeholder icons.\n\n### `useNodeSpec` is a slice subscription, not a `useQuery` ([client/src/lib/nodeSpec.ts](./client/src/lib/nodeSpec.ts))\n- Reads via `useSyncExternalStore` against `queryClient.getQueryCache().subscribe(...)` filtered by `hashKey(['nodeSpec', type])`. Per-spec observer count is **0**; only the matching slot triggers a re-render.\n- Lazy fetch is one-shot via `useEffect`, gated on `isReady` (see below).\n- **Do not re-introduce `useQuery(['nodeSpec', type])`** anywhere -- N consumers would create N observers, all woken on every cache write.\n- **Critical: any cache entry consumed via `useSyncExternalStore` MUST set `gcTime: GC_TIME.FOREVER`** ([lib/queryConfig.ts](./client/src/lib/queryConfig.ts)). Slice subscribers don't register as observers, so without this override TanStack garbage-collects the entry after `GC_TIME.DEFAULT` (5 min) and every consumer reads `undefined`. Symptom: canvas nodes lose their icons + handles after idling on the page. Applies to `fetchNodeSpec`, `fetchNodeGroups`, `useNodeGroups`. The persistor in `lib/queryPersist.ts` only handles cross-reload survival, not in-session GC.\n\n### `nodeStatusStore` for high-frequency state ([client/src/stores/nodeStatusStore.ts](./client/src/stores/nodeStatusStore.ts))\n- Per-workflow node statuses live in a Zustand store (built on `useSyncExternalStore`). `useNodeStatus(id)` is a slice selector -- only the affected node's consumers re-render on a status tick.\n- Mirror this pattern when adding any new high-frequency push state. Do **not** put it on `WebSocketContext.value` -- that's a context fan-out trap.\n\n### `useAppStore` reads must be slice selectors, never whole-store destructure\n- Always `const x = useAppStore((s) => s.x)`, never `const { x } = useAppStore()`. The whole-store form re-renders the consumer on ANY mutation (sidebar toggle, unrelated workflow rename, parameter save on another node), which defeats `React.memo` + `nodePropsEqual` on the canvas. Setters are stable refs from Zustand — single-field selectors are the cheapest read.\n- Audited and converted across the canvas + parameter-panel hot paths: every node component, `Dashboard.tsx`, `useDragVariable`, `useParameterPanel`, `useReactFlowNodes`, `useWorkflowManagement`, `InputSection`, `MiddleSection`, `OutputPanel`, `ParameterRenderer`, `ParameterPanel`. New code should follow.\n\n### `isConnected` vs `isReady` -- gate every catalogue/spec query on `isReady` ([WebSocketContext.tsx](./client/src/contexts/WebSocketContext.tsx))\n- `isConnected` flips when the socket opens. `isReady` flips immediately after `drainPendingSends(ws)` inside `ws.onopen`; there is no init-burst gate any more (Wave 32).\n- The former `Promise.allSettled` init burst and its hardcoded `probeApiKey` loop are gone. Credential state comes from the `initial_status` broadcast and `useCatalogueQuery`'s `provider.stored` flag; terminal / chat / console history restore runs fire-and-forget after `setIsReady(true)`.\n- Queries that depend on backend-served catalogue data (`useCatalogueQuery`, `useNodeParamsQuery`, `useUserSettingsQuery`, `useNodeGroups`, `useNodeSpec` lazy fetch, prefetch effect) gate on `isReady` so queued sends replay first and they fire once on the live socket.\n- `WebSocketContext.value` is `useMemo`'d -- consumers only re-render when an actual field they read changes. Pending requests are rejected on `ws.onclose` so retries fire immediately on the new socket instead of waiting the 30 s `REQUEST_TIMEOUT`.\n\n### Catalogue invalidation is debounced\n- `invalidateCatalogue(queryClient)` in [`hooks/useCatalogueQuery.ts`](./client/src/hooks/useCatalogueQuery.ts) wraps `queryClient.invalidateQueries({ queryKey: CATALOGUE_QUERY_KEY })` with a 300 ms trailing-edge debounce via a single shared module-scope timer. **Always go through it** from broadcast handlers — direct `invalidateQueries` calls were the old pattern.\n- The broadcast handlers in `WebSocketContext.tsx` that touch the catalogue (`initial_status` / `full_status`, `api_key_status`, `credential_catalogue_updated`, `plugin_connection_status`, `twitter_oauth_complete`, `google_oauth_complete`, `google_status`) all route through it. An OAuth burst or multi-service reconnect collapses to one refetch instead of N back-to-back round-trips.\n\n### React.memo every canvas node component ([client/src/components/nodeMemoEquality.ts](./client/src/components/nodeMemoEquality.ts))\n- React Flow's documented requirement. Use the shared `nodePropsEqual` comparator -- it skips drag-state props (`xPos` / `yPos` / `dragging`) so the memo isn't defeated during drag.\n- Applies to `SquareNode`, `AIAgentNode`, `TriggerNode`, `StartNode`. Add new node components the same way.\n- Reference: https://reactflow.dev/learn/advanced-use/performance\n\n### Icon + color — per-plugin folder + visuals.json fallback\n\nPlugin icons and colors live co-located in the plugin folder; `visuals.json` is the legacy central registry for plugins that predate it. Resolution chain: **co-located SVG (`icon_<nodeType>.svg` → `icon.svg`) → the plugin's own `meta.json` → `visuals.json`**, documented in [server/nodes/README.md → Icon + color](./server/nodes/README.md) and [docs-internal/plugin_system.md](./docs-internal/plugin_system.md).\n\n**For a node that belongs to a recognisable product, ship the brand mark as an SVG in the plugin folder** — `icon_<nodeType>.svg` per node type, `icon.svg` for the whole folder. This is what makes a node identifiable at canvas size, and it depends on nothing outside the repo.\n\n`meta.json` can also carry icon *references* (`\"icons\": {\"<nodeType>\": \"lucide:Send\"}` per node type, or `\"icon\"` folder-wide) for generic utility nodes with no brand of their own. Treat that as the lesser option: a `lucide:<Name>` string is a hard dependency on a third-party export that can be renamed or dropped, and when it breaks the node renders **nothing** rather than erroring. Library glyphs are also monochrome `currentColor` line art, so they read as washed-out grey next to brand artwork.\n\nThree traps: a **file always beats a meta.json ref**, so a folder shipping `icon.svg` shadows refs for every node type in it (this is why the four WhatsApp Business nodes once rendered one glyph); `lucide:` names match the package's **export** identifiers, so `lucide:CheckCheck` resolves and kebab-case `lucide:check-check` silently renders nothing; and emoji, while dependency-free, are generic rather than branded. Locked from both sides — `client/src/assets/icons/index.test.ts` walks every `meta.json` under `server/nodes` and asserts each ref resolves to a real component; `test_node_spec.py` asserts every `icons` key is a registered node type.\n\nBackend endpoints serve SVGs at `GET /api/schemas/nodes/<type>/icon` (plugin icons) and `GET /api/schemas/credentials/<provider>/icon` (credential brand icons). Frontend resolver at [client/src/assets/icons/index.ts](./client/src/assets/icons/index.ts) dispatches `lib:brand` / URL passthrough / emoji / `asset:<key>`. The `asset:` branch is currently inert at runtime (the frontend `ICON_REGISTRY` glob finds no SVGs so it resolves to null) but it is NOT dead code — the backend still emits `asset:google` / `asset:stripe` for palette groups (`server/nodes/groups.py`) and the format is invariant-tested on both sides (`test_node_spec.py` Wave 10.B, `icons/index.test.ts`).\n\n**Do not** declare `icon` / `color` as class attributes on a node (the override path was removed in F1). Put `meta.json` in the plugin folder (colour, plus icon refs as above), and `icon.svg` / `icon_<nodeType>.svg` only when artwork is genuinely needed. SKILL.md icon/color resolves from the first node in `allowed-tools` — only orphan skills keep inline `metadata.icon` / `metadata.color`.\n\n## Key Files & Components\n\n### Core Types\n- `src/types/INodeProperties.ts` - Core interfaces for n8n-inspired node properties system\n- `src/types/NodeTypes.ts` - Legacy compatibility types (NodeParameter, NodeOutput)\n- `src/types/workspaceFiles.ts` - Wire types for the gallery / workspace file explorer (`WorkspaceEntry`, `WorkspaceFileRef`, `FILE_REF_KINDS`, `isWorkspaceFileRef`, `WORKSPACE_FILE_DRAG_TYPE`). Declarations only — it documents which decisions are server-owned and must not be re-derived client-side\n\n### Node System\nNode metadata is SSOT on the backend after Wave 11. Each node is a Python\nplugin at `server/nodes/<category>/<plugin>/__init__.py` that emits a `NodeSpec` via\nthe registry. The frontend fetches specs through\n[`client/src/lib/nodeSpec.ts`](./client/src/lib/nodeSpec.ts) and adapts\nthem via [`client/src/adapters/nodeSpecToDescription.ts`](./client/src/adapters/nodeSpecToDescription.ts).\nSee [`docs-internal/plugin_system.md`](./docs-internal/plugin_system.md)\nand [`server/nodes/README.md`](./server/nodes/README.md) for the plugin\nauthoring model.\n\n- `src/lib/nodeSpec.ts` - TanStack-Query-backed spec fetch, `resolveNodeDescription`, `listCachedNodeSpecs`, group lookup\n- `src/lib/aiModelProviders.ts` - Frontend-only AI provider icon/credential map\n- `src/adapters/nodeSpecToDescription.ts` - Backend `NodeSpec` → legacy `INodeTypeDescription` shape\n- `src/services/executionService.ts` - Node execution routed through the backend WebSocket layer\n\n### Assets\n- `src/assets/icons/index.ts` - Icon resolver (`lib:brand` / URL / emoji / `asset:<key>` dispatch); `src/assets/icons/themedGlyphs.ts` - per-theme SVG glyph registry read by `NodeIcon.tsx`. Brand marks (Google services included) are served from the backend plugin folders via `GET /api/schemas/nodes/<type>/icon`; there is no client-side `google/` icon folder\n\n### UI Components\n- `src/components/ParameterRenderer.tsx` - Universal parameter renderer (also handles AI-specific control rendering; the former `AIParameterRenderer.tsx` was absorbed here)\n- `src/components/parameterPanel/MiddleSection.tsx` - Parameter panel middle section with conditional display logic\n- `src/components/output/OutputPanel.tsx` - Connected node output display with drag mapping\n- `src/components/LocationParameterPanel.tsx` - Location-specific parameter handling\n- `src/components/parameterPanel/GalleryPanel.tsx` - Workspace file explorer for the `gallery` node (`isGalleryPanel` uiHint); supporting parts in `parameterPanel/gallery/` (`FilePreviewDialog`, `FileGlyph`, `fileIcons`)\n- `src/components/AIAgentNode.tsx` - Spec-driven agent canvas component. Reads `useNodeSpec(type)` for handles / icon / colour / displayName / uiHints; renders any plugin whose backend `component_kind` is `\"agent\"` or `\"chat\"`. No `AGENT_CONFIGS` map.\n- `src/ParameterPanel.tsx` - Main parameter configuration modal\n\n### AI Chat Model Components\nAI model nodes route through `SquareNode` via `Dashboard.tsx`'s `COMPONENT_BY_KIND['model']` lookup. Per-provider visual data (icon, color, displayName) comes from the backend `NodeSpec` declared in `server/nodes/model/<provider>_chat_model/__init__.py`. The pre-Wave-11 per-provider wrappers (`BaseChatModelNode`, `OpenAIChatModelNode`, `ClaudeChatModelNode`, `GeminiChatModelNode`, `ModelNode`) were deleted -- nothing imported them after the migration.\n\n### Specialized UI\n- `src/components/maps/GoogleMapsPicker.tsx` - Interactive location picker (click / drag marker); wrapped by `maps/MapsPreviewPanel.tsx` and rendered through `parameterPanel/MapsSection.tsx` for `gmaps_create`. Uses Google's default map styling.\n- `src/components/output/OutputPanel.tsx` - Execution result display (the active renderer; the legacy `ui/OutputDisplayPanel.tsx` was deleted)\n- `src/components/ui/ComponentPalette.tsx` - Searchable component library with emoji icons and dracula-themed category colors. Categories come from the backend node-groups index (`server/nodes/groups.py`); the palette renders them verbatim.\n- `src/components/ui/ComponentItem.tsx` - Draggable node items with hover effects and icon rendering\n- `src/components/ui/CodeEditor.tsx` - Syntax-highlighted code editor (react-simple-code-editor + prismjs). Token colours come from the per-theme `--code-*` tokens (see [Theme System](./docs-internal/theme_system.md) tier 6) — the code editor, console/output JSON viewers, and chat code blocks all paint in the active theme's syntax palette, not a global dracula scheme. (Retired the old `--prism-*` block + dead `getPrismTokenCSS()`.)\n\n### Hooks & State\n- `src/hooks/useParameterPanel.ts` - Parameter management via WebSocket\n- `src/services/executionService.ts` - Node execution via WebSocket (`executeNodeViaWebSocket`)\n- `src/hooks/useApiKeys.ts` - API key management via WebSocket\n- `src/hooks/useWhatsApp.ts` - WhatsApp operations via WebSocket\n- `src/hooks/useDragAndDrop.ts` - Drag-and-drop functionality (palette → canvas, `application/reactflow`)\n- `src/hooks/useDragWorkspaceFile.ts` - Drag a workspace file onto another node's parameter (`workspaceFile` payload); mirrors `useDragVariable`'s dual-MIME contract — `application/json` for the structured payload, `text/plain` for the bare path\n- `src/hooks/useComponentPalette.ts` - Component palette state with localStorage persistence\n- `src/store/useAppStore.ts` - Zustand application state with localStorage persistence for UI settings\n\n### Theme System\n\nThree themes — `light`, `dark` and the stylized `atomic` (light family; the handoff's nine other skins were removed on 2026-10-12) — driven by `<html data-theme>` (set by [ThemeContext.tsx](./client/src/contexts/ThemeContext.tsx), which also toggles `.dark` for DARK_FAMILY themes) + per-theme CSS in `client/src/themes/`. Home, the editor and the sign-in screen all show the chosen theme, and one theme button ([components/ui/ThemeButton.tsx](./client/src/components/ui/ThemeButton.tsx)) in both modes steps Light → Dark → Atomic. Token VALUES are hex + `color-mix()` (never HSL): per-theme files own shadcn/dracula/node/action hex, `base.css` owns the shared `--tint-*` scale, `index.css` is plumbing (`@theme inline` maps `--color-X: var(--X)`). Six token tiers, the `--pulse-keyframe` animation system, the per-component decoration hooks, the 3-pack WebAudio sound system, and the canvas-wide edge/node status rules (`canvasAnimations.ts`) are all documented in **[Theme System](./docs-internal/theme_system.md)** — read it before adding a theme or a canvas-node component. The strict frontend theme RULES remain normative under \"Frontend Design + Theme System (strict)\" above.\n\n### WebSocket-First Architecture\nThe project uses WebSocket as the primary communication method between frontend and backend, replacing most REST API calls:\n- `src/contexts/WebSocketContext.tsx` - Central WebSocket context with request/response pattern\n- `server/routers/websocket.py` - WebSocket endpoint; the live handler set is the `MESSAGE_HANDLERS` dict plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain a count here.\n- `server/services/status_broadcaster.py` - Connection management and broadcasting\n\n**Canvas mutations from the backend** -- any handler that needs to add / move / delete nodes or edges (auto-add-skill on tool connect, Agent Builder runtime tools called by the LLM mid-execution, future workflow-template features) returns a workflow-ops batch (`{operations: [...]}`) and the frontend applies it through `applyOperations` in [client/src/lib/workflowOps.ts](./client/src/lib/workflowOps.ts). Backend builders live in [server/services/workflow_ops.py](./server/services/workflow_ops.py). Two delivery modes: request/response (frontend-driven, e.g. auto-skill) and push broadcast (`workflow_ops_apply`, sent by `services/workflow_ops.broadcast_workflow_ops` and picked up by `useWorkflowOpsListener`). A server-side change to a saved workflow (Turn on Talk, the Agent Builder) goes through `services/workflow_storage/mutate.apply_graph_additions`, which writes the nodes, edges and parameter rows in one transaction and pushes `workflow_ops_apply` with `persisted: true`; editors adopt the server's ids without saving (`useSavedGraphSync` also updates the workflow the app store holds while Home shows). Full spec: [docs-internal/workflow_ops_protocol.md](./docs-internal/workflow_ops_protocol.md).\n\n## Implemented Node Types\n\n> **Authoritative source: backend plugin registry.** Read the live count from `len(services.node_registry.NODE_METADATA)` after `import nodes`; a file glob over [`server/nodes/`](./server/nodes/) miscounts (`**/__init__.py` also matches group packages, and excluding `__init__.py` drops most plugins). The per-node descriptions below are reference material — they drift on every plugin add and should be cross-checked against [`server/nodes/README.md`](./server/nodes/README.md), the per-domain docs in `docs-internal/`, and the actual plugin classes before relying on any specific detail.\n\n### Node Catalogue (collapsed)\n\n> The authoritative, per-node reference is the backend plugin registry plus the per-node \"logic-flow\" cards under [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) (one card per node, grouped by category, with handles / params / outputs / side-effects / edge-cases). Live node list = the plugin registry (one folder per node under `server/nodes/<group>/`; read the total from `len(services.node_registry.NODE_METADATA)` rather than hardcoding it here — a bare `__init__.py` glob overcounts by also matching the group packages). Do NOT maintain a per-node catalogue here — it drifts on every plugin add.\n\nNode groups (palette categories) are registered in [`server/nodes/groups.py`](./server/nodes/groups.py), 34 keys at time of writing: agent, ai, android, api, browser, chat, code, deployment, discord, document, email, filesystem, google, language, location, memory, microsoft, model, payments, proxy, scheduler, scraper, search, service, skill, social, text, tool, trigger, utility, vcs, whatsapp, whatsapp_business, workflow. Folder names are not palette keys: telegram and twitter nodes declare `social`, stripe and dodo_payments declare `payments`, vercel / cloudflare / gcloud / aws declare `deployment`, github declares `vcs`, the `context` node declares `memory`, `vision` declares `tool`, and speech and translate declare `language` (provider-abstracted `textToSpeech` / `speechToText` and `translateText` / `transliterateText` / `detectLanguage`; `nodes/sarvam/` was retired into them, and only `sarvamChatModel` under `nodes/model/` remains vendor-named). See [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) for the card index.\n\n## Backend Services\n\n### Python Backend (FastAPI)\n- **Port**: `PYTHON_BACKEND_PORT` (defaults in `.env.template`)\n- **Base URL**: `http://localhost:${PYTHON_BACKEND_PORT}`\n- **Main File**: `server/main.py`\n\n### API Endpoints\n#### Android Services (`server/nodes/android/_router.py`, plugin-owned, mounted by the `register_router` loop in `main.py`)\n- `GET /api/android/devices` - List connected Android devices via ADB with model and state info\n- `POST /api/android/port-forward` - Setup ADB port forwarding for device communication\n- `POST /api/android/{service_id}/{action}` - Execute Android service actions with parameters\n- `GET /api/android/health` - Android service health check\n\n#### Remote Android WebSocket\n- **WebSocket**: Configurable via environment variable - Persistent WebSocket connection for remote Android devices\n- **Health Check**: `{relay-url}/ws-health` - WebSocket proxy health status\n- **Stats**: `{relay-url}/ws-stats` - Active connection statistics\n- **Implementation**: `server/nodes/android/_relay/` (`client.py`, `manager.py`, `broadcaster.py`, `protocol.py`) - Persistent WebSocket relay client with background tasks\n - Background message receiver continuously queues incoming messages\n - Keepalive loop sends ping every 25 seconds to maintain connection\n - Message queue (asyncio.Queue) for async message handling\n - Connection reuse across multiple API requests\n - Message filtering to skip non-response messages (presence, pong, ping)\n\n#### Webhook Router (`server/routers/webhook.py`)\n- `ANY /webhook/{path}` - Dynamic webhook endpoint for incoming HTTP requests (GET, POST, PUT, DELETE, PATCH)\n- Dispatches `webhook_received` event via `broadcaster.send_custom_event()` to trigger waiting webhookTrigger nodes\n- Returns immediate 200 OK response (responseNode mode planned for future)\n- `GET /webhook/` - Webhook endpoint info and usage documentation\n\n#### Workspace Router (`server/routers/workspace.py`)\n- `GET /api/workspace/{workflow_id}/files/{path:path}` - Serve a file from a workflow's workspace.\n Range/seeking comes free from Starlette's `FileResponse` (`206` / `Content-Range` / `If-Range` /\n `416`) — do NOT wrap it in a `StreamingResponse`. Containment via `resolve_within`; 404 never 403\n (a distinct status would confirm what exists outside the workspace). **The `Content-Disposition`\n is not decided here** — it comes from `services.media.preview.serves_inline`, which the gallery\n listing also reads (via `preview_kind`) so the panel never offers a preview the route refuses to\n serve. Only `audio/ image/ video/` render inline; `NEVER_INLINE` is `{image/svg+xml, text/html,\n text/xml, application/xhtml+xml}`, because nodes can write arbitrary files into a workspace and\n inline markup from the app origin is stored XSS.\n- **Listing is a WebSocket command, not an HTTP route.** `list_workspace_files` (owned by the\n gallery plugin) is the listing channel; these HTTP routes stay the *content* channel. The\n consumer is the parameter panel, which already holds an authenticated socket with request\n correlation — a second HTTP listing surface would mean a second auth path and a second error\n envelope for no gain.\n- `POST /api/workspace/{workflow_id}/uploads` - Streamed multipart upload (the first in the repo on\n either side of the wire). Chunked read with a running total — `Content-Length` is never trusted —\n 413 past `MEDIA_MAX_UPLOAD_BYTES`. Owner-only, and never falls back to the shared anonymous\n workspace (both refusals are 404). Returns an `AudioRef` for audio (probed) and otherwise a\n `FileRef` whose kind follows `preview_kind`; `coerce_file_param` accepts both.\n- **The URL carries `workflow_id`; the directory is named by `Workflow.slug`.** The router owns that\n lookup because it needs the database, while `services.media` stays synchronous. See\n [Media Transport](./docs-internal/media_transport.md).\n\n#### Workflow Services (`server/services/workflow.py`)\n- Node execution dispatches every registered plugin via the `BaseNode` registry (one self-contained folder per node under `server/nodes/<group>/`; live total via `len(services.node_registry.NODE_METADATA)` — do not hardcode it, and note a bare `__init__.py` glob overcounts by also matching the group packages)\n- Parameter resolution and template variable substitution\n- Result formatting and error handling\n\n#### Frontend-Backend WebSocket (`server/routers/websocket.py`)\n- **WebSocket Endpoint**: `/ws/status` - Real-time status updates between React and Python\n- **REST Endpoint**: `GET /ws/info` - WebSocket connection info and current status\n- **Message Types**:\n - `android_status` - Android device connection status updates\n - `node_status` - Individual node execution status\n - `node_output` - Node execution output data\n - `variable_update` - Single variable value change\n - `variables_update` - Batch variable updates\n - `workflow_status` - Workflow execution progress\n - `ping/pong` - Keep-alive messages\n\n### Development Scripts\nService orchestration lives in the Python CLI (`company dev` / `start` / `stop`, implemented under `cli/commands/`). See [Scripts Reference](./docs-internal/SCRIPTS.md). The former `start.bat` / `stop.bat` / `restart.bat` wrappers and the `concurrently`-based `npm run dev` no longer exist.\n\n### Temporal Distributed Execution\n\nWorkflows execute via Temporal for durability and horizontal scaling, gated by `TEMPORAL_ENABLED`. Three dispatch paths exist — legacy single `execute_node_activity` (fallback), per-type `node.{type}.v{version}` activities (F4.A, `TEMPORAL_PER_TYPE_DISPATCH=true`), and Agent-as-child-workflow (F4.B, `TEMPORAL_AGENT_WORKFLOW_ENABLED=true`) — with `rlm_agent`/`claude_code_agent` always bypassing AgentWorkflow. **Per-queue activity routing is production-default (Wave 16)**: a `TemporalWorkerPool` runs one activity-only worker per plugin-declared `cls.task_queue` (ai-heavy / browser / code-exec / rest-api / messaging / ...) with per-queue concurrency + rate limits + resource-based tuning for ai-heavy/browser; rollback via `TEMPORAL_WORKER_POOL_ENABLED=false`. Resilience knobs (Waves 17-18): `DEPLOYMENT_MODE` (local halves concurrency; sizes the sticky cache), unlimited-with-exponential-backoff retry on `agent.execute_llm_step` (`LLM_STEP_RETRY`, `maximum_attempts=0`, 5 s to 5 min; terminal provider categories still fail fast as non-retryable; the earlier one-shot policy was reverted), observability interceptors (`activity_retry` WARN on re-dispatch), 30s periodic heartbeat during long activity bodies, cron `catchup_window=24h`, poller autoscaling. **Conditional edges are evaluated on this path too, as of the `machina-conditional-edges-v1` patch.** They previously were not: `MachinaWorkflow._find_ready_nodes` scheduled purely on dependency completion, so a condition set in the editor rendered an edge label and then did nothing once execution routed through Temporal — silently, with both branches running. The skip mirrors `WorkflowExecutor._evaluate_incoming_conditions` exactly rather than improving on it: **OR-any** across a node's conditional incoming edges, and **skipping is not transitive** (a skipped node counts as completed, matching `get_completed_nodes` including `SKIPPED`, so an unconditional downstream node still runs). `evaluate_condition` is imported from `services.execution.conditions` **directly, never via the package `__init__`**, which also pulls in the executor / cache / recovery sweeper / DLQ; the module itself is pure (`re` + comparisons, no IO, no clock, no randomness) so it is safe to evaluate inside a workflow. The `workflow.patched(...)` gate is mandatory — the skip changes which activities get scheduled, so an ungated change would break replay for in-flight workflows. Locked by `tests/temporal/test_conditional_edges.py`, whose patch-closed case asserts the pre-fix command sequence is still reproduced verbatim.\n\nExecution routing falls back Temporal → sequential; the Temporal dev server + embedded worker are managed in-process under `server/services/temporal/` (pooch-downloaded CLI, single `temporal server start-dev` process, gRPC `TEMPORAL_FRONTEND_GRPC_PORT` + Web UI `TEMPORAL_UI_PORT`, SQLite at `~/.opencompany/temporal.db`). Full architecture, dispatch matrix, per-node + agent-loop lifecycle, the F4.B `agent.*` activities (unsuffixed since the AgentWorkflow fold; read the live set from `collect_agent_activities()` rather than a hardcoded count), heartbeat semantics, delegation input contract, the worker tuning recipe, and all `.env` tunables live in [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md).\n\n**Months-long durability contract (July 2026).** Running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. Load-bearing invariants: (1) `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` stays `false` (debug-only sweep; even enabled, any control row in the shared `WORKFLOW_CONTROL_ACTIVE_STATES` — including `resetting` — vetoes it). (2) New child workflow starts carry **no** `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so lifetime caps silently terminated paused runs; liveness comes from activity heartbeats (30s beat / 2min timeout), never from workflow lifetime caps. Removing/adding start options or retry policies on recorded commands requires a `workflow.patched(...)` guard (list the live markers with `grep -rn \"workflow.patched(\" server/services/temporal`; [TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md) says what each one gates). (3) Every long-lived workflow loop must continue-as-new under history pressure (`is_continue_as_new_suggested()` + a soft cap) — Temporal hard-terminates around ~51,200 history events; `WorkflowControlWorkflow` carries triggers/queued events/seen-ids/control state across rollovers, so controller handles are addressed **by workflow id only, never run_id-pinned**. (4) `dispatch.emit` skips controllers whose `ControlEventTypes` Search Attribute doesn't match the event (absent attribute = legacy match-all). (5) The Temporal lifecycle is owned by [services/temporal/lifecycle.py](./server/services/temporal/lifecycle.py) (`main.py` only schedules it): dev-server supervision + resident watchdog (`TEMPORAL_HEALTH_MONITOR_INTERVAL_SECONDS`), worker crash-restarts that REBUILD the single-use SDK `Worker` per attempt (manager + every pool queue worker), and the boot-time `reconcile_active_controls_on_boot` pass (converges crash-stranded `starting` rows, re-arms running/paused generations from the persisted graph snapshot). (6) **Recovery policies** (env-driven, defaults in `.env.template`; full semantics in [temporal-workflow-control.md → Recovery policies](./docs-internal/temporal-workflow-control.md)): `WORKFLOW_CONTROL_CRASH_RECOVERY=pause` — after a kill/crash (dirty-bit marker cleared only by graceful teardown) boot recovers running generations as **paused** so the user consciously resumes; `WORKFLOW_CONTROL_MISSING_CONTROLLER=pause` — a killed/vanished controller converges the generation to paused and **Resume rebuilds the controller** (`WorkflowIdConflictPolicy.USE_EXISTING`, re-arm from snapshot) instead of forcing a state-archiving Reset; `WORKFLOW_CONTROL_PAUSE_ON_FAILURE=true` — repeatedly-failing trigger-spawned runs pause their deployment via the `workflow_control.pause_on_failure` activity (circuit breaker; trips only after `WORKFLOW_CONTROL_PAUSE_ON_FAILURE_THRESHOLD` (default 3) failures inside a rolling `_WINDOW_SECONDS` (default 600) so one node hiccup never pauses anything; Resume resets the streak; manual canvas runs never qualify). Temporal's native Pause/Unpause (server 1.28+) is deliberately NOT used — no Python SDK surface, and it halts workflow-task dispatch so a natively-paused controller couldn't process the resume Update. (7) **Workflow-scoped event delivery**: an envelope whose `workflow_id` is set by its producer's call site reaches only that workflow's consumers (`dispatch.emit` narrows both Visibility clauses by `EventWorkflowId`); chat is the first scoped producer — the decision lives in `routers/websocket.py`, the narrowing in core dispatch, and plugin `_events.py` factories only plumb the field (see [event_framework.md](./docs-internal/event_framework.md)). (8) **Canvas editability is the server-owned `can_edit` capability** emitted by `serialize_control` (paused = editable; starting/running/transitional = locked); the FE renders it via `lib/canvasLock.ts` + Dashboard's `guardCanvasEdit` and never re-derives the rule from state strings (see [temporal-workflow-control.md → Canvas editability](./docs-internal/temporal-workflow-control.md)). Locked by `tests/temporal/test_durability_hardening.py` + `test_worker_restart.py`.\n\n**Temporal tracing ownership is strict.** Register the SDK `TracingInterceptor` exactly once on the shared `Client.connect(...)`; the Python SDK automatically prepends compatible client interceptors to every worker. Never repeat `TracingInterceptor` in `Worker(..., interceptors=...)`. Worker lists contain the distinct `ObservabilityWorkerInterceptor` and plugin-specific worker interceptors only. Exact paired `StartActivity` / `RunActivity` / `CompleteWorkflow` console spans with identical Temporal identities indicate duplicate instrumentation, not duplicate execution; use Temporal Event History and the `node.<type>.execute` application span to verify actual attempts. See the tracing and debugging sections in [TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md) and [errors.md](./docs-internal/errors.md).\n\n## Development Commands\n\n**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.\n\n### CLI Commands (after the global install)\n```bash\ncompany start # Start all services (production mode)\ncompany dev # Start all services in dev mode (Vite HMR)\ncompany 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)\ncompany stop # Stop all services\ncompany build # Build for production\ncompany clean # Clean build artifacts\ncompany provision # Set up the Python side of a global install (automatic on first use; --force redoes it)\ncompany help # Show all commands\n```\n\n### package.json scripts (run with bun)\n```bash\n# Core (thin wrappers over the Python CLI)\nbun run start # Start all services (python -m cli start)\nbun run stop # Stop all services (python -m cli stop)\nbun run build # Build for production (python -m cli build)\nbun run clean # Clean build artifacts (python -m cli clean)\nbun run deploy # Self-deploy to a cloud VM (python -m cli deploy)\n```\nNo root script hops through `npm run`; cross-package scripts use `bun --cwd=<dir> run <script>`.\n\n### Cross-Platform Scripts\nService 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.\n\nSee **[Scripts Reference](./docs-internal/SCRIPTS.md)** for full documentation.\n\n## Current Status\n✅ **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.\n✅ **WebSocket-First Architecture**: most frontend-backend RPC goes through WebSocket; live handler set lives in `MESSAGE_HANDLERS` in `server/routers/websocket.py`\n✅ **Code Editor**: Python, JavaScript, and TypeScript executors with syntax-highlighted editor (react-simple-code-editor + prismjs) and console output\n✅ **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\n✅ **Component Palette**: Emoji icons with distinct dracula-themed category colors, localStorage persistence for collapsed sections\n✅ **Android Integration**: 16 Android service nodes with ADB automation and remote WebSocket support\n✅ **Conditional Parameter Display**: Dynamic UI rendering based on parameter values (displayOptions.show)\n✅ **Execution Engine**: Full component execution with result display\n✅ **Parameter Mapping**: Drag-and-drop output to parameter connections\n✅ **AI Integration**: API key management and model selection\n✅ **Location Services**: Interactive map picker with coordinate handling, Google Maps API key fetched from backend credentials\n✅ **Code Cleanup**: Dead code removed, unused files deleted\n✅ **Process Management**: Python CLI supervisor (`cli/supervisor.py`) with Job Object / process-group tree kill and port-based `company stop`\n✅ **WhatsApp Integration**: Square node design with QR code viewer, group/sender name persistence, newsletter channel support (send, query, follow/unfollow, create, mute, mark viewed, react, live updates), media download, profile pics, and proper error handling\n✅ **Backend Stability**: Fixed dependency injection and error handling preventing crashes\n✅ **Development Server**: the app URL is the same in every mode, **`http://localhost:${VITE_CLIENT_PORT}`**; `.env.template` sets `VITE_CLIENT_PORT` equal to `PYTHON_BACKEND_PORT` (locked by `cli/tests/test_env_ports.py`). `company dev` = Vite HMR on `VITE_CLIENT_PORT`, proxying /api /ws /webhook to the backend on the `PYTHON_BACKEND_PORT` that `.env.dev` overrides; `company start` (production) = uvicorn alone on `PYTHON_BACKEND_PORT` (API + WS + SPA)\n✅ **WebSocket Integration**: Persistent WebSocket connections for remote Android devices with background tasks and message queue\n✅ **Real-time Status WebSocket**: Frontend-backend WebSocket at `/ws/status` for live Android status, node status, and variable updates\n✅ **Event-Driven Trigger Nodes**: WhatsApp Receive and Webhook Trigger with asyncio.Future-based event waiting, filter builders, and cancel support\n✅ **Continuous Scheduling Execution**: Temporal/Conductor pattern using `asyncio.wait(FIRST_COMPLETED)` for true parallel pipelines where dependent nodes start immediately when their specific dependency completes\n✅ **Event-Driven Deployment**: n8n-style architecture where each trigger event spawns an independent, concurrent execution run (no iteration loop)\n✅ **HTTP/Webhook Nodes**: HTTP Request for external APIs, Webhook Trigger for incoming requests, Webhook Response for custom responses\n✅ **Theme System**: Neutral-slate (dark) + grey-blue paper (light) surfaces with Dracula accent palette, dark mode support, vibrant action buttons, and themed React Flow edges\n✅ **Modular Backend Architecture**: workflow.py refactored from 2068 lines into a facade (~840 lines today) over NodeExecutor, ParameterResolver, and DeploymentManager modules\n✅ **Node Rename System**: n8n-style node renaming via F2 keyboard shortcut, double-click on label, or right-click context menu with inline editing\n✅ **UI State Persistence**: localStorage persistence for sidebar visibility, component palette visibility, dev mode, and collapsed sections\n✅ **Normal/Dev Mode**: Normal mode (Home: hire and supervise AI employees) is the landing screen; the Normal/Dev switch in the editor toolbar and the Home header (or Ctrl/Cmd+Shift+D) moves to Dev mode, the workflow editor. `VITE_NORMAL_MODE=false` restores the old palette-filter toggle\n✅ **Production Deployment**: `company deploy` provisions a login-gated VM via Terraform + cloud-init running `company serve` under systemd; `docker compose up -d --build` runs a one-container self-hosting image built from source (see [docker.md](./docs-internal/docker.md)); the old 4-container Docker Compose topology was removed (see [deployment_legacy.md](./docs-internal/deployment_legacy.md))\n✅ **Authentication System**: n8n-style JWT authentication with HttpOnly cookies, single-owner and multi-user modes, rate-limited login. Note `AUTH_MODE=multi` authenticates but does NOT isolate data — see Known Limitations in [authentication.md](./docs-internal/authentication.md)\n✅ **Cache System**: n8n-pattern cache with Redis (production) / SQLite (local dev) / Memory fallback hierarchy\n✅ **AI Thinking/Reasoning**: Extended thinking for Claude, Gemini 2.5/3, OpenAI GPT-5/GPT-6/o-series, Groq Qwen3 with output available in Input Data & Variables for downstream nodes\n✅ **Onboarding Service**: 3-step Welcome guide on Home with shadcn UI, database persistence, skip/resume/replay support\n✅ **Proxy System**: Residential proxy provider management with template-based URL formatting, auto-selection by health score, transparent proxy injection on httpRequest/httpScraper nodes via `useProxy: true`\n✅ **Markdown Formatter**: GFM markdown to platform-native formatting (Telegram HTML, WhatsApp syntax, plain text) using markdown-it-py\n\n## Key Features\n\n### Parameter System\n- **Universal Renderer**: Supports both INodeProperties and NodeParameter interfaces\n- **Type-Specific Controls**: String, number, boolean, select, slider, file, array types\n- **Drag-and-Drop**: Map outputs from connected nodes to parameters\n- **Validation**: Required field checking and type constraints\n- **Conditional Display**: Dynamic parameter visibility using displayOptions.show pattern\n - Implemented by `shouldShowParameter()` in `client/src/utils/parameterVisibility.ts` (imported by `MiddleSection.tsx`)\n - Supports array-based conditions (e.g., `messageType: ['text']`)\n - Filters parameters before rendering based on other parameter values\n\n### Node Rename System (n8n-style)\nThree methods for renaming nodes, following n8n UX patterns:\n- **F2 Keyboard Shortcut**: Press F2 with a node selected to enter rename mode\n- **Double-click on Label**: Click the node label twice to edit inline\n- **Right-click Context Menu**: \"Rename\" option in the context menu\n\nAll three are canvas edits and obey the canvas lock: F2 and the menu call Dashboard's `guardCanvasEdit`, and `EditableNodeLabel` reads the same guard through `contexts/canvasEditGuard.ts`, which Dashboard provides around `<ReactFlow>`.\n\n#### Architecture\n```\nGlobal State (useAppStore) Node Components\n├── renamingNodeId: string | null ├── SquareNode.tsx\n├── setRenamingNodeId() ├── TriggerNode.tsx\n ↓ └── StartNode.tsx\n Coordinates which node ↓\n is currently being renamed Local State:\n ├── isRenaming: boolean\n ├── editLabel: string\n └── inputRef: HTMLInputElement\n```\n\n#### Implementation Files\n- **`client/src/store/useAppStore.ts`** - Global rename state (`renamingNodeId`, `setRenamingNodeId`)\n- **`client/src/components/ui/NodeContextMenu.tsx`** - Right-click menu with Rename, Copy, Delete\n- **`client/src/Dashboard.tsx`** - Context menu handler, F2 keyboard handler\n- **`client/src/components/ui/EditableNodeLabel.tsx`** - the single inline-rename component; every canvas node renders it.\n\n#### Key Pattern (EditableNodeLabel.tsx)\n```typescript\n// Sync with global rename state.\nuseEffect(() => {\n if (renamingNodeId === nodeId) {\n setIsRenaming(true);\n setEditLabel(label || defaultLabel);\n } else {\n setIsRenaming(false);\n }\n}, [renamingNodeId, nodeId, label, defaultLabel]);\n\n// Handle save - only save if changed and non-empty\nconst handleSave = useCallback(() => {\n const newLabel = editLabel.trim();\n const original = label || defaultLabel;\n if (newLabel && newLabel !== original) {\n onLabelChange(newLabel);\n }\n setIsRenaming(false);\n setRenamingNodeId(null);\n}, [editLabel, label, defaultLabel, onLabelChange, setRenamingNodeId]);\n```\n\n#### NodeContextMenu Features\n- Rename (F2), Copy (Ctrl+C), Delete (Del) with keyboard shortcuts shown\n- Uses existing `useCopyPaste.copySelectedNodes()` for Copy\n- Delete goes through `useReactFlowNodes.deleteNodeById` (React Flow's `deleteElements`), the same path as the Delete key, so the node's edges are removed too and `onEdgesDelete` reports them\n- Keyboard navigation (Arrow keys, Enter)\n- Click outside to close\n- Tailwind semantic tokens (no palette names)\n\n### UI State Persistence\nThe application persists UI state to localStorage for a consistent user experience across sessions:\n\n#### Persisted Settings\n| Setting | Storage Key | Default | Location |\n|---------|-------------|---------|----------|\n| Sidebar visibility | `ui_sidebar_visible` | `true` | `useAppStore.ts` |\n| Component palette visibility | `ui_component_palette_visible` | `true` | `useAppStore.ts` |\n| Shell mode (Normal / Dev screen) | `ui_shell_mode` | `normal` (`dev` when `ui_pro_mode` is `'true'`) | `useAppStore.ts` |\n| Palette filter (only with `VITE_NORMAL_MODE=false`) | `ui_pro_mode` | `false` | `useAppStore.ts` |\n| Collapsed palette sections | `component_palette_collapsed_sections` | All collapsed | `useComponentPalette.ts` |\n\n#### Implementation Pattern\n```typescript\n// In useAppStore.ts\nconst STORAGE_KEYS = {\n sidebarVisible: 'ui_sidebar_visible',\n componentPaletteVisible: 'ui_component_palette_visible',\n};\n\nconst loadBooleanFromStorage = (key: string, defaultValue: boolean): boolean => {\n try {\n const saved = localStorage.getItem(key);\n if (saved !== null) return saved === 'true';\n } catch { /* Ignore storage errors */ }\n return defaultValue;\n};\n\n// Initial state loads from localStorage\nsidebarVisible: loadBooleanFromStorage(STORAGE_KEYS.sidebarVisible, true),\n\n// Toggle functions save to localStorage\ntoggleSidebar: () => {\n set((state) => {\n const newValue = !state.sidebarVisible;\n saveBooleanToStorage(STORAGE_KEYS.sidebarVisible, newValue);\n return { sidebarVisible: newValue };\n });\n},\n```\n\n### Normal/Dev Mode Toggle\nThe app has two screens, and a Normal / Dev switch moves between them:\n\n| Mode | Screen |\n|------|--------|\n| **Normal** (default) | Home: hire AI employees by describing a job, and supervise them ([client/src/features/home/](./client/src/features/home/)) |\n| **Dev** | The workflow editor (`Dashboard.tsx`); its palette lists every node the blocklists allow |\n\n#### Implementation\n- **State**: `shellMode` (`'normal' | 'dev'`) in `useAppStore.ts`, persisted as `ui_shell_mode`. While that key is unset it comes from the old palette choice: `ui_pro_mode === 'true'` starts in Dev, anything else in Normal.\n- **Switching**: [`components/shell/ModeToggle.tsx`](./client/src/components/shell/ModeToggle.tsx) (editor toolbar and Home header) and Ctrl/Cmd+Shift+D (`app/useModeShortcut.ts`) call `enterNormal` / `enterDev` from [`app/useShellActions.ts`](./client/src/app/useShellActions.ts), never `setShellMode` directly: those guard unsaved editor work, preload the editor chunk, and run the transition (`app/shellTransition.ts`). [`app/ShellModeSwitch.tsx`](./client/src/app/ShellModeSwitch.tsx) renders the current screen; both screens are lazy chunks, so ReactFlow stays out of a Normal-mode session. Locked end to end by `app/__tests__/modeSwitch.test.tsx`.\n- **Kill switch**: `VITE_NORMAL_MODE=false` ([`lib/featureFlags.ts`](./client/src/lib/featureFlags.ts)) turns Normal mode off. The app then opens straight into the editor and the toolbar switch goes back to filtering the palette with `proMode` (`ui_pro_mode`): in its Normal setting a node is hidden unless its first group's `groups.py` `visibility` is `'normal'` or `'all'`, and `enabled_nodes` applies.\n- **Allowlist**: with Normal mode on, `node_allowlist.json` `enabled_nodes` governs what Hire may build instead of filtering the editor palette (see [Node Allowlist](./docs-internal/node_allowlist.md)).\n- **Themes**: Home and the editor show the chosen theme, Atomic included (until 2026-10-12 Home showed only light and dark). The theme button ([`components/ui/ThemeButton.tsx`](./client/src/components/ui/ThemeButton.tsx)) in the Home header, the editor's toolbar and the sign-in screen steps Light → Dark → Atomic, and Home Settings → Profile → Appearance offers the same three.\n\n### Console Panel\nThe Console Panel provides a resizable bottom panel with three sections: Chat (AI conversation), Console (node execution logs), and Terminal (server logs). **Hybrid layout (design-handoff)**: split view (default) docks Chat as a resizable pane beside the Console/Terminal tabs so chat and logs stay simultaneously visible during agent runs; tab mode makes Chat the first of three tabs. Toggled via the Columns2 button in the tab row; persisted in `consolePrefs.splitView` (default `true` — existing users see no change). Both layouts render one `ConsoleChat` ([components/ui/ConsoleChat.tsx](./client/src/components/ui/ConsoleChat.tsx)): the shared chat ([features/chat](./client/src/features/chat/), the same `ChatPane` as Home's employee page) in its compact form, over the open workflow's chat session showing the live generation only. Its turns carry the per-theme `chat-msg*` hooks, and the console's font size applies to the conversation.\n\n#### Features\n- **Resizable**: Drag handle at top to resize (vertical) + chat-pane divider (horizontal, split view), persisted to localStorage\n- **Hybrid Chat placement**: docked split pane (default) or first tab — `consolePrefs.splitView`\n- **Tabs**: Chat (tab mode only) / Console / Terminal\n- **Chat Section**: Send messages to the workflow's chat triggers and follow the runs they start (Working… until the run ends, failures inline; [Chat Protocol](./docs-internal/chat_protocol.md#client)); Clear clears the chat and what its agents remember of it; `chatFocusRequest` switches to the Chat tab before focusing the message box (through the pane's `focusComposer` handle) when in tab mode\n- **Console Section**: View and filter node execution logs\n\n#### Console Selector\nWhen the workflow has several console nodes, a dropdown in the Console section's controls filters the logs to one of them (`isConsoleSink` uiHint, with a type-string fallback). There is no chat-trigger selector: a message goes to every chat trigger of the open workflow whose filter accepts the session.\n\n**Implementation** (`client/src/components/ui/ConsolePanel.tsx`):\n```typescript\nconst consoleNodes = useMemo(() =>\n nodes.filter(n => {\n const def = n.type ? resolveNodeDescription(n.type) : undefined;\n return def?.uiHints?.isConsoleSink\n ?? (n.type ? ['console'].includes(n.type) : false);\n }),\n [nodes]\n);\nconst [selectedConsoleId, setSelectedConsoleId] = useState<string>('');\n```\n\n#### Chat Message Persistence\nChat messages are persisted to SQLite database and survive server restarts. A workflow's session id is its workflow id (`\"default\"` with no workflow open), and Home shows the same thread as Talk on the employee's page. Rows are written through [`services/chat_thread.py`](./server/services/chat_thread.py) (`record_chat_message` / `clear_chat_thread`) and, for the owner's messages and the chat runs they start, [`services/chat/ledger.py`](./server/services/chat/ledger.py); both stamp the session's live generation, append the row after the session's active leaf (one chain, `chat_threads`), and broadcast the identity-only `chat.updated`; agents answer into the thread through the `chatReply` (\"Reply in Chat\") node, as the run's reply when a chat run started it. Runs, their events and the wire contract are in [Chat Protocol](./docs-internal/chat_protocol.md). The thread lives as long as the generation: a workflow Reset (every restart, Home's Apply and Turn on Talk included) clears it through the `chatTrigger` / `chatReply` `reset_execution_state` hook, in the same Reset in which the Context node forgets the conversation, and deleting the workflow deletes it (a workflow-deleted hook the `chatReply` plugin registers).\n\n**Database Model** (`server/models/database.py`):\n```python\nclass ChatMessage(SQLModel, table=True):\n __tablename__ = \"chat_messages\"\n id: Optional[int] = Field(default=None, primary_key=True)\n session_id: str = Field(default=\"default\", index=True, max_length=255)\n execution_id: Optional[str] # the generation (root_execution_id) it was written in\n role: str = Field(max_length=20) # 'user' or 'assistant'\n message: str = Field(max_length=50000)\n uid: Optional[str] # stable wire id: m_... (owner), a_<run id> (a run's reply); unique\n parent_uid: Optional[str] # the message it follows (branches link here)\n run_id: Optional[str] # the chat run it started or answers (models/chat.py)\n kind: str # text / report / action / notice\n status: str # complete / stopped / error\n parts: Dict; attachments: list; meta: Dict # JSON\n created_at: datetime\n```\n\n**WebSocket Handlers** (`server/services/chat/handlers.py`, registered by `services/chat/__init__.py`):\n| Handler | Description |\n|---------|-------------|\n| `send_chat_message` | Save the message and dispatch it to the workflow's chatTriggers. A workflow session answers `delivery: \"now\"` (running / starting / resuming) or `\"queued\"` (paused / pausing, runs on Resume); in any other state `not_running`, saving nothing |\n| `get_chat_messages` | The path shown in a session, oldest first: `{id, role, message, timestamp, run_key, siblings, editable, feedback, ...}` (UTC-offset timestamps; `run_key` = the generation; `siblings` = the message's versions). The latest generation only (none after a Reset), unless `all_generations` (Home's thread; a Reset clears the thread, so only a row from before a Start shows beside the live ones) |\n| `clear_chat_messages` | Clear a session's chat, every generation; for a workflow's session its agents forget the conversation too (`chat_thread.clear_chat_session` tells the listeners registered with `register_chat_cleared_listener`: the Context plugin clears the workflow's conversations) |\n| `save_chat_message` | Save one message with the given role |\n| `chat_subscribe` / `chat_unsubscribe` | Start / stop receiving a session's `chat_run_event` frames; subscribe answers the live runs' snapshots |\n| `get_chat_run` | One run's snapshot |\n| `edit_chat_message` / `regenerate_chat_reply` / `switch_chat_branch` | Edit one of the owner's messages, try the latest answer again, or show another version; the agent's memory follows the path (see [Chat Protocol → Branches](./docs-internal/chat_protocol.md#branches)) |\n| `set_chat_feedback` | Rate an answer `up` / `down` (or take it back); the employee reads it on its next turn |\n| `get_chat_context` | What the message box offers: slash commands, whether files can be attached, whether Web has search to turn off, whether the employee takes a model choice (`model_choice`), the limits |\n| `get_chat_models` | Home's model picker for one employee: Auto (the owner's default model, else the employee's own), the offered models of connected providers and the thinking levels; the owner's choice is in their settings (see [Chat Protocol → Model and thinking](./docs-internal/chat_protocol.md#model-and-thinking)) |\n\nEvery chat command refuses the internal worker socket, and a workflow's session answers only the workflow's owner (`services/chat/access.py`).\n\n**Database Methods** (`server/core/database.py`):\n- `add_chat_message(session_id, role, message, execution_id=None, *, uid=None, run_id=None, ...)` - Append a message after the session's active leaf; returns the row (a `uid` already saved returns that row)\n- `append_chat_row(session, ...)` - The same, inside a caller's `reserved_session()` (the run ledger admits a message and its run in one transaction)\n- `read_chat_messages(session_id, limit=None, execution_id=None)` - Newest `limit` messages, oldest first, optionally of one generation; raises when the read fails, so a failure never reads as an empty thread\n- `clear_chat_messages(session_id)` - Delete all messages for session, with its runs, run parts and thread state\n\n#### Console Log Persistence\nConsole logs are persisted to SQLite database and loaded on page refresh.\n\n**WebSocket Handlers**:\n| Handler | Description |\n|---------|-------------|\n| `get_console_logs` | Retrieve console logs from database (limit: 100) |\n| `clear_console_logs` | Clear all console logs from database |\n\n**Database Methods** (`server/core/database.py`):\n- `add_console_log(log_data)` - Add console log to database\n- `get_console_logs(limit)` - Get console logs\n- `clear_console_logs()` - Delete all console logs\n\n#### Key Files\n| File | Description |\n|------|-------------|\n| `client/src/components/ui/ConsolePanel.tsx` | Main panel component with chat/console/terminal tabs |\n| `client/src/components/ui/ConsoleChat.tsx` | The Chat pane: the shared chat (`features/chat`), compact, over the open workflow's session |\n| `server/models/database.py` | ChatMessage and ConsoleLog SQLModel definitions |\n| `server/core/database.py` | Chat message and console log CRUD methods |\n| `server/routers/websocket.py` | WebSocket handlers for console operations |\n| `server/services/chat/` | Chat runs, run events and the chat WebSocket handlers ([Chat Protocol](./docs-internal/chat_protocol.md)) |\n\n### Per-Workflow Workspace Directory\nEach workflow execution gets a persistent workspace directory where nodes save output files and agents such as Coding Agent access them through connected filesystem tools.\n\n**Directory**: `~/.opencompany/workspaces/<workflow_slug>/` (Wave 14 — keyed by the human-readable slug, not the UUID; see \"Workflow naming\" below).\n\n**Configuration** (`server/core/config.py`):\n```python\nworkspace_base_dir: str = Field(default=\"workspaces\", env=\"WORKSPACE_BASE_DIR\") # resolved under DATA_DIR -> ~/.opencompany/workspaces/\n```\n\n**How it works:**\n- `workflow.py` creates the workspace dir and injects `workspace_dir` into the execution context. The dir name is the `workflow_slug` resolved from the DB (falls back to `\"default\"` for one-off Runs without a saved row).\n- `fileDownloader` saves to `{workspace_dir}/downloads/` by default\n- Code executors (Python/JS/TS) receive `workspace_dir` in their execution namespace\n- The `fileRead`, `fileModify`, `fsSearch`, `shell` and `gallery` nodes use the native `WorkspaceBackend` rooted at `workspace_dir`; Coding Agent can invoke the first four when they are connected as tools. **`gallery` is deliberately `usable_as_tool = False`** — it carries destructive operations, and `fsSearch` + `fileModify` already cover what an agent needs, so shipping an editor panel must not hand every agent a delete tool as a side effect\n- `WorkspaceBackend` resolves and validates paths beneath that root, rejects traversal and symlink escapes, and uses per-path locks plus atomic replacement for writes\n- Rename follows the workflow: when the user renames a workflow, `save_workflow` recomputes the slug and `os.rename`s the workspace dir to match (existing files preserved).\n\n**Key Files:**\n| File | Description |\n|------|-------------|\n| `server/core/config.py` | `workspace_base_dir` setting |\n| `server/services/workflow.py` | `_get_workspace_dir()`, injects into context |\n| `server/nodes/document/file_downloader/` | `fileDownloader` saves to the workspace |\n| `server/nodes/code/` | `workspace_dir` available in Python/JS/TS executors |\n| `server/nodes/filesystem/_backend.py` | Native contained workspace filesystem implementation |\n\n### Workflow Naming (Wave 14)\nThe workflow record carries three identity fields with strict separation:\n\n| Field | Carrier | Stable? | Surfaces |\n|---|---|---|---|\n| `Workflow.id` | opaque 32-hex UUID (`uuid.uuid4().hex`) | yes — never changes on rename | FK target (`Execution.workflow_id`), `EventWorkflowId` Search Attribute in Temporal Visibility, legacy `WorkflowEvent.workflow_id` compatibility field, `log_context(workflow_id=...)`, Redis cache keys, `DeploymentManager._deployments` dict key, frontend `useAppStore.currentWorkflow.id` |\n| `Workflow.name` | free-form display (\"AI Assistant\") | mutable | sidebar, parameter panel, exported JSON |\n| `Workflow.slug` | `<Sanitized_Name>_<N>` (`AI_Assistant_1`) | mutable, recomputed on rename | `~/.opencompany/workspaces/<slug>/`, Temporal workflow IDs (visible in Temporal Web UI), cron Schedule IDs, export filenames |\n\nSingle source of truth: [`server/services/workflow_naming.py`](./server/services/workflow_naming.py) — `slugify_name` (via `python-slugify` for Unicode transliteration, emoji strip, case preservation, length cap), `next_available_slug(name, database, *, exclude_id=None)` (fill-gap counter; pass `exclude_id=workflow_id` on rename so the row doesn't bump itself), `canonicalize_node_ids(workflow_id, nodes, edges)` (pure, idempotent: gives node instances stable `<workflow_id>:<type>:<ordinal>`-style ids derived from plugin type + per-type ordinal, returning the rewritten nodes/edges plus the old-to-new mapping), `node_label_slug(node)` (sandbox-safe stdlib slug from `node.data.label` or `node.type`, used inside Temporal `@workflow.defn` modules where `python-slugify` can't import safely).\n\n**Temporal workflow ID convention** — ids for trigger listeners, their runs, cron Schedules and direct runs start with the workflow slug (shapes below; most are `<workflow_slug>-<node_label>`). The Temporal Web UI's \"Workflow Type\" column already distinguishes those kinds (TriggerListenerWorkflow / PollingTriggerWorkflow / CronTriggerWorkflow / MachinaWorkflow), so their ids carry no middle `-trigger-` tag. Other framework workflows are keyed by immutable ids instead: agent children (row below), delegated-task runners (`_delegation_child_id` in `services/temporal/agent_workflow.py`), the per-generation controller (`workflow-control-<workflow_id>-g<generation>`, `services/deployment/control.py`) and direct Workspace tasks (`services/node_invocations.py`).\n\n| Surface | Format | Example |\n|---|---|---|\n| Trigger listener (push/poll) | `<slug>-<trigger_label>` | `AI_Assistant_1-chatTrigger` (or `AI_Assistant_1-Customer_Inbox` after F2 rename) |\n| Per-firing run (child of listener) | `<slug>-<trigger_label>-<event_id>` | `AI_Assistant_1-chatTrigger-evt-abc` |\n| Cron Schedule | `<slug>-<trigger_label>` | `AI_Assistant_1-cronScheduler` |\n| Cron firing (per-tick child) | `<slug>-<trigger_label>-<ScheduledStartTime>` | `AI_Assistant_1-cronScheduler-2026-05-27T12:00:00Z` |\n| Agent child workflow | `<root_temporal_workflow_id>-agent-<node_id>` | `AI_Assistant_1-chatTrigger-evt-abc-agent-<workflow_id>:aiAgent:1`. `_agent_child_workflow_id` (`services/temporal/workflow.py`) builds it from the root run's Temporal id and the immutable canvas node id, because labels change and need not be unique. It is not patch-gated, and there is no label-derived form. |\n| Direct MachinaWorkflow exec | `<slug>-<uuid8>` | `AI_Assistant_1-a1b2c3d4` |\n| Per-node activity (inside MachinaWorkflow) | `activity_id = <node_id>` | `<workflow_id>:chatTrigger:1` (node ids are canonical `<workflow_id>:<type>:<ordinal>`, see `canonicalize_node_ids`) |\n\n`node_label` is `node.data.label` (the F2-renamed canvas label) when set, falling back to `node.type` (`chatTrigger` / `telegramReceive` / `aiAgent` / etc.). Computed once at deploy time via `node_label_slug(node)` and passed into Temporal workflows as `trigger_label` in `listener_data`; agent child ids use the node id, not the label. Stable `TriggerNodeId` / `EventWorkflowId` Search Attributes still use the immutable node_id / UUID so admin queries don't break across rename.\n\n**Rename path** — the editor has NO dedicated rename endpoint: its auto-save chain (`TopToolbar` inline edit → `updateWorkflow({name})` → debounced save → REST `POST /api/database/workflows` → `services.workflow_storage.handlers.handle_save_workflow`) IS its rename path. Home's `rename_employee` renames through `rename_saved_workflow` in the same module, without touching the graph. When `name` changes, either path (1) allocates a fresh slug via `next_available_slug`, (2) `database.rename_workflow` updates name + slug atomically (id UUID stays put), (3) renames the on-disk workspace dir via `Path.rename()`, (4) broadcasts a CloudEvents `workflow.renamed` envelope (`broadcaster.broadcast_workflow_lifecycle(\"renamed\", workflow_id=..., name=..., slug=..., old_slug=...)`) so other tabs invalidate their workflows query. A rename leaves a running generation's Temporal ids alone: its listeners and cron Schedules keep the slug its Start recorded in the control row's `graph_snapshot` (`workflow_slug`, read by `DeploymentManager._generation_slug`), so the re-arm after a restart registers the same ids instead of a second set beside them, which made every event start two runs. The next Start names them by the new slug.\n\n**Invariants** (locked by `tests/services/test_workflow_naming.py` + `test_workflow_rename.py` — 39 tests):\n- First creation always gets `_1` suffix (no bare-base slugs).\n- Fill-gap: deleted `AI_Assistant_2` slot is reused on next \"AI Assistant\" creation, unless a live generation of another saved workflow still names its Temporal ids by it (a workflow renamed while it runs keeps the slug its Start recorded, and `list_workflow_slugs` returns those too). A cron Schedule left by a deleted workflow under a reused slug is replaced at Start (`create_cron_schedule(owner_gone=...)`), not reported as `cron_schedule_ownership_conflict`.\n- Renaming `AI Assistant` → `AI Assistant!` (same slug base) keeps `_1` via `exclude_id` (no self-bump).\n- UNIQUE constraint on `slug` is the final collision guard; `IntegrityError` indicates a race the caller should retry.\n- Non-ASCII names transliterate via `text-unidecode` (\"日本語\" → \"Ri_Ben_Yu\"); fall back to `Workflow_N` only when slug is empty after sanitize.\n- No backfill migration — the slug column is required on every save. Existing DBs must be rebuilt.\n\n### Execution System\n- **Supported Components**: AI models, location services, Android automation, WhatsApp messaging, HTTP requests, webhooks\n- **Android Integration**: ADB-based device control with 16 service nodes across monitoring, apps, automation, sensors, and media\n- **Result Display**: Formatted output panel with success/error states\n- **Performance Metrics**: Execution time and status tracking\n- **Error Handling**: Comprehensive error reporting and logging\n- **Dynamic Options**: Load options from backend (e.g., Android device list, service actions)\n- **Continuous Scheduling**: Temporal/Conductor pattern using `asyncio.wait(FIRST_COMPLETED)` - dependent nodes start immediately when their specific dependency completes\n- **Event-Driven Deployment**: n8n-style architecture where triggers spawn independent concurrent execution runs (no iteration loop)\n\n### Event-Driven Deployment Architecture (n8n Pattern)\nThe deployment system follows modern workflow engine patterns from n8n, Temporal, and Conductor:\n\n```\ndeploy_workflow() -> Sets up triggers, returns immediately\n |\n +-> cronScheduler fires -> spawns ExecutionRun 1\n +-> cronScheduler fires -> spawns ExecutionRun 2 (concurrent)\n +-> whatsappReceive fires -> spawns ExecutionRun 3 (concurrent)\n +-> webhookTrigger fires -> spawns ExecutionRun 4 (concurrent)\n```\n\n**Key Concepts:**\n- **Workflow Template**: The deployed workflow is an immutable graph snapshot persisted on the `WorkflowControlExecution` row (`graph_snapshot` JSON column, `models/database.py`), written at Start by `services/deployment/control.py` and re-read to re-arm the controller after a crash\n- **Execution Run**: Each trigger event spawns an independent, isolated run\n- **Concurrent Runs**: Multiple runs execute simultaneously without interference\n- **No Iteration Loop**: Purely event-driven, not polling or sequential iterations\n- **Pre-Executed Triggers**: The firing trigger is marked complete before downstream execution. All other trigger nodes in the run are also marked `_pre_executed` with `{not_triggered: True}` to prevent them from blocking as event waiters\n\n**Implementation Files:**\n- `server/services/workflow.py`: Thin facade (~840 lines) delegating to specialized modules\n- `server/services/node_executor.py`: Single node execution with registry-based dispatch\n- `server/services/parameter_resolver.py`: Template variable resolution (`{{node.field}}`)\n- `server/services/deployment/manager.py`: Deployment lifecycle, spawn runs, cancel\n- `server/services/deployment/triggers.py`: Cron and event trigger management\n- `server/services/deployment/state.py`: DeploymentState, TriggerInfo dataclasses\n- `server/services/execution/models.py`: `ExecutionContext.create()` with `_pre_executed` support\n- `server/services/execution/executor.py`: Continuous scheduling with `asyncio.wait(FIRST_COMPLETED)`\n\n### AI Chat Model System (5-Layer Architecture)\n\nChat-model nodes (`openaiChatModel`, `anthropicChatModel`, ...) render through `SquareNode` from the backend NodeSpec. Direct chat and every new agent execution route through the native SDK facade (`ChatUnifier` in `services/llm/`); the provider surface is 11 cloud providers, Ollama and LM Studio, plus any number of user-named OpenAI-compatible endpoints (RFC-0003). Thirteen standalone chat-model nodes live under `server/nodes/model/` (one per fixed provider except xAI, which is selected directly from agent parameters, plus `openaiCompatibleChatModel` for a named endpoint). Model params (max output, context length, thinking type, temperature range) come from `ModelRegistryService`. The provider architecture, proxy/local-LLM routing, and the per-provider model + thinking/reasoning matrix (budget / effort / format) all live in **[Native LLM SDK](./docs-internal/native_llm_sdk.md)**. There is one wire standard (`MessageWire`) and no `llm_engine` / `message_wire_version` discriminator: the cutover-era markers and the `InvalidAgentLLMEngine` refusal path were purged (`tests/llm/test_single_wire_standard.py` fails the build if they reappear), and pre-cutover deployments are handled by Reset. The runtime output schema (`thinking` field for downstream nodes) is backend-served via `register_output_schema` (see [Plugin System](./docs-internal/plugin_system.md)).\n\n## AI Agent Node Architecture\n\nAI Agent (`aiAgent`) and Chat Agent / Zeenie (`chatAgent`) both use the plain-async `run_native_agent_loop` in `server/services/agent_runtime.py` and support memory / skills / tools / task input. `AIService.execute_agent()` and `execute_chat_agent()` prepare the same canonical native messages and `AgentToolSpec` values, then the loop appends each lossless assistant message before executing its tool calls, hot-rebinds the tool surface after canvas mutations, and stops when the model returns no tool calls (with `max_iterations` as a safety cap). Connection collection is `collect_agent_connections` in `server/services/plugin/edge_walker.py` (5-tuple: context, skill, tool, input, task); the pre-Wave-11 `handle_ai_agent`/`handle_chat_agent` handlers are gone (dispatch is per-plugin `execute_op` under `server/nodes/agent/<plugin>/__init__.py`). The legacy `_run_agent_loop` is deleted, as are the cutover-era `llm_engine` markers and the `InvalidAgentLLMEngine` refusal path; pre-cutover deployments are handled by Reset.\n\n**`max_iterations` precedence differs by runtime. Temporal (`prepare_agent_payload`, highest->lowest): per-node `parameters.max_iterations` > `UserSettings.agent_recursion_limit` > env `AGENT_RECURSION_LIMIT` (default 200), with a hardcoded 200 if `Settings` cannot instantiate; it never reads `llm_defaults.json`. In-process (`execute_agent` / `execute_chat_agent`): `UserSettings.agent_recursion_limit` > `get_model_registry().get_agent_defaults()`, where env `AGENT_RECURSION_LIMIT` wins and `llm_defaults.json:agent.recursion_limit` is the last resort; the per-node tier is never read there, and no agent plugin currently declares a `max_iterations` Params field.**\n\nFull reference — agent loop, skill injection, tool building, input/auto-prompt fallback (message>text>content>str), handle topology, spec-driven `AIAgentNode`, durable Task Manager delegation (Temporal child workflows plus the legacy bridge), and specialized-agent routing — in [docs-internal/agent_architecture.md](./docs-internal/agent_architecture.md); low-level compatibility mechanics in [agent_delegation.md](./docs-internal/agent_delegation.md), and the authoritative team-lead contract in [agent_teams.md](./docs-internal/agent_teams.md).\n\n## Architecture Patterns\n- **Plugin-first (Wave 11).** One folder per plugin under [`server/nodes/<group>/<plugin>/`](./server/nodes/) rooted at `__init__.py`, subclassing `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode`. Auto-registers via `__init_subclass__`. See [`docs-internal/plugin_system.md`](./docs-internal/plugin_system.md).\n- **Backend NodeSpec is the SSOT** for icon, colour, handles, params, output schema, uiHints, palette group. Frontend consumes via `useNodeSpec(type)` and adapts the JSON Schema → `INodeTypeDescription` shape through [`adapters/nodeSpecToDescription.ts`](./client/src/adapters/nodeSpecToDescription.ts) (legacy interface kept as a render contract; not a parallel schema system).\n- **Component-driven frontend.** shadcn/ui primitives + Tailwind tokens; canvas nodes are spec-driven (see \"Spec-driven component design\" above).\n- **State management.** TanStack Query owns server-backed data; Zustand (`useAppStore`, `nodeStatusStore`) owns UI state and slice-subscribed high-frequency push state. Slice-selector reads only — never whole-store destructure (see \"Frontend Performance Architecture\").\n- **Execution pipeline.** Temporal-distributed activities for plugin execution; `WorkflowExecutor` for parallel orchestration; per-node retry / timeout / heartbeat declared on the plugin class.\n\n## File Structure Cleanup\n**Removed Files:**\n- `src/nodeDefinitions.ts` + `src/nodeDefinitions/` (27 files) — superseded by backend NodeSpec SSOT; frontend resolves specs via `lib/nodeSpec.ts` + `adapters/nodeSpecToDescription.ts`\n- `src/nodeDefinitions.backup.ts` (backup file)\n- `src/schemas/` directory (unused schema system)\n- `src/utils/schemaParser.ts` (legacy parser)\n- `src/utils/nodeSchemaParser.ts` (unused modern parser)\n- `src/types/NodeSchema.ts` (legacy schema types)\n\n**Cleaned Code:**\n- Removed unused imports and dead functions\n- Eliminated legacy NodeDefinition interface \n- Streamlined parameter handling logic\n- Maintained backward compatibility only where actively used\n\n## Testing & Validation\n```bash\n# Development server test\ncurl -I http://localhost:${PYTHON_BACKEND_PORT:-5678}\n\n# TypeScript validation — the gate is TypeScript 7 (native Go) at the REPO ROOT.\nbun run typecheck # root: tsc --noEmit -p client/tsconfig.json\nbun run --filter react-flow-client typecheck # what CI runs; delegates up to the same gate\n# NOT a bare `bun x tsc --noEmit` (or `npx tsc`) — there is no root tsconfig.json.\n# NOT client's `typecheck:tsc` — that resolves [email protected], kept only because\n# typescript-eslint's peer range excludes 6/7. It is a second opinion, not the gate.\n\n# Build verification\nbun run build\n```\n\n## Production Deployment\n\n### Self-Deploy CLI (`company deploy`) — current path\nOne command provisions a login-gated OpenCompany VM on GCP or AWS. Two stages: the\noperator's **cloud CLI** (`cli/commands/deploy/providers/gcp.py` / `aws.py`) handles auth and context: gcloud does\nproject/region/zone resolution + ADC verification + API enablement; the aws CLI checks the signed-in identity, resolves\nthe region (`--region`, `AWS_REGION`, `AWS_DEFAULT_REGION`, the CLI's configured region, then `us-east-1`), hands its\ncredentials to Terraform through `aws configure export-credentials` (so `aws login` sessions work) and refuses a region\nwithout a default VPC. Then **Terraform** (`cli/terraform/<provider>/`, one shared variable set, so `up.py` writes one\ntfvars shape) owns all resources. GCP: VM, firewall, artifact bucket (local `bun pm pack --quiet` source), service\naccount, and a GCE startup script (re-run on every boot) that installs bun (`BUN_INSTALL=/usr/local`, official installer) + uv, `bun add -g`s the package,\nprovisions 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\n`company serve` under systemd — no Node, no npm on the VM. AWS: a security group and an EC2 instance whose cloud-init\nscript (first boot only) runs `install.sh` as the login user with a published release (`--source release` only) and\npoints systemd at `$APP_HOME/.bun/bin/company` with a PATH `Environment=` line; the module ignores `ami` and `user_data`\nchanges, so a later apply never replaces a running instance and deletes its disk. Each adapter names its default\n`--machine-type` (`e2-standard-2` / `t3.micro`) and the `--source` values its module supports. Login gate = built-in auth (`VITE_AUTH_ENABLED=true`,\n`AUTH_MODE=single`) with the owner credential generated at deploy time and seeded on first boot.\n`build_app_env` (`cli/commands/deploy/_secrets.py`) also sets `DEPLOYMENT_MODE=cloud` on\ndeployed VMs and mints fresh `JWT_SECRET_KEY` / `SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` per deploy; Temporal, the event\nframework and `HOST` keep their `.env.template` values (Temporal on, as in the Docker image). A VM that installs 0.2.0 or\n0.2.1 stops with \"Project not built\" (errors.md #25, fixed after 0.2.1), which is every AWS VM until the next release.\n\n`--name` (default `opencompany`; 6-30 lowercase letters, digits and hyphens, because it is also a cloud resource id)\nnames a deployment: its state folder and its resource id. One machine drives one VM per name, and a name stays with\nthe provider that created it.\n\n```bash\ncompany deploy up --provider gcp --owner-email [email protected] # provision + install + print URL/creds\ncompany deploy up --provider aws --name acme-corp --owner-email [email protected]\ncompany deploy status [--name acme-corp] # URL + /health\ncompany deploy destroy [--name acme-corp] # terraform destroy + clear state\n```\n\nKey files: `cli/commands/serve.py` (single-port runtime: one supervised uvicorn process fronting API + WS + built SPA;\nthe bun-hosted JS code-exec sidecar, WhatsApp and Temporal are backend-spawned on demand), `cli/commands/deploy/` (verbs, secrets, Terraform driver, provider CLI adapters),\n`cli/terraform/gcp/` and `cli/terraform/aws/` (HCL modules + `startup.sh.tftpl`). `prepare_workdir` copies only a\nmodule's `*.tf` / `*.tftpl` files, so Terraform state or tfvars left in a module folder never reach a deployment.\nDeployment state lives at `<DATA_DIR>/deploy/<name>/` (`~/.opencompany/deploy/opencompany/` by default); only\n`company deploy destroy` removes it (`company clean` keeps a repo-local `.opencompany/deploy`, see `_OPENCOMPANY_KEEP`).\nThe deploy code is fully delinked from `company build` /\n`company clean` (lazy verb stubs in `cli/cli.py`; nothing in the build pipeline imports it).\nFor upgrades, `_state.py` also discovers pre-rebrand `deploy/machinaos/` state for the default name\nunder the configured root, `~/.machina`, or `<repo>/.machina`. Such deployments\nretain their durable `machinaos` cloud/systemd id; changing it would cause\nTerraform replacement or strand live state. Fresh deployments use `opencompany`.\nThe `machina` executable remains only as a deprecated legacy alias; use `company`\nfor all new commands and automation.\n\nThe legacy `deploy.sh` (docker-compose images over SCP to a GCE box) was removed.\n\n### Docker (self-hosting)\n\n`docker compose up -d --build` builds a single image from source and runs it with all state on one named volume. The image runs the backend the way the desktop shell does (uvicorn directly, env file on the data volume, readiness on `/health/ready`), not through `company serve`. Full guide: **[docker.md](./docs-internal/docker.md)**.\n\n### Docker Deployment (legacy reference)\n\nThe historical Docker Compose topology (4-container stack: redis / backend / frontend / whatsapp, nginx reverse proxy, dev + prod compose files, env config, resource usage, useful commands) and the `npm run build` / `npm run preview` local-build commands are preserved in **[Deployment (legacy reference)](./docs-internal/deployment_legacy.md)**.\n\n## Authentication System\n\nn8n-style JWT auth in HttpOnly cookies. `VITE_AUTH_ENABLED=false` bypasses login (anonymous owner, dev); when enabled, `AUTH_MODE=single` (first user = owner, registration then closed) or `multi` (open registration). Backend: `User` (bcrypt) + `UserAuthService` + `/api/auth/*` router + `AuthMiddleware` (public-path allowlist + `/webhook/` prefix). `/login` and `/register` are throttled by the in-process `core/rate_limit.py` sliding window (`AUTH_RATE_LIMIT_*`; no `slowapi` dependency — the primary runtime is a single uvicorn worker). Frontend: `AuthContext` (a TanStack-Query bootstrap check that never retries on its own, plus `useMutation` for login/register/logout) + `ProtectedRoute` (the sign-in gate: Connecting while the server can't be reached, then sign-in or the app, and Connecting over the app while the WebSocket is down) + `LoginPage` (RHF + zod via the shadcn `Form` primitives; after a sign-in its welcome, `SignedIn`, stays while `signingIn` — the login/register mutations' own state, in flight or succeeded — until `finishSignIn` resets them); all API calls send `credentials: 'include'`, and the WebSocket refuses to connect without the cookie.\n\n**Two context distinctions that are load-bearing, not stylistic:** `isLoading` is the bootstrap query (gates the whole app in `ProtectedRoute`) while `isSubmitting` is per-request — using the former to disable the login form disables nothing, since it has already settled by the time that form renders. And `error` means \"cannot reach the server\" while `submitError` is the server's own rejection text, shown as the server words it (or `AUTH_UNREACHABLE` when a sign-in got no answer); a `setQueryData` write is a *success* value, so routing a login failure through the status cache surfaces no error at all and additionally collapses `can_register`.\n\n**Read the Known Limitations section of [authentication.md](./docs-internal/authentication.md) before building on this.** `AUTH_MODE=multi` provides authentication but no data isolation — `request.state.user_id` is written by the HTTP middleware (`middleware/auth.py`) and read by no route handler, so REST traffic shares one workflow store and one credential store. The WebSocket surface is different: `websocket.state.user_id` (`routers/websocket.py`) IS consumed by `execution_principal` (`services/authz/ws_surface.py`) to pick the principal an execution runs as, so identity is resolved there even though enforcement is missing. There is also no CSRF token and no token revocation (`User.is_active` is the only lever).\n\n**Load-bearing rule:** JWT handling uses **PyJWT** (`import jwt`, HS256 with `Settings.jwt_secret_key`). Do NOT reintroduce `python-jose` — it drags in pure-Python `ecdsa` with the unpatchable Minerva timing-attack advisory (GHSA-wj6h-64fc-37mp). Full reference (models, router, middleware, config, startup retry, key files, deps) in **[Authentication](./docs-internal/authentication.md)**.\n\n## Encrypted Credentials System\n\nAPI keys and OAuth tokens live in a separate encrypted database (`credentials.db`): Fernet (AES-128-CBC + HMAC-SHA256) with the key derived via PBKDF2HMAC-SHA256 (600K iterations, OWASP-2024) from the server-scoped `API_KEY_ENCRYPTION_KEY` (`.env`) + a salt stored in `credentials.db`, initialized at startup and held for the process lifetime. Two distinct systems that never cross: API keys (`store_api_key`/`get_api_key` → `EncryptedAPIKey`) and OAuth tokens (`store_oauth_tokens`/`get_oauth_tokens` → `EncryptedOAuthToken`). `core/credential_backends.py` also defines Keyring and AWS Secrets Manager backends behind a `create_backend` factory, but nothing calls it: every install uses Fernet in `credentials.db`, and `CREDENTIAL_BACKEND` has no effect beyond `Settings` rejecting a value other than `fernet` / `keyring` / `aws`.\n\n**Load-bearing rule:** every credential operation MUST go through `AuthService` (`from core.container import container; container.auth_service()`); routers must NEVER touch `CredentialsDatabase` directly. Full pipeline, cache contract, backends, config, key files, and design decisions are in **[Credentials Encryption](./docs-internal/credentials_encryption.md)**.\n\n## Example Workflows\n\n### Overview\nExample workflows are pre-built workflow templates that auto-load on first use. They provide users with starting points to explore the platform's capabilities. Seeds live as JSON files at **`<repo>/.opencompany/workflows/`** — the only git-tracked content under `<repo>/.opencompany/` (everything else there is `.gitignore`d as runtime state). The path is also preserved by `company clean` (see `_OPENCOMPANY_KEEP` in `cli/commands/clean.py`).\n\n### Architecture\n```\n<repo>/.opencompany/workflows/ # Shipped seed JSONs (git-tracked)\n├── AI_Assistant.json\n├── AI_Employee.json\n└── Claude_Assistant.json\n\nserver/services/\n└── example_loader.py # Loads and imports examples via core.paths.example_workflows_dir()\n\nserver/models/database.py # UserSettings.examples_loaded flag\nserver/core/database.py # Migration for examples_loaded column\nserver/routers/database.py # Auto-load logic in get_all_workflows\n```\n\n### How It Works\n1. **First Fetch Detection**: When `get_all_workflows` API is called, it checks `UserSettings.examples_loaded`\n2. **Auto-Import**: If `examples_loaded=false`, calls `example_loader.get_example_workflows()` which reads from `core.paths.example_workflows_dir()` = `<repo>/.opencompany/workflows/`\n3. **Mark Complete**: Sets `examples_loaded=true` to prevent re-import on subsequent fetches\n4. **Anonymous Support**: Uses `user_id=\"default\"` when `VITE_AUTH_ENABLED=false`\n\n### Workflow JSON Format\nExample workflows use the same format as UI exports:\n```json\n{\n \"id\": \"hello_world\",\n \"name\": \"Hello World\",\n \"description\": \"A simple workflow with a start node\",\n \"nodes\": [\n {\n \"id\": \"start_1\",\n \"type\": \"start\",\n \"position\": {\"x\": 250, \"y\": 150},\n \"data\": {\"label\": \"Start\"}\n }\n ],\n \"edges\": [],\n \"nodeParameters\": {\n \"start_1\": { \"someParam\": \"value\" }\n },\n \"version\": \"0.0.36\"\n}\n```\n\n**Fields:**\n| Field | Description |\n|-------|-------------|\n| `id` | Unique identifier (prefixed with `example_` when imported) |\n| `name` | Display name in workflow sidebar |\n| `description` | Optional description |\n| `nodes` | Array of node objects with id, type, position, data |\n| `edges` | Array of edge connections between nodes |\n| `nodeParameters` | Optional map of node_id to parameter objects (saved to DB on import) |\n| `version` | App version (e.g., \"0.0.36\") |\n\n### Key Files\n| File | Description |\n|------|-------------|\n| `.opencompany/workflows/*.json` | Shipped seed workflow JSONs (git-tracked) |\n| `server/core/paths.py` | `example_workflows_dir()` → `<repo>/.opencompany/workflows/` (fixed path, NOT under `DATA_DIR`) |\n| `server/services/example_loader.py` | `get_example_workflows()`, `import_examples_for_user()` |\n| `server/models/database.py` | `UserSettings.examples_loaded` field |\n| `server/core/database.py` | Migration adds `examples_loaded` column |\n| `server/routers/database.py` | Auto-load check in `get_all_workflows` |\n\n### Example Loader Service\n```python\n# server/services/example_loader.py\nfrom core.paths import example_workflows_dir\n\ndef get_example_workflows() -> List[Dict[str, Any]]:\n \"\"\"Load all example workflow JSON files from disk.\"\"\"\n examples_dir = example_workflows_dir()\n ...\n\nasync def import_examples_for_user(database) -> int:\n \"\"\"Import all examples using existing database.save_workflow().\n Returns count of workflows imported.\"\"\"\n```\n\n### Auto-Load Logic\n```python\n# server/routers/database.py - get_all_workflows endpoint\nuser_id = \"default\"\nsettings = await database.get_user_settings(user_id)\n\nif not settings or not settings.get(\"examples_loaded\", False):\n count = await import_examples_for_user(database)\n if count > 0:\n logger.info(f\"Auto-loaded {count} example workflows\")\n current = settings or {}\n current[\"examples_loaded\"] = True\n await database.save_user_settings(current, user_id)\n```\n\n### Adding Custom Examples\n1. Export a workflow from the UI (File > Export)\n2. Copy the JSON file to `<repo>/.opencompany/workflows/` (git-tracked seed location)\n3. Edit the `id` and `name` fields as needed\n4. Delete `~/.opencompany/workflow.db` (or set `examples_loaded=false` in DB)\n5. Restart server - examples auto-load on first workflow list fetch\n\n### Database Migration\nThe `examples_loaded` column is automatically added to existing databases:\n```python\n# server/core/database.py - _migrate_user_settings()\nif \"examples_loaded\" not in columns:\n await conn.execute(text(\n \"ALTER TABLE user_settings ADD COLUMN examples_loaded BOOLEAN DEFAULT 0\"\n ))\n```\n\n## Onboarding Service\n\nThe Welcome guide on Home ([features/home/onboarding/](./client/src/features/home/onboarding/), mounted by `HomeShell`): Welcome, Connect an AI model (the shared `CredentialsBrowser` cut to AI models) and Your first hire (Home's composer through genui's effect-free `useJobComposer`). It opens on first launch for an owner whose `UserSettings.onboarding_completed` is false, at the saved `onboarding_step`, and again from the header's Guide button or Settings → Help; skipping finishes it, and existing users were marked finished by the migration (`onboarding_completed=1` where `examples_loaded=1`). The open state and step live in `homeStore.guide` with a once-per-session `checked` flag, so a remount never reopens it. Once it is finished, a Get started checklist in Home's corner ticks off four first steps (two latched in `UserSettings`: `getting_started_said_hello`, `getting_started_approved_draft`). With `VITE_NORMAL_MODE=false` there is no Home and so no guide and no checklist. Steps, state, tests and key files are in **[Onboarding Service](./docs-internal/onboarding.md)**.\n\n## AI Chat Model Development Guide\n\nA new chat-model provider is one self-contained folder under `server/nodes/model/<provider>_chat_model/` with `__init__.py` declaring a `ChatModelBase` subclass (auto-registers via `BaseNode.__init_subclass__`; the frontend renders it through `SquareNode` from the NodeSpec with zero TS changes). Credentials live in `server/nodes/model/_credentials.py`. The full recipe — native provider registration under `services/llm/providers/`, `llm_defaults.json` configuration, the `_COMPAT_PROVIDERS` entry required for OpenAI-compatible endpoints, and the per-provider implementation-file map — is in **[Native LLM SDK](./docs-internal/native_llm_sdk.md)**.\n\n## Context and Memory (RFC-0002)\n\nTwo different things, deliberately separated. Read [RFC-0002](./RFC-0002-AGENT-CONTEXT-AND-MEMORY.md) before touching either.\n\n**Context** is the plain conversation store — what the agent actually sent and received, as JSON messages. One table (`agent_conversations`, [models/agent_context.py](./server/models/agent_context.py)) keyed by **`(workflow_id, generation, agent_node_id)`** → `messages` (MessageWire list) + `updated_at`; the service is four functions in [`services/agent_context/conversation.py`](./server/services/agent_context/conversation.py) (`load_conversation` / `save_conversation` (per-key lock, whole-list upsert, post-commit notify) / `clear_conversation` / `list_conversations`). Every firing of an agent — chat message or taskTrigger review — loads the row at run start and saves the live message list back per turn, so the one conversation continues across firings; Reset admits a new generation = new key = fresh conversation, AND the Context node's `reset_execution_state` clears the workflow's stored rows + fences warm claude subprocesses + broadcasts `context.updated` — the generation bump alone is not enough because the panel shows the newest STORED generation, so surviving rows would render the pre-Reset conversation as the live context and Reset would look like a no-op. (A plain Stop→Start leaves prior generations as inert, non-browsable history until workflow delete or Reset.) The `context` node (`server/nodes/context/`, `input-context` handle) is the **opt-in switch and viewing panel**, nothing more — it declares no parameters. It is an ordinary canvas node the user deletes like any other: `normalize_workflow_graph` never creates, reconnects or deletes one (rewriting a legacy `simpleMemory -> input-memory` edge is the one exception), save never restores a deleted one, and `workflow_validator` does not require one — `INVALID_CONTEXT_EDGE` / `MULTIPLE_CONTEXTS` / `SHARED_CONTEXT` still reject ambiguous wiring. Deleting it opts the agent out, and the save's archive outbox then clears the workflow's stored conversations. The palette does not offer it (`uiHints.systemManaged`), so a deleted Context cannot be re-added from there. This is the LangGraph `thread_id` / OpenAI `conversation_id` pattern; the previous hash-chained journal (threads, epochs, checkpoints, blobs, provider bindings, session/task/execution thread routing) is deleted.\n\nLoad-bearing invariants, learned the hard way: (1) *attaching a Context node must never change what the agent sends* — requests are always built from `messages`; `conversation_key` only says where to save. (2) *The store records what was sent, after it was sent* — `agent.execute_llm_step` saves `[...sent, assistant]` immediately after `ChatUnifier.chat` returns; nothing writes before a request exists (the retired `prepare_context` activity did, and journalled fabricated requests). (3) **Loads are LOUD, saves are best-effort** — `agent.prepare_payload` raises `ApplicationError(\"ConversationLoadFailed\")` (retryable) / `ApplicationError(\"ConversationTooLarge\")` (non-retryable, 1 MB cap) rather than silently running an amnesiac agent that burns tokens on an empty prompt; the save runs post-billing and swallows failures with a WARN. (4) Seeding precedence is **carried rollover transcript > stored conversation > bare build** — a `continue_as_new` resume carries the live transcript in its resume marker (size-guarded ≤ 1 MB) and must win over the store. Locked by `tests/temporal/test_agent_workflow.py::TestConversationIdentity`.\n\nBoth paths implement the same contract: Temporal via `prepare_agent_payload` (load) + `_save_conversation` in the LLM activity; in-process via `AIService._prepare_context` → `_AgentContextRuntime{key, history, database}` + the loop's `conversation_saver=runtime.save` hook. Specialized providers (claude_code / codex / rlm) use `SpecializedAgentContextBridge` ([services/cli_agent/context_bridge.py](./server/services/cli_agent/context_bridge.py)): `resolve` loads, `augment_prompt` renders the transcript into the prompt, `record_turn(original_prompt, response)` saves — always the ORIGINAL prompt, never the augmented one, or the save nests the transcript inside itself. The claude pool key is the conversation key (`(workflow_id, agent_node_id, generation)`), so a Reset's generation bump fences warm subprocesses at `acquire`; a same-generation panel Clear calls `ClaudeSessionPool.terminate_conversations`. Manual canvas Runs persist nothing (`generation > 0` gate — only Start admits a generation).\n\n**Live viewing is emitted at the persistence boundary, not per caller.** `save_conversation` is the one place every writer passes through, and it announces durable saves through the fanout registry in [`services/agent_context/listeners.py`](./server/services/agent_context/listeners.py) — `register_conversation_listener` / `notify_conversation_saved` — with `nodes/context/__init__.py` registering the broadcaster. Same shape as the plugin registries, same reason: the store must never import `nodes/`. The notification fires after the commit, and a listener can never fail a save (failures log at WARNING — a silently failing listener is exactly how \"the panel never updates live\" becomes undiagnosable). The single Context event (`context.updated`) **broadcasts directly via `get_status_broadcaster()`, not through `services.events.dispatch.emit`** — no canary consumer exists for `com.opencompany.context.*`, so `emit`'s Visibility query would match nothing once per save. Payload is identity + count only; the panel refetches through the authorized `get_agent_context` WS handler (`clear_agent_context` is the other handler; the journal-era fork/export handlers are gone). One `case 'context.updated'` in `WebSocketContext.tsx` invalidates `['agentContext']`; the panel contains no subscription code. See [event_framework.md → UI-only lifecycle events](./docs-internal/event_framework.md).\n\n**The store also stamps timestamps.** `save_conversation` attaches a `ts` (UTC ISO) to every stored message: callers regenerate wires from live `Message` objects each turn, so the store keeps the original stamp for the unchanged prefix and stamps only the appended turn — a message's time is when it first persisted, not when the conversation last saved. `ts` is a stored-view field only; `message_from_wire` ignores it, so it never reaches a provider on any path.\n\n**Compaction never touches the system prompt, and its summary rides a USER message.** The AgentWorkflow's threshold compaction swaps `messages` for `[original system (verbatim), user(summary + current request)]`, followed by the latest turn verbatim on runs recorded with `context_pressure_version` 1 (its tool results are still unread). The system prompt is the agent's byte-stable contract (prompt caching, behavioral consistency), and the seeding filter drops stored system messages — so a summary stored under the system role (the earlier design) silently vanished on the next firing while the noisy tool tail survived it. Tool calls/results of the summarized turns are dropped at the swap and live only inside the summary; tool messages after the summary in the panel are the kept latest turn or new post-compaction work. Trigger, swap (before→after counts), and summarizer usage all log at INFO; a summarizer failure after the activity's retries fails the run (`CompactionError`), it is not best-effort. Locked in `tests/temporal/test_agent_workflow.py` and `tests/temporal/test_agent_workflow_pressure.py`. See [agent_context_flow.md → Compaction](./docs-internal/agent_context_flow.md).\n\n**The transcript is bounded in bytes, not only in tokens** (`docs-internal/errors.md` #28: uncapped TikHub results grew a saved row past the 1 MB seed cap, and every later firing failed with `ConversationTooLarge`). Each external tool result is cut to `tool_result_max_chars` characters (per-user Settings > Tool Result Limit, else env `TOOL_RESULT_MAX_CHARS`, default 100,000; delegated-agent answers, skill loads and Task Manager are exempt) by `server/services/tool_output.py`, on both paths. On Temporal, `agent.prepare_payload` records `tool_result_max_chars`, `transcript_budget_bytes` (three quarters of `TEMPORAL_PAYLOAD_WARN_BYTES`) and `context_pressure_version`; after each tool turn over the budget the workflow clears earlier turns' results to a placeholder (oldest and external first), gates summarization on the NEXT request (the last step's `total_tokens` plus the turn's added characters, never a running sum of every step), summarizes only earlier turns, and cuts an overflowing latest turn to fit (`server/services/temporal/agent_context_pressure.py`). The recorded version selects these rules on replay: a history recorded without it replays the original cumulative gate, so any change to the rules needs a new version. See [agent_context_flow.md → Transcript size](./docs-internal/agent_context_flow.md).\n\n**Memory** (node type `simpleMemory`, displayed as **\"Memory\"** — the wire type is stored verbatim in graphs/pool keys and must not be renamed; plugin `server/nodes/tool/simple_memory/`) is a `ToolNode` on `input-tools` — durable facts the agent explicitly remembers, recalls, updates and forgets. It is not conversation history and has no markdown surface; `SimpleMemoryParams` declares only `reset_policy` (with `extra=\"ignore\"`, so leftover legacy keys on migrated graphs are inert). `reset_policy` is in `server_controlled_fields`, which stops the **model** overriding it through tool arguments — it does not stop the operator editing it. Two model-facing contracts are load-bearing: (1) the `tool_description` ClassVar is imperative — *check memory (recall/list) before answering anything about the user; never claim ignorance without checking* — because with a passive \"store and retrieve when useful\" wording, models answered \"I don't know who you are\" from priors while the user's name sat one recall away (`tool_schema_locked = True` pins this description against stale ToolSchema rows). (2) Every durable mutation (remember/update/forget/clear, from the agent tool call or the panel) broadcasts the identity-only `memory.updated` CloudEvent ([`_events.py`](./server/nodes/tool/simple_memory/_events.py), same direct-broadcast rationale as `context.updated`), which `WebSocketContext.tsx` routes to invalidate the `memoryItems`/`memoryItem` queries.\n\nLifecycle helpers live in `server/services/memory/`; token tracking and compaction thresholds are in **[Memory Compaction](./docs-internal/memory_compaction.md)**. The pre-RFC-0002 markdown model is archived at [ARCHIVE/memory_lifecycle.md](./docs-internal/ARCHIVE/memory_lifecycle.md).\n\n## Memory Compaction, Token Tracking, and Cost Calculation\n\nMemory-connected standard agents aggregate native `Usage` across every model\nturn. The in-process path calls `CompactionService.track()` after execution to\npersist session metrics and can trigger `compact_context()`, which performs a\nshared client-side summarization call through `ChatUnifier`. The Temporal\n`AgentWorkflow` also aggregates and returns loop usage and can invoke the same\nsummarizer, but it does not currently persist that loop aggregate through\n`CompactionService.track()`. Provider-native Anthropic/OpenAI context-management\ncompaction is not used by the agent runtime. Executions without connected\nmemory still aggregate usage inside the loop but do not create session\ncompaction records.\n\n**Threshold precedence inside `CompactionService.track()` (highest-to-lowest): per-session `SessionTokenState.custom_threshold` > per-user `UserSettings.compaction_ratio` > env `COMPACTION_RATIO` (default 0.8) > `llm_defaults.json:agent.compaction.ratio`.** The Temporal agent workflow currently prepares its threshold from the model/user/env ratio without reading the per-session custom threshold, so do not promise that override on every execution path.\n\nFull reference — the `CompactionService` API, shared client-side compaction, the 5-section summary format, DB models (`TokenUsageMetric` / `SessionTokenState` / `CompactionEvent`), WS handlers, and the broadcast events — in **[Memory Compaction](./docs-internal/memory_compaction.md)**; per-service API cost tracking is in **[Pricing Service](./docs-internal/pricing_service.md)**.\n\n## API Cost Tracking\n\nCentralized cost tracking for third-party API services (Twitter/X, Google Maps). See [Pricing Service](./docs-internal/pricing_service.md) for full documentation.\n\n### Two Tracking Methods\n\n**1. Manual Tracking** - For services using native SDKs:\n```python\n# usage tracked inside server/nodes/twitter/\nawait _track_twitter_usage(node_id, 'tweet', 1, workflow_id, session_id)\n\n# usage tracked inside server/nodes/location/_service.py\nawait _track_maps_usage(node_id, 'geocode', 1, workflow_id, session_id)\n```\n\n**2. Automatic HTTPX Tracking** - For services using httpx client:\n```python\nfrom services.tracked_http import get_tracked_client, set_tracking_context\n\nset_tracking_context(node_id=\"twitter-1\", session_id=\"user-123\")\nclient = get_tracked_client()\nresponse = await client.post(\"https://api.twitter.com/2/tweets\", json={...})\n# Automatically tracked via HTTPX response event hook!\n```\n\n### Pricing Configuration\n\nAll pricing in `server/config/pricing.json` (user-editable):\n- `llm`: Per-model token pricing (USD/MTok)\n- `api`: Per-service operation pricing (USD/request)\n- `operation_map`: Maps handler actions to pricing operations\n- `url_patterns`: Regex patterns for automatic HTTPX tracking\n\n### Database Storage\n\n`APIUsageMetric` table stores: service, operation, endpoint, resource_count, cost (USD)\n\n### Frontend Display\n\n`credentials/sections/ApiUsageSection.tsx` shows per-service API usage and costs; `LlmUsageSection.tsx` shows per-provider token usage. Both read **precomputed** costs (`SUM(APIUsageMetric.cost)` / `TokenUsageMetric`) — neither reads `config/pricing.json`, which is consumed only server-side by `PricingService` at execution time.\n\n## AI Agent Tool System\n\n### Overview\nTool nodes provide capabilities that AI Agents can invoke during reasoning. Each tool node connects to the AI Agent's `input-tools` handle and defines a schema for the LLM to understand how to call it.\n\n### Architecture\n```\nTool Node (calculatorTool) → (tool output) → AI Agent (input-tools handle)\n ↓\n AIService builds AgentToolSpec values\n ↓\n run_native_agent_loop sends ToolDef schemas\n ↓\n LLM selects zero or more tool calls\n ↓\n Tool executor runs handlers\n ↓\n Native tool results return to LLM\n```\n\n### Tool Execution Flow\n1. **Tool Discovery**: AI Agent scans edges for nodes connected to `input-tools` handle\n2. **Schema Building**: `_build_tool_from_node()` in `ai.py` combines the Pydantic validation model with an inlined JSON schema in an `AgentToolSpec` / `ToolDef`\n3. **Provider Compilation**: `run_native_agent_loop` passes provider-neutral `ToolDef` values through `ChatUnifier`; each native provider compiles the schema it supports\n4. **LLM Decision**: LLM decides when to call tools based on user query\n5. **Status Broadcast**: `executing_tool` status broadcast with tool_name for UI animation\n6. **Tool Execution**: `execute_tool()` in `tools.py` dispatches to appropriate handler\n7. **Result Return**: Native tool-result messages are appended for continued reasoning\n\n### Key Files\n| File | Description |\n|------|-------------|\n| `server/services/handlers/tools.py` | Tool execution handlers |\n| `server/services/ai.py` | `_build_tool_from_node()` / `_get_tool_schema()` - provider-neutral tool specs and Pydantic validation |\n| `server/services/agent_runtime.py` | `AgentToolSpec` and the shared native agent loop |\n| `server/services/plugin/edge_walker.py` | `collect_agent_connections` — tool/skill/memory discovery from edges |\n\n### Adding a new tool or specialized agent (Wave 11)\n\n**Single source of truth: [`server/nodes/README.md`](./server/nodes/README.md)** (5-minute recipe) and [`docs-internal/plugin_system.md`](./docs-internal/plugin_system.md) (full reference). The pre-Wave-11 `toolNodes.ts` / `specializedAgentNodes.ts` / `AGENT_CONFIGS` files do not exist — the canonical authoring shape is one Python file.\n\nThe whole workflow:\n\n```python\n# server/nodes/tool/<plugin>/__init__.py ← for a tool\n# server/nodes/agent/<plugin>/__init__.py ← for a specialized agent\nclass MyTool(ToolNode): # or SpecializedAgentBase for an agent\n type = \"myTool\"\n display_name = \"My Tool\"\n group = (\"tool\", \"ai\")\n component_kind = \"tool\" # or \"agent\"\n Params = MyParams # Pydantic — feeds UI + AI tool schema\n Output = MyOutput\n @Operation(\"run\")\n async def run(self, ctx, params): ...\n```\n\n`BaseNode.__init_subclass__` registers the class into `_NODE_CLASS_REGISTRY` (first), then into `NODE_METADATA`, `_DIRECT_MODELS`, `NODE_OUTPUT_SCHEMAS`, and `_HANDLER_REGISTRY` on import. The class-registry-first order matters: `_metadata_dict` calls `get_plugin_icon_path(cls.type)` which goes through `get_node_class()`. NodeSpec emits at `GET /api/schemas/nodes/<type>/spec.json`. The frontend auto-discovers via `useNodeSpec` + `componentKind` dispatch (see \"Spec-driven component design\" above). Icon goes in `<plugin>/icon.svg` (or `visuals.json` for emoji / library brand); color goes in `<plugin>/meta.json` (or `visuals.json` legacy fallback).\n\n**Cross-cutting edits that are still required (small):**\n- New specialized agent: update `AI_AGENT_TYPES` and the canonical teammate\n discovery/validation surfaces so a team lead can authorize it through\n `input-teammates`. Team leads delegate with Task Manager; `delegate_to_*`\n remains an internal/legacy dispatch identity and must not be taught as the\n model-facing team contract.\n- Brand-new uiHint flag: add to `INodeUIHints` in [`client/src/types/INodeProperties.ts`](./client/src/types/INodeProperties.ts) AND to the `known` set in `test_ui_hints_only_carry_known_flags` (`server/tests/test_node_spec.py`).\n\n**No edits needed:** any TypeScript node definition file, `_get_tool_schema()`, `AGENT_CONFIGS`, `AGENT_WITH_SKILLS_TYPES`, `aiAgentTypes`, `Dashboard.tsx`, `MiddleSection.tsx`, `InputSection.tsx`, or any of the other arrays the pre-Wave-11 docs listed.\n\n### Tool Execution Animation\nTool nodes display execution status via the standard node status system:\n- Backend broadcasts `executing` status to tool node when AI Agent calls it\n- `SquareNode.tsx` uses `getNodeStatus()` from WebSocket context\n- Tool nodes show cyan border and pulse animation when `isExecuting` is true\n- **Minimum glow duration**: 500ms ensures fast-executing tools are visible (via `isGlowing` state)\n- Dual-purpose tools (Python/JavaScript) fall back to node params when LLM returns empty args\n\n### Implemented Tools\n| Tool | Schema | Handler | Description |\n|------|--------|---------|-------------|\n| calculatorTool | `CalculatorParams` | `CalculatorToolNode.calculate` (`nodes/tool/calculator_tool/`) | Math operations |\n| currentTimeTool | `CurrentTimeParams` | `CurrentTimeToolNode.now` (`nodes/tool/current_time_tool/`) | Date/time with timezone |\n| duckduckgoSearch | `DuckDuckGoSearchParams` | `DuckDuckGoSearchNode.search` (`nodes/search/duckduckgo_search/`) | DuckDuckGo web search (free) |\n| taskManager | `TaskManagerParams` | `_execute_task_manager()` | Intrinsic durable team assignment; returns queued through detached Temporal runner, preserves cross-run history, review, retry/reassignment, cancellation, acceptance, timestamps, elapsed time, and token usage |\n| writeTodos | `WriteTodosParams` | `execute_write_todos()` / `handle_write_todos()` | Structured task list planning with checklist rendering |\n| braveSearch | `BraveSearchParams` | `BraveSearchNode.search` (`nodes/search/brave_search/`) | Brave Search API web results |\n| serperSearch | `SerperSearchParams` | `SerperSearchNode.search` (`nodes/search/serper_search/`) | Google SERP via Serper API |\n| perplexitySearch | `PerplexitySearchParams` | `PerplexitySearchNode.search` (`nodes/search/perplexity_search/`) | AI-powered search with citations |\n| Android service nodes | Per-service schema | `execute_android_service_tool()` (`nodes/android/_base.py`) | Direct Android service tools (see below) |\n\n### Direct Android Service Tools\nAndroid service nodes (batteryMonitor, wifiAutomation, etc.) connect directly to any agent's `input-tools` handle — this is the only Android tool path (the former `androidTool` aggregator was retired; legacy graphs are migrated on load by `workflow_migrations.normalize_legacy_android_toolkit`). The `execute_tool()` function detects these via `ANDROID_SERVICE_NODE_TYPES` and routes to `execute_android_service_tool()` (`server/nodes/android/_base.py`).\n\n**Service ID Mapping** (camelCase node type -> snake_case service ID):\n```python\nservice_id_map = {\n 'batteryMonitor': 'battery',\n 'networkMonitor': 'network',\n 'systemInfo': 'system_info',\n 'location': 'location',\n 'appLauncher': 'app_launcher',\n 'appList': 'app_list',\n 'wifiAutomation': 'wifi_automation',\n 'bluetoothAutomation': 'bluetooth_automation',\n 'audioAutomation': 'audio_automation',\n 'deviceStateAutomation': 'device_state',\n 'screenControlAutomation': 'screen_control',\n 'airplaneModeControl': 'airplane_mode',\n 'motionDetection': 'motion_detection',\n 'environmentalSensors': 'environmental_sensors',\n 'cameraControl': 'camera_control',\n 'mediaControl': 'media_control',\n}\n```\n\n### Android Toolkit Pattern (retired)\nThe former `androidTool` gateway node (single `android_device` tool aggregating multiple Android service nodes, n8n Sub-Node / LangChain Toolkit pattern) no longer exists. Android service nodes connect straight to `input-tools`, and sub-node exclusion keys solely on AI-agent config handles (`input-context` / `input-tools` / `input-skill` / `input-teammates`) — the `TOOLKIT_NODE_TYPES` constant was deleted along with all its usage sites. Legacy `service -> androidTool -> agent` graphs are rewritten on load by `services/workflow_migrations.normalize_legacy_android_toolkit`.\n\n### Tool Schemas (per-service customization)\nCustom LLM-visible schemas for Android service tools persist in the `tool_schemas` table and are read by the AI service at execution time.\n\n**The write path has no reachable entry point — this is a known gap, not a design.** `ToolSchemaEditor.tsx` shipped with the retired Android Toolkit node and was removed with it; the `useToolSchema` client hook was its only consumer and was deleted in turn once it had zero importers. The WebSocket handlers and database CRUD remain, but nothing reachable calls `save_tool_schema` any more: no REST route writes the table and no server-internal code calls `database.save_tool_schema` outside the WS handler itself. So rows can only survive from before the editor was removed, or be written by hand.\n\nThe **read** path is live and load-bearing — do not delete it as \"unused\". [`services/ai.py`](./server/services/ai.py) fetches the stored row during tool construction and overrides `tool_name` / `tool_description` / `connected_services` from it, and `_build_schema_from_config` turns `schema_config[\"fields\"]` into the actual LLM-visible tool schema. Restoring an editor means giving `save_tool_schema` a caller again; it does not require touching the read side.\n\n#### Architecture\n```\n(no client writer — see above)\n ↓\n Database (tool_schemas table)\n ↓\n AI Service reads schemas at execution\n```\n\n#### Key Files\n| File | Description |\n|------|-------------|\n| `server/models/database.py` | `ToolSchema` SQLModel table definition |\n| `server/core/database.py` | Database CRUD methods for tool schemas |\n| `server/routers/websocket.py` | WebSocket handlers for schema operations |\n\n#### Database Model\n```python\nclass ToolSchema(SQLModel, table=True):\n __tablename__ = \"tool_schemas\"\n node_id: str # Service node ID (unique key)\n tool_name: str # Display name (e.g., \"Battery Monitor\")\n tool_description: str # Description shown to LLM\n schema_config: Dict # Schema fields and types (JSON)\n connected_services: Optional[Dict] # Legacy field from the retired toolkit aggregation\n```\n\n#### WebSocket Messages\n| Message Type | Description |\n|--------------|-------------|\n| `get_tool_schema` | Get schema for a node by ID |\n| `save_tool_schema` | Save/update schema for a node |\n| `delete_tool_schema` | Delete schema for a node |\n| `get_all_tool_schemas` | Get all stored schemas |\n\n#### Default Schema Generation\nWhen no custom schema exists, service-specific defaults are generated:\n```typescript\n{\n description: `Control ${serviceName} on Android device`,\n fields: {\n action: { type: 'string', description: `Action to perform on ${serviceName}`, required: true },\n parameters: { type: 'object', description: `Parameters for the ${serviceName} action`, required: false }\n }\n}\n```\n\n### Web Search Implementation\n\n#### DuckDuckGo (duckduckgoSearch - free, no API key)\nUses `ddgs` library for web results:\n```python\nfrom ddgs import DDGS\ndef do_search():\n ddgs = DDGS()\n return list(ddgs.text(query, max_results=max_results))\nsearch_results = await asyncio.get_event_loop().run_in_executor(None, do_search)\n```\n\n#### Search API Nodes (braveSearch, serperSearch, perplexitySearch)\nDedicated plugins under `server/nodes/search/` (`brave_search` / `serper_search` / `perplexity_search`) using `httpx.AsyncClient`:\n- **Brave Search**: `GET https://api.search.brave.com/res/v1/web/search` with `X-Subscription-Token` header. Returns `{query, results: [{title, snippet, url}], result_count, provider}`.\n- **Serper**: `POST https://google.serper.dev/search` with `X-API-KEY` header. Supports web/news/images/places search types. Returns `{query, results, result_count, search_type, provider}` with optional `knowledge_graph`.\n- **Perplexity Sonar**: `POST https://api.perplexity.ai/chat/completions` with Bearer token. Returns `{query, answer (markdown), citations: [url], results: [{url}], model, provider}` with optional `images` and `related_questions`.\n\nAll handlers fetch API keys via `auth_service.get_api_key()`; usage is tracked declaratively through the `cost={...}` argument on each node's `@Operation(\"search\", ...)`.\n\n## Config Node Architecture\n\n### Overview\nConfig nodes (context, tools, models) connect to parent nodes via special \"config handles\" (e.g., `input-context`, `input-tools`). These are auxiliary connections for configuration, not main data flow. The UI intelligently handles visibility of connected inputs based on this architecture.\n\n### Config Handle Convention\nConfig handles follow the pattern `input-<type>` where type is NOT 'main':\n- `input-context` - Context node (RFC-0002; observation surface onto the journal)\n- `input-tools` - Tool nodes (including `simpleMemory`, which is a ToolNode)\n- `input-model` - Model configuration nodes\n- `input-skill` - Skill nodes\n- `input-task` - Task completion trigger nodes\n- `input-teammates` - Team member agent nodes\n- `input-main` - Main data flow (NOT a config handle)\n- `input-memory` - **retired.** Kept only so legacy graph snapshots recorded with it replay; no agent declares it. `normalize_workflow_graph` rewrites legacy `simpleMemory -> input-memory` edges into a Context node plus an ordinary tool edge.\n\n**Note**: Trigger nodes (e.g., `taskTrigger`) connecting via config handles are excluded from downstream inclusion in `_get_downstream_nodes()` to prevent them from blocking as event waiters.\n\n### Config Node Detection\nNodes are identified as config nodes by their `group` array in the node definition:\n```typescript\n// Config node example (simpleMemory)\ngroup: ['skill', 'memory'] // 'memory' or 'tool' indicates config node\n```\n\n### Input Inheritance\nConfig nodes automatically inherit their parent node's main inputs in the parameter panel:\n```\nWhatsApp Trigger → AI Agent ← Simple Memory\n ↓ ↑\n main input config handle\n\nWhen viewing Simple Memory's parameters:\n- Shows: \"WhatsApp Trigger (via AI Agent)\"\n- Can drag WhatsApp outputs into Memory's parameters\n```\n\n### Filtering Logic\nLocated in `InputSection.tsx`:\n1. **Parent nodes** (AI Agent): Skip showing config node connections as inputs\n2. **Config nodes** (Memory): Inherit parent's main input connections with \"(via Parent)\" label\n\n### Key Functions\n```typescript\n// Check if handle is for config nodes (not main data flow)\nconst isConfigHandle = (handle: string | null | undefined): boolean => {\n if (!handle) return false;\n if (handle.startsWith('input-') && handle !== 'input-main' && handle !== 'input-chat' && handle !== 'input-task' && handle !== 'input-teammates') {\n return true;\n }\n return false;\n};\n\n// Check if node is a config/auxiliary node — reads the backend-derived\n// uiHint, not a frontend group-string heuristic.\nconst isConfigNode = (nodeType: string | undefined): boolean => {\n if (!nodeType) return false;\n const definition = resolveNodeDescription(nodeType);\n return definition?.uiHints?.isConfigNode === true;\n};\n```\n\nThe `isConfigNode` flag is **auto-derived on the backend** by `_derive_auto_ui_hints` in [`server/services/plugin/base.py`](./server/services/plugin/base.py): plugins whose `group` tuple contains `memory` or `tool` (the centralized `_CONFIG_NODE_GROUPS = frozenset({\"memory\", \"tool\"})`) automatically export `uiHints.isConfigNode: True`. Explicit `cls.ui_hints` always wins (merge order: auto-derived first, then `dict.update` with the plugin's declaration). Pytest invariant `test_ui_hints_only_carry_known_flags` locks the flag name in `server/tests/test_node_spec.py`.\n\n### Adding New Config Node Types\n1. Put the plugin in `('memory',)` or `('tool',)` (or any tuple containing one of those). The backend auto-derivation does the rest — do NOT declare `isConfigNode` in `ui_hints` unless you want to override.\n2. Use `input-<type>` naming for the target handle on the parent node.\n3. Input inheritance and filtering work automatically — the frontend reads `definition.uiHints.isConfigNode`, never the group strings.\n\n### Sub-Node Execution Exclusion\n\nSub-nodes (tools, memory, skills, teammates) connect TO an agent, not from it, so in parallel execution mode Kahn's algorithm would see them with in-degree 0 and incorrectly schedule them in layer 0. The executor excludes them: any node whose edge targets an AI-agent config handle (`input-context`, `input-tools`, `input-skill`, `input-teammates`) is detected as a sub-node in `ExecutionContext.create()` / `_compute_execution_layers()` and skipped from execution layers — it executes only when the agent invokes it (e.g. as an AI tool).\n\nToolkit aggregator nodes (the former `androidTool` and its `TOOLKIT_NODE_TYPES` constant) were retired; Android service nodes now connect directly to the agent's `input-tools` handle. Legacy `service -> androidTool -> agent` graphs are migrated on load by `services/workflow_migrations.normalize_legacy_android_toolkit` (pure, idempotent: services re-wire directly to each agent, orphaned toolkits are removed with a warning).\n\n## Android Services Development Guide\n\n### Local emulator workspace (separate plugin)\n\n`server/nodes/mobile/` owns **Mobile Agent** (`mobile_use_agent`) and the **Android** tool (`android_tool`). Both declare `ui_hints.workspace.kind=\"mobile\"`; Home and Dev render `MobileWorkspace`. Android’s Tool output connects to an agent’s Tools input. Both phone nodes follow the saved global model by default; custom settings override it, and a connected Model node takes highest priority. Its AI-visible schema contains only `prompt`; saved configuration controls time/step limits. This plugin does not replace the relay services documented below.\n\nStartup must hold `driver_lock` while reading the initialization reply; regular commands use the same lock. `/status` must skip driver I/O during lifecycle transitions. A serial alone does not mean the phone is ready. Keep connection warnings separate from action errors and clear them after successful polling.\n\nDiagnostics live in `mobile/mobile.log` (1 MiB, three backups); recent events are exposed under **Help & diagnostics**. Never log prompts, credentials, screenshots or typed text. Relative mobile `DATA_DIR` currently resolves against backend CWD, so source-dev installations can live at `server/.opencompany/mobile`; that runtime directory is ignored by Git and must not be deleted as temporary test data. Full setup, lifecycle, storage caveats and iOS plan: [Mobile Workspace](docs/mobile-workspace.md).\n\n### Architecture\nAndroid services use a factory pattern with `createAndroidServiceNode()` for consistent node structure:\n- **SquareNode Component**: Visual representation with configuration status indicators\n- **Dynamic Actions**: Load available actions from backend via `loadOptionsMethod`\n- **ADB Integration**: All services communicate with Android devices via ADB commands\n- **Parameter System**: Flexible JSON parameters for service-specific configuration\n\n### Adding New Android Services\n\n**Wave 11+**: Android service nodes are authored as backend plugins\nunder `server/nodes/android/<service>.py`. Each plugin subclasses the\nshared `AndroidServiceBase` (see `server/nodes/android/_base.py`), which\nhandles ADB dispatch via `SERVICE_ID_MAP`. See the\n[Plugin development guide](./docs-internal/plugin_system.md).\n\nAdding a new Android service:\n\n1. **Create the plugin** at `server/nodes/android/<service_name>.py`\n subclassing `AndroidServiceBase` — the base handles `service_id`\n routing, argument translation, and broadcast status updates.\n2. **Register the service id** in `SERVICE_ID_MAP` on\n `server/nodes/android/_base.py` (camelCase node type → snake_case\n service id).\n3. **Implement the execution path** in the plugin's `execute` method;\n shared ADB infrastructure lives in `AndroidService`.\n\n### Key Files\n- **Shared base**: `server/nodes/android/_base.py` — `AndroidServiceBase`, `SERVICE_ID_MAP`, `execute_android_service_tool`\n- **Backend Router**: `server/nodes/android/_router.py` - plugin-owned API endpoints, mounted by the `register_router` loop in `main.py`\n- **Workflow Handler**: `server/services/workflow.py` - Execution logic for all nodes\n- **Execution Service**: `src/services/executionService.ts` - Routes Android nodes to Python backend\n\n### Requirements\n- **Device Connection**: Configure Android connection via Credentials Modal (Android panel)\n- **Permissions**: Android app must have necessary permissions for services\n\n### Android Device Connection\nAndroid device connection is configured via the **Credentials Modal** (Android panel), not via workflow nodes.\n\n**Connection Types:**\n1. **Remote Relay** (recommended): Connect to Android device via relay server (QR code pairing)\n2. **Local ADB**: Connect via USB with ADB port forwarding\n\n**WebSocket Handlers** (`server/routers/websocket.py`):\n- `android_relay_connect` - Connect to relay server, get QR code for pairing\n- `android_relay_disconnect` - Disconnect from relay server\n- `android_relay_reconnect` - Reconnect to relay server\n\n### Android Relay Client\nLocated in `server/nodes/android/_relay/`:\n\n**Key Components:**\n- `client.py` - RelayWebSocketClient manages persistent connection\n- `broadcaster.py` - Status broadcast functions (connected, paired, disconnected)\n- `manager.py` - Global client instance management\n- `protocol.py` - JSON-RPC 2.0 message handling\n\n**Message Filtering:**\n```python\nasync def receive_message(self, timeout: float = 10.0):\n \"\"\"Receive response message, skipping non-response types\"\"\"\n skip_types = {'presence', 'pong', 'ping', 'connected'}\n\n while True:\n data = await asyncio.wait_for(self._message_queue.get(), timeout)\n msg_type = data.get('type', '')\n\n if msg_type in skip_types:\n continue # Skip and wait for next message\n\n return data # Return actual response\n```\n\n**Performance Benefits:**\n- Initial connection: ~0.18s (WebSocket handshake + registration)\n- Reused connection: ~0.0003s (600x faster)\n- Background tasks maintain connection health\n- Message queue decouples receiving from service execution\n\n### Android Relay Connection vs Device Pairing\n\nThe Android relay system uses a **two-state model** for connection status:\n\n| State | Description | Frontend Indicator |\n|-------|-------------|-------------------|\n| `connected` | WebSocket connection to relay server is active | N/A (not shown directly) |\n| `paired` | Android device has scanned QR and is paired via relay | Green/Red status dot |\n\n**Key Concepts:**\n- **Relay Connection**: The WebSocket connection to `wss://relay.opencompany.sh/ws` - can be active without a device\n- **Device Pairing**: An Android device scans the QR code and pairs - required for service execution\n- **Android service nodes require pairing**, not just relay connection, to execute\n\n**Status Broadcasting Architecture:**\n```\nserver/nodes/android/_relay/\n├── client.py # RelayWebSocketClient - manages WebSocket connection\n├── broadcaster.py # Status broadcast functions\n├── manager.py # Global client instance management\n└── protocol.py # JSON-RPC 2.0 message handling\n```\n\n**Broadcast Functions** (`server/nodes/android/_relay/broadcaster.py`):\n```python\n# Device connected and paired\nawait broadcast_connected(device_id, device_name)\n\n# Device disconnected but relay still connected (for re-pairing)\nawait broadcast_device_disconnected(\n relay_connected=True,\n qr_data=qr_data,\n)\n\n# Relay connection fully closed\nawait broadcast_relay_disconnected()\n\n# QR code available for pairing\nawait broadcast_qr_code(qr_data)\n```\n\n**Frontend Status Indicator** (`client/src/components/SquareNode.tsx`):\n```typescript\n// Android nodes use 'paired' status, not 'connected'\nconst isAndroidConnected = isAndroidNode && androidStatus.paired;\n```\n\n**Status Flow:**\n1. User clicks \"Connect\" → Relay WebSocket connects → `connected=true, paired=false`\n2. QR code displayed → User scans with Android app → `connected=true, paired=true`\n3. Android app disconnects → `connected=true, paired=false` (can re-pair)\n4. Relay WebSocket closes → `connected=false, paired=false`\n\n**WebSocket Context Interface** (`client/src/contexts/WebSocketContext.tsx`):\n```typescript\nexport interface AndroidStatus {\n connected: boolean; // Relay WebSocket connected\n paired: boolean; // Android device paired\n device_id: string | null;\n device_name: string | null;\n connected_devices: string[];\n connection_type: string | null;\n qr_data: string | null;\n session_token: string | null;\n}\n```\n\n## WhatsApp Integration\n\n### Overview\nWhatsApp nodes use square design with integrated QR code viewing and proper error handling. The integration proxies all requests through the Python backend to the WhatsApp RPC service (port from `WHATSAPP_RPC_PORT`, or the `--port` CLI flag). Supports individual chats, groups, and newsletter channels (sending, querying, follow/unfollow, create, mute, mark viewed, react, live updates, media download, profile pics). All 14 WhatsApp events handled.\n\n### Architecture\n```\nFrontend (useWhatsApp / WebSocket) -> Python backend WS handlers (nodes/whatsapp/_handlers.py) -> WhatsApp RPC service (localhost:${WHATSAPP_RPC_PORT})\n```\n\n### Key Features\n- **Square Node Design**: 80x80px square nodes with status indicators\n- **QR Code Viewer**: Embedded QR code display via Python backend proxy\n- **Error Handling**: Robust error handling with proper HTTP status codes (503, 504, 410)\n- **No Mock Data**: All endpoints return proper errors instead of mock responses\n- **Connection Status**: Real-time status display with device ID, session, and service info\n\n### Backend Helpers (`server/nodes/whatsapp/_service.py`)\n\nWave 11 renamed `routers/whatsapp.py` (misnamed — never an APIRouter) to `services/whatsapp_service.py`; Wave 11.I then moved it into the plugin folder as `nodes/whatsapp/_service.py`. Provides RPC proxy helpers consumed by `nodes/whatsapp/*` plugins and the WhatsApp WebSocket handlers.\n\n#### `whatsapp_status` - Get Connection Status\n- Returns WhatsApp connection status from Flask service\n- Handles ConnectError, TimeoutException with 503/504 status codes\n- Safe JSON parsing with error handling\n\n#### `whatsapp_qr` - Get QR Code\n- Checks connection status first\n- Returns QR code data if not connected\n- Returns \"Already connected\" message if connected\n- Handles errors gracefully without crashing\n\n#### `whatsapp_start` - Start Connection\n- Proxies start request to Flask service\n- Safe JSON parsing and error handling\n- Returns proper HTTP errors on failure\n\n#### `whatsapp_send` - Send Message\n- Enhanced messaging endpoint\n- Comprehensive error handling with specific exception catches\n- Never crashes on service unavailability\n\n### Frontend (SquareNode.tsx via NodeSpec component_kind; QR panel under components/credentials/)\n- **Canvas node**: `client/src/components/SquareNode.tsx` renders the WhatsApp plugins from their backend NodeSpec (`component_kind = \"square\"`; `whatsappReceive` is `\"trigger\"`) and reads live connection state through `useWhatsAppStatus()` -- there is no WhatsApp-specific node component\n- **QR / connection panel**: `client/src/components/credentials/panels/QrPairingPanel.tsx` (mounted by `PanelRenderer.tsx`) -- Start / Restart / Refresh actions call `useWhatsApp()`'s `startConnection` / `restartConnection` / `getStatus`, which send `whatsapp_start` / `whatsapp_restart` / `whatsapp_status`; the QR image comes from `whatsapp_qr`\n- **Requests**: every call is a WebSocket `sendRequest` (see `WebSocketContext.tsx`); no `/api/whatsapp/*` REST routes exist\n\n### Critical Bug Fixes\n\n#### 1. Missing Dependency Injection Wiring\n**Problem**: `main.py` was missing `\"routers.whatsapp\"` in `container.wire()` modules list\n**Impact**: Uvicorn reloader child process crashed with exit code 1, triggering SIGTERM\n**Fix**: Added `\"routers.whatsapp\"` to wiring list in `server/main.py`\n\n(Historical snippet — the router set has since changed: `routers.whatsapp` /\n`routers.maps` / `routers.android` moved into plugin folders (Wave 11.I) and\n`routers.nodejs_compat` was deleted (July 2026). The live wire list is in\n`server/main.py`. The lesson stands: every wired module must be listed or the\nreloader child crashes.)\n\n#### 2. Unhandled JSON Parse Errors\n**Problem**: `.json()` calls without error handling raised `JSONDecodeError` when Flask returned HTML errors\n**Impact**: Server crashes when WhatsApp service unavailable\n**Fix**: Wrapped all `.json()` calls in try-except blocks with proper error responses\n\n#### 3. Unhandled HTTP Status Errors\n**Problem**: `response.raise_for_status()` raised `httpx.HTTPStatusError` not caught by specific handlers\n**Impact**: Unhandled exceptions crashed the server\n**Fix**: Removed `.raise_for_status()`, manually check `response.status_code != 200`\n\n#### 4. Missing HTTPException Re-raise\n**Problem**: Generic `Exception` handlers didn't re-raise `HTTPException`\n**Impact**: Double exception wrapping and unclear errors\n**Fix**: Added `except HTTPException: raise` before generic handler\n\n### Error Handling Pattern\nAll WhatsApp endpoints follow this pattern:\n```python\ntry:\n response = await client.get(url, timeout=10.0)\n\n # Check status manually\n if response.status_code != 200:\n raise HTTPException(status_code=503, detail=\"...\")\n\n # Safe JSON parsing\n try:\n data = response.json()\n return data\n except Exception as json_err:\n logger.error(f\"Failed to parse JSON: {json_err}\")\n raise HTTPException(status_code=503, detail=\"Invalid response\")\n\nexcept httpx.ConnectError as e:\n raise HTTPException(status_code=503, detail=\"Service not running\")\nexcept httpx.TimeoutException as e:\n raise HTTPException(status_code=504, detail=\"Service timeout\")\nexcept HTTPException:\n raise # Re-raise HTTPException\nexcept Exception as e:\n logger.error(f\"Unexpected error: {e}\")\n raise HTTPException(status_code=503, detail=\"Service unavailable\")\n```\n\n### Result\n- Python backend never crashes when WhatsApp service is down\n- Proper HTTP error codes (503, 504, 410) returned\n- No SIGTERM crashes\n- Frontend receives proper error messages\n- QR code viewer works seamlessly\n- All mock data removed from production code\n\n### WhatsApp Group/Sender Name Persistence\nThe WhatsApp Receive node stores human-readable names alongside JIDs/phone numbers:\n\n#### Problem\nWhen reopening the parameter panel, group/sender selectors showed the raw JID (e.g., `[email protected]`) instead of the group name because the name was only fetched when the dropdown was opened.\n\n#### Solution\nStore the name as a separate parameter alongside the ID:\n- `group_id` + `group_name` - Group JID and display name\n- `phone_number` + `sender_name` - Phone number and contact name\n\n#### Implementation\n```typescript\n// In ParameterRenderer.tsx - GroupIdSelector\n<GroupIdSelector\n value={currentValue || ''}\n onChange={onChange}\n onNameChange={(name) => onParameterChange?.('group_name', name)}\n storedName={allParameters?.group_name || ''}\n ...\n/>\n\n// GroupIdSelector stores name when selection changes\nconst handleChange = (value: string, option: any) => {\n onChange(value);\n if (option?.label && onNameChange) {\n onNameChange(option.label);\n }\n};\n\n// Display uses storedName when available\nconst displayLabel = storedName || (value && !loading ? value : '');\n```\n\n#### Key Files\n- `client/src/components/ParameterRenderer.tsx` - GroupIdSelector and SenderNumberSelector with `onNameChange` and `storedName` props\n- `client/src/components/parameterPanel/MiddleSection.tsx` - Passes `onParameterChange` to ParameterRenderer\n\n## Event-Driven Trigger Node System\n\n### Overview\nTrigger nodes wait for external events (WhatsApp messages, webhooks, etc.) using Python's asyncio.Future. The backend handles all event waiting logic with the frontend displaying waiting state and providing cancel functionality.\n\n### Architecture\n```\nUser clicks \"Run\" on Trigger Node\n ↓\nFrontend sends execute_node via WebSocket\n ↓\nPython backend detects trigger node type (event_waiter.is_trigger_node)\n ↓\nBackend registers asyncio.Future waiter with filter\n ↓\nBackend broadcasts \"waiting\" status to frontend\n ↓\nExternal service sends event (e.g., whatsapp_message_received)\n ↓\nevent_waiter.dispatch() resolves matching waiters\n ↓\nBackend returns execution result with event data as output\n ↓\nFrontend displays result in output panel\n```\n\n### Backend Implementation\n\n#### Event Waiter Service (`server/services/event_waiter.py`)\nGeneric event waiting using standard asyncio primitives:\n\n```python\n@dataclass\nclass TriggerConfig:\n node_type: str\n event_type: str # e.g., 'whatsapp_message_received'\n display_name: str\n\nTRIGGER_REGISTRY: Dict[str, TriggerConfig] = {\n # Framework-level triggers — not owned by any plugin domain.\n \"start\": TriggerConfig(node_type=\"start\", event_type=\"deploy_triggered\", display_name=\"Deploy Start\"),\n \"webhookTrigger\": TriggerConfig(node_type=\"webhookTrigger\", event_type=\"webhook_received\", display_name=\"Webhook Request\"),\n \"chatTrigger\": TriggerConfig(node_type=\"chatTrigger\", event_type=\"chat_message_received\", display_name=\"Chat Message\"),\n \"taskTrigger\": TriggerConfig(node_type=\"taskTrigger\", event_type=\"task_completed\", display_name=\"Task Completed\"),\n # plugin-owned entries are backfilled by _auto_populate_from_plugins()\n}\n\n@dataclass\nclass Waiter:\n id: str = field(default_factory=lambda: str(uuid.uuid4()))\n node_id: str = \"\"\n node_type: str = \"\"\n event_type: str = \"\"\n filter_fn: Callable[[Dict], bool] = field(default_factory=lambda: lambda x: True)\n future: Optional[asyncio.Future] = None\n cancelled: bool = False\n created_at: float = field(default_factory=time.time)\n\n# Key functions:\nasync def register(node_type: str, node_id: str, params: Dict) -> Waiter\ndef dispatch(event_type: str, data: Dict) -> int # Returns count resolved\ndef cancel(waiter_id: str) -> bool\ndef cancel_for_node(node_id: str) -> int\ndef get_active_waiters() -> List[Dict]\n```\n\n#### Trigger Node Execution (`server/services/handlers/triggers.py`)\n```python\nasync def handle_trigger_node(node_id: str, node_type: str, parameters: Dict, context: Dict) -> Dict:\n config = event_waiter.get_trigger_config(node_type)\n waiter = await event_waiter.register(node_type, node_id, parameters)\n\n # Broadcast waiting status\n await broadcaster.update_node_status(node_id, \"waiting\", {\n \"message\": f\"Waiting for {config.display_name}...\",\n \"waiter_id\": waiter.id\n })\n\n # Wait indefinitely (user cancels via cancel_event_wait)\n event_data = await waiter.future\n return {\"success\": True, \"result\": event_data, ...}\n```\n\n#### Filter Builders\nEach trigger type has a filter builder that creates a function to match events:\n\n```python\ndef build_whatsapp_filter(params: Dict) -> Callable[[Dict], bool]:\n \"\"\"Build filter for WhatsApp messages based on node parameters.\"\"\"\n msg_type = params.get('messageTypeFilter', 'all')\n sender_filter = params.get('filter', 'all') # all, any_contact, contact, group, keywords\n forwarded_filter = params.get('forwardedFilter', 'all') # all, only_forwarded, ignore_forwarded\n # ... builds closure that checks message fields\n```\n\n**Sender Filter Options:**\n- `all` - Accept all messages (groups and contacts)\n- `any_contact` - Accept only non-group messages (individual chats)\n- `contact` - Accept from specific phone number\n- `group` - Accept from specific group (optionally filter by sender)\n- `keywords` - Accept messages containing specific keywords\n\n### WebSocket Handlers\n\n#### Cancel Event Wait (`server/routers/websocket.py`)\n```python\n@ws_handler()\nasync def handle_cancel_event_wait(data: Dict[str, Any], websocket: WebSocket):\n \"\"\"Cancel by waiter_id or node_id.\"\"\"\n if waiter_id := data.get(\"waiter_id\"):\n success = event_waiter.cancel(waiter_id)\n elif node_id := data.get(\"node_id\"):\n count = event_waiter.cancel_for_node(node_id)\n return {\"success\": success, ...}\n\n@ws_handler()\nasync def handle_get_active_waiters(data: Dict[str, Any], websocket: WebSocket):\n \"\"\"Get list of active waiters for debugging/UI.\"\"\"\n return {\"waiters\": event_waiter.get_active_waiters()}\n```\n\n### WhatsApp Receive Node\n\n#### Node Definition (plugin: `server/nodes/whatsapp/whatsapp_receive.py`; pre-Wave-11 frontend shape shown below for historical reference)\n```typescript\nwhatsappReceive: {\n displayName: 'WhatsApp Receive',\n name: 'whatsappReceive',\n icon: WHATSAPP_RECEIVE_ICON, // Bell with notification dot\n group: ['whatsapp', 'trigger'],\n outputs: [{\n name: 'main',\n displayName: 'Message',\n type: 'main',\n description: 'message_id, sender, chat_id, message_type, text, timestamp, is_group, is_from_me, push_name, group_info'\n }],\n properties: [\n // Message Type Filter: all, text, image, video, audio, document, location, contact\n // Sender Filter: all, contact (specific phone), group (specific group), keywords\n // Ignore Own Messages: boolean (default true)\n // Include Media Data: boolean (default false)\n ]\n}\n```\n\n#### Output Schema (plugin-owned, `server/nodes/whatsapp/whatsapp_receive.py`)\nRuntime output shapes are fetched lazily by InputSection per the Wave 3 source-of-truth decision. WhatsApp's schemas live in the plugin folder (the node's `Output` Pydantic classes — `WhatsAppGroupInfo` / `WhatsAppReceiveOutput` / `WhatsAppSendOutput` / `WhatsAppDbOutput`) and self-register from `nodes/whatsapp/__init__.py` via `register_output_schema(...)` — same pattern as telegram; `services/node_output_schemas.py` carries no whatsapp code.\nServed via `GET /api/schemas/nodes/whatsappReceive.json` + `get_node_output_schema` WS handler. See [docs-internal/plugin_system.md](./docs-internal/plugin_system.md) (the original RFC is archived at [ARCHIVE/schema_source_of_truth_rfc.md](./docs-internal/ARCHIVE/schema_source_of_truth_rfc.md)).\n\n### Task Trigger Node\n\nThe Task Trigger node fires when a delegated child agent completes its task (success or error). This enables parent agents to react to child completion via workflow nodes.\n\n#### Node Definition (plugin: `server/nodes/trigger/task_trigger/__init__.py`; pre-Wave-11 frontend shape shown below for historical reference)\n```typescript\ntaskTrigger: {\n displayName: 'Task Completed',\n name: 'taskTrigger',\n icon: '📨',\n group: ['trigger', 'workflow'],\n outputs: [{\n name: 'main',\n displayName: 'Output',\n type: 'main',\n description: 'task_id, status, agent_name, result/error, parent_node_id'\n }],\n properties: [\n // Task ID Filter: Optional specific task ID to watch\n // Agent Name Filter: Optional partial match on agent name\n // Status Filter: all, completed, error\n // Parent Node ID: Optional filter by parent agent node\n ]\n}\n```\n\n#### Output Schema (`client/src/components/parameterPanel/InputSection.tsx`)\n```typescript\ntaskTrigger: {\n task_id: 'string',\n status: 'string', // 'completed' or 'error'\n agent_name: 'string',\n agent_node_id: 'string',\n parent_node_id: 'string',\n result: 'string', // Present when status='completed'\n error: 'string', // Present when status='error'\n workflow_id: 'string',\n}\n```\n\n#### Event Dispatch (`server/services/handlers/tools.py`)\nThe `task_completed` event is dispatched when a delegated child agent finishes:\n```python\n# On success:\nawait broadcaster.send_custom_event('task_completed', {\n 'task_id': task_id,\n 'status': 'completed',\n 'agent_name': agent_label,\n 'agent_node_id': node_id,\n 'parent_node_id': config.get('parent_node_id', ''),\n 'result': result.get('result', {}).get('response', ...),\n 'workflow_id': workflow_id,\n})\n\n# On error:\nawait broadcaster.send_custom_event('task_completed', {\n 'task_id': task_id,\n 'status': 'error',\n 'agent_name': agent_label,\n 'agent_node_id': node_id,\n 'parent_node_id': config.get('parent_node_id', ''),\n 'error': str(e),\n 'workflow_id': workflow_id,\n})\n```\n\n### Adding New Trigger Types\n\n1. **Add to Registry** in `server/services/event_waiter.py`:\n ```python\n TRIGGER_REGISTRY['emailTrigger'] = TriggerConfig('emailTrigger', 'email_received', 'Email')\n ```\n\n2. **Add Filter Builder**:\n ```python\n def build_email_filter(params: Dict) -> Callable[[Dict], bool]:\n # Build filter based on node parameters\n FILTER_BUILDERS['emailTrigger'] = build_email_filter\n ```\n\n3. **Add the plugin** at `server/nodes/<category>/<trigger_name>.py`:\n - Define the `NodeSpec` (inputs / outputs / uiHints) as a subclass\n or dataclass per the plugin system\n - Implement the trigger-handler `execute` method\n\n4. **Add Output Schema** in `InputSection.tsx`:\n ```typescript\n email: { from: 'string', subject: 'string', body: 'string', ... }\n ```\n\n5. **Dispatch Events** from external service:\n ```python\n from services import event_waiter\n event_waiter.dispatch('email_received', email_data)\n ```\n\n### Polling Triggers (Gmail, Outlook, IMAP, Twitter)\n\nSome triggers require active API polling instead of waiting for externally dispatched events. These use `setup_polling_trigger` in `TriggerManager` instead of `setup_event_trigger`.\n\n**Architecture:**\n```\nsetup_polling_trigger() → broadcasts \"waiting\" status\n ↓\n poller task: runs poll_coroutine(queue, is_running_fn)\n ↓ ↓\n polls API at interval → enqueues new items to asyncio.Queue\n ↓\n processor task: reads queue → calls on_event → spawns execution run\n```\n\n**Key differences from event triggers:**\n- Event triggers: `event_waiter.register()` + `wait_for_event()` (push-based)\n- Polling triggers: Custom poll coroutine + `asyncio.Queue` (pull-based)\n\n**Routing** (`server/services/deployment/manager.py`):\n```python\nif node_type in POLLING_TRIGGER_TYPES: # googleGmailReceive, twitterReceive, emailReceive, msMailReceive\n poll_coroutine = self._create_poll_coroutine(node_type, node_id, params)\n await trigger_manager.setup_polling_trigger(...)\n```\n\n**Constants** (`server/constants.py`):\n- `POLLING_TRIGGER_TYPES`: `frozenset({'googleGmailReceive', 'twitterReceive', 'emailReceive', 'msMailReceive'})`\n- These are also in `WORKFLOW_TRIGGER_TYPES` for trigger node detection\n\n### Key Design Decisions\n\n- **No Timeout**: Trigger nodes wait indefinitely; users cancel via Cancel button\n- **Backend-First**: All event waiting logic in Python backend, minimal frontend changes\n- **Generic Architecture**: Same execution flow for all trigger types via registry\n- **Filter Functions**: Each trigger type builds its own filter from node parameters\n- **asyncio.Future**: Simpler than asyncio.Event for single-value resolution\n- **Polling triggers**: Use asyncio.Queue + dedicated poll coroutine for APIs without push support\n\n## Real-time Status WebSocket System\n\n### Overview\nThe frontend and Python backend communicate via WebSocket for real-time status updates. This replaces API polling with push-based updates for Android connection status, node execution status, and variable changes.\n\n### Architecture\n```\nReact Frontend (WebSocketContext.tsx) <--WebSocket--> Python Backend (status_broadcaster.py)\n | |\n v v\n SquareNode.tsx nodes/android/_relay/\n (uses androidStatus) (broadcasts Android status)\n```\n\n### Backend Implementation\n\n#### Status Broadcaster (`server/services/status_broadcaster.py`)\nCentral service for managing WebSocket connections and broadcasting status updates:\n\n```python\nclass StatusBroadcaster:\n def __init__(self):\n self._connections: Set[WebSocket] = set()\n self._status: Dict[str, Any] = {\n \"android\": {\n \"connected\": False,\n \"paired\": False,\n \"device_id\": None,\n \"device_name\": None,\n \"connected_devices\": [],\n \"connection_type\": None,\n \"qr_data\": None,\n \"session_token\": None,\n },\n # No \"whatsapp\" seed: the plugin owns its slot outright\n # (nodes/whatsapp/_events.py writes the full dict) and the FE\n # guards on key presence — absent means disconnected.\n \"twitter\": {\"connected\": False, \"username\": None, \"user_id\": None, \"name\": None, \"profile_image_url\": None},\n \"google\": {\"connected\": False, \"email\": None, \"name\": None},\n \"telegram\": {\"connected\": False, \"bot_id\": None, \"bot_username\": None, \"bot_name\": None},\n \"api_keys\": {}, # provider -> validation status\n \"nodes\": {}, # node_id -> node status\n \"variables\": {}, # variable_name -> value\n \"workflow\": {\"executing\": False, \"current_node\": None},\n \"workflow_lock\": {\"locked\": False, \"workflow_id\": None, \"locked_at\": None, \"reason\": None},\n \"deployment\": {\"isRunning\": False, \"activeRuns\": 0, \"status\": \"idle\", \"workflow_id\": None},\n }\n\n async def connect(self, websocket: WebSocket): ...\n async def disconnect(self, websocket: WebSocket): ...\n async def update_android_status(self, connected, device_id, connected_devices, connection_type): ...\n async def update_node_status(self, node_id, status, data): ...\n async def update_variable(self, name, value): ...\n async def update_workflow_status(self, executing, current_node, progress): ...\n```\n\nKey methods:\n- `connect()` - Accepts WebSocket, adds to connection set, sends initial status\n- `update_android_status()` - Updates Android status and broadcasts to all clients\n- `update_node_status()` - Updates individual node status with data/output\n- `update_variable()` - Updates single variable value\n- `_broadcast()` - Sends message to all connected clients\n\n#### WebSocket Router (`server/routers/websocket.py`)\nFastAPI WebSocket endpoint:\n\n```python\n@router.websocket(\"/ws/status\")\nasync def websocket_status_endpoint(websocket: WebSocket):\n broadcaster = get_status_broadcaster()\n await broadcaster.connect(websocket)\n try:\n while True:\n data = await websocket.receive_json()\n if data.get(\"type\") == \"ping\":\n await websocket.send_json({\"type\": \"pong\"})\n elif data.get(\"type\") == \"get_status\":\n await websocket.send_json({\"type\": \"full_status\", \"data\": broadcaster.get_status()})\n except WebSocketDisconnect:\n await broadcaster.disconnect(websocket)\n```\n\n### Frontend Implementation\n\n#### WebSocket Context (`client/src/contexts/WebSocketContext.tsx`)\nReact context providing WebSocket connection and status state:\n\n```typescript\nexport interface AndroidStatus {\n connected: boolean;\n device_id: string | null;\n connected_devices: string[];\n connection_type: string | null;\n}\n\nexport const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {\n const [androidStatus, setAndroidStatus] = useState<AndroidStatus>(defaultAndroidStatus);\n const [nodeStatuses, setNodeStatuses] = useState<Record<string, NodeStatus>>({});\n const [variables, setVariables] = useState<Record<string, any>>({});\n // WebSocket connection with auto-reconnect\n};\n\n// Hooks for consuming status\nexport const useWebSocket = (): WebSocketContextValue => { ... }\nexport const useAndroidStatus = (): AndroidStatus => { ... }\nexport const useNodeStatus = (nodeId: string): NodeStatus => { ... }\n```\n\nFeatures:\n- Auto-connect on mount\n- Reconnect with exponential backoff through PartySocket (`WS_RECONNECT` in `client/src/lib/connectionConfig.ts`, no jitter); a remote close, even with code 1000, keeps retrying, and only logout or unmount (`disposeConnection`) stops it\n- App heartbeat (`client/src/lib/webSocketHeartbeat.ts`): a ping every 30 s while the page is visible; no pong within 10 s forces a reconnect\n- Message type handlers for all status update types\n\n#### Usage in Components (`client/src/components/SquareNode.tsx`)\n```typescript\nconst { androidStatus } = useWebSocket();\n// Android service nodes use 'paired' status (device must be paired to execute)\nconst isAndroidConnected = isAndroidNode && androidStatus.paired;\n```\n\n### Android Status Broadcasting\nThe Android relay client (`server/nodes/android/_relay/client.py`) broadcasts status changes via dedicated functions in `broadcaster.py`:\n\n```python\n# When device pairs successfully\nawait broadcast_connected(device_id, device_name)\n\n# When device unpairs (relay may still be connected)\nawait broadcast_device_disconnected(\n relay_connected=self.is_connected(),\n qr_data=self.qr_data,\n)\n\n# When relay WebSocket closes unexpectedly\nawait broadcast_relay_disconnected()\n```\n\n**Key distinction:**\n- `broadcast_device_disconnected()` - Device unpaired, relay still connected (can re-pair via QR)\n- `broadcast_relay_disconnected()` - Full disconnection, need to reconnect\n\n### Real Device Detection\nFixed issue where Android status remained green after device disconnect:\n\n**Problem**: Base name `android_system_services` remained in connected devices set after real device `android_system_services_1764708352672` left.\n\n**Solution**: Added methods to distinguish real devices (with timestamp suffix) from base names:\n\n```python\ndef _get_discovered_devices(self) -> list:\n \"\"\"Get list of actual discovered devices (with timestamp suffix).\"\"\"\n discovered = []\n for device_id in self._connected_android_devices:\n parts = device_id.rsplit('_', 1)\n if len(parts) == 2 and parts[1].isdigit():\n discovered.append(device_id)\n return discovered\n\ndef has_real_android_devices(self) -> bool:\n \"\"\"Check if there are any real (discovered) Android devices connected.\"\"\"\n return len(self._get_discovered_devices()) > 0\n```\n\nUpdated `client_left` and presence handlers use `has_real_android_devices()` instead of checking total device count.\n\n### WebSocket Message Types\n\n> Live count = `len(MESSAGE_HANDLERS) + len(get_ws_handlers())` (core dict in `server/routers/websocket.py` + plugin-registered handlers). The catalogue below is illustrative, not exhaustive or hand-maintained.\n\n#### Request/Response Messages (Client -> Server -> Client)\n| Category | Message Types |\n|----------|--------------|\n| **Status/Ping** | `ping`, `get_status`, `get_android_status`, `get_node_status`, `get_variable` |\n| **Node Parameters** | `get_node_parameters`, `get_all_node_parameters`, `save_node_parameters`, `delete_node_parameters` |\n| **Tool Schemas** | `get_tool_schema`, `save_tool_schema`, `delete_tool_schema`, `get_all_tool_schemas` |\n| **Node Execution** | `execute_node`, `execute_workflow`, `cancel_execution`, `get_node_output`, `clear_node_output` |\n| **Triggers/Events** | `cancel_event_wait`, `get_active_waiters` |\n| **Dead Letter Queue** | `get_dlq_entries`, `get_dlq_entry`, `get_dlq_stats`, `replay_dlq_entry`, `remove_dlq_entry`, `purge_dlq` |\n| **Deployment** | `deploy_workflow`, `cancel_deployment`, `get_deployment_status`, `get_workflow_lock`, `update_deployment_settings` |\n| **AI Operations** | `execute_ai_node`, `get_ai_models` |\n| **API Keys** | `validate_api_key`, `get_stored_api_key`, `save_api_key`, `delete_api_key` |\n| **CLI agent auth** | `claude_code_login`, `claude_code_logout`, `codex_cli_login`, `codex_cli_logout` |\n| **Twitter OAuth** | `twitter_oauth_login`, `twitter_oauth_status`, `twitter_logout` |\n| **Google OAuth** | `google_oauth_login`, `google_oauth_status`, `google_logout` |\n| **Discord / Microsoft OAuth** | `discord_oauth_login`, `discord_oauth_status`, `discord_logout`, `microsoft_oauth_login`, `microsoft_oauth_status`, `microsoft_logout` (all minted by `services.events.oauth_lifecycle.make_oauth_lifecycle_handlers`) |\n| **Android** | `get_android_devices`, `execute_android_action`, `android_relay_connect`, `android_relay_disconnect`, `android_relay_reconnect` |\n| **WhatsApp** | `whatsapp_status`, `whatsapp_connected_phone`, `whatsapp_qr`, `whatsapp_send`, `whatsapp_start`, `whatsapp_restart`, `whatsapp_groups`, `whatsapp_group_info`, `whatsapp_chat_history`, `whatsapp_newsletters`, `whatsapp_rate_limit_get`, `whatsapp_rate_limit_set`, `whatsapp_rate_limit_stats`, `whatsapp_rate_limit_unpause`, `whatsapp_mark_read`, `whatsapp_typing`, `whatsapp_presence`, `whatsapp_stop`, `whatsapp_diagnostics` |\n| **Telegram** | `telegram_connect`, `telegram_disconnect`, `telegram_status`, `telegram_send`, `telegram_reconnect`, `telegram_get_me`, `telegram_get_chat` |\n| **Workflow Storage** | `save_workflow`, `get_workflow`, `get_all_workflows`, `delete_workflow` |\n| **Chat Messages** | `send_chat_message`, `get_chat_messages`, `clear_chat_messages`, `save_chat_message`, `chat_subscribe`, `chat_unsubscribe`, `get_chat_run`, `edit_chat_message`, `regenerate_chat_reply`, `switch_chat_branch`, `set_chat_feedback`, `get_chat_context`, `get_chat_models`, plus the speech plugin's `dictation_status` / `transcribe_audio` (see [chat_protocol.md](./docs-internal/chat_protocol.md)) |\n| **Console/Terminal** | `get_console_logs`, `clear_console_logs`, `get_terminal_logs`, `clear_terminal_logs` |\n| **User Skills** | `get_user_skills`, `get_user_skill`, `create_user_skill`, `update_user_skill`, `delete_user_skill` |\n| **Built-in Skills** | `get_skill_content`, `save_skill_content`, `scan_skill_folder`, `list_skill_folders` |\n| **Memory/Skill Reset** | `clear_memory`, `reset_skill` |\n| **User Settings** | `get_user_settings`, `save_user_settings` |\n| **Provider Defaults** | `get_provider_defaults`, `save_provider_defaults` |\n| **Pricing** | `get_pricing_config`, `save_pricing_config` |\n| **Usage/Compaction** | `get_api_usage_summary`, `get_compaction_stats`, `configure_compaction`, `get_provider_usage_summary` |\n| **Agent Teams** | `create_team`, `get_team`, `get_team_status`, `dissolve_team`, `add_team_task`, `claim_team_task`, `complete_team_task`, `get_team_tasks`, `send_team_message`, `get_team_messages` |\n| **Model Registry** | `get_model_constraints`, `refresh_model_registry` |\n| **Employees (Normal mode)** | `list_employees`, `get_employee`, `get_employee_usage`, `generate_employee_setup`, `cancel_employee_setup`, `hire_employee`, `start_employee`, `enable_employee_talk`, `apply_employee_changes`, `rename_employee`, `set_employee_photo`, `workspace_steps_list` (see [normal_mode.md](./docs-internal/normal_mode.md)) |\n| **Approvals** | `list_approvals`, `decide_approval` (the `approvalGate` node's drafts) |\n\n#### Broadcast Messages (Server -> All Clients)\n| Message Type | Description |\n|--------------|-------------|\n| `android_status` | Android device connection update |\n| `node_status` | Node execution status change |\n| `node_output` | Node execution output data |\n| `agent_progress` | CloudEvents v1.0 envelope (type=`com.opencompany.agent.progress`) — per-step agent-loop iteration count, drives the live \"N / max\" badge on AI Agent canvas nodes |\n| `agent_capability` | CloudEvents v1.0 envelope (`com.opencompany.agent.(skill|tool).*`) — exact-agent capability lifecycle with deterministic Temporal IDs, `(source,id)` deduplication, sanitized data, and an optional exact target node |\n| `employee_lifecycle` | CloudEvents v1.0 envelope (type=`com.opencompany.employee.{hired,updated,removed}`, subject = workflow id) — Home's team list; `updated` is coalesced to one per second per employee, control changes go out at once |\n| `approval_lifecycle` | CloudEvents v1.0 envelope (type=`com.opencompany.approval.{requested,decided,expired,cancelled}`) — identity only, never the draft or the recipient; the card refetches via `list_approvals` |\n| `chat.updated` | CloudEvents v1.0 envelope (type=`com.opencompany.chat.updated`, data `{workflow_id, session_id, role}`) — sent directly (not `dispatch.emit`) by `services/chat_thread.py` after every chat insert and clear, and when a chat run ends; identity only, Home's thread and the editor's chat pane refetch via `get_chat_messages` |\n| `chat_run_event` | CloudEvents v1.0 envelope (type=`com.opencompany.chat.run.<suffix>`, id `<run id>:<seq>`, subject = run id) — AG-UI run events, sent by `services/chat/hub.py` only to sockets subscribed to the session through `chat_subscribe`, never on the broadcast; see [chat_protocol.md](./docs-internal/chat_protocol.md) |\n| `workflow_lifecycle` | CloudEvents v1.0 envelope for workflow stages (`deployment.*`, `lock.*`, `execution.*`, `imported`, `renamed`, `created`, `deleted`) — other tabs invalidate their workflow lists |\n| `workspace_step` | CloudEvents v1.0 envelope (type=`com.opencompany.workspace.step`, subject = workflow id, data `{workflow_id, surface, step_id}`) — sent directly by `services/workspace_steps.py` when a Browser, Canvas or phone step is recorded; identity only, Home's Workspace timeline refetches via `workspace_steps_list` |\n| `deployment_snapshot` | CloudEvents v1.0 envelope (type=`workflow.deployment.snapshot`) — pushed once per WS connect from `broadcaster._send_deployment_snapshot`; lets the FE reconcile stale `deploymentStatus.isRunning=true` after a backend restart wiped `DeploymentManager._deployments`. Empty list is meaningful (forces reset). |\n| `variable_update` | Single variable value change |\n| `workflow_status` | Workflow execution progress |\n| `api_key_status` | API key validation status |\n| `node_parameters_updated` | Node parameters changed by another client |\n\n#### Status Messages\n| Message Type | Direction | Description |\n|--------------|-----------|-------------|\n| `initial_status` | Server -> Client | Full status on connect |\n| `full_status` | Server -> Client | Full status response |\n| `pong` | Server -> Client | Keep-alive response |\n| `error` | Server -> Client | Error response with code and message |\n\n## WebSocket Hooks\n\n### useWhatsApp (`client/src/hooks/useWhatsApp.ts`)\nHook for WhatsApp operations via WebSocket:\n```typescript\nconst { getStatus, getQRCode, sendMessage, startConnection, isLoading, connectionStatus } = useWhatsApp();\n```\n\n### Node execution (`client/src/services/executionService.ts`)\n`ExecutionService.executeNodeViaWebSocket()` is the live path, called from\n[`ParameterPanel.tsx`](./client/src/ParameterPanel.tsx). It delegates to the\ncontext's `executeNode`, which sizes its request budget from the node's own\n`uiHints.executionTimeoutMs` rather than any local list of \"slow\" node types.\n(A `useExecution` hook once wrapped this; it was unreachable and was deleted.)\n\n### useApiKeys (`client/src/hooks/useApiKeys.ts`)\nHook for API key management via WebSocket:\n```typescript\nconst { validateApiKey, getStoredKey, saveApiKey, deleteApiKey } = useApiKeys();\n```\n\n### Android operations (no dedicated hook)\nAndroid work goes through the WebSocket context directly — `getAndroidDevices` / `executeAndroidAction` / `androidStatus` off `useWebSocket()`, or a raw `sendRequest('android_relay_connect', …)`. A `useAndroidOperations` hook once wrapped those context methods; every live surface bypassed it, so it was deleted.\n\n### useParameterPanel (`client/src/hooks/useParameterPanel.ts`)\nHook for parameter management via WebSocket:\n```typescript\nconst { parameters, saveParameters, loadParameters, isDirty } = useParameterPanel(nodeId);\n```\n\n### Conditional Parameter Display Implementation\nLocated in `client/src/utils/parameterVisibility.ts` (imported by `client/src/components/parameterPanel/MiddleSection.tsx`):\n\n```typescript\nconst shouldShowParameter = (param: INodeProperties, allParameters: Record<string, any>): boolean => {\n if (!param.displayOptions?.show) {\n return true;\n }\n\n const showConditions = param.displayOptions.show;\n\n for (const [paramName, allowedValues] of Object.entries(showConditions)) {\n const currentValue = allParameters[paramName];\n\n if (Array.isArray(allowedValues)) {\n if (!allowedValues.includes(currentValue)) {\n return false;\n }\n } else {\n if (currentValue !== allowedValues) {\n return false;\n }\n }\n }\n\n return true;\n};\n```\n\nThis function:\n- Checks if parameter has displayOptions.show configuration\n- Evaluates all show conditions against current parameter values\n- Returns false if any condition fails (parameter hidden)\n- Returns true if all conditions pass (parameter visible)\n- Applied before rendering: `.filter(param => shouldShowParameter(param, parameters))`\n\n## Planned Features\n\n### Workflow-Level Execution (n8n-style Parallel Workflows)\n\n**Current Limitations:**\n- Single workflow execution at a time (global `_deployment_running` flag)\n- Nodes fetch status on component mount, not when workflow is selected\n- Status broadcasts to all clients without workflow filtering\n- No isolation between workflow executions\n\n**Planned Architecture:**\n\n1. **Defer Node Status Checks Until Workflow Selected**\n - Status should only fetch when workflow containing those nodes is selected\n - Use cached status from WebSocket context instead of per-node fetching\n\n2. **Workflow-Isolated Execution Context**\n ```python\n # server/services/workflow.py\n class ExecutionContext:\n def __init__(self, workflow_id: str, session_id: str):\n self.workflow_id = workflow_id\n self.session_id = session_id\n self.outputs: Dict[str, Any] = {}\n self.iteration = 0\n self.running = False\n self.task: Optional[asyncio.Task] = None\n\n # Replace single deployment state with:\n self._execution_contexts: Dict[str, ExecutionContext] = {}\n ```\n\n3. **Parallel Workflow Deployment**\n - Each workflow gets unique `workflow_id` in execution requests\n - Backend tracks `_execution_contexts[workflow_id]` instead of single `_deployment_running`\n - Cancel by `workflow_id` instead of globally\n - Status broadcasts include `workflow_id` for client filtering\n\n4. **Frontend Changes**\n - `WebSocketContext`: Add `activeWorkflowId`, filter status by workflow\n - `useAppStore`: Add `runningWorkflows: Set<string>` to track parallel executions\n - `WorkflowSidebar`: Show running indicator next to deployed workflows\n - `Dashboard`: Pass `workflow_id` to all execution calls\n\n**Files to Modify:**\n- `client/src/components/SquareNode.tsx` - Remove mount config check\n- `client/src/contexts/WebSocketContext.tsx` - Add workflow filtering\n- `client/src/store/useAppStore.ts` - Track running workflows\n- `server/services/workflow.py` - ExecutionContext class, parallel support\n- `server/routers/websocket.py` - workflow_id in messages\n- `server/services/status_broadcaster.py` - workflow_id filtering\n\n## Notes\n- **No Legacy Support**: Pure modern methods only, backward compatibility removed\n- **Interface Alignment**: ParameterRenderer supports both interface types seamlessly\n- **Execution Ready**: Components can be executed with real-time result display\n- **Clean Codebase**: Significant file and code reduction while maintaining full functionality\n- **Modular Backend**: workflow.py reduced from 2068 lines to a facade (~840 lines today)\n - NodeExecutor: Registry-based dispatch with `functools.partial` for dependency injection\n - ParameterResolver: Compiled regex for `{{node.field}}` template resolution\n - DeploymentManager: Handles deploy/cancel lifecycle with TriggerManager for cron/events\n - No global state: `_active_cron_jobs` moved to TriggerManager instance variable\n- **Performance**: Fast HMR updates and clean TypeScript compilation\n- **AI Architecture**: 5-layer system with factory pattern and secure credential management\n- **Android Architecture**: Factory-based node creation with ADB integration for device automation\n- **WebSocket-First Architecture**: most frontend-backend RPC (parameters, execution, API keys, Android, WhatsApp, skill operations) goes through WebSocket. Live handler set lives in the `MESSAGE_HANDLERS` dict in `server/routers/websocket.py` plus plugin-registered handlers via `services.ws_handler_registry`.\n- **WebSocket Hooks**: Dedicated React hooks (useWhatsApp, useApiKeys, useParameterPanel) for clean component integration; node execution goes through `services/executionService.ts`\n- **WebSocket Support**: Persistent remote Android device connections via WebSocket proxy with background tasks\n - Connection stays alive across multiple API requests until switched to local ADB\n - Background message receiver and keepalive loop (25s interval)\n - Message queue for async message handling with filtering logic\n - Connection reuse reduces execution time from 0.18s to 0.0003s\n- **Real-time Status WebSocket**: Frontend-backend WebSocket at `/ws/status` for live updates\n - Android connection status broadcasts when devices connect/disconnect\n - Node execution status and output updates\n - Variable value changes\n - Workflow execution progress\n - Replaces API polling with push-based updates\n - Auto-reconnect with exponential backoff plus an app-level heartbeat (see \"WebSocket Reconnect via PartySocket\" below)\n - Real device detection distinguishes actual devices (with timestamp suffix) from base names\n - **Android two-state model**: `connected` (relay WebSocket) vs `paired` (device paired)\n - Android service nodes use `paired` status for indicator (green = paired, red = not paired)\n - Relay can be connected without a device (shows QR for pairing)\n - Device disconnect broadcasts `paired=false` while keeping `connected=true` for re-pairing\n- **Conditional Display**: Full implementation of displayOptions.show pattern for dynamic UI rendering\n- **Process Management**: the Python CLI supervisor (`cli/supervisor.py`) owns child lifecycle; on Windows a Job Object kills the whole tree on exit, on POSIX `setsid` + `killpg`; `company stop` frees the ports named in `.env.template`\n- **WhatsApp Integration**: Square node design with QR code viewer, proper error handling, no crashes\n - Critical fix: Added \"routers.whatsapp\" to dependency injection wiring\n - All endpoints use safe JSON parsing with comprehensive error handling\n - Backend proxies all requests to WhatsApp RPC service (`WHATSAPP_RPC_PORT`)\n - Returns proper HTTP status codes (503, 504, 410) instead of mock data\n - Python server never crashes when WhatsApp service is unavailable\n - WebSocket handlers for status, QR code, send message, and start connection\n - useWhatsApp hook provides clean React component integration\n - Uses external npm package `whatsapp-rpc` with pre-built Go binaries\n - Newsletter channels: send to channels (text/image/video/audio/document), query channel DB (list, info, messages, stats), follow/unfollow, create, mute, mark viewed, react, live updates. Channel JID format: `<numeric_id>@newsletter`. All 14 WhatsApp events handled (including `event.history_sync_complete`).\n - Media download: `include_media_data` param on chat_history and channel_messages triggers `media` RPC for base64 media retrieval\n - Channel message filters: date range (since/until), media type, text search, pagination offset\n - WebSocket RPC passthroughs: mark_read, typing, presence, stop, diagnostics\n- **Event-Driven Triggers**: Generic trigger node architecture with asyncio.Future\n - `server/services/event_waiter.py` - Waiter registration, dispatch, cancellation\n - TRIGGER_REGISTRY for extensible trigger types (WhatsApp, Webhook, Telegram, future: Email, MQTT)\n - Filter builders create closures from node parameters (whatsapp_filter, webhook_filter)\n - No timeout - wait indefinitely until event or user cancel\n - WebSocket handlers: `cancel_event_wait`, `get_active_waiters`\n - **Trigger State Machine** (n8n pattern):\n - `idle` → `waiting` (on deploy, cyan indicator)\n - `waiting` → `idle` (on event received, graph starts executing, green indicator)\n - `idle` → `waiting` (after graph completes, listening again)\n - Triggers NEVER show `executing` status - only downstream nodes do\n - **Sequential Queue Processing**: Events are queued and processed one at a time via `wait_for_completion=True`\n- **HTTP/Webhook Integration**: 3 utility nodes for HTTP communication\n - `httpRequest` - Make outgoing HTTP requests with httpx async client\n - `webhookTrigger` - Receive incoming HTTP requests at `/webhook/{path}`\n - `webhookResponse` - Send custom responses back to webhook callers\n - `server/routers/webhook.py` - Dynamic webhook router using broadcaster.send_custom_event()\n - Output panel shows clean summaries (method, path, body for webhooks; status code for HTTP)\n- **n8n-Pattern Cache System**: Automatic fallback hierarchy for different environments\n - Opt-in (`REDIS_ENABLED=true`; no shipped configuration sets it): Redis → SQLite → Memory\n - Default: SQLite → Memory\n - `server/core/cache.py` - CacheService with fallback logic\n - `server/models/cache.py` - CacheEntry SQLModel for SQLite persistence\n - `server/core/database.py` - Cache CRUD methods (get/set/delete/cleanup)\n - Supports TTL expiration and automatic cleanup of expired entries\n- **Conditional Redis (historical)**: the Docker Compose topology (Redis profiles, `scripts/docker.js` wrapper) is historical — see [docs-internal/deployment_legacy.md](./docs-internal/deployment_legacy.md)\n- **WebSocket Reconnect via PartySocket** (`partysocket/ws` from Cloudflare): native-WS-compatible class handles exponential backoff (`MIN_DELAY_MS · GROW_FACTOR^(n-1)`, capped; no jitter, since PartySocket randomises only its own default minimum, which ours replaces) and replays sends buffered while disconnected (`maxEnqueuedMessages: 200`). While it is down after sign-in, the sign-in gate (`components/auth/ProtectedRoute.tsx`) shows Connecting over the app, read from `useWebSocketActions().reconnecting`. A remote close keeps it retrying whatever the code, including 1000 (RFC 6455 §7.4.1 Normal Closure); only an explicit `close()` stops it, which `disposeConnection` does on logout and unmount. An app-level heartbeat (`client/src/lib/webSocketHeartbeat.ts`, `WS_HEARTBEAT`: 30 s ping, 10 s pong deadline, visible pages only) reconnects a socket that stopped answering, with close code 4000. Replaces the previous flat 3 s `setTimeout(connect, 3000)` loop. Reconnect envelope (`MIN_DELAY_MS: 250`, `MAX_DELAY_MS: 8000`, `GROW_FACTOR: 1.3`) lives in `client/src/lib/connectionConfig.ts`. The +12 s WS-drop-and-reconnect cycle observed under React Strict Mode is gone — verified across two consecutive cold launches with zero `Client disconnected` events through 130+ s of activity. See `docs-internal/performance.md` for measurements.\n- **Docker image runs uvicorn, not `company serve`**: `docker/entrypoint.sh` writes the three secrets into `/data/opencompany.env` once (the container env's value when set there, else a random one), then execs the desktop shell's uvicorn argv (`--timeout-graceful-shutdown 5`, port resolved through `core.env_defaults`). `company serve` would need root `node_modules` + the CLI venv, ignores `OPENCOMPANY_ENV_FILE`, and its supervisor would add a second tree-kill deadline (`backend_shutdown_grace_seconds`, `cli/_common.py`). `HOST` stays `127.0.0.1` (the backend dials itself at `ws://HOST:PORT/ws/internal`); the external bind is the `--host 0.0.0.0` argument. The image has no Node: `/usr/local/bin/node` links to bun, so the `#!/usr/bin/env node` bin scripts (vercel, cf) run. The Dockerfile now sets `BROWSER_RUNTIME=system`, `BROWSER_FAMILY=chromium` and `BROWSER_HEADLESS=true`; the browser extra supplies Chromium. This matches the default of rendering inside the workspace without a desktop window. The retired agent-browser variable `AGENT_BROWSER_EXECUTABLE_PATH` is no longer in the image. Installed-browser discovery, opt-in Chrome for Testing/browser-use installation and explicit headless deployment requirements are documented in [Browser](./docs-internal/browser.md). The compose project is named `opencompany-selfhost` so it never merges with another compose project called `opencompany`. See [docker.md](./docs-internal/docker.md).\n- **Configurable Authentication**: `VITE_AUTH_ENABLED` environment variable\n - Set to `false` to bypass login entirely (useful for local development)\n - Frontend creates anonymous user with owner privileges when disabled\n - AuthContext checks via TanStack Query `useQuery({queryKey: ['auth','status'], retry: false, networkMode: 'always', signal})` and never retries on its own: while the server can't be reached the sign-in gate shows Connecting, which checks again through `checkAuth` after 2, 3, 5 and then every 8 s (`CONNECT_RETRY` in `client/src/lib/connectionConfig.ts`), with a countdown, Try now and the attempt on screen, then holds \"Connected\" 1.5 s before sign-in or the app (see [Authentication](./docs-internal/authentication.md)). `checkAuth` says whether the server answered; a failed check keeps the last answer. `signal` (AbortController) plumbed through `queryFn` so unmount + Strict Mode cleanup cancel in-flight requests automatically. login / register / logout invalidate the cache via `queryClient.invalidateQueries(AUTH_STATUS_QUERY_KEY)`.\n - The backend reads the same variable through `Settings.vite_auth_enabled` (auth middleware, `routers/auth.py`, WebSocket session checks, the dev-secret guard); `Settings` itself ignores unknown variables (`extra=\"ignore\"`)\n- **CloudEvents v1.0 envelope on the wire (preserved end-to-end)**: backend `WorkflowEvent` ([server/services/events/envelope.py](./server/services/events/envelope.py)) and frontend `WorkflowEvent<T>` interface ([client/src/types/cloudEvents.ts](./client/src/types/cloudEvents.ts)) mirror each other. `matchesType(event, 'credential.api_key.*')` parity-tested vs `WorkflowEvent.matches_type` Pydantic method. Today wraps inside the legacy `{type, data}` WS frame (e.g. `credential_catalogue_updated` → `data: <envelope>`); future Wave 12 sources (`stripe.*`, `telegram.*`, `task.*`) drop into the same envelope so a single FE switch case routes them via glob dispatch instead of inventing per-source wire keys.\n- **whatsapp-rpc Package**: External dependency for WhatsApp integration\n - Published to npm as `whatsapp-rpc` (unscoped) and GitHub Packages as `@trohitg/whatsapp-rpc`\n - Published to PyPI as `whatsapp-rpc` (async Python client)\n - Cross-platform binaries built via GitHub Actions (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64)\n - Binary downloaded from GitHub releases during npm postinstall\n - Configurable port via `--port` CLI flag, `PORT` or `WHATSAPP_RPC_PORT` env vars (OpenCompany passes WHATSAPP_RPC_PORT; the npm package's own default is 9400)\n - QR codes generated as base64 PNG in memory (no file I/O, no `data/qr` directory)\n - Source: https://github.com/trohitg/whatsapp-rpc\n- **Node Data Architecture**: `node.data` only stores `label` (display name). All parameters are stored in the database via `save_node_parameters` WebSocket handler. This prevents parameter bloat in workflow JSON exports and keeps React Flow state lightweight. `useDragAndDrop.ts` saves default parameters to DB on drop, not to `node.data`.\n- **Workflow Export/Import with Parameters**: Exported workflow JSON includes a `nodeParameters` field containing all node configuration (provider, model, prompt, skillsConfig, etc.) fetched from the database at export time. On import, embedded `nodeParameters` are saved back to the database. `sanitizeNodes()` in `workflowExport.ts` still strips `node.data` to UI-only fields (`label`, `disabled`, `condition`). The `parameterSanitizer.ts` utility strips credential-bearing keys (SENSITIVE key sets + substring matching + runtime-key stripping) and is ACTIVE in the export path (`buildExportParameters` in `workflowExport.ts` calls `sanitizeParameters`). Canvas copy/paste uses its `withoutRuntimeKeys` instead: the pasted node gets the original's saved parameter row, read when the nodes are copied, minus the runtime keys (credentials kept, since the copy stays in this install), or the spec defaults when the row could not be read. Old exports without `nodeParameters` import cleanly (backward compatible). Key files: `client/src/utils/workflowExport.ts`, `client/src/utils/parameterSanitizer.ts`, `client/src/Dashboard.tsx` (export/import handlers), `server/services/example_loader.py`.\n - **The sanitizer is client-only, and the backend depends on it without enforcing it.** There is no server-side sanitizer and no server-side export endpoint; the raw material is freely available to any caller via `handle_get_all_node_parameters` (`routers/websocket.py`), which returns stored parameters verbatim. So *any* export path built outside the React app is unsanitized by construction. This is deliberate but load-bearing: `server/tests/test_export_sanitizer_sync.py` reads `parameterSanitizer.ts` off disk and asserts its `RUNTIME_KEYS` covers everything `clear_agent_session_state` wipes — a cross-language invariant that exists because these two lists *already drifted once*, when the sanitizer held camelCase `memoryContent` against the real `memory_content` and every export carried full conversation histories into the shipped example workflows and from there into a public repo. Two consequences worth knowing before touching either side: adding a field to `clear_agent_session_state` fails that test until `RUNTIME_KEYS` matches, and adding a server-side export path silently bypasses stripping entirely. Known accepted hole: `sanitizeParameters` recurses into objects but passes arrays through untouched (documented in its own docstring and locked by `parameterSanitizer.test.ts`), so `{tasks: [{api_key: 'sk-1'}]}` exports the key.\n- **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.\n- **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.\n- **Onboarding Service**: 3-step Welcome guide on Home (Welcome, Connect an AI model, Your first hire) 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 the Home header's Guide button and Settings → Help. No new WebSocket handlers needed. See [Onboarding Service](./docs-internal/onboarding.md) for details.\n- **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).\n- **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.\n- **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`).\n- **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.\n- **WebSocket disconnect must not cancel database teardown**: a client that disconnects within ~100 ms of connecting (Strict Mode double mount, a health probe) used to make the `/ws/status` endpoint cancel its in-flight init-burst handlers mid-statement, so SQLAlchemy's reset-on-return rollback took the `CancelledError` and logged `Exception during reset or similar` with a traceback per handler. Three guards, locked by `tests/test_ws_disconnect_cancellation.py`: `core/session_teardown.py` runs rollback + close under `asyncio.shield` for both `Database.get_session` and `CredentialsDatabase.get_session`; `_drain_handler_tasks` in `routers/websocket.py` waits one second for handlers before cancelling stragglers; `StatusBroadcaster.broadcast` skips and prunes sockets that are no longer `CONNECTED` on either side. Any new session helper must reuse `teardown_session`, and a new `core` module that `core/database.py` imports must also be file-loaded in `tests/conftest.py` (the stubbed `core` package has an empty `__path__`).\n- **Claude Code budget flag**: the Claude Code agent (`nodes/agent/claude_code_agent/`) does not pass `--max-budget-usd`. It, `--max-turns` and `--fallback-model` are print-mode (`-p`) flags, and the session pool runs `claude` interactively over stream-json, so `_provider.py` accepts the task spec's `max_budget_usd` and ignores it; `tests/services/cli_agent/test_providers.py` asserts the flag is absent.\n- **Persisted-prefix cache contract**: `PersistQueryClientProvider` hydrates entries with the QueryClient's *default* options, so any prefix in `PERSISTED_KEY_PREFIXES` (`client/src/lib/queryPersist.ts`) MUST also have a matching `queryClient.setQueryDefaults(['<prefix>'], { staleTime: FOREVER, gcTime: FOREVER })` declaration in `client/src/lib/queryClient.ts`. Per-call options don't apply on hydration. Canonical persisted set: `nodeSpec`, `nodeGroups`. `skillContent` and `credentialValues` carry FOREVER `setQueryDefaults` for the in-memory cache but are deliberately NOT persisted; `credentialValues` was previously persisted here but was removed per OWASP HTML5 Security Cheat Sheet / ASVS V9.9 — decrypted API keys must never live in `localStorage`. The in-memory TanStack Query cache (`gcTime: ∞`) keeps the credentials form populated for the session lifetime; on reload the panel refetches via WS. `credentialCatalogue` has its own `idb-keyval` warm-start path so it is intentionally not in either list.\n- **WebSocket `sendRequest` replay queue**: when the socket is not open, requests enqueue with `AbortController`-backed per-request timeouts (default 30s) and replay on reconnect inside `ws.onopen` before `setIsReady(true)`. Queue capped at 200 with FIFO eviction. Any close rejects requests already sent (their outcome is unknown, so they are never replayed) and keeps queued ones under their original deadline; only `disposeConnection` (logout or unmount) closes with code 1000 and drops the queue. Implementation in `client/src/contexts/WebSocketContext.tsx` (`pendingSendQueueRef`, `drainPendingSends`, `disposeConnection`).\n- **Deleting a workflow stops it first, and nothing writes it back**: the REST `DELETE /api/database/workflows/{id}` and the `delete_workflow` WS command share `delete_workflow_with_context_archival` (`services/workflow_storage/handlers.py`), which first calls `stop_workflow_for_deletion` (`services/workflow_storage/deletion.py`): a generation that is live, paused, failed or still resetting, or an existing Workspace controller, goes through Reset (`handle_reset_workflow` with the latest control revision), and a legacy local deployment is cancelled. A failed shutdown, or a Start admitted meanwhile, refuses the delete with `workflow_shutdown_failed` (reason in `detail`) and keeps the graph; a hire that never ran is deleted without connecting to Temporal. Every save of an existing workflow passes `save_workflow(..., require_existing=True)` (an UPDATE whose row count is checked in the same transaction as the Context archive intents), so an editor save or read-time normalization that lands after the delete fails with `workflow_not_found` instead of re-inserting the graph. Client: `useAppStore.deleteWorkflow` deletes, then `forgetWorkflow` (also run by the `workflow.deleted` case in `WebSocketContext.tsx`, so it applies while Home is unmounted) cancels in-flight list and detail reads, prunes the workflow and employee caches (`features/home/data/employeeCache.ts::removeEmployee`) and clears only matching editor, Home and Workspace state. Nothing creates an Untitled replacement, and the Dev editor no longer creates one when no workflow exists. Employee lifecycle events and the hire, Turn on Talk and Apply responses refresh the employee queries (`refreshEmployee`) instead of merging their summaries, so a late payload cannot bring a deleted employee back. Locked by `tests/services/test_workflow_deletion_shutdown.py`, `tests/services/test_workflow_context_archive_outbox.py`, `client/src/store/__tests__/deleteWorkflow.test.ts` and `features/home/__tests__/homeSidebar.test.tsx`.\n- **`currentWorkflowId` single source**: lives in `useAppStore.currentWorkflow.id` only. Non-React listeners (WS handlers) read via `useAppStore.getState().currentWorkflow?.id` -- the documented Zustand escape hatch. The push to `nodeStatusStore.setCurrentWorkflowId` is driven from one `useEffect` in `Dashboard.tsx`. Removed the prior `currentWorkflowIdRef` mirror inside WebSocketContext that misrouted broadcasts during workflow switches.\n- **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.\n- **`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.\"\n- **`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\n- **`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.\n- **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).\n- **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).\n- **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)), as does Home's Workspace dock, a third host. 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()`. The current Browser node persists screenshots as workspace FileRefs via the containment-checked [nodes/browser/_screenshots.py](./server/nodes/browser/_screenshots.py); the live Browser workspace has its own binary stream. Full reference: [docs-internal/canvas_node.md](./docs-internal/canvas_node.md).\n- **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).\n- **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`.\n- **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.\n- **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.\n- **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.\n- **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 `clearConsoleLogs` so the callback doesn't re-create on every workflow switch. A dedicated `useEffect([currentWorkflowId, isReady])` resets local `consoleLogs` and refetches them 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). `WebSocketContext` keeps no chat state: every reader (the console's Chat pane, Home's employee page, Home's Get started checklist in `features/home/onboarding/useGetStarted.ts`) reads `get_chat_messages` through the shared thread query (`useChatThread` from `features/chat`), which `chat.updated`, a runtime reset and a reconnect invalidate.\n- **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}`).\n- **`isMasterSkillEditor` uiHint replaces `node.type === 'masterSkill'` checks**: the frontend callsites (`useAutoSkillEdges.ts` constant + edge filter, `MiddleSection.tsx` × 3; Dashboard's component-dispatch branch went with the unused `ToolkitNode`, because masterSkill declares `component_kind = \"tool\"` and renders through SquareNode) 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.\n- **`outputMode: \"terminal\"` uiHint — spec-driven CLI output rendering**: the output panel (`components/output/OutputPanel.tsx`, the active renderer — `ui/OutputDisplayPanel.tsx` is legacy/unimported) renders string responses through ReactMarkdown by default, which whitespace-collapses CLI text. CLI-wrapper plugins (`githubAction`, `vercelAction`, `shell`) declare `ui_hints = {\"outputMode\": \"terminal\"}`; the panel resolves the spec via `useNodeSpec(selectedNode?.type)` and renders their text in a `<pre>` on the per-theme `--code-*` surface, routes wholly-JSON strings to the JSON tree via the shared `tryParseJson` (`utils/formatters.ts`), and surfaces object/array `result` payloads (server-side-parsed CLI JSON; arrays survive `unwrap` un-peeled) in the Response section. Pair with the `_shape` convention: parsed JSON in `result` OR text in `stdout` — never both — empty keys omitted. Locked by `client/src/components/__tests__/OutputPanel.test.tsx` (render tests: real `\\n`/`\\t` preserved) + the uiHints known-set in `test_node_spec.py`. Cache note: nodeSpecs are session-sticky (`staleTime: FOREVER`, revision-busted at page load) — after a backend restart a hard browser reload is needed before new uiHints reach an open canvas.\n- **`--action-X-hover` triplet + ActionButton zero-arithmetic**: each of the 6 action roles (`run`/`stop`/`save`/`config`/`secret`/`tools`) now exposes a `-hover` variant (0.25 alpha) alongside the existing `-soft` (0.15) and `-border` (0.6). ActionButton's CVA reads `hover:bg-action-X-hover` directly; disabled state is the shadcn-idiomatic `disabled:opacity-50` on the base class. No per-token `/25`, `/40`, `/10` opacity arithmetic at any call site. Credential-modal panels (`OAuthConnect`, `EmailPanel`, `QrPairingPanel`) and the skill editor (`MasterSkillEditor`) consume `<ActionButton intent=\"...\">` directly. `ActionDef` carries an `intent` key; the catalogue adapter maps server-sent `theme_color` palette strings to intents via `SERVER_COLOR_TO_INTENT`.\n- **Credentials: DB as single source of truth + symmetric broadcasts + cache dedup**: `CredentialsDatabase` (encrypted SQLite) is canonical; every other layer is a derived cache with explicit invalidation. Backend `AuthService._memory_cache + _models_cache` collapsed into one `_api_key_cache: Dict[str, ApiKeyCacheEntry]` dataclass — single write/evict site. Per RFC 9700 (OAuth 2.0 BCP, 2024) the `_oauth_cache` no longer carries `refresh_token`; new `get_oauth_refresh_token(provider, customer)` reads from the encrypted DB on every call. `validate_api_key`, `save_api_key`, `delete_api_key`, `twitter_logout`, `google_logout` now broadcast symmetrically: `update_api_key_status` (in-memory map) + `broadcast_credential_event(...)` (refetch signal) wrapping `WorkflowEvent` (CloudEvents v1.0 from `services/events/envelope.py`, the same envelope the Wave 12 EventSource framework uses). The dead-letter `credential_catalogue_updated` event is finally emitted by the backend. Frontend retired the 200-LOC `client/src/components/credentials/providers.tsx` static fallback — `useCatalogueQuery` is the only source; cold-boot renders `<Skeleton>`, server-unreachable shows an explicit error state. `ApiKeyStatus.hasKey` mirror dropped (duplicated catalogue's `provider.stored`); two new selector hooks (`useProviderStored`, `useStoredProviderCount`) read the catalogue. Pytest invariant `test_credential_broadcasts.py` (17 tests) locks the broadcast contract via `inspect.getsource` introspection + the CloudEvents v1.0 envelope shape + AuthService DB-write-then-cache-update ordering + the no-refresh-token-in-cache rule.\n- **Local-LLM provider routing + per-model context**: Ollama and LM Studio are first-class providers. Chat-model node detection is `detect_ai_provider` in `server/constants.py`, which MUST list `ollama` / `lmstudio` or those nodes silently fall through to `'openai'`; agents need no edit, because their `provider` field is the loader-driven `ProviderRef` (`nodes/agent/_provider.py`, `aiProviders` loader). Saving (`nodes/model/_local_validator.py::save_llm_server`, shared with named endpoints) first roots the URL through the OpenAI surface (`services/llm/endpoints.py::resolve_base_url`, body must be an OpenAI list), writes nothing on failure, and then probes via the official SDKs (`ollama.AsyncClient.ps()` for typed `ProcessResponse.Model`, `lmstudio.AsyncClient.llm.list_loaded()` for typed `LlmInstanceInfo`) — reads only typed fields (`context_length`, `max_context_length`, `vision`, `trained_for_tool_use`, `architecture`, `params_string`, `format`, plus Ollama's `details.{family,parameter_size,quantization_level}`). No regex, no Modelfile-parameters parsing, no `/api/show` modelinfo dict-key hunting. Per-model params persist in `EncryptedAPIKey.models[\"model_params\"]` (via `store_api_key(model_params=...)`) AND via `register_local_model()`, which keeps them apart from the OpenRouter snapshot and persists them under DATA_DIR (`local_models.json`) — sync `get_context_length()` / `get_max_output_tokens()` find real values without async DB lookups, entries survive process restart, an OpenRouter refresh cannot wipe them, and user model names never land in the tracked `config/model_registry.json`. `is_model_valid_for_provider` returns `True` for providers that declare `\"open_world_models\": true` (openrouter / groq / ollama / lmstudio / openai_compatible) so local model names like `qwen/qwen3.6-27b` aren't rejected by the cloud-style pattern check. Runtime path passes the resolved URL to `OpenAIProvider` as `proxy_url` (it wins over the JSON `base_url`) with the stored key or the vendor's declared placeholder (`resolve_credential`) — no provider rewrites a key, and traffic stays on `localhost`.\n- **Typed SDK error → `LLMError` → `NodeUserError`**: Native providers normalize SDK failures into structured `LLMError` values carrying category, retryability, HTTP status, provider code, request ID, and retry-after metadata. `ChatUnifier` translates them at the execution boundary into a user-safe `NodeUserError`; `BaseNode.execute()` logs that at WARN with one line and no stack trace. Unexpected exceptions retain the full-traceback path. In-process agent turns retry only errors marked retryable, while Temporal owns activity retries and disables the inner retry loop.\n- **Plugin extraction (Wave 11.I)**: every plugin's WS handlers, OAuth client, FastAPI router, and lifecycle service live entirely under `nodes/<plugin>/`. Eight plugin domains migrated this round (whatsapp / twitter / google-workspace / android / browser / email / code / credential-validation-scaffold for maps+apify+ollama+lmstudio) follow the telegram pattern. `routers/websocket.py` shrunk from ~3,785 to ~2,977 LOC (-808). Three plugin routers (`routers/twitter.py`, `routers/google.py`, `routers/android.py`) moved into `nodes/<plugin>/_router.py` and mount via the plugin-router loop in `main.py`; the explicit `app.include_router(<plugin>.router)` calls and `from routers import <plugin>` imports in `main.py` are gone. **`register_router(router, name=...)` is the new sibling helper to `register_ws_handlers` (same file: `services/ws_handler_registry.py`)** — the generic registry set has grown since (the Plugin System row at the top of this file gives the `grep` for the live list). **`Credential.validate(data) -> dict` + `Credential._probe(api_key) -> ProbeResult` is the new shared validator scaffold** in `services/plugin/credential.py` — replaces the per-router `_SPECIAL_PROVIDER_VALIDATORS` dict; one `_LLMApiKey._probe` method serves all 10 cloud LLM providers, dedicated `_probe` overrides handle Maps + Apify, `_LocalLLM.validate` overrides for Ollama / LM Studio's 2-storage edge case. **`tests/test_plugin_self_containment.py` locks the contract** with 10 invariant classes (forbidden-imports / no-router-outside-nodes / per-plugin self-registration / registry-API sanity / stale-paths-absent / main.py-does-not-mount / WS_HANDLERS-non-empty / plugin-folder-has-node-file / typed-event-factories / package-imports-cleanly); same `inspect.getsource` introspection style as `test_credential_broadcasts.py`. Wire format unchanged — frontend WS message-type strings (`whatsapp_status`, `twitter_oauth_login`, `google_oauth_status`, `android_relay_connect`, etc.) and HTTP route paths (`/api/twitter/callback`, `/api/google/callback`, `/api/android/*`) are byte-identical post-migration.\n- **Typed CloudEvents factory pattern for new broadcasts** (b6aecd3): every new server→FE lifecycle broadcast follows the recipe locked by `broadcast_credential_event`, `broadcast_agent_progress`, and `broadcast_agent_capability`. (1) Add a typed factory — convention: `source = \"opencompany://services/<area>\"`, reverse-DNS `type = \"com.opencompany.<area>.<event>\"`, and `subject = <exact primary entity id>`. Put snake_case workflow/execution scope inside `data`; CloudEvents extension attribute names MUST be lowercase-alphanumeric, so the historical top-level `workflow_id`/`trigger_node_id`/`correlation_id` fields are compatibility debt and are forbidden on new contracts. (2) Add a broadcaster wrapper that emits `broadcast({type: \"<wire_key>\", data: event.model_dump(mode=\"json\", exclude_none=True)})`. (3) FE validates `specversion`, ID/source/type, subject ownership, and event-specific payload invariants, deduplicates by `(source,id)`, then writes only the exact scoped entity. (4) Add contract tests in `test_events.py` and keep `tests/test_status_broadcasts.py`'s raw-callsite allowlist empty. Raw `node_status` remains allowed only as the established high-frequency latest-state/reconnect projection paired with a typed lifecycle occurrence; it is not the event of record.\n- **Plugin-folder location for plugin-specific CloudEvents factories** (RFC §6.4): when a typed event is owned by one plugin (telegram, whatsapp, android, email, google, master_skill, webhook_trigger, agent), the factory + `broadcast_<event>` wrapper live in [`server/nodes/<plugin>/_events.py`](./server/nodes), NOT on `WorkflowEvent` / `StatusBroadcaster` directly. Telegram's [`_events.py`](./server/nodes/telegram/_events.py) is the canonical template — `broadcast_telegram_status` constructs the envelope via a plain factory function and calls `get_status_broadcaster().broadcast(...)` itself. Latest example: [`server/nodes/skill/master_skill/_events.py`](./server/nodes/skill/master_skill/_events.py) (`broadcast_skill_lifecycle(\"created\" \\| \"updated\" \\| \"deleted\" \\| \"content_saved\", name=..., **data_extra)`) — replaces four raw-dict broadcasts in `handle_create_user_skill` / `handle_update_user_skill` / `handle_delete_user_skill` / `handle_save_skill_content` (the last one was previously silent). FE routes wire key `skill_lifecycle` to invalidate `userSkills` + `folderSkills` queries and drop the `skillContent` cache on delete + content_saved so the Master Skill panel refreshes live across every connected client. Cross-cutting events (credential, workflow_lifecycle, agent_progress, agent_capability, node_parameters_updated) keep their `WorkflowEvent` classmethods + `StatusBroadcaster` wrappers — only plugin-scoped events move to the plugin folder. A core service's own event keeps its factory beside it, so core never imports a plugin `_events.py`: `services/workflow_ops.py` (`workflow_ops_apply`), `services/chat_thread.py` (`chat.updated`) and `services/chat/events.py` (the owner's chat message to the chatTrigger listeners, which moved there from the plugin, and `chat_run_event`).\n- **Operator-metadata fields in credential panels** (f746ddf): when a credential panel needs a non-credential follow-up field (e.g. Telegram bot token + owner chat id), declare it as a second entry in the provider's `fields` array in `server/config/credential_providers.json`. The first field stays the validate/connect target; subsequent fields render below as plain text inputs via `SecondaryFieldRow` in `ApiKeyPanel.tsx` (shadcn `Input` + `Label` + `<ActionButton intent=\"save\">`). Each field carries an optional `help` slot (`FieldDef.help` / `ServerFieldDef.help`) for always-visible explanatory text under the input. Save writes via `panel.actions.save(field.key, value)` → `auth_service.store_api_key` (which is permissive about provider string). The credential class must declare the new key in `extra_fields` (`Credential` subclass attribute) so the storage layer accepts it. Reference: `telegram_owner_chat_id` field.\n- **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 `_send.py` `resolve_chat_id` (read DB → `service.set_owner`), which `telegram_send.py` calls, sits on top of all three.\n- **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.\n- **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.\n- **`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`, `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. `installed_version(name)` reads `node_modules/<name>/package.json`: an existing shim says nothing about its version and `company clean` keeps `packages/`, so a pinned plugin compares against it and re-runs `add_package` on a mismatch (Cloudflare does; the other installers check only that the shim exists, so their pin bumps reach fresh installs only). 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). The Browser runtime does not use this npm tree: its CLI installer uses `packages/browser-use/`; only explicit testing mode installs Chrome under `packages/chrome-for-testing/` (see [Browser](./docs-internal/browser.md)). 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`, and the model-registry caches `local_models.json` (models registered from the user's own LLM servers) / `litellm_models.json` (LiteLLM's model table, RFC-0003 D16). 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.\n- **`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.\n- **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.\n- **`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`.\n- **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. **The one shape the query does accept** is normalise-then-prefix-check performed *before* the path is used: `core/approot.py::resolve_static_asset` joins the request path onto the real base dir, runs `os.path.normpath`, and returns `None` unless the result starts with that base plus a separator. `main.py`'s SPA fallback was rewritten onto it in September 2026 (alerts #158-160) because that route can take a `None` and fall through to the SPA shell. Reach for that shape when the call site tolerates a miss; keep the dismissal route for helpers whose flagged sink IS the `resolve()`. 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.\n- **CLI recovery-resilience invariants** (May 2026): `python -m cli clean` must run end-to-end on a system Python with no third-party deps. Achieved by: (a) every verb in [`cli/cli.py`](./cli/cli.py) is a lazy stub that imports its impl inside the function body — `import cli.cli` does NOT pull in `anyio` / `psutil` / `cli.supervisor` / sibling verb modules (300 → 131 modules at boot). (b) [`cli/_common.py`](./cli/_common.py) defers `cli.supervisor` imports inside `build_backend_spec` so importing `cli._common` (and therefore `clean.py`) doesn't drag in rich. (c) [`cli/platform_.py`](./cli/platform_.py) lazy-imports `platformdirs` inside the four `user_*_dir` helpers — module loads without the wheel. (d) [`cli/commands/clean.py`](./cli/commands/clean.py) uses stdlib `print()` (no rich) + lazy `cli.ports` import inside `_kill_running_processes` wrapped in `try/except ImportError` (skip-with-warning if psutil is missing). (e)+(f) retired July 2026: the CLI no longer supervises Temporal at all — the backend lifespan owns the dev server via `services.temporal._runtime.ensure_started()` (`cli/commands/_temporal_specs.py` and the `_supervised_runtime.py` shim were deleted; long-running specs spawn the server venv interpreter directly via `cli.platform_.server_venv_python`, no resident `uv run` parents). (g) `daemon` is now a verb-per-file package ([`cli/commands/daemon/`](./cli/commands/daemon/) — `_state.py` + `start.py` + `stop.py` + `status.py` + `restart.py`) following pdm's `commands/venv/` shape; PID-file resolution is a function (`pid_dir()`) not a module-level attribute so platformdirs only loads at call time.\n- **Wave 13 canary fixes** — six load-bearing corrections to the Wave 12 event framework. See [docs-internal/event_framework.md → Wave 13 fixes](./docs-internal/event_framework.md#wave-13-fixes) for the full breakdown. Key invariants to remember when working on canary triggers: (1) `register_canary_trigger_type(node_type, cloudevent_type)` requires the CloudEvents reverse-DNS string as second arg — must match the producer's `WorkflowEvent.type` exactly or the deployment manager's `EventType` SA won't match `dispatch.emit`'s Visibility query (silent firing failure). Diverging re-registration raises `ValueError` so plugin upgrades surface loudly. (2) Plugin `_events.py` for canary-registered triggers is canary-only — no `event_waiter.dispatch` / `send_custom_event` calls (those have zero consumers in canary-on mode). `dispatch.emit(envelope, wire_routing_key=...)` handles BOTH Temporal Signal fan-out AND in-process WS broadcast. (3) `TriggerListenerWorkflow` + `PollingTriggerWorkflow` call `broadcast_trigger_status_activity` before/after each child spawn for firing-pulse UX (matches legacy `triggers.py` collector/processor). (4) `PollingTriggerNode.as_poll_activity` returns `seen_ids: list(current)` — NOT `list(prior_seen | current)` (the latter grows unboundedly; Gmail at ~100/day hit ~36K entries in a year). The legacy `_build_poll_coroutine` does `seen = set(current)` at end of cycle for the same reason. Visibility-filtered providers (Gmail-unread) re-emit on re-surface, which is correct. (5) Canary trigger output persistence: `MachinaWorkflow.run`'s pre-executed loop schedules `store_node_output_activity` for every firing trigger so `ParameterResolver` can resolve `{{triggerNode.field}}` in downstream nodes (the legacy `_execute_from_trigger` did this via `_store_output(trigger_node_id, \"output_0\", ...)`; canary skipped it pre-fix). Skips non-firing siblings (`_trigger_output={\"not_triggered\": True}`). (6) `DeploymentManager.cancel` sweeps stuck node statuses via `_clear_stuck_node_statuses(workflow_id, include_waiting=True)` + emits terminal `update_workflow_status(executing=False, workflow_id=...)`. Without these the FE leaves downstream nodes glowing forever after deployment cancel and the toolbar Start/Stop indicator stays at `executing=True`. The delegation guard inside `_clear_stuck_node_statuses` still protects in-flight fire-and-forget child agents.\n- **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.\n- **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).\n- **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).\n- **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.\n- **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]` (`BaseNode._run_operation` in `services/plugin/base.py`), 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).\n- **Never name a Params field `model` or `api_key` on a node that also has a `provider` field.** An effect at [`ParameterRenderer.tsx:898`](./client/src/components/ParameterRenderer.tsx#L898) 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. L952 / L1207 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`.\n- **A dual-purpose node gets no main canvas handles unless it declares them.** `BaseNode.__init_subclass__` (`services/plugin/base.py`) sets `hide_input_handle` / `hide_output_handle` to `True` for `usable_as_tool` and tool classes unless the class sets them, and `_metadata_dict` adds an `output-tool` handle to their spec. `SquareNode` renders a spec's declared `handles` whenever there are any and reads the hide flags only in its cold-cache fallback, so setting the flags `False` alone adds nothing: a node that must also chain on the canvas lists `input-main` / `output-main` in `handles` (the plugins that do this, such as speech and translate, also set both flags `False`). Symptom: the node works fine as an AI tool but shows only its Tool handle on the canvas.\n- **Temporal LLM tool calls carry unmerged `tool_args`, and ToolNodes take `execute_as_tool`.** The AgentWorkflow schedules each tool call as the tool's own per-type activity; the payload carries BOTH the merged `node_data` (legacy/dual-purpose contract) AND the model's raw arguments as `tool_args`, forwarded through `as_activity`'s extras into the legacy handler, which routes ToolNodes through `execute_as_tool` for real `ToolInput` validation. Without this, the merged dict validated against `Params` (`extra=\"ignore\"`) and a split-schema tool's model arguments were silently DROPPED — every Simple Memory `remember` degraded to a harmless `list`, reported success, and stored nothing. Dual-purpose ActionNodes deliberately keep their documented merged-params behavior. Locked by `tests/nodes/test_tool_call_dispatch.py` (including an end-to-end store assertion). Related guard: a function-local `import` makes its name local for the WHOLE function, so any use above it raises `UnboundLocalError` at runtime that `py_compile` cannot catch — a mid-function `import json` below the conversation size guard failed every Context-connected run this way (AST-locked in `test_agent_workflow.py`).\n- **Inspection panels opt out of the global `refetchOnMount: false`.** The QueryClient default (\"trust the cache; the broadcast bridge keeps it in sync\") assumes an active observer exists when the invalidation lands — but Context/Memory data mutates while those panels are CLOSED, so the broadcast invalidates a query nobody observes and a later mount renders stale cache until a manual Refresh. `ContextPanel` and `MemoryToolPanel` therefore declare `refetchOnMount: 'always', staleTime: 0`; the `context.updated` / `memory.updated` broadcasts cover the panel-open case. Apply the same override to any future panel whose data is written by agent runs rather than by the panel itself.\n- **Media leaves a node as a reference, never as bytes.** `services/media/` + `FileRef` (~400 B, `extra=\"forbid\"`) with `AudioRef(FileRef)` as the probed-container narrowing — set `kind=\"audio\"` only when the duration actually came from `inspect_audio`, because a fabricated one silently mis-bills per-second providers; the `gallery` node therefore emits `kind=\"file\"` even for a `.wav`. A node result is persisted 3x, broadcast 2x, retained in `_status` forever, aggregated into the workflow result, copied into every downstream activity *input*, and — if `usable_as_tool` — serialized into an LLM message; a 12 MB base64 payload therefore fails the activity, **retries 3x re-billing the provider each time**, and reports a generic error. Nodes call `write_audio` (out) and `coerce_file_param` (in); both enforce containment through `resolve_within`, which closed a live traversal that let `audio_file=\"../../credentials.db\"` read the encrypted credential store and upload it. **id/slug trap:** workspace dirs are named by the mutable `Workflow.slug` while a ref stores the immutable `workflow_id` so refs survive rename — `workspace_root()` raises rather than composing a wrong path, and the lookup now lives in `services/workspace_locator.py`, which every database-holding caller delegates to (the HTTP route, the gallery WS handlers, `WorkflowService`). Reads may fall back to the anonymous `\"default\"` workspace; **mutating callers must pass `allow_default=False`**, or a stale tab's unresolvable id destroys files in a different context than the caller believes. Full reference: **[Media Transport](./docs-internal/media_transport.md)**.\n- never use emojis in prints\n","archived":false,"sha256":"0b230d1fc5dd5198567520100365043c087ee04c5c4f8b06982f12b7608dfe01"},"doc:cli/README.md":{"id":"doc:cli/README.md","path":"cli/README.md","title":"company","content":"# company\n\nProject supervisor CLI for the OpenCompany stack. The public command is\n`company`; the npm package is `@zeenie-ai/opencompany`, and the legacy `machina` bin\nremains as a deprecated compatibility alias. It is also backwards-compatible\nwith `bun run start`/`dev`/`stop`/etc.\n\n## Install\n\nNo install step is required for a source checkout: `bin/cli.js` and the root\npackage.json scripts both invoke `python -m cli` from the repo root;\n`scripts/postinstall.js` deliberately does not pip-install it. To install the\n`company` entry point on PATH:\n\n```sh\npython -m pip install -e . # run from the repository root, not from cli/\n```\n\n## Use\n\n```sh\ncompany --help # list commands\ncompany stop # kill ports + orphans + temporal\n```\n\nOr via the package.json scripts (`bun run <script>`, which invoke the same Python CLI):\n\n```sh\nbun run stop\n```\n\n## Cross-platform notes\n\n- **Windows**: `python` resolves correctly out of the box.\n- **macOS / Linux**: requires `python` to point to Python 3.12+. Most\n modern distros provide this via `python-is-python3` or a symlink. If\n your distro only ships `python3`, run `python3 -m cli <cmd>` or\n add an alias.\n\n## Architecture\n\nBuilt on battle-tested primitives — minimal custom code:\n\n| Layer | Library |\n|---|---|\n| CLI | `typer` |\n| Subprocess | `anyio.open_process` |\n| Tree-kill | `psutil` + `pywin32` (Job Objects on Windows) |\n| Restart backoff | stdlib (deque + monotonic time + jittered exponential, ~20 LOC) |\n| Output | `rich.Console` |\n| Env | stdlib parser over `.env.template`, `.env`, and `.env.dev` |\n","archived":false,"sha256":"9c561792f096f1e0a4b2631ac10fa4b3a82989a27546c8ea69207e52634b427e"},"doc:cli/terraform/aws/README.md":{"id":"doc:cli/terraform/aws/README.md","path":"cli/terraform/aws/README.md","title":"OpenCompany on AWS (Terraform)","content":"# OpenCompany on AWS (Terraform)\n\nOne login-gated EC2 instance running OpenCompany per deployment, driven by\n`company deploy --provider aws` (`cli/commands/deploy/providers/aws.py`). The\nadapter checks the aws CLI and its login, resolves the region (`--region`,\nthen `AWS_REGION` / `AWS_DEFAULT_REGION`, then the profile, then `us-east-1`),\nhands the credentials the CLI resolved to Terraform (its aws provider cannot\nread every source the CLI can, `aws login` sessions included), and checks\nthat the region has a default VPC. `up` then writes `terraform.tfvars.json`\ninto the deployment's own folder and runs `terraform apply`.\n\nFile layout follows the HashiCorp AWS get-started tutorial\n(https://developer.hashicorp.com/terraform/tutorials/aws-get-started):\n`terraform.tf` (providers), `main.tf`, `variables.tf` (the variable set every\nprovider module declares, plus `region` and three optional AWS settings),\n`outputs.tf` (`external_ip`, `url`, `instance_id`), plus `startup.sh.tftpl`\n(the cloud-init startup script template).\n\n```bash\ncompany deploy up --provider aws --name acme-corp --owner-email [email protected]\ncompany deploy status --name acme-corp\ncompany deploy destroy --name acme-corp\n```\n\nEach `--name` is a separate deployment: its own Terraform state under\n`<DATA_DIR>/deploy/<name>/`, its own instance, security group (`<name>-app`),\nsystemd unit, env file and data directory. That is how one machine creates\none VM per user. Names are 6-30 lowercase letters, digits and hyphens\nstarting with a letter (GCP's service-account rule, so a name works on both\nproviders).\n\n| Setting | Value | Why |\n|---|---|---|\n| Instance | `--machine-type`, default `t3.micro` (2 vCPU, 1 GiB) | Smallest size the app runs on (backend ~200 MB + Temporal ~150 MB). 512 MB OOM-loops. |\n| Credit mode | `standard` | Caps compute at the hourly rate under continuous CPU load. |\n| Root disk | 10 GiB gp3, deleted with the instance | A fresh install uses ~4.5 GiB. |\n| Image | Ubuntu 24.04 LTS (Canonical), the newest when the instance is created | Python 3.12 inside the server's `<3.13` pin. |\n| Install | `install.sh` as `ubuntu`, no sudo; a published release only | Root installs leave the venvs unusable by the login user (errors.md #16). The module has no artifact bucket, so `--source local` is refused. |\n| 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. systemd gets `$APP_HOME/.bun/bin` on PATH and `ExecStart=$APP_HOME/.bun/bin/company serve`. |\n| Runtime | `company serve` under systemd as `ubuntu` on `--port` (default `PYTHON_BACKEND_PORT`) | The server rejects ports below 1024; 80/443 stay free for a TLS front door. |\n| Temporal | on (the `.env.template` default, as in the Docker image) | Chat, chat and webhook triggers, and cron need it. |\n| Security group | 22, 80, 443 and the app port from `--allow-cidr` | Same shape as the gcp module. |\n| Re-apply | never replaces or restarts a running instance (`ignore_changes = [ami, user_data]`) | Replacing deletes the root volume and everything in `DATA_DIR`. The boot script runs only on the first boot, so a new image, script or `app_env` reaches new instances only. |\n\nReleases up to 0.2.1 do not come up on a fresh instance: `company serve`\nstops with `Project not built` and systemd restarts it in a loop\n([errors.md #25](../../../docs-internal/errors.md), fixed after 0.2.1).\n`--version` picks the release (the tag without the `v`); the default `latest`\ninstalls the newest one.\n\n`app_env` carries the owner login, fresh JWT/encryption keys, `PORT`,\n`DATA_DIR=/var/lib/<name>` and `DEPLOYMENT_MODE=cloud`; `company deploy` builds\nit with `build_app_env` (`cli/commands/deploy/_secrets.py`). To run the module\nby hand, write `terraform.tfvars.json` with the variables in `variables.tf`\n(the file `company deploy up` writes is the template) and run `terraform\ninit` / `apply` in a folder of its own. First boot takes about 10 minutes on a\nt3.micro.\n\nFirst boot fetches `https://opencompany.sh/install.sh` (override with\n`install_sh_url`), and that script asks `https://opencompany.sh/version` for\nthe release unless `opencompany_version` is set. Both endpoints must be served\nfrom the opencompany.sh site.\n\nCost at us-east-1 list prices: about $12/month per t3.micro deployment\n(instance, disk, public IPv4), and CPU load cannot raise it. Egress past the\nfree 100 GB/month is the only open-ended line.\n","archived":false,"sha256":"a68d10a8fba8d2baec55e163a8eba1b36b091fa8e936ad9be3ce70440bcec171"},"doc:client/src/test/README.md":{"id":"doc:client/src/test/README.md","path":"client/src/test/README.md","title":"Frontend Test Suite","content":"# Frontend Test Suite\n\nLocks in the user-facing invariants from [docs-internal/ARCHIVE/credentials_panel.md §5](../../../docs-internal/ARCHIVE/credentials_panel.md).\n\n## Run\n\n```bash\ncd client\nbun run test # one-shot (vitest run)\nbun run test:watch # watch mode\nbun run test:coverage # with v8 coverage report\n```\n\nDependencies come from `bun install` at the repo root (the client is a workspace member).\n\n## Layout\n\nTest files live beside their subjects, almost all under `__tests__/` directories, across adapters/, app/, assets/icons/, components/, contexts/, features/ (chat/, home/), hooks/, lib/, store/, stores/, types/ and utils/. Targeted subsets: `bun run test:credentials`, `bun run test:nodepanels`.\n\n## Tooling\n\n- **Vitest** + **jsdom** for fast component tests\n- **@testing-library/react** + **@testing-library/user-event** for behaviour assertions\n- **builders.ts** for test-data factories — keep test bodies focused on deltas, not boilerplate\n- **setup.ts** stubs `matchMedia` / `ResizeObserver` / `IntersectionObserver` (jsdom doesn't ship them)\n- **waapi.ts** records Web Animations (`installWaapiStub()`) for tests that assert on motion; jsdom has no `Element.animate`\n\n## What this suite does NOT test\n\n- The internals of the shadcn / Radix primitives\n- `react-flow` rendering\n- Backend handlers (covered by `server/tests/credentials/`)\n- Full OAuth round-trip with real X / Google (no network)\n","archived":false,"sha256":"79e29be2212e3eb34591adf846ee1663cff92bb0f4f553d8c2095e352404672d"},"doc:CONTRIBUTING.md":{"id":"doc:CONTRIBUTING.md","path":"CONTRIBUTING.md","title":"Contributing to OpenCompany","content":"# Contributing to OpenCompany\n\nWelcome! This guide is a contributor's map to the codebase. It tells you *where things live* and *where to start reading* when you want to add a feature. For the full architecture tour, use the [DeepWiki badge](https://deepwiki.com/zeenie-ai/OpenCompany) on the README or browse [docs-internal/](docs-internal/).\n\n## Contribution Workflow\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\nSee [SETUP.md](docs-internal/SETUP.md) for environment setup and [SCRIPTS.md](docs-internal/SCRIPTS.md) for the full scripts reference.\n\n## System Overview\n\n[](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/system-overview.svg)\n\nAt a glance:\n\n- **140+ workflow nodes** across 33 populated palette groups (34 registered in `server/nodes/groups.py`) (live count: `len(services.node_registry.NODE_METADATA)` *after* importing `nodes` — a bare `server/nodes/**/__init__.py` glob both over-counts helper packages and under-counts groups that hold several node types in one package)\n- **Native LLM providers**: 11 cloud providers, Ollama and LM Studio, plus any number of user-named OpenAI-compatible endpoints (llama.cpp, vLLM, a LiteLLM proxy) added in the Credentials Modal with no code. One standalone chat-model node per provider except xAI, which agent nodes select directly, plus `openaiCompatibleChatModel` for a named endpoint\n- **Specialized AI agents** with the Agent Teams delegation pattern — SSOT is the `AI_AGENT_TYPES` frozenset in `server/constants.py`, which spans the base/specialized/team-lead agents plus the CLI-backed (`claude_code_agent`, `rlm_agent`) variants; `codex_agent` is a sibling CLI-agent plugin\n- **WebSocket-first API** replacing most REST endpoints (live handler count = `MESSAGE_HANDLERS` + plugin registries)\n- **78 built-in skills** across 18 folders, editable in-UI with SKILL.md defaults on disk (live count: `find server/skills -name SKILL.md | wc -l`)\n- **Two execution modes** with automatic fallback: Temporal distributed, sequential\n\n## How Workflows Execute\n\n[](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/execution-flow.svg)\n\n[WorkflowService](server/services/workflow.py) is a thin facade that routes each run through Temporal when available, falling back to a plain sequential walk otherwise. Every run has an isolated `ExecutionContext` with no shared global state. Nodes are scheduled continuously — when any node completes, its newly-ready dependents start immediately (`FIRST_COMPLETED` pattern) instead of waiting for a whole layer to finish.\n\nNewly started Temporal generations use revision-ordered cooperative control:\nStop closes admission across the execution tree, admitted work finishes with\nits bookkeeping, and Resume releases the same pending continuation. Signals\nqueue events, completed Updates acknowledge control and root membership, and\nQueries expose read-only state. Preserve the legacy/version-marker command\npaths when editing Workflow code; validate them with native history replay.\n\nDeep dives: [DESIGN.md](docs-internal/DESIGN.md) - [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) - [temporal-workflow-control.md](docs-internal/temporal-workflow-control.md) - [event_framework.md](docs-internal/event_framework.md)\n\n## AI Agent System\n\n[](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/ai-agent-routing.svg)\n\nDirect chat completions and every new agent execution use the native SDK layer in [services/llm/](server/services/llm/) through `ChatUnifier`. The shared `run_native_agent_loop` consumes lossless native messages and provider-neutral `AgentToolSpec` definitions; Groq, Cerebras, xAI, DeepSeek, Kimi, Mistral, the local servers and every named OpenAI-compatible endpoint ride the OpenAI-compatible client with provider-specific `base_url` values. LangChain has been removed; Temporal histories recorded before the native cutover are refused rather than replayed. Team leads (`orchestrator_agent`, `ai_employee`) receive an intrinsic Task Manager and may assign only agents connected to their `input-teammates` handle. Delegate descriptors stay internal. `task_manager(assign_task)` persists and returns `queued`; Temporal hands work to a detached `DelegatedTaskWorkflow`, while legacy execution reuses the same durable task record. Completion emits `taskTrigger` with owning execution context for a separate lead review. The RLM Agent uses a REPL-based recursive language model pattern. Long-running activities remain alive through activity heartbeats.\n\nDeep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [native_llm_sdk.md](docs-internal/native_llm_sdk.md) - [agent_teams.md](docs-internal/agent_teams.md) - [memory_compaction.md](docs-internal/memory_compaction.md) - [cli_agent_framework.md](docs-internal/cli_agent_framework.md)\n\n## More Diagrams\n\nFourteen source-backed architecture and product-panel diagrams live next to the ones above in [docs/diagrams/](docs/diagrams/). Each carries the source files it was drawn from in its `<desc>`.\n\n| Diagram | What it shows |\n|---|---|\n| [System context](docs/diagrams/system-context.svg) | Who uses OpenCompany and which external capabilities it orchestrates |\n| [Runtime and trust topology](docs/diagrams/runtime-trust-topology.svg) | Browser, desktop and CLI clients, the authenticated REST / WebSocket / MCP / webhook surfaces, Temporal and the lazy sidecars |\n| [Workflow execution routing](docs/diagrams/workflow-execution-routing.svg) | Temporal, parallel and sequential branches converging on the NodeExecutor pipeline |\n| [Durable deployment and events](docs/diagrams/durable-deployment-events.svg) | Generation snapshots, WorkflowControlWorkflow, push / poll / cron triggers, CloudEvents dispatch |\n| [Plugin, agent and team composition](docs/diagrams/plugin-agent-team-composition.svg) | How plugins become chat-model and agent nodes, assemble context, skills and tools, and form teams |\n| [Persistence and secret plane](docs/diagrams/persistence-secret-plane.svg) | workflow.db versus the encrypted credentials.db boundary |\n| [Workspace anatomy](docs/diagrams/workspace-anatomy.svg) | Immutable id to mutable slug directories, contained I/O, CLI worktrees and materialized skills |\n| [Node configuration anatomy](docs/diagrams/node-configuration-anatomy.svg) | The Input / Parameters / Output modal, local draft, save-before-run and correlated output |\n| [Credentials architecture](docs/diagrams/credentials-architecture.svg) | Server-owned catalogue, WebSocket handlers, AuthService and encrypted storage |\n| [Team operations](docs/diagrams/team-operations.svg) | Task Manager lifecycle from blocked and queued through submission, review and finish |\n| [Agent context versus memory](docs/diagrams/agent-context-memory.svg) | The stored conversation (RFC-0002) beside the explicit Memory tool |\n| [Master Skill editor](docs/diagrams/master-skill-editor.svg) | Skill sources, the catalogue and instruction panes, expansion and runtime badges |\n| [Workspace files](docs/diagrams/workspace-files.svg) | The Gallery node panel: WebSocket listing, HTTP content and the FileRef output |\n| [Runtime observability dock](docs/diagrams/runtime-observability-dock.svg) | Chat, Console and Terminal producers, retention and the dock UI |\n\n## Repository Map\n\n| Directory | What lives here | Start reading |\n|---|---|---|\n| `server/nodes/<category>/<node>/__init__.py` | Workflow node plugins (self-contained folders, NodeSpec + execute) — backend SSOT since Wave 11 | [plugin_system.md](docs-internal/plugin_system.md), [server/nodes/README.md](server/nodes/README.md) |\n| `client/src/components/` | React Flow canvas, parameter panel, modals | [CLAUDE.md](CLAUDE.md) |\n| `server/services/` | WorkflowService, NodeExecutor, AI service | [DESIGN.md](docs-internal/DESIGN.md) |\n| `server/services/handlers/` | Cross-cutting orchestration only (`tools.py` AI-tool dispatch + delegation, `triggers.py`, `todo.py`) — per-node handlers live inside the plugins since Wave 11 | [node_creation.md](docs-internal/node_creation.md) |\n| `server/services/llm/` | Native LLM SDK layer (every provider, plus named OpenAI-compatible endpoints) | [native_llm_sdk.md](docs-internal/native_llm_sdk.md) |\n| `server/services/execution/` | Decide pattern, DLQ, recovery, conditions | [DESIGN.md](docs-internal/DESIGN.md) |\n| `server/services/temporal/` | Distributed execution via Temporal | [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) |\n| `server/routers/websocket.py` | WebSocket endpoint + core `MESSAGE_HANDLERS` (plugins register more via `ws_handler_registry`) | [status_broadcaster.md](docs-internal/status_broadcaster.md) |\n| `server/core/` | Cache, encryption, DI container, config | [credentials_encryption.md](docs-internal/credentials_encryption.md) |\n| `server/skills/` | Skill SKILL.md files, one folder per agent domain (live count: glob `server/skills/**/SKILL.md`) | [GUIDE.md](server/skills/GUIDE.md) |\n| `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) |\n| `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) |\n| `client/src/` (styling + themes) | Tailwind tokens, shadcn primitives, the theme contract | [frontend_architecture.md](docs-internal/frontend_architecture.md), [theme_system.md](docs-internal/theme_system.md) |\n| `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) |\n| `docs-internal/` | In-repo architecture deep dives (50+ files) | Index below |\n\n## How to Contribute Features\n\n[](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/node-anatomy.svg)\n\nThe diagram above shows the full lifecycle of a workflow node: one self-contained Python plugin folder that auto-registers on import and renders itself on the frontend with zero TypeScript edits. Use these recipes as a starting point:\n\n**Add a workflow node**\n- Start at [node_creation.md](docs-internal/node_creation.md) (the decision tree routes action / trigger / tool / dual-purpose / agent work), copy the recipe from [server/nodes/README.md](server/nodes/README.md), and reach for [plugin_system.md](docs-internal/plugin_system.md) as the deep reference\n- One plugin folder: `server/nodes/<category>/<node>/__init__.py` — subclasses `ActionNode` / `TriggerNode` / `ToolNode`, declares Pydantic `Params`/`Output` + `@Operation` methods; auto-registers on import, zero frontend edits\n- Icon = `icon.svg` in the folder, color = `meta.json` (never class attributes); raise `NodeUserError` for user-correctable failures\n- Add a behavioral test in `server/tests/nodes/test_<category>.py` (the invariant suites cover the contract automatically — see Testing below)\n\n**Add an LLM provider**\n- Guide: [native_llm_sdk.md](docs-internal/native_llm_sdk.md) → \"Adding a New Provider\"\n- OpenAI-compatible (DeepSeek, Kimi, Mistral pattern): add the provider configuration to `server/config/llm_defaults.json` and its name to `services/llm/providers/_compat.py::_COMPAT_PROVIDERS`\n- Custom-SDK provider: new file in `server/services/llm/providers/` that calls `register_provider(ProviderSpec(...))` at module bottom (lazy factory + `sdk_exception_refs`; the legacy `factory.py` was removed — `register_provider` is the only entry point)\n- Chat-model node plugin: `server/nodes/model/<provider>_chat_model/__init__.py`, plus a branch in `detect_ai_provider` (`server/constants.py`), or the node falls through to `'openai'`. Agent dropdowns need no edit: their `provider` field is the loader-driven `ProviderRef` (`nodes/agent/_provider.py`), which lists every registered provider\n- A server the user runs (llama.cpp, vLLM, a LiteLLM proxy, another Ollama host) needs no code at all: it is a named endpoint added in the Credentials Modal ([RFC-0003](RFC-0003-OPENAI-COMPATIBLE-PROVIDER-CONTRACT.md))\n\n**Add a dual-purpose tool (workflow node + AI tool)**\n- Guide: [node_creation.md](docs-internal/node_creation.md); live references: the whatsapp / twitter / stripe folders\n- Plugin folder with `group: ['category', 'tool']` and `usable_as_tool = True`; the Pydantic `Params` doubles as the LLM-visible tool schema (keep it flat — no nested models / `$defs`)\n- If you give the tool a short `tool_name` that isn't `<snake_case_of_node_type>` AND ship a paired skill, add a `visuals.json` alias entry keyed by the tool name carrying **icon and color** — otherwise the Master Skill row renders blank (locked by `server/tests/test_skill_icon_resolution.py`)\n\n**Add a specialized AI agent**\n- Guide: [node_creation.md](docs-internal/node_creation.md) + [agent_architecture.md](docs-internal/agent_architecture.md)\n- Add the plugin under `server/nodes/agent/<name>/` (extends `SpecializedAgentBase` from `server/nodes/agent/_specialized.py`)\n- Single cross-cutting edit: add the agent's `type` string to the `AI_AGENT_TYPES` frozenset in `server/constants.py` — delegation dispatch imports that frozenset, nothing else to update\n- CLI-backed agents (Claude Code / Codex shape) follow [cli_agent_framework.md](docs-internal/cli_agent_framework.md)\n\n**Add a skill**\n- Guide: [GUIDE.md](server/skills/GUIDE.md) (folder structure, SKILL.md frontmatter, and the tool-naming contract that drives the skill's icon)\n- New folder under `server/skills/<domain>/<skill-name>/SKILL.md` with YAML frontmatter + markdown body\n\n**Add an event source / trigger (Wave 12)**\n- Guides: [node_creation.md](docs-internal/node_creation.md) → Wave 12 recipe (authoring) → [event_framework.md](docs-internal/event_framework.md) (Temporal routing + ops) → [stripe_service.md](docs-internal/stripe_service.md) (the reference implementation)\n- Pick the source shape: `DaemonEventSource` (CLI daemon), `WebhookSource` + `WebhookTriggerNode` (signed webhooks, with a verifier from `services.events.verifiers`), or `PollingEventSource` (API polling)\n- Register via `register_canary_trigger_type(node_type, cloudevent_type)` + emit `WorkflowEvent`s via `dispatch.emit` from the plugin's `_events.py`; plugin-owned filters go through `register_filter_builder` — never hand-edit `event_waiter.py` ([event_waiter_system.md](docs-internal/event_waiter_system.md) is historical, pre-Wave-11)\n\n**Integrate a CLI-managed-auth service (Stripe / Vercel / GitHub shape)**\n- Guide: [node_creation.md](docs-internal/node_creation.md) → \"CLI-managed auth\" recipe; references: [stripe_service.md](docs-internal/stripe_service.md) (two-step browser OAuth), [vercel_service.md](docs-internal/vercel_service.md) (device-flow variant), [github_service.md](docs-internal/github_service.md) (gh owns auth entirely)\n- The external CLI owns the real tokens; the plugin writes marker tokens via `auth_service.store_oauth_tokens(provider, \"cli-managed\", \"cli-managed\")` and broadcasts the generic `credential_catalogue_updated` event — zero per-provider frontend code\n- `_install.py` auto-downloads the pinned CLI binary into the shared packages tree\n\n**Integrate an OAuth service**\n- Guides: [plugin_system.md](docs-internal/plugin_system.md) (Connection facade, credentials, `register_router` / `register_option_loader`); live reference: [server/nodes/google/](server/nodes/google/) — 7 nodes sharing one OAuth connection via `_oauth.py` / `_router.py` / `_auth_helper.py`\n- ([new_service_integration.md](docs-internal/ARCHIVE/new_service_integration.md) is archived — do not follow its steps)\n\n**Add a credential provider**\n- Declare a `Credential` subclass in the plugin folder's `_credentials.py` and add the provider entry to `server/config/credential_providers.json` — the Credentials Modal renders it with no React edits\n- Guides: [credentials_encryption.md](docs-internal/credentials_encryption.md) (storage pipeline) + [frontend_architecture.md → Credentials](docs-internal/frontend_architecture.md) (the config-driven modal); the numbered invariants the tests cite live in the archived [credentials_panel.md §5](docs-internal/ARCHIVE/credentials_panel.md); test conventions in [server/tests/credentials/README.md](server/tests/credentials/README.md)\n\n**Contribute frontend / a new theme**\n- Read [frontend_architecture.md](docs-internal/frontend_architecture.md) first (stack, token tiers, state-ownership boundary, the strict styling rules), then [theme_system.md](docs-internal/theme_system.md) for the theme contract\n- New themes follow theme_system.md → \"Adding a new theme\" (per-theme CSS file + tokens; no component code changes — that is the contract)\n- New backend uiHint flags need two frontend-side edits: `INodeProperties.ts` + the `known` set in `server/tests/test_node_spec.py`\n\n## Testing Your Contribution\n\n- **Contract invariants run automatically.** `server/tests/test_plugin_contract.py` and `test_node_spec.py` iterate every registered plugin and assert the declared shape — a new node is covered the moment it imports. `test_plugin_self_containment.py` enforces the no-cross-plugin-imports rule; `test_skill_icon_resolution.py` asserts every skill resolves an icon.\n- **Behavioral tests** live per category in `server/tests/nodes/test_<category>.py`, driven through `NodeTestHarness` ([server/tests/nodes/_harness.py](server/tests/nodes/_harness.py)) — it executes any node via `NodeExecutor` with mocked services and asserts the result envelope.\n- **Import sanity:** `uv run pytest --collect-only` (from `server/`) is the live plugin-count invariant — it fails if any plugin errors at import.\n- **Credential tests** follow the numbered-invariant style documented in [server/tests/credentials/README.md](server/tests/credentials/README.md).\n- **Temporal control tests** include real SDK workflows with stub Activities,\n worker restart, Continue-As-New and captured-history replay. Run the\n [control verification commands](docs-internal/temporal-workflow-control.md#verification-and-operations)\n when changing admission gates, root enrollment, event queues or messaging.\n Replay hooks must remain deterministic and unchanged while replaying.\n- Run everything: `uv run pytest` from `server/`, `bun run --filter react-flow-client test` from the repo root, `uv run pytest cli/tests` from the repo root.\n- **Desktop shell:** from `desktop/`, `bun run typecheck && bun run test && bun run test:invariants` (the last needs `bun run stage` first), and `bun run build && bun run test:e2e` for the Playwright Electron smoke. In an editor-hosted terminal unset `ELECTRON_RUN_AS_NODE` before launching Electron by hand.\n\n## Local Dev Quick Reference\n\nDevelopment 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`.\n\n```bash\nbun install # install workspace dependencies\nbun run dev # start the app (Vite HMR + backend; Temporal starts from the backend when TEMPORAL_ENABLED, WhatsApp only on demand)\nbun run stop # stop everything\nbun run build # production build\nbun run --filter react-flow-client typecheck # THE gate: TypeScript 7 (native Go). Same command CI runs.\nbun run --filter react-flow-client typecheck:tsc # second opinion under tsc 5.9 — for triaging a red gate, not a substitute\nuv run pytest # run backend tests (from server/, uv-managed venv)\n```\n\nThe desktop shell has its own package: `cd desktop && bun install && bun run stage && bun run dev` (see [desktop/README.md](desktop/README.md)). It is not a root workspace member, so root `bun install` does not touch it.\n\n`server/uv.lock` is committed. After changing `server/pyproject.toml`, run `uv lock` in `server/` and commit the lock too; CI fails with `uv lock --check` otherwise, and the desktop app installs from the lock with `--frozen`.\n\n**Known differences from pnpm** (the workspace migrated from pnpm@9 to [email protected]):\n\n- **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.\n- **Dependabot is disabled (no PRs of any kind).** Alerts still show in the Security tab; remediation is a hand bump, through the top-level `overrides` block in the root `package.json` for transitive JS pins (the pins formerly under `pnpm.overrides`) or `uv lock --upgrade-package` for the server. See [ci_cd.md](docs-internal/ci_cd.md) \"Dependency update policy\".\n- **`--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.\n\nFull setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.md](docs-internal/SCRIPTS.md)\n\n## Full Documentation Index\n\n| Document | Description |\n|---|---|\n| [DESIGN.md](docs-internal/DESIGN.md) | Execution engine architecture, design patterns, execution modes |\n| [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) | Distributed execution via Temporal activities |\n| [temporal-workflow-control.md](docs-internal/temporal-workflow-control.md) | Versioned Stop/drain/Resume, execution roots, messaging, event accumulation, compatibility and verification |\n| [chat_protocol.md](docs-internal/chat_protocol.md) | Tracked chat runs, controlled Stop/Resume, subscriptions, legacy Stop and watchdog behavior |\n| [workflow-schema.md](docs-internal/workflow-schema.md) | Workflow JSON schema and node catalog (live count = `len(services.node_registry.NODE_METADATA)` after importing `nodes`) |\n| [ROADMAP.md](docs-internal/ARCHIVE/ROADMAP.md) | *Archived* status snapshot; current state is in DESIGN.md and the Temporal docs |\n| [SETUP.md](docs-internal/SETUP.md) | Development environment setup |\n| [SCRIPTS.md](docs-internal/SCRIPTS.md) | bun/shell scripts and CLI verbs reference |\n| [server-readme.md](docs-internal/ARCHIVE/server-readme.md) | *Archived*; see SETUP.md, authentication.md, plugin_system.md |\n| [agent_architecture.md](docs-internal/agent_architecture.md) | AI Agent / Chat Agent skill and tool discovery |\n| [agent_delegation.md](docs-internal/agent_delegation.md) | How delegated agents share context and memory |\n| [agent_teams.md](docs-internal/agent_teams.md) | Agent Teams pattern with `input-teammates` handle |\n| [native_llm_sdk.md](docs-internal/native_llm_sdk.md) | Native LLM SDK layer and provider protocol |\n| [rlm_service.md](docs-internal/rlm_service.md) | Recursive Language Model agent via REPL |\n| [claude_code_agent.md](docs-internal/claude_code_agent.md) | Claude Code agent hub (routes to architecture, interactive mode, and the vendored `claude_code_*_reference.md` snapshots) |\n| [claude_code_agent_architecture.md](docs-internal/ARCHIVE/claude_code_agent_architecture.md) | *Archived* LangGraph-era design notes; see claude_code_interactive_mode.md |\n| [cli_agent_framework.md](docs-internal/cli_agent_framework.md) | Multi-provider CLI agent runtime (Claude Code / Codex / Gemini) — worktree isolation, MCP bridge, memory bridge |\n| [autonomous_agent_creation.md](docs-internal/ARCHIVE/autonomous_agent_creation.md) | *Archived* external research notes on Code Mode agents; the plugin is `server/nodes/agent/autonomous_agent/` |\n| [event_framework.md](docs-internal/event_framework.md) | Wave 12 event framework — Temporal Signals + Visibility routing, Search Attributes, plugin `_events.py` contract |\n| [stripe_service.md](docs-internal/stripe_service.md) | Reference Wave 12 plugin — signed webhooks + CLI-managed auth, file-by-file |\n| [vercel_service.md](docs-internal/vercel_service.md) | CLI-managed auth, device-flow variant |\n| [github_service.md](docs-internal/github_service.md) | gh CLI integration — CLI owns auth entirely |\n| [discord_service.md](docs-internal/discord_service.md) | Discord bot — gateway/REST split, multi-account on the credential `session_id` scope, Ed25519 interactions endpoint |\n| [event_waiter_system.md](docs-internal/event_waiter_system.md) | In-memory trigger waiters for the canvas-Run path (deployed triggers ride Temporal) |\n| [status_broadcaster.md](docs-internal/status_broadcaster.md) | WebSocket broadcaster (live handler count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`) |\n| [credentials_encryption.md](docs-internal/credentials_encryption.md) | Fernet + PBKDF2 credentials system |\n| [memory_compaction.md](docs-internal/memory_compaction.md) | Token tracking and model-aware compaction |\n| [pricing_service.md](docs-internal/pricing_service.md) | LLM and API cost tracking |\n| [proxy_service.md](docs-internal/proxy_service.md) | Residential proxy provider management |\n| [ci_cd.md](docs-internal/ci_cd.md) | GitHub Actions workflows |\n| [desktop_app.md](docs-internal/desktop_app.md) | Electron desktop shell: bundled runtimes, first-run provisioning, packaging, updates, CI |\n| [desktop_host_contract.md](docs-internal/desktop_host_contract.md) | The backend's side of being owned by a GUI shell: relocatable app root, readiness, watchdogs, shutdown route |\n| [node_creation.md](docs-internal/node_creation.md) | How to create new nodes |\n| [memory_lifecycle.md](docs-internal/ARCHIVE/memory_lifecycle.md) | *Archived* pre-RFC-0002 markdown memory model; see agent_context_flow.md and memory_compaction.md |\n| [tool_building_pipeline.md](docs-internal/tool_building_pipeline.md) | Canonical home for `_build_tool_from_node`, tool discovery, per-type Temporal dispatch |\n| [new_service_integration.md](docs-internal/ARCHIVE/new_service_integration.md) | *Archived* pre-Wave-11 integration guide; see node_creation.md and the OAuth recipe above |\n| [cli_services_integration.md](docs-internal/cli_services_integration.md) | CLI service lifecycle management |\n| [onboarding.md](docs-internal/onboarding.md) | Welcome wizard and replay |\n| [frontend_architecture.md](docs-internal/frontend_architecture.md) | Current frontend stack, token tiers, state-ownership boundary, strict styling rules |\n| [theme_system.md](docs-internal/theme_system.md) | The theme token contract + \"Adding a new theme\" checklist |\n| [workflow_ops_protocol.md](docs-internal/workflow_ops_protocol.md) | Backend → canvas mutation wire format (`{operations: [...]}`) |\n| [schema_source_of_truth_rfc.md](docs-internal/ARCHIVE/schema_source_of_truth_rfc.md) | *Archived* backend-as-SSOT RFC (shipped); see plugin_system.md |\n| [node_allowlist.md](docs-internal/node_allowlist.md) | Single-config UI visibility gating (`node_allowlist.json`) |\n| [authentication.md](docs-internal/authentication.md) | JWT/cookie auth — modes, middleware, frontend bootstrap |\n| [errors.md](docs-internal/errors.md) | Known errors and troubleshooting |\n| [performance.md](docs-internal/performance.md) | Cold-start measurements, optimisation history, anti-patterns |\n| [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) |\n| [Skill Creation Guide](server/skills/GUIDE.md) | How to create new skills |\n\n## Community\n\nJoin our [Discord](https://discord.gg/c9pCJ7d8Ce) for help, feedback, and updates.\n","archived":false,"sha256":"88ea6f72501f787883d241512e7063d117c4500c19329497452e6a70bef4fb2a"},"doc:desktop/README.md":{"id":"doc:desktop/README.md","path":"desktop/README.md","title":"OpenCompany desktop shell","content":"# OpenCompany desktop shell\n\nElectron host for the OpenCompany backend. It ships `uv`, a standalone\nPython and bun inside the installer (no Node, no npm), provisions the\nbackend's virtual environment in the user's data directory on first\nlaunch, spawns uvicorn, and shows the backend-served UI in a native window.\n\nFull documentation: [docs-internal/desktop_app.md](../docs-internal/desktop_app.md)\nand the backend contract in\n[docs-internal/desktop_host_contract.md](../docs-internal/desktop_host_contract.md).\n\n## Develop\n\nThis directory is a standalone bun package (not a workspace member).\n\n```bash\n# once, from the repo root: build the client + sidecar the shell serves\nbun install && bun run --filter react-flow-client build && bun run --filter opencompany-nodejs-executor build\n\ncd desktop\nbun install\nbun run stage # app-root + pinned runtimes for this machine -> stage/\nbun run dev # electron-vite dev (main/preload HMR, setup page HMR)\n```\n\nRun against the checkout without staging or provisioning:\n\n```bash\nOPENCOMPANY_DESKTOP_APP_ROOT=.. OPENCOMPANY_DESKTOP_VENV_PYTHON=../server/.venv/bin/python bun run dev\n```\n\n## Test\n\n```bash\nbun run typecheck\nbun run test # unit (vitest)\nbun run test:invariants # staged tree matches what the backend expects\nbun run build && bun run test:e2e # Playwright Electron smoke\n```\n\n## Package\n\n```bash\nbun run gen-icons\nbun run dist # installers -> release/\n```\n\nVersions of the bundled runtimes are pinned in `runtimes.json`.\n","archived":false,"sha256":"67df03e8b9f310d148734215cffe161f6d9665d9460afd7f62c3151ac5da568a"},"doc:docs/diagrams/README.md":{"id":"doc:docs/diagrams/README.md","path":"docs/diagrams/README.md","title":"Diagrams","content":"# Diagrams\n\nOne set, dark theme, all SVG. This folder is the only copy; nothing under\n`docs-internal/` vendors these files.\n\n**Overview diagrams** (linked from the README and CONTRIBUTING):\n\n- `how-it-works.svg`, `default-workflows.svg` (README)\n- `system-overview.svg`, `execution-flow.svg`, `ai-agent-routing.svg`, `node-anatomy.svg` (CONTRIBUTING)\n\n**Architecture and product-panel diagrams** (indexed in CONTRIBUTING under\n\"More Diagrams\"): `system-context`, `runtime-trust-topology`,\n`workflow-execution-routing`, `durable-deployment-events`,\n`plugin-agent-team-composition`, `persistence-secret-plane`,\n`workspace-anatomy`, `node-configuration-anatomy`, `credentials-architecture`,\n`team-operations`, `agent-context-memory`, `master-skill-editor`,\n`workspace-files`, `runtime-observability-dock`. Each file's `<desc>` lists\nthe source files it was drawn from.\n\nFacts on every diagram were checked against the code in September 2026.\nCounts come from the live registries (`len(NODE_METADATA)`,\n`len(CREDENTIAL_REGISTRY)`, `config/llm_defaults.json`), and ports are\nnamed by their `.env.template` variables rather than numbers.\n","archived":false,"sha256":"9ab3173a17c24c23703bbdf9624ed1967e63a13ff3761b7bb29ca0638dbde604"},"doc:docs/mobile-workspace.md":{"id":"doc:docs/mobile-workspace.md","path":"docs/mobile-workspace.md","title":"Mobile Workspace","content":"# Mobile Workspace\n\nMobile Workspace runs the open-source **mobile-use** agent against one persistent, local Android emulator. Mobile Agent and the Android tool are plugin nodes with a Workspace capability; its task execution uses the saved workflow, node configuration, and authenticated principal. The emulator belongs to the OpenCompany installation and is shared across Mobile nodes and workflows. Tasks queue for this device.\n\n## Supported deployment\n\nThe initial implementation supports **Android on a Windows host**. The OpenCompany backend, Android SDK, emulator, device broker, and mobile worker must run on the same host. A remote browser can display the Workspace, but does not supply the emulator. Only the installation owner can access Mobile Workspace.\n\niOS is not enabled. Future iOS support requires a same-host macOS backend and Apple's simulator tooling; installing this plugin on Windows does not provide an iOS simulator. Physical devices, remote device farms, multiple concurrent emulators, and distributed mobile workers are outside this implementation.\n\nThe runtime singleton and its leases are process-local. Run one backend process with its local Temporal activity worker; multiple API processes or an independently deployed Android activity worker do not share this device broker. Merely placing separate processes on the same machine does not make their runtime state shared. A future multiprocess deployment needs a dedicated broker service and explicit authenticated routing to it.\n\n## Setup and use\n\n1. Install `uv` for the optional Python environment and enable the host virtualization support required by Android Emulator. Setup downloads pinned Android command-line tools and a private Temurin Java runtime when needed. An existing SDK can be selected with `ANDROID_SDK_ROOT` or `ANDROID_HOME`; the standard Windows Android SDK location is also detected.\n2. Add **Mobile Agent** for direct tasks or employee delegation, or **Android** for an existing AI agent to call as a tool. Save the workflow and open **Workspace → Mobile**. The setup diagnostics inspect SDK tools, emulator acceleration, the system image, engine, and video server.\n3. Review and accept the Android SDK license in setup. Setup installs the optional engine and Android packages and creates the persistent `OpenCompany` AVD using a Pixel 7 device profile. Network access and sufficient disk space are required for these downloads.\n4. Click **Start phone** and wait for **Ready**. The emulator runs without a separate desktop window; the Workspace shows its video. Device storage persists across stopping and starting the emulator.\n5. Click **Use phone** to sign in to the Play Store, install applications, or upload an APK. APK uploads are limited to 256 MB and require the current manual-control lease. Play Store availability comes from the selected Google Play system image; account sign-in is performed on the device.\n6. Connect a provider in OpenCompany Settings, then choose a supported global model in the toolbar. Phone nodes use it by default. For an override, choose **Custom** under the node’s **Model selection**, or connect exactly one model to its **Model** input. Save the workflow. The resolved model is used for every mobile-use stage. OpenAI, Anthropic, and Gemini credentials are supported. Choose a model with image input and tool use, then enter a request under **Ask AI to use the phone** and click **Run task**, or call the node through its agent connection.\n\nThe setup is optional. Ordinary application startup does not install the mobile engine or boot an emulator. Runtime data lives under the configured OpenCompany data directory's `mobile` subdirectory, including the engine environment, AVD, and device resource metadata. Stopping the emulator does not reset its apps or account sessions.\n\nSetup shows the current component, download or SDK output, elapsed time, last update age, and recent activity. Complete compatible SDK packages are reused. Progress is saved in `mobile/setup-status.json`; reopening Workspace retains it. A backend shutdown or restart during setup is shown as interrupted with a retry action, rather than silently returning to idle. Retry reuses completed components; an incomplete download may need to restart. Setup does not continue while the backend is stopped. Timeout failures include the command and its latest output.\n\n## Choosing a node\n\n| Node | Use it for | Connection |\n| --- | --- | --- |\n| **Mobile Agent** (`mobile_use_agent`) | Direct Workspace requests or delegated phone tasks | Global model by default; optional **Model** override; **Delegate** output for employee delegation |\n| **Android** (`android_tool`) | Giving an existing AI agent a phone tool | **Tool** output into the agent’s **Tools** input; global model by default, with an optional **Model** override |\n\nBoth nodes use the same phone. Adding another node does not create another emulator. The existing `android_agent` and relay service nodes are separate integrations; they do not set up this local phone.\n\n## Everyday controls\n\nThe live phone fills the available Workspace height in normal view, inside a phone frame (a dark bezel) shaped by the screen's own width and height, so it turns when the phone rotates; wide panels have side bars. Above it the server says which phone it is (`status.device`, \"Pixel 7 · local emulator · up to 30 fps\", from `DEVICE_NAME` and `VIDEO_MAX_FPS` in `_install.py`, which also set the AVD profile and scrcpy's `max_fps`). Below it the device bar has **Back**, **Home**, **Recent apps** and **Rotate** (on its side, and back), each sent through `/input` and enabled while you use the phone, and **Screenshot to Canvas** where the employee has a Canvas: `POST /screenshot` saves the screen as a PNG in the workflow's workspace (`write_media`, a read that needs no control) and `canvas_add` puts it on the board.\n\nHome's **Take over** (in the Workspace footer) takes the phone's lease the way **Use phone** does, and stops the employee. **Hand back** releases the lease with `resume: true`, so a task waiting for you goes on; when this view no longer holds the lease (it was hidden meanwhile), `POST /resume` lets a waiting task go on without it. `/resume` is refused while someone uses the phone and does nothing when no task of that workflow waits: the phone is shared, so one employee's Hand back never lets another employee's task go on. Each action an AI task takes on the phone (\"Tapped the screen\", \"Went back\"; `TASK_STEPS` and `KEY_STEPS` in `_runtime.py`), and you taking the phone over and handing it back, adds a line to the employee's Workspace timeline on Home (`services/workspace_steps.py`); a line never holds typed text or what the screen showed. Expand **Ask AI to use the phone** to enter a task; collapsing it keeps your draft. The **Phone controls** toolbar toggle exposes Stop phone, refresh, APK installation while controlling the phone, completed setup history, and help. Status and takeover stay visible.\n\nChoose **Full view** in the toolbar to fill the screen. The task panel is hidden, and secondary controls remain available through the toolbar toggle. Controls stay outside the picture so they do not cover Android buttons. Use **Exit full view** or **Esc** to return. Entering full view keeps the current connection and does not restart the phone or grant manual control. Browser Workspace uses the same layout, with address and navigation under **Browser controls**. If the browser does not support fullscreen, use the existing Workspace expand button instead.\n\n| Label | Meaning |\n| --- | --- |\n| **Phone is off / Start phone** | The phone is installed but needs to be started before tasks can run. |\n| **Starting phone…** | Android and its automation connection are initializing. Wait for **Ready**. |\n| **Ready** | The phone can accept a task or manual control. |\n| **Use phone** | Pause AI control and use the screen yourself. |\n| **Finish using phone** | Release manual control without explicitly resuming a paused task. |\n| **Let AI continue** | Release manual control and resume a waiting task from the current screen. |\n| **AI is working** | An agent is using the shared phone. |\n| **Stop phone** | Shut down the phone while preserving apps and sign-ins. Cancel an active task first. |\n\nConnection warnings clear after a successful status check. Action errors have a **Dismiss** button. Task submission is disabled while the phone is off. Download details, completed setup history, and technical diagnostics are collapsed by default.\n\n## Model selection\n\nBoth Mobile Agent and Android use this order:\n\n1. A connected **Model** node overrides all node/global settings. Multiple connections or a disabled/invalid connector produce an error rather than falling back silently.\n2. With **Model selection = custom**, the saved phone provider/model is used. An empty model uses that provider’s configured default.\n3. With **Model selection = global** (the default), the current toolbar selection is read for every new task. Changing it applies to the next task, not a worker already running.\n\nThe selected model serves every mobile-use stage. OpenAI, Anthropic and Gemini are supported. An unsupported or missing global selection gives an actionable error; it never silently selects a different provider. Credentials always come from stored provider settings. Android’s AI-visible tool schema remains prompt-only, so an agent cannot override model selection or saved execution limits through tool arguments.\n\nGemini backend selection follows the main AI agent: Vertex AI Express credentials use Vertex, and Developer API credentials use the Gemini Developer API. The isolated phone worker receives an explicit backend setting derived from the stored credential; it does not inherit an unrelated host setting. Terminal events include `model_backend=vertex_express` or `model_backend=gemini_developer`, without printing the credential. A rejected Android tool result is shown as a failed node, even though the handled error is returned to its calling AI agent.\n\nOpenAI and Anthropic (Claude) use their own saved API credentials and official SDK endpoints by default. A saved OpenAI or Anthropic custom endpoint is passed unchanged to the phone engine, matching the main agent's provider configuration. All three model-selection modes support these providers. Choose a model that supports image input and tool use; a valid API key alone does not establish access to every model. Endpoint values and credentials are excluded from diagnostic logs. Client construction is verified with the installed engine SDKs; this does not constitute a live provider-generation test.\n\n## Runtime files and Git\n\n`mobile_root()` currently resolves a relative `DATA_DIR` against the backend process’s working directory. With source development launched from `server/` and `DATA_DIR=.opencompany`, the installed phone is therefore under `server/.opencompany/mobile/`. This differs from the application’s canonical repository-relative data resolver. An absolute `DATA_DIR` avoids this ambiguity. Do not move an existing installation or switch its data directory while the backend is running.\n\nThe repository ignores `server/.opencompany/`. Emulator disks, snapshots, downloaded dependencies and logs are runtime data, not source changes; deleting them is not Git cleanup. Preserve `avd/` to retain the phone’s apps and sign-ins. Test fixtures and research checkouts under `.tmp/` can be removed once their checks finish.\n\n## Control and task lifecycle\n\n### Android tool for AI agents\n\nAdd the **Android** tool node (`android_tool`) and connect its **Tool** output to an AI agent's **Tools** input. The tool follows the saved global model by default. Optionally choose a custom model in its settings or connect an OpenAI, Anthropic, or Gemini model node to Android’s **Model** input; a connected model takes priority. Save the workflow, then set up and start the phone in Workspace → Mobile. The agent calls `android` with one argument, `prompt`, such as “Open Settings and turn on dark mode.” The tool uses the same mobile-use engine, owner checks, task queue, manual takeover, and saved time/step limits as Mobile Agent. It does not install software or accept licenses automatically.\n\n### Troubleshooting and logs\n\nWorkspace shows plain-language phone status and clears connection warnings after a successful status check. **Use phone** enables manual interaction; **Let AI continue** returns control to a waiting task. Technical checks and recent events are under **Help & diagnostics**.\n\nOperational events are written to `mobile/mobile.log` relative to the active data directory, rotating at 1 MiB with three backups. They include startup, driver/video failures, task lifecycle and command durations. Errors include exception type, error code where available, and stack locations. Prompts, typed text, screenshots, credentials, and command parameters are excluded. Existing emulator output remains in `mobile/emulator.log`.\n\n| Symptom | Check or recovery |\n| --- | --- |\n| Setup appears slow | Expand download details and recent setup activity; large system images take time. Complete compatible SDK packages are reused. |\n| Setup interrupted after a backend restart | Use **Retry setup** after accepting the SDK terms. Completed components are reused; partial downloads may restart. |\n| Phone will not start | Open **Help & diagnostics** for the acceleration check, then inspect `mobile/mobile.log` and `mobile/emulator.log`. |\n| `readuntil() called while another coroutine is already waiting` during startup | Older code let status polling read the driver’s initialization pipe concurrently. The fix shares `driver_lock` across initialization and commands and skips geometry polling during lifecycle transitions. Restart the backend after updating. |\n| Phone works but an old error remains | Current UI clears recovered connection warnings; dismiss action errors. Refresh the frontend after updating. |\n| New Android node is absent | Restart the backend to register the plugin and refresh the frontend. Search for **Android**, type `android_tool`. |\n| Task asks for a model | Select a supported global model, choose a custom provider/model in the phone’s settings, or connect a model to the phone’s **Model** input. A parent agent’s separate custom model is not inherited automatically. |\n| Live view cannot connect | Check recent video events. Only one viewer is supported; close another preview and use **Reconnect**. |\n\n`setup-status.json` retains setup progress across backend restarts. Recent diagnostic events in status are bounded to 40 records in memory; `mobile.log` and its rotated backups retain operational history on disk. Logs exclude user content, but still include workflow/run identifiers: review them before sharing. The startup race explains a failed request and phone cleanup; it does not by itself prove a whole-backend crash.\n\nVideo is a read-only scrcpy transport. Mouse, touch, text, navigation, rotation, APK installation, and agent mutations go through the server's device-control broker rather than the video socket. The initial preview supports one browser tab at a time.\n\nTaking control revokes the agent's lease and capability before stopping its worker, then waits for an already admitted device mutation to drain. A monotonically increasing epoch rejects delayed inputs from an old controller. Operation identifiers deduplicate successful mutations within the current lease. An uncertain device failure fences control and requires recovery rather than replaying the mutation automatically.\n\nResuming starts a fresh agent worker against the current device state with a new capability. This is not continuation of an in-memory model conversation. The remaining active time and step budgets are carried forward. A task can wait for human control for up to 30 minutes. Cancelling a queued task prevents it from starting; cancelling a task while a person controls the device preserves that person's lease.\n\nWorkspace submissions use a client-generated submission UUID and a durable Temporal workflow identity scoped to principal, saved workflow, and node. Repeating a submission returns the existing task; reusing its UUID with a different prompt is rejected. Mobile task activities have automatic retries disabled. This is not a guarantee that arbitrary device actions are globally exactly-once across host failure.\n\n### Resetting phone tasks\n\nUse the workflow toolbar's **Reset** for phone tasks submitted through **Ask AI to use the phone**, as well as phone work invoked by the workflow. Direct Workspace submissions are tracked by a per-workflow Temporal `WorkspaceTaskControllerWorkflow`, so Reset is available even when the regular workflow has never started.\n\nReset blocks new Workspace submissions, cancels queued and running tasks for this workflow, and waits for cancellation and phone cleanup before reporting completion. Other workflows' phone tasks are unaffected. If cleanup or Temporal status is unavailable, Reset remains unconfirmed and can be retried; an already-ready workflow alone is not proof that its phone task stopped. The workflow remains stopped afterward.\n\nThe phone stays running, with its apps, sign-ins, and existing human-control lease preserved. Reset clears this workflow's task and activity panel and browser submission recovery IDs, then loads a fresh phone status. If you were controlling the phone, choose **Use phone** again to reconnect this view's manual controls. Completed task history remains in Temporal.\n\nAfter upgrading to this implementation, restart the backend and its Temporal worker so they register `WorkspaceTaskControllerWorkflow` and its cleanup activity. The process-local device broker still requires the backend and mobile activity worker to share the supported single-process deployment described above.\n\n## Engine isolation and credentials\n\nOpenCompany installs mobile-use into its own Python 3.12 environment. The main server does not import its agent dependencies. Each task receives a separate worker process; a trusted device process owns the explicitly selected emulator serial. The worker's injected controller talks to a loopback capability broker. It does not choose an ADB serial or receive an arbitrary host-command API.\n\nA maintained source patch injects the controller before mobile-use's normal device initialization and redirects screenshot and platform-helper calls. It blocks SDK-side app installation and disables dotenv loading. The patch fails closed when its expected source structure changes. The upstream SDK's cancellation method alone is not used as proof that device work has stopped.\n\nThe node resolves the selected provider's existing default-account credentials on the server and passes only that provider credential in the worker configuration. Credentials are not supplied by the browser and are not included in task status. Device processes receive a filtered environment. Agent telemetry and trace recording are disabled by this integration. Task screenshots and prompts still go to the configured model provider as part of inference. Custom provider base URLs are not currently exposed by the Mobile Agent configuration.\n\n## Dependency pins and attribution\n\nThe optional installer verifies downloaded artifacts before extraction or execution:\n\n| Component | Pin |\n| --- | --- |\n| mobile-use source | `62913c933e21b27da353a89316a09f60525af496` |\n| Source archive SHA-256 | `e2bac1f1d47e895d8c9ec840b0e896391ffd664ed2d4149a1ff1744252ca8384` |\n| Python dependencies | Upstream lockfile, installed with `uv sync --frozen --no-dev` |\n| scrcpy server | `4.1` |\n| scrcpy artifact SHA-256 | `deacb991ed2509715160ffdc7907e47b4160eb30d1566217e9047fd5b8850cae` |\n| Android command-line tools | Windows revision `15859902` |\n| Command-line tools SHA-256 | `90ae805d20434428bffcb699c290860f19bb5f66a67e6b330067e3de801fb04a` |\n| Private Java runtime | Temurin JRE Windows x64 `21.0.12.1+1` |\n| Java archive SHA-256 | `d35f31e712f0fcf6ac5a093edc90204fbff22f720ba3950bd09d331d5e621636` |\n| Android system image | `system-images;android-36;google_apis_playstore;x86_64` |\n\nThe Android package identifier selects an SDK package, not an immutable revision checksum. Updating the engine pin requires reviewing the patch, its bypass coverage, and the upstream lockfile together. Source archive extraction preserves upstream legal files; mobile-use is Apache-2.0 licensed, and its attribution and NOTICE must remain with redistribution.\n\n## Local integration versus Minitap services\n\n[mobile-use](https://github.com/minitap-ai/mobile-use) is the open-source Python agent and CLI reused here. The embedded preview, lease broker, takeover behavior, optional installation, and Workspace task routing are OpenCompany integration code.\n\nMinitap's [platform](https://www.minitap.ai/platform#slack-cli-mcp) and [miniTest documentation](https://www.minitap.ai/docs/minitest) describe separate hosted testing products, including managed runs and integrations. This local plugin does not automatically provide their device fleet, hosted test reports, Slack integration, or hosted MCP service, and does not require a Minitap account for local engine execution.\n\n## Validation and limitations\n\nAndroid tool calls publish live step counts and phases to the normal canvas node-status channel and Workspace's phone header, including calls made by another AI agent. These are internal phone steps; the parent agent advances its own turn when the tool finishes. Step counts retain the already-consumed budget after manual takeover/resume. Model waits are labelled separately from device work. The Android tool's registered `android-phone-skill` teaches goal-based calls, manual handoff, and error handling; existing workflows can add it through their Master Skill node, while new tool connections use the normal auto-add-skill policy.\n\nManual control avoids an extra geometry/status round trip after every input. Device geometry uses the automation server's current display dimensions, falling back to the SDK size query when missing; taps and swipes still validate current size and rotation before executing. Non-coordinate commands avoid unnecessary geometry reads, and status polling does not queue behind a busy driver. Device read/action timings remain in Terminal to distinguish device latency from model inference time. These changes do not eliminate the phone engine's multiple model calls per task.\n\nAndroid lifecycle and task events appear in the application's **Terminal** under source `mobile`, prefixed `Android:`. They are also retained in the bounded `mobile.log` and Workspace's recent phone activity. For task debugging, look for `engine_starting`, `engine_stage`, `engine_failed`, and `engine_exited`; correlate them by execution ID, run ID, workflow, and node. Model events include the selected provider/model and failures include the HTTP status and engine stage. HTTP 400 means the provider rejected the request, 401/403 indicates credentials or permissions, 404 indicates a missing model, 429 indicates quota/rate limits, and 5xx indicates a provider service failure. Invalid-key responses reported as HTTP 400 are classified as authentication failures.\n\nRaw engine stderr and provider response bodies are not forwarded because they can contain prompts, phone screenshots, or API keys. The structured worker protocol supplies diagnostic metadata instead. Earlier generic `ClientError` failures cannot be reconstructed from logs that discarded this metadata; restart the backend after updating, then retry the task to capture a diagnostic event. This logging does not include a continuous Android OS `logcat` stream.\n\nPhone startup first checks for an existing emulator. Recovery requires the console-reported AVD path to match this installation and the process to belong to its Android SDK. A process-wide device lock prevents two updated backends from owning the same writable phone. A disconnected automation driver can be restarted without launching a second emulator. Stop waits for the emulator and cleans up its owned child processes; it does not wipe phone data or stop unrelated emulators.\n\nIf startup fails, the message remains in Workspace after a refresh. A duplicate-AVD error means another emulator still holds the phone; if verified reconnection is unavailable, close that OpenCompany emulator and retry. Do not delete AVD lock files or use `-read-only` to bypass ownership. `emulator.log` retains launcher output and rotates to `emulator.previous.log` before a new launch when it exceeds 2 MiB. Error classification reads only the current attempt; `mobile.log` records recovery and boot-probe timeout events without model prompts or credentials.\n\nRun backend validation with a boolean `DEBUG` environment value (for example, `$env:DEBUG='false'` in PowerShell). Values such as `release` fail settings validation in subprocess tests. Source-boundary checks exclude installed runtime data in `.opencompany` and legacy `.machina`; the mobile engine runs in its own dependency environment. The Android tool intentionally receives canvas edges to resolve its connected model, and the device driver's JSON wire replies are protocol output rather than application logs.\n\nAutomated tests exercise fencing, successful-operation deduplication, cancellation while draining, takeover and resume with fake subprocesses, queued cancellation, source-patch compatibility, and Python syntax compilation of the patched upstream package. Additional tests use the actual loopback HTTP broker with a fake driver, reject unsafe archives and checksum mismatches, and verify that SDK tools run through Java arguments without a command shell. Patch tests require `.tmp/mobile-use-upstream` or `MOBILE_USE_UPSTREAM_SOURCE` pointing to the pinned checkout; they skip when that fixture is absent.\n\nAn earlier local smoke test executed `worker.main` profile construction, SDK initialization, a fake task, and cleanup using the actual pinned dependency environment in `.tmp/engine-smoke` and a fake controller. It made no model request and connected to no emulator.\n\nA separate Windows host check confirmed usable WHPX acceleration, a real Android boot, a 1080 × 2400 automation connection, and screenshot/UI inspection, followed by clean shutdown. That sequential check did not cover concurrent Workspace polling; dedicated regression tests now cover the startup race. The temporary smoke-test fixtures were removed after use.\n\nAutomated tests also cover the Android tool’s schema and saved execution limits, privacy-filtered bounded diagnostic logging, setup interruption recovery, and connection-warning recovery in the UI. These checks do not establish successful Play Store login, APK execution, live model inference, or a complete browser-video acceptance run. Validate those on a supported Windows host before treating this as production device automation. Current task results contain a response and run identity; the artifact list is empty, and hosted-style videos or reports are not generated.\n\n## Planned iOS implementation\n\nThis is an implementation plan, not currently supported functionality. Keep the Workspace capability, task submission, ownership checks, and lease protocol shared, and add platform-specific lifecycle, driver, installation, and video adapters.\n\n1. Add a macOS-only setup diagnostic for Xcode selection, accepted Apple licenses, installed simulator runtimes, and the chosen simulator device type. Setup must ask for the required Apple license acceptance and must not promise unattended Xcode installation.\n2. Create or select one managed simulator by persisted UDID using `xcrun simctl`; explicitly boot it, wait for readiness, and shut down only the simulator owned by this installation. Never infer the target from whichever simulator happens to be booted. Preserve simulator data across normal restarts.\n3. Implement an iOS driver in a separate trusted process on the same Mac. Evaluate and pin the upstream simulator controller's IDB companion requirements. Route its screenshots, hierarchy reads, gestures, text, app lifecycle, and platform helpers through the same lease checks as Android. Do not allow the agent worker to discover devices or spawn its own companion.\n4. Add a simulator video adapter with a defined framing and geometry contract. Android scrcpy is not an iOS transport. Validate encoding, browser decoding, rotation, coordinate scaling, disconnect cleanup, and backpressure on the supported macOS and browser versions before enabling live preview.\n5. Accept simulator-compatible application builds and install them through a lease-protected `simctl` operation. Do not describe arbitrary physical-device IPA files or iOS App Store installation as supported simulator workflows. Display platform-specific app prerequisites and controls.\n6. Extend the pinned upstream patch and smoke tests for the iOS context, then execute the acceptance matrix below on a real Mac. Keep the iOS Workspace entry disabled until the lifecycle, automation, and takeover checks pass together.\n\n## Acceptance matrix\n\n| Area | Automated coverage now | Required device acceptance |\n| --- | --- | --- |\n| Setup | Checksums, archive safety, license refusal, Java argument boundary | Clean Windows x64 setup, acceleration diagnostics, SDK download failure and retry |\n| Agent adapter | Pinned-source patch compilation and real-dependency fake-task smoke | Image-capable model completes a task through the broker |\n| Device lifecycle | Runtime tests use fake processes | Start, stop, crash, restart, persistent apps and session state |\n| Ownership | Lease fencing, drain, deduplication, queue cancellation, scoped identities | Two browser tabs, delayed input, takeover during a real device mutation |\n| Human resume | Fake subprocess termination and new capability | Agent resumes from the manually changed screen within remaining budgets |\n| Video and input | Transport code is separate from mutation broker | H.264 decoding, rotation, scaled pointer coordinates, typing, disconnect cleanup |\n| Android apps | APK admission and installation are broker-owned | Install a simulator-compatible APK; manually authenticate and install from Play Store |\n| iOS | Not implemented | Same-Mac lifecycle, IDB adapter, simulator app install, preview, gestures, fenced takeover |\n\nPassing a source or fake-process test does not count as passing the corresponding device acceptance check.\n\n\n### Live Android activity\n\nWorkspace shows the active phone task's model/provider, step budget, total elapsed time,\ncurrent phase duration, and time since the last reported activity. The main activity panel\nshows the SDK's subtask plan and current subtask, followed by the latest 40 plan/action\nupdates. Actions include the selected app or screen target, the SDK tool's explicit intent,\nduration, and confirmed tool outcome. A tool completing an action does not mark a subtask\ncomplete: subtask status comes from the SDK's planner/orchestrator updates. Interrupted\nactions whose outcomes were not confirmed are shown as unconfirmed.\n\nThe counter is labeled **Engine step** because it measures LangGraph execution steps,\nincluding planning and coordination, rather than taps or completed subtasks. Nested chain\ncallbacks and graph branches at the same step do not generate duplicate counter events.\nThe current subtask stays visible across model waits and device reads. A resumed worker\ncreates a fresh plan from the current screen; earlier activity remains in the timeline.\n\nA separate collapsed **Technical activity** section retains the latest 40 phase/device\nevents: model requests/responses, screen/accessibility-tree reads, and device operations.\nConsecutive identical phase messages are coalesced. Completed operations include duration.\nThe last task remains visible after completion, failure, or cancellation until another task\nruns; history is in memory and clears on restart. Older runs cannot recover details that\nwere not captured at the time.\n\nA 30-second quiet period shows a notice, not a claim that the engine is stuck. Use the last\nphase to distinguish a model wait from device I/O; take manual control using Use phone if needed.\nThe panel is outside the phone canvas and hidden in full-screen mode. Detailed summaries\nare bounded and available only through the owner-only mobile status response. They can\ncontain task-specific plan descriptions and screen labels. Typed tool payloads and input\ntools' echoed field contents are omitted, and URL strings are redacted. These summaries\nare not sent to diagnostic logs or the generic workflow status broadcast. Raw model\nresponses, provider thinking blocks, cumulative agent thoughts, screenshots, and injected\ngraph state are never forwarded to the activity panel.\n\nThis integration follows the SDK's [Agent configuration](https://www.minitap.ai/docs/mobile-use-sdk/sdk-reference/agent)\nand the pinned source's `AgentConfigBuilder.with_graph_config_callbacks(...)`: graph node\nresults expose `subgoal_plan`, and tool callbacks expose intent/arguments plus\n`Command.update.executor_messages` with `ToolMessage.status`. The SDK's internal\n`on_plan_changes` hook is not exposed by this pinned Agent configuration. No additional\nupstream patch or dependency is needed. [Local trace recording](https://www.minitap.ai/docs/mobile-use-sdk/core-concepts/observability)\nis a separate feature that creates screenshots and step artifacts; `record_trace=False`\nremains intentional for the live activity panel.\n\nRegression coverage includes callback filtering, SDK-shaped plans, tool error results,\ninput-content filtering, interruption, bounded histories, and preserving subtask context\nduring quiet waits. An optional test executes a mock graph with the installed pinned SDK\nand its real executor tool node, without a model request or device connection.\n","archived":false,"sha256":"e698228c4113c847b4a353b69c6cd83495c605bee24841a9c85a98c62c54f1df"},"doc:docs-internal/agent_architecture.md":{"id":"doc:docs-internal/agent_architecture.md","path":"docs-internal/agent_architecture.md","title":"AI Agent Architecture: Skill Injection & Tool Execution","content":"# AI Agent Architecture: Skill Injection & Tool Execution\n\nDetailed architecture reference for how AI Agent (`aiAgent`) and Chat Agent (`chatAgent`) discover skills and tools from connected nodes, inject them into the LLM prompt, and execute tools via the plain-async agent loop.\n\n> **Related Documentation:**\n> - [Node Creation Guide](./node_creation.md) - Canonical plugin recipe (covers tool nodes, dual-purpose nodes, specialized agents)\n> - [Tool Building Pipeline](./tool_building_pipeline.md) - Canonical home for `_build_tool_from_node`, tool discovery, per-type Temporal dispatch\n> - [Agent Context Flow](./agent_context_flow.md) - Canonical home for conversation continuity (RFC-0002 Context store). The retired markdown memory model is archived at [ARCHIVE/memory_lifecycle.md](./ARCHIVE/memory_lifecycle.md) and is not an SSOT for anything current.\n> - [CLAUDE.md](../CLAUDE.md) - Project overview and full node inventory\n> - [Pi Coding Agent](./pi_coding_agent.md) - SDK rounds coordinated through durable Temporal model/tool leaves\n\nNew `coding_agent` executions use `PiCodingAgentWorkflow`, including manual\ninvocation and delegated work. The SDK driver has isolated worker capacity and\nparks during child waits. Existing native generations and other agent types\nretain the execution paths described below.\n\n## Table of Contents\n\n1. [End-to-End Data Flow](#end-to-end-data-flow)\n2. [Agent Loop](#agent-loop)\n3. [Skill Injection Pipeline](#skill-injection-pipeline)\n4. [Tool Building Pipeline](#tool-building-pipeline)\n5. [Tool Execution and Dispatch](./tool_building_pipeline.md)\n6. [Context and Memory Integration](#context-and-memory-integration)\n7. [execute_agent vs execute_chat_agent](#execute_agent-vs-execute_chat_agent)\n\n---\n\n## End-to-End Data Flow\n\n### Browser AI Agent\n\n`browser_agent` inherits `SpecializedAgentBase`, standard parameters, provider\nselection/model inheritance, handles and the existing output envelope. It uses\nthe provider-neutral reasoning loop and its saved Browser tool; it does not\ninvoke Browser Use's Agent SDK. The private creation bundle is defined once\nin `services/browser_agent_recipe.py` and reused by canvas creation, Agent\nBuilder and new employee Browser capabilities.\n\nEmployee chat delegates through the ordinary delegation schema. Direct tasks\nare server-admitted Workspace invocations using the saved agent/tool binding:\n`WorkspaceTaskControllerWorkflow → NodeInvocationWorkflow → AgentWorkflow`.\nTheir submitted prompt is applied after saved/template preparation, preserving\nthe saved Browser system role. Their conversation is isolated from employee\nchat and deployed Context. A versioned native Workspace continuation permits\ngeneration-zero Continue-As-New without enrolling direct tasks in deployment\nStart/Stop/Resume. Cancel and Reset wait for owner cleanup; prepared tools,\npolicy and routing remain frozen across continuation.\n\nA stable task token holds the Browser profile during reasoning, tool calls\nand human assistance. Delegated agents have separate tokens. Both in-process\ntool adapters forward trusted Browser bindings and task identity. The saved\npolicy is tightened by trusted `interaction=read_only` restrictions, including\nAsk first; model arguments cannot relax it. The viewer remains attached to\nthe saved Browser tool, preserving takeover and the binary frame protocol.\n\n1Password values are resolved inside the calling model Activity or browser\nowner, never during catalogue reads or into Temporal inputs. Configured login\nuses private CDP only while browser-use is suspended and page/capture channels\nare gated; the model receives an opaque binding ID and safe status. Multi-step\nlogin, MFA and passkeys use human assistance. See\n[1Password credentials](./onepassword_credentials.md),\n[Browser workspace](./browser_workspace.md) and\n[Temporal control](./temporal-workflow-control.md).\n\n```\nUser clicks \"Run\" on AI Agent\n |\n v\nExecutionService.executeNodeViaWebSocket() client/src/services/executionService.ts\n Called from ParameterPanel.tsx:81\n Sends ALL workflow nodes + edges\n |\n v\nWebSocket: handle_execute_node() server/routers/websocket.py\n Passes nodes[], edges[] to WorkflowService\n |\n v\nWorkflowService.execute_node() server/services/workflow.py\n Builds context = {nodes, edges, session_id, workflow_id}\n Calls NodeExecutor.execute()\n |\n v\nNodeExecutor._dispatch() server/services/node_executor.py\n Plugin handler registry lookup (plain dict: self._handlers.get(node_type))\n Dispatches via BaseNode.execute() to the agent plugin's execute_op()\n (server/nodes/agent/<plugin>/__init__.py — Wave 11 deleted handle_ai_agent /\n handle_chat_agent; agent logic moved into the plugin folder)\n |\n v\ncollect_agent_connections() server/services/plugin/edge_walker.py\n (called by nodes/agent/_inline.prepare_agent_call)\n Scans edges where target == node_id\n Groups by targetHandle into 5 buckets (returns a 5-tuple\n context_data, skill_data, tool_data, input_data, task_data —\n edge_walker.py:181-199; the first element is the Context descriptor,\n or the legacy Memory descriptor on `input-memory` graphs):\n input-context -> context_data\n input-skill -> skill_data[]\n input-tools -> tool_data[]\n input-main / input-chat -> input_data\n input-task -> task_data\n |\n v\nAIService.execute_agent() / execute_chat_agent() server/services/ai.py\n 1. Inject personality-skill bodies into the system message\n (_build_skill_system_prompt -> services/skill_prompt.py); standard\n skills ride the Skill tool instead\n 2. Build provider-neutral AgentToolSpecs from tool_data\n 3. Call run_native_agent_loop(ChatUnifier, ...)\n 4. Save the conversation (Context store; legacy memory markdown\n only for `input-memory` graphs), return result\n |\n v\nrun_native_agent_loop() execution\n ChatUnifier -> native SDK -> if tool_calls: dispatch via tool_executor -> loop\n Return on final response (no tool_calls) or max_iterations cap.\n |\n v\nResult broadcast via WebSocket\n```\n\n### Key Files\n\n| File | Responsibility |\n|------|---------------|\n| `client/src/services/executionService.ts` | Frontend execution trigger, sends nodes + edges (`executeNodeViaWebSocket`, called from `ParameterPanel.tsx`) |\n| `server/routers/websocket.py` | WebSocket handler `handle_execute_node()` |\n| `server/services/workflow.py` | Facade, builds context, delegates to NodeExecutor |\n| `server/services/node_executor.py` | Plugin handler registry, plain dict dispatch (`self._handlers.get(node_type)`) |\n| `server/services/plugin/edge_walker.py` | `collect_agent_connections()` (the renamed `_collect_agent_connections`), `format_task_context()` |\n| `server/nodes/agent/_inline.py` | `prepare_agent_call()` — task-context injection + auto-prompt fallback + teammate collection; calls `collect_agent_connections` then `ai_service.execute_[chat_]agent` |\n| `server/nodes/agent/<plugin>/__init__.py` | Per-plugin `execute_op()` (Wave 11 replaced `handle_ai_agent` / `handle_chat_agent`) |\n| `server/services/ai.py` | `AIService` facade -- skill injection (`_build_skill_system_prompt`), tool building, context/memory and execution-boundary handling |\n| `server/services/skill_prompt.py` | `build_skill_system_prompt` -- the only skill-to-system-message path (personality bodies only) |\n| `server/services/agent_runtime.py` | `AgentToolSpec`, `run_native_llm_step`, and `run_native_agent_loop` |\n| `server/services/llm/` | `ChatUnifier`, provider-neutral messages/tool definitions, and native provider SDK adapters |\n| `server/services/handlers/tools.py` | `execute_tool()` -- dispatch router for all tool types |\n| `server/services/skill_loader.py` | `SkillLoader` -- filesystem/DB skill discovery and loading |\n\n---\n\n## Agent Loop\n\nThe agent loop is the plain async\n`services.agent_runtime.run_native_agent_loop`. No state machine or graph DSL\nis involved — each iteration:\n\n1. Optional `progress_callback(iteration)` so consumers (UI iteration badge) get a per-turn tick.\n2. `filter_empty_messages(messages)` strips empty native message content\n rejected by providers.\n3. `run_native_llm_step` calls `ChatUnifier.chat`, which invokes the selected\n native provider SDK and returns `LLMResponse`.\n4. The canonical `LLMResponse.assistant_message` is appended verbatim before\n any tool runs, preserving Gemini thought signatures, Anthropic\n signed/redacted thinking, and OpenAI continuation metadata. Normalized\n `Usage` is accumulated across iterations.\n5. Thinking text is accumulated across iterations with the\n `--- Iteration N ---` separator.\n6. If `response.tool_calls` is empty → return\n `{messages, iteration, thinking_content, truncated: False, usage,\n response}`.\n7. Otherwise validate each call against its `AgentToolSpec.args_schema`,\n dispatch it through `tool_executor`, and append a native\n `Message(role=\"tool\", tool_call_id=...)`. Malformed arguments become a\n deterministic tool error containing `raw_arguments` rather than crashing.\n An external tool's result text is cut to `tool_output_limit` characters\n before it is appended (see Signature below).\n Results containing workflow `operations` are passed to\n `rebind_from_operations`; returned `AgentToolSpec` values extend\n `current_tools` for the next request.\n\nOn hitting `max_iterations`, append a terminal native assistant `Message`\nwith a truncation note and return `truncated: True`.\n\n### Signature\n\n```python\nasync def run_native_agent_loop(\n chat_unifier,\n *,\n provider: str,\n api_key: str,\n model: str,\n temperature: float,\n max_tokens: int,\n initial_messages: Sequence[Message],\n thinking: Optional[ThinkingConfig] = None,\n tools: Optional[Sequence[AgentToolSpec]] = None,\n tool_executor: Optional[Callable[[str, Dict[str, Any]], Awaitable[Any]]] = None,\n max_iterations: int = 500,\n progress_callback: Optional[Callable[[int], Awaitable[Any]]] = None,\n rebind_from_operations: Optional[\n Callable[[List[Dict[str, Any]]], Awaitable[List[AgentToolSpec]]]\n ] = None,\n context_management: Optional[Dict[str, Any]] = None,\n compaction_pause_callback: Optional[\n Callable[[int, LLMResponse, List[Message]], Awaitable[Optional[List[Message]]]]\n ] = None,\n conversation_saver: Optional[Callable[[List[Message]], Awaitable[None]]] = None,\n tool_output_limit: Optional[int] = None,\n) -> Dict[str, Any]:\n \"\"\"Returns messages, iteration, thinking, truncation, usage, and response.\"\"\"\n```\n\n(`run_native_agent_loop` in `services/agent_runtime.py`.) `context_management`,\n`compaction_pause_callback` and `conversation_saver` are the RFC-0002 hooks:\n`context_management` is forwarded to the provider step (the Anthropic\ncompaction edit), `compaction_pause_callback` lets the caller swap the\nmessage list after a provider-side compaction pause, and `conversation_saver`\npersists the full transcript after every turn through the plain conversation\nstore (see [agent_context_flow.md](agent_context_flow.md)).\n`tool_output_limit` caps, in characters, what one external tool result adds\nto `messages` (`bound_tool_output` in `services/tool_output.py`; `None` or `0`\nkeeps results whole). Delegated-agent answers, skill loads and Task Manager\nresults are exempt (`tool_output_is_capped`). `execute_agent` /\n`execute_chat_agent` pass the resolved Tool Result Limit; see\n[agent_context_flow.md → Transcript size](agent_context_flow.md).\n\nThere is no mutable model binding step. Each native LLM request derives its\nprovider-facing declarations from the current `AgentToolSpec.definition`\nvalues. When a canvas-mutating tool returns workflow operations (today only\n`agentBuilder`), newly built specs extend that list and are visible on the\nnext iteration.\n\n### Termination\n\n| Trigger | What happens |\n|---|---|\n| LLM emits no `tool_calls` | Return with `truncated: False`. This is the normal exit. |\n| `finish_reason == \"compaction\"` with no `tool_calls` | **Not** an exit. Anthropic's durability pause returns only a compaction block; it has already been saved, so the loop calls `compaction_pause_callback` (when given, its non-`None` return replaces `messages`) and continues to the next iteration. |\n| `tool_executor` is `None` but LLM emits tool calls | WARN + return (treat as final). |\n| `iteration` reaches `max_iterations` | Append a synthetic native assistant `Message` + return with `truncated: True`. |\n\n### `max_iterations` precedence\n\nResolved per-execution, and the two runtimes differ. **Temporal** (`prepare_agent_payload`, `services/temporal/agent_activities.py`) applies tiers 1-3 below and falls back to a hardcoded 200 if `Settings` cannot instantiate; it never reads `llm_defaults.json`. **In-process** (`execute_agent` / `execute_chat_agent` in `services/ai.py`) applies tiers 2-4 through `get_model_registry().get_agent_defaults()`, where the env value wins and the JSON is the last resort; only tier 1 is unreachable there. Highest to lowest:\n\n1. **Per-agent-node** `parameters.max_iterations` — set by the user on the agent node itself. Temporal path only; no agent plugin currently declares a `max_iterations` Params field, so this tier is reachable only from a hand-written graph.\n2. **Per-user** `UserSettings.agent_recursion_limit` — Settings tab override (DB-backed).\n3. **Env** `Settings.agent_recursion_limit` from `AGENT_RECURSION_LIMIT` (default 200).\n4. **JSON** `llm_defaults.json:agent.recursion_limit` — in-process only, reached when `Settings` cannot instantiate; the Temporal path uses a hardcoded 200 instead.\n\nThe iteration limit is the termination backstop. Compaction is a post-turn\ncontext-pressure control (on the Temporal path for every agent, in-process for\nagents with connected memory); it summarizes active history so a loop can\ncontinue within the model's context window, but it does not decide when the\nloop terminates. Tool results are bounded separately, per call, by the Tool\nResult Limit. See [memory_compaction.md](memory_compaction.md) and\n[agent_context_flow.md → Transcript size](agent_context_flow.md).\n\n### Hot rebind after canvas mutation\n\nWhen `agentBuilder` (the only canvas-mutating tool today) adds a tool (`add_tool`) or a teammate (`add_subagent`) mid-run, it saves the change (`apply_graph_additions`) and returns the saved `workflow_ops` batch in its result's `operations` field. The loop detects the field, calls `rebind_from_operations(ops)`, and extends the bound tool surface so the LLM can invoke the new tool in the very next iteration — no Run-stop-Run cycle. A deployed run starts from the generation's frozen snapshot, so a tool saved in an earlier run can be missing from a later one; `add_tool` then returns that saved node alone (a bind-only batch, nothing saved) for the loop to bind. `add_skill` returns no operations: a skill is not bound as a tool, and a merge into an existing Skills node applies from the next run.\n\nClosure responsibilities:\n\n- **`_rebind_from_operations(ops) -> List[AgentToolSpec]`** (in\n `execute_agent` / `execute_chat_agent`): filter ops for `add_node` with the\n plugin class's `component_kind == \"tool\"` OR `usable_as_tool=True`\n (excluding `component_kind == \"model\"`, and the Skills node, whose\n `uiHints.isMasterSkillEditor` marks it: tool-kind, but it feeds\n `input-skill`), skip a node already bound, synthesize a `tool_info` dict,\n call `node_tools(self, tool_info)` (`services/agent_bindings.py`), and return the new specs. Tool\n configs get folded into the captured `tool_configs` dict so\n `tool_executor` can dispatch the new call.\n- The closure is gated on the user toggle: `UserSettings.auto_rebind_tools_after_canvas_change` (default `True`). When off, the LLM is told \"Available on your next turn\" in the operation summary and the closure isn't wired.\n\nFor the F4.B Temporal path, the closure is replaced by `agent.refresh_tools`.\nThe `agent-node-binding-refresh-v2` path passes bound node IDs, the run's graph,\nand parameter snapshot, then filters repeated node bindings. A distinct node\nthat would introduce a conflicting provider-visible tool name is rejected\nwith conflict details. Older histories preserve their recorded refresh path.\nVersion 1 preparation/refresh also records plugin Activity policies for each\nbound tool. See [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md).\n\n**A node that gives several tools.** A ToolNode may stand for several tools\n(`ToolNode.tool_bindings`, read from its settings: a custom MCP connector gives\none per remote tool it has on, see [MCP Connectors](mcp_connectors.md)). Every\nplace that builds an agent's tools goes through `node_tools`\n(`services/agent_bindings.py`). It returns the one tool\n`AIService._build_tool_from_node` builds, or one tool per `ToolBinding`, each\nnamed by its binding and run with the binding's settings over the node's. Each Temporal tool entry carries a\n`binding_key` (`<node id>:<key>`, or the node id for a single tool); behind\n`agent-tool-binding-key-v1` the workflow drops repeats by it instead of by\n`tool_node_id`, so the tools of one node are not collapsed into one. CLI agents\n(Claude Code, Codex) leave such a node out, and RLM refuses it.\n\n### Where it's called\n\nTwo callsites in `server/services/ai.py`:\n\n- `execute_agent` — for `aiAgent` plugins.\n- `execute_chat_agent` — for `chatAgent` + all specialized agents + team leads.\n\nBoth build native `initial_messages` (system, stored conversation history,\ncurrent prompt, and personality-skill injection), build tools via `_build_tool_from_node`, then call\n`run_native_agent_loop` and extract the final assistant message, accumulated\nthinking, usage, and iteration count from the returned dict.\n\n---\n\n## Skill Injection Pipeline\n\n### 1. Edge Scanning\n\nIn `collect_agent_connections()` (`server/services/plugin/edge_walker.py`; the renamed Wave-11 successor to `_collect_agent_connections` — the old `handlers/ai.py` was deleted), all edges targeting the agent node are scanned:\n\n```python\nfor edge in edges:\n if edge.get('target') != node_id:\n continue\n\n target_handle = edge.get('targetHandle')\n source_node_id = edge.get('source')\n\n if target_handle == 'input-skill':\n # Collect skill data...\n```\n\n### 2. Regular Skill Nodes\n\nFor standard skill nodes (claudeSkill, whatsappSkill, etc.), a single entry is created:\n\n```python\nskill_entry = {\n 'node_id': source_node_id,\n 'node_type': skill_type, # e.g., 'whatsappSkill'\n 'skill_name': skill_params.get('skill_name', skill_type),\n 'parameters': skill_params, # All node parameters from DB\n 'label': source_node.get('data', {}).get('label', skill_type)\n}\nskill_data.append(skill_entry)\n```\n\n### 3. Master Skill Expansion\n\nWhen the connected skill is a `masterSkill`, its `skills_config` parameter is\nexpanded into N individual entries. The expansion lives in the skill plugin\nfolder — `nodes/skill/_expander.py`, registered into the edge walker via\n`register_master_skill_expander` — so `edge_walker.py` carries no knowledge of\nthe Master Skill parameter shape:\n\n```python\n# nodes/skill/_expander.py\nskills_config = skill_params.get('skills_config', {})\n# Structure: {'whatsapp-skill': {'enabled': True, 'instructions': '...'}, ...}\n\nfor skill_key, skill_cfg in skills_config.items():\n if not skill_cfg.get('enabled', False):\n continue # Skip disabled skills\n\n skill_data.append({\n 'node_id': f\"{source_node_id}_{skill_key}\", # Unique composite ID\n 'master_skill_node_id': source_node_id,\n 'node_type': 'masterSkill',\n 'skill_name': skill_key, # snake_case is canonical; a\n # 'skillName' mirror is kept for\n # legacy readers\n 'description': metadata.description,\n # Customized instructions remain authoritative but are not put in\n # the initial prompt for standard skills.\n 'parameters': {'instructions': skill_cfg.get('instructions', '')},\n 'label': skill_key\n })\n```\n\nOne Master Skill node with 5 enabled skills produces 5 separate `skill_data` entries.\n\nStandard entries use progressive disclosure. They do not alter the agent system\nprompt. Their bounded name/description catalogue is carried by the dynamically\nbound provider-neutral `Skill` tool, using the same contract as other connected\ntool nodes.\n\nThe Assistant folder contains a required `skill` entry whose editable SKILL.md\nbody teaches use of that tool. Master Skill defaults and legacy expansion keep\nit enabled, so the row appears checked as **Skill** beside the other Assistant\nskills. This makes the usage prompt visible/configurable on the node instead of\nhardcoding it into every agent prompt.\n`Skill.load` returns authoritative instructions and a resource manifest;\n`read_resource` and `search_resource` provide bounded access to declared text\nfiles after loading. Personality skills are the sole eager-body exception.\nDuplicate enabled names across connected Master Skill nodes fail with\n`DUPLICATE_CONNECTED_SKILL_NAME` before the first model call.\n\nThe runtime revalidates the connected descriptor on each call, keys loaded-body\ndeduplication by workflow execution and agent, and emits sanitized CloudEvents\n`com.opencompany.agent.skill.loading|loaded|resource_read|failed|cleared`.\nOrdinary tools emit the parallel\n`com.opencompany.agent.tool.started|completed|failed` contract. `subject` and\n`data.author_node_id` both identify the exact invoking agent;\n`data.target_node_id` identifies only its connected capability node. Temporal\nevent IDs are deterministic per model tool call and lifecycle stage, and\nconsumers deduplicate by `(source, id)`. Bodies and resource contents appear\nonly in tool results, never status broadcasts.\nThe generic loop, chat/specialized-agent loop, RLM bridge, Claude/Codex native\nMCP bridge, and Temporal AgentWorkflow all emit the same parent-agent\ncapability phases. Consequently\nevery agent component renders `skill <name>` and `tool <name>` consistently;\nthis behavior is not owned by the team-lead implementation.\n\n### 4. SkillLoader Architecture\n\nDefined in `server/services/skill_loader.py:54+`:\n\n```\nSkillLoader\n├── _skill_dirs: [server/skills/, <cwd>/.machina/skills/, <cwd>/.opencompany/skills/]\n│ # _default_skill_dirs(), later dirs win\n├── _database # DI database singleton (user skills live in the DB)\n├── _registry: Dict[name -> SkillMetadata] # Metadata only (~100 tokens each)\n├── _cache: Dict[name -> Skill] # Full content (lazy-loaded)\n│\n├── scan_skills() # rglob(\"SKILL.md\") across all dirs, parses frontmatter\n├── load_skill(name) # Filesystem skills: cache -> registry -> SKILL.md\n├── load_skill_async(name) # DB-aware: filesystem first, then database.get_user_skill()\n├── get_registry_prompt() # \"## Available Skills\" text — DEAD: zero callers (see §5)\n└── get_skill_instructions()# Shortcut for load_skill().instructions\n```\n\n**`scan_skills()`** (`skill_loader.py:80-105`):\n- Iterates `_skill_dirs`, uses `rglob(\"SKILL.md\")` for recursive discovery\n- Parses YAML frontmatter for each file (`_parse_skill_metadata`)\n- Populates `_registry` with `SkillMetadata` (name, description, allowed_tools, path)\n\n**`load_skill(name)`** (`skill_loader.py:228-298`):\n1. Check `_cache` -- return immediately if cached\n2. Look up `_registry[name]` -- fail if not registered\n3. Read `SKILL.md`, strip frontmatter, extract markdown body as `instructions`\n4. Discover optional `scripts/` and `references/`; the Skill tool returns a\n manifest and reads their text separately rather than injecting them eagerly\n5. Cache and return `Skill` dataclass\n\n**`get_skill_loader()` is database-wired** (`skill_loader.py`):\n- The global loader is constructed with the DI `container.database()` (resolved lazily, late-bound on a subsequent call if the container was not yet ready when the loader was first requested). User-created skills are stored in the database rather than on disk, so the wired DB is what lets them resolve.\n- `load_skill_async(name)` is the DB-aware loader: filesystem `_registry` first, then `database.get_user_skill(name)`. The `get_skill_content` WebSocket handler and the agent skill paths call it, so database user skills load just like filesystem skills. `init_skill_loader(database=...)` remains available for explicit eager initialization.\n\n**SKILL.md frontmatter parsing** (`_parse_skill_metadata`, `skill_loader.py:144-227`):\n```yaml\n---\nname: http-skill # Lowercase with hyphens, validated by regex\ndescription: Make HTTP requests... # Brief description for LLM visibility\nallowed-tools: http-request # Space-delimited tool names\nmetadata:\n author: opencompany\n version: \"2.0\"\n---\n```\n\n### 5. System Message Injection\n\nThe only path from `skill_data` to the system message is\n`_build_skill_system_prompt` (module-level in `server/services/ai.py`), a thin\nwrapper that imports and calls `services/skill_prompt.py::build_skill_system_prompt`.\nIt is called from `execute_agent`, `execute_chat_agent`, the RLM service\n(`services/rlm/service.py`) and the Temporal `agent.prepare_payload` activity\n(`services/temporal/agent_activities.py`):\n\n```python\n# server/services/ai.py\ndef _build_skill_system_prompt(skill_data, log_prefix=\"[Agent]\") -> tuple:\n from services.skill_prompt import build_skill_system_prompt\n return build_skill_system_prompt(skill_data, log_prefix)\n\n# execute_agent / execute_chat_agent\nskill_prompt, has_personality = _build_skill_system_prompt(skill_data, log_prefix=\"[AIAgent]\")\n```\n\n`build_skill_system_prompt` walks `skill_data` and injects **only personality\nskills** (names ending in `-personality`) — their full SKILL.md\n`parameters.instructions` body is appended verbatim to the system message,\nand `has_personality=True` tells the caller to drop the default system\nmessage. Every other skill is counted and logged but contributes **nothing**\nto the prompt: standard skills reach the model through the dynamically bound\n`Skill` tool (name/description catalogue, `load` for the body,\n`read_resource` / `search_resource` for declared files), as described in §3.\n\n### 6. Registry prompt (unused)\n\n`SkillLoader.get_registry_prompt()` (`skill_loader.py:361-391`) still exists\nand renders a `## Available Skills` markdown listing (name, description,\n`- Tools:` line per skill), but it has **zero callers** in the codebase. No\nagent path appends a skill listing to the system message; the Skill tool's\ncatalogue replaced it. Treat the method as dead code — do not build new\nprompt features on it.\n\n### 7. allowed-tools\n\n- **Parsed** from SKILL.md frontmatter as a space-delimited list into `SkillMetadata.allowed_tools`\n- **Surfaced** to the model through the Skill tool's catalogue / `load` result (and the `listSkills` / `getSkill` MCP tools for CLI agents), not through the system message\n- **NOT enforced** in code -- the LLM can call any tool connected to `input-tools`\n- Purpose: guides the LLM on which tools are relevant to each skill; also drives palette icon/color resolution for SKILL.md entries (first tool in `allowed-tools`)\n\n---\n\n## Tool Building Pipeline\n\nTool building + dispatch lives in\n[tool_building_pipeline.md](./tool_building_pipeline.md). The five stages\n(DISCOVER edges → BUILD `AgentToolSpec` / `ToolDef` → EXPOSE through\n`ChatUnifier` → INVOKE via native tool calls → DISPATCH through\n`execute_tool`) and the dispatch matrix (delegated agents / Android services /\ndual-purpose plugins / direct tools / search APIs / generic fallback) are\ndocumented there. The single-source-of-truth rule — `execute_tool` owns the\ntool node lifecycle, parent-agent closures only emit phase broadcasts — is the\ncontract tests enforce.\n\nPatterns covered in the canonical doc:\n\n- Plugin `tool_name` / `tool_description` class variables and database\n overrides (node type → LLM-visible identity)\n- Database tool-schema override via ToolSchema model + Tool Schema Editor UI\n- Direct tool pattern (each Android service connects to the agent independently)\n- Direct Android service tools (16 entries, skip the toolkit)\n- Durable team delegation through Task Manager; `delegate_to_*` identities are\n retained internally for compatibility dispatch\n- Per-type Temporal activity dispatch (F4.A, when TEMPORAL_PER_TYPE_DISPATCH=true)\n- Auto-skill edges (writeTodos, WhatsApp tools bundle a default skill)\n\n---\n\n\n## Context and Memory Integration\n\nConversation continuity is the RFC-0002 Context store, documented in\n[agent_context_flow.md](./agent_context_flow.md) and\n[RFC-0002](../RFC-0002-AGENT-CONTEXT-AND-MEMORY.md). The agent reads\n`context_data` — the first element of the `collect_agent_connections()`\n5-tuple (`server/services/plugin/edge_walker.py:181-199`), populated from the\n`input-context` edge to a `context` node — and `AIService._prepare_context`\nresolves it into an `_AgentContextRuntime{key, history, database}`. Stored\nhistory is seeded into `initial_messages` (system messages filtered), the\nloop runs with `conversation_saver=runtime.save` so every turn persists the\nfull transcript, and nothing else about the request changes because a Context\nnode is attached.\n\n`simpleMemory` (\"Memory\") is **not** conversation history: it is a `ToolNode`\non `input-tools` that the agent calls explicitly (its `operation` argument\ntakes the `MemoryOperation` values in `server/nodes/tool/simple_memory/`:\n`remember` / `recall` / `list` / `get` / `update` / `forget`). The\n`input-memory` handle is retired — no agent declares\nit; `normalize_workflow_graph` rewrites legacy `simpleMemory -> input-memory`\nedges into a Context node plus an ordinary tool edge. The legacy markdown\nmemory path (`memory_data`, `parse_memory_markdown`,\n`append_to_memory_markdown`, `trim_markdown_window`, the vector store) is\nreached only for `input-memory` graphs: `execute_agent` passes the tuple's\nfirst element as `context_data` to `_prepare_context` and sets `memory_data =\nNone` whenever a Context runtime resolves (the `context_runtime is not None`\nbranch right after the `_prepare_context` call). Token tracking\nand compaction thresholds are in [memory_compaction.md](memory_compaction.md).\n\n---\n\n## execute_agent vs execute_chat_agent\n\nBoth methods live in `server/services/ai.py` and follow the same general pattern. Key differences:\n\n| Aspect | `execute_agent()` | `execute_chat_agent()` |\n|--------|-------------------|----------------------|\n| **Loop call** | Calls `run_native_agent_loop` with the resolved recursion limit | Calls `run_native_agent_loop` with the resolved recursion limit when tools exist and with `max_iterations=1` otherwise |\n| **Tool failure** | Callback re-raises; the shared loop serializes the exception into a native tool-result message | Callback returns `{\"error\": str(e)}`; the shared loop serializes that result into the same native tool-result shape |\n| **No-tool path** | The first native turn normally returns immediately | One native loop iteration through `ChatUnifier` |\n| **Result metadata** | `agent_type: \"agent\"` | `agent_type: \"chat\" / \"chat_with_skills\" / \"chat_with_tools\" / \"chat_with_skills_and_tools\"` |\n\n### Specialized Agent Routing\n\nThere is no hardcoded routing table for agents. Wave 11.C deleted the\n`SPECIALIZED_AGENT_TYPES → partial(handle_chat_agent, ...)` registry that\nnode_executor used to build by hand. Every agent variant is now a\nself-contained plugin folder under `server/nodes/agent/<plugin>/` whose\n`BaseNode` subclass registers itself into `services.node_registry`\n(`_HANDLER_REGISTRY`) at import time via `register_node(...)`. `NodeExecutor._dispatch()`\ndoes a single registry lookup — `self._handlers.get(node_type)` — and the\nplugin handler that won the merge runs the node's `@Operation(\"execute\")`\n`execute_op` method (`server/services/node_executor.py:_dispatch`,\n`_build_handler_registry`).\n\nEach agent's `execute_op` calls the matching `AIService` method:\n\n```python\n# server/nodes/agent/_specialized.py — every specialized agent + team lead\nfrom ._inline import prepare_agent_call\nkwargs = await prepare_agent_call(...) # collect_agent_connections + prompt/task prep\nresponse = await ai_service.execute_chat_agent(ctx.node_id, **kwargs)\n\n# server/nodes/agent/ai_agent/__init__.py -> ai_service.execute_agent(...)\n# server/nodes/agent/chat_agent/__init__.py -> ai_service.execute_chat_agent(...)\n# server/nodes/agent/rlm_agent/__init__.py -> ai_service.rlm_service.execute(...)\n# server/nodes/agent/claude_code_agent/__init__.py / codex_agent/__init__.py\n# -> AICliService (CLI agent runtime) via the plugin's own execute_op\n```\n\n`prepare_agent_call` (in `server/nodes/agent/_inline.py`) chooses\n`execute_agent` vs `execute_chat_agent` based on `self.type` and shapes the\nshared keyword bundle; `_specialized.py` is the single body shared by all\nchat-agent-path specialized agents. Glob `server/nodes/agent/` for the\nauthoritative agent list, or read `AI_AGENT_TYPES` in\n[`server/constants.py`](../server/constants.py) — do not hand-maintain a\ncount here. The frozenset currently spans: the two\nbase agents (`aiAgent`, `chatAgent`), the specialized agents\n(`android_agent`, `browser_agent`, `coding_agent`, `web_agent`, `task_agent`, `social_agent`,\n`travel_agent`, `tool_agent`, `productivity_agent`, `payments_agent`,\n`consumer_agent`, `autonomous_agent`), the 2 team leads\n(`orchestrator_agent`, `ai_employee`), the 2 CLI/REPL agents that bypass\nthe standard loop (`rlm_agent`, `claude_code_agent`). `codex_agent` is\na sibling plugin folder on the same CLI-agent path but is not in the\nfrozenset.\n\n### Temporal dispatch routing\n\nTwo settings flags route agent execution through different Temporal paths (see [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md) for the full matrix):\n\n| Flag | Off | On (default) |\n|---|---|---|\n| `TEMPORAL_PER_TYPE_DISPATCH` | Ordinary nodes use the legacy `execute_node_activity` dispatcher (WS round-trip); enabled agent child-Workflow routing still takes precedence for supported types. | Ordinary nodes use per-type `node.{type}.v{version}` Activities registered by `BaseNode.as_activity()`. Graph dispatch honors plugin retry/queue; Workspace-task patches and version 1 agent-tool dispatch also use plugin timeout/heartbeat. |\n| `TEMPORAL_AGENT_WORKFLOW_ENABLED` | Supported agents run the in-process loop inside a node Activity: per-type when per-type dispatch is on, otherwise the legacy single dispatcher. | Types in `AGENT_WORKFLOW_TYPES` become **child Workflows** (`AgentWorkflow`). LLM steps and ordinary tools are Activities; preparation resolves configuration and explicit refresh binds canvas changes. `rlm_agent` and `claude_code_agent` remain whole-node Activities. |\n\nBoth flags default to `true` in `.env.template`; the starter freezes their\nvalues and the worker-pool routing flag into each execution's input.\n\nDistributed Browser bindings additionally freeze an owner-specific queue.\nThat queue applies to Browser Activities even when worker pools are disabled;\ngeneric orchestration workers cannot execute them. Direct `browser_agent`\nWorkspace tasks use the versioned native child path described above, while\nolder Workspace submissions retain their recorded single-Activity path.\n\n`AgentWorkflow` executions carry messages in the single `MessageWire` shape;\nthere is one engine and one wire standard, with no `llm_engine` or\n`message_wire_version` discriminator recorded (locked by\n`tests/llm/test_single_wire_standard.py`). Native executions never fall back\nafter a provider request starts, and changing the environment does not alter an\nexecution whose `agent.prepare_payload` result is already in history.\n\n### Version 1 cooperative Stop and Resume\n\nNew generation manifests enable `execution_control_version=1`, separately\nfrom the dispatch flags. Workflow gates close before model requests, tools,\ncompaction, explicit binding refresh, polling fetches, and child starts. Stop\ndrains already-admitted parallel work and its normal result bookkeeping;\nunstarted actions wait. If a recorded response requested A and B, stopping\nduring A retains A's result and leaves B pending. Resume continues with B,\npreserving the current model response and transcript.\n\nThe controller tracks graph/cron/job roots and detached delegation runners\nthat can outlive their parent. Attached agent descendants are discovered by\nnative execution descriptions after their child-start acknowledgement fence.\nCompleted Updates acknowledge admission closure and drain; Queries report\nstate. Resume holds producers while descendants/roots are released, then\nreleases controller, local, and schedule producers. Revision and chain checks\nprevent stale intent or reused Workflow IDs from controlling another execution.\n\nAt clean continue-as-new boundaries, version 1 carries prepared configuration,\nresolved tools and plugin timeout/retry/heartbeat/queue declarations, transcript,\nthinking, iteration, usage, execution identity, and control state. A stopped\nagent parks before rollover. The complete encoded next input is checked against\n1,900,000 bytes; an oversized continuation raises `AgentContinuationTooLarge`\ninstead of returning to the opening prompt. Old generations retain their\nlegacy command paths and capacity fallback for replay compatibility.\n\nUnlimited transient LLM retries can keep a Stop in `pausing`. A tool's retry\nand idempotency contract still governs effects lost before recorded completion.\nOpaque CLI/REPL/managed-agent nodes stop after the whole Activity settles;\nheartbeats do not checkpoint their internal sessions. Direct Workspace tasks\nand separately approved sends retain independent ownership. See\n[Temporal workflow control](temporal-workflow-control.md) for lifecycle/API\ndetails and [Temporal architecture](TEMPORAL_ARCHITECTURE.md#cooperative-generation-stop-and-resume)\nfor accounting, topology, and continuation.\n\n**Team leads** (`orchestrator_agent`, `ai_employee`) share the supported agent\nruntime and add an `input-teammates` handle. Connected agents become authorized\nTask Manager assignees via `collect_teammate_connections()` (in\n`server/services/plugin/edge_walker.py`, called from\n`server/nodes/agent/_inline.py:prepare_agent_call`). See [agent_teams.md](agent_teams.md).\n\n### RLM Agent Pattern\n\n`rlm_agent` replaces the standard tool-calling loop with a Python REPL executing LM calls recursively. Instead of paying one network round-trip per tool call, the RLM agent writes a code block that orchestrates many model invocations at once:\n\n```python\n# The LLM generates code like this, executed by RLMService\nresults = [llm_query(f\"summarize: {url}\") for url in urls]\nbest = rlm_query(f\"pick the most relevant: {results}\")\nFINAL(best)\n```\n\nExposed helpers inside the REPL:\n\n| Helper | Purpose |\n|---|---|\n| `llm_query(prompt)` | Call the small model connected to `input-model` |\n| `rlm_query(prompt)` | Recursively invoke the same RLM agent |\n| `FINAL(answer)` | Signal completion and return the final answer |\n\nRouting: `rlm_agent` is a plugin folder like every other agent. Its\n`execute_op` (`server/nodes/agent/rlm_agent/__init__.py`) delegates to\n`ai_service.rlm_service.execute(...)` rather than `run_native_agent_loop`. See\n[rlm_service.md](rlm_service.md) for full details.\n\n### Chat Agent Conditional Loop\n\n```python\n# In execute_chat_agent():\nif all_tools:\n final_state = await run_native_agent_loop(\n self.chat_unifier,\n provider=provider,\n api_key=api_key,\n model=model,\n temperature=temperature,\n max_tokens=max_tokens,\n initial_messages=messages,\n tools=all_tools,\n tool_executor=chat_tool_executor,\n max_iterations=recursion_limit,\n )\nelse:\n final_state = await run_native_agent_loop(\n self.chat_unifier,\n provider=provider,\n api_key=api_key,\n model=model,\n temperature=temperature,\n max_tokens=max_tokens,\n initial_messages=messages,\n max_iterations=1,\n )\n```\n\nThe no-tool path uses the same native step contract but is explicitly bounded\nto one iteration.\n\n---\n\n## AI Agent vs Chat Agent (Zeenie)\n\n`aiAgent` and `chatAgent` (display name \"Zeenie\") are near-identical in\ncapability — both run `run_native_agent_loop` through `ChatUnifier`, support\ncontext / skills / tools / task input, and can delegate asynchronously. The\ndifferences are which backend method they call and the softness of callback\nerror handling.\n\n| Feature | AI Agent (`aiAgent`) | Zeenie (`chatAgent`) |\n|---------|----------------------|----------------------|\n| Tool Calling | Yes (agent loop) | Yes (agent loop) |\n| Memory Support | Yes | Yes |\n| Skill Support | Yes | Yes |\n| Task Input | Yes (`input-task`) | Yes (`input-task`) |\n| Bottom Handles | Skill, Tools | Skill, Tools |\n| Left Handles | Input, Context, Task | Input, Context, Task |\n| Backend Method | `execute_agent()` | `execute_chat_agent()` |\n| No-tool path | Native loop returns after the first final response | Native loop is bounded to one iteration |\n| Tool-failure handling | Callback re-raises; loop creates an error tool-result message | Callback returns `{\"error\": str(e)}`; loop creates the tool-result message |\n| Async Delegation | Yes (fire-and-forget) | Yes (fire-and-forget) |\n\nSee the full method comparison in [execute_agent vs execute_chat_agent](#execute_agent-vs-execute_chat_agent) above.\n\n---\n\n## Agent Input Methods\n\nBoth agents resolve their prompt the same way (logic in `server/nodes/agent/_inline.py:prepare_agent_call`):\n\n1. **Template Variable (Explicit)** — set the Prompt field to a template like `{{chatTrigger.message}}` or `{{whatsappReceive.text}}`.\n - Templates are resolved by `ParameterResolver` before the plugin's `execute_op` runs.\n - Supports nested paths: `{{nodeName.nested.field}}`.\n\n2. **Auto-Fallback (Implicit)** — leave the Prompt field empty (`prepare_agent_call` Step 2, lines ~85-93):\n - When `not parameters.get(\"prompt\") and input_data`, the agent reads the output of the node wired to its `input-main` / `input-chat` handle (`input_data`, surfaced by `collect_agent_connections`).\n - Extraction order: `input_data[\"message\"]` → `input_data[\"text\"]` → `input_data[\"content\"]` → `str(input_data)` (whole-output fallback).\n\n**Task-context injection (Step 1)** runs before the prompt fallback: when an `input-task` edge supplies `task_data`, `format_task_context(task_data)` is prepended to the prompt. Tools are deliberately **kept**: the injected guidance tells a lead to `list_tasks` / `accept_task` / `reassign_task`, which needs the Task Manager tool (`nodes/agent/_inline.py` module docstring). The only agent that strips tools on task completion is `rlm_agent` (`nodes/agent/rlm_agent/__init__.py`, status in `(\"completed\", \"error\")`).\n\n**Example workflow:**\n```\nChat Trigger → Zeenie ← HTTP Skill (SKILL.md context)\n ← HTTP Request (tool node)\n```\nZeenie loads SKILL.md instructions from connected skill nodes, builds\n`AgentToolSpec` values from connected tool nodes (httpRequest,\ncalculatorTool, …), and uses `run_native_agent_loop` for LLM execution.\n\n---\n\n## Handle Topology\n\nHandle layouts are declared in `server/nodes/agent/_handles.py` (local to `nodes/agent/`, not a global lookup). Two layouts cover every agent variant (glob `server/nodes/agent/` for the live count):\n\n**`std_agent_handles()`** — shared by every agent variant except the two team leads:\n\n| Handle | Kind | Position | Offset | Role |\n|---|---|---|---|---|\n| `input-skill` | input | bottom | 25% | skill |\n| `input-tools` | input | bottom | 75% | tools |\n| `input-main` | input | left | 25% | main |\n| `input-context` | input | left | 50% | context |\n| `input-task` | input | left | 75% | task |\n| `output-main` | output | right | 50% | main |\n| `output-top` | output | top | — | main |\n\n**`team_lead_agent_handles()`** — `orchestrator_agent` and `ai_employee` only; adds an `input-teammates` handle (bottom, 80%) and shifts the bottom skill/tool offsets to 20%/50%. Connected agents become authorized Task Manager assignees via `collect_teammate_connections()` (in `server/services/plugin/edge_walker.py`); their delegate identities are hidden from the model and retained for trusted child dispatch. See [agent_teams.md](agent_teams.md).\n\n`AIAgentNode.tsx` is type-agnostic: it calls `useNodeSpec(type)` and renders whatever handles / icon / color the spec returns — there is no `AGENT_CONFIGS` map (retired Wave 10.D). Specialized-agent visuals all come from the NodeSpec; per-type display name / subtitle / description live on the plugin class, icon from `<plugin>/icon.svg` (visuals.json emoji fallback), color from `<plugin>/meta.json`. Glob `server/nodes/agent/` for the authoritative agent list — do not hand-maintain one.\n\n---\n\n## Async Agent Delegation (overview)\n\nAI Agents delegate to other agents wired to their `input-tools` handle, enabling hierarchical agent trees. There are two execution paths depending on whether the parent runs under Temporal F4.B:\n\n- **F4.B (default, `TEMPORAL_AGENT_WORKFLOW_ENABLED=true`)**: direct non-team delegation starts attached `AgentWorkflow` children when the target type is supported. Parent identity mirrors progress and per-invocation `{task, context}` wins over saved configuration. The deterministic child ID includes parent Workflow ID, child node ID, iteration, and call index. Team leads use Task Manager instead: assignment persists, a detached `DelegatedTaskWorkflow` owns the permit and attached child, and the lead receives `queued` without waiting. Version 1 detached runners independently enroll with generation control; attached children are controlled through the native parent tree.\n- **Legacy / F4.A-only**: fire-and-forget via `asyncio.create_task`. Still the path for `rlm_agent` / `claude_code_agent` (excluded from `AGENT_WORKFLOW_TYPES`) and any deployment with `TEMPORAL_AGENT_WORKFLOW_ENABLED=false`. The `delegate_to_*` tool spawns the child as a background task and returns immediately with `{\"status\": \"delegated\", \"task_id\": \"...\"}`; the parent keeps working while the child executes independently and broadcasts its own status (executing / success / error).\n\nDesign decisions (legacy path): **memory isolation** (child uses its own connected memory, not the parent's), **error isolation** (child errors are logged + broadcast, never propagated to the parent), **task tracking** (background tasks live in `_delegated_tasks`, cleaned up on completion).\n\nKey files: `server/services/ai.py` (`DelegateToAgentSchema` in `_get_tool_schema()`, injects `ai_service` / `database` / `nodes` / `edges` into tool config), `server/services/handlers/tools.py` (`_execute_delegated_agent()`, `get_delegated_task_status()`). Full plumbing — memory / parameter / execution-context flow — is in [agent_delegation.md](agent_delegation.md); the multi-agent team-lead variant is in [agent_teams.md](agent_teams.md).\n\n\n## Multimodal tool results\n\nA tool result may opt into vision by including `llm_media: [{\"ref\": <FileRef\nkind=image>, \"detail\": \"auto\"}]` next to its normal payload. The agent loop\n(`agent_runtime.py`) and the Temporal activity path (`agent_activities.py`)\nattach ref-only image blocks to the tool message; `run_native_llm_step`\nhydrates them per provider call, gated by `provider_supports_vision` (unknown\nproviders degrade to a text placeholder, so non-vision models keep working\nunchanged). Producers today: the `dataSource` image tier. For text-only host\nmodels the `visionAnalyze` delegate tool provides image understanding\ninstead. Details: [native_llm_sdk.md](native_llm_sdk.md) and\n[data_node.md](data_node.md).\n","archived":false,"sha256":"770e0c19453d4491f57583f50d962226901e994c82e2341b489af982933cb65d"},"doc:docs-internal/agent_context_flow.md":{"id":"doc:docs-internal/agent_context_flow.md","path":"docs-internal/agent_context_flow.md","title":"Agent Context & Team Continuity Flow","content":"# Agent Context & Team Continuity Flow\n\nNormative reference for how an agent's conversation survives across firings,\ndelegations, and rollovers — on both execution paths. Read this before\ntouching `services/agent_context/`, `nodes/context/`,\n`services/cli_agent/context_bridge.py`, `agent.prepare_payload`,\n`agent.execute_llm_step`, or the team-completion event chain. The invariants\nat the bottom are the \"do not break\" contract; several were learned from a\nproduction regression documented at the end.\n\nCompanion documents: [RFC-0002](../RFC-0002-AGENT-CONTEXT-AND-MEMORY.md)\n(design rationale for Context vs Memory), [agent_teams.md](./agent_teams.md)\n(team-lead contract), [TEMPORAL_ARCHITECTURE.md](./TEMPORAL_ARCHITECTURE.md)\n(execution engine).\n\n## The one-paragraph model\n\nContext is **plain JSON messages**. One table, `agent_conversations`, keyed\nby **`(workflow_id, generation, agent_node_id)`** → `messages` (a JSON list\nof `MessageWire` dicts) + `updated_at`. A fresh firing **loads** the row at start and\n**saves** the whole live message list back after every turn. Every firing of\nan agent — chat messages AND taskTrigger completion reviews — continues the\none conversation; a workflow Reset admits a new generation, which is a new\nkey, which is a fresh conversation. The connected Context node is the\nopt-in switch and the viewing panel, nothing more. This is the industry\npattern (LangGraph `thread_id`, OpenAI `conversation_id`, Claude Code\nsession files): a conversation id maps to a message list, and nothing else.\n\nThe conversation store adds no threads, sessions, epochs, checkpoint tables,\nblobs, or operation IDs. Temporal control revisions and suspended continuations\nlive in Workflow history and serve a separate execution contract.\nMemory (`simpleMemory`) is an ordinary tool — explicit\nremember/recall — and plays no automatic part in continuity.\n\nThe [Pi Coding Agent](./pi_coding_agent.md) stores immutable SDK snapshots and\nlarge operation receipts as execution caches. These are outside the conversation\nstore and have no mutable conversation head. A snapshot is usable only when\nits canonical projection/configuration matches the authoritative MessageWire;\nbranching, compaction and Reset rebuild the derived session as needed.\n\n## The store (`services/agent_context/`)\n\n| Function | Contract |\n|---|---|\n| `load_conversation(db, *, workflow_id, generation, agent_node_id) → List[Dict]` | The stored wires, `[]` when the key has no row. |\n| `save_conversation(db, *, …, messages)` | Whole-list upsert under a per-key asyncio lock; stamps each message with a `ts` (UTC ISO — kept for the unchanged prefix, minted for the appended turn, view-only: `message_from_wire` ignores it); notifies listeners **after** the commit. |\n| `clear_conversation(db, *, workflow_id, generation=None, agent_node_id=None) → int` | Deletes rows, optionally narrowed; returns the count. |\n| `list_conversations(db, *, workflow_id)` | Panel metadata (`generation`, `agent_node_id`, `message_count`, `updated_at`), newest generation first. |\n\n`listeners.py` carries `register_conversation_listener` /\n`notify_conversation_saved`. The store never imports `nodes/`; the Context\nplugin registers its `context.updated` broadcaster from\n`nodes/context/__init__.py` — same layering as the other plugin registries.\n\n## Full loop: chat → assign → child completes → review continues (Temporal path)\n\n```mermaid\nsequenceDiagram\n autonumber\n participant User\n participant CT as chatTrigger firing\n participant AW as Lead AgentWorkflow\n participant PP as agent.prepare_payload\n participant CS as agent_conversations<br/>(wf, gen, lead-node)\n participant LS as agent.execute_llm_step\n participant DTW as DelegatedTaskWorkflow\n participant TT as taskTrigger firing\n\n User->>CT: message\n CT->>AW: spawn lead run\n AW->>PP: prepare payload\n PP->>CS: load_conversation(key)\n CS-->>PP: stored wires (or [])\n PP-->>AW: payload + conversation + conversation_key\n Note over AW: messages = system + stored (non-system)<br/>+ THIS firing's prompt last\n AW->>LS: iterate\n LS->>CS: save_conversation([...sent, assistant])<br/>per turn, best-effort\n AW->>DTW: task_manager assign\n DTW-->>TT: task_completed event\n TT->>AW: spawn review firing (same workflow generation)\n AW->>PP: prepare payload\n PP->>CS: load_conversation(SAME key)\n CS-->>AW: full prior conversation\n Note over AW: lead remembers its plan →<br/>accepts, assigns next work, finish_team\n```\n\nThe review firing works **because the key is the same**: same workflow, same\ngeneration, same lead agent node. No event routing, session lifting, or\nthread resolution is involved — there is nothing to route.\n\n## Message seeding: what a run's initial `messages` list is\n\n```mermaid\nflowchart TD\n R[AgentWorkflow run start] --> P{resume marker has<br/>carried transcript?}\n P -- \"yes (continue-as-new)\" --> C1[\"messages = carried transcript verbatim<br/>(version 1 guards the complete continuation input)\"]\n P -- no --> Q{payload carries a stored<br/>conversation? (Context node,<br/>generation > 0, non-empty row)}\n Q -- yes --> C2[\"system (this firing's)<br/>+ stored wires minus system messages<br/>+ THIS firing's user prompt last\"]\n Q -- no --> C3[\"bare build:<br/>system + memory markdown (legacy) + prompt\"]\n```\n\nPrecedence is exactly **carried transcript > stored conversation > bare\nbuild** and is intentional:\n\n- A rollover resumes the *same application execution* mid-flight with a new\n Temporal Run ID — the live transcript is the truth and wins over store reads.\n- A fresh firing with a Context node continues the *conversation* — the\n stored row is the truth.\n- The bare build is the cold-start floor.\n\nVersion 1 generations carry the prepared payload and resolved tools along with\nthe transcript. `AgentWorkflow` restores these values and skips\n`agent.prepare_payload` on continuation, preserving provider/model, tool\ndefinitions, plugin Activity policies, and explicit in-run binding changes.\nConfiguration edited during a pause or restart cannot reconstruct a different\ncontinuation. Iteration, usage, context usage, thinking, application execution\nidentity, and control revision/hold state are carried too.\n\nRollover happens at a completed-turn boundary without live child handles or\nTask Manager tasks. A stopped agent waits there for Resume and for control\nhandlers to finish. Existing result relief and compaction bound the transcript;\nthe payload converter then measures the **whole next input** against\n`_CAN_INPUT_MAX_BYTES` (1,900,000 bytes). If it still cannot fit, version 1\nraises non-retryable `AgentContinuationTooLarge`. It never drops the transcript\nor repeats the opening prompt. The graph and prepared binding set count toward\nthis limit, so transcript size alone cannot establish that rollover will fit.\n\nLegacy generations retain their recorded path: `agent.prepare_payload` runs\nagain at rollover and can resolve current configuration; a carried transcript\nover `_CAN_TRANSCRIPT_MAX_BYTES` (1,000,000 bytes) is dropped with a warning,\nthen seeding falls back to the stored row or opening prompt. A stored row over\nthe seed cap can still raise `ConversationTooLarge`. These behaviors remain\nfor replay compatibility and are not the version 1 continuation contract.\nSee [Temporal architecture → Agent continuation](TEMPORAL_ARCHITECTURE.md#agent-continuation-under-history-pressure)\nand [Temporal Continue-As-New](https://docs.temporal.io/design-patterns/continue-as-new).\n\n### Stopped turns and unanswered calls\n\nFor a chat run owned by a version 1 generation, Stop suspends the generation\nafter admitted Activities and their result bookkeeping finish. An admitted\nLLM step completes under its existing retry policy, and its exact assistant\nmessage and pending tool calls stay in the existing Workflow continuation.\nAn admitted tool's result is consumed normally; unstarted tools wait for\nResume and are not replaced by synthetic \"not run\" results. Stop does not\nterminalize the reply, release its lane, or start a fresh firing. The watchdog\ndoes not expire an intentionally stopped controlled run by age; Resume gives\nit a fresh timeout window. See [Chat Protocol → Streaming, steps and Stop](./chat_protocol.md#streaming-steps-and-stop)\nand [Temporal workflow control](./temporal-workflow-control.md).\n\nLegacy/uncontrolled chat Stop keeps the terminal cooperative-stop behavior:\nthe LLM step saves the sent list and any partial answer (text metadata\n`{\"stopped\": true}`), and an unstarted tool receives a \"not run\" result.\nThe legacy grace-period watchdog can cancel an unfinished run. A cancellation\nor other terminal interruption while a tool runs can leave calls without\nresults, which no provider will continue from. A later fresh load therefore\npasses the stored row through `close_unanswered_tool_calls`\n(`services/agent_context/conversation.py`), which answers each open call of the\nlatest assistant turn with `UNANSWERED_TOOL_RESULT`, after the results the turn\nalready has. A closed conversation is returned unchanged. This repair applies\nto a stored row loaded for a new firing; it is not the checkpoint or Resume\nmechanism for a suspended version 1 agent.\n\n### Chat branches rewind and restore\n\nEditing the owner's message, trying an answer again or switching to another\nversion of the chat changes what the agent should remember\n([Chat Protocol → Branches](./chat_protocol.md#branches)). When a chat run's\nagent is prepared, `agent.prepare_payload` records on the run where the stored\nconversation stood (`chat_runs.context_cursors`: its length and a digest that\nleaves out the `ts` stamps), the stored row as loaded, before\n`close_unanswered_tool_calls`. A branch move then writes the conversation\ndirectly, under `conversation_lock` (the lock `save_conversation` holds) and\ninside the move's reserved transaction: back to the cursor of the first run on\nthe part of the chat being left (refused when the stored row no longer starts\nwith what the cursor recorded, as after a compaction), or, for a switch, to the\nconversation kept for the branch moved to (`chat_branch_snapshots`). Turns other\nfirings added after that point go with the branch. The Context listeners hear\nof each conversation changed, as after a save.\n\n## Transcript size: capped results, cleared old results\n\nThe transcript is the `agent.execute_llm_step` input on every turn and the\nrow the next firing seeds from, so its size is bounded in bytes, not only in\ntokens (the failure this prevents is `errors.md` #28: uncapped tool results\ngrew a saved row past the 1 MB seed cap and every later firing failed).\n\n- **Tool results are capped before they enter the transcript.** Each\n external tool result is cut to `tool_result_max_chars` characters (per-user\n Settings > Tool Result Limit, else env `TOOL_RESULT_MAX_CHARS`, default\n 100,000) with a note telling the model to call the tool again with narrower\n parameters (`services/tool_output.py`). Delegated agents' answers, skill\n loads and Task Manager results are never cut. Both paths apply it: the\n workflow right after `_serialise_tool_result`, the in-process loop in\n `run_native_agent_loop`.\n- **Old results are cleared past a byte budget** (Temporal path).\n `agent.prepare_payload` records `transcript_budget_bytes` (three quarters of\n `TEMPORAL_PAYLOAD_WARN_BYTES`). After each tool turn over that budget,\n results from earlier turns become a short placeholder, oldest first and\n external tools first, down to half the budget. Each keeps its\n `tool_call_id` and `name`, so every call still has its answer. The saved\n conversation holds the placeholder too, and the store re-stamps that\n message's `ts` when it changes. If the latest turn alone still overflows,\n its external results are cut to one shared length\n (`services/temporal/agent_context_pressure.py`).\n- **The rules are selected by the recorded payload.** `agent.prepare_payload`\n also records `context_pressure_version` and `tool_result_max_chars`; a run\n recorded before those keys existed replays the original rules (no cap,\n cumulative token gate, whole-transcript summary), because the rules decide\n which activities are scheduled. Any change to them needs a new version.\n\n## Compaction: one system prompt, summary as a user message\n\nVersion 1 summarizes when the next request (the last request's\n`total_tokens`, which every provider fills with the whole prompt including\ncache reads, plus what the turn added) reaches the threshold, or when the\nearlier turns alone keep the transcript over its byte budget. It sends\n`agent.compact_context` only the turns before the latest one and swaps\n`messages` for `[original system (verbatim), user(\"## Compacted\nconversation summary\" + summary + current request), latest turn verbatim]`:\nthe latest turn's tool results have not been read yet, so summarizing them\nwould lose what the model just asked for. With nothing older than the latest\nturn, it skips (a summary of the opening alone gains nothing). Runs recorded\nbefore version 1 keep the original rule: summarize everything when the\nrunning sum of every step's usage crosses the threshold. Two rules are\nload-bearing (locked by\n`TestConversationIdentity::test_compaction_preserves_the_system_prompt_and_summary_survival`):\n\n- **The system prompt is never modified or duplicated.** It is the agent's\n contract (personality + tool/delegation guidance) and must stay\n byte-stable — for provider prompt caching, and because the next firing's\n seeding drops stored system messages so policy changes take effect.\n Anything compaction stores under the system role therefore silently\n vanishes on the next firing; that is exactly how an earlier\n second-system-message design lost the summary on the next chat message\n while the noisy tool tail (non-system) outlived it.\n- **The summary rides a user message**, so the compacted knowledge persists\n through seeding and crosses firings with the conversation it summarizes.\n\nTool calls/results from the summarized turns are dropped from the live list\nat the swap; they survive only inside the summary text. Tool messages that\nappear *after* the summary in the panel are the kept latest turn or **new\nwork the agent did post-compaction**, not survivors of the summarized turns.\nThe trigger (projected tokens against the threshold, transcript bytes against\nthe budget), the applied swap (before → after counts, summary size, kept\nmessages), each clear and each cut log at INFO, as does the activity\n(rendered chars in, summary chars + summarizer usage out). A summarizer\nfailure after the activity's retries is terminal for the run\n(`CompactionError`), not best-effort: past that point the transcript could\nonly grow until the provider rejected it.\n\n- **Load failures raise.** `agent.prepare_payload` raises\n `ApplicationError(\"ConversationLoadFailed\")` (retryable) when the row\n cannot be read, and `ApplicationError(\"ConversationTooLarge\")`\n (non-retryable, `_SEED_TRANSCRIPT_MAX_BYTES` = 1 MB; the message sends the\n user to the Context panel and the Tool Result Limit) when it is oversized.\n Running on silently instead would burn tokens on an amnesiac prompt — the\n exact failure mode this design replaced. With the cap and the byte budget\n above, new transcripts stay far below the limit; a row saved before them\n needs one clear. Both error types and the 1 MB cap exist only on the\n Temporal path. The in-process `_prepare_context` (`services/ai.py`) and\n `SpecializedAgentContextBridge.resolve` also refuse to run after a failed\n load, but raise a plain `ValueError`, and they load a row of any size.\n- **Save failures warn and continue.** The save happens *after* the\n provider was called and billed, so raising there would fail a completed\n turn over a bookkeeping write. `_save_conversation`\n (`agent_activities.py`), the loop's `save_now()` (`agent_runtime.py`),\n and every specialized-provider `record_turn` call site swallow and log.\n `_save_conversation` also logs a WARNING when a saved row passes half of\n `_SEED_TRANSCRIPT_MAX_BYTES`, while the next firing can still load it.\n\n## Both execution paths, one contract\n\n| Path | Load | Save |\n|---|---|---|\n| Temporal (`AgentWorkflow`) | `agent.prepare_payload` loads and returns `conversation` + `conversation_key` | `agent.execute_llm_step` saves `[...sent, assistant]` after each provider call |\n| In-process (`services/ai.py`) | `_prepare_context` builds `_AgentContextRuntime{key, history, database}` | the loop's `conversation_saver=runtime.save` fires after each assistant append and after tool results |\n| Specialized providers (claude_code / codex / rlm) | `SpecializedAgentContextBridge.resolve` loads; `augment_prompt` renders the transcript into the prompt | `record_turn(original_prompt, response)` appends and saves — always the **original** prompt, never the augmented one, or the save nests the transcript inside itself |\n\nThe opt-in gate is identical everywhere: the edge-walker descriptor's\n`kind == \"context\"` plus an admitted `generation > 0` (manual canvas Runs\npersist nothing by design — only Start admits a generation).\n\nFor claude, the session-pool key is the conversation key\n(`(workflow_id, agent_node_id, generation)` — `bridge.pool_key`), so a\nReset's generation bump automatically fences warm subprocesses at `acquire`\ntime, and a same-generation panel Clear terminates them explicitly\n(`ClaudeSessionPool.terminate_conversations`).\n\n## The Context node and panel\n\n`nodes/context/` owns the opt-in descriptor (`_descriptor.py`), two WS\nhandlers (`get_agent_context` returns the **live generation only** —\n`{conversations, generation, agent_node_id, updated_at, message_count,\nmessages}`, where `messages` is the requested `agent_node_id`'s transcript,\nelse the newest row's; `clear_agent_context` deletes rows and fences warm\nclaude processes), and one CloudEvents broadcast (`context.updated`, fired from the\nregistered save listener; payload is identity + count only — the panel\nrefetches through the authorized handler). Both ways of forgetting share\n`_handlers.forget_conversations` (delete, fence warm claude processes,\nannounce). The plugin also registers `on_chat_cleared` with\n`services/chat_thread.register_chat_cleared_listener`: when the owner clears\na workflow's chat (`clear_chat_messages` → `clear_chat_session`), every\nconversation of that workflow goes too, so the agent starts over with the\nchat. A Reset forgets them through the node's `reset_execution_state`, and\nclears the chat thread through the chat nodes' own Reset hook. The node declares **no\nparameters**; the connection is the whole configuration.\n\nThe node is optional and user-owned. `normalize_workflow_graph` never\ncreates, reconnects or deletes one; rewriting a legacy\n`simpleMemory -> input-memory` edge is the one exception. Save never restores\na deleted Context, and `workflow_validator` accepts an agent without one: it\nchecks only the Context edges that exist (`INVALID_CONTEXT_EDGE`,\n`MULTIPLE_CONTEXTS`, `SHARED_CONTEXT`), and `handle_save_workflow` refuses a\ngraph with any of them (`invalid_context_topology`). A Context node therefore\nserves exactly one agent. A leftover `simpleMemory -> input-memory` edge only\nproduces a `LEGACY_MEMORY_EDGE` warning. Deleting the node is the opt-out.\n\n**Known gap: the panel is not narrowed to its own agent.** `get_agent_context`\nlists every stored conversation in the workflow's live generation, not only\nthe one for the agent wired to this Context node. In a workflow with two\nagents, each on its own Context node, each panel lists both agents in its\nselector and opens on the newest row, which can be the other agent's; the\nbadge shows whose conversation it is. Clearing from the panel clears the\nagent currently shown.\n\nThe panel ([`ContextPanel.tsx`](../client/src/components/parameterPanel/ContextPanel.tsx))\nrenders role-tinted message cards with per-message `ts` timestamps, routes\nJSON-shaped payloads (tool calls, tool results) through the themed JSON\ntree on the per-theme `--code-*` surface, and offers a **Raw** tab showing\nthe stored wires verbatim. It declares `refetchOnMount: 'always'` because\nthe app's global `refetchOnMount: false` default would render stale cache\nwhen the panel opens after a run that mutated the conversation while no\nobserver was mounted.\n\n**Reset wipes.** `AgentContextNode.reset_execution_state` clears every\nstored conversation for the workflow, terminates warm claude subprocesses\nholding the wiped transcript, and broadcasts `context.updated` so open\npanels refresh. The generation bump alone is NOT enough: the panel shows\nthe newest STORED generation, so surviving rows would keep rendering the\npre-Reset conversation as the live context and Reset would look like a\nno-op. A plain Stop → Start (new generation without Reset) leaves prior\nrows in the store as inert history — deliberately **not browsable from\nthe panel**, which shows only the agent's current context — until Reset\nruns or the archive-outbox drain in `services/workflow_storage/handlers.py`\nclears them. The drain runs when the workflow is deleted AND when a save\nremoves a Context node, and it clears every stored conversation of the\nworkflow, not only the removed Context's agent.\n\n## Invariants (do not break)\n\n| # | Invariant | Why |\n|---|---|---|\n| 1 | The store observes; it never steers. Requests are always built from `messages`; `conversation_key` only says where to save. | The original `context_ref` regression made attaching a Context node change what the agent sent. |\n| 2 | One key per agent per generation: `(workflow_id, generation, agent_node_id)`. Every firing — chat or task review — continues that one conversation. | Per-firing/per-session keys are how the lead came back amnesiac (`messages=2`). |\n| 3 | Seeding precedence: carried transcript > stored conversation > bare build. | Rollover mid-run truth beats the store; the store beats cold start. |\n| 4 | Load failures are LOUD (`ConversationLoadFailed` / `ConversationTooLarge` on Temporal; a `ValueError` on the in-process and specialized paths, which have no size cap); save failures are best-effort. | Never burn tokens on an amnesiac prompt; never fail a billed turn over bookkeeping. |\n| 5 | Save the exact sent list, after the provider call. Nothing writes to the store before a request exists. | The journal's `prepare_context` wrote fabricated requests assembled from configuration. |\n| 6 | Reset = new generation = new key, AND the Context node's reset hook clears the workflow's stored rows. | The panel shows the newest stored generation, so surviving rows make Reset look like a no-op. |\n| 7 | `input-memory` is retired; the conversation store is the continuity carrier. Do not resurrect markdown seeding. | `normalize_workflow_graph` migrates it away and the validator warns on any left (`LEGACY_MEMORY_EDGE`); two carriers would drift. |\n| 8 | Specialized bridges record the ORIGINAL prompt, never the augmented one. | Recording the rendered transcript nests the conversation inside itself and grows without bound. |\n| 9 | The store never imports `nodes/`; the plugin registers its broadcaster via `register_conversation_listener`, and a listener failure can never fail a save. | Same layering rule as every plugin registry; a UI notification must not break execution. |\n| 10 | External tool results are capped before they enter the transcript; the latest turn is never cleared or summarized; the pressure rules are chosen by the recorded `context_pressure_version`. | Uncapped results bricked every later firing (`errors.md` #28); an unread turn summarized away loses what the model asked for; a replay must schedule the commands it recorded. |\n| 11 | Version 1 Stop retains the live continuation and drains admitted results; a new stored-row load repairs calls left open by terminal interruptions. Legacy Stop saves the partial turn. | Suspension must preserve pending calls, while a later fresh firing must not send an unanswered-call conversation to the provider. |\n| 12 | Only `save_conversation` and a chat branch move (under `conversation_lock`, checked against the run's cursor) rewrite a stored conversation. | A move that ignored the lock or the cursor would cut a turn being saved, or cut a summarized conversation at the wrong place. |\n\n## How this broke (August 2026 regression), and why the journal went away\n\nSymptom: a team lead re-invoked by a `taskTrigger` completion started at\n`messages=2`, accepted the task, and returned — \"forgot its plan\" — after a\nContext node was added.\n\nThe original carrier was an append-only **journal** (7 tables: threads,\nhash-chained events, checkpoints, blobs, provider bindings, epochs) with\nper-firing operation ids and session/task/execution thread resolution. It\nfailed twice in the same direction: the Temporal path was write-only (fresh\nfirings never read the journal back), and completion firings resolved a\ndifferent thread than the chat that started the work. Both were patched —\nand the patched system still carried thread routing, epoch fencing, and\nreconstruction machinery whose only job was to approximate \"one agent, one\nconversation\".\n\nThe replacement makes that property structural instead of routed: the\nconversation key **is** workflow + generation + agent node, so a firing\ncannot land in the wrong conversation because there is no resolution step\nto get wrong. When an agent \"ignores\" its guidance, check what its\n`messages` list actually contained first.\n","archived":false,"sha256":"88bbebca164da78840310e6085d51c4da2be1981bfbf7e480b23974dd2c10a21"},"doc:docs-internal/agent_delegation.md":{"id":"doc:docs-internal/agent_delegation.md","path":"docs-internal/agent_delegation.md","title":"Agent-to-Agent Delegation (Nested Agents)","content":"# Agent-to-Agent Delegation (Nested Agents)\n\n> **Team-lead contract:** Orchestrator and AI Employee models do not call\n> `delegate_to_*` directly. They create durable work through the intrinsic\n> `task_manager(assign_task)` interface described in\n> [agent_teams.md](agent_teams.md). Delegate names below are internal dispatch\n> identities or legacy/non-team-lead compatibility mechanics.\n\nHow memory, parameters, and execution context flow when one AI agent delegates work to another agent connected as a tool.\n\n> **Related docs:** [tool_building_pipeline.md](./tool_building_pipeline.md)\n> for the underlying `_build_tool_from_node` + `execute_tool` pipeline that\n> backs `delegate_to_*` (delegation tools use the same provider-neutral\n> `AgentToolSpec` / `ToolDef` construction path as other AI tools — what makes\n> them special is the fire-and-forget background task and the\n> `{\"status\": \"delegated\"}` lifecycle opt-out documented there).\n\n## Overview\n\nAI Agents can delegate tasks to other agents connected to their `input-tools` handle. The parent agent's LLM decides when to call the child agent by invoking a `delegate_to_<agent>` tool.\n\n**Two execution paths** depending on whether the parent is running under Temporal F4.B:\n\n- **F4.B (default, `TEMPORAL_AGENT_WORKFLOW_ENABLED=true`):** Task Manager assignment persists first, then `AgentWorkflow` starts a detached **`DelegatedTaskWorkflow`** with `ParentClosePolicy.ABANDON` and immediately returns `queued` to the lead. The runner owns the root-wide permit, task claim, child `AgentWorkflow`, compact result/usage persistence, `taskTrigger`, and permit release. The LLM's `{task, context}` args travel as `child_context[\"invocation\"]`; `prepare_agent_payload` applies them after stored config resolution, so saved defaults cannot override the mission. Parent identity still travels in `parent_node_id` for status mirroring. Completion starts a separately scoped lead review instead of blocking the assigning invocation — see [TEMPORAL_ARCHITECTURE.md §F4.B](./TEMPORAL_ARCHITECTURE.md#agent-as-child-workflow-f4b).\n- **Legacy / F4.A-only:** the rest of this doc. `_execute_delegated_agent` spawns the child as an independent `asyncio.Task` and the parent continues working immediately — the **fire-and-forget** pattern. Applies the same task/context semantics by overwriting `child_params` AFTER loading them from the DB. Still the path for `rlm_agent` / `claude_code_agent` (excluded from `AGENT_WORKFLOW_TYPES`) and any deployment with F4.B disabled.\n\nIn both paths the parent passes only a `task` string and optional `context` string — per-invocation input that always wins over stored configuration. Everything else -- the child's provider, model, memory, skills, and tools -- comes from the child's own configuration and workflow connections.\n\n## Generation Stop/Resume ownership\n\nThe F4.B path has two lifetimes. Direct non-team delegation starts an attached\n`AgentWorkflow` child and collects its result through the existing child\nhandle. Task Manager assignment starts a detached `DelegatedTaskWorkflow`\nrunner with `ParentClosePolicy.ABANDON`; the runner can outlive the assigning\nlead and owns its attached agent child, permit, and terminal bookkeeping.\nNative parent discovery alone cannot find the runner after the lead closes.\n\nFor new `execution_control_version=1` generations, every detached runner\nenrolls with the existing generation controller through an acknowledged Update\nbefore admitting business work. The maintenance Activity/client bridge returns\ncurrent pause/revision/hold posture so a late runner cannot bypass Stop.\nAttached agent children inherit the scope and require no separate registration.\nThe controller's independent-root map and membership epoch survive rollover;\ncontrol checks the execution chain while addressing the current Workflow ID.\n\nStop closes admission throughout the discovered topology before waiting for\nadmitted Activities and result bookkeeping to drain. A child-start gate counts\nonly until start acknowledgement, enabling reliable native enumeration. A\nparent waiting for child completion or a runner waiting for a subagent permit\ndoes not hold the local drain count; its child is acknowledged separately.\nStopped children therefore do not deadlock a parent's checkpoint. Completion\npersistence and permit cleanup for work already completed still run normally.\nNo task is cancelled or re-queued merely because its generation is stopped.\n\nResume publishes a newer revision with producers held, releases descendants and\nregistered roots, reconciles membership, and releases controller/local/schedule\nproducers. It uses existing handles and pending continuations rather than\ncreating replacement runners or repeating completed tools. Pending task events\nremain queued for later processing. Agent continuation carries prepared\nconfiguration and bindings; rollover is deferred while child handles or Task\nManager tasks remain live.\n\nThe stronger guarantee is limited to version 1 Temporal generations. It does\nnot turn process-local `asyncio.Task` delegation inside an opaque node into\nindependent Temporal roots. Claude Code and RLM nodes remain\nwhole-Activity boundaries; their internal calls may continue until that\nActivity settles. Unlimited LLM retries can delay complete Stop acknowledgement,\nand ambiguous external effects remain subject to tool retries/idempotency.\nSee [Temporal workflow control](temporal-workflow-control.md) and\n[Agent continuation](TEMPORAL_ARCHITECTURE.md#agent-continuation-under-history-pressure).\n\n## Architecture\n\n```\nParent Agent (chatAgent / aiAgent / specialized)\n |\n | LLM calls: delegate_to_ai_agent(task=\"...\", context=\"...\")\n |\n v\ntool_executor callback (closure in ai.py)\n | Injects: ai_service, database, nodes, edges, workflow_id,\n | parent_node_id, execution_id\n |\n v\nexecute_tool() dispatcher (handlers/tools.py)\n | Routes node_type in AI_AGENT_TYPES to _execute_delegated_agent()\n |\n v\n_execute_delegated_agent() (handlers/tools.py)\n | 1. Fetches child_params from DATABASE\n | 2. Injects API key + default model from credential store\n | 3. task -> system_message (directive),\n | context-or-task -> prompt\n | 4. Builds child_context with all nodes/edges\n | 5. Spawns asyncio.create_task()\n | 6. Returns immediately: {status: \"delegated\", task_id: \"...\"}\n |\n v v\nParent continues reasoning Child runs independently\n(non-blocking) |\n v\n plugin_cls().execute(child_node_id, child_params, child_ctx)\n | (BaseNode.execute -> the agent plugin's\n | @Operation method in nodes/agent/<plugin>/)\n |\n collect_agent_connections(child_node_id)\n | (services/plugin/edge_walker.py)\n | Filters edges by child's ID\n | Finds child's own memory/skills/tools/task\n |\n AIService.execute_agent() / execute_chat_agent()\n | Uses child's provider/model\n | Uses child's memory (isolated session)\n | Uses child's skills + tools\n | system_message = delegated task,\n | prompt = delegated context\n |\n Result broadcast via WebSocket\n (NOT returned to parent LLM)\n```\n\n## The Delegation Chain (7 Steps)\n\n### Step 1: Parent Builds Tool from Child Agent Node\n\n**File:** `server/services/ai.py`, `_build_tool_from_node()`\n\nWhen the parent agent starts executing and finds a child agent connected to its `input-tools` handle, `_build_tool_from_node()` is called during tool setup:\n\n```python\nfor tool_info in tool_data:\n tool, config = await self._build_tool_from_node(tool_info)\n tools.append(tool)\n tool_configs[tool.name] = config\n```\n\nFor agent node types, the method:\n\n1. Resolves the tool name via `_resolve_default_tool_name_description(node_type)` — a closure inside `_build_tool_from_node()` that reads the plugin class's `tool_name` ClassVar (each agent plugin declares `tool_name = \"delegate_to_<x>\"`). There is no central `DEFAULT_TOOL_NAMES` dict; the name comes from the plugin class via `services.node_registry.get_node_class`. The delegation branch is gated by `_get_tool_schema()`'s `_AGENT_DELEGATION_TYPES` tuple in `services/ai.py`, which mirrors the authoritative `AI_AGENT_TYPES` frozenset in `server/constants.py`. The `tool_name = f\"delegate_to_{cls.type}\"` default is stamped by `BaseNode.__init_subclass__` in `services/plugin/base.py`; `aiAgent` and `chatAgent` declare their names explicitly.\n\n2. Creates a `DelegateToAgentSchema` Pydantic model in `_get_tool_schema()` with two fields (`task` -> the child's mission directive / system message, `context` -> the child's input data / prompt):\n ```python\n class DelegateToAgentSchema(BaseModel):\n task: str = Field(\n description=f\"The mission directive for '{agent_label}'. ...\"\n )\n context: Optional[str] = Field(\n default=None,\n description=\"Input data or specific details the agent needs to work with, ...\"\n )\n ```\n\n3. Returns a config dict:\n ```python\n config = {\n 'node_type': node_type, # e.g., 'aiAgent'\n 'node_id': node_id, # child's node ID\n 'parameters': node_params, # child's stored params (from tool_info)\n 'label': node_label,\n 'connected_services': []\n }\n ```\n\nThe LLM sees a tool like `delegate_to_ai_agent(task=\"...\", context=\"...\")`. It does NOT see or fill the child's actual configuration (provider, model, temperature, etc.).\n\n---\n\n### Step 2: Tool Executor Callback Injects Services\n\n**File:** `server/services/ai.py`, `tool_executor` / `chat_tool_executor` closures\n\nBoth `execute_agent()` and `execute_chat_agent()` define nearly identical tool executor callbacks as closures. When the parent's LLM decides to call the delegation tool, the callback fires.\n\nThe callback captures from outer scope:\n\n| Variable | Source | Purpose |\n|----------|--------|---------|\n| `tool_configs` | Built in step 1 | Maps tool name to config dict |\n| `self` | AIService instance | Provides `.database`, `.auth` |\n| `broadcaster` | Function parameter | WebSocket status broadcasts |\n| `workflow_id` | Function parameter | Scopes broadcasts to workflow |\n| `context` | Function parameter | Contains `nodes` and `edges` arrays |\n\nBefore calling `execute_tool()`, the callback injects the service + graph fields into the config:\n\n```python\nconfig[\"workflow_id\"] = workflow_id\nconfig[\"ai_service\"] = self # AIService instance (shared)\nconfig[\"database\"] = self.database # Database instance (shared)\nconfig[\"parent_node_id\"] = node_id # parent's node id (duplicate tracking)\nif context:\n config[\"nodes\"] = context.get(\"nodes\", []) # ALL workflow nodes\n config[\"edges\"] = context.get(\"edges\", []) # ALL workflow edges\n config[\"workspace_dir\"] = context.get(\"workspace_dir\", \"\")\n config[\"execution_id\"] = context.get(\"execution_id\") # stable per-run id\n```\n\nThese injected fields are what enable the child agent to discover its own connections and execute independently. Without them, the child would have no access to the workflow graph or services.\n\n---\n\n### Step 3: Dispatch to Delegation Handler\n\n**File:** `server/services/handlers/tools.py`, `execute_tool()`\n\nThe dispatcher checks `node_type` against the `AI_AGENT_TYPES` frozenset (`server/constants.py`) and routes every agent type to `_execute_delegated_agent()`:\n\n```python\nfrom constants import AI_AGENT_TYPES\n\nif node_type == \"_builtin_check_delegated_tasks\":\n return await _execute_check_delegated_tasks(tool_args, config)\n\nif node_type in AI_AGENT_TYPES:\n return await _execute_delegated_agent(tool_args, config)\n```\n\n`AI_AGENT_TYPES` in `server/constants.py` is the single source of truth for standard delegatable agents and the CLI/REPL agents that bypass the standard loop.\n\n---\n\n### Step 4: Delegated Agent Execution (Fire-and-Forget)\n\n**File:** `server/services/handlers/tools.py`, `_execute_delegated_agent()`\n\nThis is where the actual parameter assembly happens.\n\n**4a. Extract injected services from config:**\n```python\nai_service = config.get(\"ai_service\")\ndatabase = config.get(\"database\")\nnodes = config.get(\"nodes\", [])\nedges = config.get(\"edges\", [])\nworkflow_id = config.get(\"workflow_id\")\n```\n\nA `(parent_node_id, node_id, task_hash)` duplicate guard (`_active_delegations`) short-circuits with `status: \"ALREADY_DELEGATED\"` if the LLM calls the same delegation twice. A per-child counter (`_active_delegated_nodes`) keeps the child's canvas glow alive past the parent run's end (the background task outlives the `delegate_to_<x>` tool return).\n\n**4b. Fetch child's OWN parameters from database:**\n```python\nchild_params = await database.get_node_parameters(node_id) or {}\n```\n\nThe child's stored parameters (provider, model, temperature, etc.) come from the database -- whatever the user configured in the child node's parameter panel. They are NOT inherited from the parent. The stored `system_message` and `prompt` are loaded here too, but step 4e overwrites both with the delegated `task` / `context`.\n\n**4c. Inject API key if missing:**\n```python\nif not child_params.get(\"api_key\"):\n provider = detect_ai_provider(node_type, child_params)\n key = await ai_service.auth.get_api_key(provider, \"default\")\n if key:\n child_params[\"api_key\"] = key\n```\n\nThe child gets its API key from the credential store based on its own provider setting. If the child is configured for Anthropic and the parent uses OpenAI, the child gets the Anthropic key.\n\n**4d. Inject default model if not set:**\n```python\nif not child_params.get(\"model\"):\n provider = detect_ai_provider(node_type, child_params)\n models = await ai_service.auth.get_stored_models(provider, \"default\")\n if models:\n child_params[\"model\"] = models[0]\n```\n\n**4e. Map the delegated task/context onto the child's params:**\n```python\n# task -> mission directive (system message), context -> input data (prompt)\nchild_params[\"system_message\"] = task_description\nchild_params.pop(\"systemMessage\", None) # drop pre-migration camelCase mirror\nchild_params[\"prompt\"] = task_context if task_context else task_description\n```\n\nThese two strings are the **only inputs the parent passes to the child**. `task` becomes the child's `system_message` (its mission directive); `context` becomes its `prompt` (its input data), falling back to the task text when no context is given. Everything else comes from the child's own stored configuration.\n\n**4f. Build child execution context:**\n```python\nchild_context = {\n \"nodes\": nodes, # ALL workflow nodes (not just child's)\n \"edges\": edges, # ALL workflow edges (not just child's)\n \"workflow_id\": workflow_id, # Parent's workflow ID (for status scoping)\n \"outputs\": {}, # Empty -- child starts fresh\n \"parent_task_id\": task_id, # Link back to parent's delegation task\n \"execution_id\": config.get(\"execution_id\"), # shared per-run id (session-keyed tools)\n}\n```\n\n**4g. Spawn as background task and return immediately:**\n```python\ntask = asyncio.create_task(run_child_agent())\n_delegated_tasks[task_id] = task\n\nreturn {\n \"success\": True,\n \"status\": \"delegated\",\n \"task_id\": task_id,\n \"agent_node_id\": node_id,\n \"agent_name\": agent_label,\n \"message\": f\"Task delegated to '{agent_label}'. Agent is now working independently...\",\n}\n```\n\nInside `run_child_agent()`, the child executes through its own plugin class (Wave 11.E.3 — the legacy `handle_ai_agent` / `handle_chat_agent` imports are gone). Every agent type owns an `@Operation` method that wraps `prepare_agent_call` + `AIService` dispatch, so delegation just goes through `BaseNode.execute`:\n\n```python\nfrom services.node_registry import get_node_class\nfrom services.plugin import NodeContext\n\nplugin_cls = get_node_class(node_type)\ninstance = plugin_cls()\nchild_ctx = NodeContext.from_legacy(\n node_id=node_id, node_type=node_type, context=child_context,\n)\nresult = await instance.execute(node_id, child_params, child_ctx)\n```\n\n---\n\n### Step 5: Child Handler Collects Its Own Connections\n\n**File:** `server/nodes/agent/_inline.py`, `prepare_agent_call()` (called by every agent plugin's `@Operation`)\n\nThe spawned child's `execute()` runs `prepare_agent_call()`, which calls `collect_agent_connections()` (from `server/services/plugin/edge_walker.py`) with **its own node_id**. The function returns a **5-tuple** — `(context_data, skill_data, tool_data, input_data, task_data)` (`edge_walker.py:181-199`; the first element is the Context descriptor, or the legacy Memory descriptor on `input-memory` graphs):\n\n```python\ncontext_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(\n node_id, # CHILD's node ID\n child_context, # Contains ALL nodes/edges\n database,\n log_prefix=\"[AI Agent]\",\n)\n```\n\n---\n\n### Step 6: Connection Filtering by Node ID\n\n**File:** `server/services/plugin/edge_walker.py`, `collect_agent_connections()`\n\nThis function receives ALL nodes/edges but filters by the child's `node_id`:\n\n```python\nfor edge in edges:\n if edge.get(\"target\") != node_id: # Only edges pointing TO this child\n continue\n\n target_handle = edge.get(\"targetHandle\")\n source_node_id = edge.get(\"source\")\n```\n\nFor each matching edge, it checks the target handle:\n\n| Handle | Action |\n|--------|--------|\n| `input-context` | Resolves the child's Context thread (RFC-0002). Memory is now an ordinary tool on `input-tools`. |\n| `input-skill` | Loads skill instructions; expands masterSkill into individual enabled skills |\n| `input-tools` | Discovers directly connected tool nodes, including Android services |\n| `input-main` / `input-chat` | Reads upstream node output for auto-prompt fallback |\n| `input-task` | Collects `taskTrigger` output for the conversational task-report pattern |\n\nThe child only gets connections that are physically wired to it in the workflow graph. If the child has no Context node connected, `context_data` is `None` (and it runs without stored conversation history). If the child has its own tools — including a `simpleMemory` tool node — it gets those tools -- and can delegate further.\n\n---\n\n### Step 7: Child Executes with Its Own Resources\n\n**File:** `server/services/ai.py`, `execute_agent()` / `execute_chat_agent()`\n\nThe child now executes with:\n\n| Resource | Source |\n|----------|--------|\n| Prompt | Delegated `context` from parent's LLM (falls back to `task`) |\n| System message | Delegated `task` from parent's LLM (replaces the child's stored system message) |\n| Provider / model | Child's own (from its DB params) |\n| API key | Injected from credential store based on child's provider |\n| Temperature / max tokens | Child's own (from its DB params) |\n| Memory | Child's own connected simpleMemory node (if any) |\n| Skills | Child's own connected skill nodes (if any) |\n| Tools | Child's own connected tool nodes (if any) |\n\nThe child's result is broadcast to the UI via WebSocket but is NOT fed back into the parent's reasoning loop.\n\n---\n\n## Memory Isolation\n\nParent and child agents have completely separate memory systems. On current\n(V2) graphs the child's conversation is its own RFC-0002 Context store row,\nkeyed by `(workflow_id, generation, <child agent_node_id>)`, and `simpleMemory`\nis an explicit tool the child calls on its own `input-tools`; the table below\ndescribes the legacy markdown model, which survives only for graphs recorded\nwith an `input-memory` edge:\n\n| Aspect | Parent Agent | Child Agent |\n|--------|-------------|-------------|\n| Memory source | Parent's connected simpleMemory | Child's connected simpleMemory |\n| Session ID | From parent's memory node params | From child's memory node params |\n| Memory content | Parent's conversation markdown | Child's conversation markdown |\n| Vector store | `_memory_vector_stores[parent_session]` | `_memory_vector_stores[child_session]` |\n| Memory updates | Parent appends its own exchanges | Child appends its own exchanges |\n| Shared? | **No** -- completely isolated | **No** -- completely isolated |\n\nIf the child has **no memory node connected**, it has no conversation history and executes statelessly with just the delegated task prompt.\n\n---\n\n## Parameter Flow Summary\n\n### What the parent passes to the child\n\n| Parameter | How it arrives |\n|-----------|---------------|\n| `task` (string) | Parent's LLM generates it via `DelegateToAgentSchema` tool call; becomes the child's `system_message` |\n| `context` (optional string) | Parent's LLM generates it via `DelegateToAgentSchema` tool call; becomes the child's `prompt` (falls back to `task`) |\n| `workflow_id` | Injected by tool_executor callback from parent's execution context |\n| `nodes` / `edges` | Injected by tool_executor callback -- ALL workflow nodes and edges |\n| `ai_service` / `database` | Injected by tool_executor callback -- shared instances (by reference) |\n\n### What the child gets from its own config\n\n| Parameter | Source |\n|-----------|--------|\n| `provider` | Child's DB params (e.g., `'openai'`, `'anthropic'`) |\n| `model` | Child's DB params (e.g., `'gpt-4o'`), or first stored model as fallback |\n| `temperature` | Child's DB params |\n| `max_tokens` / `maxTokens` | Child's DB params |\n| `thinkingEnabled` / `thinkingBudget` | Child's DB params |\n| `api_key` | Credential store, resolved by child's own provider |\n| Memory | Child's own connected simpleMemory node |\n| Skills | Child's own connected skill nodes |\n| Tools | Child's own connected tool nodes |\n\n### What the parent does NOT pass\n\n- Provider, model, temperature, max tokens\n- The parent's own system message (the child's stored one is replaced by the delegated `task` instead)\n- Memory or conversation history\n- Skills or skill instructions\n- Tool configurations\n- API keys\n\n---\n\n## What the Parent Receives Back\n\n### Immediate Response (Fire-and-Forget)\n\nThe parent LLM receives this immediate response from the tool call:\n\n```json\n{\n \"success\": true,\n \"status\": \"delegated\",\n \"task_id\": \"delegated_node123_a1b2c3d4\",\n \"agent_node_id\": \"child_agent_node_123\",\n \"agent_name\": \"Research Agent\",\n \"message\": \"Task delegated to 'Research Agent'. Agent is now working independently...\"\n}\n```\n\nThe parent does NOT wait for the child's result. The child's output is broadcast to the UI via WebSocket (`broadcaster.update_node_status`).\n\n### Optional Blocking Delegation (delegation_wait_seconds)\n\nCallers may opt into a bounded wait for a delegated child result:\n\n- The caller sets `config[\"delegation_wait_seconds\"]` on the dispatch config for agent-type tools.\n- `_execute_delegated_agent` then awaits the spawned child via `wait_for_delegation` (`asyncio.wait_for(asyncio.shield(task))` — a timeout cancels the WAITER, never the child) and returns the child's REAL result as the function result, shaped by `_delegation_result_reply`.\n- The reply carries `delegation_lifecycle: True`; `execute_tool` pops it and skips its terminal `success` broadcast (the child's `run_child_agent` already owns the terminal status — an awaited `error` result must not be stomped by a `success` glow).\n- On timeout the child keeps running in the background and the parent receives the standard `status: \"delegated\"` ack. The parent can retrieve the result through `check_delegated_tasks` on a later turn. An identical re-call after a timeout hits the `_active_delegations` dedupe and awaits the existing in-flight task instead of duplicating work.\n- Absent `delegation_wait_seconds` (all native agents), behavior is byte-identical fire-and-forget.\n\nContract locked by `TestDelegationWait` (`tests/nodes/test_ai_tools.py`).\n\n### Result Retrieval (check_delegated_tasks Tool)\n\nWhen a parent agent has delegation tools, a `check_delegated_tasks` tool is automatically injected. The parent LLM can call this tool to check on child status and retrieve results:\n\n```python\n# LLM calls:\ncheck_delegated_tasks(task_ids=[\"delegated_abc123\"])\n\n# Returns:\n{\n \"total_tasks\": 1,\n \"completed\": 1,\n \"running\": 0,\n \"errors\": 0,\n \"tasks\": [{\n \"task_id\": \"delegated_abc123\",\n \"status\": \"completed\",\n \"agent_name\": \"Research Agent\",\n \"result\": \"The research findings show...\"\n }]\n}\n```\n\n### 3-Layer Result Storage (Celery AsyncResult / Ray ObjectRef Pattern)\n\nResults are stored in a 3-layer hierarchy for fast access and durability:\n\n| Layer | Storage | Survives Restart | Access Speed |\n|-------|---------|------------------|--------------|\n| 1 | `asyncio.Task` in `_delegated_tasks` | No | O(1), task.result() |\n| 2 | `_delegation_results` dict | No | O(1), dict lookup |\n| 3 | `NodeOutput` SQLite table | Yes | DB query |\n\n**Layer 1**: Live tasks are tracked in `_delegated_tasks`. When a task completes, `task.result()` extracts the return value.\n\n**Layer 2**: Results are cached in `_delegation_results` dict immediately after child completion/error. This survives the task cleanup in the `finally` block.\n\n**Layer 3**: Results are persisted to the existing `NodeOutput` table with `session_id=\"delegation_{task_id}\"`. This survives server restarts indefinitely.\n\n```python\n# On child completion:\n_delegation_results[task_id] = {\n \"task_id\": task_id,\n \"status\": \"completed\",\n \"agent_name\": agent_label,\n \"result\": result.get('result', {}).get('response', ...),\n}\n\n# Persist to NodeOutput table\nawait database.save_node_output(\n node_id=node_id,\n session_id=f\"delegation_{task_id}\",\n output_name=\"delegation_result\",\n data={...}\n)\n```\n\n### Auto-Injection Logic\n\nThe `check_delegated_tasks` tool is only injected when the parent has delegation tools:\n\n```python\n# In execute_agent() and execute_chat_agent():\nif any(name.startswith('delegate_to_') for name in tool_configs):\n check_info = {\n 'node_type': '_builtin_check_delegated_tasks',\n 'node_id': f'{node_id}_check_tasks',\n 'parameters': {},\n 'label': 'Check Delegated Tasks',\n }\n check_tool, check_config = await self._build_tool_from_node(check_info)\n if check_tool:\n tools.append(check_tool)\n tool_configs[check_tool.name] = check_config\n```\n\n---\n\n## Recursive Delegation\n\nIf the child agent has other agents connected to its own `input-tools` handle, it can delegate further. Each level follows the same pattern:\n\n1. Child's `_build_tool_from_node()` creates a `DelegateToAgentSchema` tool for the grandchild\n2. Child's `tool_executor` callback injects services and the same `nodes`/`edges` graph\n3. Grandchild spawns as its own `asyncio.create_task()`\n4. Grandchild collects its own connections by filtering edges with its own `node_id`\n\nThere is no hard recursion limit. Each agent in the chain is memory-isolated and independently configured.\n\n---\n\n## Status Broadcasting\n\nEvery delegated agent broadcasts status at key phases via WebSocket:\n\n| Phase | When | Broadcast to |\n|-------|------|-------------|\n| `delegated_task` | Child starts executing | Child's node ID |\n| `initializing` | Creating LLM model | Child's node ID |\n| `loading_memory` | Parsing markdown history (legacy `input-memory` graphs only; not emitted when a Context node resolves) | Child's node ID |\n| `building_tools` | Converting tool nodes to `AgentToolSpec` values | Child's node ID |\n| `invoking_llm` | Calling model | Child's node ID |\n| `executing_tool` | Running a tool called by child's LLM | Tool node ID |\n| `delegated_complete` | Child finishes successfully | Child's node ID |\n| `delegated_error` | Child fails | Child's node ID |\n\nAll broadcasts include `workflow_id` for UI scoping. The frontend uses these to show real-time execution animations on the child agent node.\n\n---\n\n## Key Files\n\n| File | Role |\n|------|------|\n| `server/services/ai.py` | `_build_tool_from_node()`, `_get_tool_schema()` (incl. `_AGENT_DELEGATION_TYPES` + `DelegateToAgentSchema`), `_resolve_default_tool_name_description()`, `tool_executor` / `chat_tool_executor` closures, `execute_agent()` / `execute_chat_agent()` |\n| `server/services/plugin/edge_walker.py` | `collect_agent_connections()` (5-tuple: context / skill / tool / input / task) |\n| `server/nodes/agent/_inline.py` | `prepare_agent_call()` — the 3-step pre-dispatch flow (connection collection + param prep) every agent plugin's `@Operation` runs |\n| `server/nodes/agent/<plugin>/__init__.py` | Per-agent plugin classes (`ai_agent`, `chat_agent`, the specialized agents) with their delegation `tool_name` ClassVar + `@Operation` execute method |\n| `server/services/handlers/tools.py` | `execute_tool()` dispatcher, `_execute_delegated_agent()`, `_execute_check_delegated_tasks()`, `_delegated_tasks` / `_delegation_results` / `_active_delegations` tracking |\n| `server/constants.py` | `AI_AGENT_TYPES` frozenset, `detect_ai_provider()` |\n| `client/src/components/AIAgentNode.tsx` | Frontend rendering of execution phase animations |\n---\n\n## Key Findings\n\n1. **Only task/context strings flow from parent to child.** No other parameters (model, temperature, memory, skills) are inherited.\n\n2. **Child configuration comes from its own database params.** Whatever the user set in the child's parameter panel is what the child uses.\n\n3. **Memory is fully isolated.** Parent and child have separate simpleMemory nodes with separate session IDs and separate vector stores.\n\n4. **The child sees the full workflow graph** via `nodes`/`edges`, but `collect_agent_connections()` filters by the child's own `node_id`, so it only gets resources physically connected to it.\n\n5. **Services are shared, not duplicated.** `ai_service` and `database` are passed by reference. They share the same credential store and DB connection.\n\n6. **Delegation is non-blocking.** `asyncio.create_task()` spawns the child; the parent continues immediately. The child's result is NOT returned to the parent's LLM.\n\n7. **Recursive delegation is supported.** If the child has agents connected to its own `input-tools`, it can delegate further with no hard depth limit.\n\n8. **Task Trigger enables workflow-based result handling.** The `taskTrigger` node fires when delegated tasks complete, allowing workflows to process child agent results.\n\n---\n\n## Event-Driven Task Completion (taskTrigger)\n\nIn addition to the `check_delegated_tasks` tool (LLM-driven result checking), the system provides an event-driven approach via the `taskTrigger` workflow node. This enables parent workflows to react to child completion without polling.\n\n### Architecture\n\n```\nChild Agent completes (success or error)\n ↓\ntools.py: _execute_delegated_agent.run_child_agent()\n ↓\nbroadcaster.send_custom_event('task_completed', event_data)\n ↓\nevent_waiter dispatch ('task_completed', event_data)\n ↓\nMatching taskTrigger nodes resolve their Futures\n ↓\nDownstream workflow nodes execute with delegation result\n```\n\n> Note (Wave 12/13): `taskTrigger` is one of the canary-registered trigger types. Under the canary path the producer's CloudEvents envelope routes via `dispatch.emit`; the legacy `event_waiter.register` / `send_custom_event` path is retained for the in-process fallback. See [event_framework.md](./event_framework.md) and the trigger-architecture notes in CLAUDE.md.\n\n### Event Data Schema\n\nThe `task_completed` event carries:\n\n```python\n{\n 'task_id': str, # e.g., \"delegated_abc123_xyz\"\n 'status': str, # 'completed' or 'error'\n 'agent_name': str, # Label of child agent\n 'agent_node_id': str, # Node ID of child agent\n 'parent_node_id': str, # Node ID of parent that delegated\n 'result': str, # Response text (if completed)\n 'error': str, # Error message (if error)\n 'workflow_id': str, # For scoping\n}\n```\n\n### Filter Options\n\nThe `taskTrigger` node supports filtering to match specific delegation events:\n\n| Filter | Description |\n|--------|-------------|\n| `task_id` | Exact match on specific task ID |\n| `agent_name` | Partial match on child agent name |\n| `status_filter` | `all`, `completed`, or `error` |\n| `parent_node_id` | Only trigger for delegations from specific parent |\n\n### Usage Example\n\n```\n[Parent Agent] --delegates--> [Research Agent]\n ↓ (completes)\n [task_completed event]\n ↓\n [Task Trigger]\n (filters: agent_name=\"Research\")\n ↓\n [Process Results Node]\n (uses {{taskTrigger.result}})\n```\n\n### Key Files\n\n| File | Changes |\n|------|---------|\n| `server/services/event_waiter.py` | TriggerConfig, filter builder, FILTER_BUILDERS entry |\n| `server/services/handlers/tools.py` | `send_custom_event()` calls (success + error paths) |\n| `server/constants.py` | `taskTrigger` in EVENT_TRIGGER_TYPES, WORKFLOW_TRIGGER_TYPES |\n| `client/src/components/parameterPanel/InputSection.tsx` | Output schema for draggable variables |\n\n### LLM-Driven vs Event-Driven vs Agent-Handled\n\n| Approach | Tool/Handle | When to Use |\n|----------|-------------|-------------|\n| **LLM-Driven** | `check_delegated_tasks` | Parent LLM decides when to check results and how to process them |\n| **Event-Driven** | `taskTrigger` | Workflow automatically reacts to completion, processes via downstream nodes |\n| **Agent-Handled** | `input-task` handle | Parent agent receives task result and reports to user conversationally |\n\nAll approaches can coexist. The LLM-driven approach is better for dynamic reasoning about results; the event-driven approach is better for deterministic post-processing workflows; the agent-handled approach is best when you want the parent agent to interpret and communicate results naturally.\n\n---\n\n## Agent Task Input Handle (input-task)\n\nAll AI agents (`aiAgent`, `chatAgent`, and the specialized agents — live count via `glob server/nodes/agent/*/__init__.py`) have an `input-task` handle on the left side that can receive task completion events from `taskTrigger` nodes. This enables a conversational pattern where the parent agent reports delegated task results to the user.\n\n### Architecture\n\n```\n[Child Agent] completes\n ↓\n[taskTrigger] fires (filters by agent_name/status)\n ↓\n[Parent Agent] (input-task handle)\n ↓\nAgent generates conversational response about completed task\n```\n\n### How It Works\n\n1. **Backend Detection**: `collect_agent_connections()` in `server/services/plugin/edge_walker.py` detects nodes connected to the `input-task` handle and returns the collected `task_data` (5th element of the tuple)\n2. **Task Data Collection**: Collects output from the connected `taskTrigger` node\n3. **Context Injection**: `prepare_agent_call` (`server/nodes/agent/_inline.py`) calls `format_task_context()` (from `edge_walker.py`) to render `task_data` as prompt context\n4. **Prompt Prepending**: Task context is prepended to the agent's prompt before execution\n\n### Task Context Format\n\nWhen a task completes successfully:\n```\nA delegated task has completed:\n- Agent: Research Agent\n- Task ID: delegated_abc123_xyz\n- Status: Completed Successfully\n- Result: [child agent's response]\n\nPlease report this result to the user in a conversational way.\n```\n\nWhen a task fails:\n```\nA delegated task has failed:\n- Agent: Research Agent\n- Task ID: delegated_abc123_xyz\n- Status: Error\n- Error: [error message]\n\nPlease report this error to the user and suggest next steps if appropriate.\n```\n\n### Key Files\n\n| File | Changes |\n|------|---------|\n| `client/src/components/AIAgentNode.tsx` | Spec-driven; renders the `input-task` handle from the backend NodeSpec (no per-agent config map) |\n| `server/services/plugin/edge_walker.py` | `task_data` collection via `collect_agent_connections()`, `format_task_context()` |\n| `server/nodes/agent/_inline.py` | `prepare_agent_call()` injects the formatted task context into the prompt |\n\n### Usage Example\n\n```\n[Parent Agent] ──delegates──> [Research Agent]\n ↓ (completes)\n [Task Trigger]\n (filters: agent_name=\"Research\")\n ↓\n [Chat Agent]\n (input-task handle)\n ↓\n Generates response:\n \"The research task has completed!\n Here's what was found: ...\"\n```\n\n### Shared Input/Output Handles (backend SSOT)\n\nPost-Wave-11 the frontend `specializedAgentNodes.ts` definition file no longer exists — handle topology is declared on the backend plugin classes and the frontend renders it from each NodeSpec via `useNodeSpec(type)`. Every specialized agent subclasses `SpecializedAgentBase` (`server/nodes/agent/_specialized.py`), which provides the standard handle set through `std_agent_handles()` (declared in `server/nodes/agent/_handles.py`):\n\n- **Left**: `input-main` (Input), `input-context` (Context), `input-task` (Task)\n- **Bottom**: `input-skill` (Skill), `input-tools` (Tool)\n- **Right**: `output-main` (Output)\n- **Top**: `output-top` (Output)\n\nTeam-lead agents (`orchestrator_agent`, `ai_employee`) add an extra `input-teammates` handle for delegation. `AIAgentNode.tsx` is type-agnostic — it reads `handles` / `icon` / `color` / `displayName` / `uiHints` straight from the spec, with no `AGENT_CONFIGS` map.\n","archived":false,"sha256":"47a90ad97a78fea1d591b077b84ca1d0b852619fdee93ba3e77e9b339143ab08"},"doc:docs-internal/agent_teams.md":{"id":"doc:docs-internal/agent_teams.md","path":"docs-internal/agent_teams.md","title":"Durable Agent Teams","content":"# Durable Agent Teams\n\nOpenCompany team leads (`orchestrator_agent` and `ai_employee`) coordinate\nagents connected to their canonical `input-teammates` handle. The topology is\nthe authorization boundary: ordinary tool edges and agents belonging to other\nleads cannot receive team tasks.\n\nManaged employee creation and Builder changes give each concrete tool node\none owning agent. The lead delegates work requiring a specialist's tools\nthrough Task Manager instead of attaching that same callable node to itself.\nPrivate utility instances may repeat a node type; their IDs and bindings stay\nseparate. This does not restrict intentional custom wiring in existing Dev\ngraphs.\n\n## Runtime model\n\n1. `build_teammate_descriptors()` expands connected agents into stable\n identities (node ID, type, label, `delegate_tool_name`).\n `collect_teammate_connections()` enriches each with the teammate's\n parameters, `child_tools` (its `input-tools` edges), `child_skills` (its\n `input-skill` edges, Master Skill nodes expanded to their enabled\n entries) and a rendered `capabilities` sentence:\n `tools: TikHub (Scrape TikTok, Douyin, ...); skills: tikhub-skill (...)`.\n Tool blurbs come from the plugin's `description` ClassVar, skill blurbs\n from the SKILL.md frontmatter description; the runtime `skill` entry and\n `*-personality` skills are skipped. `format_teammate_roster_line()` turns\n that into the one line per teammate both runtimes put in the lead's\n system prompt (`- <node_id>: <label> (<type>) - <capabilities>`). This\n roster is the lead's ONLY view of what a teammate can do, because the\n `delegate_to_*` tools that carry the long capability description are\n hidden from the lead's model (point 4), so a teammate labelled \"Web\n Agent\" holding TikHub would otherwise be indistinguishable from one\n holding nothing. Locked by `tests/test_team_topology.py`.\n2. Task Manager is intrinsically and non-removably bound to every team lead.\n It is not a palette node or an Agent Builder-addable tool.\n3. The lead delegates only by calling `task_manager` with\n `operation=\"assign_task\"`, a bounded mission, context, acceptance criteria,\n and an exact connected `assignee_node_id`.\n4. Delegate tool identities remain internal to the workflow. They resolve the\n selected teammate after persistence but are hidden from the lead's LLM.\n5. Temporal and legacy execution share the durable task lifecycle and use the\n same precreated task ID; neither path creates a second tracking record.\n The legacy path does not currently start the teammate; see\n \"Known limitations\" below.\n\n## Topology\n\n```text\n input-teammates\n Coding Agent ───────────┐\n Web Agent ──────────────┼──> Orchestrator / AI Employee\n Custom aiAgent ─────────┘ │\n ├── intrinsic Task Manager\n └── output-main -> Team Monitor\n```\n\nOnly `aiAgent` may repeat within one team. Specialized agent types are unique.\nValidation rejects invalid endpoints, ambiguous delegate names, cycles, and\ndelegation depth beyond two child layers.\n\n## Durable task lifecycle\n\n```text\nblocked -> queued -> running -> submitted -> accepted\n |\n +-> failed\n```\n\nLead-driven transitions (`AgentTeamService.mutate_durable_task`):\n\n| Operation | Allowed from | Result |\n|---|---|---|\n| `modify_task` | `blocked`, `queued` | edits title, mission, context or acceptance criteria |\n| `cancel_task` | `blocked`, `queued`, `running` | `cancelled` |\n| `accept_task` | `submitted` | `accepted` |\n| `retry_task` / `reassign_task` | `failed`, `submitted`, `cancelled` | `queued`, as a new attempt |\n\n- `submitted` means the worker finished and the lead must review the result.\n- `accepted` is the completed/Done state shown by Team Monitor.\n- `failed` is unresolved until retried or reassigned; a failed task cannot be\n cancelled.\n- `cancelled` is not final: a cancelled task can be retried or reassigned.\n- `finish_team` succeeds only when every task is accepted or cancelled.\n\nMutations are optimistic and execution-scoped. Callers pass `task_id` and,\noptionally, `expected_revision`; the service verifies team ownership and\ncurrent state. When `expected_revision` is omitted, Task Manager reads the\ntask's current revision first, so the check then only covers the moment\nbetween that read and the write. When exactly one task is submitted,\n`accept_task` may safely infer its ID and current revision. It never guesses\namong multiple submissions.\n\n## Parallel scheduling\n\nThe default root-wide limit is three active descendants, including\ngrandchildren and excluding the root lead. Assignments persist before children\nstart. Eligible tasks enter a deterministic FIFO queue, dependencies remain\nblocked, and one sibling failure does not cancel successful siblings. Multiple\n`assign_task` calls in one Temporal turn are preflighted together. Each returns\n`queued` after starting a detached `DelegatedTaskWorkflow`; the lead reports\nthe assignment and returns without polling. The runner owns admission, claim,\nchild execution, terminal persistence, event emission, and permit release.\n\nEach child receives an isolated AgentWorkflow context containing only its\nbounded mission, relevant context, and its own connected tools, skills, and\nmemory. The parent receives a compact result; full child output remains\ninspectable through task attempts and execution traces.\n\n## Generation Stop and Resume\n\nNew Temporal generations carry `execution_control_version=1`. Detached\n`DelegatedTaskWorkflow` runners enroll independently with the generation\ncontroller before business work, so Stop still reaches their attached agents\nafter the assigning lead completes or the controller rolls over. Attached\nchildren use their native parent relationships rather than a per-tool registry.\n\nStop preserves assigned tasks, lane/permit ownership, and existing continuations.\nAlready-admitted model/tool Activities and their result bookkeeping drain;\nqueued work, later calls, and new child starts wait behind the admission gate.\nPermit waits and child-result waits do not count as local business drain, so\npaused children cannot deadlock the checkpoint. Completion persistence and\npermit release for completed work continue normally. `pausing` describes the\nrequest/drain phase; `paused` requires topology-wide checkpoint acknowledgement.\nStop adds no second persisted task pause lifecycle and does not cancel tasks.\n\nResume applies the next revision with producers held, releases descendants and\nindependent roots, reconciles membership, then releases producers. It continues\nthe existing task attempt without another model response or completed tool\nbeing explicitly scheduled. Completion events accumulated while stopped remain\npending for review; handlers do not batch inactivity or discard them.\n\nExisting generations preserve their legacy protocol. Unlimited LLM retries may\nleave Stop in `pausing` during an outage; a tool's policy/idempotency still governs\nunrecorded external effects. Opaque managed agents finish the whole node\nActivity before acknowledging Stop. Direct Workspace tasks and separately\napproved sends remain independent. See\n[Temporal workflow control](temporal-workflow-control.md),\n[Delegation ownership](agent_delegation.md#generation-stopresume-ownership), and\n[Agent context flow](agent_context_flow.md#stopped-turns-and-unanswered-calls).\n\n## Completion and events\n\nAfter durable persistence, lifecycle transitions emit deterministic events such\nas `team.task.submitted`, `team.task.accepted`, `team.task.failed`, and\n`team.task.cancelled`. A canonical task completion CloudEvent feeds\n`taskTrigger` with owning team/execution/root, task, trace, result/error, and\nusage context. A connected lead starts a separate review invocation scoped to\nthe original execution, reads Task Manager, and reports without duplicating work.\n\n## Human interfaces\n\n### Task Manager\n\nSelecting a team lead opens its full-height operational middle panel. It shows\ndurable tasks across workflow restarts by default. Archived executions remain\nindividually selectable. Rows show local created/started/completed timestamps,\nlive or frozen elapsed duration, input/output/total tokens, attempts, results,\nerrors, and authorized accept/retry/reassign/modify/cancel/finish controls.\n\n### Team Monitor\n\nTeam Monitor is read-only and uses only the middle parameter-panel section.\nConnect the lead's output to it. It shows graph-connected teammates immediately,\nthen merges persisted `working`/`idle` state, lifecycle counts, and current\nexecution tasks. Its Done count includes accepted tasks, not submitted work.\n\n## Public Task Manager operations\n\n| Operation | Purpose |\n|---|---|\n| `assign_task` | Persist and dispatch work to a connected teammate |\n| `list_tasks` / `get_task` | Inspect state, result, attempts, and revision |\n| `modify_task` | Edit blocked or queued work |\n| `cancel_task` | Stop blocked, queued or running work |\n| `retry_task` | Queue a new attempt of failed, submitted or cancelled work on the same teammate |\n| `reassign_task` | Queue a new attempt on another connected teammate |\n| `accept_task` | Approve submitted work |\n| `inspect_task_trace` | Read or search the sanitized Temporal events of a task attempt (`detail`: `summary`, `failures`, `timeline` or `search`) |\n| `finish_team` | Complete a fully resolved team execution |\n\n`mark_done` is a deprecated alias for `accept_task` and never deletes history.\n\n## Known limitations\n\n- **Off Temporal, Task Manager does not start teammates.** `assign_task`,\n `retry_task` and `reassign_task` persist the task as `queued` and return a\n `delegation_request`, which only `AgentWorkflow` consumes. The in-process\n branch in `_execute_task_manager` needs `ai_service` and `database` in its\n config, and the plugin tool path in `services/handlers/tools.py` does not\n pass them. So when the lead runs in-process (`AIService.execute_agent` /\n `execute_chat_agent`) rather than as an `AgentWorkflow`, the task stays\n queued and no teammate runs it.\n\n## Key files\n\n- `server/services/plugin/edge_walker.py` — canonical teammate discovery and\n intrinsic Task Manager binding.\n- `server/nodes/tool/task_manager/__init__.py` — model-facing contract.\n- `server/services/agent_team.py` and `server/core/database.py` — authorized\n durable service and persistence.\n- `server/services/temporal/agent_workflow.py` — concurrent child orchestration.\n- `server/services/handlers/tools.py` — legacy execution bridge.\n- `client/src/components/parameterPanel/TaskManagerPanel.tsx` — operational UI.\n- `client/src/components/parameterPanel/TeamMonitorPanel.tsx` — read-only UI.\n\nSee [agent_delegation.md](agent_delegation.md) for low-level compatibility\ndelegation mechanics. Direct `delegate_to_*` calls documented there are not the\nteam-lead model-facing contract.\n","archived":false,"sha256":"cf98685d77c13b013c600c1a9245adca2fab7b8f2c63702b5eade0490c281852"},"doc:docs-internal/ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md":{"id":"doc:docs-internal/ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md","path":"docs-internal/ARCHIVE/AGENT_COMPACTION_FIX_PLAN.md","title":"Fix: agent transcripts outgrow compaction and brick the next firing","content":"# Fix: agent transcripts outgrow compaction and brick the next firing\n\n> **ARCHIVED 2026-09-24 — Shipped** (branch `fix/agent-compaction-pressure`, merged to main). The approved plan plus an as-built record, including where the implementation departed from the plan. Not maintained.\n>\n> For current state see:\n>\n> - [agent_context_flow.md → Transcript size](../agent_context_flow.md): the rules and the replay contract.\n> - [errors.md entry 28](../errors.md): the incident, the fix, and the one-time recovery for rows saved before it.\n\n## Context\n\n`errors.log` (2026-09-05) records one deployed chat workflow, `AI_Assistant_1`: an `aiAgent` on gemini-3.8-flash with writeTodos, simpleMemory and tikhubAction. Each tikhubAction call appended its whole upstream response (roughly 400,000 characters) to the transcript. The `agent.execute_llm_step` input reached 528 KB at iteration 5 and 1.4 MB from iteration 6 on, with a Temporal `PayloadSizeWarning` every turn. Compaction never fired, because its only trigger is 80% of a 1,048,576-token window, compared with a running sum. The 1.4 MB transcript was saved to `agent_conversations`, and the next chat message failed in `agent.prepare_payload` with non-retryable `ConversationTooLarge` (1,429,978 bytes against a 1,000,000 cap). Every later firing failed the same way until the user cleared the Context panel.\n\n## Decisions\n\nConfirmed by the user 2026-09-09:\n1. `ConversationTooLarge` stays a hard, non-retryable failure; the fix prevents new transcripts from reaching it.\n2. The tool-result cap is per-user through a Settings slider, with an env fallback.\n3. The wire dedupe (every tool message stores its text twice) is deferred to its own change.\n4. Compaction's token gate measures the live context, not a cumulative sum.\n\nApproved with the plan on 2026-09-24:\n5. **Byte pressure clears the oldest tool results rather than summarizing the turn the model has not read.** Clearing is free, cannot fail, and is the pattern of Anthropic's context editing (`clear_tool_uses`) and Claude Code's micro-compaction. The summarizer keeps the latest turn verbatim.\n6. **New behavior is gated on values recorded in the `agent.prepare_payload` result, not on a `workflow.patched` marker.** Histories recorded before the change carry none of the new keys and replay through the original code (the technique `capture_temporal_routing_input` uses to freeze routing flags).\n7. **Default cap 100,000 characters, external tools only**, matching the shell and browser output caps. Exempt: delegated agents (`AI_AGENT_TYPES`), `_builtin_skill`, `taskManager`, `_builtin_check_delegated_tasks`.\n\n## Root causes\n\n1. Nothing bounded a tool result before it entered the transcript: the workflow appended `_serialise_tool_result(tool_result)` whole, the in-process loop `json.dumps(result)` whole.\n2. Every tool message is stored twice (`content` plus a default `tool_result` block). Deferred (decision 3).\n3. The token gate compared a running sum of every step's usage (`context_usage_total`) with the threshold, and never looked at bytes.\n4. The seed guard's comment said the run degrades with a warning; the code raises. `save_conversation` had no size check.\n5. `_serialise_tool_result` is shared with the delegation brief and the child's answer text, so the cap could not live inside it.\n\n## As built\n\n**Phase 1, cap external tool results (both paths).**\n- `server/services/tool_output.py`: `bound_tool_output(text, limit)` keeps the first `limit` characters and appends `[Tool result truncated: showing the first N of M characters. Call the tool again with narrower parameters to see the rest.]`. Re-bounding keeps the original M. `tool_output_is_capped(node_type)` exempts decision 7's list. `resolve_tool_output_limit(user_settings, settings)` applies per-user `tool_result_max_chars` > `Settings.tool_result_max_chars`, with the `agent_recursion_limit` guard (a positive int).\n- Settings: `Settings.tool_result_max_chars` (env `TOOL_RESULT_MAX_CHARS`, default 100,000, `0` disables), `.env.template`, `UserSettings.tool_result_max_chars`, a migration whose column default is read from the model field, and the hand-written `Database.get_user_settings` dict.\n- Temporal: `prepare_agent_payload` records `tool_result_max_chars`; `AgentWorkflow.run` bounds `tool_content` right after `_serialise_tool_result` for capped, non-delegation calls.\n- In-process: `run_native_agent_loop(..., tool_output_limit=None)` bounds the serialized result; image blocks are read from the untouched result, so `llm_media` refs survive. `AIService.execute_agent` and `execute_chat_agent` resolve and pass the limit.\n- Client: `toolResultMaxChars` in `client/src/components/ui/settingsPanel/schema.ts` (range in the shared `TOOL_RESULT_MAX_CHARS_RANGE`), and a \"Tool Result Limit\" slider (10K to 200K, step 10K) in the Memory & Compaction section of `SettingsPanel.tsx`.\n\n**Phase 2, transcript pressure in `AgentWorkflow` (runs recorded with `context_pressure_version` 1).**\n- `prepare_agent_payload` also records `transcript_budget_bytes` (three quarters of `TEMPORAL_PAYLOAD_WARN_BYTES`, derived in `transcript_budget_bytes()`) and `context_pressure_version`.\n- `server/services/temporal/agent_context_pressure.py` (pure, workflow-safe). After each tool turn:\n 1. `clear_old_tool_results`: over the budget, results from earlier turns become a placeholder, oldest first, external before agent-internal, down to half the budget. `tool_call_id` and `name` survive; the wire is rebuilt so the duplicated block goes too.\n 2. Summarize when `projected_request_tokens` (the step's `total_tokens`, plus the turn's added characters net of what was cleared, at four per token) reaches the threshold, or when `earlier_turns_over_budget` (still over budget with the earlier turns holding more than half of it). Only the turns before the latest are summarized (`summarizer_view`), and the swap is `[system, user(summary + current request), latest turn verbatim]`. With nothing older than the latest turn (`has_summarizable_history`), it skips.\n 3. `clip_latest_turn`: if the latest turn alone still overflows, its external results are cut to one shared length found by bisection on the exact serialized size, never below 2,000 characters.\n- Without the key, the original cumulative gate and whole-transcript swap run unchanged.\n\n**Phase 3, seed guard.** Comment rewritten to describe the raise. The message now reads \"Clear the conversation from the Context panel, then run again. Settings > Tool Result Limit caps how much one tool call can add to it.\" `_save_conversation` logs a WARNING over half of `_SEED_TRANSCRIPT_MAX_BYTES`. `prepare_agent_payload` logs a WARNING instead of silently dropping the threshold when it cannot be computed.\n\n**Phase 4, docs.** `errors.md` entry 28; `agent_context_flow.md` (new \"Transcript size\" section, compaction rewrite, invariant 10); `memory_compaction.md`; `TEMPORAL_ARCHITECTURE.md` (the loop pseudo-code, the `agent.prepare_payload` and `agent.compact_context` rows: compaction failure is terminal, not best-effort); `data_node.md`; `CLAUDE.md`; `.env.template`.\n\n## Differences from the approved plan, and why\n\n- **Module location.** `server/services/tool_output.py`, not under `services/llm/` as planned: importing anything there runs that package's `__init__`, which reads `llm_defaults.json` from disk. The new module needs only `constants` and the standard library, so workflow code imports it at module level like `get_node_class`.\n- **Truncation note.** The approved text said \"The full result is in this tool's node output panel\". That is false for tools that hide their Output section (`simpleMemory`, `dataSource`, `visionAnalyze`, `processManager`) and only true for a tool's latest call, so the note only tells the model how to get the rest.\n- **Order: clear, then summarize, then clip.** The plan clipped the latest turn inside the clearing step, before any summary; that could cut unread results to fit a history the summary was about to replace. Clipping now runs last, against the room that remains.\n- **Byte-forced summary.** The plan summarized for token pressure only. A transcript whose bulk is text (long user or assistant messages) cannot be brought under budget by clearing tool results, so it also summarizes when the earlier turns alone keep it over budget, but not when the latest turn is the excess (clipping handles that without a paid call).\n- **Token arithmetic.** Checked per provider: every provider's `total_tokens` is the whole prompt, cache reads and writes included, plus output (Anthropic adds the cache counters itself; OpenAI and Gemini already count them in input). The gate uses the step's `total_tokens`; no provider change was needed.\n- **Settings getter.** `Database.get_user_settings` builds its dict by hand, so it needed the new key (the plan said no edit); `server/tests/test_user_settings_contract.py` enforces it.\n\n## Tests\n\n- `server/tests/services/test_tool_output.py`: bounding and re-bounding, the note, exemptions, limit precedence, and one test that keeps the four copies of the default (`.env.template`, `Settings`, `UserSettings`, client schema) equal.\n- `server/tests/temporal/test_agent_context_pressure.py`: clearing order and target, pairing, clipping to one length, the minimum length, token arithmetic, summarizer view.\n- `server/tests/temporal/test_agent_workflow_pressure.py`: `AgentWorkflow.run` end to end with scripted activities: cap and exemptions, legacy histories untouched, clearing across turns, clipping a single overflowing turn, the next-request gate against the legacy running sum, the kept latest turn, byte-forced summary, compaction off.\n- `server/tests/temporal/test_prepare_payload_pressure.py`: the recorded keys and precedence, the seed guard at and over the cap, the threshold warning, the save warning.\n- `server/tests/temporal/test_agent_workflow.py`: `TestTranscriptPressureReplaySafety` source guards.\n- `server/tests/services/test_native_agent_runtime.py`: in-process cap, `llm_media` survival, skill exemption, no limit.\n- `client/src/components/ui/settingsPanel/schema.test.ts`: round trip, mapping, default for old rows, range.\n\n## Verification\n\n```\ncd server && uv run pytest tests/ -q\nbun run typecheck\nbun --cwd=client run test\n```\n\nEnd to end, for the user to run (it needs the real app and data directory): clear the oversized conversation once from the Context panel, run the tikhub prompt that caused the incident, and expect no `PayloadSizeWarning`, tool messages ending with the truncation note, an INFO line when old results are cleared, and a second chat message that runs.\n\n## Deferred and found along the way\n\n- Wire dedupe (decision 3).\n- Pressure relief on the in-process path, which gets only the cap. `CompactionService.track()` also sums every request's `total_tokens` across a session, the same running-sum problem the workflow had.\n- Chunked summarization for models whose window is smaller than the budget.\n- From reading `services/pricing.py` and `config/pricing.json` (not exercised by a test): pricing assumes Anthropic's usage semantics for every provider: OpenAI and OpenAI-compatible cached tokens are charged at the input rate and again at the cache rate, o4-mini reasoning tokens are charged twice, and Gemini thinking tokens are never charged. Separate billing change.\n- Not verified: `BaseNode.execute_as_tool` may hand the model `{\"result\": None}` for Task Manager calls whose payload has `success` but no `result` key.\n","archived":true,"sha256":"2c6d1cac5148332ed8968241d241bf32a84bc4a7ed48807be54c3538ffd2b7fa"},"doc:docs-internal/ARCHIVE/autonomous_agent_creation.md":{"id":"doc:docs-internal/ARCHIVE/autonomous_agent_creation.md","path":"docs-internal/ARCHIVE/autonomous_agent_creation.md","title":"Autonomous Agent Creation: A Comprehensive Guide","content":"# Autonomous Agent Creation: A Comprehensive Guide\n\n> **ARCHIVED 2026-09-04 — Superseded.** External research notes (Symbolica, Cloudflare Code Mode, Anthropic, BoundaryML). Contains no OpenCompany file paths or symbols and never described this repo's `autonomous_agent` plugin.\n>\n> For current state see:\n>\n> - [server/nodes/agent/autonomous_agent/](../../server/nodes/agent/autonomous_agent/) — the real plugin\n> - [node-logic-flows/specialized_agents/autonomous_agent.md](../node-logic-flows/specialized_agents/autonomous_agent.md) — its card\n\n## Introduction\n\nThis document synthesizes insights from leading AI research organizations on building autonomous agents. The approaches discussed represent a paradigm shift from traditional tool-calling patterns toward **code-centric agent architectures** that dramatically improve efficiency, composability, and capabilities.\n\nThe core insight shared across all sources: **code is the most expressive interface through which AI models can interact with their environment**. LLMs were trained on vast amounts of code, making it their native language for expressing complex operations.\n\n---\n\n## Table of Contents\n\n1. [The Problem with Traditional Tool-Calling](#the-problem-with-traditional-tool-calling)\n2. [Code Mode: A New Paradigm](#code-mode-a-new-paradigm)\n3. [Architecture Patterns](#architecture-patterns)\n4. [Implementation Approaches](#implementation-approaches)\n5. [Security and Sandboxing](#security-and-sandboxing)\n6. [Multi-Agent Orchestration](#multi-agent-orchestration)\n7. [Practical Implementation Guide](#practical-implementation-guide)\n8. [Performance Benchmarks](#performance-benchmarks)\n9. [Future Directions](#future-directions)\n\n---\n\n## The Problem with Traditional Tool-Calling\n\n### The While Loop Problem\n\nTraditional agent frameworks operate through a tedious repetition pattern:\n\n```\nDeveloper specifies tools with parameters and return types\n -> LLM receives prompt instructing tool selection\n -> Client executes \"the while loop\":\n LLM call -> tool execution -> context update -> repeat\n```\n\nThis approach has several fundamental limitations:\n\n| Problem | Description |\n|---------|-------------|\n| **Token Overhead** | Each tool call requires round-trip communication, consuming tokens on every iteration |\n| **Context Window Bloat** | Tool definitions loaded upfront can consume 150,000+ tokens before addressing user requests |\n| **Intermediate Result Duplication** | Data retrieved by agents passes through the model multiple times |\n| **Limited Composability** | Single-step tool calls don't compose naturally into complex workflows |\n| **Framework Boilerplate** | Developers write both application logic and framework scaffolding simultaneously |\n\n### The RPC Analogy\n\nBoundaryML draws a useful parallel between tool-calling and Remote Procedure Calls:\n\n| Programming Concept | Agentic Systems Equivalent |\n|---------------------|---------------------------|\n| RPC Call | Tool call |\n| Programmer | Agent |\n| Runtime | While loop |\n| Variables | Context stack |\n\nThe critical insight: **\"The while loop is not a good runtime. The context stack is not a good binding environment.\"**\n\n### Token Economics\n\nConsider a practical example from Anthropic's research:\n- A 2-hour meeting transcript could require processing an additional **50,000 tokens** when passed through the model multiple times\n- Standard MCP implementations loading all tool definitions upfront can consume **hundreds of thousands of tokens** before any useful work begins\n\n---\n\n## Code Mode: A New Paradigm\n\n### Core Concept\n\nCode Mode represents a fundamental shift where AI agents **generate and execute code** rather than making sequential tool calls. Both Cloudflare and Anthropic independently arrived at this conclusion in late 2025.\n\n```\nTraditional Approach:\n Agent -> Tool Call 1 -> Result 1 -> Agent -> Tool Call 2 -> Result 2 -> ...\n\nCode Mode Approach:\n Agent -> Generate Code -> Execute in Sandbox -> Return Final Result\n```\n\n### Why Code?\n\n> \"Code, on the other hand, is what these models were trained on. It's their native language.\"\n> — Rita Kozlov, VP of AI & Developers at Cloudflare\n\nKey advantages:\n- **Native expression format** for LLMs\n- **Built-in control flow** (loops, conditionals, error handling)\n- **Compositional by design** (functions call functions)\n- **Type-safe** with proper annotations\n- **Self-documenting** through code structure\n\n### Progressive Tool Discovery\n\nRather than loading all tool definitions upfront, Code Mode presents tools as a navigable filesystem:\n\n```\nservers/\n├── google-drive/\n│ ├── getDocument.ts\n│ └── index.ts\n├── salesforce/\n│ ├── updateRecord.ts\n│ └── index.ts\n└── calendar/\n ├── createEvent.ts\n ├── listEvents.ts\n └── index.ts\n```\n\nAgents discover tools by navigating this structure, loading only definitions needed for current tasks.\n\n**Result**: Token usage reduced from 150,000 to approximately 2,000—a **98.7% savings**.\n\n---\n\n## Architecture Patterns\n\n### 1. Dynamic Scope Management (Symbolica Agentica)\n\nAgents operate within a **dynamic scope**—a collection of objects that evolves as the agent executes:\n\n```python\n# Initial objects placed in scope at creation\nscope = {\n 'database': DatabaseClient(),\n 'email': EmailService(),\n}\n\n# Objects returned by method calls automatically enter scope\nuser = scope['database'].get_user(123)\n# 'user' now available with its own methods: update(), delete(), get_posts()\n\nposts = user.get_posts()\n# 'posts' collection now available for iteration\n```\n\nThis pattern enables **incremental capability discovery** without preloading everything into context.\n\n### 2. Object Hierarchies Over Flat Functions\n\nInstead of exposing flat function lists, leverage object-oriented patterns:\n\n```python\n# Flat approach (problematic)\ntools = [\n get_user,\n update_user,\n delete_user,\n get_user_posts,\n create_user_post,\n # ... 50 more functions\n]\n\n# Object hierarchy approach (preferred)\nclass User:\n def update(self, **kwargs): ...\n def delete(self): ...\n def get_posts(self) -> List[Post]: ...\n\nclass Post:\n def update(self, **kwargs): ...\n def delete(self): ...\n def add_comment(self, text: str) -> Comment: ...\n```\n\nBenefits:\n- **Natural capability encoding** through method availability\n- **Reduced context size** (methods discovered on-demand)\n- **Type-safe composition** (IDE-like \"go-to-definition\" for agents)\n\n### 3. Compositional Tools (BoundaryML)\n\nRather than single-step tools, provide compositional primitives:\n\n| Tool | Purpose |\n|------|---------|\n| `sequence` | Execute ordered tool chains, returning final result |\n| `forEach` | Apply tools across collections |\n| `callBuiltin` | Execute standard functions |\n| `assignVariable` | Bind values for reuse |\n| `conditional` | Branch based on conditions |\n\nThis enables agents to compose **multi-step programs** rather than single RPC calls.\n\n### 4. Filesystem-Based Tool Organization (Anthropic MCP)\n\n```typescript\n// servers/calendar/createEvent.ts\nexport interface CreateEventParams {\n title: string;\n startTime: Date;\n endTime: Date;\n attendees?: string[];\n}\n\nexport async function createEvent(params: CreateEventParams): Promise<Event> {\n // Implementation\n}\n```\n\nAgents can:\n- Browse available servers\n- Read tool definitions on-demand\n- Use `search_tools` functions for filtered discovery\n- Cache frequently-used definitions\n\n---\n\n## Implementation Approaches\n\n### Approach 1: Code Generation with Sandboxed Execution\n\n**Used by**: Cloudflare, Anthropic\n\n```typescript\n// Agent generates code like this:\nconst events = [];\nfor (let i = 0; i < 31; i++) {\n const event = await calendar.createEvent({\n title: `Daily Standup - Day ${i + 1}`,\n startTime: addDays(startDate, i),\n duration: 30\n });\n events.push(event);\n}\nreturn events;\n```\n\n**Execution flow**:\n1. Agent receives MCP server schema\n2. Generates executable JavaScript/TypeScript\n3. Code executes in sandboxed V8 isolate (Cloudflare Workers)\n4. Results returned to agent context\n\n**Benefits**:\n- 31 events created through single loop vs. 31 API calls\n- Native control flow (loops, conditionals, try/catch)\n- Type checking before execution\n\n### Approach 2: Agentica Framework Pattern\n\n**Used by**: Symbolica\n\n```python\nfrom agentica import spawn\n\n# Third-party clients integrate directly\nfrom twelvedata import TDClient\n\nmarket_data = TDClient()\nfinance_agent = await spawn(\n system_prompt=\"You are a financial analysis assistant.\",\n scope={'market_data': market_data}\n)\n\n# Agent can now use market_data methods directly in generated code\nresult = await finance_agent.run(\n \"Analyze AAPL stock performance over the last quarter\",\n return_type=FinancialReport # Type-safe returns\n)\n```\n\n**Key features**:\n- Library integration without wrapper functions\n- `show_definition()` for on-demand inspection\n- Type-safe return type enforcement\n- Sub-agent spawning via `spawn()` in scope\n\n### Approach 3: Compositional DSL Pattern\n\n**Used by**: BoundaryML\n\n```json\n{\n \"type\": \"sequence\",\n \"steps\": [\n {\n \"type\": \"forEach\",\n \"items\": { \"ref\": \"attendees\" },\n \"body\": {\n \"type\": \"sequence\",\n \"steps\": [\n {\n \"type\": \"callBuiltin\",\n \"function\": \"calendar.getAvailability\",\n \"params\": { \"userId\": { \"ref\": \"item\" } }\n },\n {\n \"type\": \"assignVariable\",\n \"name\": \"availabilities\",\n \"value\": { \"append\": { \"ref\": \"result\" } }\n }\n ]\n }\n },\n {\n \"type\": \"callBuiltin\",\n \"function\": \"calendar.findCommonSlot\",\n \"params\": { \"availabilities\": { \"ref\": \"availabilities\" } }\n }\n ]\n}\n```\n\n**Benefits**:\n- Type-checkable and lintable\n- No per-step LLM callbacks\n- Clear program structure\n- Generalizes from examples (2-person to N-person scheduling)\n\n---\n\n## Security and Sandboxing\n\n### Multi-Layer Security Architecture\n\nProduction code execution requires robust isolation:\n\n```\n┌─────────────────────────────────────────────┐\n│ User Space │\n│ ┌─────────────────────────────────────┐ │\n│ │ Application │ │\n│ │ ┌─────────────────────────────┐ │ │\n│ │ │ WASM Sandbox │ │ │\n│ │ │ ┌───────────────────┐ │ │ │\n│ │ │ │ Agent Code │ │ │ │\n│ │ │ └───────────────────┘ │ │ │\n│ │ └─────────────────────────────┘ │ │\n│ └─────────────────────────────────────┘ │\n│ │\n│ MicroVM Boundary │\n└─────────────────────────────────────────────┘\n```\n\n### Symbolica's Approach: Remote Object Proxying\n\n```python\n# Agent code executes in sandbox\n# Objects remain local to user\n# Method calls trigger RPC across process boundaries\n\nclass RemoteProxy:\n def __init__(self, object_id: str, rpc_client: RPCClient):\n self._id = object_id\n self._rpc = rpc_client\n\n def __getattr__(self, name):\n async def method_call(*args, **kwargs):\n return await self._rpc.call(self._id, name, args, kwargs)\n return method_call\n```\n\n### Cloudflare's Approach: V8 Isolates\n\n- Code executes in sandboxed V8 isolate\n- Powered by Workers Loader\n- Negligible cold start due to Workers infrastructure\n- Code Executor binding handles script execution\n- Creation IDs for monitoring and tracking\n\n### Security Checklist\n\n| Concern | Mitigation |\n|---------|------------|\n| **Code Injection** | Sandbox execution environment |\n| **Resource Exhaustion** | CPU/memory limits per execution |\n| **Data Exfiltration** | Network restrictions, allowlists |\n| **API Key Exposure** | Keys never enter model context |\n| **Sensitive Data Leakage** | Automatic PII tokenization |\n| **Infinite Loops** | Execution timeouts |\n| **File System Access** | Virtual filesystem isolation |\n\n### Privacy-Preserving Execution\n\nAnthropic's approach to sensitive data:\n\n```typescript\n// Intermediate data remains in execution environment\n// PII automatically tokenized before entering model context\n\nconst spreadsheet = await drive.getSpreadsheet(\"salary-data.xlsx\");\n// 10,000 rows with PII\n\nconst summary = spreadsheet\n .filter(row => row.department === \"Engineering\")\n .aggregate({ avgSalary: \"mean(salary)\" });\n// Only aggregate returned to model context\n```\n\n---\n\n## Multi-Agent Orchestration\n\n### Agentica-in-Scope Pattern\n\nPlacing the `spawn()` function in an agent's scope enables autonomous multi-agent orchestration:\n\n```python\n# Orchestrator agent can spawn sub-agents dynamically\norchestrator = await spawn(\n \"You orchestrate complex research tasks.\",\n scope={\n 'spawn': spawn, # Enable sub-agent creation\n 'search': SearchClient(),\n 'summarize': SummarizationService(),\n }\n)\n\n# Orchestrator can now create specialized sub-agents\n# Sub-agents inherit capabilities and objects from orchestrator\n```\n\n### Type-Safe Agent Composition\n\n```python\n# Agents specify return types when invoked\n# Execution environment enforces type compliance\n\nresearch_result = await research_agent.run(\n \"Research quantum computing trends\",\n return_type=ResearchReport\n)\n\n# Subsequent agents can reliably depend on returned objects\nanalysis = await analysis_agent.run(\n f\"Analyze this report: {research_result}\",\n return_type=AnalysisSummary,\n scope={'report': research_result} # Type-safe injection\n)\n```\n\n### Agent Communication Patterns\n\n| Pattern | Description | Use Case |\n|---------|-------------|----------|\n| **Sequential Pipeline** | Output of agent N feeds input of agent N+1 | Document processing workflows |\n| **Parallel Fan-Out** | Multiple agents process simultaneously | Research aggregation |\n| **Hierarchical Delegation** | Parent spawns child agents for subtasks | Complex problem decomposition |\n| **Shared State** | Agents share objects through scope | Collaborative editing |\n\n---\n\n## Practical Implementation Guide\n\n### Step 1: Define Your Tool Schema\n\n```typescript\n// servers/crm/index.ts\nexport interface CRMServer {\n contacts: {\n list(filters?: ContactFilters): Promise<Contact[]>;\n get(id: string): Promise<Contact>;\n create(data: CreateContactData): Promise<Contact>;\n update(id: string, data: UpdateContactData): Promise<Contact>;\n };\n deals: {\n list(filters?: DealFilters): Promise<Deal[]>;\n create(data: CreateDealData): Promise<Deal>;\n updateStage(id: string, stage: DealStage): Promise<Deal>;\n };\n}\n```\n\n### Step 2: Implement Object Hierarchies\n\n```python\nclass Contact:\n \"\"\"CRM Contact with related operations.\"\"\"\n\n def __init__(self, data: dict, client: CRMClient):\n self.id = data['id']\n self.name = data['name']\n self.email = data['email']\n self._client = client\n\n async def get_deals(self) -> List['Deal']:\n \"\"\"Get all deals associated with this contact.\"\"\"\n return await self._client.deals.list(contact_id=self.id)\n\n async def create_deal(self, data: CreateDealData) -> 'Deal':\n \"\"\"Create a new deal for this contact.\"\"\"\n data['contact_id'] = self.id\n return await self._client.deals.create(data)\n\n async def send_email(self, subject: str, body: str) -> EmailResult:\n \"\"\"Send email to this contact.\"\"\"\n return await self._client.email.send(\n to=self.email,\n subject=subject,\n body=body\n )\n```\n\n### Step 3: Configure Sandbox Environment\n\n```typescript\n// Cloudflare Workers approach\nexport default {\n async fetch(request: Request, env: Env): Promise<Response> {\n const agent = new Agent({\n model: \"claude-4\",\n servers: {\n crm: new CRMServer(env.CRM_API_KEY),\n email: new EmailServer(env.EMAIL_API_KEY),\n },\n sandbox: {\n maxExecutionTime: 30000, // 30 seconds\n maxMemory: 128 * 1024 * 1024, // 128MB\n allowedNetworkHosts: ['api.crm.com', 'api.email.com'],\n }\n });\n\n return agent.handle(request);\n }\n};\n```\n\n### Step 4: Enable Progressive Discovery\n\n```python\nclass AgentScope:\n \"\"\"Dynamic scope with progressive discovery.\"\"\"\n\n def __init__(self, initial_objects: dict):\n self._objects = initial_objects\n self._definitions_cache = {}\n\n def show_definition(self, object_name: str) -> str:\n \"\"\"IDE-like go-to-definition for agents.\"\"\"\n if object_name not in self._definitions_cache:\n obj = self._objects.get(object_name)\n if obj:\n self._definitions_cache[object_name] = self._extract_definition(obj)\n return self._definitions_cache.get(object_name, \"Object not found\")\n\n def _extract_definition(self, obj) -> str:\n \"\"\"Extract type hints, docstrings, and method signatures.\"\"\"\n import inspect\n lines = []\n for name, method in inspect.getmembers(obj, predicate=inspect.ismethod):\n if not name.startswith('_'):\n sig = inspect.signature(method)\n doc = method.__doc__ or \"No description\"\n lines.append(f\"{name}{sig}: {doc}\")\n return \"\\n\".join(lines)\n```\n\n### Step 5: Implement Type-Safe Returns\n\n```python\nfrom pydantic import BaseModel\nfrom typing import TypeVar, Generic\n\nT = TypeVar('T', bound=BaseModel)\n\nclass TypedAgentResult(Generic[T]):\n def __init__(self, value: T, execution_trace: List[str]):\n self.value = value\n self.trace = execution_trace\n\nasync def run_agent(\n prompt: str,\n return_type: Type[T],\n scope: dict\n) -> TypedAgentResult[T]:\n \"\"\"Execute agent with type-safe return enforcement.\"\"\"\n\n # Generate and execute code\n result = await execute_in_sandbox(prompt, scope)\n\n # Validate return type\n if not isinstance(result.value, return_type):\n try:\n result.value = return_type.model_validate(result.value)\n except ValidationError as e:\n raise AgentTypeError(f\"Return type mismatch: {e}\")\n\n return result\n```\n\n---\n\n## Performance Benchmarks\n\n### Token Efficiency Comparison\n\n| Scenario | Traditional MCP | Code Mode | Savings |\n|----------|-----------------|-----------|---------|\n| Simple single-event task | 1,000 tokens | 680 tokens | 32% |\n| 31-event creation | 15,500 tokens | 2,945 tokens | **81%** |\n| Tool definition loading | 150,000 tokens | 2,000 tokens | **98.7%** |\n| Complex workflow (10 steps) | 25,000 tokens | 4,500 tokens | 82% |\n\n### Benchmark Results\n\n**Symbolica Agentica on BrowseComp-Plus**:\n- GPT-5 with Agentica: **77.11%**\n- GPT-5 without Agentica: 73.25%\n- Improvement: **3.86 percentage points**\n\n### Latency Improvements\n\n| Operation | Sequential Tool Calls | Code Mode |\n|-----------|----------------------|-----------|\n| 31 calendar events | ~31 round trips | 1 round trip |\n| Data filtering (10K rows) | N/A (context overflow) | Single execution |\n| Multi-step workflow | N * LLM latency | 1 * LLM latency |\n\n---\n\n## Future Directions\n\n### Research Areas\n\n1. **Better DSLs for Agent Programs**\n - Moving beyond single RPC calls toward coherent program structures\n - Type-checking and linting for agent-generated plans\n - Formal verification of agent behavior\n\n2. **Context Degradation Mitigation**\n - Research shows context degradation in extended conversations\n - LLMs perform better with complete program specifications\n - Single-shot program generation vs. multi-turn accumulation\n\n3. **Skill Learning and Persistence**\n - Agents save reusable code functions as recoverable skills\n - State persistence across operations through filesystem access\n - Learning from successful execution traces\n\n4. **Cross-Language Agent Interoperability**\n - Language-agnostic object models\n - Runtime type checking across language boundaries\n - Unified execution environments (Python, TypeScript, more)\n\n### Emerging Patterns\n\n| Pattern | Description |\n|---------|-------------|\n| **Agent Skills** | Persistent, reusable code snippets agents can invoke |\n| **Typed Agent Protocols** | Formal interface definitions for agent communication |\n| **Execution Traces** | Debuggable records of agent decisions and code |\n| **Rollback Capabilities** | Transaction-like semantics for agent operations |\n\n---\n\n## Conclusion\n\nThe shift from traditional tool-calling to code-centric agent architectures represents a fundamental advancement in AI agent design. Key takeaways:\n\n1. **Code is the natural interface** for LLMs to express complex operations\n2. **Progressive discovery** dramatically reduces token consumption\n3. **Object hierarchies** enable natural capability encoding\n4. **Sandboxed execution** provides necessary security guarantees\n5. **Type-safe composition** enables reliable multi-agent systems\n\nThe convergence of Cloudflare, Anthropic, Symbolica, and BoundaryML on these patterns suggests a maturing consensus on how to build production-ready autonomous agents.\n\n---\n\n## References\n\n- [Agentica: Beyond Code Mode for Autonomous Agents](https://www.symbolica.ai/blog/beyond-code-mode-agentica) - Symbolica\n- [Code Mode: The Better Way to Use MCP](https://blog.cloudflare.com/code-mode/) - Cloudflare\n- [Code Execution with MCP: Building More Efficient AI Agents](https://www.anthropic.com/engineering/code-execution-with-mcp) - Anthropic\n- [Lambda the Ultimate AI Agent](https://boundaryml.com/blog/lambda-the-ultimate-ai-agent) - BoundaryML\n- [Cloudflare Code Mode Cuts Token Usage by 81%](https://workos.com/blog/cloudflare-code-mode-cuts-token-usage-by-81) - WorkOS\n\n---\n\n*Document created: 2026-02-12*\n*Based on research from Symbolica, Cloudflare, Anthropic, and BoundaryML*\n","archived":true,"sha256":"dbee80a6a1aa37eba1d20922f63fe31af197d8be04794b06ec4de748973c2107"},"doc:docs-internal/ARCHIVE/claude_code_agent_architecture.md":{"id":"doc:docs-internal/ARCHIVE/claude_code_agent_architecture.md","path":"docs-internal/ARCHIVE/claude_code_agent_architecture.md","title":"Claude Code Agent Architecture","content":"# Claude Code Agent Architecture\n\n> **ARCHIVED 2026-09-04 — Superseded.** LangGraph-era design material. Its one current-tense claim was wrong: the claude path is a plain subprocess over stdio pipes, not a PTY (`nodes/agent/claude_code_agent/_pool.py`); PTY is used only by the non-pooled `AICliSession` for codex and gemini.\n>\n> For current state see:\n>\n> - [claude_code_interactive_mode.md](../claude_code_interactive_mode.md) — the shipped stdio protocol\n> - [cli_agent_framework.md](../cli_agent_framework.md) — the generic runtime\n> - [claude_code_agent.md](../claude_code_agent.md) — documentation hub\n\n> **Current implementation note:** The production `claude_code_agent` is an\n> interactive Claude Code CLI/PTY integration implemented under\n> `server/nodes/agent/claude_code_agent/`. It does not use LangGraph or\n> LangChain. The LangGraph diagrams and dependency snapshot below are retained\n> only as historical design material and must not be used as implementation\n> guidance.\n\n## Table of Contents\n1. [Memory & Context Compaction Architecture](#1-memory--context-compaction-architecture)\n2. [Sub-Agent Creation & Handling](#2-sub-agent-creation--handling)\n3. [Execution Flow Diagrams](#3-execution-flow-diagrams)\n4. [Data Structures Reference](#4-data-structures-reference)\n\n---\n\n# 1. Memory & Context Compaction Architecture\n\n## 1.1 Overview Diagram\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ CONTEXT WINDOW MANAGEMENT │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │\n│ │ Message │ │ Message │ │ Message │ │\n│ │ History │───▶│ Counter │───▶│ Compaction │ │\n│ │ Buffer │ │ (Tokens) │ │ Decision │ │\n│ └──────────────┘ └──────────────┘ └──────┬───────┘ │\n│ │ │\n│ ┌────────────────────┴────────────────────┐ │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌──────────────────┐ ┌────────────┐ │\n│ │ BELOW THRESHOLD │ │ ABOVE │ │\n│ │ (< 100K tokens)│ │ THRESHOLD │ │\n│ └────────┬─────────┘ └─────┬──────┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌──────────────────┐ ┌───────────────────┐ │\n│ │ Continue │ │ COMPACTION │ │\n│ │ Normal │ │ PIPELINE │ │\n│ │ Execution │ │ │ │\n│ └──────────────────┘ └───────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 1.2 Token Counting Algorithm\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOKEN COUNTING FORMULA │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ total_tokens = input_tokens │\n│ + cache_creation_input_tokens (or 0) │\n│ + cache_read_input_tokens (or 0) │\n│ + output_tokens │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ TOKEN SOURCES │ │\n│ ├─────────────────────┬───────────────────────────────────────────────┤ │\n│ │ input_tokens │ Tokens in all messages sent to model │ │\n│ │ cache_creation │ Tokens written to prompt cache (first time) │ │\n│ │ cache_read │ Tokens read from prompt cache (subsequent) │ │\n│ │ output_tokens │ Tokens in model's response │ │\n│ └─────────────────────┴───────────────────────────────────────────────┘ │\n│ │\n│ DEFAULT_THRESHOLD = 100,000 tokens │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 1.3 Compaction Pipeline (Detailed)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ COMPACTION PIPELINE │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ STEP 1: CHECK THRESHOLD │\n│ ════════════════════════ │\n│ │\n│ if compaction_control is None or not enabled: │\n│ return False ──────────────────────────────▶ [SKIP COMPACTION] │\n│ │\n│ total_tokens = calculate_tokens(last_message) │\n│ threshold = config.get(\"context_token_threshold\", 100_000) │\n│ │\n│ if total_tokens < threshold: │\n│ return False ──────────────────────────────▶ [SKIP COMPACTION] │\n│ │\n│ │ │\n│ ▼ │\n│ STEP 2: PREPARE MESSAGES │\n│ ═════════════════════════ │\n│ │\n│ messages = copy(current_messages) │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────┐ │\n│ │ CRITICAL: Remove tool_use blocks from last assistant message │ │\n│ │ │ │\n│ │ WHY? tool_use requires tool_result, which we don't have yet │ │\n│ │ This prevents API 400 validation errors │ │\n│ └─────────────────────────────────────────────────────────────────┘ │\n│ │\n│ if messages[-1][\"role\"] == \"assistant\": │\n│ non_tool_blocks = [b for b in content if b.type != \"tool_use\"] │\n│ if non_tool_blocks: │\n│ messages[-1][\"content\"] = non_tool_blocks │\n│ else: │\n│ messages.pop() # Remove entire message if only tool_use │\n│ │\n│ │ │\n│ ▼ │\n│ STEP 3: APPEND SUMMARY PROMPT │\n│ ══════════════════════════════ │\n│ │\n│ messages.append({ │\n│ \"role\": \"user\", │\n│ \"content\": SUMMARY_PROMPT # See Section 1.4 │\n│ }) │\n│ │\n│ │ │\n│ ▼ │\n│ STEP 4: CALL MODEL FOR SUMMARY │\n│ ══════════════════════════════ │\n│ │\n│ response = client.beta.messages.create( │\n│ model = config.get(\"model\", current_model), │\n│ messages = messages, │\n│ max_tokens = params[\"max_tokens\"], │\n│ extra_headers = {\"X-Stainless-Helper\": \"compaction\"} │\n│ ) │\n│ │\n│ │ │\n│ ▼ │\n│ STEP 5: REPLACE MESSAGE HISTORY │\n│ ════════════════════════════════ │\n│ │\n│ summary_text = response.content[0].text │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────┐ │\n│ │ ENTIRE HISTORY REPLACED WITH SINGLE MESSAGE │ │\n│ └─────────────────────────────────────────────────────────────────┘ │\n│ │\n│ self.set_messages_params({ │\n│ \"messages\": [{ │\n│ \"role\": \"user\", │\n│ \"content\": [{\"type\": \"text\", \"text\": summary_text}] │\n│ }] │\n│ }) │\n│ │\n│ return True ───────────────────────────────────▶ [COMPACTION DONE] │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 1.4 Summary Prompt Structure\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ DEFAULT SUMMARY PROMPT │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ \"You have been working on the task described above but have not yet │\n│ completed it. Write a continuation summary that will allow you (or │\n│ another instance of yourself) to resume work efficiently in a future │\n│ context window where the conversation history will be replaced with │\n│ this summary. │\n│ │\n│ Your summary should be structured, concise, and actionable. Include: │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ 1. TASK OVERVIEW │ │\n│ │ • The user's core request and success criteria │ │\n│ │ • Any clarifications or constraints they specified │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ 2. CURRENT STATE │ │\n│ │ • What has been completed so far │ │\n│ │ • Files created, modified, or analyzed (with paths if relevant) │ │\n│ │ • Key outputs or artifacts produced │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ 3. IMPORTANT DISCOVERIES │ │\n│ │ • Technical constraints or requirements uncovered │ │\n│ │ • Decisions made and their rationale │ │\n│ │ • Errors encountered and how they were resolved │ │\n│ │ • What approaches were tried that didn't work (and why) │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ 4. NEXT STEPS │ │\n│ │ • Specific actions needed to complete the task │ │\n│ │ • Any blockers or open questions to resolve │ │\n│ │ • Priority order if multiple steps remain │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ 5. CONTEXT TO PRESERVE │ │\n│ │ • User preferences or style requirements │ │\n│ │ • Domain-specific details that aren't obvious │ │\n│ │ • Any promises made to the user │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ Be concise but complete—err on the side of including information that │\n│ would prevent duplicate work or repeated mistakes. │\n│ │\n│ Wrap your summary in <summary></summary> tags.\" │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 1.5 Tool Runner Main Loop with Compaction\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOOL RUNNER EXECUTION LOOP │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────┐ │\n│ │ START │ │\n│ └──────┬──────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────┐ │\n│ ┌───────▶│ Check: should_stop()? │ │\n│ │ │ (max_iterations check) │ │\n│ │ └───────────┬─────────────┘ │\n│ │ │ │\n│ │ ┌──────────┴──────────┐ │\n│ │ │ │ │\n│ │ ▼ NO ▼ YES │\n│ │ ┌──────────────┐ ┌──────────────┐ │\n│ │ │ Make API │ │ EXIT │ │\n│ │ │ Request │ │ LOOP │ │\n│ │ └──────┬───────┘ └──────────────┘ │\n│ │ │ │\n│ │ ▼ │\n│ │ ┌──────────────────────┐ │\n│ │ │ yield message │ ◀─── Emit to caller │\n│ │ │ iteration_count++ │ │\n│ │ └──────────┬───────────┘ │\n│ │ │ │\n│ │ ▼ │\n│ │ ┌──────────────────────────────┐ │\n│ │ │ _check_and_compact() │ │\n│ │ │ │ │\n│ │ │ Compaction performed? │ │\n│ │ └──────────────┬───────────────┘ │\n│ │ │ │\n│ │ ┌──────────┴──────────┐ │\n│ │ │ │ │\n│ │ ▼ YES ▼ NO │\n│ │ ┌───────────┐ ┌────────────────────────┐ │\n│ │ │ SKIP tool │ │ generate_tool_call_ │ │\n│ │ │ generation│ │ response() │ │\n│ │ │ │ └───────────┬────────────┘ │\n│ │ │ │ │ │\n│ │ │ │ ┌──────────┴──────────┐ │\n│ │ │ │ │ │ │\n│ │ │ │ ▼ None ▼ Response │\n│ │ │ │ ┌────────────┐ ┌───────────────────┐ │\n│ │ │ │ │ No tool │ │ append_messages() │ │\n│ │ │ │ │ calls │ │ (message + tool │ │\n│ │ │ │ │ EXIT LOOP │ │ results) │ │\n│ │ │ │ └────────────┘ └─────────┬─────────┘ │\n│ │ │ │ │ │\n│ │ └─────┬─────┘ │ │\n│ │ │ │ │\n│ │ └───────────────┬───────────────────┘ │\n│ │ │ │\n│ │ ▼ │\n│ │ ┌──────────────────────┐ │\n│ │ │ Reset flags: │ │\n│ │ │ • _messages_modified │ │\n│ │ │ • _cached_response │ │\n│ │ └──────────┬───────────┘ │\n│ │ │ │\n│ └────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 1.6 Memory Tool Operations\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ MEMORY TOOL COMMAND DISPATCH │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────────┐ │\n│ │ Tool Input │ │\n│ │ (command obj) │ │\n│ └────────┬────────┘ │\n│ │ │\n│ ▼ │\n│ ┌───────────────────────────────────────┐ │\n│ │ command.command == ? │ │\n│ └───────────────────┬───────────────────┘ │\n│ │ │\n│ ┌────────┬────────┬─────────┼─────────┬────────┬────────┐ │\n│ ▼ ▼ ▼ ▼ ▼ ▼ ▼ │\n│ ┌──────┐┌──────┐┌─────────┐┌──────┐┌──────┐┌──────┐┌───────────┐ │\n│ │\"view\"││\"crea-││\"str_ ││\"inse-││\"dele-││\"rena-││ unknown │ │\n│ │ ││ te\" ││replace\" ││ rt\" ││ te\" ││ me\" ││ │ │\n│ └──┬───┘└──┬───┘└────┬────┘└──┬───┘└──┬───┘└──┬───┘└─────┬─────┘ │\n│ │ │ │ │ │ │ │ │\n│ ▼ ▼ ▼ ▼ ▼ ▼ ▼ │\n│ ┌──────────────────────────────────────────────────────────────────┐ │\n│ │ ABSTRACT METHODS │ │\n│ │ (Must be implemented by subclass) │ │\n│ ├──────────────────────────────────────────────────────────────────┤ │\n│ │ │ │\n│ │ view(command) │ View contents at memory path │ │\n│ │ │ Returns: file content or directory list │ │\n│ │ ─────────────────────┼──────────────────────────────────────────│ │\n│ │ create(command) │ Create new memory file │ │\n│ │ │ Params: path, file_text │ │\n│ │ ─────────────────────┼──────────────────────────────────────────│ │\n│ │ str_replace(command) │ Replace text in memory file │ │\n│ │ │ Params: path, old_str, new_str │ │\n│ │ ─────────────────────┼──────────────────────────────────────────│ │\n│ │ insert(command) │ Insert text at line number │ │\n│ │ │ Params: path, insert_line, new_str │ │\n│ │ ─────────────────────┼──────────────────────────────────────────│ │\n│ │ delete(command) │ Delete memory file or directory │ │\n│ │ │ Params: path │ │\n│ │ ─────────────────────┼──────────────────────────────────────────│ │\n│ │ rename(command) │ Rename/move memory file or directory │ │\n│ │ │ Params: old_path, new_path │ │\n│ │ │ │\n│ └──────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌──────────────────────────────────────────────────────────────────┐ │\n│ │ IMPLEMENTATION EXAMPLE (Custom Backend) │ │\n│ ├──────────────────────────────────────────────────────────────────┤ │\n│ │ │ │\n│ │ class DatabaseMemoryTool(BetaAbstractMemoryTool): │ │\n│ │ def __init__(self, db_connection): │ │\n│ │ self.db = db_connection │ │\n│ │ │ │\n│ │ def view(self, command): │ │\n│ │ path = command.path │ │\n│ │ return self.db.query(f\"SELECT content FROM memory │ │\n│ │ WHERE path = ?\", path) │ │\n│ │ │ │\n│ │ def create(self, command): │ │\n│ │ self.db.execute(f\"INSERT INTO memory (path, content) │ │\n│ │ VALUES (?, ?)\", │ │\n│ │ command.path, command.file_text) │ │\n│ │ return \"Created successfully\" │ │\n│ │ # ... other methods │ │\n│ │ │ │\n│ └──────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n# 2. Sub-Agent Creation & Handling\n\n## 2.1 Historical LangGraph Sub-Agent Architecture (non-production)\n\n> Historical design snapshot only. Production sub-agent execution uses the\n> CLI-backed agent framework and Temporal delegation workflows; no production\n> import or dependency on LangGraph is implied by this section.\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ SUB-AGENT ARCHITECTURE OVERVIEW │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ PARENT GRAPH │ │\n│ │ │ │\n│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────────────┐ │ │\n│ │ │ START │───▶│ Agent │───▶│ Conditional Edge │ │ │\n│ │ └──────────┘ │ Node │ │ (router function) │ │ │\n│ │ └──────────┘ └──────────────┬───────────────┘ │ │\n│ │ │ │ │\n│ │ ┌──────────────────────────────┼──────────────┐ │ │\n│ │ │ │ │ │ │\n│ │ ▼ ▼ ▼ │ │\n│ │ ┌─────────────────┐ ┌──────────────┐ ┌─────┐ │ │\n│ │ │ Tool Node │ │ Sub-Agent │ │ END │ │ │\n│ │ │ (parallel) │ │ (nested │ │ │ │ │\n│ │ │ │ │ graph) │ │ │ │ │\n│ │ └────────┬────────┘ └──────┬───────┘ └─────┘ │ │\n│ │ │ │ │ │\n│ │ │ ┌──────────────────────┘ │ │\n│ │ │ │ │ │\n│ │ ▼ ▼ │ │\n│ │ ┌─────────────────────────────────────────────────────┐ │ │\n│ │ │ State Reducer │ │ │\n│ │ │ (aggregates results from parallel executions) │ │ │\n│ │ └─────────────────────────────────────────────────────┘ │ │\n│ │ │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 2.2 Send API - Parallel Sub-Task Spawning\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ SEND API MECHANISM │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ PURPOSE: Spawn multiple parallel tasks with independent state │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Send(node: str, arg: Any) │ │\n│ │ │ │\n│ │ • node: Target node name to invoke │ │\n│ │ • arg: Custom state/input for that invocation │ │\n│ │ (can differ from main graph state!) │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ EXAMPLE: Map-Reduce Pattern │\n│ ─────────────────────────── │\n│ │\n│ class OverallState(TypedDict): │\n│ subjects: list[str] │\n│ results: Annotated[list[str], operator.add] # Reducer! │\n│ │\n│ def fan_out(state: OverallState) -> list[Send]: │\n│ \"\"\"Conditional edge that spawns parallel tasks.\"\"\" │\n│ return [ │\n│ Send(\"worker\", {\"subject\": s}) │\n│ for s in state[\"subjects\"] │\n│ ] │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ EXECUTION FLOW: │\n│ │\n│ subjects = [\"A\", \"B\", \"C\"] │\n│ │ │\n│ ▼ │\n│ ┌────────────────────────┐ │\n│ │ fan_out(state) │ │\n│ │ Returns: │ │\n│ │ [Send(\"worker\", A), │ │\n│ │ Send(\"worker\", B), │ │\n│ │ Send(\"worker\", C)] │ │\n│ └───────────┬────────────┘ │\n│ │ │\n│ ┌─────────────┼─────────────┐ │\n│ │ │ │ │\n│ ▼ ▼ ▼ │\n│ ┌──────┐ ┌──────┐ ┌──────┐ │\n│ │worker│ │worker│ │worker│ ◀── PARALLEL EXECUTION │\n│ │ (A) │ │ (B) │ │ (C) │ │\n│ └──┬───┘ └──┬───┘ └──┬───┘ │\n│ │ │ │ │\n│ ▼ ▼ ▼ │\n│ result_A result_B result_C │\n│ │ │ │ │\n│ └────────────┼────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌────────────────────────┐ │\n│ │ State Reducer │ │\n│ │ operator.add │ │\n│ │ │ │\n│ │ results = [A, B, C] │ │\n│ └────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 2.3 create_react_agent - Sub-Agent Factory\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ create_react_agent ARCHITECTURE │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ SIGNATURE: │\n│ ────────── │\n│ create_react_agent( │\n│ model: LanguageModelLike | Callable, # Static or dynamic model │\n│ tools: Sequence[BaseTool] | ToolNode, # Tools for the agent │\n│ prompt: Prompt | None = None, # System prompt │\n│ response_format: Schema | None = None, # Structured output │\n│ pre_model_hook: Runnable | None = None, # Before model call │\n│ post_model_hook: Runnable | None = None,# After model call │\n│ state_schema: Type | None = None, # Custom state type │\n│ checkpointer: Checkpointer = None, # For persistence │\n│ interrupt_before: list[str] | None, # HITL breakpoints │\n│ interrupt_after: list[str] | None, # HITL breakpoints │\n│ version: \"v1\" | \"v2\" = \"v2\", # Execution mode │\n│ name: str | None = None, # For sub-graph usage │\n│ ) -> CompiledStateGraph │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ GENERATED GRAPH STRUCTURE: │\n│ │\n│ ┌──────────────────────────────────────────────┐ │\n│ │ StateGraph │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────┐ │ │\n│ │ │ pre_model_hook │ │ │\n│ │ │ (optional: message trimming, etc.) │ │ │\n│ │ └────────────────┬────────────────────────┘ │ │\n│ │ │ │ │\n│ │ ▼ │ │\n│ ┌─────────┐ │ ┌─────────────────────────────────────────┐ │ │\n│ │ START │──────▶│ │ agent │ │ │\n│ └─────────┘ │ │ • Applies prompt │ │ │\n│ │ │ • Calls model │ │ │\n│ │ │ • Returns AIMessage │ │ │\n│ │ └────────────────┬────────────────────────┘ │ │\n│ │ │ │ │\n│ │ ▼ │ │\n│ │ ┌─────────────────────────────────────────┐ │ │\n│ │ │ should_continue │ │ │\n│ │ │ (conditional edge) │ │ │\n│ │ └────────┬────────────────┬───────────────┘ │ │\n│ │ │ │ │ │\n│ │ tool_calls? no tool_calls │ │\n│ │ │ │ │ │\n│ │ ▼ ▼ │ │\n│ │ ┌────────────────┐ ┌──────────────────┐ │ │\n│ │ │ tools │ │ post_model_hook │ │ │\n│ │ │ (ToolNode) │ │ (optional) │ │ │\n│ │ └───────┬────────┘ └────────┬─────────┘ │ │\n│ │ │ │ │ │\n│ │ │ ▼ │ │\n│ │ │ ┌───────────────────┐ │ │\n│ │ │ │ structured_output │ │ │\n│ │ │ │ (if response_ │ │ │\n│ │ │ │ format set) │ │ │\n│ │ │ └─────────┬─────────┘ │ │\n│ │ │ │ │ │\n│ │ │ ▼ │ │\n│ │ └─────────▶ ┌─────────┐ │ │\n│ │ │ END │ │ │\n│ │ └─────────┘ │ │\n│ │ │ │\n│ └──────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 2.4 Version v1 vs v2 Tool Execution\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOOL EXECUTION VERSIONS │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ VERSION v1 (Legacy) │\n│ ═══════════════════ │\n│ │\n│ ┌─────────────┐ │\n│ │ agent │ │\n│ │ (AIMsg │ │\n│ │ w/ 3 │ │\n│ │ tool_calls│ │\n│ └──────┬──────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────────────────────┐ │\n│ │ tools (ToolNode) │ │\n│ │ │ │\n│ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │\n│ │ │ tool_1 │ │ tool_2 │ │ tool_3 │ │ ◀── All in SAME node │\n│ │ └────────┘ └────────┘ └────────┘ │ (parallel within) │\n│ │ │ │\n│ │ Single message with all results │ │\n│ └─────────────────────────────────────────────┘ │\n│ │\n│ │\n│ VERSION v2 (Current - Uses Send API) │\n│ ════════════════════════════════════ │\n│ │\n│ ┌─────────────┐ │\n│ │ agent │ │\n│ │ (AIMsg │ │\n│ │ w/ 3 │ │\n│ │ tool_calls│ │\n│ └──────┬──────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────────────────────┐ │\n│ │ should_continue │ │\n│ │ │ │\n│ │ Returns: [ │ │\n│ │ Send(\"tools\", ToolCallWithContext( │ │\n│ │ tool_call=call_1, state=state)), │ │\n│ │ Send(\"tools\", ToolCallWithContext( │ │\n│ │ tool_call=call_2, state=state)), │ │\n│ │ Send(\"tools\", ToolCallWithContext( │ │\n│ │ tool_call=call_3, state=state)), │ │\n│ │ ] │ │\n│ └───────────────────┬─────────────────────────┘ │\n│ │ │\n│ ┌─────────────┼─────────────┐ │\n│ │ │ │ │\n│ ▼ ▼ ▼ │\n│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │\n│ │ tools │ │ tools │ │ tools │ ◀── SEPARATE Send instances │\n│ │ (call_1) │ │ (call_2) │ │ (call_3) │ (true parallelism) │\n│ └──────────┘ └──────────┘ └──────────┘ │\n│ │\n│ │\n│ ADVANTAGES OF v2: │\n│ • Human-in-the-loop can pause between individual tool calls │\n│ • Better interrupt/resume granularity │\n│ • State preserved per-tool-call via ToolCallWithContext │\n│ • More resilient to long-running tools │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 2.5 ToolNode Execution Algorithm\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ TOOLNODE EXECUTION ALGORITHM │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INITIALIZATION: │\n│ ═══════════════ │\n│ │\n│ def __init__(self, tools, handle_tool_errors, messages_key, ...): │\n│ # Build tool registry │\n│ self._tools_by_name = {tool.name: tool for tool in tools} │\n│ │\n│ # Pre-compute injection specs (ONCE, not per-call) │\n│ self._injected_args = { │\n│ tool.name: _get_all_injected_args(tool) │\n│ for tool in tools │\n│ } │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ EXECUTION FLOW (_func / _afunc): │\n│ ═════════════════════════════════ │\n│ │\n│ ┌─────────────────────────────┐ │\n│ │ INPUT │ │\n│ │ (state dict or message │ │\n│ │ list or ToolCallWithCtx) │ │\n│ └─────────────┬───────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────┐ │\n│ │ _parse_input() │ │\n│ │ │ │\n│ │ Extract tool_calls from: │ │\n│ │ • Last AIMessage │ │\n│ │ • Direct tool_call list │ │\n│ │ • ToolCallWithContext │ │\n│ └─────────────┬───────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────┐ │\n│ │ Build ToolRuntime for │ │\n│ │ each tool call: │ │\n│ │ │ │\n│ │ ToolRuntime( │ │\n│ │ state=extracted_state, │ │\n│ │ tool_call_id=call[\"id\"], │ │\n│ │ config=cfg, │ │\n│ │ context=runtime.context, │ │\n│ │ store=runtime.store, │ │\n│ │ stream_writer=..., │ │\n│ │ ) │ │\n│ └─────────────┬───────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ PARALLEL EXECUTION │ │\n│ │ │ │\n│ │ with get_executor_for_config(config) as executor: │ │\n│ │ outputs = executor.map( │ │\n│ │ self._run_one, │ │\n│ │ tool_calls, │ │\n│ │ input_types, │ │\n│ │ tool_runtimes │ │\n│ │ ) │ │\n│ │ │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────┐ │\n│ │ _combine_tool_outputs() │ │\n│ │ │ │\n│ │ • Regular: {messages: [...]}│ │\n│ │ • Command: [Command(...)] │ │\n│ │ • Mixed: both types │ │\n│ └─────────────────────────────┘ │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ SINGLE TOOL EXECUTION (_run_one): │\n│ ══════════════════════════════════ │\n│ │\n│ ┌─────────────────────────────┐ │\n│ │ Build ToolCallRequest │ │\n│ │ │ │\n│ │ request = ToolCallRequest(│ │\n│ │ tool_call=call, │ │\n│ │ tool=tools_by_name[...],│ │\n│ │ state=state, │ │\n│ │ runtime=tool_runtime, │ │\n│ │ ) │ │\n│ └─────────────┬───────────────┘ │\n│ │ │\n│ ┌──────────┴──────────┐ │\n│ │ │ │\n│ wrap_tool_call? No wrapper │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌───────────────┐ ┌───────────────────┐ │\n│ │ Call wrapper │ │ _execute_tool_ │ │\n│ │ with execute │ │ sync() directly │ │\n│ │ callback │ │ │ │\n│ └───────────────┘ └───────────────────┘ │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ ARGUMENT INJECTION (_inject_tool_args): │\n│ ═══════════════════════════════════════ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ Pre-computed _InjectedArgs structure: │ │\n│ │ │ │\n│ │ _InjectedArgs( │ │\n│ │ state = {\"param_name\": \"state_field\" or None}, │ │\n│ │ store = \"store_param_name\" or None, │ │\n│ │ runtime = \"runtime_param_name\" or None, │ │\n│ │ ) │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n│ INJECTION PROCESS: │\n│ │\n│ 1. STATE INJECTION │\n│ ├─ InjectedState(\"field\") → inject state[\"field\"] │\n│ └─ InjectedState() → inject entire state │\n│ │\n│ 2. STORE INJECTION │\n│ └─ InjectedStore() → inject runtime.store │\n│ │\n│ 3. RUNTIME INJECTION │\n│ └─ ToolRuntime param → inject full ToolRuntime object │\n│ │\n│ # Injected args HIDDEN from LLM schema │\n│ tool_call[\"args\"] = {**original_args, **injected_args} │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 2.6 Command-Based Flow Control\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ COMMAND-BASED FLOW CONTROL │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ Command( │\n│ graph: str | None = None, # Target graph (None=current) │\n│ update: Any | None = None, # State update │\n│ resume: dict | Any = None, # Resume from interrupt │\n│ goto: Send | Sequence | str, # Navigation target │\n│ ) │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ PATTERN 1: Tool Controls Navigation │\n│ ──────────────────────────────────── │\n│ │\n│ @tool │\n│ def decision_tool(query: str) -> Command: │\n│ if \"urgent\" in query: │\n│ return Command( │\n│ update={\"priority\": \"high\"}, │\n│ goto=\"urgent_handler\", # Jump to specific node │\n│ ) │\n│ return Command(goto=END) # End the graph │\n│ │\n│ │\n│ PATTERN 2: Delegate to Parent Graph │\n│ ──────────────────────────────────── │\n│ │\n│ @tool │\n│ def spawn_workers(tasks: list[str]) -> Command: │\n│ return Command( │\n│ graph=Command.PARENT, # Send to parent │\n│ goto=[ │\n│ Send(\"worker\", {\"task\": t}) │\n│ for t in tasks │\n│ ] │\n│ ) │\n│ │\n│ │\n│ PATTERN 3: Resume from Interrupt │\n│ ──────────────────────────────── │\n│ │\n│ # In node: │\n│ answer = interrupt(\"What should I do?\") │\n│ │\n│ # Client resumes with: │\n│ graph.stream(Command(resume=\"proceed\"), config) │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ COMMAND FLOW DIAGRAM: │\n│ │\n│ ┌───────────────────────────────────────────────────────────────┐ │\n│ │ TOOL NODE │ │\n│ │ │ │\n│ │ tool execution returns Command │ │\n│ └───────────────────────────┬───────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌───────────────────────────────────────────────────────────────┐ │\n│ │ _validate_tool_command() │ │\n│ │ │ │\n│ │ • Ensure ToolMessage exists for current graph │ │\n│ │ • Process Command.update │ │\n│ │ • Validate Command.goto targets │ │\n│ └───────────────────────────┬───────────────────────────────────┘ │\n│ │ │\n│ ┌──────────────┴──────────────┐ │\n│ │ │ │\n│ graph == None graph == PARENT │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌────────────────────────┐ ┌────────────────────────┐ │\n│ │ Apply to CURRENT │ │ Bubble up to │ │\n│ │ graph │ │ PARENT graph │ │\n│ │ │ │ │ │\n│ │ • Update state │ │ • ParentCommand │ │\n│ │ • Navigate via goto │ │ exception raised │ │\n│ └────────────────────────┘ └────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 2.7 Interrupt & Resume Flow\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ INTERRUPT & RESUME FLOW │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ INTERRUPT MECHANISM: │\n│ ════════════════════ │\n│ │\n│ ┌────────────────────────────────────────────────────────────────┐ │\n│ │ NODE EXECUTION │ │\n│ │ │ │\n│ │ def approval_node(state): │ │\n│ │ # First call: raises GraphInterrupt │ │\n│ │ # Resume call: returns stored value │ │\n│ │ answer = interrupt(\"Approve action?\") │ │\n│ │ return {\"approved\": answer == \"yes\"} │ │\n│ │ │ │\n│ └─────────────────────────────┬──────────────────────────────────┘ │\n│ │ │\n│ FIRST CALL │ │\n│ ▼ │\n│ ┌─────────────────────────────────────────────────────────────────┐ │\n│ │ interrupt() INTERNALS │ │\n│ │ │ │\n│ │ 1. Get config from context │ │\n│ │ 2. Increment interrupt_counter (scratchpad.idx) │ │\n│ │ 3. Check for resume values (scratchpad.resume) │ │\n│ │ ├─ Found at idx → return resume[idx] │ │\n│ │ └─ Not found → raise GraphInterrupt │ │\n│ │ │ │\n│ │ raise GraphInterrupt(( │ │\n│ │ Interrupt( │ │\n│ │ value=\"Approve action?\", │ │\n│ │ id=xxh3_hash(checkpoint_ns) │ │\n│ │ ), │ │\n│ │ )) │ │\n│ └─────────────────────────────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────────────────────────────────────────┐ │\n│ │ EXECUTION HALTS │ │\n│ │ │ │\n│ │ • State checkpointed │ │\n│ │ • Interrupt info returned to client: │ │\n│ │ {\"__interrupt__\": (Interrupt(value=\"...\", id=\"...\"),)} │ │\n│ └─────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ RESUME MECHANISM: │\n│ ═════════════════ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────┐ │\n│ │ CLIENT RESUMES │ │\n│ │ │ │\n│ │ # Option 1: Resume with value │ │\n│ │ graph.stream(Command(resume=\"yes\"), config) │ │\n│ │ │ │\n│ │ # Option 2: Resume specific interrupt by ID │ │\n│ │ graph.stream(Command(resume={\"abc123\": \"yes\"}), config) │ │\n│ └─────────────────────────────────────────────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────────────────────────────────────────┐ │\n│ │ NODE RE-EXECUTES │ │\n│ │ │ │\n│ │ • Node runs FROM THE START │ │\n│ │ • interrupt() called again │ │\n│ │ • This time: scratchpad.resume[idx] exists │ │\n│ │ • Returns \"yes\" instead of raising │ │\n│ │ │ │\n│ └─────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ MULTIPLE INTERRUPTS IN SAME NODE: │\n│ ══════════════════════════════════ │\n│ │\n│ def multi_approval_node(state): │\n│ step1 = interrupt(\"Approve step 1?\") # idx=0 │\n│ step2 = interrupt(\"Approve step 2?\") # idx=1 │\n│ step3 = interrupt(\"Approve step 3?\") # idx=2 │\n│ return {\"steps\": [step1, step2, step3]} │\n│ │\n│ # Resume with list: │\n│ graph.stream(Command(resume=[\"yes\", \"no\", \"yes\"]), config) │\n│ │\n│ # Or resume one at a time (3 separate calls): │\n│ graph.stream(Command(resume=\"yes\"), config) # step1 │\n│ graph.stream(Command(resume=\"no\"), config) # step2 │\n│ graph.stream(Command(resume=\"yes\"), config) # step3 │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n# 3. Execution Flow Diagrams\n\n## 3.1 Complete Agent Execution Cycle\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ COMPLETE AGENT EXECUTION CYCLE │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────┐ │\n│ │ USER │ │\n│ │ INPUT │ │\n│ └────┬────┘ │\n│ │ │\n│ ▼ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ SUPERSTEP LOOP │ │\n│ │ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ 1. LOAD CHECKPOINT (if exists) │ │ │\n│ │ │ • Restore channel values │ │ │\n│ │ │ • Restore versions_seen │ │ │\n│ │ │ • Check for pending interrupts │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │ │\n│ │ ▼ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ 2. DETERMINE NEXT TASKS │ │ │\n│ │ │ • Check conditional edges │ │ │\n│ │ │ • Process Send objects │ │ │\n│ │ │ • Filter by versions_seen │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │ │\n│ │ no tasks? │ tasks to run │ │\n│ │ ┌───────────────┴───────────────┐ │ │\n│ │ │ │ │ │\n│ │ ▼ ▼ │ │\n│ │ ┌────────────┐ ┌─────────────────────────────┐ │ │\n│ │ │ EXIT │ │ 3. EXECUTE TASKS │ │ │\n│ │ │ LOOP │ │ (parallel) │ │ │\n│ │ └────────────┘ │ │ │ │\n│ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │\n│ │ │ │task1│ │task2│ │task3│ │ │ │\n│ │ │ └──┬──┘ └──┬──┘ └──┬──┘ │ │ │\n│ │ │ │ │ │ │ │ │\n│ │ └─────┼──────┼──────┼────────┘ │ │\n│ │ │ │ │ │ │\n│ │ ▼ ▼ ▼ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ 4. APPLY UPDATES TO CHANNELS │ │ │\n│ │ │ • Run reducers (e.g., add_messages) │ │ │\n│ │ │ • Update channel_versions │ │ │\n│ │ │ • Handle Overwrite values │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │ │\n│ │ ▼ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ 5. SAVE CHECKPOINT │ │ │\n│ │ │ • Serialize channel_values │ │ │\n│ │ │ • Store metadata (step, source, parents) │ │ │\n│ │ │ • Persist pending_writes │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │ │\n│ │ ▼ │ │\n│ │ ┌─────────────────────────────────────────────────────────────┐ │ │\n│ │ │ 6. YIELD STATE UPDATE │ │ │\n│ │ │ • stream_mode=\"values\": full state │ │ │\n│ │ │ • stream_mode=\"updates\": node outputs │ │ │\n│ │ │ • stream_mode=\"messages\": LLM tokens │ │ │\n│ │ └─────────────────────────────────────────────────────────────┘ │ │\n│ │ │ │ │\n│ │ └──────────────┐ │ │\n│ │ │ │ │\n│ │ LOOP BACK TO STEP 2 │ │\n│ │ │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 3.2 Nested Sub-Agent Execution\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ NESTED SUB-AGENT EXECUTION │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌───────────────────────────────────────────────────────────────────────┐ │\n│ │ PARENT GRAPH │ │\n│ │ │ │\n│ │ ┌────────────┐ │ │\n│ │ │ coordinator│ │ │\n│ │ │ node │ │ │\n│ │ └─────┬──────┘ │ │\n│ │ │ │ │\n│ │ │ Returns: [Send(\"coding_agent\", task1), │ │\n│ │ │ Send(\"research_agent\", task2)] │ │\n│ │ │ │ │\n│ │ ┌─────┴─────────────────────────────────────────┐ │ │\n│ │ │ │ │ │\n│ │ ▼ ▼ │ │\n│ │ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │ │\n│ │ │ coding_agent │ │ research_agent │ │ │\n│ │ │ (compiled sub-graph) │ │ (compiled sub-graph) │ │ │\n│ │ │ │ │ │ │ │\n│ │ │ ┌────────────────────────┐│ │ ┌────────────────────────┐ │ │ │\n│ │ │ │ Has own: ││ │ │ Has own: │ │ │ │\n│ │ │ │ • State schema ││ │ │ • State schema │ │ │ │\n│ │ │ │ • Checkpointer (opt) ││ │ │ • Checkpointer (opt) │ │ │ │\n│ │ │ │ • Tools ││ │ │ • Tools │ │ │ │\n│ │ │ │ • Model ││ │ │ • Model │ │ │ │\n│ │ │ └────────────────────────┘│ │ └────────────────────────┘ │ │ │\n│ │ │ │ │ │ │ │\n│ │ │ ┌─────┐ ┌─────┐ │ │ ┌─────┐ ┌─────┐ │ │ │\n│ │ │ │agent│──▶│tools│──┐ │ │ │agent│──▶│tools│──┐ │ │ │\n│ │ │ └─────┘ └─────┘ │ │ │ └─────┘ └─────┘ │ │ │ │\n│ │ │ │ │ │ │ │ │ │\n│ │ │ loop──────────┘ │ │ loop──────────┘ │ │ │\n│ │ │ │ │ │ │ │\n│ │ └─────────────┬───────────────┘ └─────────────┬───────────────┘ │ │\n│ │ │ │ │ │\n│ │ │ code_result │ research_result │ │\n│ │ │ │ │ │\n│ │ └────────────┬───────────────────┘ │ │\n│ │ │ │ │\n│ │ ▼ │ │\n│ │ ┌──────────────────────────────────┐ │ │\n│ │ │ State Reducer │ │ │\n│ │ │ (aggregates sub-agent results) │ │ │\n│ │ │ │ │ │\n│ │ │ results: [code_result, │ │ │\n│ │ │ research_result] │ │ │\n│ │ └──────────────────────────────────┘ │ │\n│ │ │ │\n│ └───────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ═══════════════════════════════════════════════════════════════════════ │\n│ │\n│ CHECKPOINTING INHERITANCE: │\n│ ══════════════════════════ │\n│ │\n│ checkpointer = None │ Inherit from parent (recommended) │\n│ checkpointer = True │ Enable independent checkpointing │\n│ checkpointer = False │ Disable even if parent has checkpointer │\n│ checkpointer = saver │ Use specific checkpointer instance │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n# 4. Data Structures Reference\n\n## 4.1 Core Types\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ CORE DATA STRUCTURES │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Checkpoint │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ v: int # Format version (currently 1) │ │\n│ │ id: str # Unique, monotonically increasing │ │\n│ │ ts: str # ISO 8601 timestamp │ │\n│ │ channel_values: dict # Serialized state per channel │ │\n│ │ channel_versions: dict # Version string per channel │ │\n│ │ versions_seen: dict # Node -> channel versions it saw │ │\n│ │ updated_channels: list # Channels updated in this checkpoint │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Send │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ node: str # Target node to invoke │ │\n│ │ arg: Any # Custom state for that invocation │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Command │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ graph: str | None # Target (None=current, PARENT=parent) │ │\n│ │ update: Any | None # State update to apply │ │\n│ │ resume: dict | Any # Resume value for interrupt │ │\n│ │ goto: Send | Sequence | str # Navigation target(s) │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Interrupt │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ value: Any # Value surfaced to client │ │\n│ │ id: str # Unique ID for targeted resume │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ ToolRuntime │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ state: StateT # Current graph state │ │\n│ │ context: ContextT # Runtime context │ │\n│ │ config: RunnableConfig # Runnable configuration │ │\n│ │ stream_writer: StreamWriter # For custom streaming │ │\n│ │ tool_call_id: str | None # Current tool call ID │ │\n│ │ store: BaseStore | None # Persistent storage │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ CompactionControl │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ enabled: Required[bool] # Must be explicitly enabled │ │\n│ │ context_token_threshold: int # Default: 100,000 │ │\n│ │ model: str # Model for summarization │ │\n│ │ summary_prompt: str # Custom summary prompt │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ _InjectedArgs (internal) │ │\n│ ├─────────────────────────────────────────────────────────────────────┤ │\n│ │ state: dict[str, str|None] # param -> state_field (None=full) │ │\n│ │ store: str | None # Param name for store injection │ │\n│ │ runtime: str | None # Param name for runtime injection │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 4.2 State Channel Types\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ STATE CHANNEL TYPES │\n├─────────────────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ LastValue │ │\n│ │ ────────── │ │\n│ │ Default channel type. Last write wins. │ │\n│ │ │ │\n│ │ class State(TypedDict): │ │\n│ │ current_task: str # LastValue (implicit) │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ BinaryOperatorAggregate │ │\n│ │ ──────────────────────── │ │\n│ │ Uses a reducer function to combine values. │ │\n│ │ │ │\n│ │ class State(TypedDict): │ │\n│ │ messages: Annotated[list, add_messages] # Append │ │\n│ │ total: Annotated[int, operator.add] # Sum │ │\n│ │ all_items: Annotated[list, operator.add] # Concat │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ EphemeralValue │ │\n│ │ ────────────── │ │\n│ │ Value exists only within a single superstep. │ │\n│ │ Reset to default after each step. │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ NamedBarrierValue │ │\n│ │ ───────────────── │ │\n│ │ Synchronization primitive. Waits for all named writers. │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Managed Values (Special) │ │\n│ │ ──────────────────────── │ │\n│ │ Not channels - computed/managed by the runtime. │ │\n│ │ │ │\n│ │ class State(TypedDict): │ │\n│ │ remaining_steps: RemainingSteps # Auto-decremented │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Historical Dependency Snapshot (non-production)\n\nThese were the versions considered by the superseded LangGraph design. They\nare not dependencies of the current server runtime.\n\n| Package | Version |\n|---------|---------|\n| anthropic | 0.77.0 |\n| langgraph | 1.0.7 |\n| langgraph-sdk | 0.3.3 |\n| langgraph-checkpoint | 4.0.0 |\n| langchain-core | 1.2.7 |\n| langchain-anthropic | 1.3.1 |\n\n---\n\n## Quick Reference\n\n### Memory Compaction Trigger\n```python\nif total_tokens >= 100_000: # Default threshold\n trigger_compaction()\n```\n\n### Create Sub-Agent\n```python\nsub_agent = create_react_agent(model, tools, name=\"sub_agent\")\nparent_graph.add_node(\"sub_agent\", sub_agent)\n```\n\n### Spawn Parallel Tasks\n```python\ndef router(state):\n return [Send(\"worker\", {\"task\": t}) for t in state[\"tasks\"]]\n```\n\n### Control Flow from Tool\n```python\nreturn Command(update={\"status\": \"done\"}, goto=END)\n```\n\n### Human-in-the-Loop\n```python\nanswer = interrupt(\"Need approval\") # Pauses execution\n# Client: graph.stream(Command(resume=\"approved\"), config)\n```\n","archived":true,"sha256":"f832f1b3da8701965208de4ede990bd2e69a769a7efd01d6af223ca93cbe1e43"},"doc:docs-internal/ARCHIVE/credentials_panel.md":{"id":"doc:docs-internal/ARCHIVE/credentials_panel.md","path":"docs-internal/ARCHIVE/credentials_panel.md","title":"Credentials Panel — Logic Flow Documentation","content":"# Credentials Panel — Logic Flow Documentation\n\n> **ARCHIVED 2026-09-04 — Superseded.** Written against the pre-refactor 3000-line `CredentialsModal.tsx`; that file is now a one-line re-export and every `websocket.py:NNNN` citation here is dead. The credential WS handlers self-register from `server/services/credentials/handlers.py` and each plugin's `nodes/<plugin>/_handlers.py`. The §5 invariants are still locked by `server/tests/credentials/` and `client/src/test/`.\n>\n> For current state see:\n>\n> - [frontend_architecture.md → Credentials](../frontend_architecture.md) — config-driven `ProviderConfig` + `useCredentialPanel` model\n> - [credentials_encryption.md](../credentials_encryption.md) — storage pipeline\n> - [client/src/components/credentials/](../../client/src/components/credentials/) — the live modal\n\n> Reference for refactoring [client/src/components/CredentialsModal.tsx](../client/src/components/CredentialsModal.tsx) (~3000 lines).\n> Every claim here cites file + line number so reviewers can validate post-refactor.\n> Companion test suite in [server/tests/credentials/](../server/tests/credentials) and [client/src/test/](../client/src/test) locks in the invariants enumerated in section 5.\n\n---\n\n## 1. Architecture\n\n### 1.1 Layout\nTwo-panel modal:\n- **Left**: category sidebar (8 categories, ~20 items)\n- **Right**: dynamic detail panel keyed off `selectedItem.panelType`\n\nState lives entirely in `CredentialsModal` as `useState` hooks (no Zustand, no context for modal-local state). Cross-cutting status (paired devices, OAuth account info) comes from `WebSocketContext` push broadcasts.\n\n### 1.2 State taxonomy\n\n| Bucket | Variables | Provider scope |\n|---|---|---|\n| Standard API key inputs | `keys`, `validKeys`, `loading`, `models` | OpenAI/Anthropic/Gemini/Groq/Cerebras/OpenRouter/DeepSeek/Kimi/Mistral/Brave/Perplexity/Serper/Maps/Apify |\n| Provider defaults (per-LLM) | `providerDefaults`, `defaultsDirty`, `modelConstraints` | LLM providers only |\n| Usage panels | `usageSummary`, `apiUsage`, `usageExpanded` | LLM (token cost) + Twitter/Maps (API cost) |\n| Twitter-specific | `twitterClientId`, `twitterClientSecret`, `twitterCredentialsStored`, `twitterLoading`, `twitterError` | twitter only |\n| Google-specific | `gmailClientId`, `gmailClientSecret`, `gmailCredentialsStored`, `gmailLoading`, `gmailError` | google only |\n| WhatsApp-specific | `rateLimitConfig`, `rateLimitStats`, `rateLimitExpanded`, `whatsappLoading`, `whatsappError` | whatsapp only |\n| Android-specific | `androidApiKey`, `androidApiKeyStored`, `androidLoading`, `androidError` | android only |\n| Telegram-specific | `telegramToken`, `telegramTokenStored`, `telegramLoading`, `telegramError` | telegram only |\n| Email-specific | `emailProvider`, `emailAddress`, `emailPassword`, `emailImapHost/Port`, `emailSmtpHost/Port`, `emailStored`, `emailLoading`, `emailError` | email only |\n\n### 1.3 Data sources\n\n| Source | Purpose | File |\n|---|---|---|\n| `useApiKeys()` | CRUD + validation + provider defaults + usage + model constraints | [client/src/hooks/useApiKeys.ts](../client/src/hooks/useApiKeys.ts) |\n| `useWhatsApp()` | WhatsApp send/QR/status helpers (also accessible via `WebSocketContext`) | [client/src/hooks/useWhatsApp.ts](../client/src/hooks/useWhatsApp.ts) |\n| `useWebSocket()` | Status getters (`useWhatsAppStatus`, `useAndroidStatus`, `useTwitterStatus`, `useGoogleStatus`, `useTelegramStatus`), `sendRequest<T>(type, data, timeoutMs?)` | [client/src/contexts/WebSocketContext.tsx](../client/src/contexts/WebSocketContext.tsx) |\n\nPush-driven status objects (`whatsappStatus`, `androidStatus`, `twitterStatus`, `googleStatus`, `telegramStatus`) update reactively from broadcast messages — the modal does not poll for them.\n\n---\n\n## 2. Per-Provider Flow Matrix\n\n### 2.1 Pattern A — Simple API key (validated against provider)\n\n**Providers**: openai, anthropic, gemini, groq, cerebras, openrouter, deepseek, kimi, mistral, brave_search, perplexity.\n\n**Credentials stored**: one row in `EncryptedAPIKey` table, key `{session_id}_{provider}`, payload = encrypted API key + `{models: [...]}` JSON.\n\n**Happy path**:\n```\nUser types key in <Input.Password>\n -> handleValidate(provider)\n -> useApiKeys.validateApiKey(provider, key)\n -> WebSocketContext.validateApiKey(provider, key)\n -> ws.send({type: 'validate_api_key', provider, api_key, request_id})\nbackend handle_validate_api_key (websocket.py:990):\n -> ai_service.fetch_models(provider, key) // hits provider /v1/models endpoint\n -> auth_service.store_api_key(provider, key, models, session_id='default')\n -> credentials_db.save_api_key -> EncryptionService.encrypt -> EncryptedAPIKey row\n -> _api_key_cache[session_id_provider] = ApiKeyCacheEntry(key=..., models=[...])\n -> broadcaster.update_api_key_status(provider, valid=True, has_key=True, models=[...])\n -> return {valid: True, models: [...]}\nFrontend resolves Promise:\n -> setValidKeys[provider] = true\n -> setModels[provider] = models\n -> Connected tag rendered\n```\n\n**WebSocket messages used**: `validate_api_key`, `get_stored_api_key`, `save_api_key`, `delete_api_key`, `get_ai_models`.\n\n**Buttons**: Validate (disabled while empty/loading), Delete (only when stored).\n\n**Error surface**: `loading[provider]` cleared in `finally`; `validKeys[provider]` stays `false`; `<Alert type=\"error\">` with message from response.\n\n### 2.2 Pattern B — Simple API key (custom validator)\n\n**Providers**: google_maps, apify.\n\nSame as Pattern A but validation routes to dedicated handler, not the generic `validate_api_key`:\n\n| Provider | Hook method | WS message |\n|---|---|---|\n| google_maps | `validateGoogleMapsKey(key)` | `validate_maps_key` |\n| apify | `validateApifyKey(key)` | `validate_apify_key` |\n\nAfter validation succeeds, the frontend still calls `saveApiKey` (or backend stores it) under the provider name. Storage table identical to Pattern A.\n\n### 2.3 Pattern C — Save-only API key (no validation)\n\n**Providers**: android_remote, serper, twitter_client_id, twitter_client_secret, google_client_id, google_client_secret, telegram, email_*.\n\n`saveApiKey(provider, key)` calls WebSocket `save_api_key` directly. Backend `handle_save_api_key` (websocket.py:1023) skips model fetch and just calls `auth_service.store_api_key(provider, key, models=[])`.\n\n> **Invariant**: `auth_service.store_api_key()` requires `models` as a positional/keyword argument — passing `[]` is mandatory for non-LLM keys. See [server/services/auth.py:46](../server/services/auth.py).\n\n### 2.4 Pattern D — OAuth 2.0 PKCE (Twitter)\n\n**Credentials stored**:\n- API key table: `twitter_client_id`, `twitter_client_secret` (user-entered)\n- OAuth table: `EncryptedOAuthToken(provider='twitter', customer_id='owner')` with access_token + refresh_token + scopes\n\n**Happy path**:\n```\n1. User saves client_id / client_secret\n -> 2x save_api_key WS calls\n2. User clicks Login with Twitter\n -> sendRequest('twitter_oauth_login', {})\n handle_twitter_oauth_login (websocket.py:1062):\n -> auth_service.get_api_key('twitter_client_id')\n -> redirect_uri = get_redirect_uri(websocket, 'twitter') // runtime-derived\n -> oauth.generate_authorization_url()\n -> generates PKCE code_verifier + S256 code_challenge\n -> stores state in _oauth_states[state] with code_verifier + redirect_uri\n -> returns {success, url, state}\n3. Frontend window.open(response.url, '_blank')\n4. User authorizes on x.com -> X redirects to /api/twitter/callback?code=...&state=...\n5. routers/twitter.py callback:\n -> oauth.exchange_code(code, state) // pops state, exchanges via PKCE\n -> auth_service.store_oauth_tokens('twitter', access, refresh, scopes=...)\n6. Frontend periodically calls sendRequest('twitter_oauth_status')\n handle_twitter_oauth_status (websocket.py:1104):\n -> auth_service.get_oauth_tokens('twitter') // OAuth table, NOT api_key table\n -> oauth.get_user_info(access_token)\n -> on 401: oauth.refresh_access_token(refresh) + re-store\n -> returns {connected, username, user_id, name, profile_image_url, verified}\n```\n\n**Logout path**: `sendRequest('twitter_logout')` → `handle_twitter_logout` (websocket.py:1179) revokes both tokens at REVOKE_URL, then `auth_service.remove_oauth_tokens('twitter')`. Stale legacy `twitter_access_token` API-key entries are best-effort cleaned (websocket.py:1217).\n\n**PKCE invariants**:\n- `code_verifier`: 96 random bytes → urlsafe base64 → trimmed to 128 chars (twitter_oauth.py:48).\n- `code_challenge = base64url(sha256(code_verifier))` (twitter_oauth.py:59).\n- Authorization URL params include `code_challenge_method=S256`.\n- State is consumed exactly once (`_oauth_states.pop(state)` in `exchange_code`).\n- Authorization codes expire in 30 seconds (X documentation), states expire after 10 minutes (`cleanup_expired_states`).\n\n### 2.5 Pattern E — OAuth 2.0 with offline access (Google Workspace)\n\n**Credentials stored**:\n- API key table: `google_client_id`, `google_client_secret`\n- OAuth table: `EncryptedOAuthToken(provider='google', customer_id='owner')` with access + refresh + email + name + scopes\n\n**Differences from Twitter**:\n- Uses `google-auth-oauthlib` `Flow` rather than hand-rolled PKCE (google-auth-oauthlib auto-generates PKCE under the hood; `code_verifier` is captured and saved into `_oauth_states` so the new `Flow` instance in `exchange_code` can restore it — google_oauth.py:189, 226).\n- Authorization URL params include `access_type=offline` + `prompt=consent` (google_oauth.py:175) — both required to reliably receive a refresh_token.\n- `_get_user_info` calls Google's oauth2/v2 userinfo endpoint to populate email/name/picture (google_oauth.py:258).\n- `handle_google_oauth_status` (websocket.py:1272) proactively refreshes the token via `GoogleOAuth.refresh_credentials` and broadcasts `{type: 'google_status', data: {...}}` to all clients.\n- `handle_google_logout` (websocket.py:1333) clears tokens and broadcasts disconnected status.\n\n**Combined scopes** (loaded from [server/config/google_apis.json](../server/config/google_apis.json)): openid + email + profile + gmail.send/readonly/modify + calendar (full + events) + drive (full + file) + spreadsheets + tasks + contacts (full + readonly).\n\n> **Invariant (load-bearing)**: Google access/refresh tokens are read via `auth_service.get_oauth_tokens('google')`, NEVER via `auth_service.get_api_key('google_access_token')`. The two storage systems are distinct tables with distinct caches. Earlier code mixed them and broke OAuth status.\n\n### 2.6 Pattern F — OAuth via isolated subprocess (Claude)\n\n**Credentials stored**: not in OpenCompany's encrypted DB. The official `@anthropic-ai/claude-code` CLI manages its own credentials file under `CLAUDE_CONFIG_DIR = <DATA_DIR>/claude/` (= `~/.opencompany/claude/` by default), isolated from the user's own `~/.claude/` session. OpenCompany never reads or writes that file; it only writes a synthetic `\"cli-managed\"` marker OAuth token via `auth_service.store_oauth_tokens` so the catalogue's `stored` flag flips. The CLI binary is npm-installed into the shared OpenCompany tree at `<DATA_DIR>/packages/node_modules/.bin/claude[.cmd]`.\n\n**Happy path** (wire keys `claude_code_login` / `claude_code_logout`; handlers in `nodes/agent/claude_code_agent/_handlers.py`, CLI wrappers in `_oauth.py`):\n```\nsendRequest('claude_code_login')\n -> handle_claude_code_login\n -> claude auth status (already logged in? sync marker + return)\n -> else asyncio.create_task(_finalize_claude_login()), return immediately\n -> run_claude_login() -> `claude auth login`\n - binary via claude_binary_path() (npm install --prefix <packages_dir> on miss)\n - env CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/\n - stdin=PIPE (never written) so the native CLI's stdin reader\n blocks instead of EOFing -> its localhost callback server\n stays alive until the browser OAuth flow completes\n - CLI opens browser; user authorizes on claude.ai / console.anthropic.com\n -> claude auth status -> {loggedIn, email, orgName, subscriptionType}\n -> mark_logged_in('claude_code', email, name) + broadcast\n credential.oauth.connected -> FE refetches the catalogue\n```\nThe handler returns `{success: True}` synchronously; the real connect state arrives later via the `credential_catalogue_updated` broadcast (the modal flips Connected within ~2 s of CLI exit).\n\nNo logout WebSocket handler — user can manually delete the credentials file or run `claude logout` separately.\n\n### 2.7 Pattern G — QR pairing (WhatsApp)\n\n**Credentials stored**: nothing in OpenCompany DB. Session lives inside the bundled `whatsapp-rpc` Go service (default port 5683).\n\n**Happy path**:\n```\n1. User clicks Start\n -> sendRequest('whatsapp_start')\n -> backend launches/restarts whatsapp-rpc, which generates QR\n2. broadcast 'whatsapp_status' arrives with status.qr (base64 PNG payload)\n -> WebSocketContext exposes whatsappStatus\n -> CredentialsModal renders <QRCodeDisplay value={whatsappStatus.qr} />\n3. User scans QR with phone -> Go service pairs\n4. broadcast 'whatsapp_status' arrives with connected=true, has_session=true, connected_phone='...'\n -> QR replaced by \"Connected\" descriptions\n```\n\n**Buttons**: Start / Restart (regenerates QR) / Refresh (re-fetches status). All dispatch via `useWhatsApp` or `WebSocketContext`.\n\n**Rate limit collapse panel**:\n- On expand → `getWhatsAppRateLimitConfig()` (`whatsapp_rate_limit_get`) + stats fetch.\n- Edits update `rateLimitConfig`, Save → `setWhatsAppRateLimitConfig()` (`whatsapp_rate_limit_set`).\n- Pause notification with Unpause → `unpauseWhatsAppRateLimit()` (`whatsapp_rate_limit_unpause`).\n\n### 2.8 Pattern H — Relay session (Android)\n\n**Credentials stored**: API key table — `android_remote` (relay auth token).\n\n**Happy path**:\n```\n1. User saves android_remote API key (Pattern C)\n2. User clicks Connect\n -> sendRequest('android_relay_connect', {url: VITE_ANDROID_RELAY_URL, api_key})\n handle_android_relay_connect (websocket.py:1425):\n -> AndroidService.connect_relay(url, key)\n -> returns {success, qr_data, session_token}\n3. Backend broadcasts 'android_status' with paired=false, qr_data, session_token\n -> WebSocketContext exposes androidStatus\n -> CredentialsModal renders QR\n4. User scans QR with companion app -> device pairs\n5. Backend broadcasts 'android_status' with connected=true, paired=true, device_id, device_name\n```\n\n**Two-state model** (load-bearing):\n- `connected` = relay WebSocket up\n- `paired` = at least one Android device paired via relay\n- Reconnect button (`android_relay_reconnect`) issues new QR while keeping relay session.\n- Disconnect (`android_relay_disconnect`) tears down everything.\n\n### 2.9 Pattern I — Bot token + polling (Telegram)\n\n**Credentials stored**: API key table — `telegram`. Owner chat ID auto-captured on first private message and stored as `telegram_owner_chat_id`.\n\n**Happy path**:\n```\n1. User pastes BotFather token, clicks Save\n -> saveApiKey('telegram', token) // Pattern C\n2. User clicks Connect\n -> sendRequest('telegram_connect', {token})\n handle_telegram_connect (websocket.py:1844):\n -> TelegramService.connect(token)\n -> validate via getMe\n -> start long-polling (get_updates_read_timeout=30s)\n -> auth_service.store_api_key('telegram', token, models=[])\n3. broadcast 'telegram_status' arrives with connected=true, bot_username, bot_name, bot_id\n4. First private message captures owner_chat_id -> stored as telegram_owner_chat_id API key\n5. broadcast 'telegram_status' updated with owner_chat_id\n```\n\n**Disconnect**: `telegram_disconnect` stops polling AND removes both `telegram` and `telegram_owner_chat_id` API keys.\n\n**Reconnect**: Re-establishes polling using stored token (no token re-entry).\n\n**Note**: `httpx.ReadError` during long-poll is expected (network/server drops). PTB's network_retry_loop handles it; logged at DEBUG. Polling timeout of 30s on `ApplicationBuilder` is mandatory — default 5s breaks long-polling.\n\n### 2.10 Pattern J — Multi-field IMAP/SMTP (Email)\n\n**Credentials stored** (all in API key table):\n\nAlways:\n- `email_provider` ∈ {gmail, outlook, yahoo, icloud, protonmail, fastmail, custom}\n- `email_address`\n- `email_password` (App Password for Gmail/Outlook/Yahoo, regular for ProtonMail Bridge etc.)\n\nWhen `email_provider == 'custom'` only:\n- `email_imap_host`, `email_imap_port` (string), `email_imap_encryption`\n- `email_smtp_host`, `email_smtp_port` (string), `email_smtp_encryption`\n\nFor named providers (gmail/outlook/...) the IMAP/SMTP host/port come from `server/config/email_providers.json` presets — they are NOT stored as API keys.\n\n**Save flow**:\n```\nhandleEmailSave():\n validate (address required; password required on first save; custom requires hosts/ports)\n -> 3 sequential await saveApiKey() calls (provider, address, password)\n -> when provider == 'custom': 4 additional await saveApiKey() calls (imap_host/port/enc, smtp_host/port/enc)\n -> setEmailPassword('') // security: clear plaintext input after save\n -> setEmailStored(true)\n```\n\n**Update flow**: empty password input means \"keep existing\" — handler checks `!password.trim() && emailStored` and skips the password write.\n\n**Remove flow**: `handleEmailRemove()` issues parallel `removeApiKey` calls for all stored fields.\n\n---\n\n## 3. Cross-Cutting Concerns\n\n### 3.1 Loading convention\n`[name]Loading: string | null` where the string is the action tag (`'login'`, `'save'`, `'connect'`, etc.). Buttons compute `loading={twitterLoading === 'login'}`. Always cleared in `finally`.\n\n### 3.2 Error surfacing\n`[name]Error: string | null`. Cleared on retry attempt (`setXError(null)` at start of handler), set in `catch`, rendered as `<Alert type=\"error\" closable />` near the action area. Never `throw` past the handler.\n\n### 3.3 Dirty tracking (Provider Defaults)\n`defaultsDirty: Record<provider, boolean>`. `updateProviderDefault(provider, key, value)` mutates `providerDefaults` AND sets `defaultsDirty[provider]=true`. Save handler calls `saveProviderDefaults` then clears the flag. Save button is disabled when `!defaultsDirty[provider]`.\n\n### 3.4 Lazy fetching\nUsage panels (`Usage & Costs`, `API Usage`, model constraints) fetch inside `useEffect` gated on `usageExpanded === true`. Avoids paying for queries on every modal open.\n\n### 3.5 Broadcast-driven status\n`whatsappStatus`, `androidStatus`, `twitterStatus`, `googleStatus`, `telegramStatus` are subscribed via `useWebSocket()`. The modal NEVER calls a status WebSocket on mount — initial state arrives via `initial_status` broadcast on WS connect, and updates arrive via dedicated `*_status` broadcast types ([client/src/contexts/WebSocketContext.tsx](../client/src/contexts/WebSocketContext.tsx) message handler switch).\n\nThe \"Refresh\" buttons in OAuth panels (Twitter/Google/Telegram) explicitly call the corresponding status request handler to force a re-check, which in turn re-broadcasts.\n\n### 3.6 Device-flow verification code (CLI-managed providers)\nWhen an oauth-kind provider's `ws.login` response carries a `verification_code` (OAuth device flows: GitHub via `gh auth login --web`, Vercel), `useCredentialPanel.oauthLogin` captures it into transient state (reset on provider switch / logout) and `OAuthConnect` renders it prominently in the info box — large monospace, letter-spaced, `select-all` — alongside opening `url` in a new tab. GitHub's `github.com/login/device` page cannot pre-fill the code, so this display is load-bearing there. Generic: any provider returning `{success, url, verification_code}` gets it for free.\n\n### 3.7 Login gating on required fields only\n`OAuthConnect` disables the Login button via `hasRequiredFields && !stored` where `hasRequiredFields = config.fields?.some(f => f.required)`. Required fields (Google/Twitter client creds, Telegram bot token) gate Login as prerequisites; optional fields (Vercel's `vercel_token`) are an *alternative* auth path and never block it. Fieldless CLI-managed providers (Stripe, GitHub) always have Login enabled.\n\n---\n\n## 4. Backend Contract\n\n### 4.1 WebSocket handler registry\nAll handlers registered in [server/routers/websocket.py](../server/routers/websocket.py) `MESSAGE_HANDLERS` dict (lines ~3089–3153). Each handler:\n- Uses `@ws_handler(*required_fields)` decorator (websocket.py:61) which validates required fields and wraps exceptions into `{success: False, error: str(e)}`.\n- Reads dependencies via `container.auth_service()`, `container.ai_service()`, etc. — never touches `credentials_db` directly.\n- Returns a `Dict[str, Any]` with `success: True` (auto-injected by decorator if missing).\n\n### 4.2 Single point of access\nAll credential reads/writes go through [`AuthService`](../server/services/auth.py):\n- API keys: `store_api_key(provider, api_key, models, session_id='default')` / `get_api_key(provider, session_id)` / `remove_api_key(provider, session_id)` / `get_stored_models(provider, session_id)`.\n- OAuth tokens: `store_oauth_tokens(provider, access, refresh, email=None, name=None, scopes=None, customer_id='owner')` / `get_oauth_tokens(provider, customer_id)` / `remove_oauth_tokens(provider, customer_id)` / `get_oauth_refresh_token(provider, customer_id)` (DB-only — see RFC 9700 below).\n- Memory caches: `_api_key_cache: Dict[str, ApiKeyCacheEntry]` (decrypted API keys + models in one dataclass entry per `{session}_{provider}`) and `_oauth_cache` (access tokens + display fields only). Both hit BEFORE the encrypted DB; `clear_cache()` empties both (called on logout). Per RFC 9700 (OAuth 2.0 BCP, 2024) the `_oauth_cache` does NOT carry `refresh_token` — refresh tokens are long-lived secrets and must not live in process memory; `get_oauth_refresh_token()` reads from the encrypted DB on every call. Pre-Wave-12 the cache was split into `_memory_cache` (key) + `_models_cache` (models) sharing the same key shape with no shared invalidation; now collapsed into one entry so the two values can never drift.\n\n### 4.3 Two-table split\n\n| Table | Storage | Used for |\n|---|---|---|\n| `EncryptedAPIKey` | `{session_id}_{provider}` PK, encrypted single key payload + JSON models | All Pattern A/B/C providers, including `*_client_id` / `*_client_secret` for OAuth providers |\n| `EncryptedOAuthToken` | `(provider, customer_id)` composite, encrypted access + refresh, plus email/name/scopes/expiry | Pattern D/E only — Google + Twitter access/refresh |\n\nProvider × table examples:\n- `google_client_id`, `google_client_secret` → API key table\n- Google access/refresh tokens → OAuth token table under provider=`google`\n- `twitter_client_id`, `twitter_client_secret` → API key table\n- Twitter access/refresh → OAuth token table under provider=`twitter`\n- `telegram` → API key table (Pattern I uses no OAuth table)\n\n### 4.4 Encryption layer\n[server/core/encryption.py](../server/core/encryption.py): `EncryptionService` uses Fernet (AES-128-CBC + HMAC-SHA256) with PBKDF2-SHA256 key derivation (600,000 iterations, OWASP 2024). Salt is 32 random bytes, generated on first DB init and stored in `credentials_metadata` table. The encryption password is the server-scoped `API_KEY_ENCRYPTION_KEY` env var, loaded once at startup ([server/main.py](../server/main.py) lifespan).\n\n`encrypt(plaintext) -> str` / `decrypt(ciphertext) -> str`. Decryption raises `ValueError` on tampering/wrong-key, `RuntimeError` if `initialize()` was never called.\n\n### 4.5 Runtime redirect URI derivation\n[server/services/oauth_utils.py](../server/services/oauth_utils.py) `get_redirect_uri(connection, provider)` derives the OAuth callback URI from the live `WebSocket.base_url` (or `Request.base_url`) — converting `ws(s)` to `http(s)` and appending the path from `config/google_apis.json`. No hardcoded hostnames or ports. Works in dev (`http://localhost:5678/api/google/callback`) and prod (`https://flow.opencompany.sh/api/google/callback`) without env vars.\n\n---\n\n## 5. Refactor Invariants\n\nThese are the non-negotiable behaviours the test suite enforces. The refactor is acceptable iff every test in [server/tests/credentials/](../server/tests/credentials) and [client/src/test/](../client/src/test) still passes without modification.\n\n1. **WebSocket message types** for save/validate/delete/get of any API key are exactly `validate_api_key` / `save_api_key` / `get_stored_api_key` / `delete_api_key`, with payload shape `{provider, api_key, [session_id], [models]}`. The response of `get_stored_api_key` exposes `hasKey` (camelCase post-Wave-12; the WebSocketContext consumes it directly). Note: `ApiKeyStatus.hasKey` was retired on the frontend — \"is stored\" comes from the catalogue's `provider.stored` flag via `useProviderStored(id)` (single source of truth).\n2. **OAuth login flows** never expose `client_secret` in the rendered DOM after save — the input is replaced by a \"Configured\" indicator.\n3. **Google tokens** are read exclusively via `auth_service.get_oauth_tokens('google')`. No call site uses `get_api_key('google_access_token')` or any equivalent.\n4. **Email** with `email_provider='custom'` writes BOTH `email_imap_*` and `email_smtp_*` keys (host + port + encryption for each side). With any other provider, those keys MUST NOT be written.\n5. **Status objects** for whatsapp/android/twitter/google/telegram come from `WebSocketContext` broadcasts. The modal calls the corresponding `*_status` handler ONLY in response to an explicit Refresh click — never on mount, never on a polling timer.\n6. **Provider Defaults** save uses `save_provider_defaults` with payload `{provider, defaults: {...}}` — never `save_api_key`.\n7. **`auth_service.store_api_key`** receives `models` as required keyword arg; non-LLM keys pass `models=[]`.\n8. **`AuthService` is the only route** to `credentials_db`. Routers and handlers must not import or call `CredentialsDatabase` directly.\n9. **PKCE state** is consumed exactly once in `exchange_code`; a second call with the same state returns `{success: False, error: 'Invalid or expired state'}`.\n10. **Twitter PKCE** authorization URL contains `code_challenge_method=S256` and `code_challenge = base64url(sha256(code_verifier))`.\n11. **Google authorization URL** contains `access_type=offline` and `prompt=consent` (otherwise no refresh_token is returned).\n12. **`get_redirect_uri`** strips the path from `connection.base_url` and converts `ws://` → `http://`, `wss://` → `https://`.\n13. **Encryption** is reversible for unicode and large payloads; tampered ciphertext raises `ValueError`; uninitialized service raises `RuntimeError`.\n\n---\n\n## 6. Critical Files Cheat Sheet\n\n| Layer | File | What lives here |\n|---|---|---|\n| UI | [client/src/components/CredentialsModal.tsx](../client/src/components/CredentialsModal.tsx) | All panels, all per-provider state, all click handlers |\n| UI hook | [client/src/hooks/useApiKeys.ts](../client/src/hooks/useApiKeys.ts) | API key CRUD, defaults, usage, constraints |\n| UI hook | [client/src/hooks/useWhatsApp.ts](../client/src/hooks/useWhatsApp.ts) | WhatsApp-specific operations |\n| UI context | [client/src/contexts/WebSocketContext.tsx](../client/src/contexts/WebSocketContext.tsx) | `sendRequest<T>`, push status hooks |\n| WS handlers | [server/routers/websocket.py](../server/routers/websocket.py) | All ~125 handlers; credentials block at 985–1670 |\n| Credential service | [server/services/auth.py](../server/services/auth.py) | Single point of access; memory caches |\n| Encryption | [server/core/encryption.py](../server/core/encryption.py) | Fernet + PBKDF2 |\n| DB | [server/core/credentials_database.py](../server/core/credentials_database.py) | Two encrypted tables + metadata |\n| OAuth (Google) | [server/nodes/google/_oauth.py](../server/nodes/google/_oauth.py) | Flow, PKCE, refresh, service builders |\n| OAuth (Twitter) | [server/nodes/twitter/_oauth.py](../server/nodes/twitter/_oauth.py) | Manual PKCE, token exchange/refresh/revoke |\n| OAuth (Claude) | [server/nodes/agent/claude_code_agent/_oauth.py](../server/nodes/agent/claude_code_agent/_oauth.py) + [_handlers.py](../server/nodes/agent/claude_code_agent/_handlers.py) | CLI-managed `claude auth login` (subprocess, `stdin=PIPE`), `CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/` |\n| OAuth utils | [server/services/oauth_utils.py](../server/services/oauth_utils.py) | Runtime redirect URI derivation |\n| Container | [server/core/container.py](../server/core/container.py) | DI wiring for `auth_service` etc. |\n\n---\n\n## 7. Test Suite Index\n\nRun the matching tests after every refactor commit:\n\n```bash\n# Backend\ncd server && uv run pytest tests/credentials/ -v\n\n# Frontend\ncd client && npm run test\n```\n\nSee [server/tests/credentials/README.md](../server/tests/credentials/README.md) and [client/src/test/README.md](../client/src/test/README.md) for fixture details.\n","archived":true,"sha256":"6ce04006d92f5885c3f091e33ffdaacfe21cd38c3fb289a9b9f883289021bf33"},"doc:docs-internal/ARCHIVE/credentials_scaling/architecture.md":{"id":"doc:docs-internal/ARCHIVE/credentials_scaling/architecture.md","path":"docs-internal/ARCHIVE/credentials_scaling/architecture.md","title":"Credentials Panel Architecture (Scalable to 5000 Providers)","content":"> **ARCHIVED / HISTORICAL (superseded).** This is a point-in-time research/exploration record from before the antd removal. It describes keeping antd inputs via a react-hook-form `Controller`, which never shipped — the live UI is fully shadcn/ui (antd was removed in `ui_migration_plan.md` Phase 7). Kept for rationale only; do not treat as current state.\n\n# Credentials Panel Architecture (Scalable to 5000 Providers)\n\nThe architecture for the OpenCompany credentials panel after scaling work.\nBuilt on the Phase 1 refactor (21-file modular structure) with five additional\nlayers: server-owned registry, bulk-fetch cache, command palette, lazy panels,\nand react-hook-form detail panels.\n\nSee also:\n- `research_production_platforms.md` (not in repo) — evidence base from n8n, Nango, Pipedream, Zapier, Supabase\n- [research_react_stack.md](./research_react_stack.md) — library choices and benchmarks\n- `.claude/plans/typed-splashing-crown.md` (developer-local, not in repo) — execution plan\n\n---\n\n## Five-layer architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 1. BACKEND REGISTRY (Nango-style, JSON for project parity) │\n│ │\n│ server/config/credential_providers.json │\n│ └─ 5000+ entries with `extends` inheritance │\n│ │\n│ server/services/credential_registry.py │\n│ ├─ load_catalogue() parses JSON at startup │\n│ ├─ resolve_extends() deep-merges inherited fields │\n│ ├─ get_all_providers() → list[dict] │\n│ ├─ get_provider(id) → dict │\n│ └─ validated with Pydantic │\n│ │\n│ server/routers/websocket.py │\n│ └─ handle_get_credential_catalogue → one bulk JSON │\n│ │\n│ server/routers/credentials.py │\n│ └─ GET /api/credentials/icon/{id} (cached SVG) │\n└──────────────────────────────┬──────────────────────────────┘\n ▼ one WebSocket call at first modal open\n┌─────────────────────────────────────────────────────────────┐\n│ 2. ZUSTAND STORE (cached catalogue) │\n│ │\n│ client/src/stores/useCredentialRegistry.ts │\n│ ├─ providers: ProviderConfig[] │\n│ ├─ categories: CategoryGroup[] │\n│ ├─ preparedSearch: Fuzzysort.Prepared[] (memoized) │\n│ ├─ fetchOnce() — idempotent, no double-fetch │\n│ ├─ getById(id) — O(1) Map lookup │\n│ ├─ search(query) — fuzzysort.go() <5ms on 5000 items │\n│ └─ Cache lives for app session; invalidated on WS event │\n└──────────────────────────────┬──────────────────────────────┘\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 3. SEARCH + NAVIGATION (cmdk + fuzzysort + virtuoso) │\n│ │\n│ credentials/CredentialsPalette.tsx │\n│ ├─ <Command shouldFilter={false}> │\n│ ├─ <Command.Input> — debounced query │\n│ ├─ <GroupedVirtuoso> — sticky category headers │\n│ │ └─ renders only visible rows at 60fps │\n│ ├─ Keyboard nav (↑↓ Enter Esc) via cmdk built-in │\n│ └─ Ctrl+K opens palette anywhere in the app │\n└──────────────────────────────┬──────────────────────────────┘\n ▼ selected provider id\n┌─────────────────────────────────────────────────────────────┐\n│ 4. LAZY PANEL DISPATCH (React.lazy + Suspense) │\n│ │\n│ credentials/PanelRenderer.tsx │\n│ const PANEL_LOADERS = { │\n│ apiKey: () => import('./panels/ApiKeyPanel'), │\n│ oauth: () => import('./panels/OAuthPanel'), │\n│ qrPairing: () => import('./panels/QrPairingPanel'), │\n│ email: () => import('./panels/EmailPanel'), │\n│ }; │\n│ const Lazy = React.lazy(PANEL_LOADERS[config.kind]); │\n│ <Suspense fallback={<Spin />}><Lazy ... /></Suspense> │\n│ │\n│ Vite auto-chunks each panel (<50 KB each). │\n└──────────────────────────────┬──────────────────────────────┘\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 5. SCHEMA-DRIVEN FORMS (react-hook-form) │\n│ │\n│ credentials/schema/extends.ts │\n│ └─ mergeProperties(base, override) — n8n pattern │\n│ │\n│ credentials/primitives/FieldRenderer.tsx │\n│ ├─ <Controller> wrapping antd inputs │\n│ ├─ Uncontrolled — 5-10× faster than antd Form │\n│ └─ Supports `extends` via merged FieldDef[] │\n│ │\n│ panels/{ApiKey,OAuth,Email}Panel.tsx │\n│ └─ useForm() → RHF, Controller per field │\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Data flow (reading credentials)\n\n```\nUser opens CredentialsModal\n ↓\nCredentialsModal.tsx calls useCredentialRegistry().fetchOnce()\n ↓\nZustand store: if not fetched, sendRequest('get_credential_catalogue')\n ↓\nWebSocket backend: credential_registry.get_all_providers()\n ↓\nYAML loaded (cached at startup) → resolve_extends() → Pydantic-validated list\n ↓\n{ providers: [...5000], categories: [...20], version: \"abc123\" }\n ↓\nZustand stores providers + prepares fuzzysort index\n ↓\nCredentialsPalette renders GroupedVirtuoso\n ↓\nUser presses Ctrl+K or clicks sidebar → search input focus\n ↓\nUser types \"whats\" → fuzzysort.go() → 3ms → filtered list\n ↓\nUser selects WhatsApp → setSelectedId('whatsapp')\n ↓\nPanelRenderer looks up config by id → determines kind='qrPairing'\n ↓\nReact.lazy loads QrPairingPanel chunk (first time) → Suspense spinner\n ↓\nQrPairingPanel renders → calls useCredentialPanel(config, visible)\n ↓\nuseForm() initializes RHF → fields hydrate from stored credentials\n```\n\n---\n\n## Data flow (saving credentials)\n\n```\nUser edits a field\n ↓\nRHF Controller → onChange → form state (uncontrolled, no re-render)\n ↓\nUser clicks Save\n ↓\nhandleSubmit(data) → panel.actions.save(key, value)\n ↓\nuseCredentialPanel execute('save', ...) → setLoading('save')\n ↓\nuseApiKeys.saveApiKey(key, value) → WebSocket → AuthService.store_api_key()\n ↓\nEncryptedAPIKey table (Fernet + PBKDF2 + PBKDF2HMAC)\n ↓\nResponse → setStored(true), clear password field\n```\n\n---\n\n## JSON schema with `extends` inheritance\n\nOpenCompany uses JSON for all backend config (`email_providers.json`, `llm_defaults.json`,\n`pricing.json`, `google_apis.json`). Credential registry follows the same convention.\n\n```json\n{\n \"version\": \"2026.04\",\n \"providers\": {\n \"_ai_base\": {\n \"_abstract\": true,\n \"category\": \"ai\",\n \"category_label\": \"AI Providers\",\n \"kind\": \"apiKey\",\n \"has_defaults\": true,\n \"fields\": [\n { \"key\": \"apiKey\", \"label\": \"API Key\", \"type\": \"password\", \"required\": true }\n ]\n },\n \"openai\": {\n \"extends\": \"_ai_base\",\n \"name\": \"OpenAI\",\n \"color\": \"green\",\n \"fields\": [\n { \"key\": \"apiKey\", \"placeholder\": \"sk-...\" }\n ]\n },\n \"anthropic\": {\n \"extends\": \"_ai_base\",\n \"name\": \"Anthropic\",\n \"color\": \"orange\",\n \"fields\": [\n { \"key\": \"apiKey\", \"placeholder\": \"sk-ant-...\" }\n ]\n },\n \"gemini\": {\n \"extends\": \"_ai_base\",\n \"name\": \"Gemini\",\n \"color\": \"cyan\",\n \"fields\": [\n { \"key\": \"apiKey\", \"placeholder\": \"AIza...\" }\n ]\n }\n }\n}\n```\n\n**`credential_registry.resolve_extends()` behavior**:\n1. Walk providers in YAML order\n2. If `extends:` field set, deep-merge parent first, then override with child fields\n3. For array fields (`fields`, `statusRows`, `actions`): merge by `key` — child\n entries replace parent entries with the same key; unmatched child entries append\n4. `_abstract: true` providers are resolved but excluded from `get_all_providers()`\n5. Cycle detection: throw on self-reference or loops\n\n---\n\n## Why this architecture?\n\n### Why server-owned JSON?\n- **Zero per-provider TypeScript.** Adding a new provider = editing one JSON entry.\n- Git diffs stay readable as the catalogue grows.\n- Non-engineers (support team, partners) can PR new providers without touching code.\n- Parsed once at server startup, cached in memory. No runtime parsing cost per request.\n- **Matches existing project convention**: every other backend config file is JSON\n (`email_providers.json`, `llm_defaults.json`, `pricing.json`, `google_apis.json`).\n No new dependencies, stdlib `json` only.\n\n### Why one bulk WebSocket fetch?\n- At 5000 providers × ~200 bytes/entry = ~1 MB JSON. Transferable in one call, loadable\n in <500ms over a local WebSocket.\n- Cached in Zustand for the app session — no re-fetch on modal reopen.\n- Matches n8n's proven pattern (they do it at 400 providers; we scale to 5000).\n\n### Why `react-virtuoso` over antd Menu?\n- **antd Menu has no virtualization**. At 1000+ items it mounts every `<Menu.Item>`\n to the DOM, killing initial render performance.\n- `react-virtuoso`'s `GroupedVirtuoso` gives sticky category headers for free.\n- 18.8 KB gz — acceptable cost for the scalability win.\n\n### Why cmdk + fuzzysort over antd Select `filterable`?\n- antd Select's substring filter is O(N) per keystroke with no ranking — at 5000\n items users can't find anything useful.\n- cmdk provides keyboard navigation + accessibility out of the box.\n- fuzzysort is the fastest JS fuzzy search (3× faster than Fuse.js).\n- Combined cost: ~21 KB gz.\n\n### Why React.lazy per panel?\n- Each panel (ApiKeyPanel, OAuthPanel, QrPairingPanel, EmailPanel) is 40-80 lines\n but pulls in different deps (e.g., QrPairingPanel depends on `QRCodeDisplay` +\n `useWhatsApp`; EmailPanel depends on provider preset logic).\n- Lazy-loading them drops initial credentials modal JS by ~60%.\n- Vite handles chunking automatically — no config needed.\n\n### Why react-hook-form over antd Form.useForm()?\n- Uncontrolled by default → ~2ms per keystroke vs 18ms for antd Form at 200 fields.\n- Critical for the `ProviderDefaultsSection` (AI provider defaults with 8+ fields).\n- Keeps antd components via `<Controller>` — we're swapping the state engine,\n not the UI kit.\n\n### Why `extends` inheritance?\n- Today, 9 AI providers duplicate the same `fields: [{key: 'apiKey', ...}]` config.\n- With `extends: _ai_base`, each entry is 4 lines instead of 12.\n- At 5000 providers, inheritance is the difference between a 1 MB YAML and a 3 MB YAML.\n\n---\n\n## Performance targets\n\n| Metric | Current (monolith) | Phase 1 refactor | Phase 2 (after scaling) | Target |\n|--------|--------------------|--------------------|--------------------------|---------|\n| CredentialsModal initial JS | ~180 KB | ~180 KB | ~100 KB | <150 KB |\n| Per-panel chunk | N/A (monolithic) | N/A | <50 KB each | <50 KB |\n| Sidebar initial render (20 providers) | 50 ms | 40 ms | 30 ms | <50 ms |\n| Sidebar initial render (5000 providers) | crashes | 3000 ms (DOM bloat) | <200 ms (virtualized) | <300 ms |\n| Search latency (5000 items) | N/A (no search) | N/A | <5 ms | <10 ms |\n| Scroll at row 2000 | N/A | ~20 fps (jank) | 60 fps | ≥60 fps |\n| Catalogue WebSocket fetch (5000 entries) | N/A | N/A | ~300 ms | <500 ms |\n\n---\n\n## Migration safety\n\n1. **Worktree**: `feature/credentials-scaling` branched from main with Phase 1\n refactor cherry-picked on top. No changes to main until verified.\n2. **Original import site preserved**: `client/src/components/CredentialsModal.tsx`\n remains a 1-line re-export. All existing usages unchanged.\n3. **Backwards-compatible YAML**: ~~can serve the current 20 providers from YAML while\n the old `providers.tsx` is still present. Flip the switch when the YAML path is\n proven. Delete `providers.tsx` only after manual verification.~~ **DONE (Wave 12 follow-up)** — `providers.tsx` deleted; the server-driven catalogue (`server/config/credential_providers.json` → `useCatalogueQuery`) is the single source of truth. Cold-boot renders a `<Skeleton>` palette; server-unreachable shows an explicit error state.\n4. **Feature flag** (optional): `VITE_USE_YAML_CREDENTIALS=true` — gates the new\n Zustand store fetch vs the old inline array. Enables A/B testing in dev.\n5. **No main branch touches** until the full verification checklist passes.\n\n---\n\n## Files touched\n\nSee `.claude/plans/typed-splashing-crown.md` (developer-local, not in repo)\nsection \"Critical files to modify/create\" for the exhaustive list.\n\nSummary:\n- **New**: 9 files (3 research MDs, 1 YAML, 4 Python, 2 TypeScript stores, 1 palette, 1 schema helper)\n- **Modified**: 8 files (worktree credentials module + package.json + CLAUDE.md)\n- **Deleted**: 1 file (`credentials/providers.tsx`) — done in Wave 12 follow-up commit `c94a610`. Server-driven catalogue is now the single source of truth.\n\n---\n\n## Status: plan approved, execution in progress\n\nThis document is authoritative for the architecture. If implementation deviates,\nupdate this file and the plan file together.\n\n---\n\n## Addendum — Revised architecture (IndexedDB + TanStack Query + runtime targets)\n\nThe base 5-layer architecture above is correct but incomplete. Runtime/memory research revealed a sixth layer (IndexedDB persistence) and refined Phase 3 (TanStack Query owns the catalogue, Zustand holds UI state only). The revised architecture is **6 layers**:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ 1. BACKEND REGISTRY │\n│ server/config/credential_providers.json │\n│ server/services/credential_registry.py │\n│ - load_catalogue() parses JSON once at startup │\n│ - resolve_extends() deep-merges inherited fields │\n│ - content-sha256 version hash │\n│ server/routers/websocket.py │\n│ - handle_get_credential_catalogue │\n│ - handle_save_credential (+ idempotency key dedupe) │\n│ server/routers/credentials.py │\n│ - GET /api/credentials/icon/{id} (long-lived cache) │\n└──────────────────────────────┬──────────────────────────────┘\n ▼ WebSocket bulk fetch\n┌─────────────────────────────────────────────────────────────┐\n│ 2. INDEXEDDB PERSISTENCE (NEW) │\n│ idb-keyval — key `credentials:catalogue:v<sha>` │\n│ Warm-start read on app open (<50 ms); background │\n│ revalidate via WebSocket version-hash comparison │\n│ Hydration write deferred via requestIdleCallback │\n│ (avoids 50–200 ms main-thread block at app open) │\n└──────────────────────────────┬──────────────────────────────┘\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 3. TANSTACK QUERY (server cache) + ZUSTAND (UI state) │\n│ useCatalogueQuery() │\n│ - queryKey ['credentialCatalogue'] │\n│ - staleTime Infinity, gcTime 10 min │\n│ - persister experimental_createPersister(idb-keyval) │\n│ useCredentialRegistry (Zustand, UI state ONLY) │\n│ - selectedId, paletteOpen, query │\n│ - NO catalogue, NO derived state, NO preparedSearch │\n│ - Prevents the #1 memory trap: selector closures │\n│ capturing the whole 1.5–2.5 MB catalogue array │\n└──────────────────────────────┬──────────────────────────────┘\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 4. PALETTE (cmdk + fuzzysort + GroupedVirtuoso) │\n│ CredentialsPalette.tsx │\n│ - prepared fuzzysort index via useMemo(providers) │\n│ - startTransition wrapping filter updates (measured │\n│ ~30–70 ms shorter long task vs useDeferredValue) │\n│ - GroupedVirtuoso for sticky category headers │\n│ - DOM pool: 10–50 live nodes regardless of item count │\n└──────────────────────────────┬──────────────────────────────┘\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 5. LAZY PANEL DISPATCH (React.lazy + Suspense) │\n│ PanelRenderer.tsx — unchanged from base plan │\n└──────────────────────────────┬──────────────────────────────┘\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ 6. SCHEMA-DRIVEN FORMS + React Compiler │\n│ credentials/primitives/FieldRenderer.tsx │\n│ - RHF Controller wrapping antd inputs (uncontrolled) │\n│ React Compiler auto-memoizes the whole credentials module │\n│ (scoped via babel-plugin-react-compiler in vite.config) │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Runtime + memory targets (what verification must prove)\n\n| Metric | Target | Measurement method |\n|---|---|---|\n| V8 heap — catalogue retained size | ~1.5–2.5 MB, exactly one retainer (TanStack Query cache) | Chrome DevTools → Memory → Heap Snapshot → filter Array, sort by Retained Size |\n| DOM node count at any scroll position | 10–50 (virtuoso pool) | Elements panel count inside the virtuoso container |\n| Modal 50-cycle heap delta (open/close 50×) | < 1 MB | Allocation timeline before vs after |\n| INP p75 during rapid search typing | < 200 ms (stretch: < 100 ms) | `web-vitals` library `onINP` attribution mode |\n| Search latency on 5000 items | < 10 ms (fuzzysort.go only) | `performance.measure()` around the filter |\n| Catalogue cold fetch (5000 providers, first ever open) | < 500 ms | Network panel timing |\n| Catalogue warm-start (second open, IndexedDB hit) | < 50 ms | Network panel: zero calls; React Profiler commit time |\n| Scroll FPS at row 2000 | 60 fps | DevTools Performance tab |\n\n### Runtime traps to avoid (the non-negotiable list)\n\n1. **Zustand selector capturing the whole catalogue in a closure** — retains 1.5–2.5 MB permanently. Fix: keep derived data in `useMemo` inside components, not in the store.\n2. **`useState(catalogue.filter(...))`** on every render — 1–5 MB GC churn/cycle. Fix: `useMemo`.\n3. **Non-virtualized list** — 5–20 MB DOM + detached-node leaks. Fix: react-virtuoso.\n4. **IndexedDB main-thread blocking write** — 50–200 ms stall. Fix: defer via `requestIdleCallback` after first paint.\n5. **Fuse.js with `shouldSort + includeMatches`** on 5000 items — 10–50 MB transient per query. Fix: stay on fuzzysort.\n\n### Referenced modern architecture sites\n\n- **oboe.com** (inspected at user request, 2026): React + TanStack Router + TanStack Query + dehydrated→hydrated query client + SSR streaming. Our Vite SPA analog is IndexedDB persister + WebSocket version-hash invalidation. Same pattern, different transport.\n- **Sanity Studio** + **Wakelet**: production React Compiler rollouts — 15% INP improvement on already-memoized code, 50–80% on fresh code.\n- **n8n**: `credentials.store.ts` Pinia bulk fetch + `mergeNodeProperties` extends inheritance. Our Phase 3 + Phase 6 directly port this.\n- **Nango**: content-addressed provider manifests with version-keyed delta fetches. We adopt the same version-hash approach but with a single-file catalogue.\n\n### Addendum sources\n\n- React Compiler 1.0 release: https://react.dev/blog/2025/10/07/react-compiler-1\n- TanStack Query `experimental_createPersister`: https://tanstack.com/query/v5/docs/react/plugins/createPersister\n- V8 memory optimization: https://v8.dev/blog/optimizing-v8-memory\n- Chrome DevTools heap snapshots: https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots\n- web-vitals library: https://github.com/GoogleChrome/web-vitals\n- MemLab (Meta): https://engineering.fb.com/2022/09/12/open-source/memlab/\n","archived":true,"sha256":"fd12c164d3291fbc87c78ce41c67917a89494cccde7e397d9f456a61b49fe6cd"},"doc:docs-internal/ARCHIVE/credentials_scaling/research_react_stack.md":{"id":"doc:docs-internal/ARCHIVE/credentials_scaling/research_react_stack.md","path":"docs-internal/ARCHIVE/credentials_scaling/research_react_stack.md","title":"Research: React Stack for a Scalable Credentials Panel","content":"> **ARCHIVED / HISTORICAL (superseded).** This is a point-in-time research/exploration record from before the antd removal. It describes keeping antd inputs via a react-hook-form `Controller`, which never shipped — the live UI is fully shadcn/ui (antd was removed in `ui_migration_plan.md` Phase 7). Kept for rationale only; do not treat as current state.\n\n# Research: React Stack for a Scalable Credentials Panel\n\nBenchmarks, bundle sizes, and recommendations for the React libraries that power\na credentials/settings panel capable of handling thousands of providers without\nperformance degradation.\n\n---\n\n## Recommended stack (~45 KB gz total)\n\n| Concern | Library | Version | Size (gz) | Reason |\n|---------|---------|---------|-----------|--------|\n| Virtualization | `react-virtuoso` | ^4.18.4 | 18.8 KB | Native `GroupedVirtuoso` = sticky category headers for free |\n| Command palette | `cmdk` | ^1.1.1 | 14.9 KB | Used by Linear/Vercel/Raycast, keyboard nav built-in |\n| Fuzzy search | `fuzzysort` | ^3.1.0 | ~6 KB | Fastest JS fuzzy search, ~0.3ms/query on 1K items |\n| Form engine | `react-hook-form` | ^7.72.1 | 11.9 KB | Uncontrolled by default — 5-10× faster than antd Form at 100+ fields |\n| Code splitting | `React.lazy` | (built-in) | 0 KB | Vite auto-chunks dynamic `import()` |\n\n**Total added**: ~45 KB gzipped beyond existing antd.\n\n**Deliberately skipped**:\n- Module Federation — overkill for in-app plugins, +30 KB runtime, build complexity\n- `@rjsf/core` — 28.9 KB + validator (~50 KB total), heavy and opinionated styling\n- `@ant-design/pro-components BetaSchemaForm` — pulls ~200 KB of pro-components\n- `react-window` — v2 is maintained but `react-virtuoso` has better DX for grouped lists\n- antd `Menu virtual` — **antd Menu has no built-in virtualization**, you must replace it\n\n---\n\n## Virtualization\n\n### react-virtuoso v4.18.4 ⭐ recommended\n- **18.8 KB gzipped**, 6.3K GitHub stars, 2.3M weekly downloads\n- **`GroupedVirtuoso` component** gives sticky group headers out of the box\n- Auto-measures variable-height rows without configuration\n- Peer-compatible with antd rendering inside rows\n- Actively maintained (last release Oct 2024)\n\n```tsx\nimport { GroupedVirtuoso } from 'react-virtuoso';\n\n<GroupedVirtuoso\n groupCounts={[9, 3, 1, 1, 2, 2, 1]} // items per category\n groupContent={idx => <CategoryHeader category={categories[idx]} />}\n itemContent={(idx, groupIdx) => <ProviderRow provider={flatItems[idx]} />}\n/>\n```\n\n### @tanstack/react-virtual v3.13.23\n- 6.8K stars, 10.6M weekly downloads, 5 KB gz (core)\n- Headless — you compute group headers yourself via flattened item array with\n `type: 'group' | 'item'` discriminator\n- Best for custom layouts. More flexible but more code than virtuoso.\n\n### react-window v2.2.7\n- 17.1K stars, 5M weekly downloads, ~6 KB gz\n- v2 rewrite released Apr 2026 with better TypeScript\n- Fixed-size lists are fastest; variable-size and grouping require manual work\n\n### antd virtualization support\n- `List`, `Select`, `Table` have `virtual` prop — handle ~10K items fine\n- `Table` virtual uses `rc-virtual-list` internally\n- **antd `Menu` has NO `virtual` prop** — this is why the Phase 1 refactor's\n sidebar uses antd Menu, and at 1000+ items it mounts every item to the DOM.\n Must replace with `react-virtuoso`.\n\n---\n\n## Command palette / search\n\n### cmdk v1.1.1 ⭐ recommended\n- **14.9 KB gzipped** (includes Radix deps)\n- 15.7K GitHub stars, **21.1M weekly downloads (highest in category)**\n- Used by Vercel, Linear, Raycast Web, Radix UI docs\n- Built-in keyboard navigation, fuzzy matching, `shouldFilter={false}` for custom rankers\n- Handles thousands of items because it uses a flattened virtual DOM strategy\n- For >500 rendered matches, pair with `react-virtuoso` inside `<Command.List>`\n\n```tsx\nimport { Command } from 'cmdk';\n\n<Command shouldFilter={false}>\n <Command.Input onValueChange={setQuery} placeholder=\"Search...\" />\n <Command.List>\n {filtered.map(p => (\n <Command.Item key={p.id} onSelect={() => setSelectedId(p.id)}>\n {p.name}\n </Command.Item>\n ))}\n </Command.List>\n</Command>\n```\n\n### fuzzysort v3.1.0 ⭐ recommended\n- ~6 KB gzipped, zero deps, 4.3K stars, 3.9M weekly downloads\n- **Fastest JS fuzzy search** in published benchmarks (3-10× faster than Fuse.js)\n- Pre-indexed via `fuzzysort.prepare()`\n- Last pushed Oct 2024 — stable but slow-moving (good sign: feature-complete)\n\nBenchmark (1000 items, query \"whats\"):\n- fuzzysort: **0.3 ms**\n- Fuse.js: 2.1 ms\n- match-sorter: 1.8 ms\n\nBenchmark (10,000 items):\n- fuzzysort: **3 ms**\n- Fuse.js: 25 ms\n\n```tsx\n// Pre-index once\nconst prepared = useMemo(\n () => providers.map(p => ({ ...p, _p: fuzzysort.prepare(p.name) })),\n [providers]\n);\n\n// Query\nconst filtered = useMemo(() => {\n if (!query) return prepared;\n return fuzzysort.go(query, prepared, { key: '_p', threshold: -1000 })\n .map(r => r.obj);\n}, [query, prepared]);\n```\n\n### fuse.js (alternative)\n- 8.8M weekly downloads, ~13 KB gz\n- Slower than fuzzysort but richer scoring (weighted keys, nested paths, extended search)\n- Better when you need multi-field relevance (e.g., match against both `name` and `description`)\n\n### match-sorter (alternative)\n- 3M weekly downloads, simpler deterministic ranking\n- Good for small sets (<500)\n\n---\n\n## Form rendering\n\n### react-hook-form v7.72.1 ⭐ recommended for detail panels\n- **11.9 KB gzipped**, 44.6K stars, **34.1M weekly downloads**\n- **Uncontrolled by default** — this is the performance win\n- At 100+ fields RHF re-renders ~1 component per keystroke\n- antd `Form.useForm()` re-renders the whole form tree unless you wrap every\n field in `Form.Item` with `shouldUpdate`\n\nBenchmark (200-field form, per keystroke):\n- react-hook-form: **2 ms**\n- antd Form.useForm: 18 ms\n\n```tsx\nimport { useForm, Controller } from 'react-hook-form';\nimport { Input } from 'antd';\n\nconst { control, handleSubmit } = useForm();\n\n<Controller\n name=\"apiKey\"\n control={control}\n render={({ field }) => <Input.Password {...field} />}\n/>\n```\n\nKeep antd **components** as controlled inputs via `Controller`. We're not\nthrowing away antd — only swapping the form state engine.\n\n### @rjsf/core (skipped)\n- 0.93M weekly downloads, 28.9 KB gz + validator (~50 KB total)\n- Standard JSON Schema Form renderer\n- Too heavy and opinionated styling; we want antd inputs\n\n### @ant-design/pro-form BetaSchemaForm (skipped)\n- Schema-driven antd form\n- Pulls ~200 KB gzipped of pro-components\n- Only justified if you already ship pro-components\n\n---\n\n## Lazy loading\n\n### React.lazy + Suspense ⭐ recommended\n- Built into React, zero bundle cost\n- Vite auto-code-splits dynamic `import()` calls\n- Real impact: a 500 KB credentials modal split into per-provider chunks drops\n initial JS by ~400 KB\n- Pattern: lazy-load the detail panel keyed by provider kind; keep the sidebar\n list eager (it's small)\n\n```tsx\n// PanelRenderer.tsx\nconst PANEL_LOADERS = {\n apiKey: () => import('./panels/ApiKeyPanel'),\n oauth: () => import('./panels/OAuthPanel'),\n qrPairing: () => import('./panels/QrPairingPanel'),\n email: () => import('./panels/EmailPanel'),\n};\n\nconst Lazy = useMemo(() => React.lazy(PANEL_LOADERS[config.kind]), [config.kind]);\n\nreturn (\n <Suspense fallback={<Spin />}>\n <Lazy config={config} />\n </Suspense>\n);\n```\n\nVite output:\n```\ndist/assets/ApiKeyPanel-abc.js 12 KB\ndist/assets/OAuthPanel-def.js 18 KB\ndist/assets/QrPairingPanel-ghi.js 22 KB\ndist/assets/EmailPanel-jkl.js 16 KB\ndist/assets/index-main.js 180 KB (was 250 KB)\n```\n\n### Module Federation (skipped)\n- Overkill for in-app plugins\n- Adds ~30 KB runtime + build complexity\n- Only justified when truly separate teams ship independent bundles\n\n---\n\n## Concrete pattern: grouped virtualized sidebar + search + lazy detail\n\n```tsx\nimport { useMemo, useState } from 'react';\nimport { Command } from 'cmdk';\nimport { GroupedVirtuoso } from 'react-virtuoso';\nimport fuzzysort from 'fuzzysort';\n\nfunction CredentialsPalette({ providers, onSelect }) {\n const [query, setQuery] = useState('');\n\n // Pre-index once\n const prepared = useMemo(\n () => providers.map(p => ({ ...p, _p: fuzzysort.prepare(p.name) })),\n [providers]\n );\n\n // Filter on query change\n const filtered = useMemo(() => {\n if (!query) return prepared;\n return fuzzysort.go(query, prepared, { key: '_p', threshold: -1000 })\n .map(r => r.obj);\n }, [query, prepared]);\n\n // Group by category\n const { groupCounts, groupLabels, flatItems } = useMemo(() => {\n const byCategory = new Map<string, typeof filtered>();\n for (const p of filtered) {\n const list = byCategory.get(p.category) ?? [];\n list.push(p);\n byCategory.set(p.category, list);\n }\n const labels = [...byCategory.keys()];\n const counts = labels.map(k => byCategory.get(k)!.length);\n const items = labels.flatMap(k => byCategory.get(k)!);\n return { groupCounts: counts, groupLabels: labels, flatItems: items };\n }, [filtered]);\n\n return (\n <Command shouldFilter={false}>\n <Command.Input value={query} onValueChange={setQuery} placeholder=\"Search credentials...\" />\n <GroupedVirtuoso\n style={{ height: 600 }}\n groupCounts={groupCounts}\n groupContent={idx => <div className=\"group-header\">{groupLabels[idx]}</div>}\n itemContent={idx => (\n <Command.Item onSelect={() => onSelect(flatItems[idx].id)}>\n <flatItems[idx].Icon size={18} /> {flatItems[idx].name}\n </Command.Item>\n )}\n />\n </Command>\n );\n}\n```\n\n---\n\n## Real-world benchmarks\n\nFrom public benchmarks and measurements:\n- **krausest js-framework-benchmark**: `@tanstack/react-virtual` + React hits ~60fps\n at 10K rows; plain antd `List` at 1000+ drops to 15-25fps\n- **cmdk**: handles 5K items smoothly without virtualization; >5K needs virtualized\n `Command.List` (pair with virtuoso or tanstack-virtual)\n- **fuzzysort**: ~0.3ms/query on 1K items, ~3ms on 10K (vs Fuse.js 2ms / 25ms)\n- **RHF vs antd Form at 200 fields**: RHF ~2ms/keystroke, antd Form ~18ms\n\n---\n\n## Decision matrix\n\n| Scale | Virtualize? | Search? | Forms |\n|-------|-------------|---------|-------|\n| <100 providers | No | Substring filter OK | antd Form OK |\n| 100-500 | No | Add cmdk palette | antd Form OK |\n| 500-2000 | Maybe | cmdk + fuzzysort | RHF for detail panels |\n| **2000-5000 (OpenCompany target)** | **Yes, `react-virtuoso`** | **cmdk + fuzzysort** | **RHF** |\n| >5000 | Yes + server pagination | Yes | RHF |\n\n---\n\n## Verification method\n\nAfter implementation, measure:\n1. **Initial bundle**: `pnpm run build` → inspect `dist/assets/` sizes\n2. **Chunks**: Per-panel chunks should appear in `dist/assets/` as separate files\n3. **Runtime**: DevTools Performance tab, scroll sidebar to row 2000 → confirm 60fps\n4. **Search latency**: console.time around `fuzzysort.go()` → <10ms on 1000 items\n5. **Lazy loading**: Network tab → panel chunk loads on first provider selection\n\nTargets:\n- Initial JS bundle: ≥200 KB reduction vs current 3,151-line monolith\n- Per-panel chunks: <50 KB each\n- Search: <10ms on 5000 items\n- Scroll: 60fps on 5000 items\n\n---\n\n## Sources\n\n- react-virtuoso: https://virtuoso.dev\n- @tanstack/react-virtual: https://tanstack.com/virtual\n- cmdk: https://cmdk.paco.me\n- fuzzysort: https://github.com/farzher/fuzzysort\n- react-hook-form: https://react-hook-form.com\n- npm trends comparison: https://npmtrends.com\n- krausest benchmark: https://krausest.github.io/js-framework-benchmark/\n\n---\n\n## Addendum — Runtime performance, heap memory, and 2026 additions\n\nThis addendum reflects research focused specifically on **runtime cost and retained heap** at 5000 providers, not bundle size. The base stack above stays; the additions below are what actually move runtime numbers.\n\n### New stack additions (2026)\n\n| Layer | Library | Why | Runtime cost |\n|---|---|---|---|\n| Server-cache | `@tanstack/react-query@^5` | Canonical 2026 server-cache pattern. Confirmed against oboe.com which uses the dehydrated → hydrated query client pattern. Handles dedupe, stale-while-revalidate, version-keyed invalidation. | ~500 KB–2 MB per query at infinite staleTime; no double-retain with persister |\n| Persistence | `idb-keyval@^6` | ~600 B wrapper around IndexedDB. Paired with TanStack Query's `experimental_createPersister` to warm-start from the previous session's catalogue. | One-shot 2 MB structured-clone write ~50–200 ms — deferred via `requestIdleCallback` |\n| Auto-memoization | `babel-plugin-react-compiler@^1` (React Compiler 1.0, Oct 2025) | Stable. Auto-memoizes hooks/components — stop writing `useMemo` / `useCallback` / `React.memo` manually in the new module. 15–30% re-render reduction on memoized code; 50–80% on fresh code. Measured: Sanity Studio + Wakelet INP 275 → 240 ms. | Zero bundle; eliminates manual memoization boilerplate |\n\n### Hard runtime numbers at 5000 providers (~300–500 B each)\n\n| Measurement | Value | Source |\n|---|---|---|\n| V8 heap floor for catalogue array | ~1.5–2.5 MB retained | [v8.dev/blog/optimizing-v8-memory](https://v8.dev/blog/optimizing-v8-memory) |\n| DOM floor (react-virtuoso) | ~2–5 MB (10–50 live DOM nodes regardless of item count) | virtuoso v4 docs + heap snapshot |\n| DOM floor (non-virtualized) | 50–100+ MB + detached-node leaks on modal close | krausest benchmark extrapolation |\n| fuzzysort.prepare() index | ~600 KB for 5000 entries (1.2–1.5× source string size) | source review ([github.com/farzher/fuzzysort](https://github.com/farzher/fuzzysort)) |\n| fuzzysort.go() per keystroke | ~1–2 ms on 5000 pre-indexed entries | direct measurement |\n| virtuoso re-measure per keystroke | ~5–15 ms (visible rows only) | virtuoso perf docs |\n| React commit phase per keystroke | ~10–30 ms (with React Compiler) | React Compiler release notes |\n| **Total INP per keystroke** | **~20–50 ms** (vs 200 ms budget) | sum of above |\n| RHF 50-field form retained | ~50–100 KB | RHF docs |\n| antd Form.useForm 50-field form retained | ~150–300 KB (full re-render on every keystroke) | antd v5 form docs |\n\n**Conclusion**: at 5000 items with the right stack we have ~150 ms of the 200 ms INP budget unused. We are NOT INP-bound if the stack is wired correctly. The failure mode is heap bloat from bad store shapes or non-virtualized lists, not CPU.\n\n### `startTransition` > `useDeferredValue` for the search input (measured)\n\nContradicts common docs framing. `useTransition` yields a shorter long task (~50–80 ms) than `useDeferredValue` (~80–150 ms) on large filtered lists because you explicitly control *what* gets deferred.\n\n**Decision**: wrap the filter update in `startTransition`, keep the input value in normal state so typing stays synchronous. See [React 19 useTransition docs](https://react.dev/reference/react/useTransition).\n\n```tsx\nconst [query, setQuery] = useState('');\nconst [filtered, setFiltered] = useState(prepared);\nconst handleChange = (v: string) => {\n setQuery(v); // synchronous — input stays responsive\n startTransition(() => { // deferred — filter can be interrupted\n setFiltered(v ? fuzzysort.go(v, prepared, { key: '_p' }).map(r => r.obj) : prepared);\n });\n};\n```\n\n### Top 5 runtime/memory traps that would actually hurt us\n\n1. **Zustand selector capturing the whole catalogue in a closure.** A selector like `(state) => state.providers.filter(...)` retains the entire 1.5–2.5 MB array permanently inside the function's scope. Fix: keep filter/search logic **outside** the store (`useMemo` in the component), or use `useShallow` from `zustand/shallow`. The new `useCredentialRegistry` store holds UI state only — no catalogue, no derived data.\n2. **`useState(catalogue.filter(...))`** on every render — 1–5 MB GC churn per cycle. Fix: `useMemo`, never `useState` for derived data. ([blog.webdevsimplified.com: Never Store Derived State](https://blog.webdevsimplified.com/2019-11/never-store-derived-state/))\n3. **Non-virtualized list** (5000 DOM nodes + 5000 inline handlers) — 5–20 MB DOM + detached-node leaks on modal close. Fix: react-virtuoso.\n4. **IndexedDB main-thread blocking serialization** of a 2 MB snapshot — one-shot `set()` blocks 50–200 ms. Fix: kick the hydration write into `requestIdleCallback` after first paint; the UI is already showing the stale cache from the previous session.\n5. **`Fuse.js` with `shouldSort: true + includeMatches: true`** on 5000 items — transient 10–50 MB allocation per query. Not our plan; called out so we stay on fuzzysort.\n\n### Top 5 false alarms to ignore\n\n- **String interning** of category labels (V8 doesn't auto-intern; manual interning costs more than it saves). See [gist.github.com/metamatt V8 string interning](https://gist.github.com/metamatt/2fedb9249a2b06ebfb83).\n- **`Map<id, obj>` vs plain object** memory delta (~20–40% on a ~2 MB total is noise; both are dwarfed by the catalogue itself).\n- **Per-component React 19 fiber baseline** (~500 B × 50 visible rows = 25 KB — noise).\n- **antd v5 cssinjs \"leak\"** — reference-counted, actively cleaned ([github.com/ant-design/cssinjs](https://github.com/ant-design/cssinjs)), ~5 KB per distinct variant.\n- **cmdk modal open/close cycles** — no known leak in v1.x; listener leaks come from your own modal content.\n\n### Store shape decision (explicit)\n\n- **Primary storage**: flat `ProviderConfig[]` inside TanStack Query's cache — iteration-friendly, minimum V8 overhead, cheapest for react-virtuoso to consume by index.\n- **Derived `providersById: Map<string, ProviderConfig>`** for O(1) lookup during palette selection + panel rendering — built once in a `useMemo`, ~5 % memory overhead on top of the array, negligible.\n- **Do not** store filtered/searched subsets in Zustand. Compute in `useMemo` inside the component that needs them, keyed on `(query, catalogue)`.\n- **`useCredentialRegistry` Zustand store holds UI state only**: `selectedId`, `paletteOpen`, `query`. No catalogue, no derived data.\n\n### Profiling workflow (Phase 8 verification)\n\n1. **Chrome DevTools → Memory → Heap Snapshot** → filter `Array`, sort by Retained Size → **catalogue array appears once at ~1.5–2.5 MB with exactly one retainer (TanStack Query cache)**. Ref: [developer.chrome.com heap snapshots](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots).\n2. **Allocation timeline**: open/close the credentials modal 50 times → **delta < 1 MB** (no retained listeners, no detached DOM, no leaked cmdk instances).\n3. **`web-vitals` library INP attribution mode** in dev:\n ```ts\n import { onINP } from 'web-vitals';\n onINP(metric => console.log('INP:', metric.value, metric.attribution));\n ```\n Confirm p75 < 200 ms during rapid search typing on a 5000-dummy-provider catalogue. ([github.com/GoogleChrome/web-vitals](https://github.com/GoogleChrome/web-vitals))\n4. **React DevTools Profiler flamegraph** → record typing \"whats\" → confirm only the search box + visible virtuoso rows re-render (grey elsewhere).\n5. **MemLab** for CI leak detection: automates snapshot → action → `window.gc()` → snapshot → diff. ([engineering.fb.com/2022/09/12/open-source/memlab](https://engineering.fb.com/2022/09/12/open-source/memlab/))\n\n### Why NOT adopt (explicit rejections)\n\n- **Million.js** — block virtual DOM replacement. Superseded by React Compiler 1.0 (the React team is investing in Compiler, not Million). Doesn't play well with antd v5/v6 cssinjs.\n- **Jotai / Valtio / Legend State** — fine libraries, but Zustand + TanStack Query already covers our UI + server-state needs.\n- **rjsf (@rjsf/core)** — ~50 KB total, heavy and opinionated styling. We want antd inputs.\n- **pro-form BetaSchemaForm** — pulls ~200 KB pro-components; only justified if you already ship pro-components.\n- **Module Federation** — overkill for in-app plugins; ~30 KB runtime + build complexity. Only justified when truly separate teams ship independent bundles.\n- **Lucide-react icon swap** — not applicable to credentials scope; we already use raw SVGs from `client/src/assets/icons/<category>/`, not `@ant-design/icons`.\n\n### Additional sources (2026)\n\n- React Compiler 1.0 release: https://react.dev/blog/2025/10/07/react-compiler-1\n- TanStack Query v5 docs: https://tanstack.com/query/latest\n- TanStack Query `experimental_createPersister`: https://tanstack.com/query/v5/docs/react/plugins/createPersister\n- web-vitals library (INP attribution): https://github.com/GoogleChrome/web-vitals\n- idb-keyval: https://github.com/jakearchibald/idb-keyval\n- Chrome DevTools heap snapshots: https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots\n- MemLab (Meta): https://engineering.fb.com/2022/09/12/open-source/memlab/\n- V8 memory optimization: https://v8.dev/blog/optimizing-v8-memory\n- Cost of JavaScript: https://v8.dev/blog/cost-of-javascript-2019\n- React Compiler + TanStack Query referential stability issue: https://github.com/TanStack/query/issues/34211\n- React useTransition reference: https://react.dev/reference/react/useTransition\n- oboe.com (production reference, inspected at user request) — React + TanStack Router + TanStack Query + SSR dehydrate/hydrate pattern, confirms TanStack Query as the 2026 production default for React server-state layers.\n","archived":true,"sha256":"0b79920ade4bd2411fe0ce79806c97df2f682773e62d429d4393e7091b6e46d6"},"doc:docs-internal/ARCHIVE/litellm_router_migration_rfc.md":{"id":"doc:docs-internal/ARCHIVE/litellm_router_migration_rfc.md","path":"docs-internal/ARCHIVE/litellm_router_migration_rfc.md","title":"LiteLLM Router Migration RFC","content":"# LiteLLM Router Migration RFC\n\n> **ARCHIVED 2026-09-04 — Superseded.** The LiteLLM migration never happened; the native SDK layer replaced LangChain instead. `litellm` appears nowhere in first-party code or dependencies.\n>\n> For current state see:\n>\n> - [native_llm_sdk.md](../native_llm_sdk.md) — the layer that shipped\n\n**Status:** Superseded by [Native LLM SDK](native_llm_sdk.md) · **Owner:** trohitg · **Created:** 2026-07-02 · **Target:** `server/services/llm/` + the chat/agent LLM paths in `server/services/ai.py`\n\n> Historical RFC only. The adopted implementation uses provider-native SDKs,\n> not LiteLLM; dependency and migration claims below are retained solely as\n> design-history context.\n\n---\n\n## 1. Abstract\n\nOpenCompany maintains a fully custom multi-provider LLM layer: a `ChatUnifier` facade over\n12 hand-written provider integrations, plus a parallel LangChain path for the agent loop.\nThis RFC proposes replacing the provider *internals* with [LiteLLM](https://github.com/BerriAI/litellm)\n(`litellm.acompletion`, in-process, exact-pinned, lazy-imported) while keeping every\narchitectural seam OpenCompany actually relies on: the `ChatUnifier` facade, the\n`NodeUserError` error contract, `llm_defaults.json` as the quirk SSOT, our\ntemperature/max-tokens resolution, `fetch_models`, and the pricing/model-registry/\ncompaction services.\n\nThe migration runs in two flag-gated stages:\n\n- **Stage A — chat path**: swap the 4 dedicated provider classes + 8 OpenAI-compat\n registrations behind `ChatUnifier` for one LiteLLM adapter. Net ~-420 production LOC;\n per-provider quirk knowledge (message reshaping, system-split, role mapping, reasoning\n extraction) is outsourced upstream.\n- **Stage B — agent loop**: replace `create_model` + LangChain message shapes in\n `_run_agent_loop` / `execute_chat_agent` / Temporal agent activities with the same\n adapter on protocol types. Deletes the 4-format thinking extractor, the ~20.8s-cold\n `langchain_openai` import class, and 5 dependency pins. Gated on Stage A soak.\n\nLiteLLM's officially announced Rust rewrite (Router Sep 15 2026, full server Dec 1 2026,\nclient-API stability promised) means adopting the SDK surface now inherits the\nperformance work later without a second migration.\n\n---\n\n## 2. Current architecture (verified inventory, 2026-07-02)\n\n### 2.1 The two LLM paths\n\n| Path | Entry | Mechanism | Providers |\n|---|---|---|---|\n| Chat (single completion) | `execute_chat` ([ai.py:1400](../server/services/ai.py#L1400)) → `ChatUnifier.chat()` | Native SDKs behind `ProviderSpec` registry | 12 |\n| Agent loop (tool-calling) | `execute_agent` / `execute_chat_agent` ([ai.py:2105](../server/services/ai.py#L2105)) → `_run_agent_loop` ([ai.py:733](../server/services/ai.py#L733)) with `create_model` ([ai.py:1206](../server/services/ai.py#L1206)) | LangChain classes (`ChatOpenAI`, `ChatAnthropic`, `ChatGoogleGenerativeAI`, `ChatGroq`, `ChatCerebras`) + `bind_tools` | 11 |\n\n### 2.2 Size of the custom layer\n\n| Component | LOC | Files |\n|---|---|---|\n| `services/llm/` core (unifier, registry, protocol, config, factory, messages, vertex) | 796 | unifier 132, config 217, protocol 113, registry 111, factory 75, `__init__` 73, messages 47, vertex 28 |\n| `services/llm/providers/` | 905 | anthropic 203, gemini 268, openai 200, openrouter 99, `_compat` 109, `__init__` 26 |\n| Provider-path code in `services/ai.py` | ~595 of 2,987 | execute_chat, fetch_models, create_model, 4-format thinking extraction, resolution glue |\n| Dedicated tests `tests/llm/` | 1,771 | 11 files (+~480 adjacent chat-path test LOC elsewhere) |\n| Hand-curated metadata | ~630 lines | `llm_defaults.json` 291, `pricing.json` 338 (+ `model_registry.json` 10,536-line OpenRouter-refreshed cache) |\n\n**Total: ~2,300 production LOC + ~2,250 test LOC + ~630 lines of hand-maintained JSON**\ndoing what a maintained OSS library ships as its entire job.\n\n### 2.3 The facade (what stays)\n\n`ChatUnifier` ([services/llm/unifier.py](../server/services/llm/unifier.py), 132 LOC):\n\n- `chat(provider, api_key, messages, model, temperature, max_tokens, thinking, tools) -> LLMResponse`\n- `fetch_models(provider, api_key) -> List[str]` with the `incompatible_models` JSON\n filter (unifier.py:95-98)\n- Typed SDK exceptions (`ProviderSpec.sdk_exception_types`) → `NodeUserError` at exactly\n two catch sites (unifier.py:78-79, 93-94)\n- `{provider}_proxy` credential lookup from the encrypted store (unifier.py:122)\n- Wired once into the DI container (`core/container.py`, `_build_chat_unifier`)\n\nProtocol types ([services/llm/protocol.py](../server/services/llm/protocol.py)):\n`ThinkingConfig(enabled, budget=2048, effort=\"medium\", level=None, format=\"parsed\")`,\n`Message`, `ToolDef`, `ToolCall`, `Usage(input/output/total, cache_creation_tokens,\ncache_read_tokens, reasoning_tokens)`, `LLMResponse(content, thinking, tool_calls,\nusage, model, finish_reason, raw)`.\n\nResolution ([services/llm/config.py](../server/services/llm/config.py)):\n`resolve_max_tokens` (user → ModelRegistry → llm_defaults → 4096, lines 158-172);\n`resolve_temperature` (reasoning → 1.0, anthropic+thinking → 1.0, `fixed_temperature`\nprefix match, provider-range clamp, lines 175-206); `detect_provider_from_model`\n(fallback → openai); `is_model_valid_for_provider` (open-world for\nopenrouter/ollama/lmstudio).\n\n### 2.4 The 16 encoded provider quirks\n\n1. Gemini `thinking_level` is None-by-default — forwarding a fabricated default 400s on\n Vertex 2.5-era models (`providers/gemini.py:72-79`).\n2. Anthropic auto-bumps `max_tokens` to `budget + 1024` when `max_tokens <= budget`\n (`providers/anthropic.py:59-62` — API-required).\n3. Kimi fixed temperature 0.6 for the k2.x product line\n (`llm_defaults.json:227`; prefix-matched so one entry covers the family).\n4. Kimi thinks by default (`thinking_default_on`, `llm_defaults.json:226`); explicit\n disable sends `extra_body={\"thinking\":{\"type\":\"disabled\"}}` — agent path only today.\n5. OpenAI o-series/gpt-5 use `max_completion_tokens`, not `max_tokens`\n (`providers/openai.py:58-64`).\n6. Gemini model dropdown is a curated list (keys of `max_output_tokens`) because Vertex\n rejects `models.list` with API keys (`providers/gemini.py:97-138`,\n `llm_defaults.json:79`).\n7. Ollama/LM Studio have no `default_model` — the dropdown reflects user-installed\n models; empty list signals \"server offline\" (`llm_defaults.json:267-289`).\n8. `proxy_url` (from the `{provider}_proxy` encrypted credential) always overrides\n `base_url`; placeholder `api_key=\"ollama\"` when a proxy/local relay is active.\n9. Thinking extraction handles 4 response formats (`ai.py:621-730`): LangChain\n `content_blocks`, `additional_kwargs.reasoning_content`, `response_metadata` output\n arrays, raw content list.\n10. OpenRouter `[FREE] ` prefix is display-only and stripped before the API call.\n11. Provider detection falls back to `openai` on unknown patterns — a documented\n foot-gun class (\"401 from OpenAI when I picked LM Studio\",\n `constants.py:414-439`).\n12. `fixed_temperature` uses prefix matching so one override covers a model family.\n13. Reasoning models force temperature 1.0 AND omit the parameter from the API call.\n14. Vertex Express keys detected by `\"AQ.\"` prefix (`services/llm/vertex.py:23`) — flips\n google-genai to `vertexai=True`, ignores proxy_url, and is shared with the LangChain\n path (`ai.py:1256`).\n15. Compaction ratio precedence: per-session > per-user > env > `llm_defaults.json`.\n16. `register_local_model` persists ollama/lmstudio context metadata to\n `model_registry.json` across restarts.\n\n### 2.5 Parity nuances (what \"current behavior\" actually is)\n\nThese matter because parity must be defined against reality, not aspiration:\n\n1. The 4-format thinking extractor is **agent-path only** (callers: `ai.py:792`,\n `ai.py:2481`, `services/temporal/agent_activities.py:119,208`). The chat path already\n reads `LLMResponse.thinking` from the unifier.\n2. On the chat path today, groq `reasoning_format` and cerebras `thinking_budget` are\n **silently dropped** — `OpenAIProvider.chat` only applies `reasoning_effort` for\n o-series/gpt-5. Those knobs work only on the LangChain agent path (`ai.py:1336-1347`).\n3. Kimi's thinking-disable (`extra_body`) exists **only** in `create_model`\n (`ai.py:1287-1291`), not on the unifier path.\n4. `_track_token_usage` ([ai.py:1091](../server/services/ai.py#L1091)) is agent-path\n only and consumes LangChain `usage_metadata`; the chat path does not track tokens\n today. `CompactionService.track()` already accepts `cache_read_tokens` /\n `cache_creation_tokens` / `reasoning_tokens` keys (`compaction.py:133-145`).\n\n---\n\n## 3. Problems with the current layer (Motivation)\n\n### 3.1 Cost of adding provider 13 today\n\n| Step | File | Cost |\n|---|---|---|\n| Provider config block (base_url, endpoints, token limits, thinking type, temp range, quirks) | `server/config/llm_defaults.json` | ~25-40 lines, every value hand-researched |\n| Provider implementation | `_compat.py` (OpenAI-compat) or a new dedicated module (cf. gemini.py = 268 LOC) | 1 line best case; ~250 LOC + a new SDK dependency worst case |\n| Detection branch | `constants.py:414-439` — order-sensitive substring matching with a documented bug class | ~5 lines, high foot-gun density |\n| Node package | `server/nodes/model/<provider>_chat_model/` | new package (product surface — no library removes this) |\n| Pricing entries | `server/config/pricing.json` | hand-copied from the provider's pricing page; goes stale silently |\n| Tests | `tests/llm/` | ~50-150 LOC |\n\nLiteLLM removes the implementation row entirely and replaces the hand-curated\ntoken-limit/pricing research with its maintained metadata. The node package and\ndetection rows remain OpenCompany product surface — migration cuts per-provider cost from\n\"~250 LOC + research\" to \"config-only\", not to zero.\n\n### 3.2 Drift risk\n\n- Every provider API change is our emergency, discovered in production: o-series\n `max_completion_tokens`, Anthropic thinking temp=1 + budget bump, Vertex rejecting\n unsolicited `thinking_level` — each hand-patched after breakage.\n- The 4-format thinking extractor grows a new probe branch per model family\n (gemini-3 `thinking_level`, kimi `thinking_default_on` are recent in-repo examples).\n- `llm_defaults.json` carries a `last_updated` field — an explicit admission it is a\n manually refreshed artifact. `pricing.json` carries per-provider `_default` fallbacks\n precisely because entries lag reality. `model_registry.json` (10.5K lines) plus\n `services/model_registry.py` (656 LOC) exist largely to compensate.\n\n### 3.3 Missing capabilities (verified absent)\n\n| Capability | Evidence |\n|---|---|\n| Retries | `unifier.py:69-79` — a single `try: await client.chat(...)`. One transient 429/503 = user-visible failure. |\n| Fallbacks / cooldowns | No fallback logic anywhere in the chat path. |\n| Streaming | `execute_chat` awaits one complete response (`ai.py:1483`); no token-streaming path exists for chat nodes. |\n| Context-window fallback | `context_length` is declared but nothing routes on overflow — the typed error just surfaces. |\n| Maintained cost/metadata map | `pricing.json` hand-edited vs LiteLLM's continuously updated `model_prices_and_context_window.json` + `completion_cost()` + `get_model_info()`. |\n\n### 3.4 Duplicated commodity code\n\nEvery line of `services/llm/providers/` re-implements what LiteLLM ships and maintains\nweekly for 100+ providers: param normalization, typed exception taxonomy, reasoning\nnormalization, tool-call normalization, message reshaping (system-split, role mapping).\n\n---\n\n## 4. LiteLLM overview (official sources, fetched 2026-07-02)\n\n### 4.1 What it is\n\nThree usage modes:\n\n1. **SDK** — `litellm.completion()` / `litellm.acompletion()`: in-process, OpenAI-shaped\n request/response for 100+ providers.\n2. **Router class** — in-process load balancing across multiple deployments, with\n retries, fallbacks, cooldowns, context-window fallbacks. Requires a pre-declared\n `model_list`.\n3. **Proxy server (AI Gateway)** — standalone OpenAI-compatible HTTP service with\n virtual keys, budgets, spend tracking, admin UI; database-backed.\n\nCurrent: **v1.90.0** (2026-06-26), weekly-ish release cadence, Python >=3.9 (OpenCompany\nserver pins >=3.11,<3.13 — compatible). License: MIT core with a separately-licensed\n`enterprise/` directory (bundled in the wheel; never imported by us — dead weight, not\nlicense risk).\n\n### 4.2 The Rust rewrite (the \"Rust-based router\" premise, verified)\n\nLiteLLM has an **official, in-progress Rust migration**\n([blog](https://docs.litellm.ai/blog/litellm-rust-launch),\n[tracking issue #31263](https://github.com/BerriAI/litellm/issues/31263)):\n\n| Date | Milestone |\n|---|---|\n| Aug 15 2026 | `litellm.ocr()` for Mistral |\n| Sep 1 2026 | `/messages` + `/chat/completions` endpoints in Rust |\n| Sep 15 2026 | **Router (load balancing, failover) in Rust** |\n| Dec 1 2026 | Full server in pure Rust (axum) |\n\nPublished targets: 453 → 6,782 RPS throughput, 359MB → 32MB memory, 7.5ms → 0.05ms\nper-request overhead, <1ms gateway overhead at ~65MB binary. `config.yaml` and all\nclient APIs are promised stable through the transition; FastAPI remains the HTTP\nterminator for auth/rate-limiting/callbacks in proxy mode.\n\nAs of 2026-07-02 the main branch is ~85.9% Python / 0.4% Rust — **the Rust router is not\nshipped yet**. The Rust gains land primarily in the *proxy server*; the in-process SDK\ncall path this RFC adopts is the least-changed, stability-promised surface. Adopting now\npositions OpenCompany to inherit the Rust work without a second migration.\n\nRust-native gateway alternatives considered and rejected (all are sidecars, not\nin-process Python SDKs): TensorZero (pure Rust, <1ms P99), Helicone AI Gateway (Rust),\nBifrost (Go, ~11us overhead). See section 5.\n\n### 4.3 Provider coverage for OpenCompany's 12 providers\n\nAll 12 are supported. The prefix mapping this RFC adds to `llm_defaults.json`:\n\n| OpenCompany provider | `litellm_prefix` | api_base sent |\n|---|---|---|\n| openai | `openai` | only if proxy_url set |\n| anthropic | `anthropic` | only if proxy_url set |\n| gemini (AIza keys) | `gemini` | only if proxy_url set |\n| gemini (Vertex \"AQ.\" keys) | `vertex_ai` | never (proxy ignored, as today) |\n| openrouter | `openrouter` | always (`https://openrouter.ai/api/v1`) |\n| xai / deepseek / mistral / groq / cerebras | same name | always (our JSON base_url) |\n| kimi | `moonshot` | always (`https://api.moonshot.ai/v1` — our JSON decides .ai vs .cn) |\n| ollama | `openai` | always (`http://localhost:11434/v1`) |\n| lmstudio | `openai` | always (`http://localhost:1234/v1`) |\n\nOllama/LM Studio deliberately route through LiteLLM's `openai/` provider with the\nexisting `/v1` base URLs rather than the native `ollama/` route: byte-for-byte parity\nwith today's `_compat.py` behavior, no `/v1`-suffix foot-gun (LiteLLM's native ollama\nroute expects api_base WITHOUT `/v1`), and `nodes/model/_local_validator.py` stays\nuntouched.\n\n### 4.4 Feature parity\n\n| Need (from current layer) | LiteLLM answer |\n|---|---|\n| Reasoning/thinking normalization | `reasoning_effort` + `thinking={type,budget_tokens}` request params; standardized `reasoning_content` (+ Anthropic `thinking_blocks`) in responses ([docs](https://docs.litellm.ai/docs/reasoning_content)) |\n| Typed exception translation | OpenAI-style exception hierarchy with `llm_provider` populated — LiteLLM exceptions subclass the OpenAI SDK classes, so the existing `sdk_exception_types -> NodeUserError` catch keeps working with one tuple: `(openai.OpenAIError,)` ([docs](https://docs.litellm.ai/docs/exception_mapping)) |\n| Tool-call normalization | OpenAI-shaped `tool_calls` across providers; `modify_params=True` auto-fixes provider message-ordering constraints ([docs](https://docs.litellm.ai/docs/completion/function_call)) |\n| Unsupported-param safety | `drop_params=True` global + per-call `additional_drop_params` ([docs](https://docs.litellm.ai/docs/completion/drop_params)) |\n| Usage detail | `prompt_tokens_details.cached_tokens`, `completion_tokens_details.reasoning_tokens`, Anthropic `cache_creation_input_tokens` ([docs](https://docs.litellm.ai/docs/completion/prompt_caching)) |\n| Streaming (future unlock) | Uniform `stream=True` + async iteration across providers |\n| Cost/metadata cross-check | `completion_cost()`, `get_model_info()`, `register_model()` ([docs](https://docs.litellm.ai/docs/completion/token_usage)) |\n\n### 4.5 Known caveats (from official sources)\n\n- ~28MB install; **200MB+ RSS on import**; proxy code ships bundled with the SDK\n ([issue #15262](https://github.com/BerriAI/litellm/issues/15262)). Lazy import is\n mandatory here (section 6.8).\n- `fastuuid` transitive dependency can require a Rust toolchain where no wheel matches\n ([issue #14145](https://github.com/BerriAI/litellm/issues/14145)) — Windows wheel\n availability is a Phase 0 gate.\n- Weekly releases → exact pinning required; the o-series `max_tokens` →\n `max_completion_tokens` mapping has regressed repeatedly across releases\n ([#8213](https://github.com/BerriAI/litellm/issues/8213),\n [#10066](https://github.com/BerriAI/litellm/issues/10066),\n [PR #13390](https://github.com/BerriAI/litellm/pull/13390)) — we do not depend on it\n (section 6.4).\n- SDK telemetry must be disabled for a local-first product: `litellm.telemetry = False`.\n- LiteLLM has **no per-account model listing** — `fetch_models` stays ours (section 6.7).\n\n---\n\n## 5. Decision\n\n**Adopt LiteLLM now, in-process, as `litellm.acompletion` behind the retained\n`ChatUnifier` facade — chat path first (Stage A), agent loop second (Stage B).**\n\nScored against OpenCompany's constraints (local-first, single-user, Windows-primary,\n2.90s cold-start budget, one API key per provider):\n\n| Option | Effort | Runtime perf | Cold-start | Maintenance saved | Features | Risk | Verdict |\n|---|---|---|---|---|---|---|---|\n| (a) Status quo | 5 | 4 | 5 | 1 | 1 | 3 | Pays ~2.3K LOC + quirk-chasing tax forever |\n| **(b) acompletion behind ChatUnifier** | **4** | 4 | 4 (lazy import) | 4 | 4 | **2 (lowest)** | **Chosen** |\n| (c) litellm.Router in-process | 3 | 4 | 3-4 | 4 | 5 | 3 | Rejected for now — see below |\n| (d) LiteLLM proxy sidecar | 2 | 3 today → 5 post-Rust | 2 | 4 | 3 | 4 | Wrong topology for a single-user local app; revisit at Rust GA |\n| (e) Rust gateway today (TensorZero et al.) | 1 | 5 | 2 | 3 | 3 | 4 | Perf solves a problem we don't have; costs the one we do (integration effort) |\n| (f) Wait for Rust GA (Dec 2026) | 5 now | — | — | 1 for ~6 months | 1 | 3 | The SDK surface we'd adopt is the stability-promised one; waiting buys ~nothing |\n\nWhy not the Router class (c), specifically:\n\n- Router's core value is load balancing across multiple deployments per model — OpenCompany\n has one key per provider; the machinery is structurally unused.\n- Router requires a pre-declared `model_list`; OpenCompany model names are dynamic (users\n pick anything `fetch_models` returns — OpenRouter alone returns hundreds). Wildcard\n deployments would duplicate `llm_defaults.json` as a second config SSOT.\n- Context-window fallback silently switches models under a result payload that reports\n model provenance (`ai.py:1497-1509`) — behavior we explicitly do not want.\n- Retries are not Router-exclusive: `num_retries=2` per `acompletion` call covers\n transient 5xx/timeouts (LiteLLM does not retry auth/400-class errors).\n- Router internals are exactly what the Rust rewrite replaces Sep-Dec 2026; the thin\n `acompletion` surface minimizes churn exposure. Router remains a config-only upgrade\n *inside* the same facade if needs grow.\n\nWhy not replace the facade itself: it is 132 LOC and carries the `NodeUserError`\ntranslation site, the `incompatible_models` filter, and the `{provider}_proxy`\ncredential lookup — plus ~420 LOC of contract tests that pass unchanged if it stays.\n\n---\n\n## 6. Design — Stage A: chat path\n\n### 6.1 Shape\n\n- **New** `server/services/llm/litellm_adapter.py` (~400 LOC): one `LiteLLMAdapter`\n class implementing the existing `LLMProvider` protocol\n (`chat(messages, *, model, temperature, max_tokens, thinking, tools) -> LLMResponse`).\n Constructed per-call by the `ProviderSpec` factory exactly like today's providers:\n `LiteLLMAdapter(provider=name, api_key=..., proxy_url=..., defaults=LLM_DEFAULTS)`.\n- **The `ProviderRegistry` stays** (it is the contract for\n `test_provider_self_registration.py`, `unifier.is_registered()`, and\n NodeUserError-on-unknown-provider). Under the flag, registration becomes one\n data-driven loop over `LLM_DEFAULTS[\"providers\"]` registering\n `ProviderSpec(name=n, factory=partial(LiteLLMAdapter, provider=n),\n sdk_exception_refs=(\"openai:OpenAIError\",), client_kwargs={})`.\n (Since 2026-07-14 the spec takes lazy `\"module:Class\"` refs — the\n resolved-classes surface remains the `sdk_exception_types` property.)\n- **`unifier.py` changes ~15 lines**: a flag branch in `_build_client`\n (unifier.py:114) plus `fetch_models` delegation to the retained HTTP lister\n (section 6.7). Public signatures unchanged — `test_wiring.py`,\n `test_unifier_typed_errors.py`, `test_unifier_incompatible_models_filter.py` pass\n without edits.\n- Exception strategy: LiteLLM's typed exceptions inherit from the OpenAI SDK hierarchy,\n so `(openai.OpenAIError,)` is one tuple for all 12 providers; `openai` is already\n eagerly imported (`ai.py:42`) and rides in as a LiteLLM dependency regardless. Phase 0\n asserts the subclassing; if any LiteLLM exception escapes the hierarchy, add\n `litellm.exceptions.APIError` to the tuple inside the adapter module.\n\n### 6.2 Model-name prefixing\n\n`litellm_model = f\"{litellm_prefix}/{model}\"`, with `litellm_prefix` as a new per-provider\nfield in `llm_defaults.json` (table in section 4.3). The adapter contains zero hardcoded\nprovider names. Models arrive post-`[FREE]`-strip (double-guarded: `ai.py:1412-1414` and\nthe adapter re-strips for openrouter). Nested slashes in OpenRouter IDs are fine —\nLiteLLM splits on the first `/`.\n\n### 6.3 ThinkingConfig mapping\n\nOne pure function `_thinking_params(provider, model, thinking, max_tokens) -> dict`,\ndispatching on `ModelRegistryService.get_thinking_type(model, provider)` (the same\nbranch `create_model` uses at `ai.py:1318`):\n\n| thinking_type / case | Mapping |\n|---|---|\n| budget / anthropic | `thinking={\"type\":\"enabled\",\"budget_tokens\":budget}`; **keep our `max_tokens <= budget -> budget + 1024` bump** (`anthropic.py:59-62`) — do not delegate to LiteLLM; temperature already forced to 1 by our resolver |\n| budget / gemini 2.5-era | `thinking={\"type\":\"enabled\",\"budget_tokens\":budget}`; Phase 0 golden test pins the emitted `thinkingConfig.thinkingBudget`; fallback spelling is the provider-specific `thinkingConfig` kwarg if translation is absent on the pinned version |\n| level / gemini 3.x (XOR budget) | if `thinking.level` set: send effort-style (`reasoning_effort=thinking.level`) and omit budget; else budget and never a level. `ThinkingConfig.level` stays None-by-default — the Vertex-400 guard (`gemini.py:74-80`) is preserved as a contract |\n| effort / openai o-series + gpt-5 | `reasoning_effort=thinking.effort` |\n| format / groq qwen3 | `extra_body={\"reasoning_format\": thinking.format}` guarded by a Phase 0 passthrough check — strictly >= current chat-path behavior (dropped today) |\n| kimi thinks-by-default | Stage A = parity (do nothing; unifier path lets kimi think and captures reasoning today). The `extra_body` disable stays agent-path until Stage B aligns both |\n\n### 6.4 Temperature and max_tokens: our resolvers remain the authority\n\n`resolve_temperature` / `resolve_max_tokens` (`config.py:158-206`) stay at the ai.py\ncall sites, untouched. The adapter additionally:\n\n- **omits `temperature` entirely** when `is_reasoning_model(model, provider)` — matching\n both current providers and `create_model` (`ai.py:1312-1315`);\n- **emits `max_completion_tokens` itself** for reasoning models and `max_tokens`\n otherwise — LiteLLM's own o-series auto-mapping works on v1.90.0 but has a regression\n history (#8213, #10066, #13390), so it is not the mechanism of record.\n\n`litellm.drop_params = True` is set globally as a belt-and-braces measure against other\nper-provider param rejections — never as the primary mechanism (a callback logs whenever\nit fires, so silent drops are visible in DEBUG logs).\n\n### 6.5 api_base, proxy_url, placeholder keys\n\nSingle resolution method: `api_base = proxy_url or (base_url per section 4.3 table) or\nNone`. When `proxy_url` is set, `api_key` is replaced with `\"ollama\"` — byte-for-byte\ntoday's behavior (`openai.py:31-36`, `anthropic.py:27-30`). Gemini-with-proxy in Vertex\nmode logs-and-ignores the proxy exactly as `gemini.py:33-36`. No `/v1` special-casing is\nneeded because of the 6.2/4.3 routing decisions.\n\n### 6.6 Vertex Express (\"AQ.\") keys\n\n`services/llm/vertex.py` (`is_vertex_express_key`, 28 LOC) **stays as the detection\nSSOT** — contract-tested (`tests/llm/test_vertex_key.py`, 357 LOC) and shared with the\nagent path. The adapter routes AQ. keys to the `vertex_ai/` prefix.\n\n**Stated uncertainty:** LiteLLM's `vertex_ai/` route with a bare Express API key (no\nservice-account `vertex_credentials`) is the one mapping this design cannot guarantee\nfrom documentation — it is the top Phase 0 spike item.\n\n**Pre-decided contingency:** if LiteLLM cannot drive Express keys on the pinned version,\nthe gemini integration retains a ~60-LOC native google-genai fallback *for AQ. keys\nonly* (extracted from `gemini.py:28-42,86-91`), and everything else still migrates. This\nisolates the only genuinely exotic auth path without blocking the other 11 providers.\n\n### 6.7 fetch_models stays ours\n\nLiteLLM has no per-account model listing (`get_valid_models(check_provider_endpoint=True)`\nis sync, env-var oriented, and ignores our proxy/curation semantics). New\n`server/services/llm/models_http.py` (~130 LOC), called by `ChatUnifier.fetch_models`\nwhen the flag is on:\n\n- Generic: `GET providers.<name>.models_endpoint` with `build_headers()` headers\n (anthropic's `anthropic-version` header moves into the JSON `extra_headers` block),\n honoring `proxy_url`; parse `data[].id`, sorted.\n- OpenRouter: `[FREE]` tagging + free-first sort ported verbatim (`openrouter.py:56-80`).\n- Gemini: curated-list + key-probe design ported (`gemini.py:97-138`); the AQ. probe\n becomes a `max_tokens=1` adapter chat call against the first curated model (sub-cent,\n exercises the exact route users hit) — unless the 6.6 contingency retains google-genai,\n in which case `count_tokens` stays.\n- The curated-list fallback in `ai.py:1392-1398` and the credential-probe flow\n (`nodes/model/_credentials.py:55`) are untouched.\n\n### 6.8 Import and module settings (cold-start protection)\n\nLazy import is **mandatory**, not optional: the repo's cold-start budget is 2.90s to\n\"Application startup complete\" ([performance.md](./performance.md)), and the layer\nalready fought this war (eager `langchain_openai` cost ~20.8s cold on Windows; fixed via\n`functools.cache` lazy getters — the pattern to copy, `ai.py:55-96`).\n\n```python\n@functools.cache\ndef _litellm():\n import litellm\n litellm.drop_params = True # safety net for per-provider param rejection\n litellm.modify_params = True # provider-required message reshaping (e.g. Anthropic first-message-must-be-user)\n litellm.telemetry = False # SDK telemetry kill switch — mandatory for a local-first product\n logging.getLogger(\"LiteLLM\").setLevel(logging.WARNING)\n return litellm\n```\n\nNothing at `services.llm` import time may touch litellm — `core/container.py` imports\n`services.llm` during container boot. `sdk_exception_refs=(\"openai:OpenAIError\",)`\ndeliberately avoids importing litellm (or any SDK) at registration — the same lazy-ref\ncontract `tests/llm/test_lazy_sdk_imports.py` already enforces for openai/anthropic/\ngoogle-genai. New guard test\n`tests/llm/test_lazy_litellm.py`: import `services.llm`, construct `ChatUnifier`, assert\n`\"litellm\" not in sys.modules`. Phase 0 asserts the three module-setting attribute names\non the pinned version so a rename fails in CI, not production.\n\n### 6.9 Response normalization\n\nOne `_normalize(resp, model) -> LLMResponse`:\n\n- `content` = `choices[0].message.content or \"\"`; `finish_reason` defaulted to `\"stop\"`;\n `model` = the **user-facing** model string (not the prefixed one) — preserves the\n result-payload contract (`ai.py:1497-1509`); `raw` = the litellm response.\n- `thinking` = `message.reasoning_content`; for Anthropic, if empty but\n `thinking_blocks` present, join `block[\"thinking\"]` with `\"\\n\\n\"` (matches current\n formatting). This deletes per-provider extraction wholesale.\n- `tool_calls` mapped as today (`openai.py:149-157`). The chat path never passes tools\n today (`ai.py:1483-1491`) — this is protocol completeness plus Stage B groundwork.\n (Gemini synthetic tool-call IDs will differ from the current name-as-id hack — an\n accepted no-consumer change.)\n- `Usage` mapping:\n - `input/output/total` ← `usage.prompt_tokens / completion_tokens / total_tokens`\n - `cache_read_tokens` ← `usage.prompt_tokens_details.cached_tokens` (fallback:\n `cache_read_input_tokens` attr for Anthropic-style placement)\n - `reasoning_tokens` ← `usage.completion_tokens_details.reasoning_tokens`\n - `cache_creation_tokens` ← `cache_creation_input_tokens` (Anthropic; read\n defensively from both `usage` and `provider_specific_fields` — Phase 0 asserts the\n exact location; all other providers stay 0, same as today)\n- All *input* message shaping collapses to the OpenAI dict format; LiteLLM performs the\n Anthropic system-split and Gemini role/parts translation internally — deleting\n `anthropic.py:_split_system/_to_api_message` and\n `gemini.py:_split_system_and_contents`.\n\n---\n\n## 7. Design — Stage B: agent loop\n\nPer the owner's scope decision, the agent loop is an **active stage**, not an indefinite\ndeferral. It begins only after the Stage B gate (section 10, Phase 4).\n\n### 7.1 What changes\n\nReplace `create_model` (`ai.py:1206-1353`) and LangChain message shapes in\n`_run_agent_loop` (`ai.py:733-894`), `execute_chat_agent` (`ai.py:2105-2626`), and\n`services/temporal/agent_activities.py:119,208` with adapter calls on protocol types:\n\n| Concern | Mapping |\n|---|---|\n| Messages | `SystemMessage/HumanMessage/AIMessage/ToolMessage` ↔ OpenAI dicts; `AIMessage.tool_calls[{name,args,id}]` → assistant `tool_calls` with JSON-encoded arguments; `ToolMessage.tool_call_id` → role `tool` |\n| Tool binding | `bind_tools(StructuredTool)` → `ToolDef` JSON schemas passed per call (hot-rebind after canvas mutations becomes list mutation — simpler than re-binding a LangChain model) |\n| Memory | `_parse_memory_markdown` (`ai.py` memory glue) returns protocol `Message` objects instead of LangChain messages |\n| Thinking | the 4-format `extract_thinking_from_response` (`ai.py:621-730`) collapses to `reasoning_content` / `thinking_blocks` |\n| Token tracking | `_track_token_usage` (`ai.py:1091`) switches from LangChain `usage_metadata` to our `Usage` — cache/reasoning tokens start flowing into `CompactionService.track()` (which already accepts those keys, `compaction.py:133-145`) — a strict cost-accuracy improvement for Anthropic caching |\n| Compaction | native context-management configs (incl. the `compact-2026-01-12` beta header) pass via litellm `extra_headers` |\n| Kimi alignment | the `extra_body` thinking-disable moves into the shared adapter, unifying quirk handling across both paths |\n\n### 7.2 What explicitly stays\n\nThe deepagents-based Deep Agent node remains LangChain — `deepagents==0.6.9` pulls\n`langchain-core` itself, so those pins survive Stage B; *our* loop simply stops using\nthem. Removable after Stage B: `langchain-openai`, `langchain-anthropic`,\n`langchain-google-genai`, `langchain-groq`, `langchain-cerebras` pins (and with them the\n~20.8s-cold-import class and the Windows/Py3.13 gemini gRPC hang workaround).\n\n### 7.3 Stage B gate criteria\n\n1. Stage A default-on and stable for 2+ releases (repo ships ~weekly).\n2. Gemini `thought_signature` multi-turn tool round-trip verified on the pinned LiteLLM\n (assistant-turn reasoning fidelity is the known open risk).\n3. Streaming/broadcast integration for agent progress events mapped.\n\n---\n\n## 8. Config, flag, rollout, dependency policy\n\n- New Settings field (`core/config.py`, `{SERVICE}_ENABLED` convention; model:\n `event_framework_enabled`): `litellm_enabled: bool = Field(default=False,\n env=\"LITELLM_ENABLED\")` + `.env.template` row.\n- **One boolean, evaluated per-request** in `ChatUnifier._build_client` /\n `fetch_models` — not per-provider flags (the 12x2 matrix is the complexity being\n deleted). Documented escape hatch if a single provider regresses post-cutover: a\n 5-line `LITELLM_PROVIDERS` CSV allowlist addition.\n- Wiring: `_build_chat_unifier` (`core/container.py`) gains `settings`; rollback =\n `LITELLM_ENABLED=false` + restart. Both stacks stay installed and registered until\n deletion, so rollback is config-only with zero deploys.\n- Legacy deletion trigger: default flipped to `true` + one release soak with no\n provider regressions.\n- Dependency: `litellm==1.90.0` **exact pin** in `server/pyproject.toml` (weekly\n upstream releases + the Rust-rewrite window make range pins reckless), then `uv lock`\n and regenerate `server/requirements.txt` via the documented\n `uv export --frozen --no-emit-project --no-hashes --no-dev -o requirements.txt`.\n Bump policy: monthly or CVE-triggered, always through the parity suite (matches the\n existing pin-comment precedent in pyproject).\n\n---\n\n## 9. Risks and mitigations\n\n| # | Risk | Severity | Mitigation |\n|---|---|---|---|\n| R1 | Cold-start regression from import weight (200MB+ RSS, heavy module tree) vs the 2.90s budget | High | Mandatory lazy import (6.8); `test_lazy_litellm.py` CI guard; cold-start measured per performance.md method in Phase 2 |\n| R2 | Behavioral regression across the 16 encoded quirks | High | Golden-request wire-parity suite: capture exact provider-SDK kwargs the current layer produces for a (provider x thinking x model-family) matrix, assert LiteLLM emits equivalent wire params; live smoke stays the gate |\n| R3 | fetch_models gap (LiteLLM lists no per-account models) | Medium | Keep our HTTP listing (~130 LOC, section 6.7); scope LiteLLM to the completion path only |\n| R4 | Usage-shape mismatch breaks Pricing/Compaction persistence (`cache_*`, `reasoning_tokens` are DB columns) | Medium | One adapter mapping function + per-provider fixtures (anthropic/openai/gemini); compaction beta-header pass-through verified before Stage B |\n| R5 | Split-brain window: chat on LiteLLM, agent loop on LangChain until Stage B | Medium | Bounded by the Stage B gate, not indefinite; quirk SSOT stays `llm_defaults.json` so fixes are configured once; both layers already coexist today |\n| R6 | Weekly upstream churn imports regressions | Medium | Exact pin + monthly/CVE bump policy behind the parity suite |\n| R7 | Adopting immediately before LiteLLM's Rust rewrite | Medium | The `acompletion` SDK surface is the stability-promised, least-changed path; hard pin; re-evaluate topology at Dec 2026 GA |\n| R8 | `fastuuid` transitive dep needs a Rust toolchain where wheels are missing (Windows is the primary platform) | Low-Med | Phase 0 blocker check: `uv add litellm==1.90.0` must resolve binary wheels on win_amd64 / py3.11-3.12 |\n| R9 | `drop_params` silently masks misconfiguration | Low-Med | Our resolvers remain authoritative and run before the call; drop_params is a logged safety net only |\n| R10 | Test-suite rewrite cost (~2,250 LOC surface) | Medium | ~40-50% rewrite concentrated in provider-shape tests (`test_providers.py`, `test_plugin_shape.py`, mocks); ~50-60% retained (resolution, filter, vertex detection, live smoke) |\n| R11 | Supply chain / telemetry | Low | MIT core; enterprise/ dir never imported; `litellm.telemetry=False` at init; advisory-driven bump policy (pyproject precedent) |\n\n**Top-5 riskiest quirks** (rank-ordered for parity-test priority):\n\n1. Vertex Express \"AQ.\" key routing — possible outright capability gap in LiteLLM's\n `vertex_ai/` route; pre-decided native fallback (6.6).\n2. Gemini `thinking_level` None-default — LiteLLM must not inject defaults; wire-capture\n test pins it.\n3. Anthropic `max_tokens > budget` bump — kept in our adapter code, never delegated.\n4. Ollama/LM Studio `{provider}_proxy` credential + placeholder keys + offline\n empty-list UX — mappable but easy to miss.\n5. Kimi `extra_body` thinking-disable + fixed temperature — extra_body must pass through\n verbatim; fixed temp applied by our resolver before the call.\n\n(o-series `max_completion_tokens` and reasoning temp-omission rank lower — handled\nnatively by LiteLLM *and* enforced by our adapter regardless.)\n\n---\n\n## 10. Phased implementation plan\n\n### Stage A — chat path\n\n**Phase 0 — spike + bench (scratch only, go/no-go appended here).**\n1. `uv add litellm==1.90.0` resolution on Windows/py3.12 — fastuuid wheel check;\n measure `import litellm` wall time + RSS.\n2. Exception hierarchy asserts: `issubclass(litellm.exceptions.AuthenticationError,\n openai.OpenAIError)` etc. for realistically-raised classes.\n3. Vertex Express spike: `acompletion(model=\"vertex_ai/gemini-2.5-flash\",\n api_key=\"AQ. ...\")` — the 6.6 contingency trigger.\n4. Golden request captures: o-series `max_completion_tokens` + temperature omission;\n anthropic `thinking` + bump; gemini budget-XOR-level; kimi/groq `extra_body`\n passthrough; openrouter headers. Test-infra gotcha to resolve here: LiteLLM may use\n its aiohttp transport on some routes while respx intercepts httpx only — pin\n `litellm.disable_aiohttp_transport = True` in the golden-test fixture and verify the\n attribute name on the pinned version.\n5. Live smoke via a throwaway adapter for every keyed provider.\n6. Assert `litellm.drop_params` / `modify_params` / `telemetry` attribute names; assert\n the `cache_creation_input_tokens` location on an anthropic cache-hit response.\n\n**Phase 1 — core swap behind the flag (default off).**\n- New: `services/llm/litellm_adapter.py` (~400), `services/llm/models_http.py` (~130).\n- Edit: `services/llm/unifier.py` (flag branch + fetch_models delegation),\n `services/llm/__init__.py` (data-driven registration loop when flag on),\n `config/llm_defaults.json` (`litellm_prefix` x12 + anthropic `extra_headers`),\n `core/config.py` (+flag), `core/container.py` (settings into `_build_chat_unifier`),\n `server/pyproject.toml` + `uv.lock` + `requirements.txt`, `.env.template`.\n- Untouched: `ai.py`, `nodes/model/*`, `protocol.py`, `config.py` resolvers, pricing/\n registry/compaction services.\n- New tests: `test_litellm_adapter.py` (mapping units: prefix table, thinking matrix\n incl. gemini XOR, temperature/max_tokens branches, usage normalization from synthetic\n responses), `test_litellm_golden_requests.py` (respx request-shape contracts),\n `test_lazy_litellm.py`.\n\n**Phase 2 — parity + cutover.**\n- Parametrize `tests/llm/test_live_providers.py` with a fixture flipping\n `litellm_enabled`, so one `pytest -m live` run exercises both stacks and diffs\n `LLMResponse` fields (content non-empty, thinking presence, usage > 0).\n- Cold-start regression per the performance.md measurement method; add the result as a\n new optimisation-history row (post-merge follow-up, section 12).\n- Flip `litellm_enabled` default to `true`; soak one release.\n\n**Phase 3 — delete dead code.**\n- Delete: `providers/openai.py` (200), `anthropic.py` (203), `gemini.py` (268 — minus\n the AQ. fallback if the contingency fired), `openrouter.py` (99), `_compat.py` (109),\n provider imports in `providers/__init__.py`, the flag + legacy\n branch in `unifier.py`. (`factory.py` and its `create_provider` /\n `is_native_provider` / `NATIVE_PROVIDERS` exports were already deleted\n independently of this RFC — ChatUnifier + registry is the only dispatch layer.)\n- Tests: delete `test_providers.py` (`test_factory.py` is already gone with `factory.py`); rewrite\n `test_provider_self_registration.py` (data-driven registration) and the\n provider-construction halves of `test_vertex_key.py` (detection + curated-list halves\n survive); update `test_plugin_shape.py` grep-guards. Surviving unchanged:\n `test_wiring`, `test_unifier_typed_errors`, `test_unifier_incompatible_models_filter`,\n `test_max_tokens_resolution`, `test_messages`.\n- Do NOT remove `anthropic` / `google-genai` / `langchain-*` deps yet — the agent path\n still needs them until Stage B (`services/plugin/credential.py` also touches openai\n exception classes).\n\n### Stage B — agent loop (starts after the section 7.3 gate)\n\n**Phase 4 — agent-loop swap behind the same flag pattern**: `create_model` replacement,\nmessage mapping, memory parsing to protocol Messages, tool binding, extractor collapse,\n`_track_token_usage` switch, Temporal `agent_activities.py` touchpoints.\n\n**Phase 5 — agent parity**: memory round-trip, multi-turn tool loops per provider\n(gemini `thought_signature` fidelity is the named risk), compaction beta headers, agent\nprogress broadcasts, Temporal activity heartbeat behavior.\n\n**Phase 6 — LangChain glue deletion**: the 4-format extractor (~110 LOC), `create_model`\n(~148 LOC), LangChain message glue; remove `langchain-openai` / `langchain-anthropic` /\n`langchain-google-genai` / `langchain-groq` / `langchain-cerebras` pins (deepagents keeps\n`langchain-core` alive); docs updates.\n\n### LOC accounting\n\n| | Deleted | Added | Net |\n|---|---|---|---|\n| Stage A, `services/llm/` | ~1,010 | ~600 (adapter ~400, models_http ~130, registration ~40, flag/DI ~20, JSON ~15) | **~ -420** (1,701 → ~1,240) |\n| Stage A, tests | ~385 deleted + ~150 rewritten | ~490 new | ~ +100 (coverage shifts from SDK-translation internals to request-shape contracts) |\n| Stage B | ~700+ in ai.py + 5 dep pins | small | **~ -700** |\n\n---\n\n## 11. Acceptance criteria\n\n1. Cold start stays <= 2.90s warm (\"Application startup complete\", performance.md\n method), with a startup-timeline regression check.\n2. The 16-quirk golden-request parity suite passes; live smoke green on all 12 providers\n including a Vertex \"AQ.\"-key case.\n3. Provider-layer production LOC decreases >= 40% at Stage A end.\n4. `NodeUserError` user-facing error contract and the model-dropdown UX (including the\n ollama/lmstudio offline empty-state) are byte-identical.\n5. `uv sync` succeeds with binary wheels only on Windows / py3.11-3.12.\n\n---\n\n## 12. Open questions and follow-ups\n\nOpen questions:\n1. **Vertex Express negotiability** — if LiteLLM cannot serve \"AQ.\" keys, is the\n permanent native-gemini carve-out acceptable, or does Vertex Express support get\n dropped instead?\n2. **Pin-bump ownership** — who owns the monthly litellm bump-and-smoke chore?\n3. **Stage B streaming ambitions** — LiteLLM unlocks uniform streaming; do chat nodes /\n agent progress events adopt it in Stage B or a later wave?\n\nFollow-ups (post-merge; currently blocked on concurrent doc edits by another session):\n- Add the doc-table row for this RFC to `CLAUDE.md`.\n- Rewrite `docs-internal/native_llm_sdk.md` after Stage A lands (\"adding a provider =\n JSON edit incl. `litellm_prefix`\").\n- Add the Phase 2 cold-start measurement as a `docs-internal/performance.md` history row.\n\n---\n\n## 13. Sources\n\nLiteLLM (official, fetched 2026-07-02):\n- Repo: https://github.com/BerriAI/litellm · License: https://github.com/BerriAI/litellm/blob/main/LICENSE\n- Rust launch blog: https://docs.litellm.ai/blog/litellm-rust-launch · Tracking issue: https://github.com/BerriAI/litellm/issues/31263\n- Routing/Router: https://docs.litellm.ai/docs/routing · Providers: https://docs.litellm.ai/docs/providers (openai, anthropic, gemini, openrouter, xai, deepseek, mistral, groq, cerebras, ollama, openai_compatible pages)\n- Reasoning: https://docs.litellm.ai/docs/reasoning_content · Exceptions: https://docs.litellm.ai/docs/exception_mapping · drop_params: https://docs.litellm.ai/docs/completion/drop_params\n- Usage/cost: https://docs.litellm.ai/docs/completion/token_usage · Prompt caching: https://docs.litellm.ai/docs/completion/prompt_caching · Streaming: https://docs.litellm.ai/docs/completion/stream\n- Known issues cited: #15262 (SDK/proxy bundling), #14145 (fastuuid), #8213 / #10066 / PR #13390 (o-series max_tokens regressions)\n\nRepo anchors (verified this session): `services/llm/unifier.py` (78-79, 93-94, 95-98,\n114, 122), `services/llm/providers/anthropic.py:59-62`, `services/llm/providers/gemini.py:72-80`,\n`services/llm/vertex.py:23`, `services/ai.py` (621, 733, 1091, 1206, 1365, 1400, 2105),\n`constants.py:414`, `config/llm_defaults.json:226-227`, `services/compaction.py:133-145`,\n`docs-internal/performance.md`.\n","archived":true,"sha256":"095869caf57d3c760e689fa3b7b648d24036f803d7174cfb1d15270897849164"},"doc:docs-internal/ARCHIVE/memory_lifecycle.md":{"id":"doc:docs-internal/ARCHIVE/memory_lifecycle.md","path":"docs-internal/ARCHIVE/memory_lifecycle.md","title":"Memory Lifecycle","content":"# Memory Lifecycle\n\n> **ARCHIVED 2026-09-04 — Superseded.** Documents the retired `input-memory` markdown model (pre-RFC-0002). The `services/memory/` helper API, vector store and claude session bridge sections were still broadly accurate, but the test citations were not: `tests/services/memory/test_markdown.py` does not exist, the CloudEvents lock is `tests/test_cloudevents_node_parameters.py`, and `parse_memory_markdown` / `trim_markdown_window` have no test coverage.\n>\n> For current state see:\n>\n> - [agent_context_flow.md](../agent_context_flow.md) and [RFC-0002](../../RFC-0002-AGENT-CONTEXT-AND-MEMORY.md) — conversation store\n> - [memory_compaction.md](../memory_compaction.md) — token tracking and compaction\n> - [cli_agent_framework.md → Memory bridge](../cli_agent_framework.md) — claude session continuity\n\n> ## ⚠ Partly superseded by RFC-0002\n>\n> This document describes the pre-RFC-0002 model, in which `simpleMemory` hung\n> off an agent's `input-memory` handle and held the conversation transcript as\n> Markdown. **That model no longer exists.** Conversation state is now the\n> plain conversation store (`agent_conversations`, keyed by\n> `(workflow_id, generation, agent_node_id)` — see\n> [agent_context_flow.md](./agent_context_flow.md); the intermediate\n> \"Context journal\" described in RFC-0002 was itself replaced), and\n> `simpleMemory` (displayed as \"Memory\") is a `ToolNode` on `input-tools`\n> holding durable facts the agent explicitly remembers — it has no\n> transcript and no markdown surface.\n>\n> **Still accurate here:** §2 (the `services/memory/` markdown + JSONL helper\n> API), §3 (`services.memory` canonicality, `append_memory_turns_atomic`), §4\n> (vector store), §6 (the `claude_code_agent` stable-`cwd` session bridge), §9,\n> and §10.\n>\n> **Stale here:** §1's framing, §5 (state-clear orchestration — `memory_content`\n> is gone and `clear_memory` moved to `services/skills/handlers.py`), §7 (the\n> seven-step lifecycle), §8 (per-agent memory shapes), and §11's warning about\n> writing to `simpleMemory.memory_content`.\n>\n> For the current model see \"Context and Memory (RFC-0002)\" in `CLAUDE.md` and\n> [RFC-0002](../RFC-0002-AGENT-CONTEXT-AND-MEMORY.md).\n\nCanonical home for how conversation memory is loaded, appended, trimmed, archived, cleared, and resumed across every OpenCompany agent. Replaces the partial explanations previously scattered across `agent_architecture.md`, `cli_agent_framework.md`, `rlm_service.md`, and `memory_compaction.md`.\n\n> **Related docs:**\n> - [memory_compaction.md](./memory_compaction.md) — `CompactionService`, token thresholds, pricing\n> - [agent_architecture.md](./agent_architecture.md) — agent loop that calls these helpers\n> - [cli_agent_framework.md](./cli_agent_framework.md) — `claude_code_agent` native session bridge\n> - [rlm_service.md](./rlm_service.md) — `rlm_agent` engine-specific adapter\n\n## 1. Two storage formats\n\n| Format | File | Used by | Wire shape |\n|---|---|---|---|\n| **Markdown transcript** | [`services/memory/markdown.py`](../server/services/memory/markdown.py) | aiAgent, chatAgent, rlm_agent, claude_code_agent (mirror) | `### **Human/Assistant** (timestamp)` blocks under a top-level `# Conversation History` heading |\n| **Anthropic-Messages JSONL** | [`services/memory/jsonl.py`](../server/services/memory/jsonl.py) | Standalone primitive — not used by any agent today | One JSON object per line: `{\"role\": \"user\"|\"assistant\", \"content\": str \\| [ContentBlock], ...metadata}`; parsing normalizes to `Message` and discards metadata |\n\nThe markdown format is the visible UI surface — `simpleMemory.memory_content`\nis rendered as a markdown editor in the parameter panel. The normalized JSONL\nhelpers remain a standalone primitive; the live `claude_code_agent` bridge\nuses claude's own native session JSONL on disk (see §6) and mirrors the\ntranscript into `memory_content` via the **markdown** helpers for visibility.\n\n## 2. Normalized helper APIs\n\n### Markdown transcript\n\nThree pure functions, no I/O, locked by `tests/services/memory/`:\n\n```python\nfrom services.memory import (\n parse_memory_markdown, # str -> List[services.llm.protocol.Message]\n append_to_memory_markdown, # (content, role: \"human\"|\"ai\", message) -> str\n trim_markdown_window, # (content, window_size_pairs) -> (trimmed, removed_texts)\n)\n```\n\n- **`parse_memory_markdown`** — regex-extracts `### **(Human|Assistant)**[^\\n]*\\n(body)` blocks; returns normalized native `Message(role=\"user\"|\"assistant\", content=...)` instances ready for `ChatUnifier`.\n- **`append_to_memory_markdown`** — drops the empty-state placeholder (`*No messages yet.*`), appends a `### **{label}** (YYYY-MM-DD HH:MM:SS)\\n{message}\\n` entry. Timestamp comes from `datetime.now()`.\n- **`trim_markdown_window`** — keeps the last `window_size * 2` blocks (N user/assistant pairs); returns `(trimmed_content, removed_texts)`. Removed bodies are returned so the caller can hand them to the long-term vector store (§4).\n\n### Empty-state placeholder\n\n```\n# Conversation History\n\n*No messages yet.*\n```\n\nThis is also the value `clear_agent_session_state` resets `memory_content` to (see §5). Defined as `DEFAULT_MEMORY_CONTENT` in [`services/memory/state.py`](../server/services/memory/state.py).\n\n### Standalone JSONL\n\nThe JSONL module is a tested, re-exported primitive, but no production agent\ncurrently calls it:\n\n```python\nfrom services.memory import (\n parse_jsonl, # str -> List[services.llm.protocol.Message]\n append_message, # (text, role, content, **metadata) -> str\n trim_window, # (text, window_size_pairs) -> (trimmed, removed_lines)\n)\n```\n\n- **`parse_jsonl`** accepts only `user` and `assistant` rows. String content\n passes through; list content is reduced to its text blocks, joined with\n spaces. Tool blocks, unknown roles, invalid JSON, non-string content, and\n extra metadata are omitted from the returned native `Message` values.\n- **`append_message`** writes `role`, `content`, and supplied metadata to one\n JSON object and always ends the result with a newline. Metadata remains on\n that serialized line, but `parse_jsonl` does not copy it into `Message`;\n this is wire preservation, not a metadata round trip through the parser.\n- **`trim_window`** counts non-empty rows and keeps the last\n `window_size * 2`. When trimming is required, it rebuilds the result without\n blank lines and returns older serialized rows verbatim; under capacity it\n returns the original input unchanged.\n\nClaude Code's CLI owns and reads its native session JSONL independently. The\nhelpers above do not parse or rewrite those live CLI files.\n\n### Direct process-local message log\n\n[`services/memory_store.py`](../server/services/memory_store.py) is a separate\nprocess-local log. `add_message` normalizes legacy roles (`human` → `user`,\n`ai` → `assistant`); `get_messages` returns timestamped dictionaries for the\n`simpleMemory.read` operation; and `get_native_messages` returns the stored\nnative `Message` values directly, filtered to `user`/`assistant`. Its optional\nwindow is a count of individual messages, not user/assistant pairs.\n\nThis log is currently written directly by `rlm_agent`. It is not the\nDB-backed `memory_content` transcript used passively by aiAgent/chatAgent and\nthe Claude UI mirror, and it does not survive a process restart.\n\n## 3. Canonical implementation and call sites\n\n`services.memory` is the canonical implementation for DB-backed markdown,\nthe standalone JSONL helpers, vector memory, and reset orchestration. The\ndirect process-local `services.memory_store` log described above remains a\nseparate surface. `services.ai` keeps only a thin\n`_parse_memory_markdown` compatibility wrapper and aliases the canonical\nvector-store cache so older internal imports continue to resolve without\ncreating duplicate vector state. Runtime appends use\n`services.memory.runtime.append_memory_turns_atomic`, which performs the\nappend/trim mutation transactionally and idempotently.\n\n| File | Canonical surface |\n|---|---|\n| `services/ai.py` — native in-process agents | `parse_memory_markdown`, `append_memory_turns_atomic`, canonical vector store |\n| `services/temporal/agent_activities.py` — `agent.persist_turn.v1` | `append_memory_turns_atomic` |\n| `services/cli_agent/service.py` — claude_code_agent mirror | markdown/runtime helpers and canonical vector store |\n| `services/memory/state.py` — reset orchestration | canonical vector-store cache + atomic parameter mutation |\n| `services/memory_store.py` — direct process-local log | `add_message`, `get_messages`, `get_native_messages`, `clear_session` |\n\n## 4. Long-term vector store\n\n[`services/memory/vector_store.py`](../server/services/memory/vector_store.py)\nprovides a shared async embedder factory for direct `openai.AsyncOpenAI`,\n`ollama.AsyncClient`, and optional `sentence-transformers` adapters, then\nranks entries locally by cosine similarity. Hugging Face model load and\nencoding run in a worker thread. `create_embedder` is the strict constructor:\nit raises `EmbedderUnavailableError` for a missing SDK/optional extra or a\nmissing OpenAI credential. The higher-level `get_memory_vector_store` factory\ncatches availability failures, logs a warning, and returns `None`, so\nlong-term archival remains best-effort.\n\n```python\nfrom services.memory import get_memory_vector_store\nstore = await get_memory_vector_store(\n \"user-123\",\n provider=\"openai\",\n model=\"text-embedding-3-small\",\n auth_service=auth_service,\n)\nif store:\n await store.add_texts(removed_texts) # archive trimmed messages\n results = await store.similarity_search(q) # retrieve next-turn context\n```\n\nThere is one cache. `services.ai._memory_vector_stores` is a compatibility\nalias to `services.memory.vector_store._memory_vector_stores`, so state clear,\nnative agents, and the CLI bridge observe the same stores. Cache identity is\nsession + provider + model + endpoint + credential fingerprint; plaintext\ncredentials are never stored in a key. Clearing a session removes and closes\nevery matching configuration.\n\n## 5. State clear orchestration\n\n[`services/memory/state.py`](../server/services/memory/state.py) exposes one function:\n\n```python\nawait clear_agent_session_state(\n session_id: str,\n workflow_id: str = None,\n clear_long_term: bool = False, # True → drop vector store\n memory_node_id: str | None = None, # When set → reset memory_content + wipe last_session_id\n) -> {cleared_vector_store, cleared_todo_keys, cleared_memory_node}\n```\n\nThree stores are cleared in one call:\n\n1. **Vector store** (when `clear_long_term=True`) — delete and close every provider/model cache entry for the session (the `services.ai` alias observes the same deletion).\n2. **TodoService** — every candidate key (`workflow_id`, `session_id`, `\"default\"`) is cleared because [`server/nodes/tool/write_todos/__init__.py`](../server/nodes/tool/write_todos/__init__.py) uses `ctx.workflow_id or ctx.node_id or \"default\"` as the storage key and we want to clear whichever fallback the write path actually used.\n3. **simpleMemory node fields** (when `memory_node_id` provided) — `memory_content` → `DEFAULT_MEMORY_CONTENT`; diagnostic/back-compat `last_session_id` → `None`; orphan `memory_jsonl` field popped if present. Normal Claude continuity uses stable `cwd` plus `--continue`, so clearing this field alone neither deletes Claude's native JSONL nor guarantees a fresh Claude conversation.\n\nFrontend `clear_memory` WS handler ([`routers/websocket.py:2167`](../server/routers/websocket.py)) calls this; UI presents a Reset Memory button on the simpleMemory parameter panel.\n\n### Workflow Reset archives then clears Memory\n\nTemporal workflow **Reset** and the Simple Memory panel's **Clear Memory** are\nseparate lifecycle operations:\n\n| Operation | `memory_content` / `memory_jsonl` | session metadata | vector cache | compaction/token state |\n|---|---|---|---|---|\n| Workflow Reset | archived, then reset | cleared | cleared | reset for connected sessions |\n| Clear Memory | reset | cleared | optional (`clear_long_term`) | cleared for the selected session |\n\n`workflow_runtime_reset` removes the editor's disposable execution projection\nand invalidates memory/compaction projections. Before clearing, Reset copies\nthe authoritative Simple Memory parameters into the archived generation's\n`runtime_data.simple_memory` map. It then resets the live memory-node fields,\nconnected agent sessions, vector caches, direct memory-store sessions,\nconversation rows, and token counters. The next Temporal generation therefore\nstarts with the empty DB-backed conversation placeholder. Claude's own\non-disk session history is a separate lifecycle; `--continue` can still find\nit until that native session data is cleared.\n\nThe archived copy is immutable history; the live `node_parameters` row remains\nthe source of truth and is reset to the empty-state value for the next Start.\n\n## 6. claude_code_agent native session resume bridge\n\n`claude_code_agent` does **not** inject `memory_content` as a system prompt.\nWhen memory is connected, normal spawns use Claude's `--continue` flag from a\nstable working directory. Claude then selects its latest native JSONL\ntranscript under\n`<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`. Full plumbing\nis in [cli_agent_framework.md → Memory bridge](./cli_agent_framework.md#memory-bridge--simplememory--claude_code_agent).\n\n| Mechanism | Where | Why |\n|---|---|---|\n| **Stable `cwd=repo_root`** | `AICliSession.cwd()` when `memory_bound=True` | Keeps Claude's cwd-derived project key constant so `--continue` searches the same project history |\n| **`--continue` for normal continuity** | `claude_code_agent.execute()` | Every memory-bound task opts into `continue_session`; with no prior session Claude starts fresh, otherwise it loads the latest session for that cwd |\n| **Returned session ID** | `_persist_memory` in `services/cli_agent/service.py` | Saves the latest returned UUID to `simpleMemory.last_session_id` for diagnostics and backward compatibility; normal node execution does not read it to select the next session |\n\n`memory_content` is the UI mirror, not the continuation channel.\n`_persist_memory` appends every successful run's user prompt + assistant\nresponse to it via the **same markdown helpers** aiAgent uses, and records the\nmost recent `r.session_id` in the same DB write. It broadcasts\n`node_parameters_updated` (CloudEvents v1.0 envelope, `source_hint=\"cli\"`) so\nthe simpleMemory parameter panel auto-refetches mid-run. Explicit\n`--resume <UUID>` remains an internal compatibility/crash-recovery mechanism,\nbut it is not driven by `last_session_id` during the normal node path.\n\n**Parallel-batch guard.** When memory is wired AND `len(tasks) > 1`,\n`claude_code_agent` raises `NodeUserError` because concurrent memory-bound CLI\nturns under one cwd could race over the same session state.\n\n## 7. The lifecycle in motion (aiAgent example)\n\n```\nTurn N starts\n │\n ▼\n1. The agent plugin/prepare step reads simpleMemory.memory_content from DB\n │\n ▼\n2. _parse_memory_markdown(content) → List[native Message]\n │\n ▼\n3. (Optional) await get_memory_vector_store(config);\n await store.similarity_search(prompt)\n → prepend retrieved long-term context as a system message\n │\n ▼\n4. Agent loop runs (run_native_agent_loop: ChatUnifier + native tool calls)\n │\n ▼\n5. _track_token_usage(...) — see memory_compaction.md\n → if threshold tripped: CompactionService.compact_context(...) → reset messages\n │\n ▼\n6. append_memory_turns_atomic(prompt, response, window_size)\n → append markdown pair + trim in one idempotent DB transaction\n │\n ▼\n7. (Optional) await store.add_texts(removed_texts) — long-term archival\n```\n\nF4.B `AgentWorkflow` runs the work represented by steps 4-7 as separate\nTemporal activities.\n`prepare_payload.v1` records `llm_engine` and the message wire version;\nnew executions use native Message Wire V2, preserving Gemini thought\nsignatures, Anthropic signed/redacted thinking, and OpenAI continuation\nmetadata. Histories recorded before cutover lack that engine field; their\nmessages are in a retired wire format and the LLM step refuses them.\n`persist_turn.v1` appends per turn, so a mid-loop failure does not lose\nprogress.\n\n## 8. Engine-specific adapters\n\n| Engine | Memory shape on input | Memory shape on output | Notes |\n|---|---|---|---|\n| `aiAgent` / `chatAgent` | Native `Message` list parsed from markdown | Atomic appended pair + trim | Native SDK path; see §7 |\n| `rlm_agent` | DB-backed Markdown injected as REPL pre-context | Prompt/response appended to the direct process-local `services.memory_store` log; DB Markdown is not updated | RLM internal recursion uses its own state machine; only entry/exit cross the memory boundary |\n| `claude_code_agent` | Stable cwd + `--continue` lets Claude select its native JSONL; `memory_content` ignored on input | Bridge writes markdown mirror + saves diagnostic/back-compat `last_session_id` | See §6 |\n\n## 9. Compaction trigger\n\nCompaction is a separate concern documented in [memory_compaction.md](./memory_compaction.md). The trigger point is step 5 in §7. Threshold = `model_context_length * compaction_ratio` (default **0.8** = 80%, env `COMPACTION_RATIO` via `Settings`; per-user override in `UserSettings.compaction_ratio`; JSON `llm_defaults.json:agent.compaction.ratio` is the last-resort fallback).\n\nThe compaction service is the SSOT for thresholds, native-API integration (Anthropic `compact-2026-01-12` beta, OpenAI `context_management.compact_threshold`), and client-side summarization fallback. Memory lifecycle (this doc) is the SSOT for storage shape and helper signatures.\n\n## 10. Pytest invariants\n\n```\nserver/tests/services/memory/\n├── test_markdown.py # parse → append → trim round-trips\n├── test_jsonl.py # parse_jsonl + append_message + trim_window\n├── test_state.py # cross-store reset behavior\n├── test_memory_store.py # legacy/canonical role normalization\n└── test_vector_store.py # native cosine ranking and empty operations\n```\n\nThe CloudEvents `node_parameters_updated` envelope emitted on every memory write is locked by `tests/test_status_broadcasts.py:test_node_parameters_updated_envelope_shape` — see [status_broadcaster.md](./status_broadcaster.md) for the contract.\n\n## 11. What NOT to do\n\n- Don't write to `simpleMemory.memory_content` without broadcasting `node_parameters_updated` — the parameter panel won't refetch and users will see stale content.\n- Don't add new local copies of the markdown helpers. Import from `services.memory` (or from `services.memory.markdown` / `.jsonl` directly).\n- Don't bypass `clear_agent_session_state` to \"just delete the markdown\" — TodoService and the vector store will leak across sessions.\n- Don't inject `memory_content` as a system prompt for `claude_code_agent` —\n stable-cwd `--continue` is the normal continuation channel;\n `memory_content` is for the human reader.\n- Don't run claude_code_agent with `memory_bound=True` in parallel batches —\n the continuity guard raises `NodeUserError` and you'll burn a credit.\n","archived":true,"sha256":"e942d8253e7fef0e64cab440a344676df7ce91619c5c593c2582546767be6f32"},"doc:docs-internal/ARCHIVE/new_service_integration.md":{"id":"doc:docs-internal/ARCHIVE/new_service_integration.md","path":"docs-internal/ARCHIVE/new_service_integration.md","title":"New Service Integration Guide","content":"# New Service Integration Guide\n\n> **ARCHIVED 2026-09-04 — Superseded.** Pre-Wave-11 integration guide. The `*_NODE_TYPES` lists, `client/src/nodeDefinitions/`, `services/google_oauth.py` and `handlers/google_auth.py` it walks through are gone; a service is now one self-contained plugin folder.\n>\n> For current state see:\n>\n> - [node_creation.md](../node_creation.md) — decision tree\n> - [plugin_system.md](../plugin_system.md) — full reference\n> - [server/nodes/README.md](../../server/nodes/README.md) — 5-minute recipe\n\n> **⚠️ HISTORICAL — do not follow these steps.** This guide predates\n> Wave 11 and is preserved only as background for reading old code.\n>\n> **Current path for a new service integration:**\n> - Node authoring recipe + decision tree → [node_creation.md](./node_creation.md)\n> - Full plugin reference (credentials, `Connection` facade, six `register_*` hooks, Wave 12 event framework) → [plugin_system.md](./plugin_system.md)\n> - Live OAuth reference implementation → [server/nodes/google/](../server/nodes/google/) (`_oauth.py`, `_router.py`, `_option_loaders.py`, `_auth_helper.py`)\n> - CLI-managed-auth variant (Stripe / Vercel / GitHub shape) → [node_creation.md → CLI-managed auth](./node_creation.md) + [stripe_service.md](./stripe_service.md)\n\n> **⚠️ Pre-Wave-11 — historical reference only.**\n> Node authoring now happens on the backend: each node is a Python plugin in a self-contained folder under `server/nodes/<category>/<plugin>/__init__.py` that emits a `NodeSpec`. The frontend reads specs via [client/src/lib/nodeSpec.ts](../client/src/lib/nodeSpec.ts) + [adapters/nodeSpecToDescription.ts](../client/src/adapters/nodeSpecToDescription.ts). See [plugin_system.md](./plugin_system.md) and [server/nodes/README.md](../server/nodes/README.md) for the current model. The snippets below that reference `client/src/nodeDefinitions/*` are kept for historical context.\n>\n> **Path-correction note (post-extraction).** Several code locations named below moved when each plugin became a self-contained folder. When following this guide, substitute:\n> - `server/services/{service}_oauth.py` → `server/nodes/<plugin>/_oauth.py` (e.g. [server/nodes/google/_oauth.py](../server/nodes/google/_oauth.py), [server/nodes/twitter/_oauth.py](../server/nodes/twitter/_oauth.py))\n> - `server/services/handlers/{service}.py` → the plugin's own folder (Google's handler bodies are inlined into the six service plugins under [server/nodes/google/](../server/nodes/google/) plus shared helpers `_base.py` / `_gmail.py` / `_auth_helper.py`)\n> - `server/services/node_option_loaders/` → per-plugin `_option_loaders.py` registered via `register_option_loader(...)` (e.g. [server/nodes/google/_option_loaders.py](../server/nodes/google/_option_loaders.py), [server/nodes/android/_option_loaders.py](../server/nodes/android/_option_loaders.py), [server/nodes/whatsapp/_option_loaders.py](../server/nodes/whatsapp/_option_loaders.py))\n> - `server/routers/{service}.py` → the plugin's `_router.py`, mounted via `register_router(...)` (e.g. [server/nodes/google/_router.py](../server/nodes/google/_router.py))\n> - Handler registration in `server/services/node_executor.py` → automatic via `BaseNode.__init_subclass__`; no manual registry entry.\n> `server/services/handlers/` now contains only cross-cutting orchestration — `tools.py`, `triggers.py`, `todo.py`.\n\nThis guide provides a comprehensive walkthrough for integrating new external services (like Google Workspace, Slack, Notion, etc.) into OpenCompany. It covers OAuth authentication, database models, API handlers, frontend nodes, and AI Agent tool integration.\n\n> **Backend-first is canonical (post-Wave-6 / Wave-11).** Parameter schemas, validation, conditional visibility, dynamic-option dispatch, icons, and colors all live on the backend. The legacy frontend `nodeDefinitions/*.ts` files no longer exist. Follow the [canonical plugin recipe](./node_creation.md) — every node is one Python file (or self-contained folder) under `server/nodes/<group>/<plugin>/`. The frontend reads `NodeSpec` via [`client/src/lib/nodeSpec.ts`](../client/src/lib/nodeSpec.ts) and adapts via [`adapters/nodeSpecToDescription.ts`](../client/src/adapters/nodeSpecToDescription.ts). Credential icons are also backend-served via `GET /api/schemas/credentials/{provider}/icon` (F7); plugin icons via `GET /api/schemas/nodes/{type}/icon` (Phase 6 / RFC §6.5).\n\n## Overview\n\nA complete service integration includes:\n\n1. **OAuth Service** - Handle authentication with the external provider\n2. **Database Models** - Store OAuth tokens and connection state\n3. **API Handlers** - Execute service operations (CRUD)\n4. **Pydantic input model + NODE_METADATA entry** - The Wave 6 recipe replaces the bulk of the legacy frontend node definition work. See [node_creation.md Wave 6 section](./node_creation.md#wave-6-recommended-recipe-backend-first).\n5. **Dynamic-option loaders** - If your service has dropdown fields needing live data (label list, channel list, calendar list), add a loader to your plugin folder's `_option_loaders.py` and register it from the plugin's `__init__.py` via `register_option_loader(method_name, fn)` (from [server/services/ws_handler_registry.py](../server/services/ws_handler_registry.py)). One-line registration; see [server/nodes/google/_option_loaders.py](../server/nodes/google/_option_loaders.py) as the reference (`gmailLabels`, `googleCalendarList`, `googleDriveFolders`, `googleTasklists`).\n6. **Frontend visual-component routing** - Add to the appropriate `*_NODE_TYPES` list or routing branch in [client/src/Dashboard.tsx](../client/src/Dashboard.tsx) so React Flow knows which component to render.\n7. **AI Tool Schemas** - Enable LLM tool calling\n8. **Credentials Modal** - UI for managing connections\n9. **Pricing Configuration** - Cost tracking for API usage\n\nThe sections below detail each step using Google Workspace as the reference integration. Sections 1-3 + 7-9 are unchanged in Wave 6; section 4-6 are where the backend-first recipe materially cuts the work.\n\n## Architecture Pattern\n\n> **Historical diagram.** The \"Node Definitions (calendarNodes)\" frontend box below no longer exists — node schemas are backend NodeSpec (rendered via `useNodeSpec`), and the credentials modal renders from `server/config/credential_providers.json`.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Frontend │\n│ ┌─────────────────┐ ┌─────────────────┐ │\n│ │ CredentialsModal│ │ Node Definitions │ │\n│ │ (OAuth UI) │ │ (calendarNodes) │ │\n│ └────────┬────────┘ └────────┬────────┘ │\n│ │ │ │\n└───────────│────────────────────│─────────────────────────────┘\n │ WebSocket │ WebSocket\n ▼ ▼\n┌───────────────────────────────────────────────────────────────┐\n│ Backend │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │\n│ │ OAuth Router │ │ Node Executor│ │ WebSocket Handlers │ │\n│ │ (google.py) │ │ (registry) │ │ (oauth_login/status) │ │\n│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘ │\n│ │ │ │ │\n│ ▼ ▼ │ │\n│ ┌──────────────┐ ┌──────────────┐ │ │\n│ │ OAuth Service│ │ Handlers │ │ │\n│ │ (google_oauth│ │ (calendar.py)│◄────────────┘ │\n│ └──────┬───────┘ └──────┬───────┘ │\n│ │ │ │\n│ ▼ ▼ │\n│ ┌──────────────────────────────────┐ │\n│ │ Database (SQLModel) │ │\n│ │ - GoogleConnection │ │\n│ │ - Token storage via auth_service │ │\n│ └──────────────────────────────────┘ │\n└───────────────────────────────────────────────────────────────┘\n │\n ▼\n┌───────────────────────────────────────────────────────────────┐\n│ External Service API │\n│ (Google Calendar API, Slack API, Notion API, etc.) │\n└───────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Step 1: OAuth Service\n\nCreate `server/nodes/{service}/_oauth.py` (post-extraction location; the pre-Wave-11 path was `server/services/{service}_oauth.py`):\n\n```python\n\"\"\"\n{Service} OAuth 2.0 using appropriate library.\n\nTwo access modes:\n1. Owner Mode - Your own account (Credentials Modal)\n2. Customer Mode - Customer's account (database storage)\n\"\"\"\n\nimport time\nfrom typing import Any, Dict, List, Optional\n\nfrom core.logging import get_logger\n\nlogger = get_logger(__name__)\n\n# Define scopes for all service capabilities\nSERVICE_SCOPES = [\n \"scope1\",\n \"scope2\",\n # Add all scopes needed for your service\n]\n\n# In-memory state store (use Redis in production)\n_oauth_states: Dict[str, Dict[str, Any]] = {}\n\n\nclass ServiceOAuth:\n \"\"\"OAuth 2.0 handler for {Service}.\"\"\"\n\n def __init__(\n self,\n client_id: str,\n client_secret: str,\n redirect_uri: str = \"http://localhost:5678/api/{service}/callback\",\n scopes: Optional[List[str]] = None,\n ):\n self.client_id = client_id\n self.client_secret = client_secret\n self.redirect_uri = redirect_uri\n self.scopes = scopes or SERVICE_SCOPES\n\n def generate_authorization_url(\n self,\n state_data: Optional[Dict[str, Any]] = None,\n ) -> Dict[str, str]:\n \"\"\"Generate OAuth authorization URL.\"\"\"\n # Generate unique state for CSRF protection\n state = secrets.token_urlsafe(32)\n\n # Store state data for callback verification\n _oauth_states[state] = {\n \"created_at\": time.time(),\n \"data\": state_data or {\"mode\": \"owner\"},\n }\n\n # Build authorization URL\n auth_url = f\"https://provider.com/oauth/authorize?...\"\n\n return {\"url\": auth_url, \"state\": state}\n\n def exchange_code(self, code: str, state: str) -> Dict[str, Any]:\n \"\"\"Exchange authorization code for tokens.\"\"\"\n # Verify state\n oauth_state = _oauth_states.pop(state, None)\n if not oauth_state:\n return {\"success\": False, \"error\": \"Invalid or expired state\"}\n\n try:\n # Exchange code for tokens\n # Get user info\n\n return {\n \"success\": True,\n \"access_token\": \"...\",\n \"refresh_token\": \"...\",\n \"email\": \"[email protected]\",\n \"name\": \"User Name\",\n }\n except Exception as e:\n return {\"success\": False, \"error\": str(e)}\n\n @staticmethod\n def refresh_credentials(\n refresh_token: str,\n client_id: str,\n client_secret: str,\n ) -> Dict[str, Any]:\n \"\"\"Refresh expired credentials.\"\"\"\n try:\n # Refresh token\n return {\"success\": True, \"access_token\": \"...\"}\n except Exception as e:\n return {\"success\": False, \"error\": str(e)}\n\n\ndef get_pending_state(state: str) -> Optional[Dict[str, Any]]:\n \"\"\"Get pending state without removing it.\"\"\"\n return _oauth_states.get(state)\n```\n\n**Key Points:**\n- Use in-memory state store for CSRF protection\n- Support both owner mode (single account) and customer mode (multi-tenant)\n- Implement token refresh for long-running connections\n- Log operations at appropriate levels\n\n---\n\n## Step 2: Database Models\n\n### 2.1 Connection Model (`server/models/database.py`)\n\n```python\nclass ServiceConnection(SQLModel, table=True):\n \"\"\"OAuth connections for customer access mode.\"\"\"\n\n __tablename__ = \"service_connections\"\n\n id: Optional[int] = Field(default=None, primary_key=True)\n customer_id: str = Field(index=True, max_length=255)\n email: str = Field(max_length=255)\n name: Optional[str] = Field(default=None, max_length=255)\n access_token: str = Field(max_length=2000)\n refresh_token: str = Field(max_length=2000)\n token_expiry: Optional[datetime] = Field(default=None)\n scopes: str = Field(max_length=1000)\n is_active: bool = Field(default=True)\n last_used_at: Optional[datetime] = Field(default=None)\n connected_at: datetime = Field(\n default_factory=lambda: datetime.now(timezone.utc),\n sa_column=Column(DateTime(timezone=True), server_default=func.now())\n )\n updated_at: datetime = Field(\n default_factory=lambda: datetime.now(timezone.utc),\n sa_column=Column(DateTime(timezone=True), onupdate=func.now())\n )\n```\n\n### 2.2 Database CRUD Methods (`server/core/database.py`)\n\n```python\n# Add import\nfrom models.database import ServiceConnection\n\n# Add CRUD methods\nasync def save_service_connection(\n self,\n customer_id: str,\n email: str,\n access_token: str,\n refresh_token: str,\n scopes: str,\n name: Optional[str] = None,\n) -> bool:\n \"\"\"Save or update a service connection for a customer.\"\"\"\n # Implementation...\n\nasync def get_service_connection(self, customer_id: str) -> Optional[ServiceConnection]:\n \"\"\"Get service connection for a customer.\"\"\"\n # Implementation...\n\nasync def delete_service_connection(self, customer_id: str) -> bool:\n \"\"\"Delete service connection for a customer.\"\"\"\n # Implementation...\n\nasync def update_service_last_used(self, customer_id: str) -> bool:\n \"\"\"Update last_used_at timestamp.\"\"\"\n # Implementation...\n```\n\n### 2.3 Database Migration\n\nAdd migration logic in `_migrate_user_settings()`:\n\n```python\n# In server/core/database.py - _migrate_user_settings()\n\n# Check if old table exists and migrate\nresult = await conn.execute(text(\n \"SELECT name FROM sqlite_master WHERE type='table' AND name='old_table_name'\"\n))\nold_exists = result.fetchone() is not None\n\nif old_exists:\n await conn.execute(text(\"ALTER TABLE old_table_name RENAME TO new_table_name\"))\n logger.info(\"Migrated old_table_name to new_table_name\")\n```\n\n---\n\n## Step 3: API Router\n\nCreate `server/nodes/{service}/_router.py` and register it from the plugin's `__init__.py` via `register_router(router, name=\"{service}\")` (post-extraction location; the pre-Wave-11 path was `server/routers/{service}.py`):\n\n```python\n\"\"\"\n{Service} OAuth 2.0 callback and API routes.\n\"\"\"\n\nfrom typing import Optional\nfrom fastapi import APIRouter, Query\nfrom fastapi.responses import HTMLResponse, RedirectResponse\n\nfrom core.container import container\nfrom core.logging import get_logger\nfrom services.{service}_oauth import ServiceOAuth, get_pending_state\n\nlogger = get_logger(__name__)\nrouter = APIRouter(prefix=\"/api/{service}\", tags=[\"{service}\"])\n\n\n@router.get(\"/callback\")\nasync def oauth_callback(\n code: Optional[str] = Query(None),\n state: Optional[str] = Query(None),\n error: Optional[str] = Query(None),\n error_description: Optional[str] = Query(None),\n):\n \"\"\"Handle OAuth callback from provider.\"\"\"\n # Handle errors\n if error:\n return HTMLResponse(content=_callback_html(success=False, error=error_description or error))\n\n # Verify state\n pending_state = get_pending_state(state)\n if not pending_state:\n return HTMLResponse(content=_callback_html(success=False, error=\"Invalid state\"))\n\n # Exchange code for tokens\n auth_service = container.auth_service()\n client_id = await auth_service.get_api_key(\"{service}_client_id\")\n client_secret = await auth_service.get_api_key(\"{service}_client_secret\")\n\n oauth = ServiceOAuth(client_id=client_id, client_secret=client_secret)\n result = oauth.exchange_code(code=code, state=state)\n\n if not result.get(\"success\"):\n return HTMLResponse(content=_callback_html(success=False, error=result.get(\"error\")))\n\n # Store tokens\n mode = pending_state.get(\"data\", {}).get(\"mode\", \"owner\")\n if mode == \"customer\":\n database = container.database()\n await database.save_service_connection(...)\n else:\n await auth_service.store_api_key(provider=\"{service}_access_token\", api_key=result[\"access_token\"], models=[], session_id=\"default\")\n if result.get(\"refresh_token\"):\n await auth_service.store_api_key(provider=\"{service}_refresh_token\", api_key=result[\"refresh_token\"], models=[], session_id=\"default\")\n\n # Broadcast completion\n from services.status_broadcaster import get_status_broadcaster\n broadcaster = get_status_broadcaster()\n await broadcaster.broadcast({\n \"type\": \"{service}_oauth_complete\",\n \"data\": {\"success\": True, \"email\": result[\"email\"]},\n })\n\n return HTMLResponse(content=_callback_html(success=True, email=result[\"email\"]))\n\n\n@router.get(\"/status\")\nasync def get_status():\n \"\"\"Get connection status.\"\"\"\n auth_service = container.auth_service()\n access_token = await auth_service.get_api_key(\"{service}_access_token\")\n\n if not access_token:\n return {\"connected\": False}\n\n return {\"connected\": True, \"email\": \"...\"}\n\n\n@router.post(\"/logout\")\nasync def logout():\n \"\"\"Disconnect service.\"\"\"\n auth_service = container.auth_service()\n await auth_service.remove_api_key(\"{service}_access_token\")\n await auth_service.remove_api_key(\"{service}_refresh_token\")\n return {\"success\": True}\n\n\ndef _callback_html(success: bool, email: str = None, error: str = None) -> str:\n \"\"\"Generate OAuth callback HTML page.\"\"\"\n # Return success/error HTML with auto-close script\n ...\n```\n\n### Register Router\n\n**No `main.py` edit needed (post-extraction).** Register the router from the plugin's `__init__.py`; `main.py` mounts every plugin-registered router via its plugin-router loop:\n\n```python\n# server/nodes/{service}/__init__.py\nfrom services.ws_handler_registry import register_router\nfrom . import _router\n\nregister_router(_router.router, name=\"{service}\")\n```\n\nFor OAuth callback paths also call `register_oauth_callback_path(\"{service}\", \"/api/{service}/callback\")` (see [server/nodes/google/__init__.py](../server/nodes/google/__init__.py) for the full self-registration set).\n\n---\n\n## Step 4: WebSocket Handlers\n\nAdd handlers in your plugin folder's `_handlers.py` and register them from `__init__.py` via `register_ws_handlers(WS_HANDLERS)` (post-extraction; the pre-Wave-11 path was `server/routers/websocket.py`). See [server/nodes/google/_handlers.py](../server/nodes/google/_handlers.py) for the `google_oauth_login` / `google_oauth_status` / `google_logout` reference:\n\n```python\nasync def handle_{service}_oauth_login(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:\n \"\"\"Initiate OAuth flow.\"\"\"\n import webbrowser\n from ._oauth import ServiceOAuth\n\n auth_service = container.auth_service()\n client_id = await auth_service.get_api_key(\"{service}_client_id\")\n client_secret = await auth_service.get_api_key(\"{service}_client_secret\")\n\n if not client_id or not client_secret:\n return {\"success\": False, \"error\": \"Service not configured\"}\n\n oauth = ServiceOAuth(client_id=client_id, client_secret=client_secret)\n auth_data = oauth.generate_authorization_url()\n webbrowser.open(auth_data[\"url\"])\n\n return {\"success\": True, \"state\": auth_data[\"state\"]}\n\n\n@ws_handler()\nasync def handle_{service}_oauth_status(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:\n \"\"\"Check connection status.\"\"\"\n auth_service = container.auth_service()\n access_token = await auth_service.get_api_key(\"{service}_access_token\")\n\n if not access_token:\n return {\"connected\": False}\n\n return {\"connected\": True, \"email\": \"...\"}\n\n\n# Plugin-owned dict, registered from __init__.py\nWS_HANDLERS = {\n \"{service}_oauth_login\": handle_{service}_oauth_login,\n \"{service}_oauth_status\": handle_{service}_oauth_status,\n}\n```\n\n```python\n# server/nodes/{service}/__init__.py\nfrom services.ws_handler_registry import register_ws_handlers\nfrom ._handlers import WS_HANDLERS\n\nregister_ws_handlers(WS_HANDLERS)\n```\n\n---\n\n## Step 5: Service Handlers\n\n**Post-Wave-11 the operation logic is inlined into the plugin class** as `@Operation`-decorated methods on the `ActionNode` / `ToolNode` subclass in `server/nodes/{service}/{plugin}/__init__.py`; shared helpers live alongside as `_base.py` / `_<service>.py`. The standalone `server/services/handlers/{service}.py` file no longer exists (Google's six operations, for example, are inlined into the six service plugins under [server/nodes/google/](../server/nodes/google/) with shared helpers `_base.py` / `_gmail.py` / `_auth_helper.py`). The template below shows the pre-Wave-11 handler shape for historical reference:\n\n```python\n\"\"\"\n{Service} node handlers.\n\nProvides handlers for all {service} operations:\n- Operation 1\n- Operation 2\n- etc.\n\"\"\"\n\nimport asyncio\nfrom typing import Any, Dict\n\nfrom core.logging import get_logger\n\nlogger = get_logger(__name__)\n\n\nasync def _get_service(parameters: Dict[str, Any], context: Dict[str, Any]):\n \"\"\"Get authenticated service client.\"\"\"\n from core.container import container\n\n account_mode = parameters.get('account_mode', 'owner')\n\n if account_mode == 'customer':\n customer_id = parameters.get('customer_id')\n db = container.database()\n connection = await db.get_service_connection(customer_id)\n if not connection:\n raise ValueError(f\"No connection for customer: {customer_id}\")\n access_token = connection.access_token\n await db.update_service_last_used(customer_id)\n else:\n auth_service = container.auth_service()\n access_token = await auth_service.get_api_key(\"{service}_access_token\")\n if not access_token:\n raise ValueError(\"Service not connected. Please authenticate via Credentials.\")\n\n # Build and return service client\n return build_client(access_token)\n\n\nasync def handle_{operation1}(\n node_id: str,\n node_type: str,\n parameters: Dict[str, Any],\n context: Dict[str, Any]\n) -> Dict[str, Any]:\n \"\"\"Handle {operation1}.\"\"\"\n try:\n service = await _get_service(parameters, context)\n\n # Execute operation\n result = await asyncio.get_event_loop().run_in_executor(\n None, lambda: service.operation1().execute()\n )\n\n return {\n \"success\": True,\n \"result\": {...},\n \"node_id\": node_id,\n }\n except Exception as e:\n logger.error(f\"{operation1} failed: {e}\")\n return {\"success\": False, \"error\": str(e), \"node_id\": node_id}\n\n\n# Add more handlers for each operation...\n```\n\n### Register Handlers\n\n**No `node_executor.py` edit needed (post-Wave-11).** The plugin class auto-registers its handler via `BaseNode.__init_subclass__` on import — dispatch flows through `BaseNode.execute()`. The pre-Wave-11 manual registry entry in `server/services/node_executor.py::_build_handler_registry()` is gone.\n\n---\n\n## Step 6: Frontend Node Definitions\n\n**No frontend changes required.** Post-Wave-11 nodes are declared as Python plugins (Step 5); the frontend fetches NodeSpec via GET /api/schemas/nodes/{type}/spec.json and renders without per-service TypeScript. The Pydantic Params class doubles as the LLM-visible tool schema; icon goes in <plugin>/icon.svg; color in <plugin>/meta.json. See [node_creation.md](./node_creation.md) and [server/nodes/README.md](../server/nodes/README.md) for the canonical recipe.\n\n---\n\n\n## Step 7: AI Tool Schemas\n\n> **Historical — superseded.** Dual-purpose nodes no longer add schemas to `_get_tool_schema()`: the plugin's Pydantic `Params` class IS the LLM-visible tool schema (`usable_as_tool = True`), and `services/handlers/{service}.py` dispatcher modules no longer exist (logic lives in the plugin's `@Operation` methods). `_get_tool_schema` survives only for delegation schemas. Do not follow this step.\n\nAdd Pydantic schemas in `server/services/ai.py`:\n\n```python\ndef _get_tool_schema(self, node_type: str, parameters: Dict[str, Any] = None):\n \"\"\"Get Pydantic schema for tool node.\"\"\"\n\n # ... existing schemas\n\n # {Service} schemas\n elif node_type == '{operation1}Node':\n class Operation1Schema(BaseModel):\n param1: str = Field(description=\"Description of param1\")\n param2: Optional[str] = Field(default=None, description=\"Optional param2\")\n return Operation1Schema\n```\n\n### Add Tool Dispatchers\n\nIn `server/services/handlers/tools.py`:\n\n```python\nasync def execute_tool(...):\n # ... existing dispatchers\n\n elif node_type == '{operation1}Node':\n return await _execute_{operation1}(args, node_params)\n\n\nasync def _execute_{operation1}(args: Dict[str, Any], node_params: Dict[str, Any]) -> Dict[str, Any]:\n \"\"\"Execute {operation1} via service handler.\"\"\"\n from services.handlers.{service} import handle_{operation1}\n\n parameters = {**node_params, **args}\n return await handle_{operation1}(\n node_id=\"tool_{operation1}\",\n node_type=\"{operation1}Node\",\n parameters=parameters,\n context={}\n )\n```\n\n---\n\n## Step 8: Output Schemas (backend)\n\nOutput shapes live on the backend — the editor fetches them lazy (see [schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md)). Add one Pydantic model per node type to [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) and register it:\n\n```python\n# server/services/node_output_schemas.py\n\nclass YourServiceOutput(_OutputBase):\n result_id: Optional[str] = None\n field1: Optional[str] = None\n field2: Optional[list] = None\n timestamp: Optional[str] = None\n\n# In NODE_OUTPUT_SCHEMAS:\nNODE_OUTPUT_SCHEMAS[\"yourServiceOperationNode\"] = YourServiceOutput\n```\n\nInputSection consumes these automatically via `GET /api/schemas/nodes/{node_type}.json`. No frontend change needed. Shape shared across operations? Assign the same model to multiple keys in `NODE_OUTPUT_SCHEMAS` (see how `_SEARCH_TYPES` aliases `SearchOutput`).\n\n---\n\n## Step 9: Credentials Modal\n\n**No React changes required.** Post-Wave-7 the Credentials Modal renders entirely from `server/config/credential_providers.json` via the catalogue → `useCatalogueQuery` → `ApiKeyPanel` / `OAuthConnect` chain. To add a new provider:\n\n1. Add an entry to `server/config/credential_providers.json` with `id`, `name`, `category`, `fields[]` (validation/connect targets + optional secondary fields like Telegram's owner-chat-id), `icon_ref` (URL form `/api/schemas/credentials/<id>/icon`), and `panel_type` (`api_key` / `oauth` / `qr_pairing` / `email_smtp`).\n2. Drop the brand SVG at `server/credentials/icons/<id>.svg` (served by `GET /api/schemas/credentials/<id>/icon`).\n3. Implement the `Credential` subclass in your plugin folder's `_credentials.py` (validation, `_probe(api_key)` for API keys, or OAuth callback router for OAuth flows).\n\nSee [credentials_encryption.md](./credentials_encryption.md) for the catalogue contract and `Credential` base class details.\n\n---\n\n## Step 10: Pricing Configuration\n\nAdd to `server/config/pricing.json`:\n\n```json\n{\n \"api\": {\n \"{service}\": {\n \"_description\": \"{Service} API pricing\",\n \"_source\": \"https://provider.com/pricing\",\n \"operation1\": 0.001,\n \"operation2\": 0.002\n }\n },\n \"operation_map\": {\n \"{service}\": {\n \"create\": \"operation1\",\n \"list\": \"operation2\"\n }\n }\n}\n```\n\n### Add Usage Tracking\n\n```python\n# In handler\nasync def _track_{service}_usage(node_id: str, operation: str, count: int, ...):\n \"\"\"Track API usage for cost calculation.\"\"\"\n from services.pricing import get_pricing_service\n\n pricing = get_pricing_service()\n cost = pricing.calculate_api_cost(\"{service}\", operation, count)\n\n # Store to database\n ...\n```\n\n---\n\n## Step 11: WebSocket Context Updates\n\nUpdate `client/src/contexts/WebSocketContext.tsx`:\n\n```typescript\n// Add state\nconst [{service}Status, set{Service}Status] = useState<ServiceStatus>({\n connected: false,\n email: null,\n});\n\n// Add message handler\ncase '{service}_oauth_complete':\n if (data?.success) {\n set{Service}Status({\n connected: true,\n email: data.email,\n });\n }\n break;\n\n// Export in context value\n{service}Status,\n```\n\n---\n\n## Example: Google Workspace Integration\n\nThe Google Workspace integration demonstrates this pattern with:\n\n**Note:** post-extraction, all Google Workspace code lives inside the self-contained plugin folder [server/nodes/google/](../server/nodes/google/). The former `server/services/google_oauth.py`, `server/services/handlers/{calendar,drive,gmail,sheets,tasks,contacts}.py`, and `server/services/handlers/google_auth.py` files are gone — their bodies moved into the plugin folder (OAuth client → `_oauth.py`, shared credential builder → `_auth_helper.py`, per-service operations inlined into the service plugins). The pre-Wave-11 `client/src/nodeDefinitions/*.ts` files no longer exist at all.\n\n### Files (current layout)\n\n| File | Purpose |\n|------|---------|\n| `server/nodes/google/__init__.py` | Self-registration: WS handlers, router, OAuth callback path, service-refresh, filter builder, 4 option loaders, canary trigger |\n| `server/nodes/google/_oauth.py` | OAuth 2.0 client with google-auth-oauthlib (was `services/google_oauth.py`) |\n| `server/nodes/google/_auth_helper.py` | Shared credential builder + proactive refresh (was `services/handlers/google_auth.py`) |\n| `server/nodes/google/_credentials.py` | `GoogleCredential` (OAuth2) — referenced by all 6 service plugins |\n| `server/nodes/google/_handlers.py` | WS handlers: `google_oauth_login` / `google_oauth_status` / `google_logout` |\n| `server/nodes/google/_router.py` | HTTP OAuth callback (`/api/google/callback`) |\n| `server/nodes/google/_option_loaders.py` | `gmailLabels` / `googleCalendarList` / `googleDriveFolders` / `googleTasklists` loaders |\n| `server/nodes/google/_base.py`, `_gmail.py` | Shared helpers (`build_google_service`, `run_sync`, `track_google_usage`, Gmail-specific) |\n| `server/nodes/google/{gmail,calendar,drive,sheets,tasks,contacts}/__init__.py` | 6 service plugins (operation logic inlined) |\n| `server/nodes/google/gmail_receive/__init__.py` | Polling trigger plugin |\n| `server/config/google_apis.json` | API endpoints and scopes |\n\n### Files Modified (cross-cutting)\n\n| File | Changes |\n|------|---------|\n| `server/models/database.py` | Added `GoogleConnection` model |\n| `server/core/database.py` | Added CRUD methods, migration logic |\n| `server/services/ai.py` | Added Pydantic schemas for AI tools (dual-purpose nodes) |\n| `server/services/handlers/tools.py` | Added tool dispatchers |\n| `server/services/node_output_schemas.py` | Added per-operation output schemas |\n| `server/config/pricing.json` | Added Google API pricing |\n\nNo frontend edits: the node definitions, credentials panel, output schemas, and Dashboard component routing are all now driven by the backend `NodeSpec` + `credential_providers.json` catalogue.\n\n### Combined OAuth Scopes\n\n```python\nGOOGLE_WORKSPACE_SCOPES = [\n # User Info\n \"openid\",\n \"https://www.googleapis.com/auth/userinfo.email\",\n \"https://www.googleapis.com/auth/userinfo.profile\",\n # Gmail\n \"https://www.googleapis.com/auth/gmail.send\",\n \"https://www.googleapis.com/auth/gmail.readonly\",\n \"https://www.googleapis.com/auth/gmail.modify\",\n # Calendar\n \"https://www.googleapis.com/auth/calendar\",\n \"https://www.googleapis.com/auth/calendar.events\",\n # Drive\n \"https://www.googleapis.com/auth/drive\",\n \"https://www.googleapis.com/auth/drive.file\",\n # Sheets\n \"https://www.googleapis.com/auth/spreadsheets\",\n # Tasks\n \"https://www.googleapis.com/auth/tasks\",\n # Contacts\n \"https://www.googleapis.com/auth/contacts\",\n \"https://www.googleapis.com/auth/contacts.readonly\",\n]\n```\n\n---\n\n## Checklist\n\nUse this checklist when adding a new service:\n\n- [ ] **OAuth Service** (`server/nodes/{service}/_oauth.py`)\n - [ ] Define scopes\n - [ ] Implement `generate_authorization_url()`\n - [ ] Implement `exchange_code()`\n - [ ] Implement `refresh_credentials()`\n - [ ] Add `get_pending_state()` helper\n\n- [ ] **Database** (`server/models/database.py`, `server/core/database.py`)\n - [ ] Add `ServiceConnection` model\n - [ ] Add import to `core/database.py`\n - [ ] Add CRUD methods (save, get, delete, update_last_used)\n - [ ] Add migration for table rename if needed\n\n- [ ] **API Router** (`server/nodes/{service}/_router.py`)\n - [ ] Add callback endpoint\n - [ ] Add status endpoint\n - [ ] Add logout endpoint\n - [ ] Add customer endpoints if needed\n - [ ] Register from `__init__.py` via `register_router(...)` + `register_oauth_callback_path(...)`\n\n- [ ] **WebSocket Handlers** (`server/nodes/{service}/_handlers.py`)\n - [ ] Add `handle_{service}_oauth_login`\n - [ ] Add `handle_{service}_oauth_status`\n - [ ] Collect into a `WS_HANDLERS` dict, register from `__init__.py` via `register_ws_handlers(...)`\n\n- [ ] **Operation Logic** (plugin classes in `server/nodes/{service}/{plugin}/__init__.py`)\n - [ ] Add `@Operation`-decorated methods for each operation\n - [ ] Shared helpers in `_base.py` / `_<service>.py`, credential builder in `_auth_helper.py`\n - [ ] Auto-registers via `BaseNode.__init_subclass__` — no `node_executor.py` edit\n\n- [ ] **Frontend Nodes** — none. The `NodeSpec` emitted by the plugin drives the palette, canvas component, and parameter panel automatically (see [node_creation.md](./node_creation.md)).\n\n- [ ] **AI Tool Integration** — *(historical; superseded)* set `usable_as_tool = True` on the plugin class; its Pydantic `Params` IS the LLM tool schema. No `_get_tool_schema()` entry, no `execute_tool()` dispatcher, no handler functions.\n\n- [ ] **Output Schemas** (`server/services/node_output_schemas.py`)\n - [ ] Add a Pydantic model per node type, register in `NODE_OUTPUT_SCHEMAS`\n\n- [ ] **Credentials Modal** — no React edits. Add an entry to `server/config/credential_providers.json`, drop the brand SVG at `server/credentials/icons/<id>.svg`, and implement the `Credential` subclass in the plugin's `_credentials.py` (see Step 9).\n\n- [ ] **WebSocket Context** (`client/src/contexts/WebSocketContext.tsx`)\n - [ ] Add OAuth complete handler\n - [ ] Add state if needed\n\n- [ ] **Pricing** (`server/config/pricing.json`)\n - [ ] Add service pricing\n - [ ] Add operation map\n - [ ] Add URL patterns if using tracked HTTP\n\n- [ ] **Skills** (`server/skills/{agent_type}/`)\n - [ ] Create skill folder (e.g., `productivity_agent/`)\n - [ ] Add SKILL.md for each service capability\n - [ ] Define allowed-tools in frontmatter\n - [ ] Update GUIDE.md folder structure\n\n---\n\n## Best Practices\n\n1. **Use Existing Patterns** - Follow the Google Workspace implementation as a template\n2. **Unified OAuth** - If a provider has multiple services, use combined scopes\n3. **Dual-Purpose Nodes** - Add `group: ['{service}', 'tool']` for AI Agent integration\n4. **Error Handling** - Always catch and log errors, return proper error responses\n5. **Token Refresh** - Implement automatic token refresh for long-running workflows\n6. **Cost Tracking** - Add pricing config and track usage for billing\n7. **Documentation** - Update CLAUDE.md with the new service section\n8. **Skills** - Create skills for AI agents to use service operations with proper instructions\n\n---\n\n## Step 12: AI Agent Skills (Optional but Recommended)\n\nCreate skills for AI agents to use the service operations.\n\n### Skill Folder Structure\n\n```\nserver/skills/{agent_type}/\n├── {service}-skill/\n│ └── SKILL.md\n```\n\nFor Google Workspace, the skills are in `server/skills/productivity_agent/`:\n- `gmail-skill/SKILL.md`\n- `calendar-skill/SKILL.md`\n- `drive-skill/SKILL.md`\n- `sheets-skill/SKILL.md`\n- `tasks-skill/SKILL.md`\n- `contacts-skill/SKILL.md`\n\n### Skill File Format\n\n```markdown\n---\nname: {service}-skill\ndescription: Brief description of capabilities\nallowed-tools: tool1 tool2 tool3\nmetadata:\n author: opencompany\n version: \"1.0\"\n category: productivity\n icon: \"icon\"\n color: \"#HEXCOLOR\"\n---\n\n# {Service} Skill\n\nDescription of what the skill provides.\n\n## Available Tools\n\n### tool_name\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| param1 | string | Yes | Description |\n\n**Example:**\n```json\n{\n \"param1\": \"value\"\n}\n```\n\n## Setup Requirements\n\n1. Connect nodes to AI Agent's `input-tools` handle\n2. Authenticate in Credentials Modal\n```\n\nSee `server/skills/GUIDE.md` for full documentation on skill creation.\n","archived":true,"sha256":"286d69339dfd478e8f270befb5719137d3ee0a4a0bd02844b4b86bbdaead89f2"},"doc:docs-internal/ARCHIVE/plugin_authoring_rfc.md":{"id":"doc:docs-internal/ARCHIVE/plugin_authoring_rfc.md","path":"docs-internal/ARCHIVE/plugin_authoring_rfc.md","title":"RFC: Plugin Authoring Standard — Folder-Default + Temporal Activities + CloudEvents Broadcasts","content":"# RFC: Plugin Authoring Standard — Folder-Default + Temporal Activities + CloudEvents Broadcasts\n\n> **ARCHIVED — Shipped Sprint Plan.** This RFC's recommendations were shipped across Waves 11.H, F1, F2, F4.A, F4.B, F5, F6, F7 (commits `1e18d3e` through `134e7a8`). Preserved here as a design-rationale record. For current state see:\n>\n> - [TEMPORAL_ARCHITECTURE.md](../TEMPORAL_ARCHITECTURE.md) — three Temporal dispatch paths (legacy / per-type / AgentWorkflow)\n> - [plugin_system.md](../plugin_system.md) — Wave 11 plugin model (BaseNode hierarchy, six generic registries, credentials, Wave 12 event framework)\n> - [server/nodes/README.md](../../server/nodes/README.md) — canonical authoring recipe (folder-per-plugin, icon.svg, meta.json)\n> - [status_broadcaster.md](../status_broadcaster.md) — CloudEvents v1.0 envelope contract (`WorkflowEvent` factories, broadcaster wrappers)\n> - [node_creation.md](../node_creation.md) — decision tree for new plugins\n\n| Field | Value |\n|---|---|\n| Status | Shipped (archived 2026-05-14) |\n| Scope | `server/nodes/**`, `server/services/plugin/**`, `server/services/events/**`, `server/services/temporal/**`, `docs-internal/*plugin*.md`, `docs-internal/node_creation.md`, `CLAUDE.md`, `server/nodes/README.md` |\n| Authors | Plan generated by Claude Code |\n| Date | 2026-05-13 |\n\n---\n\n## 1. Summary\n\nCodify the canonical plugin authoring shape for OpenCompany: every plugin is a self-contained folder under `server/nodes/<group>/<plugin>/`, its code and media co-located, inheriting shared base classes; the backend auto-registers a per-plugin Temporal activity; every server→FE event flows through a CloudEvents v1.0 `WorkflowEvent` envelope. Update the docs to match the code, fix three real CloudEvents spec violations, and migrate the 117 legacy single-file plugins.\n\n## 2. Motivation\n\nThree problems compound today:\n\n- **Docs claim ~95% match the code; the 5% gap traps new contributors.** Examples: `NODE_INPUT_MODELS` doesn't exist (real name `_DIRECT_MODELS`); \"five registries\" should be \"up to six\"; the icon override path is dead but documented as live; six hand-maintained counts drift on every change.\n- **Authoring shape is ambiguous.** Today 117 plugins are bare `.py` at the group root; 4 use the folder pattern. New contributors see two shapes and pick the wrong one or invent a third.\n- **Two production-grade contracts are under-documented.** Plugins inherit a Temporal activity automatically (`as_activity()` → `node.<type>.v<version>`) and emit CloudEvents through a typed envelope (`WorkflowEvent`), but the docs don't say \"this is how to use them\" — new authors reinvent.\n\n## 3. Goals\n\n1. One canonical authoring shape: folder-per-plugin, mandatory.\n2. Backend is the sole authority on all plugin business logic, metadata, and assets. Frontend is a rendering layer that consumes backend APIs.\n3. Document the Temporal worker contract as a first-class plugin author concern.\n4. Document the CloudEvents broadcast contract and fix three real spec violations.\n5. Eliminate dual-source-of-truth patterns (one genuine, two false-positive).\n6. Replace hand-maintained counts with derivation methods.\n\n## 4. Non-goals\n\n- No new pytest invariants beyond what already exists.\n- ~~No wiring of per-node Temporal activity dispatch in `temporal/workflow.py` (Wave 11.F gap — separate sprint).~~ **Shipped post-RFC as F4.A (commit `8261b05`).**\n- No capability-mixin implementation (mention as future direction only).\n- No entry-point-based third-party plugin loading.\n- No edits to `themedGlyphs.ts` (UI chrome, not plugin media).\n\n## 5. Design principles\n\n- **Backend owns all business logic and plugin metadata.** Plugin discovery, NodeSpec emission, output schema, credentials, icon, color, docs — all backend-resident. The frontend consults `GET /api/schemas/nodes/...` and renders.\n- **Frontend is a thin UI layer.** No business decisions, no per-plugin TypeScript code, no static fallback tables. Frontend reads the spec, renders the canvas, sends WS messages, displays broadcasts.\n- **Folder per plugin** keeps a plugin's surface area contained — code, credentials, helpers, icon, README all in one directory. The runtime sees one Python package per plugin.\n- **Auto-discovery over manifest.** `__init_subclass__` registers plugins on import; `pkgutil.walk_packages` walks the filesystem. No `package.json`-style manifest; no YAML registry.\n- **Typed envelopes over raw dicts.** `WorkflowEvent` Pydantic envelope locked by pytest invariants for every server→FE broadcast. Telemetry-high-frequency is the only documented carve-out.\n\n## 6. Design\n\n### 6.1 Canonical plugin folder\n\n```\nserver/nodes/<group>/<plugin>/\n├── __init__.py # Required. Wiring hub (zero business logic).\n├── icon.svg # Required. Co-located plugin icon.\n├── icon.dark.svg # Optional. Dark-mode variant.\n├── README.md # Recommended. Per-plugin docs.\n├── _credentials.py # Optional. Credential subclasses.\n├── _service.py # Optional. Long-lived singleton (bot/daemon/SDK).\n├── _install.py # Optional. Binary auto-installer.\n├── _source.py # Optional. EventSource subclass.\n├── _handlers.py # Optional. WS_HANDLERS dict.\n├── _filters.py # Optional. Event filter builder (incoming events).\n├── _refresh.py # Optional. Status refresh + trigger precheck.\n├── _events.py # Optional. Plugin-specific WorkflowEvent factories + broadcaster wrappers.\n├── _router.py # Optional. FastAPI APIRouter.\n├── _option_loaders.py # Optional. Dynamic dropdown loaders.\n├── _runtime.py # Optional. Process supervisor.\n├── <plugin>.py # Single-class plugin. (Or class lives in __init__.py.)\n│\n├── <plugin>_send.py # Multi-class split: one file per node class.\n└── <plugin>_receive.py\n```\n\n`__init__.py` is purely declarative wiring. Underscore-prefixed files are package-private (skipped by `pkgutil.walk_packages` discovery — they exist only to be imported from `__init__.py`).\n\n### 6.2 Shared class hierarchy\n\n| Tier | Location | Members |\n|---|---|---|\n| Framework bases | `server/services/plugin/` | `BaseNode`, `ActionNode`, `TriggerNode`, `ToolNode`, `WebhookTriggerNode` |\n| Domain bases | `server/nodes/<group>/_base.py` | `AndroidServiceBase`, `ChatModelBase`, `SpecializedAgentBase`, `CodeExecutorBase`, `GoogleAPIBase`, `TwitterAPIBase`, `WhatsAppBase`, `SocialBase`, `EmailBase` |\n\nA new plugin in group `X` checks `nodes/X/_base.py` for a domain base first; inherits from it if present, otherwise inherits from the appropriate framework base. Never inherits from another plugin's class.\n\n### 6.3 Temporal worker contract\n\n**Auto-registration.** Every `BaseNode` subclass gets a Temporal activity via `as_activity()` (`server/services/plugin/base.py:428-454`). The classmethod returns `@activity.defn(name=f\"node.{cls.type}.v{cls.version}\")`. `TemporalWorkerPool.collect_plugin_activities(task_queue=...)` filters plugins by `cls.task_queue` and registers their activities into the matching worker.\n\n**Plugin author declares** (class attributes on `BaseNode` subclass):\n- `type: str` — activity name becomes `node.<type>.v<version>`.\n- `version: int` — bump on backward-incompatible signature changes (Temporal versioning is name-driven).\n- `task_queue: str` — one of `TaskQueue.*` enum (`scaling.py:17-37`): `DEFAULT`, `REST_API`, `AI_HEAVY`, `CODE_EXEC`, `TRIGGERS_POLL`, `TRIGGERS_EVENT`, `ANDROID`, `BROWSER`, `MESSAGING`.\n- `start_to_close_timeout: timedelta` — **mandatory**. Plugin author owns the per-attempt budget. Framework removes its default; `__init_subclass__` raises at registration if missing.\n- `retry_policy: RetryPolicy` — optional override of `DEFAULT_RETRY`.\n- `heartbeat_timeout: timedelta` — optional override of `DEFAULT_HEARTBEAT` (2 min).\n\n**Framework guarantees:**\n- `NodeUserError` is auto-injected into `retry_policy.non_retryable_error_types`. User-correctable failures never burn retries (matches Temporal's documented \"bad input data\" non-retryable case).\n- The activity's WebSocket read loop calls `activity.heartbeat()` every 30s (`activities.py:220-242`). Long-running plugins (DeepAgent, browser automation) survive past the 2-min `heartbeat_timeout`.\n- `Worker.graceful_shutdown_timeout = timedelta(seconds=30)` — explicit shutdown window honoring SIGTERM (`worker.py`).\n\n**Status (F4):** per-node activity dispatch shipped behind a settings flag:\n\n- **F4.A** (commit `8261b05`, `TEMPORAL_PER_TYPE_DISPATCH`): orchestrator resolves `node.{type}.v{version}` per plugin via the registry; `BaseNode.as_activity()` returns a full pipeline-replacement activity that calls `workflow_service.execute_node()` in-process (skipping the legacy WS round-trip). All per-type activities register alongside the legacy `execute_node_activity` so flag-off is byte-identical. Per-queue routing (`cls.task_queue`) waits for `TemporalWorkerPool` to be wired in `main.py`.\n- **F4.B** (commit `a4d009e`, `TEMPORAL_AGENT_WORKFLOW_ENABLED`): `AgentWorkflow` Temporal child workflow + 3 activities (`agent.execute_llm_step.v1`, `agent.persist_turn.v1`, `agent.compact_memory.v1`). When enabled, the orchestrator schedules `AgentWorkflow` for the 15 migrating agent types instead of an activity; tool calls inside the loop become per-type activities. `deep_agent` / `rlm_agent` / `claude_code_agent` stay single-activity (externalised loops). Per-agent orchestrator-dispatch wiring lands in a follow-up commit.\n\n### 6.4 CloudEvents broadcast contract\n\n**Envelope.** Every server→FE broadcast wraps `WorkflowEvent` (CloudEvents v1.0; `server/services/events/envelope.py`). Pydantic model stronger than `cloudevents/sdk-python` (which is dict-based). Locked by pytest invariants in `tests/credentials/test_credential_broadcasts.py:120-152` and `tests/test_status_broadcasts.py:87-473`.\n\n**Wire shape** on the WebSocket: `{\"type\": \"<legacy_routing_key>\", \"data\": <WorkflowEvent JSON>}`. Outer wrapper is a OpenCompany transport envelope (not strict CloudEvents WS binding) — defensible because the WS channel multiplexes non-CloudEvent traffic. Inner `data` is the typed envelope and consumers route on `data.type`.\n\n**Three real spec-compliance fixes** (this RFC):\n\n1. **Extension attribute naming.** CloudEvents v1.0 mandates lowercase-alphanumeric extension keys (no underscores, dashes, dots). Today's `workflow_id`, `trigger_node_id`, `correlation_id` are non-conformant. Rename to `workflowid`, `triggernodeid`, `correlationid`. Update all 9 typed factories, frontend `cloudEvents.ts` interface, WebSocketContext readers, pytest assertions.\n2. **`type` reverse-DNS prefix.** CloudEvents Primer SHOULDs the reverse-DNS convention. Today's `credential.api_key.connected`, `agent.progress` become `com.opencompany.credential.api_key.connected`, `com.opencompany.agent.progress`. Affects all 9 typed factories and frontend glob patterns.\n3. **`dataschema` URI per event type.** Add `dataschema = f\"opencompany://schemas/events/{type_segment}.json\"` to each factory; pair with `GET /api/schemas/events/<type>.json` endpoint returning the Pydantic-derived JSON Schema for the event's `data` field.\n\n**Two factory tiers — plugin-specific factories live in the plugin folder.**\n\n- **Cross-cutting factories** stay in `server/services/events/envelope.py`. These are parametrized by plugin name and serve any plugin: `credential`, `oauth_completed`, `connection_status`, `agent_progress`, `task_completed`, `workflow_lifecycle`, `deployment_snapshot`, `team_event`, **`node_parameters_updated`** (added post-RFC at `7c9e873` — replaces 3 legacy raw-dict emission sites: parameter-panel save, Claude CLI memory bridge, AgentWorkflow per-turn memory; distinguished by `source_hint`).\n- **Plugin-specific factories** live in the plugin folder's `_events.py`. The plugin alone owns its event types, data payloads, and broadcaster wrappers. Examples: `telegram_message_received`, `stripe_payment_succeeded`, `whatsapp_group_invite`. Today these are mixed into central `envelope.py` (`WorkflowEvent.message(plugin, direction, data)` is parametrized but lives centrally); a migration step (Phase 5b) moves the plugin-specific ones out.\n\n**Plugin event author rule** (canonical four-step pattern for a new plugin-owned event type):\n\n1. **Add a typed factory in the plugin's `_events.py`** (NOT central `envelope.py`):\n ```python\n # server/nodes/telegram/_events.py\n from services.events.envelope import WorkflowEvent\n\n def telegram_message_received(*, chat_id: str, text: str, workflowid: str | None = None) -> WorkflowEvent:\n return WorkflowEvent(\n source=\"opencompany://nodes/telegram\",\n type=\"com.opencompany.telegram.message.received\",\n subject=chat_id,\n dataschema=\"opencompany://schemas/events/telegram.message.received.json\",\n data={\"chat_id\": chat_id, \"text\": text},\n workflowid=workflowid,\n )\n\n async def broadcast_telegram_message_received(broadcaster, **kwargs):\n event = telegram_message_received(**kwargs)\n await broadcaster.broadcast({\n \"type\": \"telegram_message_received\",\n \"data\": event.model_dump(mode=\"json\"),\n })\n ```\n2. **Import + register from the plugin's `__init__.py`** so the broadcaster wrapper is reachable:\n ```python\n from ._events import broadcast_telegram_message_received # noqa: F401 — re-export\n ```\n Plugin code (e.g. `_service.py`) imports the wrapper from the plugin module and calls it with the singleton `StatusBroadcaster` instance.\n3. **Add a frontend handler in `client/src/contexts/WebSocketContext.tsx`** routing on the wire key (`telegram_message_received`). The frontend is plugin-aware only at the wire-key level — no plugin-specific TypeScript code beyond the case branch + the typed cast on `msg.data`.\n4. **Add a pytest parity test in `tests/test_status_broadcasts.py`** using `inspect.getsource` introspection (mirrors existing pattern). The test asserts the broadcaster wrapper constructs the typed envelope and emits with the expected wire key.\n\n**What lives where (definitive table):**\n\n| Concern | Location | Why |\n|---|---|---|\n| Cross-cutting event factories (`credential`, `agent_progress`, etc.) | `server/services/events/envelope.py` | Parameterized by plugin name; serve every plugin uniformly. |\n| Cross-cutting broadcaster helpers (`broadcast_credential_event`, `broadcast_agent_progress`) | `server/services/status_broadcaster.py` | Same reasoning — cross-cutting. |\n| Plugin-specific event factories | `server/nodes/<group>/<plugin>/_events.py` | Plugin alone owns its events; no central catalog touched on plugin add. |\n| Plugin-specific broadcaster wrappers | `server/nodes/<group>/<plugin>/_events.py` | Co-located with factories. |\n| Wire-key routing on frontend | `client/src/contexts/WebSocketContext.tsx` | The frontend is a thin renderer — one switch case per wire key; no plugin-specific logic. |\n| Pytest invariants | `server/tests/test_status_broadcasts.py` + `tests/credentials/test_credential_broadcasts.py` | Centralized for contract-locking. |\n\n**Forbidden.** Emitting raw-dict payloads via `update_node_status` for new event types. `_LEGACY_RAW_DICT_CALLSITES` allowlist (`test_status_broadcasts.py:87-109`) is closed; only telemetry-high-frequency carve-outs (node_status, variable updates, logs) are permanently exempt. Plugin-specific factories MUST NOT be added to central `envelope.py` — they belong in the plugin folder.\n\n**Definition — plugin-specific vs cross-cutting:**\n\nA factory is **plugin-specific** if its `type` string names a single plugin AND its payload shape differs from peers in the same domain (`com.opencompany.telegram.message.received` carries `chat_id`; `com.opencompany.whatsapp.message.received` carries `phone_number` + `group_jid`). These belong in `_events.py` in the plugin folder.\n\nA factory is **cross-cutting** if either (a) its `type` is the same shape across plugins and the payload is identical, OR (b) its construction is invoked from a single centralized helper that fans out per plugin: `credential.<action>` (every plugin with credentials), `oauth.completed` (every OAuth plugin), `agent.progress` (every agent), `task.completed` (every delegated task), `workflow.<stage>` (workflow lifecycle), `deployment.snapshot` (deployment state), `connection_status` (single `_emit_connection_typed` helper in `StatusBroadcaster` fans out to every plugin status method). These stay in central `envelope.py`.\n\n**Phase 5b audit outcome:**\n- `WorkflowEvent.message(plugin, direction, data)` — **removed** in Phase 5b. Zero callers in the codebase; it was speculative. Plugins that later need to emit message envelopes add a typed factory in their own `_events.py`.\n- `WorkflowEvent.connection_status(plugin, ...)` — **kept** in central `envelope.py`. Single call site (`StatusBroadcaster._emit_connection_typed`); the parametrization is genuinely shared. Moving per-plugin would duplicate the broadcast helper across plugins with no payload divergence.\n- `nodes/stripe/_source.py` hand-constructs `WorkflowEvent(...)` directly. Stripe webhook events keep their producer-side type (`stripe.charge.succeeded` — no `com.opencompany.` prefix since OpenCompany isn't the producer). Already in the plugin folder. No move needed.\n\n### 6.5 Icon and media handling — backend owns, frontend consumes\n\n**Storage**: per-plugin `icon.svg` co-located in `server/nodes/<group>/<plugin>/`.\n\n**Serving**: new backend endpoint `GET /api/schemas/nodes/{type}/icon` reads the SVG from disk and returns it with `Content-Type: image/svg+xml` and a cache header. Optional `?variant=dark` for `icon.dark.svg`. NodeSpec metadata exposes the URL: `{\"icon\": \"/api/schemas/nodes/aiAgent/icon\"}` instead of the legacy `asset:aiAgent` wire format. Adds one route to `server/routers/schemas.py` (or wherever the existing `/api/schemas/nodes/<type>/spec.json` route lives).\n\n**Frontend resolver** (`client/src/assets/icons/index.ts` + `NodeIcon.tsx`):\n- Existing `import.meta.glob('./**/*.svg', {eager: true, query: '?raw'})` stays — covers themed glyphs (`themedGlyphs.ts`) and library icons.\n- Dispatch becomes: `lobehub:<brand>` → React component; emoji/text → inline; URL (starts with `/api/schemas/nodes/…/icon` or `https://`) → `<img src={url}>`; legacy `asset:<key>` → bundled `ICON_REGISTRY` (kept for transition; removed when migration completes).\n\n**Why API-served, not build-step copy**: the frontend is a thin UI layer. Build-time coupling between `server/nodes/**/*.svg` and `client/public/node-icons/...` makes the frontend a stakeholder in backend file layout. API-served icons mean the backend is the sole authority on plugin assets; the frontend just renders URLs. Hot-reload works without rebuilding the frontend; new plugins drop in without a build step. Browser HTTP cache handles performance.\n\n**`visuals.json` shrinks** to entries that don't have a folder `icon.svg`:\n- Emoji-only plugins.\n- `lobehub:<brand>` library icons.\n- Color overrides (icon defaults to the folder `icon.svg`; color stays declared until colors also move to per-folder `meta.json` — deferred).\n\n**Stays put** (NOT plugin media): `client/src/assets/icons/themedGlyphs.ts` (UI chrome — 290 glyphs across 29 keys × 10 themes), `@lobehub/icons` library imports.\n\n### 6.6 Eliminate the icon/color class-attr dead path\n\n`server/services/plugin/base.py`:\n- Delete `icon: ClassVar[str] = \"\"` and `color: ClassVar[str] = \"\"` (lines 123-124).\n- Simplify `_metadata_dict` lines 206-207: `icon = get_icon(cls.type)`, `color = get_color(cls.type)`.\n- Remove docstring sentence about the optional override (lines 199-203).\n\nAudit confirmed at RFC time: 0 of 122 plugins set the dead class-attr `icon`/`color`. Post-Phase-8 plugin count: 113 plugin folders (live count via `glob server/nodes/**/__init__.py`). `_metadata_dict` resolves icon in three tiers (RFC §6.5 + F7 closure): per-node-type `<plugin>/icon_<nodeType>.svg` → shared `<plugin>/icon.svg` → `visuals.json` emoji / `lobehub:<brand>`. The asset:<key> fallback that originally lived in tier 3 is dead post-F7 — visuals.json carries zero `asset:` entries. Color resolves via per-plugin `meta.json` (F2) → `visuals.json` legacy fallback (currently empty — all 117 plugins ship `meta.json`).\n\n### 6.7 Doc rewrites — what changes where\n\n| File | Sections rewritten |\n|---|---|\n| `CLAUDE.md` | \"Adding a new node — the canonical recipe\", \"Icon + color\", \"WebSocket-first architecture\" handler count |\n| `docs-internal/plugin_system.md` | \"Adding a new node\", \"Registries\" (5→up-to-6 plus `register_router`), new \"Temporal worker contract\" + \"CloudEvents broadcast contract\" sections, icon section |\n| `docs-internal/node_creation.md` | \"Choose your shape\" → one shape; full walkthrough rewritten around folder template |\n| `docs-internal/schema_source_of_truth_rfc.md` | `NODE_INPUT_MODELS` → `_DIRECT_MODELS`; path claim updated; icon section |\n| `server/nodes/README.md` | Quick-start + 5-minute recipe rewritten around folder template + Temporal + CloudEvents contracts |\n| `docs-internal/ai_tool_node_creation.md`, `specialized_agent_node_creation.md`, `dual_purpose_tool_node_creation.md` | Banner verification only (prepend pre-Wave-11 historical-reference banner if missing) |\n\n### 6.8 Factual corrections + count strip\n\n**Discrepancies:**\n- `NODE_INPUT_MODELS` → `_DIRECT_MODELS` in `plugin_system.md:79-81`, `node_creation.md:210`, `schema_source_of_truth_rfc.md:39`.\n- \"Five cross-cutting registries\" → \"Up to six\" in `plugin_system.md:482`. Add `register_router` (`services/ws_handler_registry.py:85-94`).\n- Telegram \"6 register_* calls\" → 5 in `plugin_system.md:468`, `server/nodes/README.md:227`.\n\n**Counts replaced with derivation methods:**\n\n| File:line | Stale | Replace with |\n|---|---|---|\n| `CLAUDE.md:49` | \"89 handlers\" | \"live count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`\" |\n| `plugin_system.md:9` | \"111 plugin classes … 124 pytest invariants\" | \"live count via `glob server/nodes/**/__init__.py`\" |\n| `plugin_system.md:674` | \"108 … 124 total\" | \"live total via `pytest --collect-only`\" |\n| `schema_source_of_truth_rfc.md:7` | \"98 Pydantic models\" | \"live size via `len(NODE_OUTPUT_SCHEMAS)`\" |\n| `schema_source_of_truth_rfc.md:20` | \"105 input models\" | \"live count via `len(_DIRECT_MODELS)`\" |\n| `schema_source_of_truth_rfc.md:25` | \"25 groups with 110 entries … 34 hand-rolled\" | \"live count via `len(NODE_GROUPS)`\" |\n\nSnapshot counts marking historical milestones (`12.8K → 1.1K LOC`) stay.\n\n## 7. Implementation phases\n\n| # | Phase | Scope | Risk |\n|---|---|---|---|\n| 1 | Dead-path removal | `server/services/plugin/base.py` icon/color class attrs | Low |\n| 2 | Factual corrections + count strip | 5 doc files | Low |\n| 3 | Folder-template doc rewrite | 5 doc files | Low |\n| 4 | Temporal contract tightening | `base.py` mandatory `start_to_close_timeout`, `scaling.py` NodeUserError mapping, `Worker` graceful_shutdown_timeout | Medium (touches every plugin — need migration) |\n| 5a | CloudEvents spec fixes | `envelope.py` extension rename + type prefix + dataschema; `cloudEvents.ts` interface; `WebSocketContext.tsx` readers; pytest assertions | Medium (wire-format change — coordinate FE+BE in one commit) |\n| 5b | Migrate plugin-specific factories to plugin folders | Move `WorkflowEvent.message(plugin, ...)` and any plugin-named factories from `services/events/envelope.py` into `server/nodes/<plugin>/_events.py`. Audit existing broadcaster calls in `_service.py` files (whatsapp, telegram, stripe) — they currently hand-construct envelopes; refactor to import the per-plugin wrapper from `_events.py`. Update pytest invariants to assert plugin-specific factories are NOT in central `envelope.py`. | Medium (touches plugin services that emit events today) |\n| 6 | Icon endpoint | `server/routers/schemas.py` new `GET /api/schemas/nodes/{type}/icon`; `_metadata_dict` URL emission | Low |\n| 7 | Frontend icon resolver | `index.ts` + `NodeIcon.tsx` URL dispatch | Low |\n| 8 | Plugin migration to folders | 117 plugins, group-by-group; pytest-gated per batch | High volume, low per-unit risk |\n| 9 | SVG migration to per-folder | 30 SVGs move from `client/src/assets/icons/<group>/<name>.svg` to `server/nodes/<group>/<plugin>/icon.svg` | Low |\n| 10 | Banner verification | 3 pre-Wave-11 historical guides | Low |\n\n**Phase 8 batch order** (lowest-risk first):\n\n| Batch | Groups | Plugin count |\n|---|---|---|\n| B1 | chat, scheduler, text, workflow | 7 |\n| B2 | tool, search, trigger, utility | 17 |\n| B3 | location, proxy, scraper, skill | 10 |\n| B4 | document, filesystem, browser | 11 |\n| B5 | code, email | 6 |\n| B6 | model (`ChatModelBase`) | 11 |\n| B7 | agent (`SpecializedAgentBase`) | 19 |\n| B8 | google, twitter, social | 13 |\n| B9 | android (`AndroidServiceBase`) | 16 |\n| B10 | telegram, stripe, whatsapp | 7 (verify only — already folder-shape) |\n\nPer-batch verification: `pytest tests/test_node_spec.py -x && pytest tests/test_plugin_self_containment.py -x && pytest tests/ -x` plus frontend smoke (drag 3 migrated nodes onto canvas).\n\n## 8. Migration / rollout\n\n**Phase 1-3** ship independently (doc fixes + dead-code removal). No runtime effect.\n\n**Phase 4 (mandatory `start_to_close_timeout`)** is breaking — every plugin must declare it. Migration: walk all 122 plugins, add `start_to_close_timeout = timedelta(minutes=…)` matching the kind-specific default the framework had (ACTION 10m, AI 30m, TRIGGER 24h, CODE 5m). Single commit, gated by pytest registration check.\n\n**Phase 5 (CloudEvents spec fixes)** is a wire-format change — extension keys rename + type prefix change. FE + BE coordinated in one commit. Existing connected sessions hit one disconnect/reconnect cycle; no persistent data affected. Pytest invariants in `test_credential_broadcasts.py` and `test_status_broadcasts.py` update in the same commit.\n\n**Phases 6-7 (icon endpoint + frontend resolver)** ship together. The frontend keeps the legacy `asset:<key>` → bundled `ICON_REGISTRY` fallback during transition. Remove the fallback after Phase 9 completes.\n\n**Phase 8 (plugin migration)** runs in 10 batches over multiple commits. Each batch is mechanical and reversible. Pytest invariants gate progress.\n\n**Phase 9 (SVG migration)** runs after Phase 8 (per-plugin folders exist) and after Phase 6 (endpoint serves the new location).\n\n## 9. Backward compatibility\n\n- **Legacy `asset:<key>` wire format** stays during transition. Frontend resolver: URL paths (start with `/`) → `<img>`; `asset:<key>` → bundled `ICON_REGISTRY`; emoji/text → inline; `lobehub:<brand>` → React component. Bundled registry removed after Phase 9.\n- **CloudEvents wire keys** (the outer `type` value) stay unchanged for existing event types — only the inner `WorkflowEvent.type` gains the `com.opencompany.` prefix. Frontend handlers route on the outer wire key (e.g., `case 'credential_catalogue_updated'`) so they continue to work without coordination.\n- **Plugin imports.** Migrating `server/nodes/tool/calculator_tool.py` to `server/nodes/tool/calculator_tool/__init__.py` preserves the import path `from nodes.tool.calculator_tool import CalculatorToolNode`. Sub-module imports like `from nodes.tool.calculator_tool.calculator_tool import X` work for multi-class plugins. Audit `server/tests/` before each batch for deeper imports.\n\n## 10. Open questions\n\nNone blocking. Status of the three original follow-ups:\n\n1. ✅ **Migrate node colors from `visuals.json` to per-plugin `meta.json`** — Shipped (F2, commits `796d365` + `637de1e`). 113 plugin folders ship `meta.json`. Resolver: `get_plugin_meta(type, 'color')` falls through to `get_color()` for legacy entries.\n2. **Capability mixins** (`RequiresOAuth`, `SupportsStreaming`) — Still deferred (F3).\n3. ✅ **Per-node Temporal activity dispatch + AgentWorkflow** — Shipped behind flags (F4.A `8261b05` + F4.B infra `a4d009e`). Per-agent orchestrator wiring for the 15 migrating types is a separate follow-up commit.\n\n## 11. Verification\n\n**Code edits:**\n- `git grep -E \"cls\\.icon|cls\\.color\"` in `server/services/plugin/base.py` → 0 hits.\n- `git grep -E \"(icon|color): ClassVar\"` in `server/` → 0 hits.\n- `git grep -E \"\\bworkflow_id\\b|\\btrigger_node_id\\b|\\bcorrelation_id\\b\" server/services/events/envelope.py` → 0 hits.\n- `git grep -E '\"type\":\\s*\"(credential|agent|workflow|team|connection)\\.[^c]'` in `envelope.py` → 0 hits (every event type starts with `com.opencompany.`).\n- Boot backend; `GET /api/schemas/nodes/aiAgent/spec.json` returns populated `metadata.icon` pointing at `/api/schemas/nodes/aiAgent/icon`.\n- `GET /api/schemas/nodes/aiAgent/icon` returns SVG with `Content-Type: image/svg+xml`.\n- `pytest server/tests/ -x` passes, including the three load-bearing suites: `test_node_spec.py`, `test_plugin_self_containment.py`, `test_credential_broadcasts.py`, `test_status_broadcasts.py`.\n- `find server/nodes/<group>/ -maxdepth 1 -type f -name '*.py' -not -name '_*' -not -name '__init__.py'` → 0 hits in every group post-Phase-8.\n\n**Doc edits:**\n- `git grep -n \"NODE_INPUT_MODELS\"` in docs → 0 hits.\n- `git grep -n \"Five cross-cutting registries\"` → 0 hits.\n- `git grep -nE \"\\b(89|111|98|105|110|124) (handlers|plugins|invariants|models|entries)\"` → 0 hits.\n- Five canonical doc files contain \"Canonical folder template\", \"Temporal worker contract\", \"CloudEvents broadcast contract\" sections.\n- Hypothetical \"add a `weatherForecast` ToolNode\" walkthrough: one path through the docs, no ambiguity.\n\n**Frontend behavior:**\n- Canvas renders every plugin icon (no broken-image fallbacks).\n- Browser network tab shows GETs to `/api/schemas/nodes/<type>/icon` returning 200 with SVG bodies.\n- No build-step references `server/nodes/**/*.svg` (frontend is decoupled).\n\n## 12. References\n\n**OpenCompany (internal):**\n- `server/services/plugin/base.py:428-454` — `as_activity()`.\n- `server/services/plugin/scaling.py:17-37` — `TaskQueue` enum, retry defaults.\n- `server/services/temporal/workflow.py:177-183` — orchestrator scheduling (gap noted).\n- `server/services/temporal/activities.py:220-242` — heartbeat-in-WS-read-loop.\n- `server/services/temporal/worker.py:171-268` — `TemporalWorkerPool`.\n- `server/services/events/envelope.py` — `WorkflowEvent` model + 9 typed factories.\n- `server/services/status_broadcaster.py:286-352` — reference broadcaster methods.\n- `server/tests/credentials/test_credential_broadcasts.py:120-152` — CloudEvents shape invariant.\n- `server/tests/test_status_broadcasts.py:87-473` — broadcast contract + `_LEGACY_RAW_DICT_CALLSITES`.\n- `client/src/types/cloudEvents.ts` — frontend envelope interface.\n- `client/src/contexts/WebSocketContext.tsx:698-712, 844-876` — broadcast handler reference.\n- `server/nodes/telegram/`, `stripe/`, `whatsapp/`, `android/` — reference folder plugins.\n\n**External standards:**\n- CloudEvents v1.0 — https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md\n- CloudEvents WebSocket binding — https://github.com/cloudevents/spec/blob/main/cloudevents/bindings/websockets-protocol-binding.md\n- CloudEvents Primer (naming guidance) — https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md\n- Temporal Python SDK — https://docs.temporal.io/develop/python\n- Temporal activity decorator API — https://python.temporal.io/temporalio.activity.html\n- Temporal retry policies — https://docs.temporal.io/encyclopedia/retry-policies\n- Temporal activity failure detection / heartbeats — https://docs.temporal.io/encyclopedia/detecting-activity-failures\n\n**Industry references (architecture patterns):**\n- n8n per-node folder + co-located SVG — https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Telegram\n- Pipedream `components/<app>/` + `common/` folder pattern — https://github.com/PipedreamHQ/pipedream/tree/master/components\n- Prefect block + capability-mixin pattern — https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py\n- Nango YAML provider registry (rejected for OpenCompany) — https://github.com/NangoHQ/nango/tree/master/packages/providers\n- Composio cloud-registry model (rejected — we're self-hosted) — https://docs.composio.dev\n\n## 13. Diff size (rough)\n\n| Area | Lines |\n|---|---|\n| `server/services/plugin/base.py` | ~50 changed (dead path, mandatory timeout, NodeUserError mapping, icon URL emission) |\n| `server/services/events/envelope.py` | ~80 changed (extension rename, type prefix, dataschema) + ~50 removed (plugin-specific factories moved out) |\n| `server/nodes/<plugin>/_events.py` (5-8 plugins) | ~40-80 added per plugin (telegram, whatsapp, stripe, twitter, google) |\n| `server/services/plugin/scaling.py` | ~10 changed |\n| `server/routers/schemas.py` | ~30 added (icon endpoint) |\n| `client/src/assets/icons/index.ts` + `NodeIcon.tsx` | ~30 changed (URL dispatch) |\n| `client/src/types/cloudEvents.ts` | ~10 changed (extension keys) |\n| `client/src/contexts/WebSocketContext.tsx` | ~30 changed (extension readers + type pattern updates) |\n| `server/nodes/visuals.json` | ~80 lines removed |\n| `CLAUDE.md` | ~140 (80 changed + 60 added) |\n| `docs-internal/plugin_system.md` | ~400 (150 changed + 250 added — Temporal contract + CloudEvents contract + folder template) |\n| `docs-internal/node_creation.md` | ~180 (80 changed + 100 added) |\n| `docs-internal/schema_source_of_truth_rfc.md` | ~30 changed |\n| `server/nodes/README.md` | ~220 (100 changed + 120 added) |\n| 3 exemplar READMEs (telegram, stripe, calculator) | ~150 added |\n| Pytest assertion updates | ~50 changed |\n| Plugin migration | 117 file moves |\n| SVG migration | 30 file moves |\n\nTotal: ~1100-1400 doc lines, ~300 code lines, 147 file moves. Phase 8 is heaviest by volume (mechanical, pytest-gated). Phase 5 has the highest coordination risk (wire-format change requires FE+BE in one commit).\n","archived":true,"sha256":"d0bf32ec19633158bec98aae80e5cf9e399c624bb6405e7408cf9fd3f0f6ea99"},"doc:docs-internal/ARCHIVE/ROADMAP.md":{"id":"doc:docs-internal/ARCHIVE/ROADMAP.md","path":"docs-internal/ARCHIVE/ROADMAP.md","title":"Execution Engine Roadmap","content":"# Execution Engine Roadmap\n\n> **ARCHIVED 2026-09-04 — Superseded.** A status snapshot whose helper names, DLQ path, test list and pending-features section had all drifted (OpenTelemetry tracing shipped; `_add_to_dlq` never existed; the listed test files do not). Implementation status now lives with the design docs.\n>\n> For current state see:\n>\n> - [DESIGN.md](../DESIGN.md) — execution engine\n> - [TEMPORAL_ARCHITECTURE.md](../TEMPORAL_ARCHITECTURE.md) and [temporal-workflow-control.md](../temporal-workflow-control.md)\n\n## Overview\n\nThis document tracks the implementation status of the robust workflow execution engine based on industry-standard patterns from Netflix Conductor, Prefect 3.0, and Redis Streams.\n\n---\n\n## Completed Features\n\n### Phase 1: State Machine + Caching\n- [x] `TaskStatus` enum (PENDING, SCHEDULED, RUNNING, COMPLETED, FAILED, CACHED, CANCELLED, WAITING, SKIPPED)\n- [x] `WorkflowStatus` enum (PENDING, RUNNING, PAUSED, COMPLETED, FAILED, CANCELLED)\n- [x] `ExecutionContext` dataclass with isolated state per workflow run\n- [x] `NodeExecution` dataclass for tracking individual node state\n- [x] `execute_node_cached()` with input hashing for idempotency (Prefect pattern)\n- [x] `hash_inputs()` and `generate_cache_key()` utilities\n- [x] Redis HASH storage for execution state\n\n### Phase 2: Decide Pattern + Parallel Execution\n- [x] `workflow_decide()` with distributed locking (Conductor pattern)\n- [x] `execute_parallel_nodes()` using `asyncio.gather()` for Fork/Join (since removed; superseded by continuous scheduling via `asyncio.wait(FIRST_COMPLETED)`)\n- [x] `_compute_execution_layers()` for DAG topological sort\n- [x] `_find_ready_nodes()` to detect nodes with satisfied dependencies\n- [x] Redis distributed locks via SETNX with TTL\n\n### Phase 4: Crash Recovery\n- [x] `RecoverySweeper` background task\n- [x] Heartbeat tracking for running nodes\n- [x] `scan_on_startup()` to find interrupted executions\n- [x] Automatic recovery trigger for stuck nodes\n- [x] Integration in `main.py` lifespan\n\n### Phase 5: Event History\n- [x] Event storage in Redis Streams per execution\n- [x] Event types: workflow_started, node_started, node_completed, node_failed, workflow_completed\n- [x] `add_event()` and `get_events()` methods in ExecutionCache\n\n### Phase 6: Integration with Existing Handlers\n- [x] `_node_executor_adapter()` bridging WorkflowExecutor to existing handlers\n- [x] `_get_workflow_executor()` for lazy initialization with status callback\n- [x] `execute_workflow()` dispatches to parallel or sequential based on settings\n- [x] `_execute_workflow_parallel()` using new WorkflowExecutor\n- [x] `_execute_workflow_sequential()` as fallback when Redis unavailable\n- [x] `use_parallel_executor` deployment setting (default: True)\n\n---\n\n## Completed Features (Continued)\n\n### Phase 3: Runtime Conditional Branching [COMPLETED]\n\n**Goal**: Enable dynamic workflow paths based on node output values at runtime.\n\n**Status**: COMPLETED - Full implementation of Prefect-style runtime conditional branching.\n\n**Implementation**:\n- Created `server/services/execution/conditions.py` with 20+ condition operators\n- Updated `executor.py` `_find_ready_nodes()` to evaluate edge conditions\n- Added `TaskStatus.SKIPPED` handling for unmatched conditional branches\n- Created `client/src/types/EdgeCondition.ts` with TypeScript types and utilities\n- Created `client/src/components/EdgeConditionEditor.tsx` for condition UI\n- Created `client/src/components/ConditionalEdge.tsx` for custom edge rendering\n- Integrated ConditionalEdge into Dashboard with edgeTypes registration\n\n#### Implementation Tasks\n\n1. **Edge Condition Schema**\n ```typescript\n // Frontend: client/src/types/\n interface EdgeCondition {\n field: string; // Output field to check (e.g., \"status\", \"result.success\")\n operator: \"eq\" | \"neq\" | \"gt\" | \"lt\" | \"gte\" | \"lte\" | \"contains\" | \"exists\";\n value: any; // Value to compare against\n }\n\n interface ConditionalEdge extends Edge {\n data?: {\n condition?: EdgeCondition;\n label?: string; // Display label for the edge\n };\n }\n ```\n\n2. **Condition Evaluator** (`server/services/execution/conditions.py`)\n ```python\n def evaluate_condition(condition: dict, output: dict) -> bool:\n \"\"\"Evaluate edge condition against node output.\n\n Args:\n condition: {field, operator, value}\n output: Node execution output\n\n Returns:\n True if condition matches\n \"\"\"\n field_value = get_nested_value(output, condition[\"field\"])\n operator = condition[\"operator\"]\n target_value = condition[\"value\"]\n\n if operator == \"eq\":\n return field_value == target_value\n elif operator == \"neq\":\n return field_value != target_value\n elif operator == \"gt\":\n return field_value > target_value\n # ... etc\n ```\n\n3. **Update `decide_next_node()` in executor.py**\n ```python\n def decide_next_node(self, ctx: ExecutionContext, current_node_id: str,\n output: dict) -> List[str]:\n \"\"\"Determine next nodes based on edge conditions.\n\n Returns list of node IDs to execute next (may be multiple for fork).\n \"\"\"\n next_nodes = []\n for edge in ctx.edges:\n if edge.get(\"source\") != current_node_id:\n continue\n\n condition = edge.get(\"data\", {}).get(\"condition\")\n if condition:\n if evaluate_condition(condition, output):\n next_nodes.append(edge[\"target\"])\n else:\n # No condition = always follow\n next_nodes.append(edge[\"target\"])\n\n return next_nodes\n ```\n\n4. **Frontend Edge Condition UI** (`client/src/components/EdgeConditionEditor.tsx`)\n - Modal to configure edge conditions\n - Field selector (from source node output schema)\n - Operator dropdown\n - Value input (type-aware based on field)\n - Visual indicator on conditional edges (different color/style)\n\n5. **Edge Label Display** (`client/src/components/ConditionalEdge.tsx`)\n - Custom React Flow edge component\n - Shows condition summary as label\n - Different styling for conditional vs unconditional edges\n\n#### Files Created/Modified\n\n| File | Status | Description |\n|------|--------|-------------|\n| `server/services/execution/conditions.py` | DONE | Condition evaluation logic (20+ operators) |\n| `server/services/execution/executor.py` | DONE | Updated `_find_ready_nodes()` with condition evaluation |\n| `server/services/execution/models.py` | DONE | Added SKIPPED status handling |\n| `client/src/types/EdgeCondition.ts` | DONE | Edge condition TypeScript types |\n| `client/src/components/EdgeConditionEditor.tsx` | DONE | UI for editing conditions |\n| `client/src/components/ConditionalEdge.tsx` | DONE | Custom edge rendering |\n| `client/src/Dashboard.tsx` | DONE | Integrated edgeTypes for conditional edges |\n\n---\n\n### Phase 6: Integration - Connect WorkflowExecutor to Existing Handlers [COMPLETED]\n\n**Goal**: Replace the sequential execution in `workflow.py` with the new parallel executor.\n\n**Status**: COMPLETED - Parallel executor integrated with toggle for sequential fallback.\n\n**Implementation**:\n- Added `_node_executor_adapter()` to bridge WorkflowExecutor to existing handlers\n- Added `_get_workflow_executor()` for lazy initialization with status callback\n- Modified `execute_workflow()` to dispatch to parallel or sequential based on settings\n- Added `_execute_workflow_parallel()` using new WorkflowExecutor\n- Renamed original method to `_execute_workflow_sequential()` as fallback\n- Added `use_parallel_executor` to deployment settings (default: True)\n- Parallel execution automatically enabled when Redis is available\n\n#### Implementation Tasks\n\n1. **Create Adapter Function**\n ```python\n # server/services/workflow.py\n\n async def _node_executor_adapter(self, node_id: str, node_type: str,\n parameters: dict, context: dict) -> dict:\n \"\"\"Adapter to bridge WorkflowExecutor to existing node handlers.\"\"\"\n # Reuse existing execute_node logic\n return await self.execute_node(\n node_id=node_id,\n node_type=node_type,\n parameters=parameters,\n nodes=context.get(\"nodes\"),\n edges=context.get(\"edges\"),\n session_id=context.get(\"session_id\"),\n execution_id=context.get(\"execution_id\"),\n )\n ```\n\n2. **Initialize WorkflowExecutor in WorkflowService**\n ```python\n def __init__(self, ...):\n # ... existing init ...\n\n # Initialize execution engine\n from services.execution import WorkflowExecutor, ExecutionCache\n self._execution_cache = ExecutionCache(cache)\n self._workflow_executor = WorkflowExecutor(\n cache=self._execution_cache,\n node_executor=self._node_executor_adapter,\n status_callback=self._broadcast_node_status,\n )\n ```\n\n3. **Replace execute_workflow Implementation**\n ```python\n async def execute_workflow(self, nodes, edges, session_id, status_callback):\n \"\"\"Execute workflow using parallel executor.\"\"\"\n workflow_id = f\"workflow_{session_id}\"\n\n return await self._workflow_executor.execute_workflow(\n workflow_id=workflow_id,\n nodes=nodes,\n edges=edges,\n session_id=session_id,\n enable_caching=True,\n )\n ```\n\n4. **Update deploy_workflow for Concurrent Executions**\n ```python\n async def deploy_workflow(self, nodes, edges, session_id, status_callback):\n \"\"\"Deploy workflow with support for concurrent executions.\"\"\"\n # Generate unique execution_id per deployment iteration\n # Track multiple active executions\n # Use WorkflowExecutor for each iteration\n ```\n\n5. **Wire Status Callback to WebSocket Broadcaster**\n ```python\n async def _broadcast_node_status(self, node_id: str, status: str, data: dict):\n \"\"\"Broadcast node status via WebSocket.\"\"\"\n from services.status_broadcaster import get_status_broadcaster\n broadcaster = get_status_broadcaster()\n await broadcaster.update_node_status(node_id, status, data)\n ```\n\n#### Files to Modify\n\n| File | Changes |\n|------|---------|\n| `server/services/workflow.py` | Add WorkflowExecutor integration, adapter function |\n| `server/routers/websocket.py` | Update handlers to use new executor |\n| `server/core/container.py` | Add ExecutionCache to DI container |\n\n---\n\n### Phase 7: Retry Policies + Dead Letter Queue [COMPLETED]\n\n**Goal**: Implement robust error handling with automatic retries and failed execution quarantine.\n\n**Status**: COMPLETED - Full retry policies with exponential backoff and DLQ for failed executions.\n\n**Implementation**:\n\n#### RetryPolicy Dataclass (`server/services/execution/models.py`)\n```python\n@dataclass\nclass RetryPolicy:\n \"\"\"Retry configuration for node execution.\"\"\"\n max_attempts: int = 3\n initial_delay: float = 1.0 # seconds\n max_delay: float = 60.0 # seconds\n backoff_multiplier: float = 2.0\n retry_on_timeout: bool = True\n retry_on_connection_error: bool = True\n retry_on_server_error: bool = True # 5xx errors\n\n def calculate_delay(self, attempt: int) -> float:\n \"\"\"Exponential backoff: min(initial * multiplier^attempt, max_delay)\"\"\"\n\n def should_retry(self, error: str, attempt: int) -> bool:\n \"\"\"Check if error is retryable based on type and attempt count\"\"\"\n```\n\n#### Default Retry Policies\n```python\nDEFAULT_RETRY_POLICIES = {\n \"httpRequest\": RetryPolicy(max_attempts=3, initial_delay=2.0),\n \"webhookTrigger\": RetryPolicy(max_attempts=1), # Don't retry triggers\n \"whatsappReceive\": RetryPolicy(max_attempts=1), # Don't retry triggers\n \"aiAgent\": RetryPolicy(max_attempts=2, initial_delay=5.0, max_delay=30.0),\n \"openaiChatModel\": RetryPolicy(max_attempts=2, initial_delay=5.0),\n \"anthropicChatModel\": RetryPolicy(max_attempts=2, initial_delay=5.0),\n \"googleChatModel\": RetryPolicy(max_attempts=2, initial_delay=5.0),\n}\n```\n\n#### DLQEntry Dataclass (`server/services/execution/models.py`)\n```python\n@dataclass\nclass DLQEntry:\n \"\"\"Dead Letter Queue entry for failed node executions.\"\"\"\n id: str\n execution_id: str\n workflow_id: str\n node_id: str\n node_type: str\n error: str\n inputs: Dict[str, Any]\n retry_count: int\n created_at: float\n last_error_at: float\n```\n\n#### ExecutionCache DLQ Methods (`server/services/execution/cache.py`)\n- `add_to_dlq(entry)` - Add failed node to DLQ with multi-index storage\n- `get_dlq_entry(entry_id)` - Get single DLQ entry\n- `get_dlq_entries(workflow_id, node_type, limit)` - Query entries with filtering\n- `remove_from_dlq(entry_id)` - Remove after successful replay\n- `update_dlq_entry(entry_id, retry_count, error)` - Update after retry attempt\n- `get_dlq_stats()` - Get DLQ statistics (total, by node type, by workflow)\n- `purge_dlq(workflow_id, node_type, older_than)` - Bulk remove entries\n\n#### WorkflowExecutor Retry Integration (`server/services/execution/executor.py`)\n- `_execute_node_with_retry()` - Wraps node execution with retry loop\n- `_add_to_dlq()` - Adds failed nodes to DLQ after exhausted retries\n- `replay_dlq_entry()` - Re-execute failed node from DLQ\n- `_execute_parallel_nodes()` - Updated to use retry wrapper (helper since removed; continuous scheduling is the only implementation)\n- `_execute_single_node()` - Updated to use retry wrapper\n\n#### WebSocket API Handlers (`server/routers/websocket.py`)\n| Handler | Description |\n|---------|-------------|\n| `get_dlq_entries` | Get DLQ entries with filtering |\n| `get_dlq_entry` | Get single entry by ID |\n| `get_dlq_stats` | Get DLQ statistics |\n| `replay_dlq_entry` | Re-execute failed node |\n| `remove_dlq_entry` | Remove entry without replay |\n| `purge_dlq` | Bulk remove entries |\n\n#### Redis Key Schema (DLQ)\n```\ndlq:entries:{id} -> HASH (entry data)\ndlq:workflow:{workflow_id} -> LIST (entry IDs for workflow)\ndlq:node_type:{node_type} -> LIST (entry IDs by type)\ndlq:all -> SET (all entry IDs)\n```\n\n#### Files Modified\n| File | Changes |\n|------|---------|\n| `server/services/execution/models.py` | Added RetryPolicy, DLQEntry, DEFAULT_RETRY_POLICIES |\n| `server/services/execution/cache.py` | Added DLQ methods (add, get, remove, update, purge, stats) |\n| `server/services/execution/executor.py` | Added retry wrapper, DLQ integration, replay method |\n| `server/services/execution/__init__.py` | Export new classes and functions |\n| `server/routers/websocket.py` | Added 6 DLQ WebSocket handlers |\n\n---\n\n### Phase 8: Temporal Distributed Execution [COMPLETED]\n\n**Goal**: Enable horizontal scaling via Temporal for production deployments.\n\n**Status**: COMPLETED - Optional Temporal integration with per-node activities.\n\n**Implementation**:\n\n#### Architecture\nWhen `TEMPORAL_ENABLED=true`, each workflow node executes as an independent Temporal activity:\n- Per-node retry policy (3 attempts with exponential backoff)\n- Per-node timeout (10 min default)\n- Horizontal scaling across worker pool\n- FIRST_COMPLETED pattern for dependency resolution\n\n#### Key Components\n| File | Purpose |\n|------|---------|\n| `server/services/temporal/workflow.py` | MachinaWorkflow orchestrator (pure orchestration, no business logic) |\n| `server/services/temporal/activities.py` | NodeExecutionActivities class with connection pooling |\n| `server/services/temporal/executor.py` | TemporalExecutor interface matching WorkflowExecutor |\n| `server/services/temporal/worker.py` | TemporalWorkerManager + `run_standalone_worker()` |\n| `server/services/temporal/client.py` | Client wrapper with runtime heartbeat disabled |\n\n#### Configuration\n```env\nTEMPORAL_ENABLED=true\nTEMPORAL_SERVER_ADDRESS=localhost:5681\nTEMPORAL_NAMESPACE=default\nTEMPORAL_TASK_QUEUE=machina-tasks\n```\n\n#### Execution Routing (`workflow.py`)\n1. If `TEMPORAL_ENABLED=true` and Temporal configured -> `_execute_temporal()`\n2. Else -> `_execute_sequential()` (fallback)\n\n(The Redis-parallel `_execute_parallel()` branch is unreachable in all shipped configs; effective routing is Temporal -> sequential.)\n\n---\n\n### Phase 9: Expanded Node Types [COMPLETED]\n\n**Goal**: Comprehensive workflow automation coverage.\n\n**Status**: COMPLETED.\n\n> **The node table below is frozen at its 2025 snapshot and is NOT maintained.**\n> It read \"58 total nodes across 14 categories\" against a live count that has\n> since passed 130. Do not add to it. The authoritative count is\n> `len(services.node_registry.NODE_METADATA)`, and the authoritative list is the\n> plugin registry itself — see [node-logic-flows/](./node-logic-flows/) for\n> per-node cards and `server/nodes/README.md` for the folder map. Kept only as a\n> record of what Phase 9 delivered at the time.\n\n**Implementation**:\n\n#### Node Categories (58 total)\n| Category | Count | Nodes |\n|----------|-------|-------|\n| AI Chat Models | 6 | openai, anthropic, gemini, openrouter, groq, cerebras |\n| AI Agents & Memory | 3 | aiAgent, chatAgent, simpleMemory |\n| AI Skills | 9 | claude, whatsapp, memory, maps, http, scheduler, android, code, custom |\n| AI Tools | 4 | calculator, currentTime, webSearch, androidTool (androidTool since retired; services connect directly to `input-tools`) |\n| Android Services | 16 | battery, network, system, location, apps(2), automation(6), sensors(2), media(2) |\n| Android Device | 1 | androidDeviceSetup |\n| WhatsApp | 4 | send, connect, receive, chatHistory |\n| Location/Maps | 3 | createMap, addLocations, showNearbyPlaces |\n| Utility | 5 | httpRequest, webhookTrigger, webhookResponse, chatTrigger, console |\n| Code | 2 | pythonExecutor, javascriptExecutor |\n| Scheduler | 2 | timer, cronScheduler |\n| Chat | 2 | chatSend, chatHistory |\n| Workflow | 1 | start |\n\n#### WebSocket Handlers (51 total)\n- Execution: 4 handlers\n- Parameters: 7 handlers\n- Status & Variables: 6 handlers\n- AI Services: 6 handlers\n- Android Services: 7 handlers\n- Deployment: 4 handlers\n- Triggers & Events: 3 handlers\n- Workflow Management: 4 handlers\n- Dead Letter Queue: 5 handlers\n- WhatsApp: 8 handlers\n- Maps: 1 handler\n- Skills & Chat: 6 handlers\n\n---\n\n## Pending Features\n\n### Future Enhancements\n\n#### Sub-Workflow Support\n- Execute workflow as a node within another workflow\n- Parent-child execution tracking\n- Output propagation from sub-workflow\n\n#### Workflow Versioning\n- Track workflow definition versions\n- Support running specific versions\n- Migration between versions\n\n#### Metrics & Observability\n- Execution duration histograms\n- Success/failure rates\n- Node-level performance tracking\n- Integration with Prometheus/Grafana\n\n---\n\n## Architecture Diagram\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ WebSocket Router │\n│ (routers/websocket.py) │\n└─────────────────────────────┬───────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ WorkflowService │\n│ (services/workflow.py) │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ Node Handler Registry │ │\n│ │ - AI handlers, Android handlers, HTTP handlers, etc. │ │\n│ └─────────────────────────────────────────────────────────┘ │\n└─────────────────────────────┬───────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ WorkflowExecutor │\n│ (services/execution/executor.py) │\n│ │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │\n│ │ workflow_ │ │ execute_ │ │ _compute_execution_ │ │\n│ │ decide() │ │ parallel_ │ │ layers() │ │\n│ │ │ │ nodes() │ │ │ │\n│ │ Conductor │ │ │ │ DAG topological │ │\n│ │ pattern │ │ asyncio. │ │ sort │ │\n│ │ │ │ gather() │ │ │ │\n│ └──────────────┘ └──────────────┘ └──────────────────────┘ │\n└─────────────────────────────┬───────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ ExecutionCache │\n│ (services/execution/cache.py) │\n│ │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │\n│ │ Result │ │ Distributed │ │ Event History │ │\n│ │ Caching │ │ Locks │ │ (Redis Streams) │ │\n│ │ (Prefect) │ │ (Conductor) │ │ │ │\n│ └──────────────┘ └──────────────┘ └──────────────────────┘ │\n└─────────────────────────────┬───────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ Redis │\n│ │\n│ execution:{id}:state execution:{id}:events │\n│ result:{exec}:{node} lock:execution:{id} │\n│ heartbeat:{exec}:{node} executions:active │\n│ dlq:entries:{id} dlq:all │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Testing Checklist\n\n### Unit Tests\n- [ ] `test_models.py` - TaskStatus, WorkflowStatus, ExecutionContext serialization\n- [ ] `test_cache.py` - Result caching, distributed locks, event storage\n- [ ] `test_executor.py` - Parallel execution, decide pattern, layer computation\n- [ ] `test_recovery.py` - Sweeper detection, startup scan\n- [ ] `test_conditions.py` - Edge condition evaluation\n\n### Integration Tests\n- [ ] Execute simple linear workflow\n- [ ] Execute workflow with parallel branches\n- [ ] Execute workflow with conditional edges\n- [ ] Crash recovery simulation\n- [ ] Concurrent workflow execution\n\n### Performance Tests\n- [ ] Parallel execution speedup vs sequential\n- [ ] Redis operation latency\n- [ ] Large workflow (100+ nodes) execution time\n\n---\n\n## References\n\n- **Netflix Conductor**: [Architecture](https://conductor-oss.github.io/conductor/devguide/architecture/index.html)\n- **Prefect 3.0**: [Task Caching](https://docs.prefect.io/v3/develop/task-caching)\n- **Redis Streams**: [Consumer Groups](https://redis.io/docs/data-types/streams/)\n- **Plan Document**: `C:\\Users\\Tgroh\\.claude\\plans\\buzzing-gathering-pie.md`\n","archived":true,"sha256":"b19f80ed6cb3a5854476ce8b0182963b9b4abc606ba1afae087f5589b3d7b149"},"doc:docs-internal/ARCHIVE/schema_source_of_truth_rfc.md":{"id":"doc:docs-internal/ARCHIVE/schema_source_of_truth_rfc.md","path":"docs-internal/ARCHIVE/schema_source_of_truth_rfc.md","title":"Schema source of truth — RFC","content":"# Schema source of truth — RFC\n\n> **ARCHIVED 2026-09-04 — Superseded.** Backend-as-SSOT RFC. Everything it deferred to Wave 7 shipped: `VITE_NODESPEC_BACKEND` defaults ON, `client/src/nodeDefinitions/` was deleted, and option loaders exist for google, android, whatsapp, whatsapp_business, discord, speech and translate.\n>\n> For current state see:\n>\n> - [plugin_system.md](../plugin_system.md) — NodeSpec, registries, credentials\n> - [server/nodes/README.md](../../server/nodes/README.md) — authoring recipe\n\n**Status:** ✅ **implemented + extended to full plugin registry** · **Owner:** frontend + backend platform · **Landing:** 2026-04-14 (output schemas) → **Wave 6** (NodeSpec contract) → **Wave 10** (plugin pattern + visual contract + icons, 2026-04-15)\n\n## Landed outcome (Wave 3 — output schemas)\n\n- Backend registry seeded with Pydantic models in [server/services/node_output_schemas.py](../server/services/node_output_schemas.py) — live size via `len(NODE_OUTPUT_SCHEMAS)` — covering every node type the deleted `sampleSchemas` map covered, plus all specialized agents and chat models.\n- `GET /api/schemas/nodes/{node_type}.json` serves static JSON Schema (Cache-Control `public, max-age=86400`). 404 for unknown types.\n- `get_node_output_schema` WebSocket handler for authenticated editor fetches.\n- [InputSection.tsx](../client/src/components/parameterPanel/InputSection.tsx) consumes schemas lazy via `queryClient.fetchQuery(['nodeOutputSchema', nodeType])`, in-memory cache only. **1,673 → 972 LOC** (−701). sampleSchemas map, 20 `isXxxNode` detection constants, and 60-line pattern-match chain all gone.\n- `outputSchema` field removed from `INodeTypeDescription` — the frontend type no longer has any shape-describing surface for runtime output.\n- Adding a new node type's output shape: one Pydantic model in `node_output_schemas.py`. Zero frontend change.\n\n## Wave 6 extension (input schemas + full NodeSpec)\n\nWave 3 proved the pattern for output schemas. Wave 6 generalises it to the **full parameter contract** — the business-logic surface the frontend still owned via `nodeDefinitions/*.ts` `properties` arrays, `displayOptions`, validation rules, dynamic-option loaders, and credential mappings.\n\n**Shipped contract:**\n\n- **Input schemas** — [server/services/node_input_schemas.py](../server/services/node_input_schemas.py) holds the `_DIRECT_MODELS` registry (aliased `NODE_INPUT_MODELS`) of Pydantic input models across every node type — live count via `len(_DIRECT_MODELS)`. Post-Wave-11 each plugin's `Params` class self-registers here at import (the earlier Wave 6 Literal-union introspection of `SpecializedAgentParams` / `AndroidServiceParams` is gone — specialized agents and Android service nodes are now individual plugin folders under `server/nodes/agent/` and `server/nodes/android/`).\n- **NodeSpec envelope** — [server/services/node_spec.py](../server/services/node_spec.py) assembles `{type, displayName, icon, group, description, version, inputs (JSON Schema), outputs (JSON Schema, reuses Wave 3), credentials, uiHints}` fusing three sources of truth.\n- **Display metadata** — [server/models/node_metadata.py](../server/models/node_metadata.py) defines the `NodeMetadata` / `NodeHandle` TypedDicts and the `NODE_METADATA` dict — live size via `len(NODE_METADATA)`. Post-Wave-11 it starts empty at import and is plugin-populated via `services.node_registry.register_node` (called from `BaseNode.__init_subclass__`), rather than being hand-maintained.\n- **Endpoints** — alongside the Wave 3 `/nodes/{type}.json` output endpoint: `GET /api/schemas/nodes/{type}/spec.json`, `/nodes/{type}/input.json`, `/nodes/specs` (list), all with 24h `Cache-Control`. WS mirrors: `get_node_spec`, `list_node_specs`. **Icon endpoints (RFC §6.5 + F7):** `GET /api/schemas/nodes/{type}/icon` serves the plugin's co-located `icon.svg` (or per-node-type `icon_<nodeType>.svg` for multi-node folders like whatsapp); `GET /api/schemas/credentials/{provider}/icon` serves the credential brand icon from `server/credentials/icons/<provider>.svg`. Both with long cache headers.\n- **loadOptionsMethod dispatch** — per-plugin `_option_loaders.py` files ([server/nodes/android/_option_loaders.py](../server/nodes/android/_option_loaders.py), [server/nodes/google/_option_loaders.py](../server/nodes/google/_option_loaders.py), [server/nodes/whatsapp/_option_loaders.py](../server/nodes/whatsapp/_option_loaders.py)) self-register into a shared loader registry, generalising the WhatsApp-only pattern. Adding a new dynamic-option loader = one registration inside the owning plugin folder. `POST /api/schemas/nodes/options/{method}` + WS `load_options`.\n- **Node-groups index** — `GET /api/schemas/nodes/groups` returns `{group: [node_type, ...]}` derived from every NodeSpec's `group` array — live count via `len(NODE_GROUPS)` — replacing the hand-rolled `*_NODE_TYPES` arrays scattered across 6 frontend files.\n- **Pydantic Field hints** — authors encode `displayOptions.show`/`.hide`, `loadOptionsMethod`, `placeholder`, `validation`, `typeOptions` via `Field(json_schema_extra={...})`. Currently ~36 rules encoded across TwitterSend/User, TelegramSend, HttpRequest, WhatsAppSend, SocialSend, Gmail, Calendar.\n\n**Frontend consumer (feature-flagged):**\n\n- `VITE_NODESPEC_BACKEND` flag at [client/src/lib/featureFlags.ts](../client/src/lib/featureFlags.ts). Defaults OFF — legacy `nodeDefinitions/*.ts` wins; ON routes rendering through backend NodeSpec via the adapter.\n- [client/src/lib/nodeSpec.ts](../client/src/lib/nodeSpec.ts) — shared `fetchNodeSpec`/`prefetchAllNodeSpecs`/`resolveNodeDescription` helpers following the Wave 3 colocation pattern (no new hook file).\n- [client/src/adapters/nodeSpecToDescription.ts](../client/src/adapters/nodeSpecToDescription.ts) — NodeSpec wire shape → legacy `INodeTypeDescription` bridge. Handles `required`, JSON Schema `format` (dateTime/file/binary), `displayOptions`, `validation`, typeOptions lift (`loadOptionsMethod`, `password`, `rows`, `editor`, `editorLanguage`, `accept`, …), and reads hints from both top-level and nested `uiHints` wrapper.\n- Dashboard idle-time prefetch (`prefetchAllNodeSpecs` in [client/src/lib/nodeSpec.ts](../client/src/lib/nodeSpec.ts)) warms every NodeSpec after WebSocket connect. (The `VITE_NODESPEC_BACKEND` flag is now the default-on path — backend NodeSpec is the SSOT; the legacy `nodeDefinitions/*.ts` files were deleted in the Wave 7/10 reductions.)\n\n**Adding a new node type's parameter surface** (Wave 6 recipe; superseded post-Wave-11 — see the plugin recipe in [10.C](#10c--register_node-decorator) and [Wave 11](#wave-11--plugin-first-class-hierarchy)):\n\nAt Wave 6 the surface was three separate data files:\n\n1. Define `XyzParams(BaseNodeParams)` with a `type: Literal[\"xyz\"]` discriminator and Field constraints, register it in the `KnownNodeParams` discriminated union, and register it in the `_DIRECT_MODELS` dict in `node_input_schemas.py`.\n2. Add `NODE_METADATA[\"xyz\"] = {displayName, icon, group, description, version}` in `node_metadata.py`.\n\nPost-Wave-11 all three collapse onto the plugin class: `Params` is declared on the `BaseNode` subclass in `server/nodes/<group>/<plugin>/__init__.py`, and `register_node` (via `__init_subclass__`) writes the class's `Params` into `_DIRECT_MODELS` (aliased as `NODE_INPUT_MODELS`) and its metadata into `NODE_METADATA` at import time. There is no `server/models/nodes.py` and no `KnownNodeParams` union any more — plugin `Params` extend `BaseModel` directly (no `type:` discriminator).\n\nZero frontend change for parameter rendering. Icons that are SVG assets still need frontend import until SVG payload migration is its own follow-up.\n\n**What's deferred (Wave 7):**\n\n- Phase 3e flag flip + frontend `nodeDefinitions/*.ts` reductions (~3000 LOC deletion). Adapter is ready; snapshot Playwright tests are the remaining prerequisite.\n- Phase 5.b per-component migration from `*_NODE_TYPES` arrays to backend groups.\n- Gmail/Calendar/Telegram/Twitter loadOptions loaders (Phase 4 registry is ready for one-line registrations).\n- ParameterRenderer → DIY widget registry (the capstone). Now unblocked on backend since NodeSpec's `uiHints` already carry widget routing.\n\n## Problem\n\nThe editor's Input panel (`client/src/components/parameterPanel/InputSection.tsx`) needs to show the runtime output shape of every connected source node so users can drag variables into downstream parameters. Today there are two places this shape is declared:\n\n1. A 350-line `sampleSchemas` map inline in `InputSection.tsx` (59 entries).\n2. As-of Wave 3 Phase 1 Batch 1 (commit `f1b2813`), a new `outputSchema` field on each `INodeTypeDescription` that the frontend consults before the legacy map.\n\nBoth are **frontend duplications of what the backend already owns** — the handler's return type (Pydantic models colocated with each node handler). Every node addition requires a frontend edit to keep schemas in sync.\n\n> **Historical note.** This RFC was written pre-Wave-11 when handler bodies lived under `server/services/handlers/*`. Post-Wave-11 those bodies inlined into per-plugin folders under `server/nodes/<group>/<plugin>/__init__.py`; only `todo.py` / `tools.py` / `triggers.py` remain under `server/services/handlers/`. Path references throughout the earlier sections have been updated to their current locations; the design decisions still hold.\n\n## How this scales to 1000+ nodes elsewhere\n\nRaw-GitHub-API research against three schema-driven platforms (n8n ~500 nodes, Activepieces ~400 pieces, Nango 100+ integrations):\n\n**n8n** — the canonical comparison point, React Flow / Vue inspector:\n- Node type descriptions come from the backend via `GET /node-types` on boot (`packages/frontend/editor-ui/src/app/stores/nodeTypes.store.ts`).\n- The Input panel (`VirtualSchema.vue`) pulls the output shape from two sources in order of preference:\n 1. Actual execution data — `getSchemaForExecutionData(props.data)`.\n 2. A JSON Schema preview fetched lazy per-node via `GET /schemas/{nodeType}/{version}/{resource?}/{operation?}.json` (`schemaPreview.api.ts`). These are **static JSON files served alongside the backend**, `withCredentials: false`, keyed `${nodeType}_${version}_${resource}_${operation}` in a `Map<string, Result<JSONSchema7, Error>>` in-memory cache.\n 3. Empty state when neither is available.\n\n**Activepieces** (`packages/pieces/framework/src/lib/*`):\n- Piece-authors declare Actions in TypeScript inside the piece's backend package. **Actions have no `outputSchema` field at all.** Triggers carry `sampleData: unknown` — a free-form example value the UI renders in the variable picker before first run.\n- The backend emits two payloads to the editor: `PieceMetadataSummary` (icon + counts + suggested) for catalog browsing, and the full `PieceMetadata` (actions + triggers records) on select.\n\n**Nango** (`packages/types/lib/nangoYaml/index.ts`):\n- YAML config declares `input: ModelName` / `output: ModelName[]` per sync or action. Model definitions in the same YAML are codegen'd into TypeScript types shipped to both backend and frontend.\n\n**Finding:** zero of these platforms keep node-shape declarations on the frontend. n8n explicitly serves per-node JSON Schema files from the backend; Activepieces skips declared schemas entirely in favor of real run data.\n\n## Decision\n\nAdopt n8n's layered pattern.\n\n**Schema source of truth:** backend only. Pydantic models colocated with node handlers.\n\n**Frontend rendering order** (three-tier, mirrors `VirtualSchema.vue`):\n1. Real execution data from the most recent run (already wired at [`InputSection.tsx:164-174`](../client/src/components/parameterPanel/InputSection.tsx)).\n2. `GET /api/schemas/nodes/{nodeType}.json` — JSON Schema served lazy from the backend, cached in-memory per node type.\n3. Empty state / `{ data: 'any' }` fallback.\n\n**What the frontend keeps:**\n- `INodeTypeDescription` stays a **UI-only** description: `displayName`, `icon`, `group`, `inputs`, `outputs`, `properties`, `defaults`, `uiHints`, `credentials`. No data schemas.\n- `uiHints` (Wave 2 Phase 1) is genuinely UI-owned (panel visibility, editor variants, selector dispatch) and stays.\n\n**What leaves the frontend:**\n- `outputSchema` field on `INodeTypeDescription` (added by commit `f1b2813`) — deleted.\n- `sampleSchemas` map in `InputSection.tsx` — deleted once the backend endpoint has coverage for the node types currently listed there.\n\n## Backend contract\n\n```\nGET /api/schemas/nodes/{node_type}.json\n 200 → application/json: JSON Schema 7 describing the node's output shape\n 404 → node has no declared schema (frontend falls back to run data / empty)\n headers: Cache-Control: public, max-age=86400 (or similar)\n```\n\nWebSocket parallel:\n```\nrequest: { type: \"get_node_output_schema\", node_type: \"whatsappReceive\" }\nresponse: { schema: JSONSchema7 | null }\n```\n\nSchema generation: each handler's existing Pydantic response model (or a new minimal `NodeOutputSchema` Pydantic model colocated with the handler) emits JSON Schema via `.model_json_schema()`. Registry at `server/services/node_output_schemas.py`: `NODE_OUTPUT_SCHEMAS: dict[str, type[BaseModel]]` mapping node type → model class. Missing entries return 404.\n\n## Frontend changes\n\n1. New `useNodeOutputSchemaQuery(nodeType)` inline at top of `InputSection.tsx` (one consumer — inline per the Wave 2/3 colocation rule):\n ```ts\n function useNodeOutputSchemaQuery(nodeType: string | null) {\n return useQuery<Record<string, any> | null>({\n queryKey: ['nodeOutputSchema', nodeType],\n queryFn: () => nodeType\n ? sendRequest('get_node_output_schema', { node_type: nodeType })\n .then(r => r?.schema ?? null)\n : Promise.resolve(null),\n staleTime: Infinity,\n enabled: !!nodeType,\n });\n }\n ```\n\n2. `InputSection` dispatch becomes three-tier:\n ```ts\n if (executionData?.length) outputSchema = executionData[0][0].json;\n else if (backendSchema) outputSchema = backendSchema;\n else outputSchema = { data: 'any' };\n ```\n Delete the `sampleSchemas` map + pattern-match else-if chain + all `isXxx` constant flags.\n\n3. Revert commit `f1b2813` (frontend `outputSchema` annotations). Remove the `outputSchema` field from `INodeTypeDescription`.\n\n## Migration order\n\n1. Write this RFC. (this file)\n2. Frontend: add the `useNodeOutputSchemaQuery` hook + three-tier dispatch. **Keep** the legacy `sampleSchemas` map as a temporary final fallback below the backend call so nothing breaks before the backend endpoint exists. The `nodeDef.outputSchema` branch goes away in this commit (revert + remove the type field).\n3. Backend: implement `/api/schemas/nodes/{node_type}.json` + `get_node_output_schema` WS handler. Seed the registry from existing Pydantic response models (start with the high-traffic nodes: `chatTrigger`, `webhookTrigger`, `whatsappReceive`, `aiAgent`/`chatAgent` family, `httpRequest`, code executors, Google Workspace).\n4. Frontend: once the backend has coverage for every type in the legacy `sampleSchemas` map, **delete the map**. Verify via manual smoke of the 20 node categories.\n\n## What this unblocks\n\nPhase 6 (`ParameterRenderer` → DIY widget registry) was blocked on the backend emitting `NodeSpec { jsonSchema, uiSchema, _uiHints? }`. The endpoint defined here is the `jsonSchema` slice of that same `NodeSpec` — Phase 6 extends it with `uiSchema` + `_uiHints`. Phase 1-REVISED is therefore the on-ramp to Phase 6, not a detour.\n\n## Non-goals\n\n- Build-time codegen of TypeScript types from the backend schemas (Nango's pattern) — deferred. The frontend reads schemas as plain JSON; typed inference on top would be nice-to-have but isn't load-bearing.\n- Versioning of schemas per node-type version — deferred. All current node types are v1; add `{version}` to the URL path the first time we bump.\n\n## Wave 10 — plugin pattern + visual contract\n\nWave 6 made the backend authoritative for node schemas. Wave 10 closed the\nremaining tribal-code paths so **adding a new node = one Python file, zero\nfrontend edits**.\n\n### 10.A — Visual contract extended\n\n`NodeMetadata` TypedDict in [server/models/node_metadata.py](../server/models/node_metadata.py)\ngains the fields the frontend previously hardcoded:\n\n- `color` (hex / dracula token)\n- `componentKind` (`square` / `circle` / `trigger` / `start` / `agent` / `chat` / `tool` / `model` / `generic`)\n- `handles: NodeHandle[]` — full React Flow topology (replaces the 400-line\n `AGENT_CONFIGS` map in `AIAgentNode.tsx`)\n- `credentials`, `hideOutputHandle`, `visibility`\n\nEach field flows through `get_node_spec()` into the `/api/schemas/nodes/{type}/spec.json`\nenvelope, so every consumer (React Flow dispatch, parameter panel, palette)\nreads from one source.\n\n### 10.C — `register_node` registry writer\n\n[server/services/node_registry.register_node(...)](../server/services/node_registry.py)\nwrites to four registries in one call: `NODE_METADATA`, `_DIRECT_MODELS`,\n`NODE_OUTPUT_SCHEMAS`, `_HANDLER_REGISTRY` (and invalidates the per-type\nNodeSpec + input-schema caches). `server/nodes/__init__.py` recursively\nimports every submodule at import time via `pkgutil.walk_packages`, so\nplugin registration is a side effect at startup. Post-Wave-11 the caller is\n`BaseNode.__init_subclass__` (via `register_node_class`), so every plugin\nfolder self-registers — live migrated count via\n`glob server/nodes/**/__init__.py`.\n\n**New node checklist (post-Wave-10):**\n\n```python\n# server/nodes/<group>/<plugin>/__init__.py\nfrom typing import Literal\nfrom pydantic import Field\nfrom services.plugin import ActionNode, NodeContext, Operation\n\nclass MyNodeParams(ActionNode.Params):\n query: str = Field(default=\"\", json_schema_extra={\"placeholder\": \"Search...\"})\n\nclass MyNodeOutput(ActionNode.Output):\n result: dict = {}\n\nclass MyNode(ActionNode):\n type = \"myNode\"\n display_name = \"My Node\"\n group = (\"tool\",)\n component_kind = \"square\"\n Params = MyNodeParams\n Output = MyNodeOutput\n\n @Operation(\"run\")\n async def run(self, ctx: NodeContext, params: MyNodeParams) -> MyNodeOutput:\n return MyNodeOutput(success=True, result={...})\n```\n\nDrop `icon.svg` and `meta.json` (`{\"color\": \"#xxx\"}`) into the plugin folder. Zero edits elsewhere.\n\n### 10.B — Icon + color: per-plugin folder + visuals.json fallback\n\nIcons live as `icon.svg` (or `icon_<nodeType>.svg` for multi-node folders like whatsapp) in the plugin folder; colors live in `meta.json`. `visuals.json` is the fallback registry for emoji / `lobehub:<brand>` icons + the skill reverse-map. Full resolution chain + wire format + frontend rendering all documented in [server/nodes/README.md → Icon + color](../server/nodes/README.md). Credential brand icons via `Credential.get_icon_path()` resolve to `server/credentials/icons/<provider>.svg` or co-located `credential_<id>.svg`; served by `GET /api/schemas/credentials/{provider}/icon`.\n\n### 10.G — Parameter panel fully spec-driven\n\n- `ParameterRenderer.tsx` gains `case 'code'` + `case 'dateTime'` + generic\n `loadOptionsMethod` dispatch via the backend `load_options` WS handler\n (unlocking the 4 Google Workspace dynamic-option loaders that were\n previously unreachable). `displayOptions.show` now propagates into nested\n `fixedCollection` renders. Password masking wins over multi-row textarea.\n- `MiddleSection` / `InputSection` / `SquareNode` / `ParameterPanel` retire\n the last 14 hardcoded type-array fallbacks (`TRIGGER_NODE_TYPES`,\n `AGENT_WITH_SKILLS_TYPES`, `SKILL_NODE_TYPES`, etc.). Every widget\n decision reads a uiHint or handle-topology fact declared by the node's\n own plugin module.\n- `nodeDefinitions/*.ts` files strip every `icon:` field (−272 LOC) — \n backend is sole declaration site. `INodeTypeDescription.icon` narrowed\n to `icon?: string`.\n\n### Contract invariants (`tests/test_node_spec.py` — live count via `pytest --collect-only`)\n\n`TestWave10GContractInvariants` enforces:\n\n- every agent-kind node has `uiHints.hasSkills`\n- every tool-kind node has `uiHints.isToolPanel`\n- every Google Workspace node has a field gated by\n `displayOptions.show.operation`\n- every code executor emits `editor: \"code\"` on its `code` field\n- every `api_key` / `apiKey` field emits `password: True`\n- every `asset:<key>` icon resolves to a real SVG under\n `client/src/assets/icons/`\n- every palette group carries non-empty label + icon\n\n## Wave 11 — plugin-first class hierarchy\n\nWave 10 shipped the `@register_node` decorator and per-file plugin\nlayout but kept handlers as standalone async functions. Wave 11\npromotes nodes to a class-based plugin model, extracts runtime\ninfrastructure into `services/plugin/`, and unifies the node-creation\nAPI around a single `BaseNode` hierarchy. See\n**[plugin_system.md](./plugin_system.md)** for the canonical reference.\n\n### What changed\n\n- **`BaseNode` class hierarchy.** Three concrete kinds —\n `ActionNode` / `TriggerNode` / `ToolNode`. Each subclass declares\n everything on its class object: `type`, metadata, `Params` +\n `Output` Pydantic models, `credentials`, `handles`, `task_queue`,\n `retry_policy`, operations. `__init_subclass__` writes to the four\n legacy registries on import, so existing consumers are unchanged.\n- **`@Operation` decorator** for multi-op dispatch.\n- **Declarative `Routing` DSL** + **`Connection` facade (Nango\n pattern).** Plugins never see tokens; routing owns templating + HTTP.\n- **Credential classes** (`ApiKeyCredential`, `OAuth2Credential`)\n with declarative `inject()` methods. Auto-registry via\n `__init_subclass__`.\n- **Per-plugin Temporal activities** (Wave 11.F). Every subclass\n exposes `cls.as_activity()` with name `node.{type}.v{version}`.\n `TemporalWorkerPool` spawns one worker per declared `task_queue`\n with tuned concurrency (ai-heavy=4, rest-api=50, triggers-poll=100).\n- **Folder layout mirrors palette groups.** `server/nodes/<group>/<name>.py`.\n- **Auto-populate trigger registries** (Wave 11.D.11). Plugins\n declaring `event_type` + `build_filter` auto-register into\n `event_waiter.TRIGGER_REGISTRY` + `FILTER_BUILDERS`.\n- **Shared helpers under `services/plugin/`**: `edge_walker.py`\n (agent connection discovery), `base.py` (BaseNode lifecycle),\n `context.py` (typed NodeContext), `scaling.py` (TaskQueue +\n RetryPolicy), `operation.py` (@Operation decorator + collector),\n `routing.py` (declarative REST DSL), `connection.py` (authed\n httpx wrapper), `credential.py`, `interceptor.py`.\n\n### Contract invariants\n\nAdds a further set of invariants on top of the Wave 10 suite (live total via `pytest --collect-only` on `tests/test_node_spec.py`):\n\n- Every `BaseNode` subclass has `type`, `display_name`, `group`.\n- `Params` + `Output` are Pydantic `BaseModel` subclasses.\n- Every declared credential resolves to `CREDENTIAL_REGISTRY`.\n- `@Operation` names unique per class; `routing=…` requires credentials.\n- `task_queue` ∈ `TaskQueue.ALL`; `retry_policy` is `RetryPolicy`.\n- Every `ToolNode` JSON schema has no `$defs` / `$ref`.\n- Every event-mode `TriggerNode` declares `event_type`.\n- Fast-path covers every AI-tool-usable plugin.\n- Trigger registry auto-populates for every event-mode plugin.\n\n### Status\n\nPlugins (live count via `glob server/nodes/**/__init__.py`) live across 9 Temporal task queues (`rest-api`,\n`ai-heavy`, `code-exec`, `triggers-poll`, `triggers-event`, `android`,\n`browser`, `messaging`, `machina-default`). Handler bodies are fully\ninlined into plugin files — `services/handlers/` shrank from\n**12.8K LOC / 16 files → a few files** (live set: `todo.py` / `tools.py` /\n`triggers.py` + `__init__.py`). Only cross-cutting orchestration remains\nthere: `tools.py` (AI-tool dispatch + agent delegation through\n`BaseNode.execute()` via the node registry — the live delegation handler is\n`_execute_delegated_agent`), `triggers.py` (generic event-trigger handler),\nand `todo.py`. The shared Google credential helper moved out of handlers\ninto its owning plugin folder at\n[server/nodes/google/_auth_helper.py](../server/nodes/google/_auth_helper.py).\nAgent connection collection lives at\n[server/services/plugin/edge_walker.py::collect_agent_connections](../server/services/plugin/edge_walker.py)\n(a 5-tuple: memory, skill, tool, input, task), and per-plugin pre-dispatch\nprep is [server/nodes/agent/_inline.py::prepare_agent_call](../server/nodes/agent/_inline.py).\nSunset of the empty `nodes/{agents,services,triggers,tools,utilities}.py`\nbulk files + dead dispatcher fallbacks is complete (Wave 11.D.13).\n\n### Sub-waves shipped\n\n- **11.A / B / B.1** — `BaseNode` hierarchy, `ActionNode` /\n `TriggerNode` / `ToolNode`, `__init_subclass__` registry writes.\n- **11.C** — `@Operation` decorator + multi-op dispatch.\n- **11.D.0–13** — handler inlining, bulk-file sunset, trigger\n registry auto-population, dispatcher cleanup.\n- **11.E** — declarative `Credential` subclasses\n (`ApiKeyCredential`, `OAuth2Credential`) with `inject()` methods\n and auto-registry via `Credential.__init_subclass__`.\n- **11.E.1** — credentials modularised into per-domain\n `server/nodes/<group>/_credentials.py` files (or inline for\n single-use). **Central `server/credentials/` directory deleted.**\n 18 `Credential` subclasses at the time (25 concrete subclasses today).\n- **11.E.2 / E.3 / E.4** — credential polish + doc sync.\n- **11.F** — per-plugin Temporal activities\n (`cls.as_activity()` named `node.{type}.v{version}`),\n `TemporalWorkerPool` per task queue with tuned concurrency\n (ai-heavy=4, rest-api=50, triggers-poll=100, etc.).\n- **11.G** — nodes cookbook (`server/nodes/README.md`) + CLAUDE.md\n sync.\n\n## References\n\n- [n8n `schemaPreview.api.ts`](https://github.com/n8n-io/n8n/blob/master/packages/frontend/editor-ui/src/features/ndv/runData/schemaPreview.api.ts)\n- [n8n `VirtualSchema.vue`](https://github.com/n8n-io/n8n/blob/master/packages/frontend/editor-ui/src/features/ndv/runData/components/VirtualSchema.vue)\n- [n8n `nodeTypes.store.ts`](https://github.com/n8n-io/n8n/blob/master/packages/frontend/editor-ui/src/app/stores/nodeTypes.store.ts)\n- [n8n node-icon conventions](https://docs.n8n.io/integrations/creating-nodes/build/reference/node-base-files/icons/) — `file:` + `fa:` prefix-dispatch which Wave 10.B generalises\n- [Activepieces `piece-metadata.ts`](https://github.com/activepieces/activepieces/blob/main/packages/pieces/framework/src/lib/piece-metadata.ts)\n- [Activepieces `action.ts`](https://github.com/activepieces/activepieces/blob/main/packages/pieces/framework/src/lib/action/action.ts)\n- [Nango `nangoYaml/index.ts`](https://github.com/NangoHQ/nango/blob/master/packages/types/lib/nangoYaml/index.ts)\n- [@lobehub/icons](https://github.com/lobehub/lobe-icons) — the default `<lib>:<brand>` target for AI provider brand logos\n","archived":true,"sha256":"96a51c1462308e6033576fc1c5108463d168df4de49621dbae6ce1b70e09c865"},"doc:docs-internal/ARCHIVE/server-readme.md":{"id":"doc:docs-internal/ARCHIVE/server-readme.md","path":"docs-internal/ARCHIVE/server-readme.md","title":"Python Backend - Environment Setup","content":"# Python Backend - Environment Setup\n\n> **ARCHIVED 2026-09-04 — Superseded.** Most of this file described modules that never existed in this tree (`handlers/gmail.py`, `WHATSAPP_SERVICE_URL`, `.env.example`, an auth-gated encryption init). Kept only as a record; do not follow it.\n>\n> For current state see:\n>\n> - [SETUP.md](../SETUP.md) — environment and first run\n> - [authentication.md](../authentication.md) and [credentials_encryption.md](../credentials_encryption.md)\n> - [plugin_system.md](../plugin_system.md) — backend architecture\n> - [CLAUDE.md](../../CLAUDE.md) — the live index\n\n## Quick Start\n\n1. Copy the template to create your .env file:\n```bash\ncp .env.template .env\n```\n\n(If you run `company build` instead, its step [0/6] scaffolds `.env` from `.env.template` automatically and generates fresh random secrets — `secrets.token_hex(24)` — for `SECRET_KEY`, `JWT_SECRET_KEY`, and `API_KEY_ENCRYPTION_KEY` instead of copying the dev placeholders. An existing `.env` is never touched.)\n\n2. Edit `.env` and add your API keys:\n```bash\n# Required for remote Android devices\nWEBSOCKET_API_KEY=your-actual-key-here\n\n# Optional: Default API keys (users can also add these through the UI)\nGOOGLE_MAPS_API_KEY=your-google-maps-key\nOPENAI_API_KEY=your-openai-key\n```\n\n3. Start the server:\n```bash\npython main.py\n```\n\n## Environment Variables\n\n### Required\n\n- `SECRET_KEY` - Server encryption key (32+ characters)\n- `API_KEY_ENCRYPTION_KEY` - API key encryption (32+ characters)\n\n### Optional but Recommended\n\n- `WEBSOCKET_API_KEY` - Required for remote Android device connections\n- `GOOGLE_MAPS_API_KEY` - Default Google Maps API key\n- `OPENAI_API_KEY` - Default OpenAI API key\n- `ANTHROPIC_API_KEY` - Default Anthropic API key\n- `GOOGLE_AI_API_KEY` - Default Google AI API key\n\n### Service URLs\n\n- `WEBSOCKET_URL` - WebSocket server URL (default: ws://www.disutopia.xyz/ws)\n- `WHATSAPP_SERVICE_URL` - WhatsApp service URL (default: http://localhost:3012)\n\n### Development vs Production\n\nThe `.env.template` file contains development-safe defaults.\n\nFor production:\n1. Change `DEBUG=false`\n2. Generate new secure `SECRET_KEY` and `API_KEY_ENCRYPTION_KEY` (a `company build`-scaffolded `.env` already has fresh random values; a hand-copied template does not)\n3. Set `RATE_LIMIT_ENABLED=true`\n4. Configure proper CORS origins\n5. Consider enabling Redis caching\n\nThe server also guards against placeholder secrets at startup: `server/core/config.py` exposes `DEV_SECRET_LITERALS` + `dev_secret_offenders()`, and the lifespan logs a non-fatal error banner if dev placeholder secrets are detected while auth is enabled or `DEPLOYMENT_MODE` is not `local`.\n\n## Authentication & Encryption\n\n### Authentication Toggle\n\nSet `VITE_AUTH_ENABLED=false` in `.env` to bypass the login page entirely.\n\nWhen auth is disabled:\n- Login page is skipped\n- User is set as anonymous with owner privileges\n- Encryption service auto-initializes using `API_KEY_ENCRYPTION_KEY` as the password\n- API keys can be saved/retrieved without user login\n\n### Encryption Auto-Initialization\n\nThe encryption service requires initialization before encrypting/decrypting API keys. This normally happens during user login via `_initialize_encryption()`.\n\nWhen `VITE_AUTH_ENABLED=false`, the encryption is auto-initialized at startup in `main.py`:\n\n```python\n# In main.py lifespan()\nif settings.vite_auth_enabled == \"false\":\n encryption = container.encryption_service()\n if not encryption.is_initialized():\n encryption.initialize(settings.api_key_encryption_key, salt)\n```\n\nThis allows API keys to be stored without authentication, useful for local development.\n\n## Security Notes\n\n**NEVER commit `.env` files to git!**\n\nThe `.env.template` file is safe to commit because it contains no real credentials.\n\nAll API keys should be:\n- Stored in `.env` files (ignored by git)\n- Or set as environment variables\n- Or managed through the UI (stored encrypted in database)\n\n## Files\n\n- `.env` - Your local configuration (git-ignored, created from template)\n- `.env.template` - Template with safe defaults (committed to git)\n- `.env.example` - Full example with all options (committed to git)\n- `.env.development` - Development environment (git-ignored)\n- `.env.production` - Production environment (git-ignored)\n\n## Google Workspace Integration\n\nGoogle Workspace services (Gmail, Calendar, Drive, Sheets, Tasks, Contacts) share a single OAuth connection.\n\n### Setup\n\n1. Create a Google Cloud project and enable the required APIs\n2. Create OAuth 2.0 credentials (Web Application type)\n3. Add credentials via the Credentials Modal in the UI\n4. Click \"Login with Google\" to authenticate\n\n### Environment Variables (Optional)\n\n```bash\n# Custom OAuth redirect URI (defaults to localhost:5678)\nGOOGLE_REDIRECT_URI=http://localhost:5678/api/google/callback\n```\n\n### Token Storage\n\nAll Google tokens use the `google_*` prefix:\n- `google_client_id` - OAuth Client ID\n- `google_client_secret` - OAuth Client Secret\n- `google_access_token` - Access token for API calls\n- `google_refresh_token` - Refresh token for renewal\n- `google_user_info` - Connected user email and name\n\n### API Handlers\n\n| Service | Handler File | Node Types |\n|---------|-------------|------------|\n| Gmail | `handlers/gmail.py` | gmailSend, gmailSearch, gmailRead, gmailReceive |\n| Calendar | `handlers/calendar.py` | calendarCreate, calendarList, calendarUpdate, calendarDelete |\n| Drive | `handlers/drive.py` | driveUpload, driveDownload, driveList, driveShare |\n| Sheets | `handlers/sheets.py` | sheetsRead, sheetsWrite, sheetsAppend |\n| Tasks | `handlers/tasks.py` | tasksCreate, tasksList, tasksComplete |\n| Contacts | `handlers/contacts.py` | contactsCreate, contactsList, contactsSearch |\n\n### AI Agent Skills\n\nSkills for AI agents are in `server/skills/productivity_agent/`:\n- gmail-skill, calendar-skill, drive-skill, sheets-skill, tasks-skill, contacts-skill\n","archived":true,"sha256":"521b37a9ca45d15ec9beb07335965d9a416fa5c99ad88b3bab70aa8b6d8dd41b"},"doc:docs-internal/ARCHIVE/temporal-execution-engine-rfc.md":{"id":"doc:docs-internal/ARCHIVE/temporal-execution-engine-rfc.md","path":"docs-internal/ARCHIVE/temporal-execution-engine-rfc.md","title":"RFC: Temporal Execution Engine Architecture","content":"# RFC: Temporal Execution Engine Architecture\n\n> **ARCHIVED 2026-09-04 — Superseded.** Design rationale for the Temporal engine. Items this RFC lists as pending have shipped: boot reconciliation (§14, §19.1 — `reconcile_active_controls_on_boot`), controller continue-as-new (§18, §19.2 — `WorkflowControlWorkflow`), indexed event routing (§19.4 — the `ControlEventTypes` Search Attribute), and most of the §19.5 test list (`test_worker_restart.py`, `test_cooperative_pause.py`, `test_terminate_sweep.py`, `test_agent_workflow_replay.py`). Agent activity names carry no `.v1` suffix.\n>\n> For current state see:\n>\n> - [temporal-workflow-control.md](../temporal-workflow-control.md) — control plane as shipped\n> - [TEMPORAL_ARCHITECTURE.md](../TEMPORAL_ARCHITECTURE.md) — dispatch paths and activities\n\n| Field | Value |\n|---|---|\n| Status | Implemented; canonical current-state design |\n| Date | 2026-07-20 |\n| Owners | Workflow Platform, Agent Platform, Editor |\n| Scope | Durable workflow control, trigger admission, graph execution, AI agents, team delegation, observability |\n| Supersedes | The current-state portions of `TEMPORAL_ARCHITECTURE.md`; legacy execution remains documented there |\n\n## 1. Executive summary\n\nOpenCompany uses Temporal as its durable production execution engine. A saved\ncanvas workflow is a stable application identity. Each deployment has a\nrevision-guarded **control generation**, represented by a long-lived\n`WorkflowControlWorkflow`. Each actual graph invocation is a\n`MachinaWorkflow`. AI-agent nodes normally execute as `AgentWorkflow` child\nworkflows, and asynchronous teammate assignments execute through\n`DelegatedTaskWorkflow` runners.\n\nThe application database and Temporal have deliberately different authority:\n\n- The application database owns workflow authorization, graph snapshots,\n control generations, teams, tasks, immutable attempts, and UI indexes.\n- Temporal owns durable command/event history, timers, retries, workflow and\n activity state, and actual execution identity.\n- WebSocket broadcasts are a realtime projection. They are not authoritative.\n- Process-local registries are caches and legacy compatibility surfaces. They\n must never be the only durable record of controlled execution.\n\nControlled push and polling triggers live inside the control workflow rather\nthan separate listener workflows. Only a real graph invocation appears as a\nchild workflow. Temporal cron schedules remain server-side Schedule resources;\ntheir firings execute the plugin-owned `CronTriggerWorkflow` compatibility\npath.\n\n## 2. Goals and non-goals\n\n### 2.1 Goals\n\n1. Survive API-server and worker restarts without losing durable execution.\n2. Execute independent graph branches and agent tool calls concurrently.\n3. Isolate node, agent, teammate, memory, and tool capabilities.\n4. Make Start, Pause, Resume, and Reset explicit, revision-safe operations.\n5. Persist delegation before child startup and cap all descendants per root.\n6. Preserve immutable task-attempt history and link it to actual Temporal runs.\n7. Expose sanitized, bounded, searchable traces without exposing payloads or\n trusting caller-supplied Temporal IDs.\n8. Keep plugin-owned activity schemas, retry behavior, and task queues\n extensible.\n\n### 2.2 Non-goals\n\n- Native Temporal Workflow Pause. The engine uses an acknowledged controller\n Update, cooperative descendant Signals, and deterministic wait conditions.\n- Temporal's history-rewind Reset. Product Reset terminates and archives the\n current application generation.\n- Shared parent/child LLM transcripts. Delegated agents start with isolated\n conversations and return compact results.\n- Raw Temporal payload or prompt access through Task Manager.\n- Exactly-once side effects outside Temporal. Activities must be idempotent or\n protected by database idempotency records.\n\n## 3. System context\n\n```mermaid\nflowchart LR\n User[Workflow author / operator]\n Editor[OpenCompany Editor<br/>Canvas, toolbar, Task Manager, Team Monitor]\n API[OpenCompany API<br/>Validation, authorization, control and projections]\n DB[(Application DB<br/>Graphs, generations, teams, tasks, attempts)]\n Temporal[Temporal Cluster<br/>Histories, timers, retries, schedules]\n Workers[Temporal Workers<br/>Framework and plugin workers]\n LLM[LLM providers]\n Services[Connected services<br/>Browser, Android, HTTP, SaaS, code]\n OTel[OpenTelemetry backend]\n\n User --> Editor\n Editor <-->|Authenticated WebSocket| API\n API <-->|Authoritative application state| DB\n API <-->|Start, Signal, Query, history| Temporal\n Temporal <-->|Workflow/activity tasks| Workers\n Workers <-->|Idempotent lifecycle writes| DB\n Workers --> LLM\n Workers --> Services\n API --> OTel\n Workers --> OTel\n```\n\n## 4. Logical architecture\n\n```mermaid\nflowchart TB\n subgraph UI[Editor]\n Toolbar[Start / Pause / Resume / Reset]\n Canvas[Canvas and node status]\n TM[Task Manager and trace search]\n Monitor[Team Monitor]\n end\n\n subgraph API[Application control plane]\n WS[WebSocket handlers]\n WCS[WorkflowControlService]\n Deploy[DeploymentManager compatibility facade]\n Team[AgentTeamService]\n Trace[TeamTaskTraceService]\n Events[CloudEvent dispatch]\n end\n\n subgraph DB[Application database]\n Controls[(workflow_control_executions)]\n Teams[(agent_teams)]\n Tasks[(team_tasks)]\n Attempts[(team_task_attempts)]\n Messages[(agent_messages)]\n Permits[(subagent_concurrency_permits)]\n end\n\n subgraph Temporal[Temporal namespace]\n Controller[WorkflowControlWorkflow]\n Root[MachinaWorkflow]\n Agent[AgentWorkflow]\n Runner[DelegatedTaskWorkflow]\n Cron[Temporal Schedule / CronTriggerWorkflow]\n Activities[Framework and plugin activities]\n end\n\n Toolbar --> WS --> WCS --> Controls\n WCS --> Controller\n Deploy --> Controller\n Events --> Controller\n Controller --> Root\n Cron --> Root\n Root --> Agent\n Agent --> Runner\n Runner --> Agent\n Root --> Activities\n Agent --> Activities\n Runner --> Activities\n Team --> Teams\n Team --> Tasks\n Team --> Attempts\n Team --> Messages\n Team --> Permits\n Trace --> Tasks\n Trace --> Attempts\n Trace --> Temporal\n TM --> WS\n Monitor --> WS\n WS --> Canvas\n```\n\n## 5. Identity model\n\n| Identity | Lifetime | Authority | Purpose |\n|---|---|---|---|\n| `workflow_id` | Saved workflow lifetime | Application DB | Stable product identity and authorization scope |\n| `generation` | One Start-to-Reset interval | Application DB | Separates clean deployment epochs |\n| `execution_id` / `root_execution_id` | Application execution tree | Application DB | Teams, tasks, permits, and descendant correlation |\n| Temporal Workflow ID | Temporal execution chain | Temporal | Stable address for Signal/Query/command routing |\n| Temporal Run ID | One run in a workflow chain | Temporal | Exact history version and attempt link |\n| `team_id` | Lead node in one execution | Application DB | Team membership and task authorization |\n| `task_id` | Durable assignment | Application DB | Stable task identity across retries |\n| `attempt_number` | One claim/run | Application DB | Immutable assignee, result, and Temporal links |\n| `trace_id` | Cross-component correlation | Application DB / OTel | Opaque correlation only; never authorization |\n\nIdentity rules:\n\n- New workflow IDs are backend-allocated positive integers (`1`, `2`, ...).\n Existing legacy records remain exactly as stored; the server does not run an\n identity migration or rewrite historical Temporal links.\n- Application execution IDs are workflow-scoped sequences\n (`<workflow_id>:execution:<sequence>`). They are not Temporal Run IDs.\n- Node instance IDs are `<workflow_id>:<plugin_type>:<ordinal>`. The plugin\n type is the fixed metadata identity; the ordinal distinguishes multiple\n instances, including multiple `aiAgent` nodes.\n- Browser and model callers never choose a Temporal workflow/run ID for trace\n access. The server resolves it from an authorized task attempt.\n- Workflow IDs and Run IDs are distinct. Resume signals the existing workflow;\n it does not manufacture a replacement Run ID.\n- A Reset archives the current generation and returns control state `ready`.\n The next Start creates generation `N + 1`.\n- Random IDs remain appropriate only for correlation, idempotency, events,\n leases, and provider-owned identities. They are not application workflow,\n execution, or node identities.\n\n## 6. Deployment control plane\n\n### 6.1 Persisted control record\n\n`WorkflowControlExecution` stores the workflow, generation, execution/root\nidentities, controller workflow/run IDs, graph snapshot and hash, session,\nstatus, revision, idempotency key, timestamps, and terminal reason. Unique\nconstraints protect `(workflow_id, generation)` and\n`(workflow_id, idempotency_key)`.\n\n### 6.2 State machine\n\n```mermaid\nstateDiagram-v2\n [*] --> never_started\n never_started --> starting: Start\n ready --> starting: Start next generation\n starting --> running: controller + deployment established\n starting --> failed: validation/start/deployment failure\n running --> pausing: Pause(expected revision)\n pausing --> paused: controller, triggers, schedules gated\n paused --> resuming: Resume(expected revision)\n resuming --> running: gates released\n running --> resetting: Reset\n paused --> resetting: Reset\n failed --> resetting: Reset\n resetting --> ready: tree terminated and generation archived\n```\n\nPublic state `ready` is persisted internally as terminal status `reset`. This\ndistinguishes a workflow that has never run from one with archived generations,\nwhile presenting Start in both cases.\n\n### 6.3 Control command sequence\n\n```mermaid\nsequenceDiagram\n autonumber\n actor User\n participant UI as Editor\n participant API as Control handler\n participant DB as Application DB\n participant T as Temporal\n participant C as WorkflowControlWorkflow\n participant DM as DeploymentManager\n\n User->>UI: Start\n UI->>API: start_workflow(graph, revision, idempotency_key)\n API->>DB: create generation + snapshot\n API->>T: start controller\n T->>C: run(generation)\n API->>DM: deploy snapshot\n DM->>C: register_trigger(spec) signals\n API->>DB: starting -> running (CAS)\n API-->>UI: running + new revision\n\n User->>UI: Pause\n UI->>API: pause_workflow(expected_revision)\n API->>DB: running -> pausing (CAS)\n API-->>UI: workflow_control_status(pausing)\n API->>DM: close local admission\n API->>C: set_control_state(paused) Update\n C-->>API: acknowledged paused state\n API->>T: strictly pause cron schedules\n API->>T: strictly signal running descendants\n T-->>API: schedule + descendant fan-out complete\n API->>DM: disarm trigger UI\n API->>DB: pausing -> paused\n API-->>UI: workflow_control_status(paused)\n\n User->>UI: Resume\n UI->>API: resume_workflow(expected_revision)\n API->>DB: paused -> resuming (CAS)\n API-->>UI: workflow_control_status(resuming)\n API->>C: set_control_state(running) Update\n C-->>API: acknowledged running state\n API->>T: strictly unpause cron schedules\n API->>T: strictly signal running descendants\n T-->>API: schedule + descendant fan-out complete\n API->>DM: drain buffered legacy events FIFO + rearm UI\n API->>DB: resuming -> running\n API-->>UI: workflow_control_status(running)\n```\n\n### 6.4 Cooperative pause semantics\n\nPause is an admission barrier, not suspension of operating-system threads:\n\n- Push events are accepted as durable controller Signals and remain queued.\n- The controller does not create new graph child workflows while paused.\n- Poll cycles do not start new graph runs; a poll activity already in flight may\n finish and its events wait for Resume.\n- Temporal cron schedules are explicitly paused.\n- `WorkflowControlWorkflow`, `TriggerListenerWorkflow`,\n `PollingTriggerWorkflow`, `CronTriggerWorkflow`, `MachinaWorkflow`,\n `AgentWorkflow`, and `DelegatedTaskWorkflow` gate new scheduling at\n deterministic, replay-patched wait conditions. Admission is rechecked after\n awaited trigger broadcasts, polling cycles, LLM, preflight, permit, and\n delegation operations, immediately before the next activity or child\n workflow is scheduled.\n- Activities already started are allowed to finish. Their results remain in\n history and are consumed after the gate opens.\n- Trigger nodes broadcast an idle/paused projection, stop their listening\n animation, and rearm on Resume.\n- Stable `paused`/`running` is published only after strict cron-Schedule and\n running-execution fan-out completes. Visibility or per-target failures leave\n the generation transitional and retryable.\n\n### 6.5 Reset semantics\n\nReset transitions the generation to `resetting` and quiesces producers before\nits final execution sweep: it synchronously closes local admission, signals the\ncontroller to close, deletes generation cron schedules, and cancels local\ncompatibility resources. It then strictly terminates controller descendants and\nstandalone roots carrying the application workflow search attribute before\narchiving the data scope. `EventWorkflowId` is propagated to Schedule action\nexecutions and detached/abandoned graph children so those standalone runs remain\ndiscoverable. Runtime/node cleanup completes before the database publishes\n`reset`; a failed step leaves `resetting` retryable. A duplicate command against\nan already-reset generation returns idempotently without repeating cleanup,\nwhich prevents an old retry from affecting a later generation. Reset does\n**not** start the next generation.\n\nTask history and historical Temporal histories are preserved. Existing\nhistorical rows continue to appear in Temporal Web until namespace retention or\nan explicit administrative deletion policy removes them.\n\n## 7. Trigger architecture\n\n### 7.1 Controlled push and polling triggers\n\n```mermaid\nsequenceDiagram\n autonumber\n participant Producer as Plugin producer\n participant Dispatch as events.dispatch\n participant Visibility as Temporal Visibility\n participant Control as WorkflowControlWorkflow\n participant Activity as Poll/plugin activity\n participant Run as MachinaWorkflow\n\n Producer->>Dispatch: emit(CloudEvent)\n par realtime projection\n Dispatch-->>Dispatch: broadcast WebSocket event\n and durable routing\n Dispatch->>Visibility: list legacy EventType consumers OR controllers\n Dispatch->>Control: on_event(envelope)\n end\n Control->>Control: filter by registered types + deduplicate\n alt running\n Control->>Run: start actual graph child\n else paused\n Control->>Control: retain FIFO event\n end\n\n loop polling trigger while running\n Control->>Activity: poll.{node_type}.v{version}\n Activity-->>Control: seen_ids + events\n Control->>Control: deduplicate\n Control->>Run: start actual graph child\n end\n```\n\nThere are no `TriggerListenerWorkflow` or `PollingTriggerWorkflow` executions\nfor a controlled generation. Those workflow types stay registered only to\nreplay and serve legacy uncontrolled deployments.\n\n### 7.2 Trigger graph materialization\n\nBefore a trigger starts `MachinaWorkflow`, the engine builds a downstream graph:\n\n1. Mark the firing trigger `_pre_executed` with the event payload.\n2. Mark sibling triggers as non-firing so they do not block dependency\n resolution.\n3. Retain downstream executable nodes and their configuration attachments.\n4. Optionally load the latest persisted graph through an activity; the saved\n deployment snapshot is the deterministic fallback.\n5. Start a child ID derived from workflow slug, trigger label, and event ID.\n\n### 7.3 Cron exception\n\nCron remains a Temporal Schedule because server-side calendar evaluation,\ntimezone handling, catch-up windows, and overlap policy belong to Temporal's\nSchedule service. Pause/unpause operates on the Schedule resource. A firing\nuses the plugin-owned `CronTriggerWorkflow`, which then starts the graph run.\nThis is a scheduled execution, not a continuously running listener.\n\n## 8. Graph execution (`MachinaWorkflow`)\n\n```mermaid\nflowchart TD\n Input[Graph payload] --> Normalize[Normalize nodes, edges, identities]\n Normalize --> Filter[Remove configuration-only nodes from executable DAG]\n Filter --> Deps[Build dependencies and reverse edges]\n Deps --> Seed[Seed pre-executed trigger outputs]\n Seed --> Ready[Find all ready nodes]\n Ready --> Gate{Paused?}\n Gate -- yes --> Wait[workflow.wait_condition]\n Wait --> Ready\n Gate -- no --> Route{Node class}\n Route -- agent --> AgentWF[Start AgentWorkflow child]\n Route -- plugin per-type --> PluginAct[node.type.version activity on declared queue]\n Route -- legacy --> LegacyAct[execute_node_activity]\n AgentWF --> Complete[Record result]\n PluginAct --> Complete\n LegacyAct --> Complete\n Complete --> Fanout[Make downstream nodes eligible]\n Fanout --> Done{All terminal?}\n Done -- no --> Ready\n Done -- yes --> Result[outputs + execution_trace + error]\n```\n\nThe scheduler follows a continuous ready-set/FIRST_COMPLETED pattern. It does\nnot wait for an entire topological layer when one branch finishes early.\nConfiguration handles (`input-tools`, `input-memory`, `input-model`,\n`input-skill`, `input-task`, and `input-teammates`) bind capabilities but do not\nnormally create executable dependencies. `taskTrigger -> input-task` is the\nexplicit runtime-data exception.\n\n### 8.1 Dispatch matrix\n\n| Node | Primary dispatch | Compatibility dispatch |\n|---|---|---|\n| Ordinary plugin node | `node.{type}.v{version}` activity | `execute_node_activity` |\n| Supported AI/team agent | `AgentWorkflow` child | Per-type/legacy agent activity when feature-disabled |\n| RLM / CLI session agents | Per-type activity | Legacy dispatcher |\n| Controlled push/poll trigger | Controller Signal/activity | Listener workflows for legacy deployments |\n| Cron trigger | Temporal Schedule + plugin workflow | No in-memory APScheduler production path |\n\n### 8.2 Retries and timeouts\n\n- Framework activities use shared retry policies with user-correctable error\n classes marked non-retryable.\n- Plugin activities may declare their own task queue, timeout, heartbeat, and\n retry settings.\n- LLM steps use a longer LLM-specific retry/timeout policy.\n- Tool failures are returned to the agent as structured tool errors after\n activity retries; sibling calls are not cancelled.\n- Workflow code contains orchestration only. Network, database, LLM, filesystem,\n broadcast, and clock-dependent side effects belong in activities.\n\n## 9. Agent execution\n\n```mermaid\nsequenceDiagram\n autonumber\n participant Root as MachinaWorkflow\n participant Agent as AgentWorkflow\n participant LLM as agent.execute_llm_step.v1\n participant Tools as Plugin activities\n participant Memory as persist/compact activities\n\n Root->>Agent: child(payload, isolated conversation)\n loop bounded agent iterations\n Agent->>Agent: pause gate\n Agent->>LLM: messages + visible tool schemas\n LLM-->>Agent: final answer or ordered tool calls\n alt tool calls\n par independent calls\n Agent->>Tools: activity/child call 1\n and\n Agent->>Tools: activity/child call N\n end\n Tools-->>Agent: success/error results\n Agent->>Agent: append results in original call order\n Agent->>Memory: persist turn\n opt token threshold exceeded\n Agent->>Memory: compact memory\n end\n else final\n Agent-->>Root: compact result + usage\n end\n end\n```\n\nEvery agent receives only the tools, skills, memory, model configuration, and\nteammates connected to that node in the server-side graph. The canvas is used\nfor capability resolution but unrelated canvas content is not serialized into\nthe model prompt.\n\nDynamic tool refresh uses `agent.refresh_tools.v1`. Provider-visible names must\nbe unique. Specialized delegate names are type-derived; repeatable `aiAgent`\ndelegates use label-derived, collision-safe names.\n\n## 10. Durable team delegation\n\n### 10.1 Runtime topology\n\n```mermaid\nflowchart LR\n Lead[Lead AgentWorkflow] -->|task_manager.assign_task| Persist[Persist TeamTask]\n Persist --> Runner[DelegatedTaskWorkflow]\n Runner --> Permit[(Root-wide permit)]\n Permit --> Child[Child AgentWorkflow]\n Child --> Result[Submit compact result]\n Result --> Attempt[(Immutable TeamTaskAttempt)]\n Result --> Trigger[taskTrigger CloudEvent]\n Trigger --> Control[WorkflowControlWorkflow]\n Control --> Review[New lead review invocation]\n Review --> Decision{Lead decision}\n Decision -->|accept| Accepted[accepted]\n Decision -->|retry/reassign| Runner\n Decision -->|cancel| Cancelled[cancelled]\n```\n\n### 10.2 Delegation invariants\n\n- Only canonical `input-teammates` connections authorize assignment.\n- `aiAgent` is repeatable; other specialized teammate types are unique.\n- Maximum delegation depth is two child layers.\n- The default root-wide active-descendant cap is three. The root is excluded;\n children and grandchildren are included.\n- Persistence succeeds before a child starts.\n- `DelegatedTaskWorkflow` waits for a durable permit and heartbeats while\n queued.\n- Graceful success, failure, and cancellation paths release their permit\n idempotently. Immediate Temporal termination requires the reset reconciler\n described in Known Limitations.\n- A worker result moves a task to `submitted`, not `accepted`.\n- The lead or authorized human must review submitted work.\n- Retry and reassignment create new attempts; they never overwrite history.\n- The assigning lead returns after durable queueing and does not synchronously\n wait for the teammate.\n\n### 10.3 Task state machine\n\n```mermaid\nstateDiagram-v2\n [*] --> blocked: unresolved dependencies\n [*] --> queued: eligible assignment\n blocked --> queued: dependencies accepted\n queued --> running: task claimed + permit acquired\n running --> submitted: child completed\n running --> queued: retryable failure\n running --> failed: terminal failure\n running --> cancelled: cancellation/reset\n submitted --> accepted: lead/human review passes\n submitted --> queued: retry or reassignment\n submitted --> cancelled: waived/cancelled\n failed --> queued: retry or reassignment\n cancelled --> queued: revised retry/reassignment\n```\n\n## 11. Persistence model\n\n### 11.1 Saved definition versus run-data scope\n\n`workflows` stores the editable, stable canvas definition. Runtime state is\npartitioned by `workflow_run_data_scopes`, with exactly one scope per workflow\ncontrol generation. The scope snapshots all admitted node data, maps the\napplication execution identity to the actual Temporal controller Workflow/Run\nidentity, and supplies the session namespace used by node-output persistence.\n\nReset archives the scope rather than deleting it. A later Start creates a new\nscope and therefore a fresh node-data namespace, while archived task, output,\ntrace, and graph-snapshot records remain available for historical inspection.\n\n`simpleMemory` settings remain durable, but its conversation state is\ngeneration-bound. Reset first writes the final memory parameters to the\narchived scope's `runtime_data.simple_memory`, then clears the live transcript,\ncontinuation metadata, connected sessions, vector/direct-memory caches,\nconversation rows, and token counters. The next Start reads the reset live row.\n\n| State class | Reset behavior | Current source after Reset |\n|---|---|---|\n| Graph/node execution outputs and statuses | archived; live projection cleared | new generation scope |\n| Console and chat-trigger run rows | archived by root execution | new generation scope |\n| Team tasks, attempts, and traces | archived and queryable | selected execution history |\n| Node parameters and canvas configuration | preserved | `node_parameters` / `workflows` |\n| `simpleMemory` transcript and session state | archived, then cleared | reset `node_parameters` + memory services |\n\n### 11.2 Generic node runtime lifecycle\n\nReset orchestration must not contain node-type branches. The framework archives\nevery admitted node under `WorkflowRunDataScope.runtime_data.nodes`, keyed by\nnode ID and therefore transitively by `{workflow_id, execution_id, node_id}`.\nEach entry contains the node type, admitted canvas data, and final parameter\nsnapshot.\n\nAfter the generic archive succeeds, the coordinator resolves each node through\nthe node registry and calls `BaseNode.reset_execution_state(...)`. The default\nimplementation is a no-op for stateless nodes. A stateful plugin overrides the\nhook to clear stores it owns and returns refreshed parameters for the standard\n`node_parameters_updated` broadcast. Adding another stateful node therefore\nrequires a plugin lifecycle declaration, not a deployment-manager condition.\n\nNormal execution output remains isolated by the generation's `data_scope_id`\nsession namespace. Console/chat rows, teams, tasks, attempts, and traces carry\nthe root execution ID explicitly. Together these identities prevent a current\nrun from reading another generation's mutable data while keeping archived runs\ninspectable.\n\n```mermaid\nerDiagram\n WORKFLOW_CONTROL_EXECUTION {\n string id PK\n string workflow_id\n int generation\n string execution_id\n string root_execution_id\n string controller_workflow_id\n string controller_run_id\n string status\n int revision\n json graph_snapshot\n string graph_hash\n string idempotency_key\n }\n AGENT_TEAM {\n string id PK\n string workflow_id\n string execution_id\n string root_execution_id\n string team_lead_node_id\n string status\n }\n TEAM_TASK {\n string id PK\n string team_id FK\n string execution_id\n string root_execution_id\n string assigned_to\n string status\n int revision\n int current_attempt\n json result\n json usage\n }\n TEAM_TASK_ATTEMPT {\n string id PK\n string task_id FK\n int attempt_number\n string runner_workflow_id\n string runner_run_id\n string child_workflow_id\n string child_run_id\n string parent_workflow_id\n string parent_run_id\n string status\n json result\n json usage\n }\n AGENT_MESSAGE {\n int id PK\n string team_id FK\n string event_id\n string message_type\n json extra_data\n }\n SUBAGENT_CONCURRENCY_PERMIT {\n string permit_id PK\n string root_execution_id\n string status\n }\n\n WORKFLOW_CONTROL_EXECUTION ||--o{ AGENT_TEAM : scopes\n AGENT_TEAM ||--o{ TEAM_TASK : owns\n TEAM_TASK ||--o{ TEAM_TASK_ATTEMPT : preserves\n AGENT_TEAM ||--o{ AGENT_MESSAGE : records\n WORKFLOW_CONTROL_EXECUTION ||--o{ SUBAGENT_CONCURRENCY_PERMIT : limits\n```\n\nSQLite startup migrations add new nullable columns and indexes without making\nhistorical rows unreadable. Historical attempts without execution links report\n`execution_not_registered`.\n\n## 12. Trace and observability architecture\n\n```mermaid\nsequenceDiagram\n autonumber\n actor Lead as Team lead / human\n participant TM as Task Manager\n participant API as TeamTaskTraceService\n participant DB as Application DB\n participant Temporal as Temporal History\n participant Audit as Agent messages/audit\n\n Lead->>TM: inspect_task_trace(task_id, attempt, detail)\n TM->>API: trusted workflow + lead + execution scope\n API->>DB: authorize task and resolve persisted attempt link\n DB-->>API: actual workflow/run IDs\n API->>Audit: trace_inspection event (no raw query)\n API->>Temporal: fetch_history_events(cursor, bounded page)\n Temporal-->>API: event page\n API->>API: allowlist normalize + redact\n alt detail = search\n API->>API: literal/all/any term match + category filter + context window\n end\n API-->>TM: sanitized events + next_cursor + availability state\n```\n\nTrace detail modes:\n\n| Mode | Purpose |\n|---|---|\n| `summary` | Failures, activities, and child transitions |\n| `failures` | Failure and timeout events only |\n| `timeline` | Sanitized normalized event page |\n| `search` | Bounded grep-style scan with context and continuation cursor |\n\nSearch scans at most 500 normalized events per request, supports literal,\nall-term, and any-term matching, filters by event category, and returns at most\nfive surrounding events. Raw payload mode does not exist. Prompts, tool\narguments, credentials, tokens, raw results, and arbitrary failure payloads are\nexcluded by allowlist normalization and secret redaction.\n\n### 12.1 OpenTelemetry interceptor ownership\n\n`core.tracing.init_tracing()` owns the process-wide `TracerProvider` and span\nexporter. The shared Temporal client owns exactly one SDK\n`TracingInterceptor`. A Python SDK `Worker` automatically prepends compatible\ninterceptors from its client, so worker interceptor lists **must not** repeat\n`TracingInterceptor`; they contain only OpenCompany's\n`ObservabilityWorkerInterceptor` and any distinct plugin-owned worker\ninterceptors.\n\n```text\nTemporal client\n└── TracingInterceptor (registered once)\n └── inherited by every Worker built from that client\n └── ObservabilityWorkerInterceptor (explicit, worker-only)\n```\n\nRegistering `TracingInterceptor` on both `Client.connect(...)` and\n`Worker(...)` wraps every workflow and activity twice. The resulting spans are\ndifferent OpenTelemetry spans, but the compact console formatter omits their\nspan IDs, so adjacent copies have the same operation name and Temporal\nworkflow/run/activity attributes and appear identical. This is duplicate\ninstrumentation, not evidence that Temporal executed the workflow twice.\n\n| Span or log | Meaning |\n|---|---|\n| `StartActivity:<activity>` | Workflow-side scheduling and trace-context propagation; not the activity body |\n| `RunActivity:<activity>` | Worker-side activity invocation; a real retry is a separate attempt |\n| `node.<type>.eFile truncated at 1 MB.