Skip to content

Self-improving AI Employees for everyone

docs: correct docs-internal against the code, archive what it superseded, card every node

trohitgb020e566592e
diff --git a/CLAUDE.md b/CLAUDE.md
index cdafca5c..61c55b89 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,12 +10,12 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| Document | Description |
|----------|-------------|
| **[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. |
-| **[UI Migration Plan](./docs-internal/ui_migration_plan.md)** | antd → shadcn/ui migration plan + completion log. Waves 1–10 done. Full frontend is schema-driven (backend SSOT); remaining DIY widget registry (ex-Phase 6) is the one deferred item. |
-| **[Temporal Cleanup & Resilience Plan (Waves 15-18)](./docs-internal/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md)** | RFC for the four forward waves: 15 dead-code retirement (Redis-Streams branch in event_waiter, APScheduler cron stack, orphaned `connection_status` factory — ~556 LOC), 16 per-queue task routing activation (`TemporalWorkerPool` + `TEMPORAL_WORKER_POOL_ENABLED` gate), 17 resilience hardening (cron `catchup_window`, one-shot LLM-step retry, SDK interceptors, `DEPLOYMENT_MODE`, periodic heartbeats), 18 worker performance tuning (per-queue rate limits, sticky cache, poller autoscaling, resource-based slot supplier). Ship order, rollback channels, verified line citations. |
+| **[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). |
+| **[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). |
| **[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. |
| **[Theme System](./docs-internal/theme_system.md)** | 12-way visual theme system — 2 base (light, dark) + 5 utopian (renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. 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), per-theme `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-component decorative ornaments (panel textures + canvas decorations + node pseudo-element overlays + theme-specific keyframes), **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 (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine, etc.), **`data-page-hidden` animation pause** (toggled by Dashboard's `visibilitychange` listener; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyph system** (290 SVGs across 29 keys × 10 themes via [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts) + theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **decorative HTML primitives** (`<SvgFilterDefs>` mounting `#ink-blot` / `#noise` / `#crt` filter IDs at app root, `<DropCap>` wrapper for Renaissance ornament rule), **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), **per-theme scrollbar webkit rules** in all 12 themes, 9-event WebAudio sound system (10 packs 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. |
| **[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`), 12-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 × 12 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). |
-| **[Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md)** | Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons. 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`. Live invariant total via `pytest --collect-only`. |
+| **[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). |
| **[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)` — 30 at time of writing, do not hand-maintain. `TaskQueue` constants route to Temporal worker pools. Plugins live across 9 queues (live count via `glob server/nodes/**/__init__.py`); 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"** — up to seven generic registries (`ws_handler_registry`, `register_router`, `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`) so rich plugins like telegram own their entire surface area without core-services edits. |
| **[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. |
| **[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 six `register_*` hooks. Covers tool nodes, dual-purpose nodes (workflow + AI tool), and specialized agents as variations of the same recipe. |
@@ -46,14 +46,14 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Release Build Pipeline](./docs-internal/release_build_pipeline.md)** | npm-distribution build pipeline: `typescript@7` (native Go compiler, exact-pinned in **root** devDependencies — client keeps `typescript@^5.x` because typescript-eslint's peer range excludes 6/7, and one manifest cannot declare `typescript` twice) for type-check, measured 5.9× faster than tsc 5.9.3 (820 ms vs 4830 ms); `bun run --filter react-flow-client typecheck` delegates up to the root gate, Vite `manualChunks` + `target: 'es2022'`, esbuild Node.js sidecar bundle (drops `tsx` interpreter cost), bytecode pre-compile in two halves — `[tool.uv] compile-bytecode = true` (uv sync compiles `.venv/` site-packages) + `python -m compileall` for project source (plain `.pyc`, **no `-O`** — per PEP 488 the non-`-O` runtimes never load `.opt-1.pyc`; excludes `.venv/`, `tests/`). Single source of truth for the bytecode-compile path list: `cli.commands.build.COMPILEALL_SOURCE_DIRS`. Dev PM is **[email protected]** (tracked text `bun.lock`, `bunfig.toml` pins the isolated linker, ranged security pins in top-level `overrides`); `company build` step [1/6] is `bun install`. |
| **[Workflow Schema](./docs-internal/workflow-schema.md)** | JSON schema for workflows, edge handle conventions, config node architecture |
| **[Execution Engine Design](./docs-internal/DESIGN.md)** | Architecture patterns, design standards, and implementation details for the workflow execution engine |
-| **[Execution Roadmap](./docs-internal/ROADMAP.md)** | Implementation status, completed phases, and pending features |
+| **[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 |
| **[Setup Guide](./docs-internal/SETUP.md)** | Development environment setup and installation instructions |
-| **[Scripts Reference](./docs-internal/SCRIPTS.md)** | Available npm/shell scripts and their usage |
-| **[Server Documentation](./docs-internal/server-readme.md)** | Python backend architecture and API documentation |
+| **[Scripts Reference](./docs-internal/SCRIPTS.md)** | `bun run` scripts, `company` CLI verbs, and their usage |
+| **[Server Documentation](./docs-internal/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) |
| **[Skill Creation Guide](./server/skills/GUIDE.md)** | How to create new skills (folder structure, SKILL.md format, metadata, supporting files) |
| **[Known Errors & Troubleshooting](./docs-internal/errors.md)** | Documented root causes and fixes for common errors (SQLAlchemy Windows hang, Temporal issues, WhatsApp timeouts) |
-| **[New Service Integration](./docs-internal/new_service_integration.md)** | Complete guide for integrating external services (OAuth, database, handlers, nodes, AI tools) - use Google Workspace as reference |
-| **[Onboarding Service](./docs-internal/onboarding.md)** | First-launch welcome wizard with 5 steps, database persistence, and replay from Settings |
+| **[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 |
+| **[Onboarding Service](./docs-internal/onboarding.md)** | First-launch welcome wizard with 4 steps, database persistence, and replay from Settings |
| **[CLI Services Integration](./docs-internal/cli_services_integration.md)** | Guide for integrating CLI-based services (Temporal, etc.) with proper lifecycle management |
| **[Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md)** | Distributed workflow execution: activities, FIRST_COMPLETED scheduling, horizontal scaling |
| **[Native LLM SDK](./docs-internal/native_llm_sdk.md)** | Native SDK layer in `services/llm/`: protocol-based providers, config-driven base URLs, and 13 providers (11 cloud plus Ollama / LM Studio; 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. Every provider is native; `tests/llm/test_langchain_removed.py` locks the retired-dependency end state. |
@@ -71,11 +71,11 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[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 default is `acceptEdits`. |
| **[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`. |
| **[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`. |
-| **[Autonomous Agent Creation](./docs-internal/autonomous_agent_creation.md)** | Creating autonomous agents with Code Mode patterns and agentic loops |
+| **[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/) |
| **[Polyglot Server](../polyglot-server/ARCHITECTURE.md)** | Plugin registry microservice with MCP gateway (optional integration) |
| **[Authentication](./docs-internal/authentication.md)** | JWT/cookie auth: toggle, single/multi mode, backend + frontend, middleware, startup retry. |
-| **[Credentials Panel](./docs-internal/credentials_panel.md)** | CredentialsModal.tsx logic-flow reference (state taxonomy, per-provider panels, invariants). |
-| **[Memory Lifecycle](./docs-internal/memory_lifecycle.md)** | **Stale — pre-RFC-0002.** Documents the retired `input-memory` markdown model. The `services/memory/` helper API, vector store and `claude_code_agent` session bridge sections still hold; the lifecycle and state-clear sections do not. See "Context and Memory (RFC-0002)" below. |
+| **[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). |
+| **[Memory Lifecycle](./docs-internal/ARCHIVE/memory_lifecycle.md)** | *Archived — pre-RFC-0002.* Documented the retired `input-memory` markdown model. See "Context and Memory (RFC-0002)" below, [Agent Context Flow](./docs-internal/agent_context_flow.md) and [Memory Compaction](./docs-internal/memory_compaction.md). |
| **[Node Parameter Panel](./docs-internal/node_panels.md)** | Three-section node config UI (Input / Parameters / Output) logic-flow reference. |
| **[Deployment (legacy reference)](./docs-internal/deployment_legacy.md)** | `company deploy` CLI summary + the historical Docker Compose topology. |
| **[GCP VM Deploy Runbook](./docs-internal/gcp_vm_deploy_runbook.md)** | Manual gcloud + Cloudflare runbook for deploying the released npm package (non-Terraform path). |
@@ -123,7 +123,7 @@ The workflow backend follows modular architecture patterns from n8n, Temporal, a
```
server/services/
-├── workflow.py # Facade (~460 lines) - thin coordinator
+├── workflow.py # Facade (~840 lines) - thin coordinator
├── node_executor.py # Single node execution with registry pattern
├── parameter_resolver.py # Template variable resolution
├── agent_team.py # AgentTeamService for multi-agent coordination
@@ -813,7 +813,7 @@ See **[Scripts Reference](./docs-internal/SCRIPTS.md)** for full documentation.
✅ **Event-Driven Deployment**: n8n-style architecture where each trigger event spawns an independent, concurrent execution run (no iteration loop)
✅ **HTTP/Webhook Nodes**: HTTP Request for external APIs, Webhook Trigger for incoming requests, Webhook Response for custom responses
✅ **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
-✅ **Modular Backend Architecture**: workflow.py refactored from 2068 to 460 lines using facade pattern with NodeExecutor, ParameterResolver, and DeploymentManager modules
+✅ **Modular Backend Architecture**: workflow.py refactored from 2068 lines into a facade (~840 lines today) over NodeExecutor, ParameterResolver, and DeploymentManager modules
✅ **Node Rename System**: n8n-style node renaming via F2 keyboard shortcut, double-click on label, or right-click context menu with inline editing
✅ **UI State Persistence**: localStorage persistence for sidebar visibility, component palette visibility, dev mode, and collapsed sections
✅ **Normal/Dev Mode**: Toggle in toolbar to filter Component Palette - Normal mode shows only AI Agents, Models, and Skills; Dev mode shows all categories
@@ -821,7 +821,7 @@ See **[Scripts Reference](./docs-internal/SCRIPTS.md)** for full documentation.
✅ **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)
✅ **Cache System**: n8n-pattern cache with Redis (production) / SQLite (local dev) / Memory fallback hierarchy
✅ **AI Thinking/Reasoning**: Extended thinking for Claude, Gemini 2.5/3, OpenAI GPT-5/o-series, Groq Qwen3 with output available in Input Data & Variables for downstream nodes
-✅ **Onboarding Service**: 5-step welcome wizard with shadcn UI, database persistence, skip/resume/replay support
+✅ **Onboarding Service**: 4-step welcome wizard with shadcn UI, database persistence, skip/resume/replay support
✅ **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`
✅ **Markdown Formatter**: GFM markdown to platform-native formatting (Telegram HTML, WhatsApp syntax, plain text) using markdown-it-py
@@ -1147,7 +1147,7 @@ deploy_workflow() -> Sets up triggers, returns immediately
- **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
**Implementation Files:**
-- `server/services/workflow.py`: Thin facade (~460 lines) delegating to specialized modules
+- `server/services/workflow.py`: Thin facade (~840 lines) delegating to specialized modules
- `server/services/node_executor.py`: Single node execution with registry-based dispatch
- `server/services/parameter_resolver.py`: Template variable resolution (`{{node.field}}`)
- `server/services/deployment/manager.py`: Deployment lifecycle, spawn runs, cancel
@@ -1158,7 +1158,7 @@ deploy_workflow() -> Sets up triggers, returns immediately
### AI Chat Model System (5-Layer Architecture)
-Chat-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 12-provider surface is 10 cloud providers plus Ollama and LM Studio. Eleven providers have standalone chat-model nodes, while xAI is selected directly from agent parameters. 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)**. A Temporal history recorded before the native cutover carries no `llm_engine` marker and messages in a retired wire format; `agent.execute_llm_step` refuses it with a non-retryable `InvalidAgentLLMEngine` rather than misreading it, and the deployment must be Reset. The runtime output schema (`thinking` field for downstream nodes) is backend-served per [Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md).
+Chat-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 13-provider surface is 11 cloud providers plus Ollama and LM Studio. Twelve providers have standalone chat-model nodes under `server/nodes/model/`, while xAI is selected directly from agent parameters. 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)**. A Temporal history recorded before the native cutover carries no `llm_engine` marker and messages in a retired wire format; `agent.execute_llm_step` refuses it with a non-retryable `InvalidAgentLLMEngine` rather than misreading it, and the deployment must be 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)).
## AI Agent Node Architecture
@@ -1404,7 +1404,7 @@ Both paths implement the same contract: Temporal via `prepare_agent_payload` (lo
**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.
-Lifecycle helpers live in `server/services/memory/`; token tracking and compaction thresholds are in **[Memory Compaction](./docs-internal/memory_compaction.md)**. **[Memory Lifecycle](./docs-internal/memory_lifecycle.md)** still documents the pre-RFC-0002 markdown model and is stale.
+Lifecycle 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).
## Memory Compaction, Token Tracking, and Cost Calculation
@@ -2175,7 +2175,7 @@ whatsappReceive: {
#### Output Schema (plugin-owned, `server/nodes/whatsapp/whatsapp_receive.py`)
Runtime 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.
-Served via `GET /api/schemas/nodes/whatsappReceive.json` + `get_node_output_schema` WS handler. See [docs-internal/schema_source_of_truth_rfc.md](./docs-internal/schema_source_of_truth_rfc.md).
+Served 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)).
### Task Trigger Node
@@ -2647,7 +2647,7 @@ This function:
- **Interface Alignment**: ParameterRenderer supports both interface types seamlessly
- **Execution Ready**: Components can be executed with real-time result display
- **Clean Codebase**: Significant file and code reduction while maintaining full functionality
-- **Modular Backend**: workflow.py reduced from 2068 to 460 lines via facade pattern
+- **Modular Backend**: workflow.py reduced from 2068 lines to a facade (~840 lines today)
- NodeExecutor: Registry-based dispatch with `functools.partial` for dependency injection
- ParameterResolver: Compiled regex for `{{node.field}}` template resolution
- DeploymentManager: Handles deploy/cancel lifecycle with TriggerManager for cron/events
@@ -2739,10 +2739,10 @@ This function:
- **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.
- **Skill System Architecture**: Skills organized in `server/skills/<folder>/` subfolders. Each folder appears in Master Skill dropdown. DB/Master Skill customization is authoritative. Standard skills use progressive disclosure without modifying the agent system prompt: the dynamically connected `Skill` tool carries the bounded name/description catalogue, loads instructions, then separately reads/searches declared resources. Personality skills remain eager. Duplicate connected names block with `DUPLICATE_CONNECTED_SKILL_NAME`. Runtime state and sanitized `agent.skill.*` observability live in [`skill_runtime.py`](./server/services/skill_runtime.py); tool results persist in the current conversation while canvas badges clear at turn end. Icon resolution mirrors `BaseNode._metadata_dict`: per-plugin `<plugin>/icon.svg` (served as `/api/schemas/nodes/<type>/icon`) → `visuals.json` (emoji / `lobehub:<brand>`); color: per-plugin `<plugin>/meta.json` → `visuals.json`. Lives in [`skill_loader.py::_parse_skill_metadata`](./server/services/skill_loader.py). Native DOM keydown handler prevents React Flow from intercepting Ctrl shortcuts in skill editor. **Mutation broadcasts use the CloudEvents-typed `skill_lifecycle` wire key** with stages `created` / `updated` / `deleted` / `content_saved` — see "Plugin-folder location for plugin-specific CloudEvents factories" below.
- **Example Workflows**: Auto-load example workflow seeds from `<repo>/.opencompany/workflows/` on first use (git-tracked; the only non-ignored content under `<repo>/.opencompany/`). Path resolved by `core.paths.example_workflows_dir()` — fixed, NOT under `DATA_DIR`, preserved by `company clean` via `_OPENCOMPANY_KEEP`. Uses `UserSettings.examples_loaded` flag; supports anonymous users (`user_id="default"`); embedded `nodeParameters` saved to DB on import.
-- **Onboarding Service**: 5-step welcome wizard (Welcome, Concepts, API Keys, Canvas Tour, Get Started) using shadcn primitives + lucide icons. Database-backed via `UserSettings.onboarding_completed` + `onboarding_step`. Existing users auto-skip (migration marks `examples_loaded=1` as completed). Replayable from Settings "Help" section. No new WebSocket handlers needed. See [Onboarding Service](./docs-internal/onboarding.md) for details.
+- **Onboarding Service**: 4-step welcome wizard (Welcome, How it works, Connect your AI, Try it) using shadcn primitives + lucide icons. Database-backed via `UserSettings.onboarding_completed` + `onboarding_step`. Existing users auto-skip (migration marks `examples_loaded=1` as completed). Replayable from Settings "Help" section. No new WebSocket handlers needed. See [Onboarding Service](./docs-internal/onboarding.md) for details.
- **Node.js Code Executor**: Persistent Node.js server (Express + tsx) at `NODEJS_EXECUTOR_PORT` for JavaScript/TypeScript execution, replacing subprocess spawning per execution. The code executor plugins under `server/nodes/code/` call `NodeJSClient` which makes HTTP requests to the Node.js server. All config via environment variables (`NODEJS_EXECUTOR_URL`, `NODEJS_EXECUTOR_PORT`, etc.).
- **writeTodos Tool Node**: Dedicated AI tool for task planning connecting to any agent's `input-tools` handle. `TodoService` singleton (`server/services/todo_service.py`) stores JSON-based per-session todo state keyed by workflow_id. Handler broadcasts `phase: "todo_update"` via WebSocket on each update for real-time UI. (The former checklist rendering — `formatTodoOutput()` — lived only in the legacy `ui/OutputDisplayPanel.tsx`, which was deleted as dead code; the active `components/output/OutputPanel.tsx` shows todo results as regular JSON.) Schema uses `TodoItem`/`TodoStatus` Pydantic enum. Skill at `server/skills/assistant/write-todos-skill/SKILL.md` teaches the plan-work-update loop.
-- **Temporal Activity Heartbeats**: Activities send `activity.heartbeat()` on every non-matching WebSocket broadcast inside the read loop in `services/temporal/activities.py`. This keeps long-running browser and claude_code_agent operations alive past the 2-minute `heartbeat_timeout`. Start/end heartbeats alone were causing `TIMEOUT_TYPE_HEARTBEAT` failures on ops taking 5-10 minutes. Connection config: `heartbeat=30`, `receive_timeout=540` (fits within 10-min `start_to_close_timeout`).
+- **Temporal Activity Heartbeats**: Activities send `activity.heartbeat()` on every non-matching WebSocket broadcast inside the read loop in `services/temporal/activities.py`. This keeps long-running browser and claude_code_agent operations alive past the 2-minute `heartbeat_timeout`. Start/end heartbeats alone were causing `TIMEOUT_TYPE_HEARTBEAT` failures on ops taking 5-10 minutes. Connection config: `heartbeat=30`, `receive_timeout=None` (each receive is bounded by a 30 s `asyncio.wait_for`; liveness comes from heartbeats, and per-node activities run under a 24 h `start_to_close_timeout`).
- **WebSocket `_safe_send` Guard**: `server/routers/websocket.py` checks `websocket.client_state.name != "CONNECTED"` before sending and logs at `debug` level (not `error`) on failure. Prevents "ASGI message after websocket.close" errors when broadcasts race with disconnects.
- **Claude Code CLI Flag**: the Claude Code agent (`nodes/agent/claude_code_agent/`) uses `--max-budget-usd <amount>` (previously incorrectly `--max-cost`, which caused "unknown option" errors on every run).
- **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 set: `nodeSpec`, `nodeGroups`, `skillContent`. `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.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4b3f8761..5d1c1888 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -104,11 +104,11 @@ The diagram above shows the full lifecycle of a workflow node: one self-containe
**Integrate an OAuth service**
- 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`
-- ([new_service_integration.md](docs-internal/new_service_integration.md) is historical — do not follow its steps)
+- ([new_service_integration.md](docs-internal/ARCHIVE/new_service_integration.md) is archived — do not follow its steps)
**Add a credential provider**
- 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
-- Guides: [credentials_encryption.md](docs-internal/credentials_encryption.md) (storage pipeline) + [credentials_panel.md](docs-internal/credentials_panel.md) (modal state machine); test conventions in [server/tests/credentials/README.md](server/tests/credentials/README.md)
+- 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)
**Contribute frontend / a new theme**
- 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
@@ -121,7 +121,7 @@ The diagram above shows the full lifecycle of a workflow node: one self-containe
- **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.
- **Import sanity:** `uv run pytest --collect-only` (from `server/`) is the live plugin-count invariant — it fails if any plugin errors at import.
- **Credential tests** follow the numbered-invariant style documented in [server/tests/credentials/README.md](server/tests/credentials/README.md).
-- Run everything: `uv run pytest` from `server/`, `npm test` from `client/`, `uv run pytest cli/tests` from the repo root.
+- 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.
## Local Dev Quick Reference
@@ -152,25 +152,25 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.
| [DESIGN.md](docs-internal/DESIGN.md) | Execution engine architecture, design patterns, execution modes |
| [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) | Distributed execution via Temporal activities |
| [workflow-schema.md](docs-internal/workflow-schema.md) | Workflow JSON schema and node catalog (live count = glob `server/nodes/**/__init__.py`) |
-| [ROADMAP.md](docs-internal/ROADMAP.md) | Implementation status and completed phases |
+| [ROADMAP.md](docs-internal/ARCHIVE/ROADMAP.md) | *Archived* status snapshot; current state is in DESIGN.md and the Temporal docs |
| [SETUP.md](docs-internal/SETUP.md) | Development environment setup |
-| [SCRIPTS.md](docs-internal/SCRIPTS.md) | npm/shell scripts reference |
-| [server-readme.md](docs-internal/server-readme.md) | Python backend architecture and API |
+| [SCRIPTS.md](docs-internal/SCRIPTS.md) | bun/shell scripts and CLI verbs reference |
+| [server-readme.md](docs-internal/ARCHIVE/server-readme.md) | *Archived*; see SETUP.md, authentication.md, plugin_system.md |
| [agent_architecture.md](docs-internal/agent_architecture.md) | AI Agent / Chat Agent skill and tool discovery |
| [agent_delegation.md](docs-internal/agent_delegation.md) | How delegated agents share context and memory |
| [agent_teams.md](docs-internal/agent_teams.md) | Agent Teams pattern with `input-teammates` handle |
| [native_llm_sdk.md](docs-internal/native_llm_sdk.md) | Native LLM SDK layer and provider protocol |
| [rlm_service.md](docs-internal/rlm_service.md) | Recursive Language Model agent via REPL |
| [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) |
-| [claude_code_agent_architecture.md](docs-internal/claude_code_agent_architecture.md) | Claude Code SDK integration as a specialized agent |
+| [claude_code_agent_architecture.md](docs-internal/ARCHIVE/claude_code_agent_architecture.md) | *Archived* LangGraph-era design notes; see claude_code_interactive_mode.md |
| [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 |
-| [autonomous_agent_creation.md](docs-internal/autonomous_agent_creation.md) | Autonomous agents with Code Mode patterns |
+| [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/` |
| [event_framework.md](docs-internal/event_framework.md) | Wave 12 event framework — Temporal Signals + Visibility routing, Search Attributes, plugin `_events.py` contract |
| [stripe_service.md](docs-internal/stripe_service.md) | Reference Wave 12 plugin — signed webhooks + CLI-managed auth, file-by-file |
| [vercel_service.md](docs-internal/vercel_service.md) | CLI-managed auth, device-flow variant |
| [github_service.md](docs-internal/github_service.md) | gh CLI integration — CLI owns auth entirely |
| [discord_service.md](docs-internal/discord_service.md) | Discord bot — gateway/REST split, multi-account on the credential `session_id` scope, Ed25519 interactions endpoint |
-| [event_waiter_system.md](docs-internal/event_waiter_system.md) | Push-based trigger waiters *(historical, pre-Wave-11 — canvas-Run path only)* |
+| [event_waiter_system.md](docs-internal/event_waiter_system.md) | In-memory trigger waiters for the canvas-Run path (deployed triggers ride Temporal) |
| [status_broadcaster.md](docs-internal/status_broadcaster.md) | WebSocket broadcaster (live handler count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`) |
| [credentials_encryption.md](docs-internal/credentials_encryption.md) | Fernet + PBKDF2 credentials system |
| [memory_compaction.md](docs-internal/memory_compaction.md) | Token tracking and model-aware compaction |
@@ -178,15 +178,15 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.
| [proxy_service.md](docs-internal/proxy_service.md) | Residential proxy provider management |
| [ci_cd.md](docs-internal/ci_cd.md) | GitHub Actions workflows |
| [node_creation.md](docs-internal/node_creation.md) | How to create new nodes |
-| [memory_lifecycle.md](docs-internal/memory_lifecycle.md) | Canonical home for markdown memory format, vector store, claude_code_agent session resume |
+| [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 |
| [tool_building_pipeline.md](docs-internal/tool_building_pipeline.md) | Canonical home for `_build_tool_from_node`, tool discovery, per-type Temporal dispatch |
-| [new_service_integration.md](docs-internal/new_service_integration.md) | External service integration *(historical, pre-Wave-11 — do not follow; see the OAuth recipe above)* |
+| [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 |
| [cli_services_integration.md](docs-internal/cli_services_integration.md) | CLI service lifecycle management |
| [onboarding.md](docs-internal/onboarding.md) | Welcome wizard and replay |
| [frontend_architecture.md](docs-internal/frontend_architecture.md) | Current frontend stack, token tiers, state-ownership boundary, strict styling rules |
| [theme_system.md](docs-internal/theme_system.md) | The 12-theme token contract + "Adding a new theme" checklist |
| [workflow_ops_protocol.md](docs-internal/workflow_ops_protocol.md) | Backend → canvas mutation wire format (`{operations: [...]}`) |
-| [schema_source_of_truth_rfc.md](docs-internal/schema_source_of_truth_rfc.md) | Backend-as-SSOT for node schemas, icons, output schemas |
+| [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 |
| [node_allowlist.md](docs-internal/node_allowlist.md) | Single-config UI visibility gating (`node_allowlist.json`) |
| [authentication.md](docs-internal/authentication.md) | JWT/cookie auth — modes, middleware, frontend bootstrap |
| [errors.md](docs-internal/errors.md) | Known errors and troubleshooting |
diff --git a/cli/commands/docs.py b/cli/commands/docs.py
index 051b6a39..e2304dd7 100644
--- a/cli/commands/docs.py
+++ b/cli/commands/docs.py
@@ -30,10 +30,15 @@ app = typer.Typer(
_START = "<!-- AUTO-GENERATED-INDEX-START -->"
_END = "<!-- AUTO-GENERATED-INDEX-END -->"
_H1 = re.compile(r"^#\s+(.+)$", re.MULTILINE)
-# Mirror the existing JS regex: `` type[: str] = "<nodeType>"`` at
-# class-attribute indentation.
+# `` type[: str] = "<nodeType>"`` or `` type = NAME`` at class-attribute
+# indentation. Group 1 is the literal, group 2 the bare constant name.
_TYPE_ATTR = re.compile(
- r"^\s{4}type\s*(?::\s*str\s*)?=\s*['\"]([A-Za-z_][\w]*)['\"]",
+ r"^\s{4}type\s*(?::\s*str\s*)?=\s*(?:['\"]([A-Za-z_]\w*)['\"]|([A-Za-z_]\w*))",
+ re.MULTILINE,
+)
+# Module-level ``NAME[: str] = "<value>"`` -- the target of ``type = NAME``.
+_STR_CONST = re.compile(
+ r"^([A-Za-z_]\w*)\s*(?::\s*str\s*)?=\s*['\"]([A-Za-z_]\w*)['\"]",
re.MULTILINE,
)
@@ -96,16 +101,25 @@ def _collect_documented_keys(docs_dir: Path) -> set[str]:
def _collect_registry_keys(plugins_dir: Path) -> set[str]:
- """Scrape ``type = "<nodeType>"`` from every plugin file."""
+ """Scrape ``type = "<nodeType>"`` from every plugin file.
+
+ Scans ``__init__.py`` too (folder-per-plugin nodes declare their class
+ there), skips ``_``-prefixed helpers, collects every class in a file, and
+ resolves ``type = NAME`` against a module-level ``NAME = "..."`` string
+ constant in the same file.
+ """
keys: set[str] = set()
if not plugins_dir.exists():
return keys
for path in plugins_dir.rglob("*.py"):
- if path.name == "__init__.py" or path.name.startswith("_"):
+ if path.name.startswith("_") and path.name != "__init__.py":
continue
- match = _TYPE_ATTR.search(path.read_text(encoding="utf-8"))
- if match:
- keys.add(match.group(1))
+ text = path.read_text(encoding="utf-8")
+ consts = dict(_STR_CONST.findall(text))
+ for literal, name in _TYPE_ATTR.findall(text):
+ key = literal or consts.get(name)
+ if key:
+ keys.add(key)
return keys
diff --git a/cli/tests/test_docs.py b/cli/tests/test_docs.py
index 058fa9bd..d7fe240a 100644
--- a/cli/tests/test_docs.py
+++ b/cli/tests/test_docs.py
@@ -66,10 +66,51 @@ def test_collect_registry_keys_scrapes_type_attribute(tmp_path: Path):
assert keys == {"fooNode"}
-def test_collect_registry_keys_skips_underscore_and_init(tmp_path: Path):
+def test_collect_registry_keys_skips_underscore_helpers(tmp_path: Path):
cat = tmp_path / "category"
cat.mkdir(parents=True)
(cat / "_base.py").write_text(' type = "skipMe"\n')
- (cat / "__init__.py").write_text(' type = "alsoSkip"\n')
+ (cat / "_inline.py").write_text(' type = "alsoSkip"\n')
(cat / "good.py").write_text(' type = "goodNode"\n')
assert docs._collect_registry_keys(tmp_path) == {"goodNode"}
+
+
+def test_collect_registry_keys_scans_init_files(tmp_path: Path):
+ plugin = tmp_path / "group" / "plugin"
+ plugin.mkdir(parents=True)
+ (plugin / "__init__.py").write_text(
+ "class InitNode:\n" ' type = "initNode"\n',
+ encoding="utf-8",
+ )
+ assert docs._collect_registry_keys(tmp_path) == {"initNode"}
+
+
+def test_collect_registry_keys_collects_every_class_in_a_file(tmp_path: Path):
+ plugin = tmp_path / "group" / "two.py"
+ plugin.parent.mkdir(parents=True)
+ plugin.write_text(
+ "class Receive:\n"
+ ' type = "fooReceive"\n'
+ "\n"
+ "class Status:\n"
+ ' type: str = "fooStatus"\n',
+ encoding="utf-8",
+ )
+ assert docs._collect_registry_keys(tmp_path) == {"fooReceive", "fooStatus"}
+
+
+def test_collect_registry_keys_resolves_module_level_constant(tmp_path: Path):
+ plugin = tmp_path / "group" / "plugin" / "__init__.py"
+ plugin.parent.mkdir(parents=True)
+ plugin.write_text(
+ '_MY_TYPE = "constNode"\n'
+ "_OTHER = frozenset({_MY_TYPE})\n"
+ "\n"
+ "class ConstNode:\n"
+ " type = _MY_TYPE\n"
+ "\n"
+ "class Unresolvable:\n"
+ " type = _NOT_DEFINED_HERE\n",
+ encoding="utf-8",
+ )
+ assert docs._collect_registry_keys(tmp_path) == {"constNode"}
diff --git a/cli/tests/test_docs_paths_resolve.py b/cli/tests/test_docs_paths_resolve.py
new file mode 100644
index 00000000..e5569ad1
--- /dev/null
+++ b/cli/tests/test_docs_paths_resolve.py
@@ -0,0 +1,81 @@
+"""Every repo path a live internal doc names must exist.
+
+``docs-internal`` cites files in backticks (``server/services/foo.py``). When
+the file moves, the citation silently rots; a September 2026 audit found
+dozens of dead ones, some pointing at modules that never existed. This test
+keeps that from recurring. It checks existence only -- never line numbers or
+symbols, which drift with every commit and would make the test a nuisance.
+
+Skipped on purpose:
+
+- anything under ``docs-internal/ARCHIVE/`` and any doc whose first lines
+ carry an ARCHIVED / HISTORICAL / Superseded banner -- those record the
+ past and are expected to name things that are gone;
+- paths containing ``<``, ``*`` or ``...`` (templates and globs);
+- the ``_ILLUSTRATIVE`` set (recipe placeholders such as ``acme_search``);
+- any line carrying ``docs-lint: ignore``.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+from cli.platform_ import project_root
+
+ROOT = project_root()
+DOCS = ROOT / "docs-internal"
+SEARCH_BASES = (ROOT, ROOT / "server", ROOT / "client", ROOT / "client" / "src")
+SKIP_DIRS = {"ARCHIVE", "design-system", "diagram-generation"}
+
+_BANNER = re.compile(r"ARCHIVED|HISTORICAL|Superseded", re.I)
+_PATH = re.compile(
+ r"`((?:server|client|cli|scripts|docs-internal|services|nodes|core|routers|src|"
+ r"components|hooks|models|middleware|tests|config|skills|lib|store|stores|utils|"
+ r"types|contexts|assets)/[A-Za-z0-9_./-]+"
+ r"\.(?:py|ts|tsx|js|json|md|css|svg|toml|yml|yaml|html))`"
+)
+
+_ILLUSTRATIVE = {
+ "server/nodes/search/acme_search.py",
+ "server/nodes/search/acme_search/__init__.py",
+ "client/src/components/onboarding/steps/NewStep.tsx",
+}
+
+
+def _live_docs() -> list[Path]:
+ out: list[Path] = []
+ for path in sorted(DOCS.rglob("*.md")):
+ if SKIP_DIRS & set(path.relative_to(DOCS).parts):
+ continue
+ head = "\n".join(path.read_text(encoding="utf-8", errors="replace").splitlines()[:12])
+ if _BANNER.search(head):
+ continue
+ out.append(path)
+ return out
+
+
+def _resolves(rel: str) -> bool:
+ return any((base / rel).exists() for base in SEARCH_BASES)
+
+
[email protected]("doc", _live_docs(), ids=lambda p: p.relative_to(DOCS).as_posix())
+def test_backtick_paths_resolve(doc: Path) -> None:
+ dead: list[str] = []
+ for lineno, line in enumerate(doc.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
+ if "docs-lint: ignore" in line:
+ continue
+ for rel in _PATH.findall(line):
+ if rel in _ILLUSTRATIVE or "<" in rel or "*" in rel or "..." in rel:
+ continue
+ if "/dist/" in rel: # build output, exists only after a build
+ continue
+ if not _resolves(rel):
+ dead.append(f" line {lineno}: {rel}")
+ assert not dead, (
+ f"{doc.relative_to(ROOT).as_posix()} names paths that do not exist:\n"
+ + "\n".join(dead)
+ + "\nFix the citation, or mark the line with `docs-lint: ignore` if it is illustrative."
+ )
diff --git a/client/src/components/parameterPanel/InputSection.tsx b/client/src/components/parameterPanel/InputSection.tsx
index 8be380f2..56d423a2 100644
--- a/client/src/components/parameterPanel/InputSection.tsx
+++ b/client/src/components/parameterPanel/InputSection.tsx
@@ -24,7 +24,7 @@ import { resolveNodeDescription } from '../../lib/nodeSpec';
// Backend-driven node output schema lookup.
//
// Mirrors n8n's schemaPreview pattern (see
-// docs-internal/schema_source_of_truth_rfc.md): the shape shown in the
+// docs-internal/ARCHIVE/schema_source_of_truth_rfc.md): the shape shown in the
// drag-drop variable panel for a node that has not been executed yet
// comes from the backend's Pydantic model registry via the
// `get_node_output_schema` WS handler. Results are cached per node
diff --git a/client/src/hooks/__tests__/useApiKeys.test.ts b/client/src/hooks/__tests__/useApiKeys.test.ts
index 11f31b5a..3045c8b4 100644
--- a/client/src/hooks/__tests__/useApiKeys.test.ts
+++ b/client/src/hooks/__tests__/useApiKeys.test.ts
@@ -1,7 +1,7 @@
/**
* Tests for useApiKeys hook.
*
- * Locks in invariants 1, 6 from docs-internal/credentials_panel.md:
+ * Locks in invariants 1, 6 from docs-internal/ARCHIVE/credentials_panel.md:
* - validate/save/delete route to the correct WebSocket message types
* - Google Maps and Apify use dedicated validators (not generic validate_api_key)
* - Provider Defaults uses save_provider_defaults, NOT save_api_key
diff --git a/client/src/hooks/useOnboarding.ts b/client/src/hooks/useOnboarding.ts
index 18bf5f1a..fd7d93c5 100644
--- a/client/src/hooks/useOnboarding.ts
+++ b/client/src/hooks/useOnboarding.ts
@@ -12,7 +12,7 @@ export interface OnboardingState {
hasChecked: boolean;
}
-const DEFAULT_TOTAL_STEPS = 5;
+const DEFAULT_TOTAL_STEPS = 4;
/**
* Onboarding wizard state hook.
@@ -20,8 +20,8 @@ const DEFAULT_TOTAL_STEPS = 5;
* @param reopenTrigger - bump from SettingsPanel to replay the wizard.
* @param totalSteps - number of steps the wizard will render. Caller
* owns the step list (`STEPS.length` in OnboardingWizard); the hook
- * uses this only to detect last-step completion. Defaults to 5 for
- * backwards compatibility.
+ * uses this only to detect last-step completion. The default matches
+ * the shipped wizard so a caller that omits it still completes.
*/
export const useOnboarding = (
reopenTrigger?: number,
diff --git a/client/src/test/README.md b/client/src/test/README.md
index edbf8348..192926e8 100644
--- a/client/src/test/README.md
+++ b/client/src/test/README.md
@@ -1,6 +1,6 @@
# Frontend Test Suite
-Locks in the user-facing invariants from [docs-internal/credentials_panel.md §5](../../../docs-internal/credentials_panel.md).
+Locks in the user-facing invariants from [docs-internal/ARCHIVE/credentials_panel.md §5](../../../docs-internal/ARCHIVE/credentials_panel.md).
## Run
diff --git a/client/src/test/nodeDefinitionContract.ts b/client/src/test/nodeDefinitionContract.ts
index de77af89..3e60fa39 100644
--- a/client/src/test/nodeDefinitionContract.ts
+++ b/client/src/test/nodeDefinitionContract.ts
@@ -30,7 +30,7 @@ export interface ContractIssue {
// services/node_spec.get_node_spec). The frontend type declares it as
// ``icon?: string`` — do NOT add ``icon`` back to this required list;
// the source of truth is the backend. See
-// docs-internal/schema_source_of_truth_rfc.md.
+// docs-internal/ARCHIVE/schema_source_of_truth_rfc.md.
const REQUIRED_TOP_LEVEL: (keyof INodeTypeDescription)[] = [
'displayName',
'name',
diff --git a/client/src/types/INodeProperties.ts b/client/src/types/INodeProperties.ts
index dafced16..a0fb59c3 100644
--- a/client/src/types/INodeProperties.ts
+++ b/client/src/types/INodeProperties.ts
@@ -308,7 +308,7 @@ export interface INodeTypeDescription {
// NOTE: runtime output shape is no longer declared on the frontend. It is
// served lazy by the backend at GET /api/schemas/nodes/{nodeType}.json and
// consumed by InputSection via useNodeOutputSchemaQuery. See
- // docs-internal/schema_source_of_truth_rfc.md.
+ // docs-internal/ARCHIVE/schema_source_of_truth_rfc.md.
}
// Node type interface that nodes must implement
diff --git a/docs-internal/ROADMAP.md b/docs-internal/ARCHIVE/ROADMAP.md
similarity index 98%
rename from docs-internal/ROADMAP.md
rename to docs-internal/ARCHIVE/ROADMAP.md
index 16795e62..a621a402 100644
--- a/docs-internal/ROADMAP.md
+++ b/docs-internal/ARCHIVE/ROADMAP.md
@@ -1,5 +1,12 @@
# Execution Engine Roadmap
+> **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.
+>
+> For current state see:
+>
+> - [DESIGN.md](../DESIGN.md) — execution engine
+> - [TEMPORAL_ARCHITECTURE.md](../TEMPORAL_ARCHITECTURE.md) and [temporal-workflow-control.md](../temporal-workflow-control.md)
+
## Overview
This 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.
diff --git a/docs-internal/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md b/docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md
similarity index 97%
rename from docs-internal/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md
rename to docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md
index c2bedcd8..3fff9700 100644
--- a/docs-internal/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md
+++ b/docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md
@@ -1,5 +1,11 @@
# RFC: Temporal Cleanup, Queue Routing, Resilience & Performance (Waves 15-18)
+> **ARCHIVED 2026-09-04 — Superseded.** Waves 15–18 shipped. One recorded outcome was later reverted: the 17.2 one-shot `LLM_STEP_RETRY` (`maximum_attempts=1`) killed whole runs on a single 429 and is now unlimited with backoff (`services/temporal/_retry_policies.py`). `get_backend_mode` in `event_waiter.py` was kept deliberately rather than deleted. The Temporal Web UI port is `TEMPORAL_UI_PORT`, not 8233.
+>
+> For current state see:
+>
+> - [TEMPORAL_ARCHITECTURE.md](../TEMPORAL_ARCHITECTURE.md) — current worker pool, retry and resilience settings
+
> **Historical implementation plan.** This document records the Waves 15-18
> migration and retains names that must remain replay-compatible. The current
> execution and control architecture is specified in
diff --git a/docs-internal/autonomous_agent_creation.md b/docs-internal/ARCHIVE/autonomous_agent_creation.md
similarity index 97%
rename from docs-internal/autonomous_agent_creation.md
rename to docs-internal/ARCHIVE/autonomous_agent_creation.md
index 967cd98d..3cc0e9ae 100644
--- a/docs-internal/autonomous_agent_creation.md
+++ b/docs-internal/ARCHIVE/autonomous_agent_creation.md
@@ -1,5 +1,12 @@
# Autonomous Agent Creation: A Comprehensive Guide
+> **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.
+>
+> For current state see:
+>
+> - [server/nodes/agent/autonomous_agent/](../../server/nodes/agent/autonomous_agent/) — the real plugin
+> - [node-logic-flows/specialized_agents/autonomous_agent.md](../node-logic-flows/specialized_agents/autonomous_agent.md) — its card
+
## Introduction
This 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.
diff --git a/docs-internal/claude_code_agent_architecture.md b/docs-internal/ARCHIVE/claude_code_agent_architecture.md
similarity index 99%
rename from docs-internal/claude_code_agent_architecture.md
rename to docs-internal/ARCHIVE/claude_code_agent_architecture.md
index 98f23ebc..292915f3 100644
--- a/docs-internal/claude_code_agent_architecture.md
+++ b/docs-internal/ARCHIVE/claude_code_agent_architecture.md
@@ -1,5 +1,13 @@
# Claude Code Agent Architecture
+> **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.
+>
+> For current state see:
+>
+> - [claude_code_interactive_mode.md](../claude_code_interactive_mode.md) — the shipped stdio protocol
+> - [cli_agent_framework.md](../cli_agent_framework.md) — the generic runtime
+> - [claude_code_agent.md](../claude_code_agent.md) — documentation hub
+
> **Current implementation note:** The production `claude_code_agent` is an
> interactive Claude Code CLI/PTY integration implemented under
> `server/nodes/agent/claude_code_agent/`. It does not use LangGraph or
diff --git a/docs-internal/credentials_panel.md b/docs-internal/ARCHIVE/credentials_panel.md
similarity index 97%
rename from docs-internal/credentials_panel.md
rename to docs-internal/ARCHIVE/credentials_panel.md
index 69b20761..15b6e48b 100644
--- a/docs-internal/credentials_panel.md
+++ b/docs-internal/ARCHIVE/credentials_panel.md
@@ -1,5 +1,13 @@
# Credentials Panel — Logic Flow Documentation
+> **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/`.
+>
+> For current state see:
+>
+> - [frontend_architecture.md → Credentials](../frontend_architecture.md) — config-driven `ProviderConfig` + `useCredentialPanel` model
+> - [credentials_encryption.md](../credentials_encryption.md) — storage pipeline
+> - [client/src/components/credentials/](../../client/src/components/credentials/) — the live modal
+
> Reference for refactoring [client/src/components/CredentialsModal.tsx](../client/src/components/CredentialsModal.tsx) (~3000 lines).
> Every claim here cites file + line number so reviewers can validate post-refactor.
> 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.
diff --git a/docs-internal/litellm_router_migration_rfc.md b/docs-internal/ARCHIVE/litellm_router_migration_rfc.md
similarity index 99%
rename from docs-internal/litellm_router_migration_rfc.md
rename to docs-internal/ARCHIVE/litellm_router_migration_rfc.md
index 25f964f1..12400c3b 100644
--- a/docs-internal/litellm_router_migration_rfc.md
+++ b/docs-internal/ARCHIVE/litellm_router_migration_rfc.md
@@ -1,5 +1,11 @@
# LiteLLM Router Migration RFC
+> **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.
+>
+> For current state see:
+>
+> - [native_llm_sdk.md](../native_llm_sdk.md) — the layer that shipped
+
**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`
> Historical RFC only. The adopted implementation uses provider-native SDKs,
diff --git a/docs-internal/memory_lifecycle.md b/docs-internal/ARCHIVE/memory_lifecycle.md
similarity index 95%
rename from docs-internal/memory_lifecycle.md
rename to docs-internal/ARCHIVE/memory_lifecycle.md
index 807b6aea..4671a203 100644
--- a/docs-internal/memory_lifecycle.md
+++ b/docs-internal/ARCHIVE/memory_lifecycle.md
@@ -1,5 +1,13 @@
# Memory Lifecycle
+> **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.
+>
+> For current state see:
+>
+> - [agent_context_flow.md](../agent_context_flow.md) and [RFC-0002](../../RFC-0002-AGENT-CONTEXT-AND-MEMORY.md) — conversation store
+> - [memory_compaction.md](../memory_compaction.md) — token tracking and compaction
+> - [cli_agent_framework.md → Memory bridge](../cli_agent_framework.md) — claude session continuity
+
> ## ⚠ Partly superseded by RFC-0002
>
> This document describes the pre-RFC-0002 model, in which `simpleMemory` hung
diff --git a/docs-internal/new_service_integration.md b/docs-internal/ARCHIVE/new_service_integration.md
similarity index 98%
rename from docs-internal/new_service_integration.md
rename to docs-internal/ARCHIVE/new_service_integration.md
index 730ed620..499b844d 100644
--- a/docs-internal/new_service_integration.md
+++ b/docs-internal/ARCHIVE/new_service_integration.md
@@ -1,5 +1,13 @@
# New Service Integration Guide
+> **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.
+>
+> For current state see:
+>
+> - [node_creation.md](../node_creation.md) — decision tree
+> - [plugin_system.md](../plugin_system.md) — full reference
+> - [server/nodes/README.md](../../server/nodes/README.md) — 5-minute recipe
+
> **⚠️ HISTORICAL — do not follow these steps.** This guide predates
> Wave 11 and is preserved only as background for reading old code.
>
diff --git a/docs-internal/schema_source_of_truth_rfc.md b/docs-internal/ARCHIVE/schema_source_of_truth_rfc.md
similarity index 98%
rename from docs-internal/schema_source_of_truth_rfc.md
rename to docs-internal/ARCHIVE/schema_source_of_truth_rfc.md
index f48b6e15..024fe924 100644
--- a/docs-internal/schema_source_of_truth_rfc.md
+++ b/docs-internal/ARCHIVE/schema_source_of_truth_rfc.md
@@ -1,5 +1,12 @@
# Schema source of truth — RFC
+> **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.
+>
+> For current state see:
+>
+> - [plugin_system.md](../plugin_system.md) — NodeSpec, registries, credentials
+> - [server/nodes/README.md](../../server/nodes/README.md) — authoring recipe
+
**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)
## Landed outcome (Wave 3 — output schemas)
diff --git a/docs-internal/server-readme.md b/docs-internal/ARCHIVE/server-readme.md
similarity index 90%
rename from docs-internal/server-readme.md
rename to docs-internal/ARCHIVE/server-readme.md
index 13c428c7..3760b5a8 100644
--- a/docs-internal/server-readme.md
+++ b/docs-internal/ARCHIVE/server-readme.md
@@ -1,5 +1,14 @@
# Python Backend - Environment Setup
+> **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.
+>
+> For current state see:
+>
+> - [SETUP.md](../SETUP.md) — environment and first run
+> - [authentication.md](../authentication.md) and [credentials_encryption.md](../credentials_encryption.md)
+> - [plugin_system.md](../plugin_system.md) — backend architecture
+> - [CLAUDE.md](../../CLAUDE.md) — the live index
+
## Quick Start
1. Copy the template to create your .env file:
diff --git a/docs-internal/temporal-execution-engine-rfc.md b/docs-internal/ARCHIVE/temporal-execution-engine-rfc.md
similarity index 98%
rename from docs-internal/temporal-execution-engine-rfc.md
rename to docs-internal/ARCHIVE/temporal-execution-engine-rfc.md
index f3c1e471..338c1d05 100644
--- a/docs-internal/temporal-execution-engine-rfc.md
+++ b/docs-internal/ARCHIVE/temporal-execution-engine-rfc.md
@@ -1,5 +1,12 @@
# RFC: Temporal Execution Engine Architecture
+> **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.
+>
+> For current state see:
+>
+> - [temporal-workflow-control.md](../temporal-workflow-control.md) — control plane as shipped
+> - [TEMPORAL_ARCHITECTURE.md](../TEMPORAL_ARCHITECTURE.md) — dispatch paths and activities
+
| Field | Value |
|---|---|
| Status | Implemented; canonical current-state design |
diff --git a/docs-internal/ui_migration_plan.md b/docs-internal/ARCHIVE/ui_migration_plan.md
similarity index 99%
rename from docs-internal/ui_migration_plan.md
rename to docs-internal/ARCHIVE/ui_migration_plan.md
index 18d527ce..1eea2f9a 100644
--- a/docs-internal/ui_migration_plan.md
+++ b/docs-internal/ARCHIVE/ui_migration_plan.md
@@ -1,5 +1,12 @@
# Frontend UI Stack Migration — antd → shadcn/ui (canonical, no custom wrappers)
+> **ARCHIVED 2026-09-04 — Superseded.** The antd → shadcn migration completion log. Waves 1–10 shipped; the `get_node_spec` blocker it names for Phase 6 no longer exists, and the design system grew to 12 themes. `pnpm` commands in the per-wave records are pre-bun-migration.
+>
+> For current state see:
+>
+> - [frontend_architecture.md](../frontend_architecture.md) — current stack
+> - [theme_system.md](../theme_system.md) — 12-theme system
+
> **Status (2026-05-08):** Phases 0–5 + 7 **complete**. Phase 6 (`ParameterRenderer` → JSON Forms) deferred pending backend `NodeSpec` handler. Zero antd / `@ant-design/icons` / styled-components imports remain. Wave 12 retired the surviving tribal patterns (string-compares, opacity arithmetic, whole-store destructure). Wave 13 unified credential storage on a single source of truth + RFC 9700 / OWASP V9.9 compliance. **Wave 14** (May 2026) lit up the 10-theme design system end-to-end (chrome migration, decorative wrappers, sound packs, canvas overlays). Current state lives in [frontend_architecture.md](./frontend_architecture.md) and [theme_system.md](./theme_system.md) — those docs supersede this plan as the source of truth for what the frontend IS; this doc documents how we got there.
## Completion table
diff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.md
index 859c0401..b03019a3 100644
--- a/docs-internal/DESIGN.md
+++ b/docs-internal/DESIGN.md
@@ -21,7 +21,7 @@ Related docs:
## Execution Modes
-`WorkflowService` in `server/services/workflow.py` is a thin facade (~460 lines) that routes every workflow run based on available infrastructure. In every shipped configuration the effective routing is Temporal -> sequential:
+`WorkflowService` in `server/services/workflow.py` is a thin facade (~840 lines) that routes every workflow run based on available infrastructure. In every shipped configuration the effective routing is Temporal -> sequential:
```
workflow.execute(workflow_id, workflow_data)
@@ -42,7 +42,7 @@ workflow.execute(workflow_id, workflow_data)
When `TEMPORAL_ENABLED=true` and the Temporal server is reachable, every workflow node executes through Temporal. Three dispatch paths coexist (legacy `execute_node_activity` / per-type `node.{type}.v{version}` / Agent-as-child-workflow `AgentWorkflow`) gated by `TEMPORAL_PER_TYPE_DISPATCH` and `TEMPORAL_AGENT_WORKFLOW_ENABLED` flags. Per-node retries, per-node timeouts, horizontal scaling via worker pool, and the FIRST_COMPLETED orchestrator pattern.
-Full dispatch matrix + activity inventory (legacy + per-type + the 5 F4.B agent activities) + worker configuration + heartbeat semantics live in [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md). Tool-call dispatch under F4.A: [tool_building_pipeline.md §9](./tool_building_pipeline.md).
+Full dispatch matrix + activity inventory (legacy + per-type + the F4.B `agent.*` activities — read the live set from `collect_agent_activities()` in `services/temporal/agent_activities.py`) + worker configuration + heartbeat semantics live in [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md). Tool-call dispatch under F4.A: [tool_building_pipeline.md §9](./tool_building_pipeline.md).
### 2. Sequential Fallback
@@ -54,7 +54,7 @@ When Temporal is not available, workflow execution falls back to a simple topolo
- Conductor's decide pattern in `_workflow_decide()` under distributed Redis SETNX locks
- Continuous scheduling via `asyncio.wait(FIRST_COMPLETED)` (`_execute_with_continuous_scheduling` — the only scheduling implementation; the legacy Fork/Join `_execute_parallel_nodes` helper was removed)
-- Prefect-style result caching keyed by `hash_inputs()` (see `services/execution/cache.py`)
+- Prefect-style result caching keyed by `hash_inputs()` (defined in `services/execution/models.py`; the cache read/write lives in `services/execution/cache.py`)
- Crash recovery via `RecoverySweeper` with heartbeats
- Dead Letter Queue for failed nodes (`services/execution/dlq.py`)
@@ -464,25 +464,23 @@ class ExecutionContext:
nodes: List[Dict] # Node definitions
edges: List[Dict] # Edge definitions
- # Workspace (per-workflow filesystem for nodes and agents)
- workspace_dir: str # Absolute path to <DATA_DIR>/workspaces/<workflow_slug>/
- # (Wave 14 — keyed by the human-readable slug,
- # not the UUID id; see CLAUDE.md "Workflow Naming")
-
# Execution Progress
- execution_order: List[List[str]] # Computed layers
+ execution_order: List[str] # Topological order (flat list)
current_layer: int # Current layer index
checkpoints: List[str] # Completed node IDs
# Timing
- started_at: float
- completed_at: float
+ created_at: float
updated_at: float
+ started_at: Optional[float]
+ completed_at: Optional[float]
# Errors
errors: List[Dict] # Error records
```
+The per-workflow workspace directory (`<DATA_DIR>/workspaces/<workflow_slug>/`, Wave 14 — keyed by the human-readable slug, not the UUID id; see CLAUDE.md "Workflow Naming") is **not** a field on `ExecutionContext`. `WorkflowService` resolves it and injects `workspace_dir` into the execution context dict that node handlers receive (`services/workflow.py`).
+
### NodeExecution
```python
@@ -628,11 +626,13 @@ _deployment_settings = {
### Execution Toggle
```python
-# Automatic fallback
-if use_parallel and settings.redis_enabled:
- return await self._execute_workflow_parallel(...)
-else:
- return await self._execute_workflow_sequential(...)
+# services/workflow.py — Temporal first, then the (unreachable) Redis branch, then sequential
+if use_temporal and self._temporal_executor is not None:
+ return await self._execute_temporal(...)
+# use_temporal with no executor logs an ERROR (silent fallthrough looked like success)
+if use_parallel and self.settings.redis_enabled:
+ return await self._execute_parallel(...)
+return await self._execute_sequential(...)
```
---
@@ -655,7 +655,7 @@ else:
### Runtime Conditional Branching (conditions.py)
Edge conditions are evaluated at runtime using Prefect-style dynamic branching:
-- 20+ operators: eq, neq, gt, lt, gte, lte, contains, exists, matches, in, starts_with, etc.
+- 19 operators (the `OPERATORS` table in `conditions.py`): eq, neq, gt, lt, gte, lte, contains, not_contains, exists, not_exists, is_empty, is_not_empty, matches, in, not_in, starts_with, ends_with, is_true, is_false
- Supports nested field access via dot notation (e.g., `result.status`)
- AND/OR condition groups with recursive evaluation
@@ -663,11 +663,11 @@ Edge conditions are evaluated at runtime using Prefect-style dynamic branching:
Failed nodes (after all retries exhausted) are stored for inspection and replay:
- `DLQHandler` - Active handler storing failed nodes with full context
- `NullDLQHandler` - No-op handler when DLQ disabled (Null Object pattern)
-- WebSocket handlers: `get_dlq_entries`, `replay_dlq_entry`, `remove_dlq_entry`, `get_dlq_stats`
+- WebSocket handlers: `get_dlq_entries`, `get_dlq_entry`, `replay_dlq_entry`, `remove_dlq_entry`, `purge_dlq`, `get_dlq_stats`
### Temporal Distributed Execution (Optional)
When `TEMPORAL_ENABLED=true`, each node executes as an independent Temporal activity:
-- Per-node retry (3 attempts) and timeout (10 min default)
+- Per-node retry (3 attempts by default; plugin `retry_policy` wins) and a 24 h `start_to_close` ceiling (`_NODE_ACTIVITY_START_TO_CLOSE`); liveness is the 30 s heartbeat against a 2 min `heartbeat_timeout`
- Horizontal scaling across worker pool
- FIRST_COMPLETED pattern for dependency resolution
- Connection pooling for WebSocket activity execution
diff --git a/docs-internal/SCRIPTS.md b/docs-internal/SCRIPTS.md
index cc65ccda..0d559f31 100644
--- a/docs-internal/SCRIPTS.md
+++ b/docs-internal/SCRIPTS.md
@@ -7,11 +7,13 @@ npm install -g @zeenie-ai/opencompany
company start
```
-Open http://localhost:5678
+Open the app URL — `http://localhost:${PYTHON_BACKEND_PORT}` (the port
+is declared once in `.env.template`; see [SETUP.md](./SETUP.md) for the
+default).
## CLI Commands (`company`, Python Typer app under `cli/`)
-The CLI is the single orchestration surface — every `npm run <verb>` at
+The CLI is the single orchestration surface — every `bun run <verb>` at
the root is a thin wrapper over `python -m cli <verb>`. The old
`scripts/{start,stop,build,clean,docker}.js` orchestrators were retired
(each `cli/commands/<verb>.py` docstring records what it replaced).
@@ -20,7 +22,7 @@ deprecation warning; kept for upgrade compatibility).
| Command | Description |
|---------|-------------|
-| `company start` | Production mode, single port: uvicorn serves API + WS + built SPA on :5678. Optional daemons (Temporal dev server, WhatsApp) are backend-owned, started from the lifespan when enabled |
+| `company start` | Production mode, single port: uvicorn serves API + WS + built SPA on `PYTHON_BACKEND_PORT`. Optional daemons (Temporal dev server, WhatsApp) are backend-owned, started from the lifespan when enabled |
| `company dev` | Start in dev mode (Vite HMR + uvicorn). `--force` re-bundles Vite deps (recovers "Outdated Optimize Dep"); `--daemon` binds backend to 0.0.0.0 |
| `company serve` | Single-port production runtime (uvicorn serves API + WS + built SPA; optional daemons incl. the Node.js executor are backend-spawned on demand) — the systemd `ExecStart` on deployed VMs |
| `company stop` | Stop all services and free configured ports |
@@ -30,7 +32,9 @@ deprecation warning; kept for upgrade compatibility).
| `company daemon start/stop/status/restart` | Detached backend management (PID file under user data dir) |
| `company version sync` | Propagate the root package.json version |
| `company docs nodes [--check]` | Regenerate (or verify) the `docs-internal/node-logic-flows/` index |
-| `company help` | Show help |
+
+There is no `help` verb: `company` with no arguments, `company --help`, and
+`company <verb> --help` print Typer's help (`no_args_is_help=True` in `cli/cli.py`).
### Dependency checks
@@ -39,10 +43,15 @@ running.
---
-## npm Scripts
+## package.json scripts (run with bun)
-Run with `npm run <script>` from the project root (`package.json` is
-the source of truth).
+Run with `bun run <script>` from the project root (`package.json` is
+the source of truth). The dev package manager is [email protected] —
+`scripts/preinstall.js` rejects `npm install` in a source checkout.
+The commands below are quoted verbatim from `package.json`; two of them
+(`client:start`, `test:frontend`) still spell `npm run` internally
+because they invoke another package's script, which bun executes on
+Node either way (recorded follow-up).
### CLI wrappers
@@ -59,8 +68,8 @@ the source of truth).
| Script | Command | Description |
|--------|---------|-------------|
| `client:start` | `cd client && npm run start` | React frontend (Vite dev server) |
-| `python:start` | `cd server && uv run uvicorn main:app --host 127.0.0.1 --port 5678 ...` | Backend only |
-| `python:daemon` | same, bound to `0.0.0.0` | Backend only, LAN-reachable |
+| `python:start` | `cd server && uv run python main.py` | Backend only (`main.py` reads `HOST` / `PYTHON_BACKEND_PORT` from the env) |
+| `python:daemon` | `cd server && cross-env HOST=0.0.0.0 uv run python main.py` | Backend only, LAN-reachable |
| `temporal:worker` | `cd server && uv run python -m services.temporal.worker` | Standalone Temporal worker |
The Temporal dev server is backend-owned: the FastAPI lifespan starts it via `TemporalServerRuntime.ensure_started()` when `TEMPORAL_ENABLED` (see [Temporal Architecture](./TEMPORAL_ARCHITECTURE.md)). The official `temporal` CLI is downloaded by `pooch` to `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default) during `company build`.
@@ -87,7 +96,7 @@ The Temporal dev server is backend-owned: the FastAPI lifespan starts it via `Te
| File | Purpose |
|------|---------|
-| `install.js` | npm-tarball install pipeline (npm/uv install for end users — dev workspaces use bun; client + sidecar build, bytecode compile, temporal binary fetch) — mirrors `company build`; the compileall command shape is locked in sync by `cli/tests/test_release_pipeline_config.py` |
+| `install.js` | npm-tarball install pipeline (npm/uv install for end users — dev workspaces use bun; client build only when `client/dist` is missing from the tarball, `uv sync`, bytecode compile, CLI runtime venv, non-fatal Temporal binary fetch; the Node.js sidecar `dist/index.js` ships pre-built in the tarball) — mirrors `company build`; the compileall command shape is locked in sync by `cli/tests/test_release_pipeline_config.py` |
| `preinstall.js` | Legacy-package/temp cleanup (also runs on uninstall) |
| `postinstall.js` | npm lifecycle entry that guards recursion and invokes install.js |
| `migrate_icons.py`, `migrate_skill_icons.py` | One-off icon-migration utilities (historical) |
@@ -109,11 +118,14 @@ Key variables in `.env` (see `.env.template` for the full list):
### Ports
| Variable | Default | Description |
|----------|---------|-------------|
-| `VITE_CLIENT_PORT` | 5678 | App port (Vite dev server; proxies backend prefixes) |
-| `PYTHON_BACKEND_PORT` | 5678 | Backend port (5679 in dev via `.env.dev`, behind the Vite proxy) |
-| `WHATSAPP_RPC_PORT` | 5683 | WhatsApp API port |
-| `NODEJS_EXECUTOR_PORT` | 5682 | Node.js code-executor sidecar |
-| — | 5681 / 5680 | Temporal gRPC / Temporal Web UI |
+| `VITE_CLIENT_PORT` | `.env.template` | App port (Vite dev server; proxies backend prefixes). Equal to `PYTHON_BACKEND_PORT` in production |
+| `PYTHON_BACKEND_PORT` | `.env.template` | Backend port (`.env.dev` moves it one up in dev, behind the Vite proxy) |
+| `WHATSAPP_RPC_PORT` | `.env.template` | WhatsApp API port (plugin-owned) |
+| `NODEJS_EXECUTOR_PORT` | `.env.template` | Node.js code-executor sidecar (plugin-owned) |
+| `TEMPORAL_FRONTEND_GRPC_PORT` / `TEMPORAL_UI_PORT` | `.env.template` | Temporal gRPC / Temporal Web UI |
+
+All values live in the serial block declared at the top of `.env.template`; no
+code or doc should carry the numerals.
### Features
| Variable | Default | Description |
@@ -138,9 +150,9 @@ Key variables in `.env` (see `.env.template` for the full list):
```bash
# Development
-company dev # app at :5678 (Vite HMR; backend :5679 behind the proxy)
+company dev # app at PYTHON_BACKEND_PORT (Vite HMR; backend one port up via .env.dev, behind the proxy)
company dev --force # ...forcing a Vite dependency re-bundle
-company start # Production mode (single port :5678)
+company start # Production mode (single port: PYTHON_BACKEND_PORT)
company stop # Stop all services
# Build / clean
diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.md
index 00d396bc..34b2d066 100644
--- a/docs-internal/SETUP.md
+++ b/docs-internal/SETUP.md
@@ -4,18 +4,19 @@
```
OpenCompany/
-├── client/ # React frontend (Vite dev server on :5678, proxying the backend; production build served by uvicorn on :5678)
+├── client/ # React frontend (Vite dev server on VITE_CLIENT_PORT, proxying the backend; production build served by uvicorn on PYTHON_BACKEND_PORT)
│ ├── src/
│ └── package.json
-├── server/ # Python FastAPI backend (port 5678)
+├── server/ # Python FastAPI backend (port PYTHON_BACKEND_PORT)
│ ├── services/ # Business logic (workflow, AI, etc.)
│ ├── routers/ # API endpoints
│ ├── core/ # DI container, database, cache
│ ├── models/ # SQLModel definitions
-│ ├── whatsapp-rpc/ # Go WhatsApp service (port 5683)
+│ ├── nodes/ # Plugin folders (one per node; the WhatsApp bridge is the
+│ │ # `edgymeow` npm package installed under DATA_DIR/packages/, not in-tree)
│ └── requirements.txt
-├── scripts/ # Build and utility scripts
-└── package.json # Workspace root with npm scripts
+├── scripts/ # npm-tarball install lifecycle helpers (install/preinstall/postinstall)
+└── package.json # Workspace root; [email protected] scripts wrapping `python -m cli`
```
## Quick Start
@@ -49,22 +50,22 @@ the embedding node and long-term memory, install the optional extra:
cd server && uv sync --extra local-embeddings
```
-Services (production `company start`):
-- **App (API + WS + SPA)**: http://localhost:5678
-- **WhatsApp Service**: http://localhost:5683 (backend-spawned on demand)
-- **Temporal dev server**: gRPC :5681, Web UI :5680 (backend-spawned when `TEMPORAL_ENABLED`)
+Services (production `company start`; every port is declared once in `.env.template`):
+- **App (API + WS + SPA)**: `http://localhost:${PYTHON_BACKEND_PORT}`
+- **WhatsApp Service**: `WHATSAPP_RPC_PORT` (backend-spawned on demand)
+- **Temporal dev server**: gRPC `TEMPORAL_FRONTEND_GRPC_PORT`, Web UI `TEMPORAL_UI_PORT` (backend-spawned when `TEMPORAL_ENABLED`)
-`company dev` serves the same URL (http://localhost:5678) from the Vite HMR server, which proxies /api /ws /webhook to the backend on :5679.
+`company dev` serves the same app URL from the Vite HMR server, which proxies /api /ws /webhook /health /mcp to the backend; `.env.dev` moves the backend one port up (`PYTHON_BACKEND_PORT` override) so the app URL stays put.
## Services Overview
-### Frontend (React — always at :5678; Vite dev server proxying the backend, or the production build served by uvicorn)
+### Frontend (React — always at the app port; Vite dev server proxying the backend, or the production build served by uvicorn)
- React 19 with TypeScript
- React Flow for workflow canvas
- Zustand for state management
- WebSocket connection to backend
-### Backend (Python FastAPI - Port 5678)
+### Backend (Python FastAPI - `PYTHON_BACKEND_PORT`)
- FastAPI with async support
- SQLAlchemy + SQLite database
- Native Anthropic and Google Gen AI providers plus the OpenAI SDK for OpenAI-compatible chat through `ChatUnifier`; Ollama's SDK is used for local model discovery and embeddings
@@ -74,8 +75,8 @@ Services (production `company start`):
- `GET /health` - Health check
- `WS /ws/status` - Real-time status WebSocket
- `ANY /webhook/{path}` - Dynamic webhook endpoints
-- `POST /api/ai/*` - AI model execution
-- `POST /api/android/*` - Android device operations
+- `/api/android/*` - Android device operations (plugin router in `nodes/android/_router.py`)
+- AI model execution has no REST surface — it is WebSocket-only (`execute_ai_node`, `get_ai_models`, `execute_node`)
### WhatsApp Service (Go — optional, on-demand; port `WHATSAPP_RPC_PORT`)
- Go service using whatsmeow library
@@ -87,9 +88,9 @@ Services (production `company start`):
- Provides durable workflow execution with per-node retry and horizontal scaling
- Official `temporal` CLI downloaded by `pooch` from `https://temporal.download/cli/archive/latest` on `company build` (or first backend boot with Temporal enabled)
- Backend-owned: the FastAPI lifespan starts `temporal server start-dev` via `TemporalServerRuntime.ensure_started()` when `TEMPORAL_ENABLED` and the configured address is loopback (external clusters are detected via TCP probe and left alone) — SQLite at `~/.opencompany/temporal.db`
-- Ports: gRPC 5681, Web UI 5680
-- Embedded worker runs inside Python backend (`TemporalWorkerManager` in `main.py`)
-- Workflow auto-resumption disabled at startup (history preserved); see `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP`
+- Ports: gRPC `TEMPORAL_FRONTEND_GRPC_PORT`, Web UI `TEMPORAL_UI_PORT` (values in `.env.template`)
+- Embedded worker runs inside the Python backend (`TemporalWorkerManager` + `TemporalWorkerPool`, built by `services/temporal/lifecycle.py`; `main.py` only schedules `run_temporal_lifecycle`)
+- Running and paused deployments survive restarts: `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP=false` is the default, and the boot-time reconcile pass re-arms them. Setting it `true` is a debug-only sweep (history preserved; active control rows still veto it)
- See [Temporal Architecture](./TEMPORAL_ARCHITECTURE.md) and [CLI Services Guide](./cli_services_integration.md)
### Database (SQLite)
@@ -104,7 +105,7 @@ Services (production `company start`):
Copy the example environment file:
```bash
-cp .env.example .env
+cp .env.template .env
```
Alternatively, `company build` scaffolds `.env` from `.env.template` automatically when it is missing (step `[0/6]`) and generates fresh random secrets for `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` instead of the dev placeholders. An existing `.env` is never modified. If you copy the template by hand and later enable auth (or set `DEPLOYMENT_MODE` to anything other than `local`), the server logs a non-fatal error banner at startup until the placeholder secrets are replaced.
@@ -113,11 +114,11 @@ Alternatively, `company build` scaffolds `.env` from `.env.template` automatical
| Variable | Default | Description |
|----------|---------|-------------|
-| `VITE_CLIENT_PORT` | 5678 | App port (Vite dev server; proxies backend prefixes) |
-| `PYTHON_BACKEND_PORT` | 5678 | Backend port (5679 in dev via `.env.dev`, behind the Vite proxy) |
+| `VITE_CLIENT_PORT` | see `.env.template` | App port (Vite dev server; proxies backend prefixes). Same value as `PYTHON_BACKEND_PORT` in production |
+| `PYTHON_BACKEND_PORT` | see `.env.template` | Backend port (`.env.dev` moves it one up in dev, behind the Vite proxy) |
| `AUTH_MODE` | single | Authentication mode (single/multi) |
| `REDIS_ENABLED` | false | Enable Redis cache (production) |
-| `DEBUG` | true | Debug mode |
+| `DEBUG` | false | Debug mode |
### API Keys (Optional)
Add these to `.env` or configure via the Credentials UI:
@@ -148,7 +149,7 @@ When `VITE_AUTH_ENABLED=false` (the default):
|---------|-------------|
| `bun run start` | Start the app (backend-owned daemons start on demand) |
| `bun run stop` | Stop all services |
-| `bun run build` | Install dependencies |
+| `bun run build` | Full production build (`company build`: bun install, client, sidecar, uv sync, bytecode, Temporal binary) |
| `bun run dev` | Start development server |
## Troubleshooting
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index 9dcbfd83..27e81778 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -30,11 +30,13 @@ Each workflow node executes as a **Temporal activity** with its own isolated con
**Running with Temporal** — the Temporal server and the embedded worker start automatically with every launch script:
```bash
-npm run start # Starts the app; the backend lifespan starts the Temporal dev server when TEMPORAL_ENABLED
-npm run dev # Starts Temporal server + all services (dev mode)
-npm run stop # Stops all services including Temporal
+company start # Starts the app; the backend lifespan starts the Temporal dev server when TEMPORAL_ENABLED
+company dev # Starts Temporal server + all services (dev mode)
+company stop # Stops all services including Temporal
```
+(`bun run start` / `bun run dev` / `bun run stop` are thin wrappers over the same `company` verbs.)
+
The embedded Temporal worker runs **inside the Python backend** — registered in the `main.py` lifespan via `TemporalWorkerManager`, not as a separate process.
**Standalone worker** (for horizontal scaling — add more pollers against the same task queue):
@@ -49,7 +51,7 @@ This invokes `run_standalone_worker()` from `services/temporal/worker.py`.
## System Architecture
```
- TEMPORAL SERVER (port 5681)
+ TEMPORAL SERVER (port TEMPORAL_FRONTEND_GRPC_PORT)
|
Task Queue: machina-tasks (workflows + framework activities)
+---------------------------------------------------------------+
@@ -93,7 +95,7 @@ This invokes `run_standalone_worker()` from `services/temporal/worker.py`.
Each node runs as a separate Temporal activity with:
- **Own context** - No shared mutable state between nodes
- **Own retry policy** - Failed nodes retry independently (up to 3 attempts)
-- **Own timeout** - Long AI nodes don't block short nodes (10 min default)
+- **Own timeout** - Long AI nodes don't block short nodes (`_NODE_ACTIVITY_START_TO_CLOSE` = 24 h ceiling in `services/temporal/workflow.py`; liveness comes from the 2-minute heartbeat, not the start-to-close cap)
- **Own worker** - Can execute on any available worker in the cluster
### 2. Workflow = Pure Orchestrator
@@ -181,9 +183,13 @@ while True:
activity_name, activity_queue = self._resolve_activity(node_type)
start_kwargs = dict(
args=[context],
- start_to_close_timeout=timedelta(minutes=10),
+ activity_id=node_id,
+ # Heartbeat is the liveness mechanism; start_to_close only
+ # bounds a single legitimate step (24h; pre-patch histories
+ # replay against the old 10min cap).
+ start_to_close_timeout=_NODE_ACTIVITY_START_TO_CLOSE,
heartbeat_timeout=timedelta(minutes=2),
- retry_policy=retry_policy,
+ retry_policy=activity_retry_policy, # plugin cls.retry_policy wins when declared
)
if activity_queue is not None:
start_kwargs["task_queue"] = activity_queue
@@ -321,9 +327,9 @@ Env overrides: `TEMPORAL_<QUEUE>_CONCURRENCY` (int) and `TEMPORAL_<QUEUE>_RATE_L
- **Resource-based slot supplier** (Wave 18.4): `ai-heavy` + `browser` (unpredictable workloads) use `ResourceBasedSlotSupplier` targeting 80% host CPU + memory, `minimum_slots=1`, `maximum_slots` = the per-queue concurrency. Requires `temporalio>=1.25.0` (pinned).
- **SDK tracing interceptor ownership**: `TracingInterceptor` is registered exactly once on the shared `Client.connect(...)`. The Temporal Python SDK automatically prepends compatible client interceptors to every `Worker` built from that client. Worker constructors must not repeat `TracingInterceptor`; doing so creates paired OpenTelemetry spans for one execution.
- **Application observability interceptor** (Wave 17.3, `services/temporal/_interceptors.py`): workers explicitly register `ObservabilityWorkerInterceptor` for `activity_retry` WARN logs when `activity.info().attempt > 1` — the "worker died and Temporal re-dispatched" signal — and replay-guarded `workflow_start` logs. This is separate from SDK tracing and remains worker-owned.
-- **Periodic activity heartbeat** (Wave 17.6, `plugin/base.py::as_activity`): 30s background beat during long bodies so a laptop-sleep crash is detected within one `heartbeat_timeout` (2 min) instead of `start_to_close` (10 min).
+- **Periodic activity heartbeat** (Wave 17.6, `plugin/base.py::as_activity`): 30s background beat during long bodies so a laptop-sleep crash is detected within one `heartbeat_timeout` (2 min) instead of `start_to_close` (24 h).
- **Cron catch-up bound** (Wave 17.1, `services/temporal/schedules.py`): `SchedulePolicy(catchup_window=24h)` + `SKIP` overlap — a laptop offline a week does not replay 168 hourly ticks on wake.
-- **One-shot LLM-step retry** (Wave 17.2): `LLM_STEP_RETRY(maximum_attempts=1)` on `agent.execute_llm_step` — LLM calls are not idempotent; the workflow surfaces the failure instead of silently re-billing the prompt. `agent.refresh_tools` deliberately keeps 3 attempts (idempotent canvas rebuild).
+- **LLM-step retry** (Wave 17.2, since reverted): `LLM_STEP_RETRY` on `agent.execute_llm_step` is now **unlimited** (`maximum_attempts=0`, 5 s → 5 min exponential backoff) — see the docstring in `services/temporal/_retry_policies.py`. The one-shot policy Wave 17.2 shipped meant one transient provider error killed a months-long deployment and tripped the circuit breaker; terminal outcomes still fail fast because `_as_temporal_llm_error` marks non-retryable categories (invalid_request, authentication, ...) with `non_retryable=True`, and provider `retry_after` hints ride `ApplicationError.next_retry_delay`. Accepted trade-off: an ambiguous loss can re-bill a prompt. `agent.refresh_tools` keeps the 3-attempt default (idempotent canvas rebuild).
**Metric watchlist** (Temporal Web UI / metrics endpoint): `schedule_to_start_latency` (elevated = raise pollers or slots), `worker_task_slots_available` (0 = raise concurrency or add hosts), `poll_success_rate` (target >= 90%), `sticky_cache_evictions` (persistent growth = raise `max_cached_workflows`).
@@ -390,19 +396,19 @@ AgentWorkflow.run(context):
yielding fresh AgentToolSpec / ToolDef declarations.
tools.extend(refresh_result["tools"])
tool_index.update(...)
- # next execute_llm_step.v1 sees the new tools.
+ # next execute_llm_step sees the new tools.
5. execute_activity("agent.persist_turn")
append_to_memory_markdown(content, "human", prompt) +
(content, "ai", response); trim window; broadcast
node_parameters_updated CloudEvents (source_hint="agent").
6. if token_total >= compaction_threshold:
- execute_activity("agent.compact_memory")
+ execute_activity("agent.compact_context")
null-guarded against worker-bootstrap race; replaces messages
with summary only when result.success is True.
execute_activity("agent.store_output")
wraps workflow_service.store_node_output for output_main /
output_top / output_0 — same writes NodeExecutor.execute does
- at services/node_executor.py:197-199, so downstream nodes
+ at services/node_executor.py:198-200, so downstream nodes
can resolve {{aiAgent.response}} via ParameterResolver.
emit_phase("completed", status="success")
```
@@ -439,18 +445,19 @@ addition. Seven are the core loop activities:
| `agent.execute_llm_step` | One LLM turn. The native branch decodes Message Wire V2, rebuilds `ToolDef` values, calls `run_native_llm_step(ChatUnifier, ...)` with SDK retries disabled, heartbeats while awaiting the provider, and returns the exact assistant message + tool calls + normalized usage. Guards against un-invokable payloads: post-filter system-only message lists raise `ApplicationError(type="EmptyAgentPrompt", non_retryable=True)`. |
| `agent.refresh_tools` | Translates `workflow_ops` add_node ops (`component_kind="tool"` OR `usable_as_tool=True`) into fresh `AgentToolSpec`-derived `tool_payload` entries via `_build_tool_from_node`. Workflow extends `tools` + `tool_index` from the result. |
| `agent.persist_turn` | Appends the latest human/assistant exchange to memory markdown, trims the window, broadcasts `node.parameters.updated`. |
-| `agent.compact_memory` | Context-pressure compaction when cumulative active-context tokens hit the threshold. Best-effort: continues with un-compacted history on failure; it is not an agent termination control. |
+| `agent.compact_context` | Context-pressure compaction when cumulative active-context tokens hit the threshold (the shared client-side summarizer). Best-effort: continues with un-compacted history on failure; it is not an agent termination control. |
| `agent.store_output` | Writes `output_main` / `output_top` / `output_0` so downstream nodes resolve `{{aiAgent.response}}` via `ParameterResolver`. |
| `agent.broadcast_progress` | Emits `WorkflowEvent.agent_progress` (CloudEvents v1.0) + optional raw-dict `update_node_status` for canvas-glow color. Single helper drives every phase emit. |
-The other nine support skills and durable delegation:
+The other ten support skills and durable delegation (17 `agent.*` activities in total at the time of writing; none carry a `.v1` suffix — only `node.{type}.v{n}` and `poll.*` activities are versioned):
| Activity | Purpose |
|---|---|
-| `agent.skill.invoke.v1` | Executes one progressive skill action with a history-recorded, retry-safe result. |
-| `agent.skill.clear.v1` | Clears the agent's turn-scoped skill state. |
+| `agent.skill.invoke` | Executes one progressive skill action with a history-recorded, retry-safe result. |
+| `agent.skill.clear` | Clears the agent's turn-scoped skill state. |
| `agent.begin_delegation` | Idempotently persists and claims a direct delegation before child startup. |
| `agent.queue_delegation` | Persists a team task before it waits for a root-wide concurrency permit. |
+| `agent.cancel_delegation` | Cancels a queued/running delegated task and records the cancellation idempotently. |
| `agent.acquire_subagent_permit` | Heartbeats while polling the durable root coordinator for a subagent permit. |
| `agent.release_subagent_permit` | Idempotently releases a root-wide subagent permit. |
| `agent.register_task_execution` | Persists the runner and child Temporal identities for trace inspection. |
@@ -491,15 +498,29 @@ Certain nodes provide configuration rather than executing:
```python
# Config handles - nodes connecting via these are filtered out
-CONFIG_HANDLES = {"input-tools", "input-memory", "input-model", "input-skill", "input-task", "input-teammates"}
+# (services/temporal/workflow.py)
+CONFIG_HANDLES = {
+ "input-context",
+ "input-tools",
+ "input-memory", # replay/import compatibility for V1 graph snapshots only
+ "input-model",
+ "input-skill",
+ "input-task",
+ "input-teammates",
+}
# Trigger node types - event listeners, never scheduled as blocking activities
-# Authoritative list: server/constants.py WORKFLOW_TRIGGER_TYPES (frozenset).
-TRIGGER_NODE_TYPES = frozenset([
- "webhookTrigger", "whatsappReceive", "workflowTrigger",
- "chatTrigger", "taskTrigger",
+# Authoritative list: server/constants.py WORKFLOW_TRIGGER_TYPES (frozenset,
+# 17 entries at the time of writing). Omitting a trigger there is a silent
+# failure: find_trigger_nodes filters on this set, so deploy ignores the node.
+WORKFLOW_TRIGGER_TYPES = frozenset([
+ "start", "cronScheduler",
+ "webhookTrigger", "whatsappReceive",
+ "whatsappBusinessReceive", "whatsappBusinessStatus",
+ "discordReceive", "discordInteraction",
+ "workflowTrigger", "chatTrigger", "taskTrigger",
"twitterReceive", "googleGmailReceive", "telegramReceive",
- "emailReceive",
+ "emailReceive", "msMailReceive",
])
# Android service types (connect directly to agent input-tools) -- authoritative list
@@ -522,7 +543,7 @@ Trigger nodes that aren't the firing trigger are:
| Scenario | Behavior |
|----------|----------|
| Ordinary node or agent-support activity fails transiently | Temporal retries up to 3 attempts with backoff unless the error type is non-retryable. |
-| `AgentWorkflow` LLM-step activity fails | `LLM_STEP_RETRY` allows one attempt. Provider SDK retries are also disabled so an ambiguous failure is not silently billed again. |
+| `AgentWorkflow` LLM-step activity fails | `LLM_STEP_RETRY` retries without limit (`maximum_attempts=0`, 5 s → 5 min backoff; `services/temporal/_retry_policies.py`) unless the provider error category is non-retryable (invalid_request, authentication, ...). Provider SDK retries stay disabled so Temporal owns the retry schedule and `retry_after` hints. |
| Worker crashes mid-execution | Temporal reschedules on another worker |
| Ordinary node times out | Temporal applies that activity's retry policy; plugin timeouts vary by node type. |
| All retries exhausted | Workflow receives failure, stops execution |
@@ -544,14 +565,27 @@ server/services/temporal/
│ ├── _build_dependency_maps() # Graph analysis
│ ├── _find_ready_nodes() # Dependency resolution
│ └── _wait_any_complete() # FIRST_COMPLETED wait
-├── worker.py # TemporalWorkerManager
+├── workflow_control_workflow.py # WorkflowControlWorkflow (per-generation controller: triggers, signals, polling, pause)
+├── trigger_listener_workflow.py # TriggerListenerWorkflow (legacy push-trigger listener)
+├── polling_trigger_workflow.py # PollingTriggerWorkflow (legacy polling listener)
+├── schedules.py # Temporal Schedule creation for cronScheduler
+├── search_attributes.py # EVENT_SEARCH_ATTRIBUTES (7 custom SAs, incl. ControlEventTypes)
+├── _retry_policies.py # DEFAULT_ACTIVITY_RETRY / QUICK_ACTIVITY_RETRY / LLM_STEP_RETRY / PERMIT_WAIT_RETRY / ...
+├── _interceptors.py # ObservabilityWorkerInterceptor (activity_retry WARN, workflow_start logs)
+├── plugin_registry.py # Temporal plugin registry
+├── worker.py # TemporalWorkerManager + TemporalWorkerPool
│ ├── start() # Start embedded worker
│ ├── stop() # Cleanup
│ └── run_standalone_worker() # For horizontal scaling
+├── lifecycle.py # run_temporal_lifecycle (dev-server supervision, connect loop, wiring, watchdog)
+├── _runtime.py / _install.py / _handlers.py / _refresh.py # dev-server supervisor, pooch installer, WS + refresh hooks
├── executor.py # TemporalExecutor entry point
+├── ws_client.py # WebSocket connection pool for the legacy activity path
└── client.py # TemporalClientWrapper (runtime heartbeat disabled)
```
+Read the live module list from the directory; the tree above is a map, not an inventory.
+
## Implementation Notes
### Worker Registration (Critical)
@@ -592,15 +626,15 @@ client = await Client.connect(server_address, namespace=namespace, runtime=runti
## Server Management
-The Temporal binary + persistence are managed in-process by the plugin-folder pattern at [`server/services/temporal/`](../server/services/temporal/). Single supervised process — the official `temporal` CLI's `server start-dev` mode, per [docs.temporal.io/develop/python/set-up-your-local-python](https://docs.temporal.io/develop/python/set-up-your-local-python). Five sibling files (`_install.py`, `_runtime.py`, `_handlers.py`, `_refresh.py`, `client.py`, plus `__init__.py` for registry wiring) match the [Wave 11 plugin-folder pattern](./plugin_system.md#self-contained-plugin-folders) that `server/nodes/whatsapp/` uses for its Go binary.
+The Temporal binary + persistence are managed in-process by the plugin-folder pattern at [`server/services/temporal/`](../server/services/temporal/). Single supervised process — the official `temporal` CLI's `server start-dev` mode, per [docs.temporal.io/develop/python/set-up-your-local-python](https://docs.temporal.io/develop/python/set-up-your-local-python). The server-management sibling files (`_install.py`, `_runtime.py`, `_handlers.py`, `_refresh.py`, `lifecycle.py`, `client.py`, plus `__init__.py` for registry wiring) match the [Wave 11 plugin-folder pattern](./plugin_system.md#self-contained-plugin-folders) that `server/nodes/whatsapp/` uses for its Go binary; the rest of the package (see the file structure above) is the execution engine itself.
-**What runs**: one process — `temporal server start-dev --port 5681 --ui-port 5680 --db-filename ~/.opencompany/temporal.db --namespace default`. Both gRPC + Web UI bind to the same process (per docs.temporal.io/cli/server — "all running in a single process"). SQLite-backed durability; history persisted across restarts.
+**What runs**: one process — `temporal server start-dev --port $TEMPORAL_FRONTEND_GRPC_PORT --ui-port $TEMPORAL_UI_PORT --db-filename ~/.opencompany/temporal.db --namespace default`. Both gRPC + Web UI bind to the same process (per docs.temporal.io/cli/server — "all running in a single process"). SQLite-backed durability; history persisted across restarts.
**Modern libs doing the heavy lifting** (zero custom infrastructure code):
- **[`pooch`](https://pypi.org/project/pooch/)** — `services/temporal/_install.py` downloads the official `temporal` CLI archive from `https://temporal.download/cli/archive/latest?platform=<os>&arch=<arch>`. Cross-platform (Windows zip / macOS+Linux tar.gz), cached at `<DATA_DIR>/packages/temporal/` via `_cache_dir() = core.paths.package_dir("temporal")` (pooch's `path=` argument). The retrieve call passes an explicit `downloader=pooch.HTTPDownloader(timeout=300, progressbar=True)`: the timeout is per-socket-read (not total transfer), so arbitrarily slow links can finish the ~114 MB fetch — pooch's 30 s default aborted them — and `progressbar` must live on the downloader because `retrieve()` ignores its own kwarg when `downloader=` is explicit. Failed downloads never poison the cache (pooch writes to a temp file and renames atomically on success). Standalone entry: `python -m services.temporal._install` — invoked **fatally** by `company build` step [6/6] (so first `company start` doesn't pay the download; contract locked by `test_temporal_install_is_fatal_on_failure`) and **non-fatally** by npm postinstall (`scripts/install.js` try/catch — `TemporalServerRuntime._pre_spawn()` re-downloads lazily on first `company start`, so a failed eager fetch never fails `npm install -g`). The binary cache survives `company clean` (`packages` is in `_OPENCOMPANY_KEEP`, `cli/commands/clean.py`). Pre-fix this used `pooch.os_cache("opencompany-temporal")` (`~/.cache/OpenCompany/opencompany-temporal/` etc.) — a separate OS-cache namespace operators reported as "not local"; it now sits under DATA_DIR alongside the Stripe binary and the shared npm tree.
- **`BaseProcessSupervisor` + `BaseSupervisor`** (`server/services/_supervisor/`) — the in-house supervisor base classes that `server/nodes/whatsapp/_runtime.py` also uses. Provides cross-platform signal handling (POSIX `setsid` + Windows Job Objects + `CREATE_NEW_PROCESS_GROUP` for graceful `CTRL_BREAK_EVENT` shutdown), restart policy via tenacity, log draining, status snapshots. We subclass both — zero custom supervisor logic.
-**Lifecycle wiring (July 2026)**: backend-owned, and modular — the whole Temporal runtime story lives in [`services/temporal/lifecycle.py`](../server/services/temporal/lifecycle.py) (`run_temporal_lifecycle`); `main.py` only schedules it as one background task. The module owns: (1) dev-server supervision via `TemporalServerRuntime.ensure_started()` before each connect attempt — a TCP probe on the gRPC port skips the spawn when a server (previously spawned or externally managed) is already listening, and non-loopback `TEMPORAL_SERVER_ADDRESS` values are never spawned at; (2) the forever-retrying connect loop; (3) the config-gated startup sweep; (4) executor + worker manager + worker pool wiring; (5) the boot-time workflow-control reconcile (`services.deployment.handlers.reconcile_active_controls_on_boot`); and (6) a **resident dev-server watchdog** — after startup the task stays alive, probing every `TEMPORAL_HEALTH_MONITOR_INTERVAL_SECONDS` and respawning a dev-server child that died (or restarting a supervisor-owned child that wedged: port bound but gRPC not SERVING for 4 consecutive probes). The runtime registers with `services._supervisor.register_supervisor` so `shutdown_all_supervisors()` actually stops it at teardown. The CLI no longer supervises Temporal: `cli/commands/_temporal_specs.py` and the `_supervised_runtime.py` shim were deleted (the shim was a full second server-venv Python process, ~81 MB resident, plus a ~28 MB resident `uv run` parent — pure supervision overhead).
+**Lifecycle wiring (July 2026)**: backend-owned, and modular — the whole Temporal runtime story lives in [`services/temporal/lifecycle.py`](../server/services/temporal/lifecycle.py) (`run_temporal_lifecycle`); `main.py` only schedules it as one background task. The module owns: (1) dev-server supervision via `TemporalServerRuntime.ensure_started()` before each connect attempt — a TCP probe on the gRPC port skips the spawn when a server (previously spawned or externally managed) is already listening, and non-loopback `TEMPORAL_SERVER_ADDRESS` values are never spawned at; (2) the forever-retrying connect loop; (3) the config-gated startup sweep; (4) executor + worker manager + worker pool wiring; (5) the boot-time workflow-control reconcile (`services.deployment.handlers.reconcile_active_controls_on_boot`); and (6) a **resident dev-server watchdog** — after startup the task stays alive, probing every `TEMPORAL_HEALTH_MONITOR_INTERVAL_SECONDS` and respawning a dev-server child that died (or restarting a supervisor-owned child that wedged: port bound but gRPC not SERVING for 4 consecutive probes). The runtime registers with `services._supervisor.register_supervisor` so `shutdown_all_supervisors()` actually stops it at teardown. The CLI no longer supervises Temporal: the `_temporal_specs.py` command helpers and the `_supervised_runtime.py` shim were deleted (the shim was a full second server-venv Python process, ~81 MB resident, plus a ~28 MB resident `uv run` parent — pure supervision overhead).
**Worker crash-restart (months-long durability)**: the SDK `Worker` is single-use — a second `run()` on the same instance raises `RuntimeError("Already started")`. Both restart loops therefore REBUILD a fresh worker per attempt: `TemporalWorkerManager._run_worker` via `_build_worker()`, and every `TemporalWorkerPool` queue worker runs under `_run_queue_worker` (previously a bare `worker.run()` task — one crash silently killed the queue's only worker and its activities pended forever). Backoff knobs: `TEMPORAL_WORKER_RESTART_BACKOFF_SECONDS` / `_MAX_SECONDS`. Locked by `tests/temporal/test_worker_restart.py`.
@@ -615,7 +649,7 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa
**Startup sweep (debug-only escape hatch)**: [`TemporalClientWrapper.terminate_running_workflows`](../server/services/temporal/client.py) — gated on `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` (default **`false`**; keep it false — setting `true` converts every boot into a namespace-wide terminate sweep). Even when enabled, any control row in an active state (the shared `WORKFLOW_CONTROL_ACTIVE_STATES`, which includes `resetting`) vetoes the sweep. History is preserved (UI shows workflows as `Terminated`, not deleted); only active execution stops.
-**Port management**: Temporal owns ports 5681 (gRPC) + 5680 (Web UI). Both bound by the same `temporal.exe` process; both listed in `cli.config.Config.all_ports` so `company stop`'s port-freeing pre-flight covers them.
+**Port management**: Temporal owns `TEMPORAL_FRONTEND_GRPC_PORT` (gRPC) + `TEMPORAL_UI_PORT` (Web UI). Both bound by the same `temporal.exe` process; both listed in `cli.config.Config.all_ports` so `company stop`'s port-freeing pre-flight covers them.
**Direct CLI access**: the pooch-installed `temporal` binary lives under `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default, on every OS). Run `temporal --version`, `temporal workflow list`, etc. directly from there.
@@ -624,13 +658,13 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa
| Setting | Env var | `.env.template` default | Purpose |
|---|---|---|---|
| `temporal_enabled` | `TEMPORAL_ENABLED` | `true` | Master toggle. When false, `WorkflowService` falls back to the sequential executor. |
-| `temporal_server_address` | `TEMPORAL_SERVER_ADDRESS` | `localhost:5681` | Address the Python SDK client connects to. |
+| `temporal_server_address` | `TEMPORAL_SERVER_ADDRESS` | `localhost:<TEMPORAL_FRONTEND_GRPC_PORT>` | Address the Python SDK client connects to. |
| `temporal_namespace` | `TEMPORAL_NAMESPACE` | `default` | Bootstrapped at server start. |
| `temporal_task_queue` | `TEMPORAL_TASK_QUEUE` | `machina-tasks` | Default task queue for the embedded worker. |
| `temporal_per_type_dispatch` | `TEMPORAL_PER_TYPE_DISPATCH` | `true` | F4.A flag — per-type activity dispatch. |
| `temporal_agent_workflow_enabled` | `TEMPORAL_AGENT_WORKFLOW_ENABLED` | `true` | F4.B flag — agent-as-child-workflow. |
-| `temporal_frontend_grpc_port` | `TEMPORAL_FRONTEND_GRPC_PORT` | `5681` | gRPC port (`--port`). Drives the readiness probe. |
-| `temporal_ui_port` | `TEMPORAL_UI_PORT` | `5680` | Web UI port (`--ui-port`). CLI default is `--port + 1000`; pinned into the serial 5678-block instead. |
+| `temporal_frontend_grpc_port` | `TEMPORAL_FRONTEND_GRPC_PORT` | see `.env.template` | gRPC port (`--port`). Drives the readiness probe. |
+| `temporal_ui_port` | `TEMPORAL_UI_PORT` | see `.env.template` | Web UI port (`--ui-port`). CLI default is `--port + 1000`; pinned into the serial block that starts at `PYTHON_BACKEND_PORT` instead. |
| `temporal_sqlite_path` | `TEMPORAL_SQLITE_PATH` | `temporal.db` | SQLite file (`--db-filename`). Resolved relative to `DATA_DIR` (= `~/.opencompany/`) unless absolute — flat under `~/.opencompany/` like `credentials.db` / `workflow.db`. |
| `temporal_graceful_shutdown_seconds` | `TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS` | `30` | `CTRL_BREAK_EVENT` (Windows) / `SIGTERM` (POSIX) → tree-kill grace window. Shared with the embedded worker shutdown. |
| `temporal_terminate_running_on_startup` | `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` | `false` | Debug-only startup sweep (see the durability contract above). Keep false so running and paused deployments survive restarts. |
@@ -643,17 +677,11 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa
Full recovery-policy semantics: [temporal-workflow-control.md → Recovery policies](./temporal-workflow-control.md#recovery-policies).
-The legacy `TEMPORAL_SERVER_READY_TIMEOUT_SECONDS` knob (CLI-supervised-era readiness wait) was removed — it had no consumer since the backend-owned cutover.
-
-One temporary agent-engine cutover variable is also read directly rather than
-through `Settings`:
-
-| Env var | `.env.template` default | Purpose |
-|---|---|---|
+The legacy `TEMPORAL_SERVER_READY_TIMEOUT_SECONDS` knob (CLI-supervised-era readiness wait) was removed — it had no consumer since the backend-owned cutover. The temporary agent-engine cutover variable that was read directly rather than through `Settings` is gone too: the engine selector is now recorded per execution by `agent.prepare_payload` (see above).
## Debugging
-The Web UI is at http://localhost:5680; the UI's HTTP API rides the gRPC port + 1000 (6681).
+The Web UI is at `http://localhost:<TEMPORAL_UI_PORT>`; the UI's HTTP API rides the gRPC port + 1000.
### Reading Temporal tracing output
@@ -702,10 +730,10 @@ duplicate execution.
```bash
# Temporal Web UI
-open http://localhost:5680
+open http://localhost:$TEMPORAL_UI_PORT
# List workflows via the local CLI binary (under <DATA_DIR>/packages/temporal/)
-~/.opencompany/packages/temporal/.../temporal.exe workflow list --address localhost:5681
+~/.opencompany/packages/temporal/.../temporal.exe workflow list --address localhost:$TEMPORAL_FRONTEND_GRPC_PORT
# Re-fetch the binary at any time
uv run python -m services.temporal._install
diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.md
index 9b934b40..c406b3c3 100644
--- a/docs-internal/agent_architecture.md
+++ b/docs-internal/agent_architecture.md
@@ -5,7 +5,7 @@ Detailed architecture reference for how AI Agent (`aiAgent`) and Chat Agent (`ch
> **Related Documentation:**
> - [Node Creation Guide](./node_creation.md) - Canonical plugin recipe (covers tool nodes, dual-purpose nodes, specialized agents)
> - [Tool Building Pipeline](./tool_building_pipeline.md) - Canonical home for `_build_tool_from_node`, tool discovery, per-type Temporal dispatch
-> - [Memory Lifecycle](./memory_lifecycle.md) - Canonical home for markdown memory format, vector store, session resume
+> - [Agent Context Flow](./agent_context_flow.md) - Canonical home for conversation continuity (RFC-0002 Context store); [Memory Lifecycle](./memory_lifecycle.md) covers only the retired V1 markdown model
> - [CLAUDE.md](../CLAUDE.md) - Project overview and full node inventory
## Table of Contents
@@ -15,7 +15,7 @@ Detailed architecture reference for how AI Agent (`aiAgent`) and Chat Agent (`ch
3. [Skill Injection Pipeline](#skill-injection-pipeline)
4. [Tool Building Pipeline](#tool-building-pipeline)
5. [Tool Execution Flow](#tool-execution-flow)
-6. [Memory Integration](#memory-integration)
+6. [Context and Memory Integration](#context-and-memory-integration)
7. [execute_agent vs execute_chat_agent](#execute_agent-vs-execute_chat_agent)
---
@@ -27,7 +27,7 @@ User clicks "Run" on AI Agent
|
v
ExecutionService.executeNodeViaWebSocket() client/src/services/executionService.ts
- Called from ParameterPanel.tsx:71
+ Called from ParameterPanel.tsx:81
Sends ALL workflow nodes + edges
|
v
@@ -51,7 +51,9 @@ collect_agent_connections() server/services/plugin/edge_walker.py
(called by nodes/agent/_inline.prepare_agent_call)
Scans edges where target == node_id
Groups by targetHandle into 5 buckets (returns a 5-tuple
- memory_data, skill_data, tool_data, input_data, task_data):
+ 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 immutable V1 snapshots):
input-context -> context_data
input-skill -> skill_data[]
input-tools -> tool_data[]
@@ -60,10 +62,13 @@ collect_agent_connections() server/services/plugin/edge_walker.py
|
v
AIService.execute_agent() / execute_chat_agent() server/services/ai.py
- 1. Inject skills into system message
+ 1. Inject personality-skill bodies into the system message
+ (_build_skill_system_prompt -> services/skill_prompt.py); standard
+ skills ride the Skill tool instead
2. Build provider-neutral AgentToolSpecs from tool_data
3. Call run_native_agent_loop(ChatUnifier, ...)
- 4. Save memory, return result
+ 4. Save the conversation (Context store; legacy V1 memory markdown
+ only for immutable V1 snapshots), return result
|
v
run_native_agent_loop() execution
@@ -85,7 +90,8 @@ Result broadcast via WebSocket
| `server/services/plugin/edge_walker.py` | `collect_agent_connections()` (the renamed `_collect_agent_connections`), `format_task_context()` |
| `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` |
| `server/nodes/agent/<plugin>/__init__.py` | Per-plugin `execute_op()` (Wave 11 replaced `handle_ai_agent` / `handle_chat_agent`) |
-| `server/services/ai.py` | `AIService` facade -- skill injection, tool building, memory and execution-boundary handling |
+| `server/services/ai.py` | `AIService` facade -- skill injection (`_build_skill_system_prompt`, line 273), tool building, context/memory and execution-boundary handling |
+| `server/services/skill_prompt.py` | `build_skill_system_prompt` -- the only skill-to-system-message path (personality bodies only) |
| `server/services/agent_runtime.py` | `AgentToolSpec`, `run_native_llm_step`, and `run_native_agent_loop` |
| `server/services/llm/` | `ChatUnifier`, provider-neutral messages/tool definitions, and native provider SDK adapters |
| `server/services/handlers/tools.py` | `execute_tool()` -- dispatch router for all tool types |
@@ -138,16 +144,28 @@ async def run_native_agent_loop(
initial_messages: Sequence[Message],
thinking: Optional[ThinkingConfig] = None,
tools: Optional[Sequence[AgentToolSpec]] = None,
- tool_executor: Optional[Callable] = None,
+ tool_executor: Optional[Callable[[str, Dict[str, Any]], Awaitable[Any]]] = None,
max_iterations: int = 500,
- progress_callback: Optional[Callable[[int], Any]] = None,
+ progress_callback: Optional[Callable[[int], Awaitable[Any]]] = None,
rebind_from_operations: Optional[
Callable[[List[Dict[str, Any]]], Awaitable[List[AgentToolSpec]]]
] = None,
+ context_management: Optional[Dict[str, Any]] = None,
+ compaction_pause_callback: Optional[
+ Callable[[int, LLMResponse, List[Message]], Awaitable[Optional[List[Message]]]]
+ ] = None,
+ conversation_saver: Optional[Callable[[List[Message]], Awaitable[None]]] = None,
) -> Dict[str, Any]:
"""Returns messages, iteration, thinking, truncation, usage, and response."""
```
+(`services/agent_runtime.py:190-216`.) The three trailing keywords are the
+RFC-0002 hooks: `context_management` is forwarded to the provider step (the
+Anthropic compaction edit), `compaction_pause_callback` lets the caller swap
+the message list after a provider-side compaction pause, and
+`conversation_saver` persists the full transcript after every turn through
+the plain conversation store (see [agent_context_flow.md](agent_context_flow.md)).
+
There is no mutable model binding step. Each native LLM request derives its
provider-facing declarations from the current `AgentToolSpec.definition`
values. When a canvas-mutating tool returns workflow operations (today only
@@ -201,8 +219,8 @@ Two callsites in `server/services/ai.py`:
- `execute_agent` — for `aiAgent` plugins.
- `execute_chat_agent` — for `chatAgent` + all specialized agents + team leads.
-Both build native `initial_messages` (system, memory history, current prompt,
-and skill injection), build tools via `_build_tool_from_node`, then call
+Both build native `initial_messages` (system, stored conversation history,
+current prompt, and personality-skill injection), build tools via `_build_tool_from_node`, then call
`run_native_agent_loop` and extract the final assistant message, accumulated
thinking, usage, and iteration count from the returned dict.
@@ -234,7 +252,7 @@ For standard skill nodes (claudeSkill, whatsappSkill, etc.), a single entry is c
skill_entry = {
'node_id': source_node_id,
'node_type': skill_type, # e.g., 'whatsappSkill'
- 'skill_name': skill_params.get('skillName', skill_type),
+ 'skill_name': skill_params.get('skill_name', skill_type),
'parameters': skill_params, # All node parameters from DB
'label': source_node.get('data', {}).get('label', skill_type)
}
@@ -243,28 +261,34 @@ skill_data.append(skill_entry)
### 3. Master Skill Expansion
-When the connected skill is a `masterSkill`, its `skillsConfig` parameter is expanded into N individual entries:
+When the connected skill is a `masterSkill`, its `skills_config` parameter is
+expanded into N individual entries. The expansion lives in the skill plugin
+folder — `nodes/skill/_expander.py`, registered into the edge walker via
+`register_master_skill_expander` — so `edge_walker.py` carries no knowledge of
+the Master Skill parameter shape:
```python
-if skill_type == 'masterSkill':
- skills_config = skill_params.get('skillsConfig', {})
- # Structure: {'whatsapp-skill': {'enabled': True, 'instructions': '...'}, ...}
-
- for skill_key, skill_cfg in skills_config.items():
- if not skill_cfg.get('enabled', False):
- continue # Skip disabled skills
-
- skill_data.append({
- 'node_id': f"{source_node_id}_{skill_key}", # Unique composite ID
- 'master_skill_node_id': source_node_id,
- 'node_type': 'masterSkill',
- 'skill_name': skill_key,
- 'description': metadata.description,
- # Customized instructions remain authoritative but are not put in
- # the initial prompt for standard skills.
- 'parameters': {'instructions': skill_cfg.get('instructions', '')},
- 'label': skill_key
- })
+# nodes/skill/_expander.py
+skills_config = skill_params.get('skills_config', {})
+# Structure: {'whatsapp-skill': {'enabled': True, 'instructions': '...'}, ...}
+
+for skill_key, skill_cfg in skills_config.items():
+ if not skill_cfg.get('enabled', False):
+ continue # Skip disabled skills
+
+ skill_data.append({
+ 'node_id': f"{source_node_id}_{skill_key}", # Unique composite ID
+ 'master_skill_node_id': source_node_id,
+ 'node_type': 'masterSkill',
+ 'skill_name': skill_key, # snake_case is canonical; a
+ # 'skillName' mirror is kept for
+ # legacy readers
+ 'description': metadata.description,
+ # Customized instructions remain authoritative but are not put in
+ # the initial prompt for standard skills.
+ 'parameters': {'instructions': skill_cfg.get('instructions', '')},
+ 'label': skill_key
+ })
```
One Master Skill node with 5 enabled skills produces 5 separate `skill_data` entries.
@@ -303,11 +327,12 @@ this behavior is not owned by the team-lead implementation.
### 4. SkillLoader Architecture
-Defined in `server/services/skill_loader.py:38+`:
+Defined in `server/services/skill_loader.py:54+`:
```
SkillLoader
-├── _skill_dirs: [server/skills/, .opencompany/skills/]
+├── _skill_dirs: [server/skills/, <cwd>/.machina/skills/, <cwd>/.opencompany/skills/]
+│ # _default_skill_dirs(), later dirs win
├── _database # DI database singleton (user skills live in the DB)
├── _registry: Dict[name -> SkillMetadata] # Metadata only (~100 tokens each)
├── _cache: Dict[name -> Skill] # Full content (lazy-loaded)
@@ -315,16 +340,16 @@ SkillLoader
├── scan_skills() # rglob("SKILL.md") across all dirs, parses frontmatter
├── load_skill(name) # Filesystem skills: cache -> registry -> SKILL.md
├── load_skill_async(name) # DB-aware: filesystem first, then database.get_user_skill()
-├── get_registry_prompt() # Generates "## Available Skills" for system message
+├── get_registry_prompt() # "## Available Skills" text — DEAD: zero callers (see §5)
└── get_skill_instructions()# Shortcut for load_skill().instructions
```
-**`scan_skills()`** (`skill_loader.py:63-88`):
+**`scan_skills()`** (`skill_loader.py:80-105`):
- Iterates `_skill_dirs`, uses `rglob("SKILL.md")` for recursive discovery
- Parses YAML frontmatter for each file (`_parse_skill_metadata`)
- Populates `_registry` with `SkillMetadata` (name, description, allowed_tools, path)
-**`load_skill(name)`** (`skill_loader.py:174-249`):
+**`load_skill(name)`** (`skill_loader.py:228-298`):
1. Check `_cache` -- return immediately if cached
2. Look up `_registry[name]` -- fail if not registered
3. Read `SKILL.md`, strip frontmatter, extract markdown body as `instructions`
@@ -336,7 +361,7 @@ SkillLoader
- 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.
- `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.
-**SKILL.md frontmatter parsing** (`skill_loader.py:126-172`):
+**SKILL.md frontmatter parsing** (`_parse_skill_metadata`, `skill_loader.py:144-227`):
```yaml
---
name: http-skill # Lowercase with hyphens, validated by regex
@@ -350,53 +375,47 @@ metadata:
### 5. System Message Injection
-In `execute_agent()` and `execute_chat_agent()` within `server/services/ai.py`:
+The only path from `skill_data` to the system message is
+`_build_skill_system_prompt` (`server/services/ai.py:273`), a thin wrapper
+that imports and calls `services/skill_prompt.py::build_skill_system_prompt`.
+It is called from `execute_agent` (`ai.py:917`), `execute_chat_agent`
+(`ai.py:1633`), the RLM service (`services/rlm/service.py:74-77`) and the
+Temporal `agent.prepare_payload` activity (`agent_activities.py:971-973`):
```python
-if skill_data:
- skill_loader = get_skill_loader()
- skill_loader.scan_skills()
-
- # Extract skill names from collected data
- skill_names = []
- for skill_info in skill_data:
- skill_name = skill_info.get('skill_name') or ...
- skill_names.append(skill_name)
-
- # Generate structured skill listing
- skill_prompt = skill_loader.get_registry_prompt(skill_names)
- if skill_prompt:
- system_message = f"{system_message}\n\n{skill_prompt}"
-```
-
-### 6. Registry Prompt Output
-
-`get_registry_prompt()` in `skill_loader.py:311-341` generates:
+# server/services/ai.py:273
+def _build_skill_system_prompt(skill_data, log_prefix="[Agent]") -> tuple:
+ from services.skill_prompt import build_skill_system_prompt
+ return build_skill_system_prompt(skill_data, log_prefix)
+# execute_agent / execute_chat_agent
+skill_prompt, has_personality = _build_skill_system_prompt(skill_data, log_prefix="[AIAgent]")
```
-## Available Skills
-
-You have access to the following skills. When a user's request matches
-a skill's purpose, activate it to help them.
-- **http-skill**: Make HTTP requests to external APIs
- - Tools: http-request
-- **whatsapp-skill**: Send and receive WhatsApp messages
- - Tools: whatsapp-send, whatsapp-db
-- **maps-skill**: Location services via Google Maps
+`build_skill_system_prompt` walks `skill_data` and injects **only personality
+skills** (names ending in `-personality`) — their full SKILL.md
+`parameters.instructions` body is appended verbatim to the system message,
+and `has_personality=True` tells the caller to drop the default system
+message. Every other skill is counted and logged but contributes **nothing**
+to the prompt: standard skills reach the model through the dynamically bound
+`Skill` tool (name/description catalogue, `load` for the body,
+`read_resource` / `search_resource` for declared files), as described in §3.
-To use a skill, identify when the user's request matches its purpose
-and apply the skill's instructions.
-```
+### 6. Registry prompt (unused)
-This text is appended to the system message. The full SKILL.md body (instructions) is available via individual skill entries but the registry prompt provides the high-level listing.
+`SkillLoader.get_registry_prompt()` (`skill_loader.py:361-391`) still exists
+and renders a `## Available Skills` markdown listing (name, description,
+`- Tools:` line per skill), but it has **zero callers** in the codebase. No
+agent path appends a skill listing to the system message; the Skill tool's
+catalogue replaced it. Treat the method as dead code — do not build new
+prompt features on it.
### 7. allowed-tools
-- **Parsed** from SKILL.md frontmatter as space-delimited list
-- **Included** in registry prompt as informational text for the LLM
+- **Parsed** from SKILL.md frontmatter as a space-delimited list into `SkillMetadata.allowed_tools`
+- **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
- **NOT enforced** in code -- the LLM can call any tool connected to `input-tools`
-- Purpose: guides the LLM on which tools are relevant to each skill
+- 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`)
---
@@ -427,20 +446,31 @@ Patterns covered in the canonical doc:
---
-## Memory Integration
-
-Memory load + save lives in
-[memory_lifecycle.md](./memory_lifecycle.md). The agent loop reads
-`memory_data` from `collect_agent_connections()`
-(`server/services/plugin/edge_walker.py`, via the `input-memory` edge),
-prepends history parsed into native `Message` values to the system message and
-current prompt, runs `run_native_agent_loop`, then atomically appends the turn,
-trims the window, and archives trimmed text to the optional vector store. The
-markdown helpers (`parse_memory_markdown`, `append_to_memory_markdown`,
-`trim_markdown_window`) and `NativeMemoryVectorStore` with the optional direct
-sentence-transformers embedder are the load-bearing surface — see the
-canonical doc for signatures, the markdown format, and the engine-specific
-table.
+## Context and Memory Integration
+
+Conversation continuity is the RFC-0002 Context store, documented in
+[agent_context_flow.md](./agent_context_flow.md) and
+[RFC-0002](../RFC-0002-AGENT-CONTEXT-AND-MEMORY.md). The agent reads
+`context_data` — the first element of the `collect_agent_connections()`
+5-tuple (`server/services/plugin/edge_walker.py:181-199`), populated from the
+`input-context` edge to a `context` node — and `AIService._prepare_context`
+resolves it into an `_AgentContextRuntime{key, history, database}`. Stored
+history is seeded into `initial_messages` (system messages filtered), the
+loop runs with `conversation_saver=runtime.save` so every turn persists the
+full transcript, and nothing else about the request changes because a Context
+node is attached.
+
+`simpleMemory` ("Memory") is **not** conversation history: it is a `ToolNode`
+on `input-tools` that the agent calls explicitly (`remember` / `recall` /
+`update` / `forget`). The `input-memory` handle is retired — no agent declares
+it; `normalize_workflow_graph` rewrites legacy `simpleMemory -> input-memory`
+edges into a Context node plus an ordinary tool edge. The legacy markdown
+memory path (`memory_data`, `parse_memory_markdown`,
+`append_to_memory_markdown`, `trim_markdown_window`, the vector store) is
+reached only for immutable V1 snapshots: `execute_agent` passes the tuple's
+first element as `context_data` to `_prepare_context` and sets `memory_data =
+None` whenever a Context runtime resolves (`ai.py:969-980`). Token tracking
+and compaction thresholds are in [memory_compaction.md](memory_compaction.md).
---
@@ -591,7 +621,7 @@ to one iteration.
`aiAgent` and `chatAgent` (display name "Zeenie") are near-identical in
capability — both run `run_native_agent_loop` through `ChatUnifier`, support
-memory / skills / tools / task input, and can delegate asynchronously. The
+context / skills / tools / task input, and can delegate asynchronously. The
differences are which backend method they call and the softness of callback
error handling.
@@ -602,7 +632,7 @@ error handling.
| Skill Support | Yes | Yes |
| Task Input | Yes (`input-task`) | Yes (`input-task`) |
| Bottom Handles | Skill, Tools | Skill, Tools |
-| Left Handles | Input, Memory, Task | Input, Memory, Task |
+| Left Handles | Input, Context, Task | Input, Context, Task |
| Backend Method | `execute_agent()` | `execute_chat_agent()` |
| No-tool path | Native loop returns after the first final response | Native loop is bounded to one iteration |
| Tool-failure handling | Callback re-raises; loop creates an error tool-result message | Callback returns `{"error": str(e)}`; loop creates the tool-result message |
diff --git a/docs-internal/agent_delegation.md b/docs-internal/agent_delegation.md
index 7ca71554..af09c19d 100644
--- a/docs-internal/agent_delegation.md
+++ b/docs-internal/agent_delegation.md
@@ -93,7 +93,7 @@ for tool_info in tool_data:
For agent node types, the method:
-1. 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 — the **15-agent delegatable set** (`aiAgent`, `chatAgent`, `android_agent`, `coding_agent`, `web_agent`, `task_agent`, `social_agent`, `travel_agent`, `tool_agent`, `productivity_agent`, `payments_agent`, `consumer_agent`, `autonomous_agent`, `orchestrator_agent`, `ai_employee`) plus the two bypass-loop agents `rlm_agent` and `claude_code_agent`. (`AI_AGENT_TYPES` in `server/constants.py` mirrors this same set; `codex_agent` is not currently in it.)
+1. 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 (`services/ai.py:2510-2529`) — **18 agents**: the 15 standard delegatable agents (`aiAgent`, `chatAgent`, `android_agent`, `coding_agent`, `web_agent`, `task_agent`, `social_agent`, `travel_agent`, `tool_agent`, `productivity_agent`, `payments_agent`, `consumer_agent`, `autonomous_agent`, `orchestrator_agent`, `ai_employee`), the two bypass-loop agents `rlm_agent` and `claude_code_agent`, and the bridged cloud agent `vertex_managed_agent`. (`AI_AGENT_TYPES` in `server/constants.py:32-53` mirrors this same 18-entry set; `codex_agent` is not currently in it. The `tool_name = f"delegate_to_{cls.type}"` default is stamped by `BaseNode.__init_subclass__`, `services/plugin/base.py:257`, so only `aiAgent`, `chatAgent` and `vertex_managed_agent` declare it explicitly.)
2. 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):
```python
@@ -172,7 +172,7 @@ if node_type in AI_AGENT_TYPES:
return await _execute_delegated_agent(tool_args, config)
```
-`AI_AGENT_TYPES` is the single source of truth: the 15 standard delegatable agents plus `rlm_agent` and `claude_code_agent`.
+`AI_AGENT_TYPES` is the single source of truth: the 15 standard delegatable agents plus `rlm_agent`, `claude_code_agent`, and `vertex_managed_agent` (18 total).
---
@@ -277,10 +277,10 @@ result = await instance.execute(node_id, child_params, child_ctx)
**File:** `server/nodes/agent/_inline.py`, `prepare_agent_call()` (called by every agent plugin's `@Operation`)
-The 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** — `(memory_data, skill_data, tool_data, input_data, task_data)`:
+The 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 immutable V1 snapshots):
```python
-memory_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(
+context_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(
node_id, # CHILD's node ID
child_context, # Contains ALL nodes/edges
database,
@@ -315,7 +315,7 @@ For each matching edge, it checks the target handle:
| `input-main` / `input-chat` | Reads upstream node output for auto-prompt fallback |
| `input-task` | Collects `taskTrigger` output for the conversational task-report pattern |
-The child only gets connections that are physically wired to it in the workflow graph. If the child has no memory node connected, `memory_data` is `None`. If the child has its own tools, it gets those tools -- and can delegate further.
+The 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.
---
@@ -342,7 +342,12 @@ The child's result is broadcast to the UI via WebSocket but is NOT fed back into
## Memory Isolation
-Parent and child agents have completely separate memory systems:
+Parent and child agents have completely separate memory systems. On current
+(V2) graphs the child's conversation is its own RFC-0002 Context store row,
+keyed by `(workflow_id, generation, <child agent_node_id>)`, and `simpleMemory`
+is an explicit tool the child calls on its own `input-tools`; the table below
+describes the legacy V1 markdown model, which survives only for immutable V1
+snapshots:
| Aspect | Parent Agent | Child Agent |
|--------|-------------|-------------|
@@ -540,7 +545,7 @@ All broadcasts include `workflow_id` for UI scoping. The frontend uses these to
| File | Role |
|------|------|
| `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()` |
-| `server/services/plugin/edge_walker.py` | `collect_agent_connections()` (5-tuple: memory / skill / tool / input / task) |
+| `server/services/plugin/edge_walker.py` | `collect_agent_connections()` (5-tuple: context / skill / tool / input / task) |
| `server/nodes/agent/_inline.py` | `prepare_agent_call()` — the 3-step pre-dispatch flow (connection collection + param prep) every agent plugin's `@Operation` runs |
| `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 |
| `server/services/handlers/tools.py` | `execute_tool()` dispatcher, `_execute_delegated_agent()`, `_execute_check_delegated_tasks()`, `_delegated_tasks` / `_delegation_results` / `_active_delegations` tracking |
@@ -730,6 +735,7 @@ Post-Wave-11 the frontend `specializedAgentNodes.ts` definition file no longer e
- **Left**: `input-main` (Input), `input-context` (Context), `input-task` (Task)
- **Bottom**: `input-skill` (Skill), `input-tools` (Tool)
+- **Right**: `output-main` (Output)
- **Top**: `output-top` (Output)
Team-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.
diff --git a/docs-internal/authentication.md b/docs-internal/authentication.md
index 2021222d..d681a188 100644
--- a/docs-internal/authentication.md
+++ b/docs-internal/authentication.md
@@ -6,8 +6,8 @@ n8n-inspired authentication system with JWT tokens stored in HttpOnly cookies. A
## Authentication Toggle
| Setting | Environment Variable | Description |
|---------|---------------------|-------------|
-| **Enabled** | `VITE_AUTH_ENABLED=true` | Require login (default) |
-| **Disabled** | `VITE_AUTH_ENABLED=false` | Bypass authentication, anonymous access |
+| **Enabled** | `VITE_AUTH_ENABLED=true` | Require login (`company deploy` sets this on cloud VMs) |
+| **Disabled** | `VITE_AUTH_ENABLED=false` | Bypass authentication, anonymous access (**default** in `.env.template`) |
When `VITE_AUTH_ENABLED=false`:
- Frontend skips login page entirely
@@ -91,9 +91,13 @@ and never cleared on logout. See
`routers/auth.py` defines its own local `get_auth_service()` helper
(`return container.auth_service()`) — `get_auth_service` is NOT exported from
-`services/auth.py`. The same local-helper pattern is repeated in
-`routers/twitter.py`, `routers/google.py`, and `routers/websocket.py`. In
-handlers/services use `from core.container import container; auth = container.auth_service()`.
+`services/auth.py`. `routers/websocket.py` repeats the same local helper.
+The OAuth callback routers moved into their plugin folders
+(`nodes/twitter/_router.py`, `nodes/google/_router.py`, built by
+`services.events.oauth_lifecycle.make_oauth_callback_router`) and resolve the
+service through `services.plugin.deps.get_auth_service` — the same call-time
+container lookup, deliberately not memoised. In handlers/services use
+`from core.container import container; auth = container.auth_service()`.
### Auth Middleware (`server/middleware/auth.py`)
Protects all routes except public paths:
@@ -162,7 +166,7 @@ const ProtectedRoute: React.FC<{ children: React.ReactNode }> = ({ children }) =
Environment variables in `.env`:
```bash
# Authentication Toggle (frontend - Vite)
-VITE_AUTH_ENABLED=true # 'true' or 'false' - disable to bypass login
+VITE_AUTH_ENABLED=false # 'false' (template default) bypasses login; 'true' requires it
# Authentication Mode (backend)
AUTH_MODE=single # 'single' or 'multi'
@@ -306,7 +310,7 @@ useEffect(() => {
| `client/src/components/auth/LoginPage.tsx` | Login UI |
| `client/src/components/auth/ProtectedRoute.tsx` | Route guard |
| `server/models/auth.py` | User SQLModel with bcrypt |
-| `server/services/user_auth.py` | JWT creation/verification + encryption init on login/logout |
+| `server/services/user_auth.py` | `UserAuthService`: register / login / JWT mint + verify / `get_current_user`. No encryption-service coupling (see the note under Auth Service) |
| `server/routers/auth.py` | REST endpoints |
| `server/middleware/auth.py` | Route protection (`PUBLIC_PATHS` / `PUBLIC_PREFIXES`) |
| `server/core/config.py` | Settings with `vite_auth_enabled` field |
diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.md
index 8e1ca4a7..5a774363 100644
--- a/docs-internal/ci_cd.md
+++ b/docs-internal/ci_cd.md
@@ -87,7 +87,7 @@ Reusable `workflow_call` workflow with four independent jobs (no plan/change-det
- `build-and-lint` — `bun install --frozen-lockfile` + `bun run build`, then client lint (`bun run --filter react-flow-client lint`), TypeScript check (`... typecheck`), and frontend tests (`... test`, vitest). Runs on `ubuntu-latest`.
- `backend-tests` — `uv sync` + `uv run pytest tests/ -v` in `server/`. Whole suite, unsharded. Runs on `ubuntu-latest`.
- `cli-tests` — `uv pip install --system pytest pytest-asyncio pyyaml` + `python -m pytest cli/tests/ -v`. Runs on `ubuntu-latest`.
-- `test-build-start` — cross-OS matrix (`ubuntu-latest`, `macos-latest`, `windows-latest`, `fail-fast: false`). Runs `bun run build`, then a start smoke test. On Unix it backgrounds `bun run start`, polls `http://localhost:5678/health` for up to ~30 s, then `bun run stop`. On Windows it starts the supervisor as a background job, waits 15 s, and fails if the job already exited.
+- `test-build-start` — cross-OS matrix (`ubuntu-latest`, `macos-latest`, `windows-latest`, `fail-fast: false`). Runs `bun run build`, then `bun run tsc --version` (proves the per-platform TypeScript 7 Go binary delivered via `optionalDependencies` resolves on every OS — the type-check gate itself runs on ubuntu only; `bun run`, never `bunx`, so it resolves strictly from the root `node_modules/.bin`), then a start smoke test. On Unix it backgrounds `bun run start`, reads `PYTHON_BACKEND_PORT` out of `.env.template` and polls `http://localhost:${APP_PORT}/health` for up to ~30 s, then `bun run stop`. On Windows it starts the supervisor as a background job, waits 15 s, and fails if the job already exited.
---
diff --git a/docs-internal/claude_code_agent.md b/docs-internal/claude_code_agent.md
index bfd10c08..1c3d6af1 100644
--- a/docs-internal/claude_code_agent.md
+++ b/docs-internal/claude_code_agent.md
@@ -3,7 +3,9 @@
`claude_code_agent` is a OpenCompany agent node that drives the real `claude` CLI as a
long-lived **interactive** subprocess (stdio pipes, no PTY) over the VSCode-extension
stream-json protocol — not the `claude -p` headless path. A warm `ClaudeSessionPool`
-(keyed by the connected `simpleMemory.node_id`) preserves the session across turns;
+(keyed by the RFC-0002 conversation key when a Context node is connected, or by the
+legacy `simpleMemory.node_id` on immutable V1 graphs — `services/cli_agent/service.py:354-358`)
+preserves the session across turns;
memory continuity is claude-native via `--continue` / `--resume <UUID>` on a stable
`cwd=repo_root`. Connected tools and skills reach claude through an MCP bridge; the spawn
runs under `--permission-mode dontAsk` with a strict `--allowedTools` allowlist and stays
@@ -25,7 +27,7 @@ This page is a **router**. The detail lives in the documents below — start her
| Headless / print mode (`claude -p`, `--output-format`, stream-json event schema) — the schema the pool parses off stdout | [claude_code_headless_reference.md](./claude_code_headless_reference.md) (snapshot) |
| SKILL.md frontmatter spec, discovery paths, `context: fork` — what we materialise skills against | [claude_code_skills_reference.md](./claude_code_skills_reference.md) (snapshot) |
-The four `cli-reference` / `env-vars` / `permission-modes` / `headless` / `skills`
+The five `cli-reference` / `env-vars` / `permission-modes` / `headless` / `skills`
documents are **verbatim snapshots** of code.claude.com docs (fetched 2026-05-11), kept so
the contract the pool parses is pinned even if upstream changes.
@@ -36,12 +38,12 @@ All claude-specific code is self-contained here; the generic framework at
| File | Responsibility |
|---|---|
-| `__init__.py` | `ClaudeCodeAgentNode(SpecializedAgentBase)` + `Params`/`Output`; self-registers via `factory.py` (`register_provider` / `register_session_pool` / `register_skill_materialiser`) + `register_ws_handlers`. |
+| `__init__.py` | `ClaudeCodeAgentNode(ActionNode)` (line 238 — it does not go through `SpecializedAgentBase` / the native loop) + `Params`/`Output`; self-registers via `factory.py` (`register_provider` / `register_session_pool` / `register_skill_materialiser`) + `register_ws_handlers`. |
| `_provider.py` | Builds the spawn argv (`--output-format stream-json --input-format stream-json --verbose --ide`, `--permission-mode dontAsk`, `--allowedTools`, `--continue`/`--resume`). |
| `_pool.py` | `ClaudeSessionPool` — warm subprocess keyed by `simpleMemory.node_id`; stdout reader, session-UUID capture, crash-recovery respawn. |
| `_skills.py` | `materialise_skills` — writes connected SKILL.md trees under `<workspace>/.claude/skills/`, diff-based on warm reuse. |
| `_oauth.py` | Isolated `CLAUDE_CONFIG_DIR` (`<DATA_DIR>/claude/`), browser-OAuth bridge, binary install. |
-| `_handlers.py` | WebSocket handlers (`cli_login` / `cli_auth_status`). |
+| `_handlers.py` | WebSocket handlers `claude_code_login` (line 103) / `claude_code_logout` (line 140), exported through `WS_HANDLERS`. |
## See also
diff --git a/docs-internal/claude_code_interactive_mode.md b/docs-internal/claude_code_interactive_mode.md
index 0f486d45..0539b566 100644
--- a/docs-internal/claude_code_interactive_mode.md
+++ b/docs-internal/claude_code_interactive_mode.md
@@ -1,7 +1,9 @@
# Claude Code interactive mode (subprocess + stream-json)
> **TL;DR.** `ClaudeSessionPool` keeps a warm `claude` subprocess per
-> `simpleMemory.node_id` and drives it with the same flags Anthropic's
+> session key (the RFC-0002 conversation key `context_bridge.pool_key` when
+> a Context node is wired; the legacy `simpleMemory.node_id` on immutable V1
+> graphs — `services/cli_agent/service.py:354-358`) and drives it with the same flags Anthropic's
> own VSCode extension uses — stdio pipes, `--output-format stream-json
> --input-format stream-json --verbose --ide`. Multi-turn happens by
> writing newline-delimited JSON to `proc.stdin` of the long-lived
@@ -294,11 +296,14 @@ allowlist is:
agent to load every skill through the `getSkill` MCP round-trip)
is materially worse UX for the common case where the workflow
pre-wired which skills should be on the table.
-- The five OpenCompany MCP infrastructure tools — `getWorkspaceFiles`,
- `listSkills`, `getSkill`, `getCredential`, `broadcastLog` — which
- are how the agent reads its workspace, discovers connected skills
- (when no wiring is present), fetches scoped credentials, and
- surfaces intermediate progress to the FE.
+- The seven OpenCompany MCP infrastructure tools — `getWorkspaceFiles`,
+ `listSkills`, `getSkill`, `readSkillResource`, `searchSkillResource`,
+ `getCredential`, `broadcastLog` (`_provider.py:275-283`; defined in
+ `services/cli_agent/mcp_server.py:359-560`) — which are how the agent
+ reads its workspace, discovers connected skills (when no wiring is
+ present), pages through and searches a loaded skill's declared
+ resources, fetches scoped credentials, and surfaces intermediate
+ progress to the FE.
Callers wanting specific claude built-ins back in opt in per-task via
`ClaudeTaskSpec.allowed_tools` (the field is honored verbatim — no
@@ -372,8 +377,9 @@ with `cwd=repo_root` (stable for `--continue`'s `project_key`
resolution) and non-memory runs with `cwd=worktree`, neither of which
sees files dropped by upstream nodes (`fileDownloader`,
`documentParser`, code executors, etc.). Mirrors the ai_agent
-pattern ([`services/ai.py:1899`](../server/services/ai.py) —
-`config['workspace_dir'] = context.get('workspace_dir', '')`) but
+pattern ([`services/ai.py:1186`](../server/services/ai.py) in
+`execute_agent`, `:1924` in `execute_chat_agent` —
+`config["workspace_dir"] = context.get("workspace_dir", "")`) but
uses claude's native `--add-dir` instead of MCP-tool-config injection
because claude has its own filesystem tools (`Read`, `Edit`, `Glob`,
`Grep`, `Write`, `Bash`) rather than MCP-injected ones. Verified
diff --git a/docs-internal/cli_agent_canonical_patterns_rfc.md b/docs-internal/cli_agent_canonical_patterns_rfc.md
index 1218a65a..aa4051dd 100644
--- a/docs-internal/cli_agent_canonical_patterns_rfc.md
+++ b/docs-internal/cli_agent_canonical_patterns_rfc.md
@@ -202,7 +202,7 @@ Source: [mcp#output-size](https://code.claude.com/docs/en/mcp).
500,000 chars).
- Server name `workspace` is reserved.
-## 3. The four invariants (revised)
+## 3. The six invariants (revised)
Across the official documentation:
@@ -289,9 +289,12 @@ stream-json`, `--verbose`, `--ide`, `--model`, `--permission-mode`,
**Conditional:** `--mcp-config <json>` + `--strict-mcp-config` (when
`mcp_endpoint_url` and `mcp_bearer_token` set), `--continue`/`--resume`
-(memory-bound runs, mutually exclusive), `--max-budget-usd`,
-`--append-system-prompt`, `--effort`, `--fallback-model`, `--add-dir`,
-`--disallowedTools`, `--agent`.
+(memory-bound runs, mutually exclusive), `--append-system-prompt`,
+`--effort`, `--add-dir`, `--disallowedTools`, `--agent`.
+
+**Never emitted** (`_provider.py:316-320`): `--max-turns`,
+`--max-budget-usd`, `--fallback-model` — all `-p`-only. `ClaudeTaskSpec`
+keeps the fields for back-compat and `interactive_argv` silently drops them.
### 4.2 `--mcp-config` JSON shape
@@ -328,10 +331,14 @@ Skill # only when >=1 skill is wired
mcp__opencompany__getWorkspaceFiles,
mcp__opencompany__listSkills,
mcp__opencompany__getSkill,
+mcp__opencompany__readSkillResource,
+mcp__opencompany__searchSkillResource,
mcp__opencompany__getCredential,
mcp__opencompany__broadcastLog
```
+(`_provider.py:275-283`.)
+
**Post-cutover: strict MCP-only allowlist (gated by `--permission-mode
dontAsk`).** Claude's built-in escape hatches (`Read`, `Edit`, `Bash`,
`Glob`, `Grep`, `Write`, `WebSearch`, `WebFetch`) are intentionally NOT
@@ -351,7 +358,7 @@ built-in fallbacks. Locked by
### 4.4 IDE lockfile
-[`lockfile.py:64-82`](../server/services/cli_agent/lockfile.py): writes
+[`lockfile.py:64-79`](../server/services/cli_agent/lockfile.py): writes
```json
{"port": <int>,
@@ -379,8 +386,12 @@ path today.
[`mcp_server.py`](../server/services/cli_agent/mcp_server.py),
[`workflow_tools.py`](../server/services/cli_agent/workflow_tools.py):
-5 built-in: `getWorkspaceFiles`, `listSkills`, `getSkill`,
-`getCredential`, `broadcastLog`.
+7 built-in (`mcp_server.py:359-560`): `getWorkspaceFiles`, `listSkills`,
+`getSkill`, `readSkillResource`, `searchSkillResource`, `getCredential`,
+`broadcastLog`. The three skill tools dispatch through
+`skill_runtime.execute_skill_tool` (`load` / `read_resource` /
+`search_resource`) so the CLI agent gets the same progressive-disclosure
+contract as the native `Skill` tool.
Plus dynamic per-batch: one `mcp__opencompany__<node_type>` per connected
workflow tool (refcount-tracked, schema inferred from plugin's Pydantic
`Params` field-for-field).
@@ -486,7 +497,7 @@ documented project-instruction surface.
| **I-2** MCP transport | **Aligned.** Streamable-HTTP via `--mcp-config`. | None. |
| **I-3** `list_changed` notification | **DONE (`b40011e`).** [`workflow_tools._schedule_list_changed_notify`](../server/services/cli_agent/workflow_tools.py) fires after each `add_tool` / `remove_tool` since FastMCP doesn't emit it automatically. | Optional: unit test asserting `session.send_tool_list_changed` is called. |
| **I-4** Tool-search deferral | **DONE.** `"alwaysLoad": true` set on the `opencompany` server entry in [`claude_code_agent/_provider.py::interactive_argv`](../server/nodes/agent/claude_code_agent/_provider.py). | None. |
-| **I-5** Visible-tool filtering | **Gap.** All 5 built-in OpenCompany MCP tools (including `getCredential`, `broadcastLog`) are visible to the model. | Mark internal-only tools `_meta["anthropic/alwaysLoad"]: false` or filter via FastMCP middleware. **Defer** — not breaking today. |
+| **I-5** Visible-tool filtering | **Gap.** All 7 built-in OpenCompany MCP tools (including `getCredential`, `broadcastLog`) are visible to the model. | Mark internal-only tools `_meta["anthropic/alwaysLoad"]: false` or filter via FastMCP middleware. **Defer** — not breaking today. |
| **I-6** Native session continuity | **DONE.** [`session.py`](../server/services/cli_agent/session.py) keeps a stable cwd for memory-bound spawns; the warm-subprocess pool at [`claude_code_agent/_pool.py`](../server/nodes/agent/claude_code_agent/_pool.py) preserves the session across turns. [`claude_code_agent/__init__.py`](../server/nodes/agent/claude_code_agent/__init__.py) sets `continue_session = bool(memory_data)` → argv emits `--continue` (first cold spawn) with `--resume <UUID>` reserved for crash recovery. [`service.py:_persist_memory`](../server/services/cli_agent/service.py) appends turns to `memory_content`, saves `last_session_id` (display-only), broadcasts `node_parameters_updated`, and auto-clears stale UUIDs via `_clear_stale_session_id`. See §4.8. | Markdown `memory_content` remains the UI mirror, not the resume channel. |
| **System-prompt directive** (Cursor / `CLAUDE.md` pattern) | **DONE (`b40011e`).** Second `--append-system-prompt` listing connected `mcp__opencompany__*` tools. | None. |
| `--allowedTools` strict MCP-only allowlist | **DONE (superseded R3).** Built-in escape hatches (`Read`/`Edit`/`Bash`/`Glob`/`Grep`/`Write`/`WebSearch`/`WebFetch`) are NOT in the default allowlist; `Skill` is added conditionally (only when a skill is wired). `default_allowed_tools: ""` in [`ai_cli_providers.json`](../server/config/ai_cli_providers.json); allowlist assembled in [`_provider.py::interactive_argv`](../server/nodes/agent/claude_code_agent/_provider.py). Gated by `--permission-mode dontAsk`. | None. |
@@ -514,7 +525,7 @@ The current design instead ships a strict **MCP-only** allowlist:
`default_allowed_tools: ""` in
[`ai_cli_providers.json`](../server/config/ai_cli_providers.json), and
[`_provider.py::interactive_argv`](../server/nodes/agent/claude_code_agent/_provider.py)
-assembles `mcp__opencompany__<node_type>` per wired tool + the 5 infra MCP
+assembles `mcp__opencompany__<node_type>` per wired tool + the 7 infra MCP
tools + the built-in `Skill` (conditionally, when a skill is wired),
gated by `--permission-mode dontAsk`. `WebSearch`/`WebFetch`/`Bash`/etc.
are intentionally excluded — equivalent capability is wired explicitly
diff --git a/docs-internal/cli_agent_framework.md b/docs-internal/cli_agent_framework.md
index 4d04c866..e818fbb3 100644
--- a/docs-internal/cli_agent_framework.md
+++ b/docs-internal/cli_agent_framework.md
@@ -20,7 +20,7 @@ AICliService.run_batch(provider, tasks, *, node_id, workflow_id, workspace_dir)
│ asyncio.gather under Semaphore(5)
│
├──► AICliSession_0 (BaseProcessSupervisor + ClaudeProvider + ClaudeTaskSpec)
- │ _pre_spawn(): git worktree add + write ~/.claude/ide/<pid>.lock
+ │ _pre_spawn(): git worktree add + write <DATA_DIR>/claude/ide/<pid>.lock
│ _do_start(): anyio.open_process + NDJSON stdout/stderr consumers
│ env: CLAUDE_IDE_LOCK + OPENCOMPANY_PARENT_RUN_ID
│ wait_for_completion(timeout)
@@ -29,22 +29,23 @@ AICliService.run_batch(provider, tasks, *, node_id, workflow_id, workspace_dir)
└──► AICliSession_N (CodexProvider + CodexTaskSpec)
(no lockfile yet — Codex CLI doesn't honor it; written when upstream supports it)
│
- │ ◄──── CLI calls back via MCP/HTTP at /mcp/ide
+ │ ◄──── CLI calls back via MCP/HTTP at /mcp/ide/mcp
│ Authorization: Bearer <batch-token> (per-batch isolation)
- │ tools: getWorkspaceFiles, listSkills, getSkill, getCredential, broadcastLog
+ │ tools: getWorkspaceFiles, listSkills, getSkill, readSkillResource,
+ │ searchSkillResource, getCredential, broadcastLog
▼
BatchResult { tasks: [SessionResult, ...], n_succeeded, n_failed, total_cost_usd?, wall_clock_ms }
│ token deregistered in finally
▼
-existing Temporal heartbeat fires per WS broadcast (services/temporal/activities.py:228)
-existing tool-result envelope truncates response at 4000 chars (services/handlers/tools.py:678)
+existing Temporal heartbeat fires per WS broadcast (services/temporal/activities.py:259)
+existing tool-result envelope truncates response at 4000 chars (services/handlers/tools.py:993)
```
Reuses (do not duplicate):
- `services/_supervisor/{base,process,util}.py` — `BaseProcessSupervisor` (locked start/stop, `kill_tree`, `terminate_then_kill(5s)`, drain tasks, Windows `CTRL_BREAK_EVENT`)
-- `services/llm/{protocol,factory,config}.py` — Protocol + lazy-import factory + JSON config blueprint
-- `services/handlers/tools.py:678` — 4000-char truncation
+- `services/llm/{protocol,registry,config}.py` — Protocol + lazy `register_provider(ProviderSpec)` registry + JSON config blueprint (the old `llm/factory.py` was removed)
+- `services/handlers/tools.py:993` — 4000-char truncation
- `services/status_broadcaster.py` — `update_node_status`, `broadcast_terminal_log`
- `services/skill_loader.py` — `scan_skills` / `load_skill` consumed by MCP `listSkills` / `getSkill`
- `services/auth.py` — `AuthService.get_api_key` consumed by MCP `getCredential`
@@ -62,7 +63,7 @@ class AICliProvider(Protocol):
package_name: str
binary_name: str
ide_lock_env_var: Optional[str] # CLAUDE_IDE_LOCK | GEMINI_IDE_LOCK | None
- ide_lockfile_dir: Optional[Path] # ~/.claude/ide | <tmpdir>/gemini/ide
+ ide_lockfile_dir: Optional[Path] # <DATA_DIR>/claude/ide | <tmpdir>/gemini/ide
def binary_path(self) -> Path: ...
def interactive_argv(self, task, *, defaults) -> list[str]: ...
@@ -85,8 +86,8 @@ class AICliProvider(Protocol):
### Claude argv (`AnthropicClaudeProvider.interactive_argv`)
Spawned per task — the binary path comes from
-`services.claude_oauth.claude_binary_path()` (the same project-local
-install the credentials Login button uses) and `CLAUDE_CONFIG_DIR` is
+`nodes.agent.claude_code_agent._oauth.claude_binary_path()` (`_oauth.py:82`;
+the same project-local install the credentials Login button uses) and `CLAUDE_CONFIG_DIR` is
injected on the spawn env so the agent shares one credential store with
the auth surface.
@@ -124,25 +125,33 @@ back-compat; they're silently dropped in `interactive_argv`.
All flags documented at
[code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference).
Worktree, lockfile, and bearer-token MCP server are wired in
-`session_pool.py:_spawn`; the `--ide` flag tells the CLI to discover
-that lockfile via `CLAUDE_IDE_LOCK`.
+`nodes/agent/claude_code_agent/_pool.py:_spawn` (pool path) and
+`services/cli_agent/session.py:_pre_spawn` (non-pool path); the `--ide`
+flag tells the CLI to discover that lockfile via `CLAUDE_IDE_LOCK`.
The non-pooled `AICliSession` path (one-shot prompt-in-argv runs that
don't need session reuse) still uses PTY (`ptyprocess` POSIX /
`pywinpty>=3.0.3` Windows) and remains out of scope for the
subprocess+stream-json refactor.
-Factory:
+Factory — a registry lookup, not a hardcoded branch per provider. Each plugin
+calls `register_provider(name, factory)` on import (claude from
+`nodes/agent/claude_code_agent/__init__.py`, codex from
+`services/cli_agent/__init__.py`); re-registering a different factory under an
+existing name raises:
```python
-# server/services/cli_agent/factory.py
-SUPPORTED_PROVIDERS = frozenset({"claude", "codex"}) # gemini is v2 stub
-
+# server/services/cli_agent/factory.py:84-106
def create_cli_provider(name: str) -> AICliProvider:
- if name == "claude": return AnthropicClaudeProvider()
- if name == "codex": return OpenAICodexProvider()
- if name == "gemini": raise NotImplementedError("gemini deferred to v2")
- raise ValueError(f"Unknown CLI provider: {name!r}")
+ factory = _PROVIDER_REGISTRY.get(name)
+ if factory is not None:
+ return factory()
+ if name == "gemini": # known-but-deferred, so the dropdown can grey it out
+ raise NotImplementedError("gemini provider deferred to v2. Use 'claude' or 'codex' in v1.")
+ raise ValueError(f"Unknown CLI provider: {name!r}. Registered: {sorted(_PROVIDER_REGISTRY)}. ...")
+
+is_supported(name) # name in _PROVIDER_REGISTRY
+registered_provider_names() # frozenset snapshot
```
## Task specs (discriminated union)
@@ -194,7 +203,7 @@ AICliTaskSpec = Annotated[
]
```
-Each plugin's `Params.tasks` is hard-typed to one variant — the LLM tool-schema fast-path at `services/ai.py:2898` produces a clean per-provider schema (no `$defs`/`$ref`).
+Each plugin's `Params.tasks` is hard-typed to one variant — the LLM tool-schema plugin fast-path in `_get_tool_schema` (`services/ai.py:2584`) produces a clean per-provider schema (no `$defs`/`$ref`).
## Auth model — Stripe-style CLI-managed OAuth
@@ -207,7 +216,7 @@ CLI auth is delegated to the CLI's own login flow + a synthetic marker token in
| `claude_code` | `claude_code_login` | `claude_code_logout` |
| `codex_cli` | `codex_cli_login` (returns "not yet wired") | `codex_cli_logout` |
-**Claude flow** (`server/services/cli_agent/_handlers.py:handle_claude_code_login`) uses the documented CLI subcommands from [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference):
+**Claude flow** (`server/nodes/agent/claude_code_agent/_handlers.py:103`, `handle_claude_code_login`; logout at `:140`) uses the documented CLI subcommands from [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference):
| Subcommand | Purpose |
|---|---|
@@ -233,20 +242,22 @@ Steps:
Spawned CLI sessions auto-discover OpenCompany over MCP via the lockfile pattern VSCode's Claude Code extension uses. No custom IPC.
-Lockfile path: `~/.claude/ide/<pid>.lock` (Claude) or `<tmpdir>/gemini/ide/gemini-ide-server-<pid>-<port>.json` (Gemini, v2). Format mirrors VSCode exactly:
+Lockfile path: `<DATA_DIR>/claude/ide/<pid>.lock` (Claude — `AnthropicClaudeProvider.ide_lockfile_dir = OPENCOMPANY_CLAUDE_DIR / "ide"`, so it sits under the isolated `CLAUDE_CONFIG_DIR`, not the user's `~/.claude/`) or `<tmpdir>/gemini/ide/gemini-ide-server-<pid>-<port>.json` (Gemini, v2). Format mirrors VSCode (`lockfile.py:64-79`):
```json
{
- "port": 5678,
- "url": "http://127.0.0.1:5678/mcp/ide",
+ "port": <PYTHON_BACKEND_PORT>,
+ "url": "http://127.0.0.1:<PYTHON_BACKEND_PORT>/mcp/ide/mcp",
"authToken": "<32-byte hex>",
- "workspaceFolders": ["<absolute path to per-task git worktree>"],
- "ideName": "opencompany",
+ "workspaceFolders": ["<repo_root for memory-bound runs, else the per-task git worktree>"],
+ "ideName": "claude",
"transport": "http",
"pid": 12345
}
```
+Two fields are load-bearing. The `url` MUST end in `/mcp/ide/mcp`: FastMCP's `streamable_http_app()` registers the JSON-RPC route at `/mcp` of the sub-app and `main.py` mounts the sub-app at `/mcp/ide`, so the older `/mcp/ide` form silently 404'd before the request reached the bearer-token middleware (`lockfile.py:64-70`). `ideName` is the provider name (`session.py:281` passes `self._provider.name`, which is `"claude"`), not `"opencompany"`.
+
Bearer-token middleware (`mcp_server.py:_BearerAuthMiddleware`) validates each request against an in-memory per-batch `BatchContext` registry. **Non-pool path**: tokens registered at `AICliService.run_batch()` entry, unregistered in `finally` so 401s flip immediately when a batch settles. **Pool path** (`use_pool=True`, see [Claude Code Interactive Mode](./claude_code_interactive_mode.md#mcp-bearer-token-lifecycle) for the full lifecycle): claude bakes the bearer into argv (`--mcp-config`) at spawn time and can't rotate without respawning, so the pool stashes the spawn-time token on `PooledClaudeSession.batch_token` and rebinds the `BatchContext` in place on warm reuse via `rebind_batch(token, connected_tools=..., ...)` — closes the "disconnected tool still works" leak by (a) diffing `connected_tools` and decrementing FastMCP refcounts for tools dropped between batches, and (b) updating the per-handler scope check's data so `workflow_tools._build_handler` returns 403 for stale tools. `_terminate_locked` calls `unregister_batch(session.batch_token)` so refcounts drain on pool eviction / `clear` / `shutdown_all`.
Tools exposed (mirror OpenCompany capabilities; deferred ones marked):
@@ -255,7 +266,9 @@ Tools exposed (mirror OpenCompany capabilities; deferred ones marked):
|---|---|---|
| `mcp__opencompany__getWorkspaceFiles` | `Path.rglob` over `workspace_dir` | `{files: [{path, size, mtime, content?}]}` |
| `mcp__opencompany__listSkills` | `SkillLoader.scan_skills()` filtered to `BatchContext.connected_skill_names` | `{skills: [{name, description, allowed_tools, category}]}` (~100 tokens each) |
-| `mcp__opencompany__getSkill` | `SkillLoader.load_skill(name)` | `{name, instructions, allowed_tools, scripts, references}` |
+| `mcp__opencompany__getSkill` | `skill_runtime.execute_skill_tool(action="load")` for a skill in `BatchContext.connected_skill_names` | Skill `load` result: instructions + resource manifest |
+| `mcp__opencompany__readSkillResource` | `execute_skill_tool(action="read_resource", path, cursor, limit=4000)` | Bounded page of a declared resource from a loaded skill |
+| `mcp__opencompany__searchSkillResource` | `execute_skill_tool(action="search_resource", path, query, cursor, limit=20)` | Line-numbered matches in a declared text resource |
| `mcp__opencompany__getCredential` | `auth_service.get_api_key(name)`, gated by `BatchContext.allowed_credentials` | `{name, value}` or 403 |
| `mcp__opencompany__broadcastLog` | `broadcaster.broadcast_terminal_log()` | `{success}` |
@@ -275,7 +288,8 @@ Shared by every CLI provider plugin. Imports nothing from `nodes/`.
| `config.py` | Loads `server/config/ai_cli_providers.json` (binary, package, defaults, supports flags per provider). |
| `factory.py` | Three registries (`register_provider`, `register_session_pool`, `register_skill_materialiser`) + lookups + `create_cli_provider(name)`. |
| `lockfile.py` | VSCode-style IDE lockfile read/write/sweep. |
-| `mcp_server.py` | FastMCP sub-app at `/mcp/ide` with bearer-token middleware + 5 tools + `rebind_batch` for warm-reuse context updates. |
+| `mcp_server.py` | FastMCP sub-app mounted at `/mcp/ide` (JSON-RPC endpoint `/mcp/ide/mcp`) with bearer-token middleware + 7 infrastructure tools (`getWorkspaceFiles`, `listSkills`, `getSkill`, `readSkillResource`, `searchSkillResource`, `getCredential`, `broadcastLog`) + `rebind_batch` for warm-reuse context updates. |
+| `context_bridge.py` | `SpecializedAgentContextBridge` — RFC-0002 Context continuity for specialized providers (`resolve` / `augment_prompt` / `record_turn`); shared with RLM and Vertex. |
| `workflow_tools.py` | Per-batch MCP tool exposure (`mcp__opencompany__<node_type>`) + handler scope check + `tools/list_changed` notify. |
| `session.py` | `AICliSession(BaseProcessSupervisor)` — generic non-pool path (still PTY on POSIX). |
| `service.py` | `AICliService.run_batch()` — dispatcher; routes to pool when memory-bound via `factory.get_session_pool(provider_name)`. |
@@ -309,7 +323,6 @@ the reference implementation). Four self-registration calls in
| `server/nodes/agent/codex_agent/__init__.py` | Codex node plugin — `Params.tasks: list[CodexTaskSpec]`. (Provider class still lives in `services/cli_agent/providers/openai_codex.py` until this folder adopts the per-folder layout.) |
| `server/nodes/visuals.json` | `claude_code_agent` + `codex_agent` icon/color entries. |
| `server/config/credential_providers.json` | `_cli_base` abstract + `claude_code` + `codex_cli` entries. |
-| `server/services/claude_code_service.py` | Slimmed back-compat shim — builds one `ClaudeTaskSpec` and calls `AICliService.run_batch("claude", ...)`. Eventually deletable. |
| `server/services/workflow.py` | `cancel_deployment` calls `get_ai_cli_service().cancel_workflow(workflow_id)`. |
| `server/main.py` | Mounts `/mcp/ide` sub-app, composes its lifespan, runs stale-lockfile sweep on startup. Side-effect imports `services.cli_agent` so its WS handlers self-register. Claude's plugin folder is discovered separately by the node registry. |
| `server/routers/websocket.py` | No CLI handlers inline — discovered via `services.ws_handler_registry.get_ws_handlers()`. |
@@ -359,7 +372,7 @@ the reference implementation). Four self-registration calls in
> See [memory_lifecycle.md](./memory_lifecycle.md) for the shared markdown surface (every agent uses the same `parse_memory_markdown` / `append_to_memory_markdown` / `trim_markdown_window` helpers to maintain `simpleMemory.memory_content`). This section documents what's UNIQUE to `claude_code_agent`: the markdown is the UI mirror, not the resume channel.
Connecting a `simpleMemory` node to a `claude_code_agent` makes the
-spawned `claude -p` resume its prior session natively across runs.
+spawned `claude` subprocess resume its prior session natively across runs.
**No system-prompt injection, no JSONL synthesis, no API fallback.**
Claude maintains its own session JSONL on disk under
`<CLAUDE_CONFIG_DIR>/projects/<project_key>/<session_id>.jsonl`; we
@@ -402,18 +415,27 @@ intentionally NOT emitted in interactive mode — claude rejects it.
### Plumbing
```
-ClaudeCodeAgentNode.execute_op
- ├─ collect_agent_connections() → memory_data {node_id, session_id,
- │ memory_content, window_size,
- │ long_term_enabled,
- │ last_session_id (display-only)}
+ClaudeCodeAgentNode.execute_op (__init__.py:291-330)
+ ├─ collect_agent_connections() → context_data (first tuple element)
+ │ ├─ V2 graphs: a Context descriptor (kind == "context") → context_v2,
+ │ │ handed to AICliService as connected_context and bridged through
+ │ │ SpecializedAgentContextBridge; memory_data stays None
+ │ └─ immutable V1 snapshots: the legacy Memory descriptor → memory_data
+ │ {node_id, session_id, memory_content, window_size,
+ │ long_term_enabled, last_session_id (display-only)}
├─ continue_session = bool(memory_data)
├─ ClaudeTaskSpec(..., continue_session=continue_session,
│ resume_session_id=None)
└─ AICliService.run_batch(..., connected_memory=memory_data,
broadcaster=...)
- └─ For memory-wired runs, route through ClaudeSessionPool:
- ├─ pool.acquire(memory_node_id, spec, cwd=repo_root, env, ...)
+ └─ For context/memory-wired single-task runs, route through ClaudeSessionPool
+ (service.py:343-358 — use_pool = claude AND one task AND
+ (connected_memory OR a Context bridge)):
+ ├─ pool.acquire(session_key, spec, cwd=repo_root, env, ...)
+ │ session_key = context_bridge.pool_key on V2 graphs (the
+ │ RFC-0002 conversation key, so a Reset's generation bump
+ │ fences the warm subprocess), else the legacy
+ │ connected_memory["node_id"]
│ ├─ cold: spawn `claude --output-format stream-json
│ │ --input-format stream-json --verbose --ide
│ │ --continue ...` as subprocess with stdio pipes;
@@ -525,16 +547,15 @@ Plus `broadcast_terminal_log(source=f"{provider}:{task_id}", level)` on every ND
To add a fourth provider (e.g. Mistral CLI) post-v1:
-1. New file `server/services/cli_agent/providers/<vendor>.py` implementing `AICliProvider`.
+1. New plugin folder `server/nodes/agent/<vendor>_agent/` rooted at `__init__.py` (mirror `nodes/agent/claude_code_agent/`; `codex_agent/` is the smaller example whose provider class still lives under `services/cli_agent/providers/`). Put the provider (`_provider.py`, implementing `AICliProvider`), any pool, and the WS handlers (`_handlers.py`, login + logout) in that folder.
2. New entry in `server/config/ai_cli_providers.json`.
3. New `<vendor>TaskSpec` in `types.py` + register in the discriminated union.
-4. New branch in `factory.create_cli_provider`.
+4. Call `register_provider("<vendor>", <ProviderClass>)` (and `register_session_pool` / `register_skill_materialiser` if applicable) from the plugin's `__init__.py` — there is no branch to add in `factory.create_cli_provider`; it is a registry lookup.
5. New entry in `server/config/credential_providers.json` (`extends: "_cli_base"`).
-6. New per-provider WS handlers in `_handlers.py` (login + logout) + entry in `WS_HANDLERS`.
-7. New plugin file `server/nodes/agent/<vendor>_agent.py` (mirror `codex_agent.py`).
-8. New entry in `server/nodes/visuals.json`.
+6. `register_ws_handlers({...})` from the plugin's `__init__.py` for the login/logout handlers.
+7. `meta.json` (+ `icon.svg`) in the plugin folder, or a `server/nodes/visuals.json` entry as the legacy fallback.
-No edits to `routers/websocket.py`, `main.py`, or any existing handler/service. The plugin auto-registers via `BaseNode.__init_subclass__` (Wave 11) + the `services.ws_handler_registry` self-registration in `cli_agent/__init__.py`.
+No edits to `routers/websocket.py`, `main.py`, `services/cli_agent/`, or any existing handler/service. The plugin auto-registers via `BaseNode.__init_subclass__` (Wave 11) + the `services.ws_handler_registry` self-registration from its own `__init__.py`.
## Verification
@@ -552,13 +573,13 @@ Live verification (needs a real Claude install + auth):
2. Refresh the page. Modal stays Connected (`auth_service.get_oauth_tokens("claude_code")` still returns the marker; idempotent re-click also stays Connected).
3. Click Disconnect. Modal flips Disconnected (`claude auth logout` clears CLI creds + marker dropped).
4. Add a `claude_code_agent` node, set `tasks=[{prompt:"echo A"},{prompt:"echo B"},{prompt:"echo C"}]`, run. Three distinct `claude:<task_id>` Terminal streams interleaved. Three distinct session_ids. Three worktrees created and removed. `summary.wall_clock_ms < sum(duration_ms)` (proves parallelism).
-5. With a Claude task running, `cat ~/.claude/ide/<pid>.lock` and confirm format. Stream-json shows an `mcp__opencompany__*` tool invocation.
-6. `curl -H "Authorization: Bearer <wrong>" http://127.0.0.1:5678/mcp/ide/...` → 401.
+5. With a Claude task running, `cat ~/.opencompany/claude/ide/<pid>.lock` and confirm format. Stream-json shows an `mcp__opencompany__*` tool invocation.
+6. `curl -H "Authorization: Bearer <wrong>" http://127.0.0.1:${PYTHON_BACKEND_PORT}/mcp/ide/mcp` → 401.
## Risks / open considerations
- **Codex login not yet wired.** v1 returns a graceful error directing the user to `npm install -g @openai/codex` + `codex login`. Follow-up: a codex `_oauth.py` mirroring `nodes/agent/claude_code_agent/_oauth.py` with a `HOME=<DATA_DIR>/codex/` env redirect (Codex has no `CONFIG_DIR` env; `HOME` redirect is risky on Windows, so Windows may need a different strategy or accept user-global Codex auth).
-- **Gemini deferred.** `factory.create_cli_provider("gemini")` raises `NotImplementedError`. v2 work: implement `providers/google_gemini.py`, drop the factory branch, add `nodes/agent/gemini_cli_agent.py`. ~430 LoC. No abstraction changes needed.
+- **Gemini deferred.** `factory.create_cli_provider("gemini")` raises `NotImplementedError` (the one name-specific branch left in the factory, kept so the dropdown can grey it out). v2 work: implement the provider, register it from a `nodes/agent/gemini_cli_agent/` plugin folder, and drop that branch. ~430 LoC. No abstraction changes needed.
- **`--include-partial-messages`** assumes a recent Claude CLI; older versions fall back gracefully via the parser's `parse_event` returning `None` for unknown shapes.
- **Native-binary stdin sensitivity.** claude-code >= 2.1.162 ships a native binary that reads stdin during `auth login`. We spawn it with `stdin=asyncio.subprocess.PIPE` (never written) so the read blocks and the OAuth callback server stays alive; an inherited/closed stdin EOFs the binary into an early exit that drops the browser callback. If a future CLI version changes its stdin contract this is the spot to revisit.
- **Marker token written without verifying CLI is actually functional** — we trust `claude auth status`'s exit code. If Anthropic invalidates the token server-side and the CLI hasn't re-checked, the modal still shows Connected until the next session attempt's `detect_auth_error` catches it.
diff --git a/docs-internal/cli_services_integration.md b/docs-internal/cli_services_integration.md
index f342d496..4f5007da 100644
--- a/docs-internal/cli_services_integration.md
+++ b/docs-internal/cli_services_integration.md
@@ -17,24 +17,24 @@ Wraps the official `temporal` CLI's `server start-dev` mode (per [docs.temporal.
**Install:** Automated. `company build` step [6/6] runs `python -m services.temporal._install`, which uses `pooch` to download the official CLI archive from `https://temporal.download/cli/archive/latest?platform=<os>&arch=<arch>` into `<DATA_DIR>/packages/temporal/` (= `~/.opencompany/packages/temporal/` by default, on every OS — via `core.paths.package_dir("temporal")`). No npm package, no system install required.
-**Lifecycle:** Backend-owned (July 2026): the FastAPI lifespan starts the dev server via `TemporalServerRuntime.ensure_started()` ([server/services/temporal/_runtime.py](../server/services/temporal/_runtime.py)) when `TEMPORAL_ENABLED` and the configured address is loopback; `shutdown_all_supervisors()` stops it at shutdown. The CLI no longer supervises Temporal (the `_supervised_runtime.py` shim and `cli/commands/_temporal_specs.py` were deleted); `company stop` still frees the Temporal ports.
+**Lifecycle:** Backend-owned (July 2026): the FastAPI lifespan starts the dev server via `TemporalServerRuntime.ensure_started()` ([server/services/temporal/_runtime.py](../server/services/temporal/_runtime.py)) when `TEMPORAL_ENABLED` and the configured address is loopback; `shutdown_all_supervisors()` stops it at shutdown. The CLI no longer supervises Temporal (the `_supervised_runtime.py` shim and the `_temporal_specs.py` command helpers were deleted); `company stop` still frees the Temporal ports.
**Ports (declared in `.env.template`, freed by `company stop`'s port-kill pre-flight):**
-| Service | Port | Env var |
+| Service | Env var (value in `.env.template`) | Note |
|---------|------|---------|
-| gRPC | 5681 | `TEMPORAL_FRONTEND_GRPC_PORT` |
-| Web UI | 5680 | `TEMPORAL_UI_PORT` (CLI default is 8233; we override) |
+| gRPC | `TEMPORAL_FRONTEND_GRPC_PORT` | passed as `--port` (Temporal's own default is 7233) |
+| Web UI | `TEMPORAL_UI_PORT` | passed as `--ui-port` (the CLI would otherwise pick `--port + 1000`) |
Both bound by the same `temporal.exe` process. Killing the process releases both.
**Persistence + resumption:**
- SQLite db at `~/.opencompany/temporal.db` (`TEMPORAL_SQLITE_PATH=temporal.db`, resolved under `DATA_DIR`). History is preserved across restarts; the Temporal UI keeps showing every workflow that ever ran.
-- Workflow auto-resumption is disabled at boot: [`TemporalClientWrapper.terminate_running_workflows`](../server/services/temporal/client.py) runs once after client connect and terminates every `Running` workflow with `reason="OpenCompany startup: auto-resumption disabled"`. Workflows show as `Terminated` (not deleted) in the UI. Gated by `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP=true`. Flip to `false` once `DeploymentManager` reconcile-against-Visibility lands.
+- Running and paused deployments survive restarts. `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` defaults to **`false`** and the boot-time reconcile pass (`reconcile_active_controls_on_boot`) re-arms live generations from their persisted graph snapshot. Setting it `true` is a debug-only sweep: [`services/temporal/lifecycle.py`](../server/services/temporal/lifecycle.py) then calls [`TemporalClientWrapper.terminate_running_workflows`](../server/services/temporal/client.py) once after client connect (reason `"OpenCompany startup: auto-resumption disabled"`), workflows show as `Terminated` (not deleted) in the UI — and even then any active workflow-control row vetoes the sweep so a live deployment is never killed.
**Embedded worker:**
-The Temporal worker runs inside the Python backend via `TemporalWorkerManager` in `main.py` lifespan. No separate worker process needed for single-server deployments. For horizontal scaling, run standalone workers:
+The Temporal worker runs inside the Python backend: `services/temporal/lifecycle.py` builds `TemporalWorkerManager` + `TemporalWorkerPool` inside `run_temporal_lifecycle`, which `main.py` schedules from the lifespan. No separate worker process needed for single-server deployments. For horizontal scaling, run standalone workers:
```bash
-cd server && python -m services.temporal.worker
+cd server && uv run python -m services.temporal.worker
```
---
diff --git a/docs-internal/cloudflare_service.md b/docs-internal/cloudflare_service.md
index 9a35556d..6cfe1bcc 100644
--- a/docs-internal/cloudflare_service.md
+++ b/docs-internal/cloudflare_service.md
@@ -17,7 +17,7 @@ grant** that makes the optional API token the only path to analytics.
| Auth | Dual-path: cf-owned OAuth login OR optional `cloudflare_api_token` field -> `CLOUDFLARE_API_TOKEN` env |
| Task queue | `TaskQueue.REST_API` |
| Output | `ui_hints = {"outputMode": "terminal"}`; `_shape` contract (parsed JSON -> `result`, text -> `stdout`, never both) + NDJSON recovery |
-| Tests | [`server/tests/test_cloudflare_plugin.py`](../server/tests/test_cloudflare_plugin.py) (35 contract tests) |
+| Tests | [`server/tests/test_cloudflare_plugin.py`](../server/tests/test_cloudflare_plugin.py) (42 contract tests at time of writing; `pytest --collect-only -q`) |
| Paired skill | [`server/skills/cloudflare/cloudflare-skill/SKILL.md`](../server/skills/cloudflare/cloudflare-skill/SKILL.md) |
## Folder map
diff --git a/docs-internal/credentials_encryption.md b/docs-internal/credentials_encryption.md
index 58ecd9e7..5d6e2359 100644
--- a/docs-internal/credentials_encryption.md
+++ b/docs-internal/credentials_encryption.md
@@ -54,7 +54,7 @@ API_KEY_ENCRYPTION_KEY (from .env)
The derived Fernet key lives only in `EncryptionService._fernet` in process memory. It is never written to disk or to Redis.
-`EncryptionService` (`server/core/encryption.py`) exposes exactly five methods: `initialize(password, salt)` (derive + store the Fernet cipher), `encrypt(plaintext) -> str` (base64 ciphertext), `decrypt(ciphertext) -> str`, `clear()` (drop the in-memory key), and `is_initialized() -> bool`. `CredentialsDatabase` (`server/core/credentials_database.py`) backs both systems with `initialize() -> bytes` (creates tables, returns the salt), `save_api_key` / `get_api_key` / `delete_api_key`, and `save_oauth_tokens` / `get_oauth_tokens` / `delete_oauth_tokens(provider, customer_id="owner")`.
+`EncryptionService` (`server/core/encryption.py`) exposes `initialize(password, salt)` (derive + store the Fernet cipher), `encrypt(plaintext) -> str` (base64 ciphertext), `decrypt(ciphertext) -> str`, `clear()` (drop the in-memory key), `is_initialized() -> bool`, the lower-level `derive_key_from_password(password, salt) -> bytes` that `initialize` calls, and a static `generate_salt() -> bytes`. `CredentialsDatabase` (`server/core/credentials_database.py`) backs both systems with `initialize() -> bytes` (creates tables, returns the salt), `save_api_key` / `get_api_key` / `delete_api_key`, and `save_oauth_tokens` / `get_oauth_tokens` / `delete_oauth_tokens(provider, customer_id="owner")`.
## Lifecycle
@@ -89,7 +89,7 @@ For secrets the user enters manually in the Credentials modal (OpenAI API key, A
- Table: `EncryptedAPIKey`
- Access: `AuthService.store_api_key(provider, key, models=[...], session_id=..., model_params=...)` and `AuthService.get_api_key(provider)`
-- Cache: `AuthService._api_key_cache: Dict[str, str]`
+- Cache: `AuthService._api_key_cache: Dict[str, ApiKeyCacheEntry]` keyed `{session}_{provider}` (see "Source of Truth" below)
- **Per-model parameters** (Ollama / LM Studio): the `models` JSON column carries an optional `model_params` subkey alongside the model list — `{"models": [...], "model_params": {model_id: {context_length, vision, supports_tools, ...}}}`. Populated by [`nodes/model/_local_validator.py`](../server/nodes/model/_local_validator.py) from the official SDK probes (`ollama.AsyncClient.ps()` / `lmstudio.AsyncClient.llm.list_loaded()`) so the runtime knows the user's actual loaded n_ctx instead of guessing from `llm_defaults.json`. Read back via `AuthService.get_model_params(provider)` or `CredentialsDatabase.get_api_key_model_params(provider)`. Cloud providers leave this empty — their per-model params live in `model_registry.json` (refreshed from OpenRouter).
### 2. OAuth Token System
@@ -102,7 +102,7 @@ For tokens obtained via OAuth 2.0 flows (Google Workspace, Twitter/X, Claude.ai)
### The Mistake to Avoid
-Google access tokens live in the OAuth system, not the API key system. Reading them via `get_api_key("google_access_token")` returns None even if the user is fully logged in. All Google Workspace handlers must use `get_google_credentials()` from `server/nodes/google/_auth_helper.py` (post-Wave-11.I, this replaced the retired `server/services/handlers/google_auth.py`), which calls `get_oauth_tokens("google")` internally.
+Google access tokens live in the OAuth system, not the API key system. Reading them via `get_api_key("google_access_token")` returns None even if the user is fully logged in. All Google Workspace handlers must use `get_google_credentials()` from `server/nodes/google/_auth_helper.py` (post-Wave-11.I, this replaced the retired `google_auth.py` handler module), which calls `get_oauth_tokens("google")` internally.
Twitter has the same split: `twitter_client_id` and `twitter_client_secret` are in the API key system, but `twitter_access_token` is in the OAuth system.
@@ -165,7 +165,7 @@ aws = ["boto3>=1.34.0"] # AWS Secrets Manager
## Configuration
```env
-# server/.env
+# .env at the repo root (scaffolded from .env.template; there is no server/.env)
# Required for Fernet backend
API_KEY_ENCRYPTION_KEY=<any string, at least 32 chars for good entropy>
@@ -227,7 +227,7 @@ Pytest invariant `server/tests/credentials/test_credential_broadcasts.py` locks
## No Hand-Maintained Frontend Provider Lists
-All credential providers come from the backend `get_credential_catalogue` handler (which reads `server/config/credential_providers.json`). The retired `client/src/components/credentials/providers.tsx` static fallback is gone — adding a new provider is a backend-only change. On cold-boot the `CredentialsModal` renders a `<Skeleton>` palette while the WS catalogue arrives; on server-unreachable it shows an explicit error state, never stale fallback data.
+All credential providers come from the backend `get_credential_catalogue` handler (which reads `server/config/credential_providers.json`). The retired `providers.tsx` static fallback is gone — adding a new provider is a backend-only change. On cold-boot the `CredentialsModal` renders a `<Skeleton>` palette while the WS catalogue arrives; on server-unreachable it shows an explicit error state, never stale fallback data.
## Related Docs
diff --git a/docs-internal/deployment_legacy.md b/docs-internal/deployment_legacy.md
index 731160c6..fe9e4893 100644
--- a/docs-internal/deployment_legacy.md
+++ b/docs-internal/deployment_legacy.md
@@ -34,7 +34,7 @@ company deploy destroy # terraform des
| Path | Responsibility |
|------|----------------|
-| `cli/commands/serve.py` | Single-port runtime: uvicorn fronts API + WS + built SPA, plus the node sidecar |
+| `cli/commands/serve.py` | Single-port runtime: uvicorn fronts API + WS + built SPA. `serve` supervises exactly one process — the Node.js code-exec sidecar, WhatsApp and the Temporal dev server are backend-owned and spawn on demand |
| `cli/commands/deploy/` | Verbs (`up.py` / `status.py` / `destroy.py`), `_secrets.py`, `_state.py`, `_terraform.py` (Terraform driver), `providers/` (`gcp.py` / `aws.py` provider CLI adapters) |
| `cli/terraform/gcp/` | HCL module (`main.tf` / `variables.tf` / `outputs.tf`) + `startup.sh.tftpl` cloud-init template |
@@ -76,6 +76,11 @@ The project previously deployed using Docker Compose with an nginx reverse proxy
| frontend | opencompany-frontend | 3000 | React app via nginx |
| whatsapp | opencompany-whatsapp | 5000 | Go WhatsApp bridge service |
+Every port number in this Docker section (3000 / 3010 / 3020 / 5000 / 9400 / 6379) is the
+historical compose-era value, kept verbatim as a record. The current runtime declares its
+serial port block once in `.env.template` (`PYTHON_BACKEND_PORT`, `NODEJS_EXECUTOR_PORT`,
+`WHATSAPP_RPC_PORT`, ...); nothing below applies to it.
+
**Frontend (`client/Dockerfile`):**
- Multi-stage build: Node.js builder -> nginx:alpine production
- Serves static files via nginx on port 80 (mapped to 3000)
@@ -217,29 +222,36 @@ Located at `/etc/nginx/sites-available/flow.opencompany.sh`:
### Frontend API URL Resolution
-The frontend automatically detects production vs development. This logic still ships in
-`client/src/config/api.ts` (it is independent of the deployment mechanism):
+In the Docker era the frontend sniffed `window.location.hostname` to decide between an
+explicit `http://localhost:3010` dev backend and a same-origin production backend. That
+branch is gone. `client/src/config/api.ts` is now same-origin everywhere — in production
+uvicorn serves the SPA and the API on one port, and in dev the Vite server proxies the backend
+prefixes (`/api`, `/ws`, `/webhook`, `/health`, `/mcp`) — with `VITE_PYTHON_SERVICE_URL` left
+only as an explicit escape hatch for a remote backend:
```typescript
-// client/src/config/api.ts
-const isProduction = typeof window !== 'undefined' &&
- !window.location.hostname.includes('localhost') &&
- !window.location.hostname.includes('127.0.0.1');
-
+// client/src/config/api.ts (current)
return {
- // Python FastAPI backend (port 3010 in dev, same origin in prod)
- PYTHON_BASE_URL: viteEnv.VITE_PYTHON_SERVICE_URL || (isProduction ? '' : 'http://localhost:3010'),
+ PYTHON_BASE_URL: viteEnv.VITE_PYTHON_SERVICE_URL || '',
};
```
-- **Production**: Empty base URL = relative URLs (same origin)
-- **Development**: Explicit `http://localhost:3010`
+The historical shape, for the record:
+
+```typescript
+// client/src/config/api.ts (Docker era — no longer in the tree)
+const isProduction = typeof window !== 'undefined' &&
+ !window.location.hostname.includes('localhost') &&
+ !window.location.hostname.includes('127.0.0.1');
+PYTHON_BASE_URL: viteEnv.VITE_PYTHON_SERVICE_URL || (isProduction ? '' : 'http://localhost:3010'),
+```
-WebSocket URL derived from base URL:
+WebSocket URL derivation is unchanged and still lives in `getWebSocketUrl()`
+(`client/src/contexts/WebSocketContext.tsx`): an empty base URL means the current origin, a
+non-empty one has its `http(s)` scheme rewritten to `ws(s)`:
```typescript
// client/src/contexts/WebSocketContext.tsx
if (!baseUrl) {
- // Production: use current origin
const wsProtocol = window.location.protocol === 'https:' ? 'wss' : 'ws';
return `${wsProtocol}://${window.location.host}/ws/status`;
}
@@ -313,9 +325,12 @@ docker-compose -f docker-compose.prod.yml down -v
## Local Development Build (current, non-Docker)
```bash
-# Create optimized build
-npm run build
+# Full production build (company build: bun install, client, sidecar, uv sync, bytecode, Temporal binary)
+bun run build
+
+# Serve the built SPA + API on one port, exactly as a deployed VM does
+company start # or: company serve
-# Serve built files locally
-npm run preview
+# Vite's static preview of client/dist alone (no backend) — there is no root `preview` script
+cd client && bun run preview
```
diff --git a/docs-internal/discord_service.md b/docs-internal/discord_service.md
index a036f393..a89b70fe 100644
--- a/docs-internal/discord_service.md
+++ b/docs-internal/discord_service.md
@@ -68,7 +68,7 @@ exists to keep them apart.
**`account_id` is stripped from model arguments.** `server_controlled_fields`
is enforced only in `BaseNode.execute_as_tool`'s ToolNode branch; a dual-purpose
ActionNode takes an earlier return that merges `{**node_params, **tool_args}`
-with model arguments winning ([base.py:637-652](../server/services/plugin/base.py)).
+with model arguments winning ([base.py:653-669](../server/services/plugin/base.py)).
Since inbound Discord messages are the realistic source of hostile tool
arguments and `account_id` selects which bot identity sends, `AccountScopedNode`
in [`_base.py`](../server/nodes/discord/_base.py) removes locked fields before
@@ -253,7 +253,8 @@ filters on them and ignores the node with no listener and no warning
## Testing
[`server/tests/nodes/test_discord.py`](../server/tests/nodes/test_discord.py) —
-121 tests, no live bot required. Covers account scoping, the path guard, error
+121 collected cases (80 test functions, several parametrized; `pytest --collect-only -q`
+is the counting method), no live bot required. Covers account scoping, the path guard, error
classification, rate-limit parsing, content splitting, the tool-path account
lock, send/action shapes, event shaping, filters, gateway lifecycle, the
Ed25519 verifier, the endpoint's 401/503/PONG/defer behaviour, and route
diff --git a/docs-internal/email_service.md b/docs-internal/email_service.md
index 3c40fb68..9099d0f1 100644
--- a/docs-internal/email_service.md
+++ b/docs-internal/email_service.md
@@ -303,7 +303,7 @@ The poll loop:
All credential resolution and IMAP access still delegate to `EmailService` —
nothing is duplicated in the controller. See
-[Temporal Execution Engine RFC](temporal-execution-engine-rfc.md) for the
+[Temporal Execution Engine RFC](ARCHIVE/temporal-execution-engine-rfc.md) for the
control and trigger lifecycle.
## Credentials Storage
@@ -442,7 +442,7 @@ cargo install himalaya
- [Node Creation Guide](./node_creation.md) — canonical plugin recipe (covers dual-purpose nodes; `emailSend`/`emailRead` are live examples)
- [Event Waiter System](./event_waiter_system.md) — trigger registration for `emailReceive`
-- [New Service Integration](./new_service_integration.md) — end-to-end integration pattern (use Google Workspace as a richer OAuth example)
+- [New Service Integration](./ARCHIVE/new_service_integration.md) — end-to-end integration pattern (use Google Workspace as a richer OAuth example)
- [Credentials Encryption](./credentials_encryption.md) — how `email_*` keys are encrypted on disk
## Security notes
diff --git a/docs-internal/errors.md b/docs-internal/errors.md
index 4861e3e7..d11633d7 100644
--- a/docs-internal/errors.md
+++ b/docs-internal/errors.md
@@ -62,7 +62,7 @@ Restart-Service SysMain
**Fix** (if admin is unavailable): **Reboot**. This is what clears the stuck kernel cache reliably.
-**Prevention** (`scripts/start.js`): A preflight probe times `import sqlalchemy`. If it exceeds 8 seconds, it fails fast with actionable remediation steps instead of letting uvicorn hang silently.
+**Prevention** (`cli/commands/start.py`, `_sqlalchemy_preflight`): a preflight probe times `import sqlalchemy` in the server venv. If it exceeds 8 seconds, it fails fast with actionable remediation steps instead of letting uvicorn hang silently.
---
@@ -231,7 +231,7 @@ WhatsApp RPC timeout - Go service not responding at ws://localhost:5683/ws/rpc
WhatsApp service health check (`/health`) returns 200 OK, but the WebSocket RPC connection fails.
-**Root cause**: The RPCClient WebSocket connect timeout was set to 2.0 seconds (`routers/whatsapp.py`). The Go whatsmeow service's WebSocket handshake can take 2-3 seconds on Windows, especially on cold start or when Defender is scanning the binary. A 2.1s handshake exceeds the 2.0s deadline.
+**Root cause**: The RPCClient WebSocket connect timeout was set to 2.0 seconds (in the WhatsApp RPC client, today `server/nodes/whatsapp/_service.py`). The Go whatsmeow service's WebSocket handshake can take 2-3 seconds on Windows, especially on cold start or when Defender is scanning the binary. A 2.1s handshake exceeds the 2.0s deadline.
**Fix**: Increased the connect timeout from 2.0s to 5.0s in `RPCClient.connect()`:
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index d327f7ec..69348358 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -56,7 +56,7 @@ phase plan lives in `~/.claude/plans/properly-fix-the-tech-dreamy-tarjan.md`.
If the canary fan-out causes regressions in production:
1. Set `EVENT_FRAMEWORK_ENABLED=false` in `.env` (or the process environment).
-2. Restart the server (`npm run start` / `uvicorn` reload). Pydantic Settings re-reads on startup.
+2. Restart the server (`company start` / `uvicorn` reload). Pydantic Settings re-reads on startup.
3. Confirm pass-through: `dispatch.emit()` logs `event-framework disabled — emit no-op` at DEBUG.
No DB migrations, no schema changes — the rollback is one env var + restart. The legacy `event_waiter` collector/processor keeps trigger nodes firing because plugin producers still call `event_waiter.dispatch(...)` alongside `dispatch.emit(...)` (the dual-dispatch pattern stays for the in-memory canvas-Run path; the Redis-Streams branch itself was retired in Wave 15.3).
@@ -103,14 +103,16 @@ chatTrigger. The scoping DECISION lives in the core call site
session stays unscoped) and the narrowing in core dispatch — plugin
`_events.py` factories only plumb the field of their own wire shape.
-Worker is embedded in the FastAPI process (`main.py:211-292`
-`TemporalWorkerManager.start()` runs as `asyncio.create_task()`). Activities
+Worker is embedded in the FastAPI process (`main.py:321-332` schedules
+`run_temporal_lifecycle` from `services/temporal/lifecycle.py` as one
+`asyncio.create_task()`; that module owns the connect loop and the
+`TemporalWorkerManager` / `TemporalWorkerPool` start). Activities
and the WebSocket connection pool share memory + event loop, so the fan-out
to FE clients is a direct in-process call — no Redis Streams hop required.
## Search Attributes setup
-The framework requires 6 custom Search Attributes on the Temporal
+The framework requires 7 custom Search Attributes on the Temporal
namespace. Registration is **idempotent + automatic on Temporal client
connect** (`services/temporal/client.py:TemporalClientWrapper.connect`):
@@ -122,6 +124,7 @@ connect** (`services/temporal/client.py:TemporalClientWrapper.connect`):
| `TriggerNodeId` | KEYWORD | Per-trigger event-history queries |
| `EventTriggerKind` | KEYWORD | Coarse classification (webhook / polling / …) |
| `EventReceivedAt` | DATETIME | Time-range queries |
+| `ControlEventTypes` | KEYWORD_LIST | The push event types a `WorkflowControlWorkflow` currently has triggers for (upserted as triggers register); `dispatch.emit` skips controllers whose list does not contain the event type. Absent on pre-upgrade histories = match-all. |
Declarations live in
[`services/temporal/search_attributes.py:EVENT_SEARCH_ATTRIBUTES`](../server/services/temporal/search_attributes.py).
@@ -138,7 +141,7 @@ temporal operator search-attribute create \
--namespace default \
--name EventType \
--type Keyword
-# ... repeat for the other 5 attributes
+# ... repeat for the other 6 attributes (ControlEventTypes is --type KeywordList)
```
### Verification
@@ -147,7 +150,7 @@ temporal operator search-attribute create \
temporal operator search-attribute list --namespace default
```
-Should show the 6 framework attributes alongside Temporal's built-in
+Should show the 7 framework attributes alongside Temporal's built-in
default attributes (`WorkflowType`, `WorkflowId`, `ExecutionStatus`, …).
## Temporal contract for plugin authors
@@ -290,7 +293,7 @@ Each Phase-A milestone has a verification command:
| A1 | `pytest tests/test_plugin_contract.py::TestStartToCloseTimeoutOverridesAreCommented` |
| A2 | `python -c "from services.plugin.scaling import RetryPolicy; assert 'NodeUserError' in RetryPolicy().non_retryable_error_types"` |
| A3 | `python -c "from core.config import Settings; print(Settings().temporal_graceful_shutdown_seconds)"` |
-| A4 | After Temporal connect: `temporal operator search-attribute list \| grep -E 'EventType\|EventSource\|EventWorkflowId\|TriggerNodeId\|EventTriggerKind\|EventReceivedAt'` — all 6 lines |
+| A4 | After Temporal connect: `temporal operator search-attribute list \| grep -E 'EventType\|EventSource\|EventWorkflowId\|TriggerNodeId\|EventTriggerKind\|EventReceivedAt\|ControlEventTypes'` — all 7 lines |
Full test surface landed in Phase A9. Phase B (plugin `_events.py`
modules), Phase C (Temporal trigger-waiter migration), and Phase D
@@ -305,7 +308,7 @@ inspection surface:
- **Visibility list**: `client.list_workflows(query="ExecutionStatus='Failed' AND EventWorkflowId='<deployment_workflow_id>'")` returns every failed run for a deployment. The same Search Attributes the cancel sweep uses for cleanup (per `services/temporal/search_attributes.py`) make this query work.
- **Failure detail**: `client.get_workflow_history(workflow_id, run_id)` returns the full Event History, including the `ActivityTaskFailed` event's error message + stacktrace + each retry attempt timestamp.
-- **Temporal Web UI**: http://localhost:5680 — the same data, browsable.
+- **Temporal Web UI**: `http://localhost:<TEMPORAL_UI_PORT>` — the same data, browsable.
This is why Wave 12 explicitly does NOT add a custom `event_dlq` SQLModel table. Doing so would reinvent the Temporal primitives the rest of the framework was built AROUND, not against. The pre-Temporal `services/execution/models.py::DLQEntry` for the legacy `WorkflowExecutor` is a separate concern and stays where it is.
diff --git a/docs-internal/event_waiter_system.md b/docs-internal/event_waiter_system.md
index 8f79cc79..32cbbbd4 100644
--- a/docs-internal/event_waiter_system.md
+++ b/docs-internal/event_waiter_system.md
@@ -1,7 +1,6 @@
# Event Waiter System
-> **⚠️ Pre-Wave-11 — historical reference only.**
-> Node authoring now happens on the backend: each node is a Python plugin under `server/nodes/<category>/<node>.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.
+> **Scope note.** This document describes the live in-memory waiter that backs the canvas-Run path. Node authoring happens on the backend: each node is a Python plugin folder under `server/nodes/<category>/<node>/__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 authoring model.
Trigger nodes in OpenCompany suspend workflow execution until an external event arrives (WhatsApp message, webhook request, Telegram message, chat input, delegated task completion, etc.). The Event Waiter system is the in-memory (`asyncio.Future`) primitive that backs push-based triggers on the canvas-Run path. In a controlled deployment, trigger definitions, push Signals, polling activities, pause state, and queued events live in `WorkflowControlWorkflow`; only a real graph invocation starts `MachinaWorkflow`. `TriggerListenerWorkflow` / `PollingTriggerWorkflow` are legacy replay/compatibility paths. The Redis-Streams backend that previously offered cross-restart waiter persistence was retired because Temporal owns deployed-trigger durability.
@@ -38,40 +37,36 @@ class Waiter:
### Trigger Registry
-Every event-based trigger node type is registered with the event name it listens for:
+Every event-based trigger node type is registered with the event name it listens for. Only the four framework-level triggers (not owned by any plugin domain) are hardcoded in `event_waiter.py`:
```python
TRIGGER_REGISTRY: Dict[str, TriggerConfig] = {
- 'start': TriggerConfig('start', 'deploy_triggered', 'Deploy Start'),
- 'whatsappReceive': TriggerConfig('whatsappReceive', 'whatsapp_message_received','WhatsApp Message'),
- 'webhookTrigger': TriggerConfig('webhookTrigger', 'webhook_received', 'Webhook Request'),
- 'chatTrigger': TriggerConfig('chatTrigger', 'chat_message_received', 'Chat Message'),
- 'taskTrigger': TriggerConfig('taskTrigger', 'task_completed', 'Task Completed'),
- 'twitterReceive': TriggerConfig('twitterReceive', 'twitter_event_received', 'Twitter Event'),
- 'googleGmailReceive': TriggerConfig('googleGmailReceive', 'gmail_email_received', 'Gmail Email'),
- 'telegramReceive': TriggerConfig('telegramReceive', 'telegram_message_received','Telegram Message'),
+ 'start': TriggerConfig('start', 'deploy_triggered', 'Deploy Start'),
+ 'webhookTrigger': TriggerConfig('webhookTrigger', 'webhook_received', 'Webhook Request'),
+ 'chatTrigger': TriggerConfig('chatTrigger', 'chat_message_received', 'Chat Message'),
+ 'taskTrigger': TriggerConfig('taskTrigger', 'task_completed', 'Task Completed'),
}
```
+Plugin-owned triggers (`whatsappReceive`, `twitterReceive`, `telegramReceive`, `emailReceive`, `googleGmailReceive`, `discordReceive`, `whatsappBusinessReceive`, ...) are **backfilled** into the same dict by `_auto_populate_from_plugins()` (`event_waiter.py`), which walks every registered `TriggerNode` subclass and reads its `event_type` ClassVar + `display_name`. The backfill runs lazily on first `get_trigger_config` / `build_filter` access (importing the plugin registry at module load would be circular). Hardcoded entries always win, so a plugin upgrade never silently replaces hand-maintained behaviour.
+
`cronScheduler` is **not** in this registry: it is a Temporal Schedule (created by the deployment manager via `services/temporal/schedules.py`) and does not wait for events.
### Filter Builders
-Each trigger type has a filter builder that reads the node's parameters once and returns a closure evaluated per event:
+Each trigger type has a filter builder that reads the node's parameters once and returns a closure evaluated per event. Like the registry, only the framework-level builders are hardcoded:
```python
FILTER_BUILDERS = {
- 'whatsappReceive': build_whatsapp_filter,
- 'webhookTrigger': build_webhook_filter,
- 'chatTrigger': build_chat_filter,
- 'taskTrigger': build_task_completed_filter,
- 'twitterReceive': build_twitter_filter,
- 'googleGmailReceive': build_gmail_filter,
- 'telegramReceive': build_telegram_filter,
+ 'webhookTrigger': build_webhook_filter,
+ 'chatTrigger': build_chat_filter,
+ 'taskTrigger': build_task_completed_filter,
}
```
-Filter closures capture parameter values at registration time. For example, `build_whatsapp_filter` captures `messageTypeFilter`, `sender_filter`, `contact_phone`, `group_id`, `keywords`, `ignore_own`, and `forwarded_filter`, then returns a function that checks each incoming WhatsApp message against those constraints.
+Plugin builders arrive two ways: `_auto_populate_from_plugins()` wraps each `TriggerNode` subclass's `build_filter(params)` method (validated through the plugin's `Params` model), and rich plugin folders register an explicit builder from their `__init__.py` via `event_waiter.register_filter_builder(node_type, fn)` (telegram's `_filters.py:build_telegram_filter`, whatsapp's `_filters.py:build_whatsapp_filter`, ...). `FILTER_BUILDERS` is backed by an `IdempotentRegistry`, so a same-callable re-registration is a no-op and a conflicting one raises.
+
+Filter closures capture parameter values at registration time. For example, `build_whatsapp_filter` (`nodes/whatsapp/_filters.py`) captures `messageTypeFilter`, `sender_filter`, `contact_phone`, `group_id`, `keywords`, `ignore_own`, and `forwarded_filter`, then returns a function that checks each incoming WhatsApp message against those constraints.
## Execution Flow
@@ -158,13 +153,19 @@ Users can cancel a waiting trigger from the UI (Cancel button on the trigger nod
## Adding a New Trigger Type
-1. **Register it** in `TRIGGER_REGISTRY`:
+1. **Declare the plugin** as a `TriggerNode` subclass in its own folder, `server/nodes/<group>/mqtt_trigger/__init__.py`, with `group = ('mqtt', 'trigger')` and an `event_type` ClassVar. `_auto_populate_from_plugins()` backfills `TRIGGER_REGISTRY` from that ClassVar — do not hand-edit `event_waiter.py` (only the four framework-level triggers live there).
```python
- 'mqttTrigger': TriggerConfig('mqttTrigger', 'mqtt_message_received', 'MQTT Message'),
+ class MqttTriggerNode(TriggerNode):
+ type = "mqttTrigger"
+ display_name = "MQTT Message"
+ group = ("mqtt", "trigger")
+ event_type = "mqtt_message_received"
+ Params = MqttTriggerParams
+ Output = MqttTriggerOutput
```
-2. **Build a filter** closure from node params and add it to `FILTER_BUILDERS`:
+2. **Build a filter** closure from the validated `Params`. Either implement `build_filter` on the class (auto-registered) or, for a self-contained plugin folder, put it in `_filters.py` and register it from `__init__.py`:
```python
def build_mqtt_filter(params: Dict) -> Callable[[Dict], bool]:
@@ -179,21 +180,23 @@ Users can cancel a waiting trigger from the UI (Cancel button on the trigger nod
return True
return matches
- FILTER_BUILDERS['mqttTrigger'] = build_mqtt_filter
+ # nodes/mqtt/__init__.py
+ from services.event_waiter import register_filter_builder
+ register_filter_builder('mqttTrigger', build_mqtt_filter)
```
-3. **Dispatch events** from the external service:
+3. **Dispatch events** from the external service. For a canary (Temporal-routed) trigger, register the CloudEvents type with `register_canary_trigger_type(node_type, cloudevent_type)` and emit through `services.events.dispatch.emit(envelope, wire_routing_key=...)`; the canvas-Run path also accepts the legacy shape:
```python
from services import event_waiter
event_waiter.dispatch('mqtt_message_received', {'topic': ..., 'payload': ...})
```
-4. **Add the node definition** in `client/src/nodeDefinitions/` with `group: ['..., trigger']`.
+4. **Add the trigger to `WORKFLOW_TRIGGER_TYPES`** in `server/constants.py`. Omitting it is a silent failure — `find_trigger_nodes` filters on that set, so deploy ignores the node with no warning.
-5. **Add output schema** in `client/src/components/parameterPanel/InputSection.tsx` so downstream nodes can drag fields.
+5. **Declare the output shape** as the plugin's `Output` Pydantic model (auto-registered into `NODE_OUTPUT_SCHEMAS`), or call `services.node_output_schemas.register_output_schema(node_type, Model)` from `__init__.py` when the shape is not auto-derivable. The frontend reads it from `GET /api/schemas/nodes/<type>/spec.json` — there is no frontend file to edit.
-No changes are needed in the execution engine, cancel path, or deployment manager.
+No changes are needed in the execution engine, cancel path, deployment manager, or any frontend file.
## Related Docs
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index d095df64..c3d2a461 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -354,7 +354,7 @@ components/credentials/CredentialsModal.tsx
- **TanStack Query** owns the server state (catalogue, usage summaries, etc).
- **idb-keyval** cache seeds first paint — opened modal renders from IndexedDB in <50 ms before the WS roundtrip completes.
- **`requestIdleCallback`** writes back to IDB so saves don't block first paint.
-- **DB is the single source of truth.** The retired `client/src/components/credentials/providers.tsx` static fallback is gone — `useCatalogueQuery` is the only source. Cold-boot with no IDB cache renders a `<Skeleton>` palette while the WS catalogue arrives; server-unreachable shows an explicit error state, never stale fallback data.
+- **DB is the single source of truth.** The retired `providers.tsx` static fallback is gone — `useCatalogueQuery` is the only source. Cold-boot with no IDB cache renders a `<Skeleton>` palette while the WS catalogue arrives; server-unreachable shows an explicit error state, never stale fallback data.
- **`provider.stored` is the canonical "do we have a credential for X?".** The retired `apiKeyStatuses[id].hasKey` mirror duplicated this answer with no synchronisation contract. Two new selector hooks (`useProviderStored(id)`, `useStoredProviderCount()`) read the catalogue. `apiKeyStatuses[id]` now narrowly carries the validation result (`valid`, `models`, `message`, `timestamp`).
**App-wide query persistence ([client/src/lib/queryPersist.ts](../client/src/lib/queryPersist.ts)):** the QueryClient is wrapped in `<PersistQueryClientProvider>` ([main.tsx](../client/src/main.tsx)) with a localStorage persister + `__APP_VERSION__` buster + 24h SWR window. Only queries with key prefixes `nodeSpec` / `nodeGroups` / `skillContent` are dehydrated -- high-frequency / per-session queries stay in-memory. Hard refresh paints from cached specs **before** the WebSocket connects, so canvas nodes never flash placeholder icons. The credentials catalogue uses its own dedicated `idb-keyval` warm-start (above) because its payload is large enough that localStorage's 5-10MB cap is a real constraint. **Decrypted credential values are NOT persisted** (was the retired `'credentialValues'` prefix) per OWASP HTML5 Security Cheat Sheet / ASVS V9.9 — plaintext API keys in `localStorage` are readable via DevTools on shared / compromised browsers; the in-memory TanStack Query cache (`gcTime: ∞`) keeps the form populated for the session lifetime, on reload the panel refetches via WS.
diff --git a/docs-internal/gcp_vm_deploy_runbook.md b/docs-internal/gcp_vm_deploy_runbook.md
index e86ab92d..a9dbab5d 100644
--- a/docs-internal/gcp_vm_deploy_runbook.md
+++ b/docs-internal/gcp_vm_deploy_runbook.md
@@ -162,8 +162,11 @@ AUTH_MODE=single
# true ONLY behind Cloudflare/TLS (step 4). IP-only deploy: false (pitfall 11).
JWT_COOKIE_SECURE=true
JWT_COOKIE_SAMESITE=lax
-# true works on >= 0.0.95 (dev server ships in-package; backend connects to
-# localhost:7233 after restart). false = in-process sequential execution.
+# true works on >= 0.0.95 (dev server ships in-package; the backend spawns it
+# and connects on TEMPORAL_FRONTEND_GRPC_PORT — Temporal's stock 7233 on the
+# 0.0.95-era releases this runbook was validated against, the serial-block
+# value from that release's .env.template afterwards).
+# false = in-process sequential execution.
TEMPORAL_ENABLED=false
REDIS_ENABLED=false
LOG_FORMAT=text
@@ -362,7 +365,8 @@ curl -s https://<DOMAIN>/ | grep -o "<title>[^<]*</title>" # <title>OpenCompan
# 3. auth gate on, registration closed:
curl -s https://<DOMAIN>/api/auth/status
# expect: {"auth_enabled":true,"auth_mode":"single","can_register":false,...}
-# 4. login works (200 + HttpOnly machina_token cookie):
+# 4. login works (200 + HttpOnly cookie named by JWT_COOKIE_NAME — `opencompany_token`
+# today; `machina_token` on pre-rebrand releases):
curl -s -i -X POST https://<DOMAIN>/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"<OWNER_EMAIL>","password":"<OWNER_PASSWORD>"}' | head -12
@@ -410,12 +414,15 @@ gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo systemctl res
gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo npm install -g @zeenie-ai/opencompany@latest && sudo systemctl restart opencompany"
# flip an env toggle (sudo on EVERY command touching the 600 env file - pitfall 13c):
gcloud compute ssh <VM_NAME> --zone=<ZONE> --quiet --command="sudo sed -i 's/TEMPORAL_ENABLED=false/TEMPORAL_ENABLED=true/' /etc/opencompany/opencompany.env; sudo systemctl restart opencompany"
-# Temporal Web UI (localhost-bound on the VM; gRPC :7233, UI :8080 on
-# releases <= 0.0.95; :5681/:5680 after the serial-port change):
+# Temporal Web UI (localhost-bound on the VM; gRPC :7233 / UI :8080 are the
+# release-pinned values for <= 0.0.95; later releases bind
+# TEMPORAL_FRONTEND_GRPC_PORT / TEMPORAL_UI_PORT from that release's
+# .env.template — substitute the UI port below accordingly):
gcloud compute ssh <VM_NAME> --zone=<ZONE> --tunnel-through-iap -- -L 8080:localhost:8080
-# then open http://localhost:8080. Note: `company start` runs the Temporal dev
-# server regardless of TEMPORAL_ENABLED; the flag only controls whether the
-# backend connects to it (health shows temporal.enabled/connected).
+# then open http://localhost:8080. Note: the Temporal dev server is spawned by
+# the backend lifespan ONLY when TEMPORAL_ENABLED=true (`main.py` gates
+# `run_temporal_lifecycle` on `settings.temporal_enabled`); with the flag false
+# nothing listens on those ports and /health reports temporal.enabled=false.
# env (secrets live here):
# /etc/opencompany/opencompany.env (chmod 600; service reads it via EnvironmentFile)
# data:
diff --git a/docs-internal/media_transport.md b/docs-internal/media_transport.md
index c6aa34e7..69517356 100644
--- a/docs-internal/media_transport.md
+++ b/docs-internal/media_transport.md
@@ -335,7 +335,7 @@ So the rule for the next kind:
## Images to models — the hydration boundary
Multimodal input extends the never-bytes rule to LLM requests. Durable state
-(journal events, Temporal payloads, node results) carries image **FileRefs**
+(the `agent_conversations` conversation store, Temporal payloads, node results) carries image **FileRefs**
inside `ContentBlock.source` (`kind="file_ref"`, ~450 B); actual bytes exist
only between `services/llm/media.py::hydrate_image_blocks` and the provider
HTTP call, on throwaway message copies. The protocol codec raises if a
diff --git a/docs-internal/memory_compaction.md b/docs-internal/memory_compaction.md
index 25a5e02f..c131fdff 100644
--- a/docs-internal/memory_compaction.md
+++ b/docs-internal/memory_compaction.md
@@ -41,7 +41,7 @@ native agent loop
└─ Temporal AgentWorkflow
├─ returns aggregate usage in the workflow result
└─ when its context counter reaches the prepared threshold:
- agent.compact_memory → compact_context()
+ agent.compact_context → compact_context()
compact_context()
└─ run_native_llm_step(ChatUnifier, selected provider/model)
@@ -99,6 +99,12 @@ class TokenUsageMetric(SQLModel, table=True):
iteration: int = 1 # Agent loop iteration number
execution_id: Optional[str] # Workflow execution ID
created_at: Optional[datetime]
+
+ # Cost columns (USD), computed by PricingService at track() time
+ input_cost: float = 0.0
+ output_cost: float = 0.0
+ cache_cost: float = 0.0
+ total_cost: float = 0.0
```
### SessionTokenState
@@ -143,7 +149,8 @@ class CompactionEvent(SQLModel, table=True):
node_id: str
workflow_id: Optional[str]
- trigger_reason: str # "native", "threshold", "manual"
+ trigger_reason: str # Always "native" today — record() hardcodes it
+ # (compaction.py:233); no other value is written
tokens_before: int
tokens_after: int
messages_before: int = 0
@@ -200,7 +207,8 @@ result = await svc.track(
# {
# "total": 6000, # New cumulative total
# "threshold": 800000, # Model-aware: 80% of 1M context window
-# "total_cost": 0.021, # USD cost
+# "total_cost": 0.021, # USD cost (cumulative)
+# "context_length": 1000000, # Model context window the threshold was derived from
# "needs_compaction": False
# }
#
@@ -234,12 +242,13 @@ stats = await svc.stats("user-session-123", model="claude-opus-4.6", provider="a
# "session_id": "user-session-123",
# "total": 15000,
# "threshold": 800000, # 80% of 1M context window
-# "count": 1 # Number of compactions
+# "count": 1, # Number of compactions
+# "context_length": 1000000 # 0 when no model/provider given
# }
# Without model/provider, falls back to global default
stats = await svc.stats("user-session-123")
-# {"session_id": "user-session-123", "total": 15000, "threshold": 100000, "count": 1}
+# {"session_id": "user-session-123", "total": 15000, "threshold": 100000, "count": 1, "context_length": 0}
```
### Configure Per-Session Settings
@@ -321,7 +330,7 @@ ws.send(JSON.stringify({
### Environment Variables
```bash
-# In server/.env (mirrors .env.template)
+# In the repo-root .env (defaults live in the root .env.template:189-194)
COMPACTION_ENABLED=true # Enable/disable compaction globally (default: true)
COMPACTION_RATIO=0.8 # Fraction of context window that triggers compaction
# (default: 0.8 — was 0.5 pre-2026.06). Range 0.05-0.99.
@@ -387,22 +396,28 @@ usage = final_state["usage"]
### In-Process Persistence Point
In `server/services/ai.py`, the in-process path calls the service only when a
-memory session is connected:
+legacy memory session id was resolved earlier in the run (`session_id` is set
+from `memory_data["session_id"]` at `ai.py:1005`; it stays `None` once a
+Context runtime resolves, because `execute_agent` nulls `memory_data` in that
+case):
```python
-# After native agent-loop execution, before memory save
-if memory_data and memory_data.get('session_id'):
+# ai.py:1430-1446 — after native agent-loop execution, before memory save
+if session_id and ai_response:
compaction_result = await self._track_token_usage(
- session_id=memory_data['session_id'],
+ session_id=session_id,
node_id=node_id,
provider=provider,
model=model,
- ai_response=final_state["usage"],
- all_messages=final_state["messages"],
- memory_content=memory_data.get("memory_content", ""),
+ ai_response=final_state.get("usage") or ai_response,
+ all_messages=all_messages,
+ broadcaster=broadcaster,
+ workflow_id=workflow_id,
+ memory_content=memory_data.get("memory_content", "") if memory_data else None,
api_key=api_key,
- memory_node_id=memory_data.get("node_id"),
+ memory_node_id=memory_data.get("node_id") if memory_data else None,
)
+ _accumulate_compaction_usage(final_state, compaction_result)
```
## File Reference
@@ -415,7 +430,7 @@ if memory_data and memory_data.get('session_id'):
| `server/core/database.py` | CRUD methods for metrics and events |
| `server/core/config.py` | Environment variable configuration |
| `server/core/container.py` | Dependency injection setup |
-| `server/routers/websocket.py` | WebSocket handlers |
+| `server/services/settings/handlers.py` | WebSocket handlers `get_compaction_stats` (line 215) and `configure_compaction` (line 233); registered into `MESSAGE_HANDLERS` by `routers/websocket.py` |
| `server/main.py` | Service initialization on startup |
## Design Decisions
@@ -520,7 +535,8 @@ if tracking.get('needs_compaction') and memory_content and api_key:
F4.B performs a parallel check inside `AgentWorkflow` using the workflow's
active-context usage counter and the ratio-based threshold recorded by
`agent.prepare_payload`. It invokes the same `compact_context()` method
-through `agent.compact_memory`.
+through the `agent.compact_context` activity
+(`services/temporal/agent_activities.py:1944`).
### AI Service Wiring
@@ -586,35 +602,41 @@ Broadcast when compaction finishes:
### Token Usage Panel
-The Token Usage panel is displayed in the MiddleSection of the parameter panel for memory nodes (simpleMemory). It shows:
+The Token Usage panel is displayed in the MiddleSection of the parameter panel
+for **agent nodes that have a memory session connected** — the gate is
+`isAgentWithSkills && connectedMemorySessionId`
+(`client/src/components/parameterPanel/MiddleSection.tsx:767-768`), not the
+memory node itself. It shows:
+
+- **Progress bar**: tokens used vs the model's context length when known (`compactionStats.context_length`), else vs the threshold; turns destructive at 80%
+- **Statistics**: `Total`, editable `Threshold`, `Compactions`, and `Context` (when a context length is known), plus the session id
+- **Editable threshold**: click the `Threshold` stat to reveal a number input + save button; saving fires `configure_compaction` for the connected session
-- **Progress bar**: Visual representation of tokens used vs threshold
-- **Statistics**: Current token count, threshold, compaction count
-- **Editable threshold**: Click edit icon to change threshold per session
+Built from shadcn primitives (no antd):
```typescript
-// In client/src/components/parameterPanel/MiddleSection.tsx
-<Collapse.Panel header="Token Usage" key="tokenUsage">
- <Progress
- percent={Math.min(100, Math.round((tokenStats.total / tokenStats.threshold) * 100))}
- status={tokenStats.total >= tokenStats.threshold ? 'exception' : 'normal'}
- />
- <Statistic title="Tokens Used" value={`${tokenStats.total.toLocaleString()} / ${tokenStats.threshold.toLocaleString()}`} />
- <Statistic title="Compactions" value={tokenStats.count} />
-
- {/* Editable threshold */}
- {isEditingThreshold ? (
- <InputNumber
- value={editThresholdValue}
- onChange={setEditThresholdValue}
- min={10000}
- max={1000000}
- step={10000}
- />
- ) : (
- <Button icon={<EditOutlined />} onClick={() => setIsEditingThreshold(true)} />
- )}
-</Collapse.Panel>
+// client/src/components/parameterPanel/MiddleSection.tsx:768-870 (abridged)
+{isAgentWithSkills && connectedMemorySessionId && (
+ <Accordion type="single" collapsible defaultValue="tokens">
+ <AccordionItem value="tokens">
+ <AccordionTrigger>Token Usage {total}K / {displayMax}K</AccordionTrigger>
+ <AccordionContent>
+ <Progress value={Math.min(percent, 100)} className={cn(isWarning && '[&>div]:bg-destructive')} />
+ <Stat title="Total" value={compactionStats.total} />
+ {isEditingThreshold ? (
+ <>
+ <Input type="number" value={editThresholdValue} min={10000} max={2000000} step={10000} />
+ <ActionButton intent="save" onClick={() => configureCompactionMutation.mutate({ sessionId, threshold })} />
+ </>
+ ) : (
+ <Stat title="Threshold" value={compactionStats.threshold} /> {/* click to edit */}
+ )}
+ <Stat title="Compactions" value={compactionStats.count} />
+ {hasContext && <Stat title="Context" value={`${Math.round(ctxLen / 1000)}K`} />}
+ </AccordionContent>
+ </AccordionItem>
+ </Accordion>
+)}
```
## Future Enhancements
diff --git a/docs-internal/native_llm_sdk.md b/docs-internal/native_llm_sdk.md
index 466fee89..8ff85ef8 100644
--- a/docs-internal/native_llm_sdk.md
+++ b/docs-internal/native_llm_sdk.md
@@ -37,6 +37,7 @@ server/services/llm/
|-- schema.py Provider-aware tool JSON-schema compilation
|-- vertex.py Vertex / Agent-Platform key handling
|-- messages.py filter_empty_messages, is_valid_message_content
+|-- media.py hydrate_image_blocks / provider_supports_vision (see "Multimodal image input")
`-- providers/
|-- __init__.py
|-- anthropic.py AnthropicProvider (anthropic SDK)
@@ -58,16 +59,16 @@ The native layer currently supports **13 providers**, grouped by implementation:
| Provider | Implementation | SDK | Notes |
|---|---|---|---|
-| `anthropic` | `providers/anthropic.py` | `anthropic` | Extended thinking via `budget_tokens` |
-| `openai` | `providers/openai.py` | `openai` | Reasoning models (o1/o3) and GPT-5 hybrid thinking |
+| `anthropic` | `providers/anthropic.py` | `anthropic` | Extended thinking: `{"type":"adaptive"}` on the 4.7+ flagships, `budget_tokens` on Sonnet 4.6 / Haiku 4.5 (JSON-driven `_model_policy`) |
+| `openai` | `providers/openai.py` | `openai` | Reasoning-only o-series (`o3`, `o4-mini`) and GPT-5.x hybrid `reasoning_effort` |
| `gemini` | `providers/gemini.py` | `google-genai` | Direct SDK (Windows hang fix) |
| `openrouter` | `providers/openrouter.py` | `openai` | Sets `HTTP-Referer` + `X-Title` headers |
-| `xai` | `providers/openai.py` + base_url | `openai` | OpenAI-compatible at `api.x.ai/v1` |
-| `deepseek` | `providers/openai.py` + base_url | `openai` | OpenAI-compatible at `api.deepseek.com` |
-| `kimi` | `providers/openai.py` + base_url | `openai` | Moonshot AI, OpenAI-compatible |
-| `mistral` | `providers/openai.py` + base_url | `openai` | OpenAI-compatible |
-| `ollama` | `providers/openai.py` + `{provider}_proxy` URL | `openai` (chat) + `ollama` (probe) | Local server. Validator probes via `ollama.AsyncClient.ps()` for typed `context_length` per loaded model. Runtime uses `OpenAIProvider` with `base_url={user URL}` so traffic stays on `localhost`. |
-| `lmstudio` | `providers/openai.py` + `{provider}_proxy` URL | `openai` (chat) + `lmstudio` (probe) | Local server. Validator probes via `lmstudio.AsyncClient.llm.list_loaded()` for typed `LlmInstanceInfo.context_length`. Same OpenAI-compat runtime path as Ollama. |
+| `xai` | `providers/_compat.py` + base_url | `openai` | OpenAI-compatible at `api.x.ai/v1` |
+| `deepseek` | `providers/_compat.py` + base_url | `openai` | OpenAI-compatible at `api.deepseek.com` (root-mounted, no `/v1`) |
+| `kimi` | `providers/_compat.py` + base_url | `openai` | Moonshot AI, OpenAI-compatible |
+| `mistral` | `providers/_compat.py` + base_url | `openai` | OpenAI-compatible |
+| `ollama` | `providers/_compat.py` + `{provider}_proxy` URL | `openai` (chat) + `ollama` (probe) | Local server. Validator probes via `ollama.AsyncClient.ps()` for typed `context_length` per loaded model. Runtime uses `OpenAIProvider` with `base_url={user URL}` so traffic stays on `localhost`. |
+| `lmstudio` | `providers/_compat.py` + `{provider}_proxy` URL | `openai` (chat) + `lmstudio` (probe) | Local server. Validator probes via `lmstudio.AsyncClient.llm.list_loaded()` for typed `LlmInstanceInfo.context_length`. Same OpenAI-compat runtime path as Ollama. |
| `groq` | `providers/_compat.py` + base_url | `openai` | OpenAI-compatible |
| `cerebras` | `providers/_compat.py` + base_url | `openai` | OpenAI-compatible |
| `sarvam` | `providers/_compat.py` + base_url | `openai` | Indic-first (`sarvam-105b` 128K, `sarvam-30b` 64K) at `api.sarvam.ai/v1`. Ships **no model-list route**, so it sets `supports_model_listing: false` — see below. Reasoning is on by default and returns in `reasoning_content`, which `OpenAIProvider._normalize` already reads. |
@@ -92,20 +93,20 @@ Source of truth for this list: `server/config/llm_defaults.json` (the `providers
| Provider | Key Models | Context | Max Output | Thinking | Temp Range |
|----------|-----------|---------|-----------|----------|------------|
-| **OpenAI** | GPT-5.6 Sol/Terra/Luna, GPT-5.5/5.4 | 1.05M | 128K | effort | omitted for reasoning models |
+| **OpenAI** | GPT-5.6 Sol/Terra/Luna (+ `-pro`; default `gpt-5.6-sol`), GPT-5.5/5.4 | 1.05M | 128K | effort | omitted for reasoning models |
| **OpenAI** | GPT-4.1 | ~1.05M | 32K | none | 0-2 |
-| **Anthropic** | Claude Fable 5 | 1M | 128K | budget | 0-1 |
-| **Anthropic** | Claude Opus 4.8/4.7 | 1M | 128K | budget | 0-1 |
-| **Anthropic** | Claude Sonnet 4.6 | 1M | 64K | budget | 0-1 |
+| **Anthropic** | Claude Opus 5 (default `claude-opus-5`), Fable 5.1 / 5, Sonnet 5 | 1M | 128K | adaptive | omitted (`temperature` / `top_p` / `top_k` rejected — `sampling_params_removed`) |
+| **Anthropic** | Claude Opus 4.8/4.7 | 1M | 128K | adaptive | omitted (`sampling_params_removed`) |
+| **Anthropic** | Claude Sonnet 4.6 | 1M | 128K | budget | 0-1 |
| **Anthropic** | Claude Haiku 4.5 | 200K | 64K | budget | 0-1 |
-| **Google** | Gemini 3.5-flash, 3.1-pro/flash-lite, 3-flash, 2.5-pro/flash/flash-lite | 1M | 64K | budget | 0-2 |
+| **Google** | Gemini 3.8-flash (default), 3.7/3.6/3.5-flash, 3.5-flash-lite, 3.1-pro-preview/flash-lite, 3-flash-preview, 2.5-pro/flash/flash-lite | 1M | 64K | budget (`thinking_level` on 3.x when set explicitly) | 0-2 |
| **xAI** | Grok 4.20/4.20-multi-agent, 4.5, 4.3, 3 | 131K-2M | 131K | model/provider dependent | 0-2 |
| **DeepSeek** | deepseek-v4-flash, deepseek-v4-pro (deepseek-chat/reasoner legacy) | 1M | 64K | thinking modes | 0-2 |
| **Kimi** | kimi-k3 (default), kimi-k2.6, kimi-k2.5, kimi-k2.7-code | 1M (K3); 256K (K2) | 131K (K3); 32K/96K (K2) | K2 provider default explicitly disabled unless requested | K2 fixed 0.6; K3 0-1 |
| **Mistral** | mistral-large/medium/small-latest, codestral-latest | 256K | 131K | none | 0-1.5 |
| **Groq** | GPT-OSS-120b/20b, Qwen3-32b, legacy Llama 3.x tiers | 131K | 32K-131K | effort (GPT-OSS), format (Qwen3) | 0-2 |
| **OpenRouter** | 200+ models from multiple providers | varies | varies | varies | 0-2 |
-| **Cerebras** | GPT-OSS-120b, Z.ai GLM 4.7, Gemma 4 31B | 131K | 40K | budget (GLM preview) | 0-1.5 |
+| **Cerebras** | GPT-OSS-120b (default; only production model), zai-glm-4.7 + gemma-4-31b (preview) | 131K | 40K | budget (`zai-glm-4.7` only — `thinking_models`) | 0-1.5 |
| **Ollama** | Whatever the user has pulled (qwen2.5, llama3.x, phi-3, deepseek-r1, ...) | per-loaded-model (typed via `ps()`) | ctx ÷ 4 (capped 4096) | none (per-model) | 0-2 |
| **LM Studio** | Whatever the user has loaded in the LM Studio UI | per-loaded-model (typed via `LlmInstanceInfo.context_length`) | ctx ÷ 4 (capped 4096) | none (per-model) | 0-2 |
@@ -133,7 +134,7 @@ user's URL and uses the documented placeholder key for unauthenticated local
servers. The OpenAI SDK then sends to the configured local endpoint — traffic
never reaches api.openai.com.
-**Provider detection** ([`server/constants.py:detect_ai_provider`](../server/constants.py)) MUST list `ollama` / `lmstudio` substrings, and the agent dropdown's `provider` Literal in [`ai_agent.py`](../server/nodes/agent/ai_agent/__init__.py) / [`chat_agent.py`](../server/nodes/agent/chat_agent/__init__.py) / [`_specialized.py`](../server/nodes/agent/_specialized.py) MUST include `"ollama"` / `"lmstudio"` — otherwise the chat-model node silently falls through to `'openai'` and the runtime calls the OpenAI cloud with the local-server placeholder key.
+**Provider detection** ([`server/constants.py:detect_ai_provider`](../server/constants.py)) MUST list `ollama` / `lmstudio` substrings, and the agent dropdown's `provider` Literal in [`ai_agent/__init__.py`](../server/nodes/agent/ai_agent/__init__.py) / [`chat_agent/__init__.py`](../server/nodes/agent/chat_agent/__init__.py) / [`_specialized.py`](../server/nodes/agent/_specialized.py) MUST include `"ollama"` / `"lmstudio"` — otherwise the chat-model node silently falls through to `'openai'` and the runtime calls the OpenAI cloud with the local-server placeholder key.
**Open-world skip in `is_model_valid_for_provider`** — local model names like `qwen/qwen3.6-27b` don't contain provider substrings, so the cloud-style pattern check would always reject them. The function returns `True` for `openrouter` / `ollama` / `lmstudio` without consulting `detection_patterns`. The upstream server still rejects genuinely missing models with a clear 404.
@@ -291,14 +292,15 @@ Each provider's `chat()` method reads only the fields it supports. The extracted
| Provider | Models | Parameter | Thinking Type | Notes |
|----------|--------|-----------|---------------|-------|
-| **Claude** | All Claude 4.x/3.5 | `thinkingBudget` (1024-16000 tokens) | budget | Requires `max_tokens > budget_tokens`. Temperature auto-set to 1. |
-| **Gemini** | gemini-3.x, gemini-2.5-pro/flash | `thinkingBudget` (token count) | budget | Uses `thinking_budget` API parameter |
-| **OpenAI** | o1, o3, o3-mini, o4-mini | `reasoningEffort` (low/medium/high) | effort | Reasoning-only models. Temperature fixed at 1.0. |
-| **OpenAI** | GPT-5.2/5.1/5/5-mini/5-nano | `reasoningEffort` (low/medium/high/xhigh) | effort | Hybrid reasoning: can operate with or without thinking. |
-| **Groq** | qwen3-32b | `reasoningFormat` ('parsed' or 'hidden') | format | 'parsed' returns reasoning, 'hidden' returns only final answer |
-| **Cerebras** | qwen-3-235b | `reasoningFormat` ('parsed' or 'hidden') | format | Same format-based reasoning as Groq Qwen |
+| **Claude** (adaptive) | `claude-opus-5`, `claude-fable-5*`, `claude-mythos-5`, `claude-sonnet-5`, `claude-opus-4-8`, `claude-opus-4-7` (`adaptive_thinking_models`, prefix-matched) | `thinkingEnabled` only — the budget is ignored | adaptive | Sends `{"type":"adaptive","display":"summarized"}` when enabled; when disabled the field is omitted (`disabled` is itself rejected on Fable/Mythos). `budget_tokens` is a 400 on these generations. No `temperature` / `top_p` / `top_k` is sent at all (`sampling_params_removed`). `anthropic.py:72-92`. |
+| **Claude** (budget) | `claude-sonnet-4-6`, `claude-haiku-4-5` and older 4.x/3.5 | `thinkingBudget` (1024-16000 tokens) | budget | `{"type":"enabled","budget_tokens":N}`; provider bumps `max_tokens` to `budget + 1024` if it is not already larger. Temperature auto-set to 1. |
+| **Gemini** | gemini-3.x, gemini-2.5-pro/flash | `thinkingBudget` (token count); `thinkingLevel` on 3.x when set explicitly | budget | Uses `thinking_budget` API parameter (`thinking_level` only when the user set it — Vertex rejects an unsolicited level on 2.5-era models) |
+| **OpenAI** | `o3`, `o4-mini` (reasoning-only; both on the API-shutdown path per `_models_note`, `o1`/`o3`/`o4` prefixes still detected) | `reasoningEffort` (low/medium/high) | effort | Reasoning-only models. Temperature omitted. |
+| **OpenAI** | GPT-5.6 sol/terra/luna (+ `-pro`), GPT-5.5, GPT-5.4 (`thinking_models: ["gpt-5"]`) | `reasoningEffort` (low/medium/high/xhigh) | effort | Hybrid reasoning: can operate with or without thinking. |
+| **Groq** | qwen3-32b (`thinking_models: ["qwen3"]`) | `reasoningFormat` ('parsed' or 'hidden') | format | 'parsed' returns reasoning, 'hidden' returns only final answer. GPT-OSS models on Groq use `reasoning_effort` instead (`openai.py:671-675`). |
+| **Cerebras** | zai-glm-4.7 (`thinking_models`) | `thinkingBudget` | budget | Sent as `extra_body.thinking_budget` (`openai.py:111-114`). The qwen-3-235b variants are shut down upstream. |
-The thinking/reasoning fields (`thinkingEnabled`, `thinkingBudget`, `reasoningEffort`, `reasoningFormat`) live in the backend NodeSpec for each chat model (`server/nodes/model/<provider>_chat_model/`) and are surfaced through `AIChatModelParams` in `server/models/nodes.py`. The frontend renders them automatically via the universal parameter panel.
+The thinking/reasoning fields (`thinkingEnabled`, `thinkingBudget`, `reasoningEffort`, `reasoningFormat`) live in the backend NodeSpec for each chat model (`server/nodes/model/<provider>_chat_model/`) and are declared once on the shared `ChatModelParams` model in `server/nodes/model/_base.py:24`. The frontend renders them automatically via the universal parameter panel.
### Thinking extraction (legacy replay path)
@@ -331,14 +333,15 @@ The agent/chat result envelope carries `thinking` alongside the answer:
}
```
-The `thinking` field is exposed to downstream nodes via the backend output schema (`AIAgentOutput` in `server/services/node_output_schemas.py`, shared across every LLM-backed agent + chat model) and rendered in a collapsible `ThinkingBlock` (`client/src/components/ui/NodeOutputPanel.tsx`, default-expanded, provider-aware label).
+The `thinking` field is exposed to downstream nodes via the backend output schema (`AIAgentOutput` in `server/services/node_output_schemas.py`, shared across every LLM-backed agent + chat model) and rendered as a `Thinking` section by the active output renderer (`client/src/components/output/OutputPanel.tsx:196-200`; the earlier `ThinkingBlock` / `NodeOutputPanel.tsx` no longer exist).
### Thinking limitations
- **OpenAI o-series**: Reasoning summaries are only available to organizations that have completed verification at platform.openai.com. Without verification, `thinking` is `null`.
-- **Claude**: `max_tokens` must be greater than `thinkingBudget`. Temperature is automatically set to 1 when thinking is enabled.
-- **Groq**: Only Qwen3-32b supports reasoning (QwQ removed from Groq). Format `hidden` suppresses reasoning output.
-- **Cerebras**: Qwen-3-235b supports format-based reasoning (same as Groq Qwen).
+- **Claude (budget models)**: `max_tokens` must be greater than `thinkingBudget`; the provider raises `max_tokens` to `budget + 1024` when it is not. Temperature is automatically set to 1 when thinking is enabled.
+- **Claude (adaptive models)**: `thinkingBudget` is ignored — the model picks its own depth. No sampling parameters are sent; a user-set temperature is silently dropped for these models rather than rejected.
+- **Groq**: Only Qwen3-32b supports format-based reasoning (QwQ removed from Groq). Format `hidden` suppresses reasoning output. GPT-OSS models take `reasoning_effort`.
+- **Cerebras**: Only `zai-glm-4.7` (preview) is a thinking model, via `thinking_budget`.
See [memory_compaction.md](memory_compaction.md) for how thinking token counts are tracked separately from output tokens.
@@ -350,7 +353,7 @@ See [memory_compaction.md](memory_compaction.md) for how thinking token counts a
def resolve_max_tokens(params: dict, model: str, provider: str) -> int:
registry = get_model_registry()
model_max = registry.get_max_output_tokens(model, provider)
- user_val = params.get("max_tokens") or params.get("maxTokens")
+ user_val = params.get("max_tokens") # snake_case only; the camelCase fallback is gone
if user_val:
user_int = int(user_val)
if user_int > model_max:
@@ -390,10 +393,10 @@ cached native provider factory.
Users configure default parameter values per LLM provider in the Credentials Modal; defaults apply to new AI nodes using that provider.
**Configurable parameters:**
-- `temperature` — range varies by provider (Anthropic 0-1, Cerebras 0-1.5, others 0-2; o-series fixed 1.0)
+- `temperature` — range varies by provider (Anthropic 0-1 on budget-era models, omitted entirely for the adaptive flagships; Cerebras 0-1.5; others 0-2; o-series omitted)
- `max_tokens` (1-200000) — clamped to the model's actual limit by `_resolve_max_tokens()`
- `thinking_enabled` — extended thinking toggle
-- `thinking_budget` (1024-16000) — token budget for thinking (Claude, Gemini)
+- `thinking_budget` (1024-16000) — token budget for thinking (Claude budget-era models, Gemini, Cerebras GLM; ignored by adaptive Claude models)
- `reasoning_effort` (low/medium/high) — OpenAI o-series and GPT-5 hybrid reasoning
- `reasoning_format` (parsed/hidden) — Groq Qwen3 models
@@ -401,6 +404,7 @@ Users configure default parameter values per LLM provider in the Credentials Mod
# server/models/database.py
class ProviderDefaults(SQLModel, table=True):
provider: str # openai, anthropic, gemini, groq, openrouter, cerebras
+ default_model: str # per-provider default model ("" = use llm_defaults.json)
temperature: float
max_tokens: int
thinking_enabled: bool
@@ -413,9 +417,9 @@ class ProviderDefaults(SQLModel, table=True):
|------|-------------|
| `server/models/database.py` | `ProviderDefaults` SQLModel |
| `server/core/database.py` | `get_provider_defaults()`, `save_provider_defaults()` CRUD |
-| `server/routers/websocket.py` | `get_provider_defaults`, `save_provider_defaults` handlers |
+| `server/services/settings/handlers.py` | `handle_get_provider_defaults` (line 73), `handle_save_provider_defaults` (line 108) — registered into `MESSAGE_HANDLERS` by `routers/websocket.py` |
| `client/src/hooks/useApiKeys.ts` | `getProviderDefaults()`, `saveProviderDefaults()` methods |
-| `client/src/components/CredentialsModal.tsx` | Default Parameters UI section |
+| `client/src/components/credentials/sections/ProviderDefaultsSection.tsx` | Default Parameters UI section (the root `CredentialsModal.tsx` is a one-line re-export of `credentials/CredentialsModal.tsx`) |
## Adding a New Provider
@@ -456,7 +460,7 @@ the plugin folder or add a `visuals.json` entry (`"openrouterChatModel":
3. **Credentials + agent exposure:**
- Add a `Credential` subclass in `server/nodes/model/_credentials.py` — surfaces in the Credentials Modal automatically.
- - To expose the provider in the **agent dropdown**, add its name to the `provider` Literal in `nodes/agent/ai_agent/__init__.py`, `chat_agent.py`, AND `_specialized.py`, and add the substring to `detect_ai_provider` in `server/constants.py` — otherwise an agent using it silently falls back to `'openai'`.
+ - To expose the provider in the **agent dropdown**, add its name to the `provider` Literal in `nodes/agent/ai_agent/__init__.py`, `nodes/agent/chat_agent/__init__.py`, AND `nodes/agent/_specialized.py`, and add the substring to `detect_ai_provider` in `server/constants.py` — otherwise an agent using it silently falls back to `'openai'`.
### Key implementation files
@@ -469,7 +473,7 @@ the plugin folder or add a `visuals.json` entry (`"openrouterChatModel":
| `server/services/llm/registry.py` | `ProviderSpec` / `register_provider` — the provider registration contract |
| `server/services/llm/unifier.py` | `ChatUnifier` — chat dispatch facade + typed-error translation |
| `server/services/agent_runtime.py` | Shared native agent step/loop and `AgentToolSpec` |
-| `server/services/ai.py` | Node orchestration; legacy factory retained only for recorded Temporal histories |
+| `server/services/ai.py` | Node orchestration (`execute_chat` / `execute_agent` / `execute_chat_agent`); every provider call goes through `ChatUnifier` — the legacy factory is gone (see "Registry, Unifier, and Lazy SDK Clients") |
| `client/src/Dashboard.tsx` | Generic `COMPONENT_BY_KIND` dispatch — no per-provider entry needed |
## Related Docs
@@ -481,7 +485,7 @@ the plugin folder or add a `visuals.json` entry (`"openrouterChatModel":
## Temporal migration and dependency lifecycle
-`agent.prepare_payload.v1` records `llm_engine` and `message_wire_version`.
+`agent.prepare_payload` records `llm_engine` and `message_wire_version`.
The marker is a discriminator, not a switch: there is one engine.
A history recorded before the native cutover carries neither field, and its
diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.md
index 3ce2bacb..936728a2 100644
--- a/docs-internal/node-logic-flows/README.md
+++ b/docs-internal/node-logic-flows/README.md
@@ -7,8 +7,10 @@ match its doc here, and each doc must still describe what the code does.
## How to use
- **Adding a node**: copy [`_TEMPLATE.md`](./_TEMPLATE.md) into the right
- category folder, name it `<nodeName>.md` (camelCase, matching the
- `type` field on the backend plugin at `server/nodes/<category>/<node>.py`).
+ category folder and name it `<type>.md` -- the filename stem must equal the
+ registered `type` string exactly (camelCase or snake_case, whatever the
+ plugin declares) as set on the backend plugin at
+ `server/nodes/<group>/<plugin>/__init__.py`.
- **Refactoring a node**: update the matching contract test in
`server/tests/nodes/test_<category>.py` *first*, then change the handler,
then update this doc.
@@ -35,6 +37,7 @@ match its doc here, and each doc must still describe what the code does.
- [AI Agent (`aiAgent`)](./ai_agents/aiAgent.md)
- [Zeenie (`chatAgent`)](./ai_agents/chatAgent.md)
- [Context (`context`)](./ai_agents/context.md)
+- [Master Skill (`masterSkill`)](./ai_agents/masterSkill.md)
- [Memory (`simpleMemory`)](./ai_agents/simpleMemory.md)
### ai_chat_models
@@ -58,8 +61,10 @@ match its doc here, and each doc must still describe what the code does.
- [Calculator Tool (`calculatorTool`)](./ai_tools/calculatorTool.md)
- [Canvas (`canvas`)](./ai_tools/canvas.md)
- [Current Time Tool (`currentTimeTool`)](./ai_tools/currentTimeTool.md)
+- [Data (`dataSource`)](./ai_tools/dataSource.md)
- [DuckDuckGo Search (`duckduckgoSearch`)](./ai_tools/duckduckgoSearch.md)
- [Task Manager (`taskManager`)](./ai_tools/taskManager.md)
+- [Vision Analyze (`visionAnalyze`)](./ai_tools/visionAnalyze.md)
- [Write Todos (`writeTodos`)](./ai_tools/writeTodos.md)
### android
@@ -88,9 +93,18 @@ match its doc here, and each doc must still describe what the code does.
- [Console (`console`)](./chat_utility/console.md)
- [File Handler (`fileHandler`)](./chat_utility/fileHandler.md)
- [Create Map (`gmaps_create`)](./chat_utility/gmaps_create.md)
+- [Geocoding (`gmaps_locations`)](./chat_utility/gmaps_locations.md)
+- [Nearby Places (`gmaps_nearby_places`)](./chat_utility/gmaps_nearby_places.md)
- [Team Monitor (`teamMonitor`)](./chat_utility/teamMonitor.md)
- [Text Generator (`textGenerator`)](./chat_utility/textGenerator.md)
+### cli_integrations
+
+- [Cloudflare (`cloudflareAction`)](./cli_integrations/cloudflareAction.md)
+- [Google Cloud (`gcloudAction`)](./cli_integrations/gcloudAction.md)
+- [GitHub (`githubAction`)](./cli_integrations/githubAction.md)
+- [Vercel (`vercelAction`)](./cli_integrations/vercelAction.md)
+
### code_fs_process
- [File Modify (`fileModify`)](./code_fs_process/fileModify.md)
@@ -151,6 +165,12 @@ match its doc here, and each doc must still describe what the code does.
- [Translate (`translateText`)](./language/translateText.md)
- [Transliterate (`transliterateText`)](./language/transliterateText.md)
+### microsoft
+
+- [Outlook Calendar (`msCalendar`)](./microsoft/msCalendar.md)
+- [Outlook Mail (`msMail`)](./microsoft/msMail.md)
+- [Outlook Mail Receive (`msMailReceive`)](./microsoft/msMailReceive.md)
+
### search
- [Brave Search (`braveSearch`)](./search/braveSearch.md)
@@ -159,22 +179,30 @@ match its doc here, and each doc must still describe what the code does.
### specialized_agents
-- [AI Employee (`ai_employee`)](./specialized_agents/aiEmployee.md)
-- [Android Control Agent (`android_agent`)](./specialized_agents/androidAgent.md)
-- [Autonomous Agent (`autonomous_agent`)](./specialized_agents/autonomousAgent.md)
-- [Claude Code Agent (`claude_code_agent`)](./specialized_agents/claudeCodeAgent.md)
-- [Codex (`codex_agent`)](./specialized_agents/codexAgent.md)
-- [Coding Agent (`coding_agent`)](./specialized_agents/codingAgent.md)
-- [Consumer Agent (`consumer_agent`)](./specialized_agents/consumerAgent.md)
-- [Orchestrator Agent (`orchestrator_agent`)](./specialized_agents/orchestratorAgent.md)
-- [Payments Agent (`payments_agent`)](./specialized_agents/paymentsAgent.md)
-- [Productivity Agent (`productivity_agent`)](./specialized_agents/productivityAgent.md)
-- [RLM Agent (`rlm_agent`)](./specialized_agents/rlmAgent.md)
-- [Social Media Agent (`social_agent`)](./specialized_agents/socialAgent.md)
-- [Task Management Agent (`task_agent`)](./specialized_agents/taskAgent.md)
-- [Tool Agent (`tool_agent`)](./specialized_agents/toolAgent.md)
-- [Travel Agent (`travel_agent`)](./specialized_agents/travelAgent.md)
-- [Web Control Agent (`web_agent`)](./specialized_agents/webAgent.md)
+- [AI Employee (`ai_employee`)](./specialized_agents/ai_employee.md)
+- [Android Control Agent (`android_agent`)](./specialized_agents/android_agent.md)
+- [Autonomous Agent (`autonomous_agent`)](./specialized_agents/autonomous_agent.md)
+- [Claude Code Agent (`claude_code_agent`)](./specialized_agents/claude_code_agent.md)
+- [Codex (`codex_agent`)](./specialized_agents/codex_agent.md)
+- [Coding Agent (`coding_agent`)](./specialized_agents/coding_agent.md)
+- [Consumer Agent (`consumer_agent`)](./specialized_agents/consumer_agent.md)
+- [Orchestrator Agent (`orchestrator_agent`)](./specialized_agents/orchestrator_agent.md)
+- [Payments Agent (`payments_agent`)](./specialized_agents/payments_agent.md)
+- [Productivity Agent (`productivity_agent`)](./specialized_agents/productivity_agent.md)
+- [RLM Agent (`rlm_agent`)](./specialized_agents/rlm_agent.md)
+- [Social Media Agent (`social_agent`)](./specialized_agents/social_agent.md)
+- [Task Management Agent (`task_agent`)](./specialized_agents/task_agent.md)
+- [Tool Agent (`tool_agent`)](./specialized_agents/tool_agent.md)
+- [Travel Agent (`travel_agent`)](./specialized_agents/travel_agent.md)
+- [Vertex Agent Admin (`vertex_agent_admin`)](./specialized_agents/vertex_agent_admin.md)
+- [Vertex Agent (`vertex_managed_agent`)](./specialized_agents/vertex_managed_agent.md)
+- [Cloud Tool (`vertexCloudTool`)](./specialized_agents/vertexCloudTool.md)
+- [Web Control Agent (`web_agent`)](./specialized_agents/web_agent.md)
+
+### stripe
+
+- [Stripe (`stripeAction`)](./stripe/stripeAction.md)
+- [Stripe Receive (`stripeReceive`)](./stripe/stripeReceive.md)
### telegram_social
@@ -194,6 +222,7 @@ match its doc here, and each doc must still describe what the code does.
- [Apify Actor (`apifyActor`)](./web_automation/apifyActor.md)
- [Browser (`browser`)](./web_automation/browser.md)
+- [Browser Harness (`browserHarness`)](./web_automation/browserHarness.md)
- [Crawlee Scraper (`crawleeScraper`)](./web_automation/crawleeScraper.md)
### whatsapp
diff --git a/docs-internal/node-logic-flows/_AGENT_BRIEF.md b/docs-internal/node-logic-flows/_AGENT_BRIEF.md
index a62a8620..4392db5b 100644
--- a/docs-internal/node-logic-flows/_AGENT_BRIEF.md
+++ b/docs-internal/node-logic-flows/_AGENT_BRIEF.md
@@ -24,18 +24,18 @@ are already done. Your job is to repeat the pilot pattern for your category.
## What to read
1. The handler file(s) for your category (paths in your prompt).
-2. The backend plugin at `server/nodes/<category>/<node>.py` (the NodeSpec SSOT).
+2. The backend plugin at `server/nodes/<group>/<plugin>/__init__.py` (the NodeSpec SSOT).
3. Any matching skill at `server/skills/<folder>/<skill>/SKILL.md` - link to it from the doc, do not duplicate.
4. The pilot files above so you copy the structure exactly.
## What to write
-1. **Per-node docs**: one Markdown file per node at `docs-internal/node-logic-flows/<category>/<nodeName>.md`. Use camelCase matching the registry key.
+1. **Per-node docs**: one Markdown file per node at `docs-internal/node-logic-flows/<category>/<type>.md`. The filename stem must equal the registered `type` string exactly (camelCase or snake_case, whatever the plugin declares).
2. **One test file** at `server/tests/nodes/test_<category>.py` with one test class per node, covering at minimum:
- happy path (assert envelope success + payload shape)
- one validation/error short-circuit (e.g. empty required param)
- one external-error path (HTTP 4xx/5xx, missing credential, subprocess failure)
-3. **Update the docs index**: run `node scripts/build-node-docs-index.js` after writing docs.
+3. **Update the docs index**: run `company docs nodes` after writing docs; `company docs nodes --check` fails when a registered node has no card.
## Doc style rules
diff --git a/docs-internal/node-logic-flows/ai_agents/masterSkill.md b/docs-internal/node-logic-flows/ai_agents/masterSkill.md
new file mode 100644
index 00000000..3097c2a1
--- /dev/null
+++ b/docs-internal/node-logic-flows/ai_agents/masterSkill.md
@@ -0,0 +1,134 @@
+# Master Skill (`masterSkill`)
+
+| Field | Value |
+|------|-------|
+| **Category** | ai_agents (config aggregator; palette group `tool`, `SKILL_NODE_TYPES` / `CONFIG_NODE_TYPES` in `constants.py`) |
+| **Backend handler** | [`server/nodes/skill/master_skill/__init__.py::MasterSkillNode.noop`](../../../server/nodes/skill/master_skill/__init__.py) (passive; the real consumer is [`services/plugin/edge_walker.py::_append_skill_entries`](../../../server/services/plugin/edge_walker.py) -> the expander registered by [`nodes/skill/__init__.py`](../../../server/nodes/skill/__init__.py) from [`nodes/skill/_expander.py::expand_master_skill`](../../../server/nodes/skill/_expander.py)); lifecycle events in [`master_skill/_events.py`](../../../server/nodes/skill/master_skill/_events.py) |
+| **WS handlers** | 13 skill handlers in [`services/skills/handlers.py`](../../../server/services/skills/handlers.py) (self-registered via `ws_handler_registry`): `get_skill_content`, `save_skill_content`, `scan_skill_folder`, `list_skill_folders`, `lookup_skill_metadata`, `evaluate_auto_skill`, `get_user_skills`, `get_user_skill`, `create_user_skill`, `update_user_skill`, `delete_user_skill`, `clear_memory`, `reset_skill` |
+| **Tests** | [`server/tests/test_auto_skill.py`](../../../server/tests/test_auto_skill.py), [`server/tests/services/test_skill_runtime.py`](../../../server/tests/services/test_skill_runtime.py), uiHint/spec invariants in [`server/tests/test_node_spec.py`](../../../server/tests/test_node_spec.py) and [`server/tests/test_plugin_contract.py`](../../../server/tests/test_plugin_contract.py) |
+| **Skill (if any)** | n/a — this node IS the aggregator of `server/skills/<folder>/*/SKILL.md` |
+| **Dual-purpose tool** | no - `component_kind = "tool"` but `uiHints.isMasterSkillEditor` excludes it from `iter_tool_node_classes` and from the `_metadata_dict` invokable-tool check; the LLM never calls it, it uses the connected skills instead |
+
+## Purpose
+
+Aggregates multiple skills into one canvas node with per-skill
+enable/disable toggles and inline instruction editing, and connects to an
+agent's `input-skill` handle. The node itself never executes anything
+meaningful: the connected agent reads the node's persisted `skills_config`
+during connection collection, expands every enabled entry into a per-skill
+descriptor, injects personality skills into the system prompt, and exposes
+standard skills through the dynamically bound `Skill` tool (progressive
+disclosure). The `isMasterSkillEditor` uiHint is what makes the frontend
+render the `MasterSkillEditor` split panel instead of a plain parameter
+list, route the canvas component to `ToolkitNode`, and recognise the node
+in the auto-add-skill edge dispatcher.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `output-tool` (source, top, label "Skill", role `skill`) | skill | yes (only handle) | Connect to an agent's `input-skill` |
+
+No `input-main`, no `main` output. uiHints: `isToolPanel`,
+`isMasterSkillEditor`, `hideRunButton`, `hideInputSection`,
+`hideOutputSection`; `isConfigNode` auto-derived from the `tool` group
+(the executor excludes it from execution layers).
+
+## Parameters
+
+Params model `MasterSkillParams` (`extra="ignore"`):
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `skill_folder` | string | `assistant` | no | - | Folder under `server/skills/` shown in the editor dropdown (`list_skill_folders` / `scan_skill_folder`). At runtime only one rule reads it: when it is `assistant` (or absent) the edge walker forces the `skill` entry to `enabled: true, required: true` |
+| `skills_config` | object `{ <skill_key>: { enabled: boolean; instructions: string; isCustomized: boolean; required: boolean; description?: string } }` | `{"skill": {enabled: true, instructions: "", isCustomized: false, required: true}}` | no | - | Per-skill state. `enabled` gates expansion; `instructions` overrides the skill body; `description` overrides the registry description |
+
+Persisted under the snake_case key `skills_config` (the walker reads
+`skill_params.get("skills_config")`); the auto-skill evaluator writes the
+same key through `set_node_parameters`.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| (no main output) | - | `noop` returns `MasterSkillOutput`; nothing downstream consumes it |
+
+### Output payload (TypeScript shape)
+
+```ts
+// noop echo (only if executed directly; run button hidden)
+{ skills_active: number } // count of skills_config entries whose value is a dict with truthy `enabled`
+
+// what the agent actually receives per enabled skill (expander entry)
+{
+ node_id: `${masterSkillNodeId}_${skill_key}`;
+ master_skill_node_id: string;
+ node_type: 'masterSkill';
+ skill_name: string;
+ description: string;
+ parameters: { instructions: string; skillName: string; description: string };
+ label: string;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Agent run: collect_agent_connections walks input-skill edges] --> B[_append_skill_entries: source type == masterSkill]
+ B --> C{expander registered by nodes.skill?}
+ C -- no --> C1[warning: skipping expansion - agent runs without skills]
+ C -- yes --> D[skills_config from DB params; skill_folder assistant -> force skill enabled+required]
+ D --> E[expand_master_skill: for each enabled key]
+ E --> F{key ends with -personality and no instructions?}
+ F -- yes --> F1[skill_loader.load_skill -> instructions from SKILL.md, failure logged]
+ F -- no --> G
+ F1 --> G[description = config.description or registry metadata or Instructions for key]
+ G --> H[entry node_id source_key, master_skill_node_id, parameters instructions/skillName/description]
+ H --> I[skill_prompt.build_skill_system_prompt: -personality entries injected verbatim into system message and drop the default system message]
+ H --> J[skill_runtime.validate_connected_skills: duplicate skill_name across Master Skills -> DUPLICATE_CONNECTED_SKILL_NAME]
+ J --> K[standard entries -> _builtin_skill tool node agent_skill_runtime with name/description catalogue capped at 7000 chars]
+ K --> L[model calls Skill tool -> execute_skill_tool loads the authoritative body and declared resources]
+ M[Canvas: tool -> agent input-tools edge connect/disconnect] --> N[useAutoSkillEdges -> evaluate_auto_skill WS]
+ N --> O[auto_skill.evaluate: toggle skill in existing Master Skill via set_node_parameters or add_node masterSkill + edge to input-skill]
+ P[Editor mutations: create/update/delete_user_skill, save_skill_content] --> Q[broadcast_skill_lifecycle skill_lifecycle wire key -> FE invalidates userSkills / folderSkills / skillContent]
+```
+
+## Decision Logic
+
+- **Enabled gate**: only entries with `enabled: true` expand; `required` is a UI/auto-skill concern except for the assistant `skill` forcing rule.
+- **Personality vs standard**: a `skill_name` ending in `-personality` is eager (full instructions into the system prompt; `has_personality` drops the agent's default system message); every other entry is lazy (catalogued on the `Skill` tool, body loaded on demand).
+- **Duplicate names**: `validate_connected_skills` raises `SkillRuntimeError("DUPLICATE_CONNECTED_SKILL_NAME")` when the same `skill_name` reaches an agent from more than one Master Skill node.
+- **Missing expander**: `get_master_skill_expander()` is `None` only when `nodes.skill` was never imported; the walker logs a warning and the agent runs without the node's skills. Re-registering a *different* callable raises `ValueError`.
+- **Auto-skill** (`services/auto_skill.evaluate`, driven by the `auto_add_skill_for_tools` user setting): connecting a tool that has a paired skill to an agent returns a workflow-ops batch that either toggles the skill in the agent's existing Master Skill (`set_node_parameters(master_skill_id, {skills_config})`, preserving customised `instructions` / `isCustomized`) or adds a new `masterSkill` node with that config plus an edge to `input-skill`.
+- **Error paths**: `noop` cannot fail; `load_skill` failures for personality skills are logged (`warning`) and the entry proceeds with empty instructions.
+
+## Side Effects
+
+- **Database reads**: `get_node_parameters(<master skill id>)` per agent run (edge walker); skill registry scan (`skill_loader.scan_skills`) per expansion.
+- **Database writes**: none by the node. WS handlers write user skills (`create/update/delete_user_skill`) and SKILL.md content (`save_skill_content`); auto-skill writes `skills_config` through the workflow-ops applier.
+- **Broadcasts**: `skill_lifecycle` wire key carrying a CloudEvents envelope (`source: opencompany://nodes/master_skill`, `type: com.opencompany.skill.{created|updated|deleted|content_saved}`, `subject: <skill name>`, `data`: full record for created/updated, `{name}` (+ `is_builtin` for content_saved) otherwise); agent-side `agent.skill.*` capability events from `skill_runtime` reference the Master Skill node via `master_skill_node_id` as the canvas badge target.
+- **External API calls / File I/O / Subprocess**: none by the node; `save_skill_content` writes SKILL.md files under `server/skills/`.
+
+## External Dependencies
+
+- **Credentials**: none.
+- **Services**: `services.plugin.edge_walker` (`register_master_skill_expander` / `get_master_skill_expander`), `services.skill_loader`, `services.skill_prompt`, `services.skill_runtime`, `services.auto_skill`, `services.workflow_ops`, `services.events.envelope.WorkflowEvent`.
+- **Frontend**: [`client/src/components/parameterPanel/MasterSkillEditor.tsx`](../../../client/src/components/parameterPanel/MasterSkillEditor.tsx) (dispatched by `MiddleSection` on `uiHints.isMasterSkillEditor`), `Dashboard.tsx` component dispatch to `ToolkitNode`, [`client/src/hooks/useAutoSkillEdges.ts`](../../../client/src/hooks/useAutoSkillEdges.ts).
+- **Task queue**: `TaskQueue.DEFAULT` (never dispatched in practice). Annotations: `readonly`.
+
+## Edge cases & known limits
+
+- `skill_folder` does not scope expansion: `skills_config` keys are looked up in the whole scanned registry, so a config can enable skills from any folder regardless of the dropdown value.
+- Zero enabled entries -> no skill context at all; the agent still runs (see `_pattern.md`).
+- With `skill_folder = "assistant"` the `skill` entry cannot be disabled at runtime even if the editor shows it off — the walker re-enables it.
+- `noop.skills_active` counts any dict entry with a truthy `enabled`, independent of whether the key exists in the registry.
+- `input-skill` handles exist on agents that ignore skill data (e.g. `vertex_managed_agent` discards the tuple slot); the node connects but contributes nothing there.
+- `-personality` keys with custom `instructions` in the config skip the SKILL.md load entirely — the customised text is what gets injected.
+- The wire types `hideInputSection` / `hideOutputSection` mean the panel shows only the editor; there is no way to inspect the expanded entries from the node itself (use the agent's Connected Skills view).
+
+## Related
+
+- **Consumers**: [`aiAgent`](./aiAgent.md), [`chatAgent`](./chatAgent.md), the specialized agents in [`../specialized_agents/_pattern.md`](../specialized_agents/_pattern.md).
+- **Auto-skill pairing**: tool nodes with a `visuals.json` skill alias (e.g. the search / android / location tools).
+- **Architecture docs**: [agent_architecture.md](../../agent_architecture.md), [workflow_ops_protocol.md](../../workflow_ops_protocol.md), [frontend_architecture.md](../../frontend_architecture.md) (uiHints table), [Skill Creation Guide](../../../server/skills/GUIDE.md).
diff --git a/docs-internal/node-logic-flows/ai_tools/dataSource.md b/docs-internal/node-logic-flows/ai_tools/dataSource.md
new file mode 100644
index 00000000..75ee4ec5
--- /dev/null
+++ b/docs-internal/node-logic-flows/ai_tools/dataSource.md
@@ -0,0 +1,183 @@
+# Data (`dataSource`)
+
+| Field | Value |
+|------|-------|
+| **Category** | tool / ai (palette group `tool`) |
+| **Backend** | [`server/nodes/tool/data_source/__init__.py::DataSourceNode.data`](../../../server/nodes/tool/data_source/__init__.py) (dispatch via `execute_as_tool` -> `BaseNode.execute()` + `@Operation("data")`; plugin folder: [`_paths.py`](../../../server/nodes/tool/data_source/_paths.py) two-namespace resolution, [`_readers.py`](../../../server/nodes/tool/data_source/_readers.py) bounded typed readers, [`_handlers.py`](../../../server/nodes/tool/data_source/_handlers.py) Data-panel WS API; machine-wide allowlist in [`services/data/mount_store.py`](../../../server/services/data/mount_store.py)) |
+| **WS handlers** | `data_list_mounts` / `data_add_mount` / `data_update_mount` / `data_remove_mount` / `data_browse` (self-registered via `register_ws_handlers`; `@ws_response`, external-socket + authenticated-owner checks, browse additionally requires a saved workflow that owns exactly one `dataSource` node with the given id) |
+| **Tests** | [`server/tests/nodes/test_data_source_node.py`](../../../server/tests/nodes/test_data_source_node.py) (spec, ToolInput validation, path security, workspace tiers, mount flows, handler security); [`server/tests/services/data/test_mount_store.py`](../../../server/tests/services/data/test_mount_store.py) (mount validation matrix) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | ToolNode - tool name `data` (`tool_schema_locked = True`, split schema: LLM sees `DataToolInput`, operator config `DataToolParams` is `server_controlled_fields = {mounts}`) |
+
+## Purpose
+
+An agent-facing raw-data reader/writer over two path namespaces: the
+per-workflow workspace (`reports/q3.csv`) and operator-approved external
+mounts (`mnt/<mount_name>/<rel>`). Reads dispatch to typed, bounded tiers
+(text / csv / json / pdf / html / xlsx / image metadata / binary) so a 20 MB
+spreadsheet cannot become a blown Temporal payload; binary content travels
+as references, never bytes. Writes go to the workspace or to mounts whose
+operator flipped the `writable` flag. There is deliberately **no delete** —
+deletion stays a human action in the gallery panel. `copy_to_workspace`
+imports a mount file as a real `FileRef`, which is the bridge to previews,
+drags and the [`visionAnalyze`](./visionAnalyze.md) tool.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `output-tool` (source, top, label "Data") | tools | yes (only way to use it) | Connect to an agent's `input-tools`; the agent calls `data(...)` |
+
+No `input-main`. uiHints: `isToolPanel`, `isDataPanel` (renders
+`client/src/components/parameterPanel/DataPanel.tsx`), `hideInputSection`,
+`hideOutputSection`, `hideRunButton`; `isConfigNode` auto-derived from the
+`tool` group. A framework-side execution with only `Params` (no tool args)
+is treated as a harmless root `list`.
+
+## Parameters
+
+Operator config, `DataToolParams` (`extra="ignore"`; persisted via the Data
+panel, never exposed to the model):
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `mounts` | string[] (title "Enabled Mounts") | `[]` | no | - | Names of machine-wide mounts this node exposes. A `""` or JSON-string value is coerced (`""`/`None` -> `[]`, JSON array string -> list, other string -> `[string]`) |
+
+LLM-visible arguments, `DataToolInput` (`extra="forbid"`):
+
+| Name | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `operation` | enum `list` \| `read` \| `search` \| `metadata` \| `write` \| `append` \| `copy_to_workspace` | - | yes | Operation |
+| `path` | string, `max_length=4096` | `""` | required (non-empty) by `read`, `metadata`, `write`, `append`, `copy_to_workspace` | Workspace-relative path or `mnt/<mount_name>/<file>`; empty `list` = workspace root + enabled mounts |
+| `pattern` | string \| null, `max_length=256` | `null` | required by `search` | Filename glob or bare term (a term without glob metacharacters becomes `*term*` via `search_to_pattern`) |
+| `as_type` | enum `auto` \| `text` \| `csv` \| `json` \| `pdf` \| `html` \| `xlsx` \| `image` \| `binary` | `auto` | no | `read`: force a tier instead of extension detection |
+| `offset` | integer, `ge=0` | `0` | no | `read`: rows/lines/pages to skip |
+| `limit` | integer, `ge=1, le=500` | `100` | no | rows/lines/pages/entries cap (shared by `list`, `read`, `search`) |
+| `sheet` | string \| null, `max_length=128` | `null` | no | `read` xlsx: sheet name (default: active sheet) |
+| `encoding` | string \| null, `max_length=32` | `null` | no | `read`: force text encoding (else utf-8 -> utf-8-sig -> latin-1 with `encoding_guessed: true`) |
+| `content` | string \| null, `max_length=200000` | `null` | required by `write`, `append` | UTF-8 text |
+| `dest` | string \| null, `max_length=4096` | `null` | no | `copy_to_workspace` destination (default `imports/<filename>`) |
+
+Per-operation required-field failures raise `ValueError("<op> requires
+a, b")` at validation, returned to the model as
+`{"error": "Invalid tool input/configuration: ...", "error_type": "ValidationError"}`.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| (tool result) | object | `DataToolOutput` (`extra="allow"`), passed through `bound_result` (200,000-byte serialized ceiling) |
+
+### Output payload (TypeScript shape)
+
+```ts
+type Common = {
+ operation: string;
+ source: 'workspace' | 'mount';
+ path: string; // canonical round-trippable virtual path
+ mount?: string; // mount name (mount source only)
+ truncated?: boolean; // set by any cap, including bound_result
+};
+type WorkspaceEntry = { /* gallery row */ name: string; path: string; is_dir: boolean; mime_type: string | null;
+ size_bytes: number; modified_at: string | null; ref: FileRef | null; preview: string | null; url?: string | null };
+type MountEntry = { location: string; mount: string; name: string; is_dir: boolean; mime_type: string | null;
+ size_bytes: number; modified_at: number | null; writable: boolean }; // never a FileRef, never a host path
+
+// list
+Common & { entries: WorkspaceEntry[] | MountEntry[]; count: number;
+ mounts?: Array<{ name: string; path: string; writable: boolean; available: boolean }> }; // root listing only
+// search
+Common & { pattern: string; entries: WorkspaceEntry[] | MountEntry[]; count: number };
+// read (tier-dependent)
+Common & (
+ | { type: 'text'; text: string; lines_total: number; offset: number; limit: number; encoding: string; encoding_guessed: boolean }
+ | { type: 'csv'; columns: string[]; rows: string[][]; rows_total: number; offset: number; delimiter: string; encoding: string; encoding_guessed: boolean; columns_truncated: boolean }
+ | { type: 'json'; data: unknown; pruned_paths: string[]; encoding: string; encoding_guessed: boolean }
+ | { type: 'pdf'; pages: Array<{ page: number; text: string; truncated: boolean }>; pages_total: number; offset: number }
+ | { type: 'html'; title: string | null; text: string; lines_total: number; offset: number; encoding: string; encoding_guessed: boolean }
+ | { type: 'xlsx'; sheet: string; sheets: string[]; columns: unknown[]; rows: unknown[][]; rows_total: number; offset: number; columns_truncated: boolean }
+ | { type: 'image'; image: { width: number; height: number; format: string; mode: string }; ref?: FileRef; location?: string;
+ llm_media?: [{ ref: FileRef; detail: 'auto' }] } // workspace refs with png/jpeg/webp/gif mime only
+ | { type: 'binary'; mime_type: string; size_bytes: number; sha256: string; ref?: FileRef; location?: string }
+);
+// metadata
+Common & { type: string; name: string; mime_type: string; size_bytes: number; modified_at: string; sha256: string;
+ ref?: FileRef; location?: string; image?: { width: number; height: number; format: string; mode: string } };
+// write / append
+Common & { bytes_written: number; created: boolean; appended: boolean };
+// copy_to_workspace
+{ operation: 'copy_to_workspace'; source: 'workspace'; path: string; copied_from: string; ref: FileRef };
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[execute_as_tool: validate ToolInput, Params separately; _tool_config on ctx] --> B[data op: mounts = _tool_config.mounts]
+ B --> C{operation}
+ C -- list --> L1{path is mnt/...?}
+ L1 -- yes --> L2[resolve_data_path -> must be dir -> os.scandir -> mount_entry rows, dirs first, cap limit]
+ L1 -- no --> L3[gallery list_directory on workspace_root; root path also appends _mount_summaries]
+ C -- search --> S1[search_to_pattern; empty -> NodeUserError]
+ S1 --> S2{mount?}
+ S2 -- yes --> S3[walk_mount: os.walk no symlink follow, depth 12, 5000 visited, 200 results, fnmatch on name]
+ S2 -- no --> S4[gallery list_matching recursive glob]
+ C -- read --> R1[_resolve_file: exists, not dir, <= MEDIA_MAX_READ_BYTES]
+ R1 --> R2[detect_tier: as_type wins, else extension, else mime]
+ R2 -- image --> R3[Pillow header probe + ref/location; llm_media when workspace ref mime allowlisted]
+ R2 -- binary --> R4[sha256 + mime + size + ref/location - never bytes]
+ R2 -- text/csv/json/pdf/html/xlsx --> R5[bounded reader in asyncio.to_thread]
+ C -- metadata --> M1[_resolve_file -> stat, tier, mime, sha256, ref/location, image dims if image]
+ C -- write/append --> W1[resolve_data_path for_write: mount must be writable, workspace always]
+ W1 --> W2[path lock; append = open ab, write = atomic_write_bytes; mkdir parents]
+ C -- copy_to_workspace --> K1[path must be mnt/...; dest workspace-relative, never mnt/]
+ K1 --> K2[never overwrite: suffix -1..-100; size <= MEDIA_MAX_READ_BYTES]
+ K2 --> K3[shutil.copyfile under path lock -> FileRef]
+ L2 & L3 & S3 & S4 & R3 & R4 & R5 & M1 & W2 & K3 --> Z[setdefault operation; bound_result; DataToolOutput]
+```
+
+## Decision Logic
+
+- **Namespace resolution** (`resolve_data_path`): first segment `mnt` is reserved. A mount path needs a name (`NodeUserError` listing the enabled mounts), the name must be in the node's `mounts` subset AND still present in the `data_mounts` table for the owner (`owner_id` = `ctx.user_id` / `ctx.raw.user_id` / `"owner"`), otherwise `NodeUserError`. Containment: reads use `resolve_within`, mutations `resolve_entry_within` (parent proven, basename appended unresolved); both roots are symlink-safe; `ValueError` from the backend helpers is translated to `NodeUserError`.
+- **Write gate**: mounts require `writable`; writing to a mount root or the workspace root is refused; a directory target is refused. The workspace is always writable.
+- **Tier detection** (`detect_tier`): explicit `as_type` wins; `.csv/.tsv` -> csv, `.json` -> json, `.pdf` -> pdf, `.html/.htm/.xhtml` -> html, `.xlsx/.xlsm` -> xlsx, a fixed text-extension set -> text; then mime `image/*` -> image, `text/*` -> text; else binary.
+- **Bounds** (`_readers.py`): text window 65,536 bytes; csv 500 rows / 100 cols / 2,000 chars per cell (delimiter sniffed from the first 16 KiB, `\t` fallback for `.tsv`); json source <= 5 MiB, depth 8 with `pruned_paths` (50 max); pdf 20 pages per call, 20,000 chars per page; xlsx 500 rows (`read_only`, `data_only`, `rows_total` from `max_row - 1`); mount search depth 12 / 5,000 visited / 200 results; `bound_result` halves `rows` / `pages` / `entries` / `matches` / `items` then trims `text` / `data` until the envelope is <= 200,000 bytes and sets `truncated`.
+- **References**: workspace targets get `ref` (a serialized `FileRef`, always `kind: "file"` via `to_file_ref`); mount targets get `location` only — host paths never leave the server.
+- **Vision opt-in**: an image-tier `read` of a workspace file whose mime is in `IMAGE_MIME_ALLOWLIST` (`png`, `jpeg`, `webp`, `gif`) adds `llm_media: [{ref, detail: "auto"}]`, which the agent loop turns into a ref-only image block; mount images must be `copy_to_workspace`d first.
+- **Error paths**: every user-correctable failure is a `NodeUserError` (missing file, directory-vs-file confusion, oversize, read-only mount, revoked mount, invalid JSON, bad encoding, missing optional dependency with the install hint, unknown sheet, too many copies). `execute_as_tool` renders it as `{"error": ...}` for the model.
+
+## Side Effects
+
+- **Database reads**: `data_mounts` via `DataMountStore.list_mounts` / `get_mount` (root listing and every mount resolution).
+- **Database writes**: none from the tool operation. The panel handlers write `data_mounts` rows (`add` validates: absolute, exists, directory, not a filesystem root, not the home dir, no overlap with `DATA_DIR` or a legacy `~/.machina`, readable, writable-if-flagged, unique name matching `^[a-z0-9][a-z0-9_-]{0,63}$`, unique root; `update` toggles only `writable`).
+- **Broadcasts**: none.
+- **External API calls**: none.
+- **File I/O**: reads under the workspace or mount roots; `write`/`append` create parent directories, `write` is atomic (`atomic_write_bytes`), `append` opens in `ab`; `copy_to_workspace` copies bytes into the workspace; all mutations take the per-path lock from `nodes/filesystem/_backend`.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: none.
+- **Services**: `services.media.workspace` (`workspace_root`, `workspace_file_url`), `services.media.limits.MEDIA_MAX_READ_BYTES`, `nodes/filesystem/_backend` (`resolve_within`, `resolve_entry_within`, `atomic_write_bytes`, `get_path_lock`), `nodes/filesystem/gallery/_service` (`list_directory`, `list_matching`, `search_to_pattern`, `to_file_ref`), `services.data.mount_store`, `services.llm.media.IMAGE_MIME_ALLOWLIST`.
+- **Python packages**: stdlib for text/csv/json/binary; `pypdf` (`docs` extra) for pdf; `beautifulsoup4` (`docs` extra) for html; `openpyxl` for xlsx; `Pillow` for image metadata. Each missing package surfaces as a `NodeUserError` with the install hint (html additionally suggests `as_type='text'`).
+- **Environment variables**: none directly (`DATA_DIR` shapes the protected roots via `core.paths`).
+- **Task queue**: `TaskQueue.DEFAULT`. Annotations: not destructive, not readonly, not open_world.
+
+## Edge cases & known limits
+
+- `limit` is one knob for three different things (listing entries, read rows/lines/pages, search results); a model paging a CSV with `limit=500` also caps its next listing at 500.
+- `read` and `metadata` compute a full SHA-256 of binary files (up to 25 MiB) on every call.
+- `list` on the workspace passes `limit` to the gallery's `list_directory`, which applies its own `WORKSPACE_LIST_LIMIT` cap in addition.
+- Mount `search` matches the **file name** only (`fnmatch` on `name.lower()`), never the relative directory; workspace `search` uses the backend's recursive glob.
+- Mount listings expose symlinked files (walks do not follow symlinked directories); reading one later still goes through `resolve_within`, which rejects escapes.
+- `copy_to_workspace` suffixing stops after 100 attempts with a `NodeUserError`.
+- `write` of an empty `content` is rejected by validation (required fields are checked with truthiness), so an agent cannot create an empty file.
+- Windows backslashes are normalized to `/`; `_clean` also strips leading/trailing slashes, so `/mnt/x/f` and `mnt/x/f` are the same path.
+- Mount availability is re-checked on every call: a mount removed in the panel fails immediately even if a stale node still lists it (`available: false` in the root listing).
+- No delete, no rename, no move — by design.
+
+## Related
+
+- **Skills using this as a tool**: none (the `tool_description` carries the usage contract).
+- **Other nodes that consume this output**: [`visionAnalyze`](./visionAnalyze.md) (takes workspace-relative image paths discovered here), [`canvas`](./canvas.md) (displays `ref`s), `gallery` (human-side deletion).
+- **Architecture docs**: [data_node.md](../../data_node.md), [media_transport.md](../../media_transport.md), [plugin_system.md](../../plugin_system.md).
diff --git a/docs-internal/node-logic-flows/ai_tools/visionAnalyze.md b/docs-internal/node-logic-flows/ai_tools/visionAnalyze.md
new file mode 100644
index 00000000..49ff7ad6
--- /dev/null
+++ b/docs-internal/node-logic-flows/ai_tools/visionAnalyze.md
@@ -0,0 +1,131 @@
+# Vision Analyze (`visionAnalyze`)
+
+| Field | Value |
+|------|-------|
+| **Category** | tool / ai (palette group `tool`; plugin folder `nodes/vision/`) |
+| **Backend** | [`server/nodes/vision/vision_analyze/__init__.py::VisionAnalyzeNode.vision`](../../../server/nodes/vision/vision_analyze/__init__.py) (dispatch via `execute_as_tool` -> `BaseNode.execute()` + `@Operation("vision")`; budget fitting in [`services/media/image_fit.py`](../../../server/services/media/image_fit.py); contained read via [`services/media/workspace.py::read_media_bytes`](../../../server/services/media/workspace.py)) |
+| **Tests** | [`server/tests/nodes/test_vision_analyze.py`](../../../server/tests/nodes/test_vision_analyze.py) (`TestSmartResize`, `TestFitImageBytes`, `TestSpecInvariants`, `TestProviderRequestShapes`, `TestSafety`) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | ToolNode - tool name `vision` (`tool_schema_locked = True`, split schema: LLM sees `VisionAnalyzeToolInput`; `provider` and `vision_model` are `server_controlled_fields`) |
+
+## Purpose
+
+Gives every agent — including ones running text-only models — real image
+understanding by delegating to a vision-capable model. The tool loads a
+workspace image at the provider boundary (bytes exist only inside the call
+and never enter results), fits it to a visual-token budget, sends it to the
+operator-chosen provider with an official SDK request shape, and returns
+text: `describe` (optionally steered by `question`) or `extract_text`
+(OCR-style). This is deliberately the speech-node shape rather than a
+`ChatUnifier` call, so it works regardless of the host agent's provider and
+remains the fallback rung for text-only host models once native image
+blocks land.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `output-tool` (source, top, label "Vision") | tools | yes | Connect to an agent's `input-tools`; the agent calls `vision(...)` |
+
+No `input-main`. uiHints: `isToolPanel`, `hideInputSection`,
+`hideOutputSection`, `hideRunButton`; `isConfigNode` auto-derived. A direct
+execution (Params only, no tool args) raises `NodeUserError("The vision tool
+needs an image argument; connect it to an agent's tools ...")`.
+
+## Parameters
+
+Operator config, `VisionAnalyzeParams` (`extra="ignore"`):
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `provider` | enum `openai` \| `anthropic` \| `gemini` | `openai` | no | - | Which vision-capable provider answers the delegate call |
+| `vision_model` | string | `""` | no | - | Vision model id; empty uses the provider's `default_model` from `llm_defaults.json` (`NodeUserError` if none is configured). Deliberately NOT named `model`: with a sibling `provider` field `ParameterRenderer.tsx` would overwrite a field literally named `model` with the chat-model list |
+
+LLM-visible arguments, `VisionAnalyzeToolInput` (`extra="forbid"`):
+
+| Name | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `operation` | enum `describe` \| `extract_text` | - | yes | Describe the image, or extract visible text |
+| `image` | string, `min_length=1, max_length=4096` (whitespace-only rejected) | - | yes | Workspace-relative path (e.g. `imports/chart.png`); use the `data` tool to discover files |
+| `question` | string \| null, `max_length=4000` | `null` | no | `describe` only: a specific question about the image (ignored by `extract_text`) |
+| `budget` | enum `small` \| `normal` \| `large` | `normal` | no | Visual-token budget: 256 / 1024 / 2048 tokens -> `tokens x 28^2` pixels (200,704 / 802,816 / 1,605,632) |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| (tool result) | object | `VisionAnalyzeOutput` (`extra="allow"`) |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ operation: 'describe' | 'extract_text';
+ provider: 'openai' | 'anthropic' | 'gemini';
+ vision_model: string; // resolved model id
+ text: string; // provider text ("" if the provider returned nothing)
+ image: { width: number; height: number; source: string }; // fitted dimensions + the requested path; never bytes
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[execute_as_tool: ToolInput + Params validated separately] --> B{params is bare Params?}
+ B -- yes - direct run --> E1[NodeUserError: needs an image argument]
+ B -- no --> C[config = ctx.raw._tool_config; provider; model = vision_model or _default_model]
+ C -- no default model --> E2[NodeUserError: set vision_model]
+ C --> D[read_media_bytes image, ctx, max MEDIA_MAX_READ_BYTES - containment via resolve_media]
+ D -- ValueError --> E3[NodeUserError str exc]
+ D -- missing / empty / oversize --> E4[NodeUserError from read_media_bytes]
+ D --> F[fit_image_bytes budget: smart_resize into min..max pixel window, snap to 28 px grid, LANCZOS; alpha -> PNG else JPEG q90]
+ F -- any exception --> E5[NodeUserError: not a readable image]
+ F --> G[prompt = question if describe and question else canned prompt]
+ G --> H[_api_key: ctx.connection provider .credentials .api_key]
+ H -- empty --> E6[NodeUserError: No API key stored for provider]
+ H --> I{provider}
+ I -- openai --> J[chat.completions.create model, max_completion_tokens 1024, text + image_url data URL detail auto]
+ I -- anthropic --> K[messages.create model, max_tokens 1024, image base64 block then text]
+ I -- gemini --> L[models.generate_content model, Part.from_bytes + prompt]
+ J & K & L --> M[VisionAnalyzeOutput text + fitted width/height + source path]
+```
+
+## Decision Logic
+
+- **Validation**: `image` must be non-blank; `question` is only consulted for `describe`; `extra="forbid"` rejects any unknown argument (`ValidationError` -> `{"error": "Invalid tool input/configuration: ..."}`).
+- **Config precedence** (`_config`): `ctx.raw["_tool_config"]` (validated persisted Params from `execute_as_tool`) > a bare `Params` instance > defaults. Model arguments can never set `provider` / `vision_model`.
+- **Model resolution**: `vision_model.strip()` or `get_provider_config(provider).default_model`; a provider without a configured default raises `NodeUserError`.
+- **Fitting** (`image_fit.smart_resize`): one aspect-preserving scale into `[min_pixels, max_pixels]` (floor = the `small` budget, 200,704 px, so tiny images are scaled UP), both dimensions rounded to multiples of 28 (minimum 28); resize only when the target differs; alpha (`RGBA`/`LA`/`PA`/palette with transparency) keeps PNG, otherwise JPEG quality 90.
+- **Error paths**: containment/`ValueError` from the media reader -> `NodeUserError`; not-an-image -> `NodeUserError`; missing credential row -> `Connection.credentials()` raises `PermissionError` (rendered by `BaseNode.execute()` as the annotated credential envelope), an empty stored key -> `NodeUserError`; provider SDK exceptions are **not** caught here — they propagate as genuine errors (full traceback), not as `LLMError` -> `NodeUserError` (this path bypasses `ChatUnifier`).
+
+## Side Effects
+
+- **Database writes**: none. Token usage is deliberately NOT recorded through the pricing service (same stance as the LLM-backed translate providers): this path bills provider tokens the LLM pricing layer has no per-call meter for.
+- **Broadcasts**: none.
+- **External API calls**: exactly one — OpenAI `POST /v1/chat/completions` (`AsyncOpenAI(api_key)`), Anthropic `messages.create` (`AsyncAnthropic(api_key)`), or Gemini `generate_content` (`genai.Client(api_key)`). The image is sent inline as base64 (data URL for OpenAI, `source.type = base64` for Anthropic, `Part.from_bytes` for Gemini); `detail` is set explicitly to `auto` for OpenAI because omitting it has caused order-of-magnitude token regressions elsewhere.
+- **File I/O**: one contained read of the workspace image; nothing written.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: the provider's stored API key resolved through `ctx.connection(<provider>)` -> `Credential.resolve` for the credential whose id equals the provider string (`OpenAICredential` / `AnthropicCredential` / `GeminiCredential` in `nodes/model/_credentials.py`). The node declares no `credentials` tuple of its own.
+- **Services**: `services.media` (`read_media_bytes`, `resolve_media` containment, `MEDIA_MAX_READ_BYTES`), `services.media.image_fit`, `services.llm.config.get_provider_config`.
+- **Python packages**: `Pillow`; `openai`, `anthropic`, `google-genai` (imported lazily per provider).
+- **Task queue**: `TaskQueue.AI_HEAVY`. Annotations: `readonly`, `open_world` (image content leaves the machine).
+
+## Edge cases & known limits
+
+- Workspace-relative paths only: a `mnt/...` mount path from the `data` tool is not resolvable here — `copy_to_workspace` first.
+- Output is capped at 1,024 tokens per call (`_MAX_OUTPUT_TOKENS`), not configurable.
+- `budget` controls the pixel area sent, not the provider's own tiling: 28 px is the Anthropic patch edge used as a single default for every provider.
+- `llm_defaults.json providers.<p>.vision.enabled` (the native-image-block gate) is irrelevant to this tool — it always sends the image, regardless of that flag.
+- Gemini uses the plain `AIza` API-key client only; Vertex/ADC project auth is not supported on this path.
+- An empty provider response yields `text: ""` with `success: true` — no retry, no error.
+- Every call re-reads and re-encodes the image; there is no cache across repeated questions about the same file.
+
+## Related
+
+- **Skills using this as a tool**: none.
+- **Other nodes that consume this output**: none directly; pairs with [`dataSource`](./dataSource.md) (path discovery, `llm_media` opt-in for natively vision-capable hosts) and [`canvas`](./canvas.md) / browser screenshot FileRefs as inputs.
+- **Architecture docs**: [data_node.md](../../data_node.md) (vision section + native image blocks), [media_transport.md](../../media_transport.md), [native_llm_sdk.md](../../native_llm_sdk.md).
diff --git a/docs-internal/node-logic-flows/android/_pattern.md b/docs-internal/node-logic-flows/android/_pattern.md
index 4fba4e0c..419d32f7 100644
--- a/docs-internal/node-logic-flows/android/_pattern.md
+++ b/docs-internal/node-logic-flows/android/_pattern.md
@@ -11,8 +11,8 @@ Wave 11.C migrated all 16 Android nodes to self-contained plugin folders
under `server/nodes/android/<service>/__init__.py`. Each is a trivial
subclass of the shared `AndroidServiceBase` (`server/nodes/android/_base.py`)
that sets `type` / `display_name` / `description` / `tool_name` only. The old
-`server/services/handlers/android.py::handle_android_service` and
-`server/services/android_service.py` files are **deleted**. Dispatch flows
+`handlers/android.py::handle_android_service` handler and the
+`android_service.py` service module are **deleted**. Dispatch flows
through `BaseNode.execute()` -> the `@Operation("invoke")` method on
`AndroidServiceBase`.
diff --git a/docs-internal/node-logic-flows/chat_utility/chatSend.md b/docs-internal/node-logic-flows/chat_utility/chatSend.md
index deecd748..3b0ad1f2 100644
--- a/docs-internal/node-logic-flows/chat_utility/chatSend.md
+++ b/docs-internal/node-logic-flows/chat_utility/chatSend.md
@@ -93,7 +93,8 @@ flowchart TD
- **Credentials**: optional `api_key` parameter forwarded as the chat backend's
auth token. No lookup via `auth_service`.
- **Services**: external chat backend speaking the project chat JSON-RPC
- protocol (e.g. the chat mircoservice in `docs-internal/chat-service.md`).
+ protocol (see `services/chat_client.py` for the client side; no in-repo
+ server exists).
- **Python packages**: `websockets` (via `services.chat_client`).
- **Environment variables**: none.
diff --git a/docs-internal/node-logic-flows/chat_utility/gmaps_locations.md b/docs-internal/node-logic-flows/chat_utility/gmaps_locations.md
new file mode 100644
index 00000000..46990185
--- /dev/null
+++ b/docs-internal/node-logic-flows/chat_utility/gmaps_locations.md
@@ -0,0 +1,125 @@
+# Geocoding (`gmaps_locations`)
+
+| Field | Value |
+|------|-------|
+| **Category** | chat_utility (grouping) / location (functional domain; palette groups `location`, `service`, `tool`) |
+| **Backend handler** | [`server/nodes/location/gmaps_locations/__init__.py::GmapsLocationsNode.geocode`](../../../server/nodes/location/gmaps_locations/__init__.py) — dispatch via `BaseNode.execute()` + `@Operation("geocode")` -> [`server/nodes/location/_service.py::MapsService.geocode_location`](../../../server/nodes/location/_service.py) |
+| **Tests** | none dedicated — spec-level coverage only: `TestPhase3dCoverage` in [`server/tests/test_node_spec.py`](../../../server/tests/test_node_spec.py), tool-name snapshot in [`server/tests/fixtures/tool_names_snapshot.json`](../../../server/tests/fixtures/tool_names_snapshot.json) |
+| **Skill (if any)** | [`server/skills/travel_agent/geocoding-skill/SKILL.md`](../../../server/skills/travel_agent/geocoding-skill/SKILL.md) (`allowed-tools: "gmaps_locations"`) |
+| **Dual-purpose tool** | yes - tool name `geocode` (`usable_as_tool = True`) |
+
+## Purpose
+
+Forward geocoding (address -> coordinates) and reverse geocoding
+(coordinates -> address) through the Google Maps Geocoding API via the
+`googlemaps` client. Used as a workflow node or, more commonly, as the
+`geocode` tool on a travel/consumer agent. Each call tracks a `geocode` or
+`reverse_geocode` usage row at $0.005 (from `pricing.json`).
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream address / coordinates via templates |
+| `output-tool` (source, synthesized) | tools | no | `usable_as_tool = True` with neither hide flag declared: the base class marks `input-main` / `output-main` hidden on the canvas and `_metadata_dict` appends an `output-tool` handle for agent wiring |
+
+## Parameters
+
+Params model `GmapsLocationsParams` (`extra="ignore"`):
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `service_type` | enum `geocode` \| `reverse_geocode` | `geocode` | no | - | `geocode`: address -> lat/lng; `reverse_geocode`: lat/lng -> address |
+| `address` | string | `""` | required by `geocode` (service raises "Address is required for geocoding") | `service_type: [geocode]` | Street address or place name |
+| `region` | string | `""` | no | `service_type: [geocode]` | ISO country code bias — **never read by the service** (see Edge cases) |
+| `lat` | number | `0.0` | no | `service_type: [reverse_geocode]` | Latitude (-90..90, validated by the service) |
+| `lng` | number | `0.0` | no | `service_type: [reverse_geocode]` | Longitude (-180..180) |
+
+The API key is not a Param. `node_executor._inject_api_keys` adds `api_key`
+to the raw params for `GOOGLE_MAPS_TYPES` (stored `google_maps` credential,
+else `settings.google_maps_api_key`), but `extra="ignore"` drops it from
+`params.model_dump()`, so `MapsService.geocode_location` sees no `api_key`
+and falls back to `settings.google_maps_api_key` (env
+`GOOGLE_MAPS_API_KEY`). `GoogleMapsCredential` (`google_maps`) is declared on
+the node for credential-modal visibility and key validation.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | The service's `result` dict. `GmapsLocationsOutput` declares `latitude` / `longitude` / `formatted_address` / `place_id`, but the op returns the raw service payload; with `extra="allow"` + `exclude_unset` serialization the declared fields are simply absent |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ service_type: 'geocoding' | 'reverse_geocoding';
+ input: { address: string } | { lat: number; lng: number };
+ results: Array<GoogleGeocodingResult>; // raw googlemaps client rows: formatted_address, geometry.location, place_id, address_components, ...
+ status: 'OK' | 'ZERO_RESULTS';
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[geocode op: params.model_dump] --> B[MapsService.geocode_location node_id, params, ctx.raw]
+ B --> C{api_key from params or settings?}
+ C -- none --> E[success false: Google Maps API key is required]
+ C -- ok --> D[googlemaps.Client key]
+ D --> F{service_type}
+ F -- geocode --> G{address empty?}
+ G -- yes --> E2[success false: Address is required for geocoding]
+ G -- no --> H[gmaps.geocode address - synchronous call]
+ H --> I[_track_maps_usage geocode]
+ F -- reverse_geocode --> J{validate_coordinates lat, lng}
+ J -- invalid --> E3[success false: Invalid coordinates]
+ J -- ok --> K[gmaps.reverse_geocode lat, lng - synchronous call]
+ K --> L[_track_maps_usage reverse_geocode]
+ F -- other --> E4[success false: Unsupported service type]
+ H -- ApiError --> E5[success false: Google Maps API error: ...]
+ K -- ApiError --> E5
+ I --> M[result service_type, input, results, status OK or ZERO_RESULTS]
+ L --> M
+ M --> N[op returns response.result]
+ E & E2 & E3 & E4 & E5 --> O[op raises NodeUserError response.error]
+```
+
+## Decision Logic
+
+- **Validation** (inside the service): API key present; `address` non-empty for `geocode`; `validate_coordinates` for `reverse_geocode`; unknown `service_type` (unreachable through the Literal) -> error.
+- **Branches**: `geocode` vs `reverse_geocode`; `status` is `OK` when the client returned rows, `ZERO_RESULTS` otherwise (still `success: true`).
+- **Fallbacks**: `lat` / `lng` default to `0` inside the service when missing.
+- **Error paths**: the service returns `{success: false, error}` for `googlemaps.exceptions.ApiError` (prefixed "Google Maps API error: ") and any other exception; the op raises `NodeUserError(error or "Geocoding failed")` so the framework emits one WARN line and the structured error envelope (as a tool: `{"error": ...}`).
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per successful call via `_track_maps_usage` (`service: google_maps`, `operation`/`endpoint: geocode` or `reverse_geocode`, `resource_count: 1`, cost from `PricingService.calculate_api_cost` — $0.005 each per `pricing.json`), keyed by `ctx.raw.workflow_id` / `session_id`. The `cost=` on `@Operation` is inert metadata.
+- **Broadcasts**: none.
+- **External API calls**: Google Geocoding API through `googlemaps.Client` (key as query param).
+- **File I/O / Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `GoogleMapsCredential` (`google_maps`, `key_location = "query"`, probe = geocoding a sentinel address); at execution time the service effectively needs `settings.google_maps_api_key` (see Edge cases).
+- **Services**: `MapsService` via `services.plugin.deps.get_maps_service()`, `PricingService`.
+- **Python packages**: `googlemaps`.
+- **Environment variables**: `GOOGLE_MAPS_API_KEY` (the fallback that is, in practice, the only key the service uses).
+- **Task queue**: `TaskQueue.REST_API`. Annotations: `readonly`, `open_world`.
+
+## Edge cases & known limits
+
+- **Stored credential vs env key**: the injected `api_key` is stripped by `extra="ignore"` before `params.model_dump()` reaches the service, so a key saved in the Credentials modal is not what executes — only `GOOGLE_MAPS_API_KEY` works. (Documented, not fixed here; same wiring as `gmaps_create`.)
+- `region` is a dead parameter: the service never passes it to `gmaps.geocode`.
+- The `googlemaps` client is synchronous; `gmaps.geocode` / `gmaps.reverse_geocode` block the event loop for the duration of the HTTP call (no `to_thread`).
+- `results` is the untrimmed Google payload — several KB per row — and it is persisted, broadcast and (as a tool) replayed into the LLM context.
+- Usage is charged even for `ZERO_RESULTS`.
+- The declared `Output` fields (`latitude`, `longitude`, `formatted_address`, `place_id`) never appear; consumers must read `results[0].geometry.location` / `results[0].formatted_address` themselves.
+- The skill doc still calls the node "Add Locations" with an `add_locations` tool; the registered display name is "Geocoding" and the tool name is `geocode`. Its argument table (`service_type`, `address`, `lat`, `lng`) does match the Params.
+
+## Related
+
+- **Skills using this as a tool**: [`geocoding-skill`](../../../server/skills/travel_agent/geocoding-skill/SKILL.md).
+- **Other nodes that consume this output**: [`gmaps_nearby_places`](./gmaps_nearby_places.md) (coordinates), [`gmaps_create`](./gmaps_create.md) (map centre).
+- **Architecture docs**: [pricing_service.md](../../pricing_service.md), [plugin_system.md](../../plugin_system.md).
diff --git a/docs-internal/node-logic-flows/chat_utility/gmaps_nearby_places.md b/docs-internal/node-logic-flows/chat_utility/gmaps_nearby_places.md
new file mode 100644
index 00000000..1ebd2d67
--- /dev/null
+++ b/docs-internal/node-logic-flows/chat_utility/gmaps_nearby_places.md
@@ -0,0 +1,129 @@
+# Nearby Places (`gmaps_nearby_places`)
+
+| Field | Value |
+|------|-------|
+| **Category** | chat_utility (grouping) / location (functional domain; palette groups `location`, `service`, `tool`) |
+| **Backend handler** | [`server/nodes/location/gmaps_nearby_places/__init__.py::GmapsNearbyPlacesNode.nearby`](../../../server/nodes/location/gmaps_nearby_places/__init__.py) — dispatch via `BaseNode.execute()` + `@Operation("nearby")` -> [`server/nodes/location/_service.py::MapsService.find_nearby_places`](../../../server/nodes/location/_service.py) |
+| **Tests** | none dedicated — spec-level coverage only: `TestPhase3dCoverage` in [`server/tests/test_node_spec.py`](../../../server/tests/test_node_spec.py), identifier list in [`server/tests/services/test_identifiers.py`](../../../server/tests/services/test_identifiers.py), tool-name snapshot in [`server/tests/fixtures/tool_names_snapshot.json`](../../../server/tests/fixtures/tool_names_snapshot.json) |
+| **Skill (if any)** | [`server/skills/travel_agent/nearby-places-skill/SKILL.md`](../../../server/skills/travel_agent/nearby-places-skill/SKILL.md) (`allowed-tools: "gmaps_nearby_places"`) |
+| **Dual-purpose tool** | yes - tool name `nearby_places` (`usable_as_tool = True`) |
+
+## Purpose
+
+Google Places API `nearbySearch` around a coordinate: restaurants, banks,
+hospitals, etc., filtered by type and keyword. Used as a workflow node or as
+the `nearby_places` tool on a travel/consumer agent. Each call tracks a
+`nearby_search` usage row at $0.032.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream coordinates (e.g. from `gmaps_locations`) via templates |
+| `output-tool` (source, synthesized) | tools | no | `usable_as_tool = True` with neither hide flag declared: canvas `input-main` / `output-main` are flagged hidden and `_metadata_dict` appends `output-tool` |
+
+## Parameters
+
+Params model `GmapsNearbyPlacesParams` (`extra="ignore"`):
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `latitude` | number, `ge=-90, le=90` | - | yes | - | Search centre latitude — **not read by the service** (see Edge cases) |
+| `longitude` | number, `ge=-180, le=180` | - | yes | - | Search centre longitude — **not read by the service** |
+| `radius` | integer, `ge=1, le=50000` | `1000` | no | - | Search radius in metres (the only Param the service actually consumes) |
+| `place_type` | string | `""` | no | - | Place type — **not read by the service** (it reads `type`) |
+| `keyword` | string | `""` | no | - | Keyword filter — **not read by the service** (it reads `options.keyword`) |
+
+The API key is not a Param; the injected `api_key` is dropped by
+`extra="ignore"` before `params.model_dump()` and the service falls back to
+`settings.google_maps_api_key` (see [`gmaps_locations`](./gmaps_locations.md)).
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | The service's `result` dict. `GmapsNearbyPlacesOutput` declares `places` / `count`, but the op returns the raw service payload (`extra="allow"`, declared fields absent) |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ search_parameters: {
+ location: { lat: number; lng: number };
+ radius: number | null; // null when rank_by === 'distance'
+ type: string;
+ keyword: string | null;
+ name_filter: string | null;
+ min_price: number | null;
+ max_price: number | null;
+ open_now: boolean;
+ language: string;
+ rank_by: 'prominence' | 'distance';
+ page_size: number; // <= 20
+ };
+ results: Array<GooglePlaceResult>; // raw googlemaps rows, sliced to page_size
+ total_results: number;
+ status: string; // Google status, default 'OK'
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[nearby op: params.model_dump -> latitude, longitude, radius, place_type, keyword] --> B[MapsService.find_nearby_places node_id, params, ctx.raw]
+ B --> C{api_key from params or settings?}
+ C -- none --> E[success false: Google Maps API key is required]
+ C -- ok --> D[lat = params.lat default 40.7484; lng = params.lng default -73.9857; radius = params.radius]
+ D --> F{validate_coordinates and 1 <= radius <= 50000}
+ F -- invalid --> E2[success false]
+ F -- ok --> G[type = params.type default restaurant; page_size min 20; options = params.options default {}]
+ G --> H[keyword/name/min_price/max_price/open_now/language/rank_by read from options dict]
+ H --> I[search_params location, type, radius unless rank_by distance, + optional filters]
+ I --> J[gmaps.places_nearby - synchronous call]
+ J -- ApiError --> E3[success false: Google Places API error: ...]
+ J --> K[results sliced to page_size]
+ K --> L[_track_maps_usage nearby_search]
+ L --> M[result search_parameters, results, total_results, status]
+ M --> N[op returns response.result]
+ E & E2 & E3 --> O[op raises NodeUserError response.error]
+```
+
+## Decision Logic
+
+- **Validation**: Pydantic enforces the coordinate and radius ranges on the Params; the service re-validates `lat`/`lng` (on its own defaulted values) and `radius`.
+- **Branches**: `rank_by == "distance"` drops `radius` and sends `rank_by`; each optional filter is added only when set. All of these branches are reachable only through the service's `options` dict, which the plugin never populates.
+- **Fallbacks** (service defaults, all of which fire under the current wiring): `lat 40.7484`, `lng -73.9857`, `type "restaurant"`, `page_size 20`, `language "en"`, `rank_by "prominence"`, `open_now False`.
+- **Error paths**: `googlemaps.exceptions.ApiError` -> `success: false` with "Google Places API error: "; any other exception -> `success: false`; the op raises `NodeUserError(error or "Nearby places failed")`.
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per successful call (`service: google_maps`, `operation`/`endpoint: nearby_search`, `resource_count: 1`, $0.032 per `pricing.json`; `operation_map` also maps `nearby_places` -> `nearby_search`). The `cost=` on `@Operation` (`action: places_nearby`) is inert metadata and names an action `pricing.json` does not list.
+- **Broadcasts**: none.
+- **External API calls**: Google Places Nearby Search through `googlemaps.Client.places_nearby`.
+- **File I/O / Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `GoogleMapsCredential` (`google_maps`); at execution time effectively `settings.google_maps_api_key`.
+- **Services**: `MapsService` via `get_maps_service()`, `PricingService`.
+- **Python packages**: `googlemaps`.
+- **Environment variables**: `GOOGLE_MAPS_API_KEY`.
+- **Task queue**: `TaskQueue.REST_API`. Annotations: `readonly`, `open_world`.
+
+## Edge cases & known limits
+
+- **Param/service key mismatch (load-bearing)**: the plugin dumps `latitude` / `longitude` / `place_type` / `keyword`, but `find_nearby_places` reads `lat` / `lng` / `type` and takes `keyword` only from a nested `options` dict (`parameters.get("options", {})` is a dict, so the top-level `keyword` fallback branch is never taken). Under the current wiring every call therefore searches for `restaurant` within `radius` metres of `40.7484, -73.9857` regardless of the configured centre, type or keyword. Only `radius` reaches the API. (Documented, not fixed here; same class of bug as the `gmaps_create` card.)
+- The tool path cannot route around it: the LLM schema is derived from the Params (`latitude`, `longitude`, ...), and a model following the skill doc's `lat` / `lng` / `type` names has those arguments stripped by `extra="ignore"` during the `{**node_params, **tool_args}` merge.
+- The service's richer filters (`name`, `min_price`, `max_price`, `open_now`, `language`, `rank_by`) are unreachable from the node.
+- Synchronous `googlemaps` call blocks the event loop.
+- `results` is the raw Google payload (up to 20 rows of several KB each), persisted, broadcast and replayed into LLM context when used as a tool.
+- Usage is charged on every successful call, including empty result sets.
+- The declared `Output` fields (`places`, `count`) never appear; the real keys are `results` / `total_results`.
+- The skill doc still calls the node "Show Nearby Places" with a `show_nearby_places` tool and a `type` field; the registered display name is "Nearby Places", the tool is `nearby_places`, and the Params field is `place_type`.
+
+## Related
+
+- **Skills using this as a tool**: [`nearby-places-skill`](../../../server/skills/travel_agent/nearby-places-skill/SKILL.md).
+- **Other nodes that feed this**: [`gmaps_locations`](./gmaps_locations.md) (coordinates from an address); [`gmaps_create`](./gmaps_create.md) shares the same `MapsService` and key-fallback behaviour.
+- **Architecture docs**: [pricing_service.md](../../pricing_service.md), [plugin_system.md](../../plugin_system.md).
diff --git a/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md b/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md
new file mode 100644
index 00000000..293cc652
--- /dev/null
+++ b/docs-internal/node-logic-flows/cli_integrations/cloudflareAction.md
@@ -0,0 +1,199 @@
+# Cloudflare (`cloudflareAction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | deployment (palette group `deployment`; class `group = ("deployment", "tool")`) |
+| **Backend handler** | [`server/nodes/cloudflare/cloudflare_action.py`](../../../server/nodes/cloudflare/cloudflare_action.py) (`CloudflareActionNode`, on `ActionNode`); env / credential routing in [`_service.py`](../../../server/nodes/cloudflare/_service.py); installer [`_install.py`](../../../server/nodes/cloudflare/_install.py); login WS handlers [`_handlers.py`](../../../server/nodes/cloudflare/_handlers.py) |
+| **Tests** | [`server/tests/test_cloudflare_plugin.py`](../../../server/tests/test_cloudflare_plugin.py) |
+| **Skill (if any)** | [`server/skills/cloudflare/cloudflare-skill/SKILL.md`](../../../server/skills/cloudflare/cloudflare-skill/SKILL.md) (`allowed-tools: "cloudflare"`) |
+| **Dual-purpose tool** | yes - tool name `cloudflare` |
+
+## Purpose
+
+Drive Cloudflare through the official `cf` CLI (npm `[email protected]`, a technical
+preview) from a workflow or from an agent. Six typed operations cover auth
+identity, zone listing and DNS record CRUD, one operation posts directly to
+the GraphQL Analytics API (the only channel to zone traffic / RUM analytics,
+which the cf OAuth grant cannot reach), and `custom` passes any `cf ...`
+command through verbatim. The CLI owns its own auth: the node performs no
+credential pre-flight and never injects a token into argv.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Declared, but `hideInputHandle` is auto-set (`usable_as_tool = True` and the class does not declare `hide_input_handle`) - the node is normally reached through `output-tool` |
+
+## Parameters
+
+`extra="ignore"` on the model. `record_body` and `graphql_variables` have a
+`mode="before"` validator that `json.dumps` a dict / list (LLM tool calls pass
+real objects; the CLI flag and HTTP body want a string).
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | `whoami \| zones_list \| dns_records_list \| dns_record_create \| dns_record_delete \| graphql_query \| custom` | `whoami` | no | - | Operation dispatch key |
+| `zone` | string | `""` | yes* | `operation` in `dns_records_list`, `dns_record_create`, `dns_record_delete` | Zone ID or domain name; becomes the global `--zone` flag. Empty raises `NodeUserError` on any DNS op |
+| `name_filter` | string | `""` | no | `operation=zones_list` | `--name <f>` when non-blank |
+| `account_id` | string | `""` | no | `operation=zones_list` | `--account-id <id>` when non-blank |
+| `record_body` | string (JSON) | `""` | yes* | `operation=dns_record_create` | Raw JSON request body passed as `--body`; validated with `json.loads` first |
+| `record_id` | string | `""` | yes* | `operation=dns_record_delete` | Positional record id for `dns records delete` |
+| `graphql_query` | string | `""` | yes* | `operation=graphql_query` | GraphQL Analytics API query text |
+| `graphql_variables` | string (JSON object) | `""` | no | `operation=graphql_query` | Parsed with `json.loads`; invalid JSON raises `NodeUserError` |
+| `command` | string | `""` | yes* | `operation=custom` | Everything after `cf `, split with `shlex.split` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `CloudflareActionOutput`; `hideOutputHandle` auto-set like the input |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+Keys are omitted when empty (`_shape` never writes `None`; `exclude_unset`
+preserves that). `extra="allow"`.
+
+```ts
+{
+ operation: string;
+ success: true; // failures raise instead of returning
+ url?: string; // custom only: stdout that is one line starting with "http"
+ result?: unknown; // parsed JSON stdout (or NDJSON recovered as an array), or the GraphQL body
+ stdout?: string; // raw stdout ONLY when nothing parsed as JSON
+ stderr_tail?: string; // last 2000 chars of stderr, present even on success (cf status noise)
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Validate params] --> B{operation}
+ B -- whoami --> R[_run: ensure_cf_cli -> run_cli_command argv, env=cf_env token,email]
+ B -- zones_list --> Z[argv zones list + optional --name / --account-id] --> R
+ B -- dns_records_list --> D1[require zone] --> R
+ B -- dns_record_create --> D2[require zone + record_body, json.loads check] --> R
+ B -- dns_record_delete --> D3[require zone + record_id] --> R
+ B -- custom --> C[require command, shlex.split, timeout 300s] --> R
+ B -- graphql_query --> G[require graphql_query, parse graphql_variables]
+ G --> K{stored token or CLOUDFLARE_API_TOKEN / CLOUDFLARE_API_KEY env}
+ K -- none, or cfk_ without email --> ERR[NodeUserError: credential guidance]
+ K -- ok --> P[POST client/v4/graphql, 60s httpx]
+ P -- 401/403 --> ERR
+ P -- non-JSON, >=400, or data null with errors --> ERR
+ P -- ok --> S[_shape: result = body]
+ R -- install raised --> RT[RuntimeError cf CLI install failed]
+ R -- exit != 0 or timeout --> ERR2[NodeUserError cf argv0 failed: stderr tail]
+ R -- ok --> S2[_shape: parsed JSON -> result, else NDJSON, else stdout; stderr_tail]
+ S --> OUT[Return envelope]
+ S2 --> OUT
+```
+
+## Decision Logic
+
+- **Validation** (all `NodeUserError`): blank `zone` on any DNS op; blank
+ `record_body` or `record_body` that is not JSON; blank `record_id`; blank
+ `graphql_query`; `graphql_variables` that is not JSON; blank `command`.
+- **No auth pre-flight**: `_run` never checks whether cf is logged in. cf's
+ own "Not logged in" text arrives on stderr and is surfaced by the failure
+ wrap.
+- **Credential routing for CLI ops** (`cf_env`): a stored key starting with
+ `cfk_` plus a stored email becomes the `CLOUDFLARE_API_KEY` +
+ `CLOUDFLARE_EMAIL` pair and the ambient `CLOUDFLARE_API_TOKEN` /
+ `CF_API_TOKEN` are popped (cf ranks tokens above the key pair); any other
+ stored key becomes `CLOUDFLARE_API_TOKEN`; a `cfk_` key without an email
+ injects nothing and cf falls back to its own OAuth session. Ambient env
+ vars are otherwise left in place for ops.
+- **Credential routing for `graphql_query`** (`api_auth_headers`): key from
+ the stored `cloudflare` row, else `CLOUDFLARE_API_TOKEN`, else
+ `CLOUDFLARE_API_KEY` env; email from the stored `cloudflare_email` row,
+ else `CLOUDFLARE_EMAIL`. `cfk_` + email sends `X-Auth-Email` /
+ `X-Auth-Key`; any other key sends `Authorization: Bearer`; `cfk_` without
+ email yields no headers and the op fails before any request.
+- **GraphQL response**: HTTP 401/403 -> `NodeUserError` naming the required
+ token permission; non-JSON body -> `NodeUserError`; status >= 400 or
+ (`data` is null and `errors` present) -> `NodeUserError` with the first
+ error's `message`; otherwise the whole body (including partial `errors`)
+ is returned as `result`.
+- **Output shaping** (`_shape`): `run_cli_command` already ran a single
+ `json.loads` on stdout; when that is `None` and stdout has two or more
+ non-blank lines, every line is parsed as JSON (`_parse_ndjson`) - one
+ failure abandons the attempt and stdout ships as text. `url` is set only by
+ `custom`, and only when stdout is a single line starting with `http`.
+- **Timeouts**: 120 s for the typed CLI ops, 300 s for `custom`, 60 s for the
+ GraphQL POST. `run_cli_command` kills the process tree on timeout and
+ returns `success: False` with `error: "<binary> timed out (Ns)"`, which the
+ failure wrap turns into a `NodeUserError`.
+- **Error paths**: `ensure_cf_cli()` raising (npm missing, npm install
+ failing) -> `RuntimeError("cf CLI install failed: ...")`, which is NOT a
+ `NodeUserError` and therefore takes `BaseNode.execute`'s generic exception
+ branch (full traceback). Non-zero exit -> `NodeUserError("cf <argv0>
+ failed: <last 2000 chars of stderr>")`, falling back to the envelope
+ `error` when stderr is empty.
+
+## Side Effects
+
+- **Subprocess**: one `cf` process per operation from the project-local
+ shim `<DATA_DIR>/packages/node_modules/.bin/cf` (`cf.cmd` on Windows).
+ The system-global `cf` is never consulted. Child env is a copy of the
+ server env plus `NO_COLOR=1` and the credential vars above; no `cwd` is
+ passed (the process inherits the server's cwd - the workflow workspace is
+ not used).
+- **Install**: on first use `npm install [email protected] --prefix <DATA_DIR>/packages
+ --no-audit --no-fund` runs in a worker thread under an install lock.
+- **External API calls**: `POST https://api.cloudflare.com/client/v4/graphql`
+ with `{query, variables}` (`graphql_query` only).
+- **Credential reads**: `auth_service.get_api_key("cloudflare")` and
+ `get_api_key("cloudflare_email")` on every `_run` and every GraphQL call.
+- **Cost metadata**: every operation declares
+ `cost={"service": "cloudflare", "action": "<operation>", "count": 1}`.
+- **Broadcasts**: standard node status via `BaseNode.execute`; nothing
+ plugin-specific. (Login / logout / status broadcasts belong to the WS
+ handlers `cloudflare_login` / `cloudflare_logout` / `cloudflare_status`,
+ not to this node.)
+- **Database writes**: none by the node.
+
+## External Dependencies
+
+- **Credentials**: `CloudflareCredential` (`id = "cloudflare"`,
+ `auth = "custom"`). `resolve()` returns the optional
+ `cloudflare_api_token` (stored under the provider id `cloudflare`; an API
+ token or a `cfk_` Global API Key) and `cloudflare_email`. The cf OAuth
+ session created by `cf auth login` lives in cf's own user-level config and
+ is never read by OpenCompany; the modal badge is a synthetic `cli-managed`
+ marker OAuth row written by `_handlers.py`.
+- **Services**: the `cf` CLI (Node >= 22, `npm` on PATH for the install);
+ Cloudflare's dashboard OAuth for login (cf opens the browser itself and
+ listens on a fixed loopback port it owns - see `_handlers.py` for the
+ single-flight guard and the never-kill rule).
+- **Python packages**: `httpx`, `pydantic`; `services.events.run_cli_command`.
+- **Environment variables**: `CLOUDFLARE_API_TOKEN`, `CF_API_TOKEN`,
+ `CLOUDFLARE_API_KEY`, `CF_API_KEY`, `CLOUDFLARE_EMAIL`, `CF_EMAIL`
+ (ambient values honoured for ops, stripped for login / whoami / logout),
+ `NO_COLOR`.
+
+## Edge cases & known limits
+
+- `annotations` declare `destructive: False` although `dns_record_delete`
+ deletes records (gcloud, by contrast, declares `destructive: True`).
+- `ui_hints = {"outputMode": "terminal"}`: text output renders
+ preformatted; JSON `result` renders as a tree.
+- `stderr_tail` is populated on success too, because cf prints status noise
+ on stderr.
+- `custom` can run any cf subcommand including `auth login` / `auth logout`;
+ those run with `cf_env`, not `login_env`, so ambient credential vars are
+ NOT stripped there (only the WS login handlers strip them).
+- The GraphQL op ignores the cf OAuth session entirely: the fixed 86-scope
+ grant has no analytics scope, so only a stored / ambient token or Global
+ API Key can satisfy it.
+- `whoami` under an ambient `CLOUDFLARE_API_TOKEN` reports the env token,
+ not the OAuth session (that is why the WS status handler uses `login_env`).
+- Argv shapes are verified only against the pinned `[email protected]`; the preview
+ CLI's surface drifts between versions.
+
+## Related
+
+- **Skills using this as a tool**: [cloudflare-skill](../../../server/skills/cloudflare/cloudflare-skill/SKILL.md)
+- **Siblings**: [`gcloudAction`](./gcloudAction.md), [`vercelAction`](./vercelAction.md), [`githubAction`](./githubAction.md) - the same CLI-managed-auth pattern
+- **Architecture docs**: [Cloudflare Service](../../cloudflare_service.md), [Plugin System](../../plugin_system.md)
diff --git a/docs-internal/node-logic-flows/cli_integrations/gcloudAction.md b/docs-internal/node-logic-flows/cli_integrations/gcloudAction.md
new file mode 100644
index 00000000..5b3be241
--- /dev/null
+++ b/docs-internal/node-logic-flows/cli_integrations/gcloudAction.md
@@ -0,0 +1,194 @@
+# Google Cloud (`gcloudAction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | deployment (palette group `deployment`; class `group = ("deployment", "tool")`) |
+| **Backend handler** | [`server/nodes/gcloud/gcloud_action.py`](../../../server/nodes/gcloud/gcloud_action.py) (`GCloudActionNode`, on `ActionNode`); env + cwd helpers in [`_service.py`](../../../server/nodes/gcloud/_service.py); installer [`_install.py`](../../../server/nodes/gcloud/_install.py); login WS handlers [`_handlers.py`](../../../server/nodes/gcloud/_handlers.py) |
+| **Tests** | [`server/tests/test_gcloud_plugin.py`](../../../server/tests/test_gcloud_plugin.py) |
+| **Skill (if any)** | [`server/skills/gcloud/gcloud-skill/SKILL.md`](../../../server/skills/gcloud/gcloud-skill/SKILL.md) (`allowed-tools: "gcloud"`) |
+| **Dual-purpose tool** | yes - tool name `gcloud` |
+
+## Purpose
+
+Run Google Cloud operations through a project-local, version-pinned
+`gcloud` CLI: account / config snapshots, project selection, Compute Engine
+instance list / start / stop / describe, Cloud Run deploy / list / describe,
+Cloud Storage ls / cp / rm, and a `custom` passthrough for the rest of the
+gcloud surface. Every invocation runs under an isolated `CLOUDSDK_CONFIG`
+directory, so the node's login and project defaults never touch the
+operator's own gcloud configuration.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Declared, but `hideInputHandle` is auto-set (`usable_as_tool = True`, class does not declare `hide_input_handle`) |
+
+## Parameters
+
+`extra="ignore"` on the model. `_PROJECT_OPS` = `projects_list`,
+`compute_instances_list`, `compute_instance_start`, `compute_instance_stop`,
+`compute_instance_describe`, `run_deploy`, `run_services_list`,
+`run_service_describe`, `storage_ls`, `storage_cp`, `storage_rm`.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | 15-value literal (see flow) | `config_list` | no | - | Operation dispatch key |
+| `project` | string | `""` | no | `operation` in `_PROJECT_OPS` | `--project <id>` when set. Applied by the compute ops, the run ops and `storage_ls` only - NOT by `projects_list`, `storage_cp` or `storage_rm`, although the field is shown for them |
+| `project_id` | string | `""` | yes* | `operation=set_project` | `config set project <id>` |
+| `zone` | string | `""` | yes* for start / stop / describe | `operation` in the four `compute_*` ops | `--zone` (required) for instance ops; optional `--zones` filter for `compute_instances_list` |
+| `instance` | string | `""` | yes* | `compute_instance_start`, `compute_instance_stop`, `compute_instance_describe` | Compute Engine instance name |
+| `region` | string | `""` | yes* for deploy / describe | `run_deploy`, `run_service_describe`, `run_services_list` | `--region`; optional filter for `run_services_list` |
+| `service` | string | `""` | yes* | `run_deploy`, `run_service_describe` | Cloud Run service name |
+| `source` | string | `""` | one of source / image | `operation=run_deploy` | `--source <dir>`; mutually exclusive with `image` |
+| `image` | string | `""` | one of source / image | `operation=run_deploy` | `--image <ref>` |
+| `allow_unauthenticated` | bool | `false` | no | `operation=run_deploy` | Appends `--allow-unauthenticated` |
+| `url` | string | `""` | yes* for rm | `storage_ls`, `storage_rm` | Positional `gs://` URL; `storage_rm` enforces the `gs://` prefix |
+| `src` | string | `""` | yes* | `operation=storage_cp` | Copy source (local path or `gs://`) |
+| `dst` | string | `""` | yes* | `operation=storage_cp` | Copy destination |
+| `recursive` | bool | `false` | no | `storage_cp`, `storage_rm` | Appends `--recursive` |
+| `limit` | int (1..500) | `50` | no | `operation=projects_list` | `--limit N` |
+| `path` | string | `""` | no | `run_deploy`, `storage_cp`, `custom` | Working directory: absolute, or relative to the workflow workspace |
+| `command` | string | `""` | yes* | `operation=custom` | Everything after `gcloud `, `shlex.split` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `GCloudActionOutput`; `hideOutputHandle` auto-set |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+Keys omitted when empty; `extra="allow"`.
+
+```ts
+{
+ operation: string;
+ success: true;
+ result?: unknown; // parsed --format=json stdout
+ stdout?: string; // text stdout when nothing parsed (set_project, storage_cp, custom without --format)
+ stderr_tail?: string; // last 2000 chars of stderr (gcloud prints progress and warnings there)
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Validate params] --> B{operation}
+ B -- auth_list / config_list --> R[_run argv --format=json]
+ B -- projects_list --> PL[projects list --format=json --limit N] --> R
+ B -- set_project --> SP[require project_id; config set project id] --> R
+ B -- compute_instances_list --> CL[compute instances list --format=json, optional --zones, --project] --> R
+ B -- compute_instance_start / stop / describe --> CI[require instance + zone; compute instances verb name --zone Z --format=json --project?]
+ CI -- start / stop --> R300[_run timeout 300s]
+ CI -- describe --> R
+ B -- run_deploy --> RD[require service, region, exactly one of source / image; --quiet --format=json; cwd from path or workspace]
+ RD --> R900[_run timeout 900s]
+ B -- run_services_list / run_service_describe --> RS[run services ... --format=json --region? --project?] --> R
+ B -- storage_ls --> SL[storage ls url? --format=json --project?] --> R
+ B -- storage_cp --> SC[require src + dst; storage cp --recursive? src dst; cwd] --> R600[_run timeout 600s]
+ B -- storage_rm --> SR[require gs:// url; storage rm --recursive? url] --> R
+ B -- custom --> CU[require command; shlex.split; cwd from path or workspace] --> R600
+ R --> X
+ R300 --> X
+ R600 --> X
+ R900 --> X
+ X{ensure_gcloud_cli -> run_cli_command env=gcloud_env}
+ X -- install raised --> RT[RuntimeError Google Cloud CLI install failed]
+ X -- exit != 0 or timeout --> ERR[NodeUserError gcloud argv0 failed: stderr tail + Login hint]
+ X -- ok --> S[_shape: result or stdout, stderr_tail] --> OUT[Return envelope]
+```
+
+## Decision Logic
+
+- **Validation** (all `NodeUserError`): blank `project_id` (`set_project`);
+ blank `instance` or blank `zone` (instance ops - `instance` is checked
+ first); blank `service` or `region` (`run_deploy`,
+ `run_service_describe`); `source` and `image` both set or both empty
+ (`run_deploy`); blank `src` or `dst` (`storage_cp`); `url` not starting
+ with `gs://` (`storage_rm`); blank `command` (`custom`).
+- **Working directory** (`_cwd` -> `resolve_workdir`): with no `path`, no
+ `required` flag and no workspace the cwd is `None` (inherit). An explicit
+ relative `path` without a workspace, or a `path` that is not a directory,
+ raises `NodeUserError`. `run_deploy` passes `required=bool(source)`, so a
+ source deploy needs a workspace or a `path` while an image deploy does not.
+ `storage_cp` and `custom` fall back to the workspace when one exists.
+- **No auth pre-flight**: gcloud's own "You do not currently have an active
+ account selected" surfaces through the failure wrap, which appends
+ "(if this is an auth error, connect via Credentials -> Google Cloud ->
+ Login)".
+- **`--project` is appended only when `project` is non-blank**, and only by
+ the ops that call `_project_flag` (compute ops, run ops, `storage_ls`).
+- **Timeouts**: 120 s default; 300 s instance start / stop; 600 s
+ `storage_cp` and `custom`; 900 s `run_deploy`. Timeout kills the process
+ tree and becomes a `NodeUserError`.
+- **Error paths**: install failure -> `RuntimeError` (generic exception
+ branch, traceback); non-zero exit -> `NodeUserError` with the last 2000
+ chars of stderr (or the envelope `error`).
+- **Output shaping**: parsed JSON wins over stdout; both never ship together;
+ `stderr_tail` present whenever stderr is non-empty.
+
+## Side Effects
+
+- **Subprocess**: one gcloud process per op from
+ `<DATA_DIR>/packages/gcloud/<asset>.unzip|.untar/google-cloud-sdk/bin/gcloud`
+ (`gcloud.cmd` on Windows). Env = server env plus
+ `CLOUDSDK_CONFIG=<DATA_DIR>/gcloud/`, `CLOUDSDK_CORE_DISABLE_PROMPTS=1`,
+ `CLOUDSDK_COMPONENT_MANAGER_DISABLE_UPDATE_CHECK=1`,
+ `CLOUDSDK_CORE_DISABLE_USAGE_REPORTING=1`, `NO_COLOR=1`. Ambient
+ `GOOGLE_APPLICATION_CREDENTIALS` / `CLOUDSDK_AUTH_ACCESS_TOKEN` /
+ `CLOUDSDK_CORE_ACCOUNT` / `CLOUDSDK_CORE_PROJECT` / `GOOGLE_CLOUD_PROJECT`
+ are NOT stripped for ops (only `login_env`, used by the WS handlers,
+ strips them).
+- **Install**: first use downloads the pinned `577.0.0` archive from
+ `dl.google.com` via `pooch.retrieve` (no hash; 300 s per-read timeout) in a
+ worker thread under a lock, extracts ~15k files under
+ `package_dir("gcloud")`, and `chmod +x`es `bin/` on POSIX. Windows ARM64
+ maps to the x86_64 bundled-python zip; darwin and linux-arm archives need a
+ system `python3` (`CLOUDSDK_PYTHON` override).
+- **File I/O**: `set_project` and any `custom` config command write into the
+ pinned config dir; `storage_cp` writes local files relative to the cwd;
+ `run_deploy --source` uploads the cwd.
+- **Cost metadata**: every op declares
+ `cost={"service": "gcloud", "action": "<operation>", "count": 1}`.
+- **Broadcasts / DB writes**: none beyond the standard node status.
+
+## External Dependencies
+
+- **Credentials**: `GCloudCredential` (`id = "gcloud"`, `auth = "custom"`,
+ `resolve()` returns `{}`) - a marker only; the node never reads it. The
+ live session is gcloud's own credential store under the pinned config dir,
+ minted by the `gcloud_login` WS handler (`gcloud auth login`, browser
+ opened by the CLI on a random loopback port). Provider id `gcloud` is
+ distinct from the Workspace `google` OAuth2 provider.
+- **Services**: Google Cloud APIs reached by gcloud; `dl.google.com` for the
+ install.
+- **Python packages**: `pooch`, `pydantic`; `services.events.run_cli_command`.
+- **Environment variables**: `CLOUDSDK_CONFIG` (always overridden),
+ `CLOUDSDK_PYTHON` (non-bundled platforms), the automation vars listed above.
+
+## Edge cases & known limits
+
+- `annotations = {"destructive": True, ...}`: start / stop / deploy / rm
+ mutate cloud state.
+- A terminal `gcloud auth login` against the operator's global config is
+ invisible to this node by design (config isolation).
+- `custom` injects no `--format`, so table output lands in `stdout`; the
+ 600 s budget applies even to quick commands.
+- `run_deploy` does not pass `path`-relative `source` through `resolve_workdir`;
+ `--source <value>` is passed verbatim and gcloud resolves it against the
+ cwd.
+- Every op pays a fresh interpreter start (seconds on Windows), which the
+ `tool_description` warns agents about.
+- Cold install is roughly 60-110 MB download and far longer than the WS
+ request budget; on the node path there is no `pending` fallback - the
+ activity simply blocks until the install completes or fails.
+- `ui_hints = {"outputMode": "terminal"}`.
+
+## Related
+
+- **Skills using this as a tool**: [gcloud-skill](../../../server/skills/gcloud/gcloud-skill/SKILL.md)
+- **Siblings**: [`cloudflareAction`](./cloudflareAction.md), [`githubAction`](./githubAction.md), [`vercelAction`](./vercelAction.md)
+- **Architecture docs**: [Google Cloud Service](../../gcloud_service.md)
diff --git a/docs-internal/node-logic-flows/cli_integrations/githubAction.md b/docs-internal/node-logic-flows/cli_integrations/githubAction.md
new file mode 100644
index 00000000..e0614caa
--- /dev/null
+++ b/docs-internal/node-logic-flows/cli_integrations/githubAction.md
@@ -0,0 +1,171 @@
+# GitHub (`githubAction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | vcs (palette group `vcs`; class `group = ("vcs", "tool")`) |
+| **Backend handler** | [`server/nodes/github/github_action.py`](../../../server/nodes/github/github_action.py) (`GitHubActionNode`, on `ActionNode`); env + cwd helpers in [`_service.py`](../../../server/nodes/github/_service.py); installer [`_install.py`](../../../server/nodes/github/_install.py); login WS handlers [`_handlers.py`](../../../server/nodes/github/_handlers.py) |
+| **Tests** | [`server/tests/test_github_plugin.py`](../../../server/tests/test_github_plugin.py) |
+| **Skill (if any)** | [`server/skills/github/github-skill/SKILL.md`](../../../server/skills/github/github-skill/SKILL.md) (`allowed-tools: "github"`) |
+| **Dual-purpose tool** | yes - tool name `github` |
+
+## Purpose
+
+Clone repositories, open / list / merge pull requests, create / list issues,
+and run any other `gh` command, through a project-local pinned GitHub CLI.
+List operations request `--json` so results land as parsed data; `gh`
+authenticates from its own credential store (populated by `gh auth login`,
+from the modal or a terminal) - the node performs no pre-flight and injects
+no token.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Declared, but `hideInputHandle` is auto-set (`usable_as_tool = True`, class does not declare `hide_input_handle`) |
+
+## Parameters
+
+`extra="ignore"` on the model.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | `repo_clone \| pr_create \| pr_list \| pr_merge \| issue_create \| issue_list \| custom` | `pr_list` | no | - | Operation dispatch key |
+| `repo` | string | `""` | no | `pr_create`, `pr_list`, `pr_merge`, `issue_create`, `issue_list` | `--repo OWNER/REPO` when non-blank; otherwise gh infers from the cwd's git remote |
+| `path` | string | `""` | no | `repo_clone`, `pr_create`, `pr_merge`, `custom` | Working directory: absolute or relative to the workflow workspace |
+| `clone_repo` | string | `""` | yes* | `operation=repo_clone` | `OWNER/REPO` or full URL |
+| `clone_dir` | string | `""` | no | `operation=repo_clone` | Optional target directory positional |
+| `title` | string | `""` | yes* (unless `fill`) | `pr_create`, `issue_create` | `--title` |
+| `body` | string | `""` | no | `pr_create`, `issue_create` | `--body`; passed even when empty |
+| `base` | string | `""` | no | `operation=pr_create` | `--base` |
+| `head` | string | `""` | no | `operation=pr_create` | `--head` |
+| `draft` | bool | `false` | no | `operation=pr_create` | `--draft` |
+| `fill` | bool | `false` | no | `operation=pr_create` | `--fill` instead of `--title` / `--body` |
+| `state` | `open \| closed \| merged \| all` | `open` | no | `pr_list`, `issue_list` | `--state`; `merged` is coerced to `all` for issues |
+| `limit` | int (1..100) | `30` | no | `pr_list`, `issue_list` | `--limit` |
+| `pr` | string | `""` | yes* | `operation=pr_merge` | PR number, URL or branch positional |
+| `merge_method` | `squash \| merge \| rebase` | `squash` | no | `operation=pr_merge` | Emitted as `--squash` / `--merge` / `--rebase` |
+| `delete_branch` | bool | `false` | no | `operation=pr_merge` | `--delete-branch` |
+| `labels` | string | `""` | no | `operation=issue_create` | Comma-separated; each becomes a `--label` |
+| `command` | string | `""` | yes* | `operation=custom` | Everything after `gh `, `shlex.split` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `GitHubActionOutput`; `hideOutputHandle` auto-set |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+Keys omitted when empty; `extra="allow"`.
+
+```ts
+{
+ operation: string;
+ success: true;
+ url?: string; // pr_create / issue_create: stdout starting with "http"; custom: single-line stdout starting with "http"
+ result?: unknown; // parsed JSON stdout (pr_list / issue_list --json, gh api via custom)
+ stdout?: string; // text stdout when nothing parsed
+ stderr_tail?: string; // last 2000 chars of stderr
+}
+```
+
+`pr_list` JSON fields: `number,title,state,url,author,headRefName,baseRefName,createdAt`.
+`issue_list` JSON fields: `number,title,state,url,author,labels,createdAt`.
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Validate params] --> B{operation}
+ B -- repo_clone --> RC[require clone_repo; cwd REQUIRED path or workspace; repo clone repo dir?] --> R600[_run timeout 600s]
+ B -- pr_create --> PC{fill}
+ PC -- yes --> PF[pr create --repo? --fill]
+ PC -- no --> PT[require title; --title T --body B]
+ PF --> PO[--base? --head? --draft?; cwd path or workspace] --> R
+ PT --> PO
+ B -- pr_list --> PL[pr list --repo? --state S --limit N --json fields; cwd workspace if any] --> R
+ B -- pr_merge --> PM[require pr; pr merge pr --repo? --method --delete-branch?; cwd] --> R
+ B -- issue_create --> IC[require title; issue create --repo? --title --body --label...; cwd workspace if any] --> R
+ B -- issue_list --> IL[issue list --state S or all --limit N --json fields] --> R
+ B -- custom --> CU[require command; shlex.split; cwd path or workspace] --> R600
+ R --> X
+ R600 --> X
+ X{ensure_gh_cli -> run_cli_command env=gh_env}
+ X -- install raised --> RT[RuntimeError gh CLI install failed]
+ X -- exit != 0 or timeout --> ERR[NodeUserError gh argv0 failed: stderr tail]
+ X -- ok --> S[_shape: url? result or stdout, stderr_tail] --> OUT[Return envelope]
+```
+
+## Decision Logic
+
+- **Validation** (`NodeUserError`): blank `clone_repo`; blank `title` when
+ `fill` is false (`pr_create`) or always (`issue_create`); blank `pr`; blank
+ `command`.
+- **Working directory** (`_cwd` -> `resolve_repo_path`): `repo_clone` passes
+ `required=True`, so without a `path` and without a workspace it raises
+ `NodeUserError`. `pr_create`, `pr_merge`, `custom` use `path` or the
+ workspace (or `None` when neither exists). `pr_list`, `issue_create`,
+ `issue_list` always call `_cwd(ctx, "")`: the workspace when present, else
+ `None`. A relative `path` without a workspace, or a non-directory, raises
+ `NodeUserError`.
+- **`--repo`** is appended only when `repo` is non-blank.
+- **`--body`** is always passed on the non-fill `pr_create` path and on
+ `issue_create`, even when `body` is empty.
+- **No auth pre-flight**: gh's own "To get started with GitHub CLI, please
+ run: gh auth login" surfaces via the failure wrap.
+- **Timeouts**: 120 s default; 600 s for `repo_clone` and `custom`.
+- **Error paths**: install failure -> `RuntimeError` (generic branch,
+ traceback); non-zero exit / timeout -> `NodeUserError` with the last 2000
+ chars of stderr.
+- **`url` extraction**: `pr_create` / `issue_create` accept multi-line stdout
+ as long as it starts with `http`; `custom` requires a single line.
+
+## Side Effects
+
+- **Subprocess**: one `gh` process per op from
+ `<DATA_DIR>/packages/gh/<asset>.unzip|.untar/gh_<V>_<os>_<arch>/bin/gh`
+ (`gh.exe` on Windows). Env = server env plus `GH_PROMPT_DISABLED=1`,
+ `NO_COLOR=1`, `GH_NO_UPDATE_NOTIFIER=1`, `GH_PAGER=cat`. Ambient
+ `GH_TOKEN` / `GITHUB_TOKEN` are honoured for ops (gh's own precedence) and
+ stripped only by `login_env` in the WS handlers.
+- **Install**: first use downloads the pinned `gh` `2.96.0` release archive
+ from GitHub releases via `pooch.retrieve` (no hash) in a worker thread
+ under a lock and `chmod +x`es the binary on POSIX. The system `gh` is never
+ consulted; gh's config / credential store is user-level, so a terminal
+ login is visible to the pinned binary.
+- **File I/O**: `repo_clone` writes a checkout into the cwd; `custom` may
+ write depending on the command.
+- **Cost metadata**: every op declares
+ `cost={"service": "github", "action": "<operation>", "count": 1}`.
+- **Broadcasts / DB writes**: none beyond the standard node status.
+
+## External Dependencies
+
+- **Credentials**: `GitHubCredential` (`id = "github"`, `auth = "custom"`,
+ `resolve()` returns `{}`) - a marker only. The session is gh's own
+ credential store; the modal badge is the synthetic `cli-managed` marker
+ OAuth row written by `github_login` after `gh auth status` succeeds, which
+ also runs `gh auth setup-git` best-effort.
+- **Services**: GitHub API via gh; GitHub releases for the install.
+- **Python packages**: `pooch`, `pydantic`; `services.events.run_cli_command`.
+- **Environment variables**: `GH_TOKEN`, `GITHUB_TOKEN` (ambient, honoured
+ for ops), the four automation vars above.
+
+## Edge cases & known limits
+
+- `annotations = {"destructive": False, ...}` although `pr_merge` and
+ `custom` can mutate repositories.
+- `issue_list` silently maps `state=merged` to `all` (gh rejects `merged`
+ for issues).
+- `ui_hints = {"outputMode": "terminal"}`.
+- `custom` runs any gh subcommand including `auth logout`; it uses `gh_env`,
+ so ambient tokens remain in place.
+- `repo_clone` into a workspace that already holds the directory fails with
+ gh's own error, surfaced as `NodeUserError`.
+
+## Related
+
+- **Skills using this as a tool**: [github-skill](../../../server/skills/github/github-skill/SKILL.md)
+- **Siblings**: [`cloudflareAction`](./cloudflareAction.md), [`gcloudAction`](./gcloudAction.md), [`vercelAction`](./vercelAction.md)
+- **Architecture docs**: [GitHub Service](../../github_service.md)
diff --git a/docs-internal/node-logic-flows/cli_integrations/vercelAction.md b/docs-internal/node-logic-flows/cli_integrations/vercelAction.md
new file mode 100644
index 00000000..a9713d11
--- /dev/null
+++ b/docs-internal/node-logic-flows/cli_integrations/vercelAction.md
@@ -0,0 +1,166 @@
+# Vercel (`vercelAction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | deployment (palette group `deployment`; class `group = ("deployment", "tool")`) |
+| **Backend handler** | [`server/nodes/vercel/vercel_action.py`](../../../server/nodes/vercel/vercel_action.py) (`VercelActionNode`, on `ActionNode`); config pinning + token helpers in [`_service.py`](../../../server/nodes/vercel/_service.py); installer [`_install.py`](../../../server/nodes/vercel/_install.py); login WS handlers [`_handlers.py`](../../../server/nodes/vercel/_handlers.py) |
+| **Tests** | [`server/tests/test_vercel_plugin.py`](../../../server/tests/test_vercel_plugin.py) |
+| **Skill (if any)** | [`server/skills/vercel/vercel-skill/SKILL.md`](../../../server/skills/vercel/vercel-skill/SKILL.md) (`allowed-tools: "vercel"`) |
+| **Dual-purpose tool** | yes - tool name `vercel` |
+
+## Purpose
+
+Deploy a directory to Vercel, inspect a deployment, list a project's
+deployments, or run any other Vercel CLI command. Unlike the other CLI
+nodes this one DOES pre-flight auth: each operation first requires either a
+stored access token (injected as `VERCEL_TOKEN`) or a CLI login in the
+OpenCompany-pinned `--global-config` directory, and raises an annotated
+`PermissionError` otherwise so the framework emits the credential envelope.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Declared, but `hideInputHandle` is auto-set (`usable_as_tool = True`, class does not declare `hide_input_handle`) |
+
+## Parameters
+
+`extra="ignore"` on the model.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | `deploy \| inspect \| list \| custom` | `deploy` | no | - | Operation dispatch key |
+| `path` | string | `""` | no | `operation=deploy` | Directory to deploy: absolute, or relative to the workflow workspace; defaults to the workspace |
+| `prod` | bool | `false` | no | `deploy`, `list` | `--prod` |
+| `prebuilt` | bool | `false` | no | `operation=deploy` | `--prebuilt` |
+| `archive` | bool | `false` | no | `operation=deploy` | `--archive=tgz` |
+| `scope` | string | `""` | no | `operation=deploy` | `--scope <team>` |
+| `extra_args` | string | `""` | no | `operation=deploy` | `shlex.split` and appended verbatim |
+| `project` | string | `""` | yes* on first deploy | `deploy`, `list` | `--project <name>` for deploy; positional project for list |
+| `deployment` | string | `""` | yes* | `operation=inspect` | Deployment URL or id positional |
+| `logs` | bool | `false` | no | `operation=inspect` | `--logs` |
+| `wait` | bool | `false` | no | `operation=inspect` | `--wait` |
+| `timeout` | string | `"3m"` | no | `operation=inspect` | `--timeout <dur>`, only emitted when `wait` is true |
+| `status` | string | `""` | no | `operation=list` | `--status <csv>` |
+| `command` | string | `""` | yes* | `operation=custom` | Everything after `vercel `, `shlex.split` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `VercelActionOutput`; `hideOutputHandle` auto-set |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+Keys omitted when empty; `extra="allow"`.
+
+```ts
+{
+ operation: string;
+ success: true;
+ url?: string; // deploy: stdout starting with "http" (the CLI prints only the deployment URL); custom: single-line stdout starting with "http"
+ result?: unknown; // parsed JSON stdout (custom commands with --json / --format=json)
+ stdout?: string; // human-readable text (list / inspect have no --json upstream)
+ stderr_tail?: string; // last 2000 chars of stderr (deploy progress lives here)
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Validate params] --> P[_preflight: stored vercel_token OR auth.json in pinned config dir]
+ P -- neither --> PE[PermissionError provider=vercel reason=missing auth=oauth2]
+ P -- ok --> B{operation}
+ B -- deploy --> D1[_resolve_deploy_cwd: path or workspace]
+ D1 --> D2[_require_project_target: project param, .vercel/project.json, VERCEL_PROJECT_ID env, or --project in extra_args]
+ D2 -- none --> ERR[NodeUserError first-deploy needs project]
+ D2 -- ok --> D3[deploy --yes --prod? --prebuilt? --archive=tgz? --project? --scope? extra_args; cwd; 600s] --> R
+ B -- inspect --> I1[require deployment; inspect dep --logs? --wait --timeout T?; 300s if wait else 60s] --> R
+ B -- list --> L1[list project? --prod? --status? --yes; 60s] --> R
+ B -- custom --> C1[require command; shlex.split; cwd = workspace or None; 600s] --> R
+ R{ensure_vercel_cli -> run_cli_command argv + --global-config dir --no-color, env NO_COLOR + VERCEL_TOKEN?}
+ R -- install raised --> RT[RuntimeError Vercel CLI install failed]
+ R -- exit != 0 or timeout --> ERR2[NodeUserError vercel argv0 failed: stderr tail]
+ R -- ok --> S[_shape: url? result or stdout, stderr_tail] --> OUT[Return envelope]
+```
+
+## Decision Logic
+
+- **Pre-flight** (`_preflight`): `stored_token()` reads the `vercel_token`
+ api-key row; `is_logged_in()` checks that `<DATA_DIR>/vercel/auth.json`
+ exists and contains the substring `token`. Neither -> `PermissionError`
+ annotated `provider="vercel"`, `reason="missing"`, `auth="oauth2"`, which
+ `BaseNode.execute` turns into `error_type="PermissionDeniedError"` plus the
+ `credential` envelope block and a `credential.oauth.runtime_failed`
+ broadcast. When both exist the token wins (it rides `VERCEL_TOKEN`; the CLI
+ gives env tokens precedence).
+- **Validation** (`NodeUserError`): deploy cwd resolution (relative `path`
+ without workspace, non-directory, or no path and no workspace); the
+ first-deploy project guard; blank `deployment`; blank `command`.
+- **First-deploy guard** (`_require_project_target`): satisfied by a
+ non-blank `project`, an existing `<cwd>/.vercel/project.json`, a
+ `VERCEL_PROJECT_ID` env var, or a literal `--project` token in
+ `extra_args`. Otherwise it fails before uploading, because Vercel would
+ derive a name from the workspace dir (`AI_Assistant_1`) and reject it late.
+- **Working directory**: `deploy` uses `_resolve_deploy_cwd`; `custom` uses
+ `ctx.workspace_dir` (may be `None`); `inspect` and `list` pass no cwd.
+- **Timeouts**: 600 s deploy and custom; 300 s inspect with `wait`, else
+ 60 s; 60 s list.
+- **Error paths**: install failure -> `RuntimeError` (generic branch);
+ non-zero exit / timeout -> `NodeUserError` with the last 2000 chars of
+ stderr.
+
+## Side Effects
+
+- **Subprocess**: one `vercel` process per op. Binary resolution order:
+ in-process cache, `shutil.which("vercel")` (a system install is PREFERRED,
+ unlike cf / gh / gcloud), the shared-tree shim
+ `<DATA_DIR>/packages/node_modules/.bin/vercel(.cmd)`, then
+ `npm install [email protected] --prefix <DATA_DIR>/packages` in a worker
+ thread under a lock followed by a best-effort `vercel telemetry disable`.
+ Every invocation appends `--global-config <DATA_DIR>/vercel/ --no-color`;
+ env = server env plus `NO_COLOR=1` and `VERCEL_TOKEN` when a token is
+ stored.
+- **File I/O**: `<DATA_DIR>/vercel/` is created on first use; `deploy`
+ writes `.vercel/` into the deploy directory (CLI behaviour); `custom`
+ directory-scoped commands run in the workspace.
+- **Credential reads**: `auth_service.get_api_key("vercel_token")` per op.
+- **Cost metadata**: every op declares
+ `cost={"service": "vercel", "action": "<operation>", "count": 1}`.
+- **Broadcasts**: standard node status; `credential.oauth.runtime_failed`
+ via the annotated `PermissionError` path.
+
+## External Dependencies
+
+- **Credentials**: `VercelCredential` (`id = "vercel"`, `auth = "custom"`);
+ `resolve()` returns `{"vercel_token": ...}` when the optional api-key row
+ exists, else `{}`. The CLI login state (`auth.json`) lives in the pinned
+ config dir and is written by the `vercel_login` WS handler's device flow;
+ the modal badge is the synthetic `cli-managed` marker OAuth row.
+- **Services**: Vercel API via the CLI; npm registry for the install.
+- **Python packages**: `pydantic`; `services.events.run_cli_command`.
+- **Environment variables**: `VERCEL_TOKEN` (injected), `VERCEL_PROJECT_ID`
+ (read by the guard), `NO_COLOR`.
+
+## Edge cases & known limits
+
+- `list` and `inspect` output is human-readable text (no `--json` upstream);
+ agents work with `stdout` directly.
+- `prod` is shared by `deploy` and `list` (it filters production
+ deployments on `list`).
+- `timeout` is a Vercel duration string (`3m`), not seconds, and only
+ reaches argv when `wait` is set.
+- `extra_args` are appended after the typed flags, so a duplicate flag there
+ is resolved by the CLI, not by the node.
+- `ui_hints = {"outputMode": "terminal"}`; `annotations.destructive` is
+ `False` although `deploy --prod` and `custom rollback` mutate state.
+- Because a system `vercel` is preferred, argv shapes may meet a version
+ other than the pinned one.
+
+## Related
+
+- **Skills using this as a tool**: [vercel-skill](../../../server/skills/vercel/vercel-skill/SKILL.md)
+- **Siblings**: [`cloudflareAction`](./cloudflareAction.md), [`gcloudAction`](./gcloudAction.md), [`githubAction`](./githubAction.md)
+- **Architecture docs**: [Vercel Service](../../vercel_service.md), [Stripe Service](../../stripe_service.md) (the origin of the CLI-managed-auth pattern)
diff --git a/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md b/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md
index cae426dc..dc3f1369 100644
--- a/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md
+++ b/docs-internal/node-logic-flows/code_fs_process/javascriptExecutor.md
@@ -4,7 +4,7 @@
|------|-------|
| **Category** | code_fs_process / code |
| **Backend handler** | [`server/nodes/code/javascript_executor/__init__.py::JavaScriptExecutorNode.execute_op`](../../../server/nodes/code/javascript_executor/__init__.py) (dispatched via `BaseNode.execute()` + `@Operation("execute")`; base in [`_base.py`](../../../server/nodes/code/_base.py)) |
-| **Node.js client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; `services/nodejs_client.py` no longer exists) |
+| **Node.js client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; the old `nodejs_client.py` service module no longer exists) |
| **Tests** | [`server/tests/nodes/test_code_fs_process.py`](../../../server/tests/nodes/test_code_fs_process.py) |
| **Skill (if any)** | [`server/skills/coding_agent/javascript-skill/SKILL.md`](../../../server/skills/coding_agent/javascript-skill/SKILL.md) |
| **Dual-purpose tool** | yes - tool name `javascript_code` |
diff --git a/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md b/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md
index e86cf947..283bf43c 100644
--- a/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md
+++ b/docs-internal/node-logic-flows/code_fs_process/typescriptExecutor.md
@@ -4,7 +4,7 @@
|------|-------|
| **Category** | code_fs_process / code |
| **Backend handler** | [`server/nodes/code/typescript_executor/__init__.py::TypeScriptExecutorNode.execute_op`](../../../server/nodes/code/typescript_executor/__init__.py) (dispatched via `BaseNode.execute()` + `@Operation("execute")`; base in [`_base.py`](../../../server/nodes/code/_base.py)) |
-| **Node.js client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; `services/nodejs_client.py` no longer exists) |
+| **Node.js client** | [`server/nodes/code/_nodejs.py::get_nodejs_client`](../../../server/nodes/code/_nodejs.py) (singleton over [`server/nodes/code/_client.py::NodeJSClient`](../../../server/nodes/code/_client.py) — plugin-owned since July 2026; the old `nodejs_client.py` service module no longer exists) |
| **Tests** | [`server/tests/nodes/test_code_fs_process.py`](../../../server/tests/nodes/test_code_fs_process.py) |
| **Skill (if any)** | - (shared with `javascript-skill`) |
| **Dual-purpose tool** | yes - tool name `typescript_code` |
diff --git a/docs-internal/node-logic-flows/microsoft/msCalendar.md b/docs-internal/node-logic-flows/microsoft/msCalendar.md
new file mode 100644
index 00000000..56ce213f
--- /dev/null
+++ b/docs-internal/node-logic-flows/microsoft/msCalendar.md
@@ -0,0 +1,162 @@
+# Outlook Calendar (`msCalendar`)
+
+| Field | Value |
+|------|-------|
+| **Category** | microsoft (class `group = ("microsoft", "tool")`) |
+| **Backend handler** | [`server/nodes/microsoft/calendar/__init__.py`](../../../server/nodes/microsoft/calendar/__init__.py) (`CalendarNode`, on `ActionNode`); Graph plumbing in [`_base.py`](../../../server/nodes/microsoft/_base.py) (`graph_request`, `mailbox_base`, `track_microsoft_usage`); token refresh in [`_auth_helper.py`](../../../server/nodes/microsoft/_auth_helper.py) |
+| **Tests** | [`server/tests/nodes/test_microsoft.py`](../../../server/tests/nodes/test_microsoft.py) |
+| **Skill (if any)** | [`server/skills/productivity_agent/ms-calendar-skill/SKILL.md`](../../../server/skills/productivity_agent/ms-calendar-skill/SKILL.md) (`allowed-tools: "ms_calendar"`) |
+| **Dual-purpose tool** | yes - tool name `ms_calendar` |
+
+## Purpose
+
+Create, list, update and delete Outlook Calendar events through Microsoft
+Graph v1.0, for the signed-in user's calendar or a shared mailbox's
+calendar. `list` reads `calendarView` over a date window that accepts
+`today` / `today+Nd` shortcuts. Same auth and bookkeeping plumbing as
+[`msMail`](./msMail.md): proactive token refresh, `Connection` facade, one
+zero-cost usage row per operation.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Declared, but `hideInputHandle` is auto-set (`usable_as_tool = True`, class does not declare `hide_input_handle`) |
+
+## Parameters
+
+`extra="ignore"` on the model.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | `create \| list \| update \| delete` | `list` | no | - | Operation dispatch key |
+| `mailbox` | string | `""` | no | - (always shown) | Shared mailbox address; empty targets `/me`, else `/users/{address}` |
+| `event_id` | string | `""` | yes* | `update`, `delete` | Graph event id |
+| `title` | string | `""` | yes* | `operation=create` | Event `subject` |
+| `body` | string | `""` | no | `operation=create` | Text body |
+| `start_time` | string | `""` | yes* | `operation=create` | ISO 8601 local datetime |
+| `end_time` | string | `""` | yes* | `operation=create` | ISO 8601 local datetime |
+| `location` | string | `""` | no | `operation=create` | `location.displayName` |
+| `attendees` | string | `""` | no | `operation=create` | Comma- or semicolon-separated; all typed `required` |
+| `timezone` | string | `UTC` | no | `operation=create` | `timeZone` for start / end. Also applied by `update` (see Decision Logic) |
+| `start_date` | string | `""` | no | `operation=list` | ISO datetime, `today`, or `today+Nd`; empty = today 00:00 UTC |
+| `end_date` | string | `""` | no | `operation=list` | ISO datetime, `today`, or `today+Nd`; empty = now + 7 days |
+| `max_results` | int (1..250) | `10` | no | `operation=list` | `$top` |
+| `update_title` | string | `""` | no | `operation=update` | `subject` patch |
+| `update_start_time` | string | `""` | no | `operation=update` | `start.dateTime` patch |
+| `update_end_time` | string | `""` | no | `operation=update` | `end.dateTime` patch |
+| `update_body` | string | `""` | no | `operation=update` | Text body patch |
+| `update_location` | string | `""` | no | `operation=update` | `location.displayName` patch |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `CalendarOutput`; `hideOutputHandle` auto-set |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+The op returns a `CalendarOutput` instance; unset fields are omitted.
+
+```ts
+// create and update
+{ operation: "create" | "update"; event_id: string; title: string; start: string; end: string;
+ location: string; web_link: string }
+// list
+{ operation: "list"; count: number; time_range: { start: string; end: string };
+ events: Array<{ event_id, title, start, end, location, organizer, web_link, is_all_day }> }
+// delete
+{ operation: "delete"; deleted: true; event_id: string }
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Operation dispatch] --> B{params.operation}
+ B -- create --> C1[require title, start_time, end_time] --> C2[POST base/events subject, start/end with timezone, body?, location?, attendees?] --> U[track_microsoft_usage]
+ B -- list --> L1[_iso_or_shortcut start_date; end_date with 7 day default] --> L2[GET base/calendarView startDateTime endDateTime $top $orderby start/dateTime $select] --> U
+ B -- update --> P1[require event_id] --> P2[build patch from non-empty update_* fields]
+ P2 -- empty --> ERR[NodeUserError No update fields provided]
+ P2 -- ok --> P3[PATCH base/events/id] --> U
+ B -- delete --> D1[require event_id] --> D2[DELETE base/events/id -> 204] --> U
+ U --> OUT[Return CalendarOutput]
+ G[every graph_request: ensure_fresh_microsoft_token -> Connection microsoft -> status >= 400 raises NodeUserError]
+```
+
+## Decision Logic
+
+- **Validation** (`NodeUserError`): `create` needs `title`, `start_time`
+ and `end_time`; `update` and `delete` need `event_id`; `update` with no
+ non-empty `update_*` field; unknown operation; invalid `mailbox`.
+- **Date shortcuts** (`_iso_or_shortcut`, `datetime.utcnow()` based, naive
+ ISO output): empty or `today` with `default_offset_days == 0`
+ (`start_date`) -> today at 00:00:00; empty or `today` with the 7-day
+ default (`end_date`) -> now plus 7 days (NOT midnight); `today+Nd` ->
+ now plus N days; anything else passes through verbatim. A malformed
+ `today+...` value raises `ValueError` from `int()`, which is not a
+ `NodeUserError`.
+- **`list`**: `$top = min(max_results, 250)`, `$orderby=start/dateTime`,
+ `$select=id,subject,start,end,location,organizer,webLink,isAllDay`;
+ usage count = number returned; `time_range` echoes the resolved window.
+- **`create`**: `body` is always `contentType: Text`; `attendees` entries
+ are `{"emailAddress": {"address"}, "type": "required"}`.
+- **`update`**: only supplied fields are patched. `update_start_time` /
+ `update_end_time` reuse the `timezone` param, whose `displayOptions` show
+ it only for `create` - through the panel an update therefore always uses
+ the default `UTC` unless the field was set while the operation was
+ `create`; tool calls can pass it explicitly. `event_id` in the output
+ falls back to the param when Graph's response lacks `id`.
+- **`delete`**: Graph returns 204 -> `graph_request` yields `None`; output
+ is `{deleted: true, event_id}`.
+- **Auth**: identical to `msMail` - `ensure_fresh_microsoft_token` raises an
+ annotated `PermissionError` (`provider="microsoft"`, `reason="missing"`,
+ `auth="oauth2"`) when not connected; the first call per process refreshes;
+ refresh failures fall back to the stored token.
+- **Error paths**: Graph status >= 400 -> `NodeUserError("Microsoft Graph
+ error (<status>): <code>: <message>")`.
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per op
+ (`service="microsoft_graph"`; `create` -> `event_create`, `list` ->
+ `event_list`, `update` -> `event_update`, `delete` -> `event_delete`;
+ cost 0.0). Token refresh persists tokens via
+ `auth_service.store_oauth_tokens`.
+- **External API calls**: `POST {base}/events`, `GET {base}/calendarView`,
+ `PATCH {base}/events/{id}`, `DELETE {base}/events/{id}` on
+ `https://graph.microsoft.com/v1.0` with `Authorization: Bearer`.
+- **Broadcasts**: standard node status only.
+- **File I/O**: none.
+
+## External Dependencies
+
+- **Credentials**: `MicrosoftCredential` (`id = "microsoft"`, OAuth2,
+ authority `/organizations`; `Calendars.ReadWrite` and
+ `Calendars.ReadWrite.Shared` among the scopes in
+ `server/config/microsoft_apis.json`; `microsoft_client_id` /
+ `microsoft_client_secret` api-key rows).
+- **Services**: Microsoft Graph v1.0; `login.microsoftonline.com` for
+ refresh.
+- **Python packages**: `httpx`, `pydantic`; `services.plugin.connection`.
+- **Environment variables**: none read directly.
+
+## Edge cases & known limits
+
+- `start_time` / `end_time` are sent verbatim; an unparseable value is
+ rejected by Graph (surfaced as `NodeUserError`), not by the node.
+- `list` uses `calendarView`, so recurring-event instances are expanded;
+ `is_all_day` rides along per instance.
+- `create` sends attendees invitations as Graph normally does for a POST
+ to `/events` (no `sendNotifications` control is exposed).
+- `annotations = {"destructive": False, ...}` although `delete` removes
+ events.
+- Shared calendars require Full Access on the mailbox plus the `.Shared`
+ scope; the node cannot detect the missing grant ahead of Graph's 403.
+
+## Related
+
+- **Skills using this as a tool**: [ms-calendar-skill](../../../server/skills/productivity_agent/ms-calendar-skill/SKILL.md)
+- **Siblings**: [`msMail`](./msMail.md), [`msMailReceive`](./msMailReceive.md)
+- **Architecture docs**: [Plugin System](../../plugin_system.md), [Pricing Service](../../pricing_service.md)
diff --git a/docs-internal/node-logic-flows/microsoft/msMail.md b/docs-internal/node-logic-flows/microsoft/msMail.md
new file mode 100644
index 00000000..9a4e987d
--- /dev/null
+++ b/docs-internal/node-logic-flows/microsoft/msMail.md
@@ -0,0 +1,200 @@
+# Outlook Mail (`msMail`)
+
+| Field | Value |
+|------|-------|
+| **Category** | microsoft (class `group = ("microsoft", "tool")`) |
+| **Backend handler** | [`server/nodes/microsoft/mail/__init__.py`](../../../server/nodes/microsoft/mail/__init__.py) (`MailNode`, on `ActionNode`); Graph plumbing in [`_base.py`](../../../server/nodes/microsoft/_base.py) (`graph_request`, `mailbox_base`, `write_attachment_bytes`, `track_microsoft_usage`); token refresh in [`_auth_helper.py`](../../../server/nodes/microsoft/_auth_helper.py) |
+| **Tests** | [`server/tests/nodes/test_microsoft.py`](../../../server/tests/nodes/test_microsoft.py) |
+| **Skill (if any)** | [`server/skills/productivity_agent/ms-mail-skill/SKILL.md`](../../../server/skills/productivity_agent/ms-mail-skill/SKILL.md) (`allowed-tools: "ms_mail"`) |
+| **Dual-purpose tool** | yes - tool name `ms_mail` |
+
+## Purpose
+
+Send, read, search and reply to Outlook mail through Microsoft Graph v1.0,
+and list or download a message's file attachments into the workflow
+workspace so a document parser can read them. Graph is plain bearer REST:
+the node uses the `Connection` facade (token injected as `Authorization:
+Bearer`, one retry on 401 / 403) after proactively refreshing the stored
+access token, and each operation records a zero-cost usage row.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Declared, but `hideInputHandle` is auto-set (`usable_as_tool = True`, class does not declare `hide_input_handle`) |
+
+## Parameters
+
+`extra="ignore"` on the model.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | `send \| read \| search \| reply \| list_attachments \| download_attachments` | `send` | no | - | Operation dispatch key |
+| `mailbox` | string | `""` | no | - (always shown) | Shared mailbox address; empty targets `/me`, otherwise `/users/{address}`. A value containing `/` or a space raises `NodeUserError` |
+| `to` | string | `""` | yes* | `operation=send` | Comma- or semicolon-separated recipients |
+| `cc` | string | `""` | no | `operation=send` | Same format |
+| `bcc` | string | `""` | no | `operation=send` | Same format |
+| `subject` | string | `""` | yes* | `operation=send` | - |
+| `body` | string | `""` | yes* | `operation=send` | Message body |
+| `body_type` | `text \| html` | `text` | no | `operation=send` | Graph `contentType` `Text` / `HTML` |
+| `message_id` | string | `""` | no for read; yes* for attachment ops | `read`, `list_attachments`, `download_attachments` | Graph message id; empty on `read` lists recent messages instead |
+| `max_results` | int (1..100) | `10` | no | `operation=read` | `$top` for the list form of `read` |
+| `query` | string | `""` | yes* | `operation=search` | Graph `$search` text (quoted by the node) |
+| `search_max_results` | int (1..100) | `10` | no | `operation=search` | `$top` |
+| `reply_message_id` | string | `""` | yes* | `operation=reply` | Message to reply to |
+| `comment` | string | `""` | yes* | `operation=reply` | Reply text |
+| `reply_all` | bool | `false` | no | `operation=reply` | `replyAll` instead of `reply` |
+| `attachment_id` | string | `""` | no | `list_attachments`, `download_attachments` | Download only this attachment (ignored by `list_attachments`) |
+| `include_inline` | bool | `false` | no | `list_attachments`, `download_attachments` | Include `isInline` attachments (signature images) |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `MailOutput`; `hideOutputHandle` auto-set |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+The op returns a `MailOutput` instance, dumped with `mode="json"`; unset
+fields are omitted. Note the sender key is `from_` (the Python field has no
+alias), so downstream templates use `{{msMail.from_}}`.
+
+```ts
+// send
+{ operation: "send"; sent: true; to: string; subject: string }
+// read (message_id given)
+{ operation: "read"; message_id: string; subject: string; from_: string; received: string;
+ body_preview: string; body: string; has_attachments: boolean; web_link: string }
+// read (no message_id) and search
+{ operation: "read" | "search"; messages: Array<{ message_id, subject, from, from_name, received,
+ body_preview, is_read, has_attachments, web_link }>; count: number; query?: string }
+// reply
+{ operation: "reply"; replied: true; message_id: string }
+// list_attachments
+{ operation: "list_attachments"; count: number;
+ attachments: Array<{ attachment_id, name, content_type, size, is_inline, kind: "file" | "item" | "reference" | "unknown" }> }
+// download_attachments
+{ operation: "download_attachments"; count: number; download_dir: string; // absolute <workspace>/attachments
+ attachments: Array<{ filename, path /* absolute */, mime_type, size, ref: FileRef /* kind "file" */ }>;
+ skipped?: Array<{ name, reason }> }
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Operation dispatch] --> B{params.operation}
+ B -- send --> S1[require to, subject, body] --> S2[POST base/sendMail message + saveToSentItems true] --> U[track_microsoft_usage]
+ B -- read --> R1{message_id}
+ R1 -- set --> R2[GET base/messages/id $select + body] --> U
+ R1 -- empty --> R3[GET base/messages $top $select $orderby receivedDateTime desc] --> U
+ B -- search --> Q1[require query] --> Q2[GET base/messages $search quoted, $top, $select, no $orderby] --> U
+ B -- reply --> P1[require reply_message_id, comment] --> P2[POST base/messages/id/reply or replyAll comment] --> U
+ B -- list_attachments --> L1[require message_id] --> L2[GET .../attachments $select id,name,contentType,size,isInline] --> L3[drop inline unless include_inline; kind from @odata.type] --> U
+ B -- download_attachments --> D1[require message_id] --> D2{attachment_id}
+ D2 -- set --> D3[GET .../attachments/attachment_id]
+ D2 -- empty --> D4[GET .../attachments]
+ D3 --> D5[per item: skip non-fileAttachment, inline, missing contentBytes, > MEDIA_MAX_READ_BYTES]
+ D4 --> D5
+ D5 --> D6[base64 decode -> write_attachment_bytes into workspace/attachments] --> D7{any downloaded}
+ D7 -- none --> ERR[NodeUserError No downloadable file attachments]
+ D7 -- yes --> U
+ U --> OUT[Return MailOutput]
+ G[every graph_request: ensure_fresh_microsoft_token -> Connection microsoft -> status >= 400 raises NodeUserError with Graph code: message]
+```
+
+## Decision Logic
+
+- **Validation** (`NodeUserError`): `send` needs `to`, `subject`, `body`;
+ `search` needs `query`; `reply` needs `reply_message_id` and `comment`;
+ attachment ops need `message_id`; unknown operation; invalid `mailbox`.
+- **Mailbox targeting**: `mailbox_base(mailbox)` -> `/me` or
+ `/users/{address}` for every op; a shared mailbox requires Full Access
+ (and Send As for `send`) plus the `.Shared` scopes.
+- **`read` branches**: with `message_id`, one message with `body`
+ (`$select` = `id,subject,from,receivedDateTime,bodyPreview,isRead,
+ hasAttachments,webLink,body`) and usage count 1; without, the list form
+ with `$top = min(max_results, 100)`, ordered newest first, usage count =
+ number returned.
+- **`search`**: `$search` is wrapped in double quotes; `$orderby` is
+ deliberately absent (Graph rejects the combination).
+- **`list_attachments`**: `$select` excludes `contentBytes`, so no payload
+ is fetched; `kind` is `file` for `#microsoft.graph.fileAttachment`,
+ otherwise the `@odata.type` suffix (`itemAttachment` -> `itemAttachment`
+ string tail) or `unknown`.
+- **`download_attachments` skip reasons**: non-`fileAttachment` type, inline
+ without `include_inline`, missing `contentBytes` (Graph may omit it for
+ large attachments), decoded size above `MEDIA_MAX_READ_BYTES` (25 MiB).
+ Nothing downloaded -> `NodeUserError` listing the skips; otherwise
+ `skipped` is included only when non-empty.
+- **Token freshness** (`ensure_fresh_microsoft_token`): no stored tokens ->
+ `PermissionError` annotated `provider="microsoft"`, `reason="missing"`,
+ `auth="oauth2"` (credential envelope + `credential.oauth.runtime_failed`).
+ The in-process expiry map is empty on first use, so the first call after
+ a restart always refreshes (needs the stored refresh token and the
+ `microsoft_client_id` api-key row); a failed refresh falls back to the
+ stored access token silently. Refresh margin is 120 s; unknown
+ `expires_in` assumes 3600 s.
+- **Error paths**: Graph status >= 400 -> `NodeUserError("Microsoft Graph
+ error (<status>): <code>: <message>")`; 204 / empty body -> `None`
+ result, which the ops treat as `{}`.
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per op via
+ `track_microsoft_usage` (`service="microsoft_graph"`, `operation` mapped
+ through `pricing.json` `operation_map.microsoft_graph` - `send` ->
+ `mail_send`, `read` -> `mail_read`, `search` -> `mail_search`, `reply` ->
+ `mail_reply`, `list_attachments` -> `mail_list_attachments`,
+ `download_attachments` -> `mail_download_attachments`; cost 0.0;
+ `resource_count` = 1 or the number of items). Token refresh persists new
+ access / refresh tokens via `auth_service.store_oauth_tokens`.
+- **External API calls**: `POST {base}/sendMail`, `GET {base}/messages[/{id}]`,
+ `POST {base}/messages/{id}/reply|replyAll`,
+ `GET {base}/messages/{id}/attachments[/{id}]` on
+ `https://graph.microsoft.com/v1.0`, bearer auth; the OAuth token endpoint
+ on refresh.
+- **File I/O**: `download_attachments` writes
+ `<workspace>/attachments/<slug>-<node8>-<uuid6>.<ext>` atomically
+ (`atomic_write_bytes`, containment via `resolve_media`) and returns a
+ `FileRef(kind="file")` plus the absolute path.
+- **Broadcasts**: standard node status only.
+
+## External Dependencies
+
+- **Credentials**: `MicrosoftCredential` (`id = "microsoft"`, `OAuth2Credential`;
+ client credentials in api-key rows `microsoft_client_id` /
+ `microsoft_client_secret`; authority `/organizations` - Work / School
+ accounts only). Scopes from `server/config/microsoft_apis.json`:
+ `openid profile email offline_access User.Read Mail.Send Mail.ReadWrite
+ Mail.ReadWrite.Shared Mail.Send.Shared Calendars.ReadWrite
+ Calendars.ReadWrite.Shared`. Connected via the `microsoft_oauth_login` WS
+ handler and `GET /api/microsoft/callback`.
+- **Services**: Microsoft Graph v1.0; `login.microsoftonline.com` for
+ refresh.
+- **Python packages**: `httpx`, `pydantic`; `services.plugin.connection`,
+ `services.media` (`FileRef`, `resolve_media`, `workspace_root`),
+ `nodes.filesystem._backend.atomic_write_bytes`.
+- **Environment variables**: none read directly.
+
+## Edge cases & known limits
+
+- The output field is `from_`, not `from` (no alias on the Pydantic field);
+ the list entries inside `messages` use `from`.
+- `read` without `message_id` always caps at 100 and ignores `query`.
+- `download_attachments` needs a resolvable workspace (`workspace_root(ctx)`);
+ attachments over ~3 MB may arrive without `contentBytes` and are skipped
+ with reason "no contentBytes" - the Graph upload / download session API
+ is out of scope.
+- `list_attachments` counts only the returned (post-filter) attachments
+ toward usage.
+- Graph throttling (per mailbox) surfaces as a 429 `NodeUserError`; the
+ `Connection` retry covers 401 / 403 only.
+- `annotations = {"destructive": False, ...}`.
+
+## Related
+
+- **Skills using this as a tool**: [ms-mail-skill](../../../server/skills/productivity_agent/ms-mail-skill/SKILL.md) (pairs `download_dir` with the document parser's `input_dir`)
+- **Siblings**: [`msMailReceive`](./msMailReceive.md), [`msCalendar`](./msCalendar.md)
+- **Architecture docs**: [Plugin System](../../plugin_system.md), [Media Transport](../../media_transport.md), [Pricing Service](../../pricing_service.md)
diff --git a/docs-internal/node-logic-flows/microsoft/msMailReceive.md b/docs-internal/node-logic-flows/microsoft/msMailReceive.md
new file mode 100644
index 00000000..52dbb9c7
--- /dev/null
+++ b/docs-internal/node-logic-flows/microsoft/msMailReceive.md
@@ -0,0 +1,183 @@
+# Outlook Mail Receive (`msMailReceive`)
+
+| Field | Value |
+|------|-------|
+| **Category** | microsoft / trigger (class `group = ("microsoft", "trigger")`) |
+| **Backend handler** | [`server/nodes/microsoft/mail_receive/__init__.py`](../../../server/nodes/microsoft/mail_receive/__init__.py) (`MailReceiveNode`, on `PollingTriggerNode`); ctx-free Graph helpers in [`_base.py`](../../../server/nodes/microsoft/_base.py) (`graph_get_raw`, `mark_message_read_raw`); base loop in [`services/plugin/polling.py`](../../../server/services/plugin/polling.py); canary registration in [`nodes/microsoft/__init__.py`](../../../server/nodes/microsoft/__init__.py) |
+| **Tests** | [`server/tests/nodes/test_microsoft.py`](../../../server/tests/nodes/test_microsoft.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | no (trigger) |
+
+## Purpose
+
+Fire when a new message appears in an Outlook mail folder. Microsoft Graph
+has no push channel here, so the node polls `mailFolders/{folder}/messages`
+on an interval, diffs the visible ids against the previous cycle, fetches
+each new message and emits its summary. Three execution paths share the same
+four hooks: the Temporal `PollingTriggerWorkflow` (deployed, canary type
+`com.opencompany.msmail.message.received`), the legacy asyncio collector, and
+an inline `execute()` override for the canvas Run button.
+
+## Inputs (handles)
+
+None - this is a trigger; it is the head of a run.
+
+## Parameters
+
+`MailReceiveParams`, `extra="ignore"`. No `displayOptions` on any field.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `mailbox` | string | `""` | no | - | Shared mailbox address to watch; empty = `/me` |
+| `only_unread` | bool | `true` | no | - | Adds `$filter=isRead eq false` |
+| `from_filter` | string | `""` | no | - | Adds `from/emailAddress/address eq '<addr>'` (single quotes doubled) |
+| `folder` | string | `inbox` | no | - | Well-known folder name or folder id, used in `mailFolders/{folder}/messages` |
+| `mark_as_read` | bool | `false` | no | - | PATCH `isRead: true` after emitting |
+| `poll_interval` | int (10..3600) | `60` | no | - | Seconds between cycles; clamped by `poll_interval_clamp` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | The summary dict from `_summarize` (plus `id` on the deployed paths) |
+
+### Output payload (TypeScript shape)
+
+The declared `MailReceiveOutput` model names the sender field `from_`, but
+every path emits the raw `_summarize` dict without passing through
+`_serialize_result` (the canvas path returns the dict from the `execute`
+override; the deployed paths hand `fetch_detail`'s dict straight to the
+queue / activity result). The wire key is therefore `from`:
+
+```ts
+{
+ message_id: string;
+ id?: string; // deployed paths only: stable dedup key (= message_id)
+ conversation_id: string | null;
+ from: string; // sender address ("" when absent)
+ from_name: string;
+ to: string[];
+ subject: string;
+ body_preview: string;
+ body: string; // full body content
+ received: string | null; // receivedDateTime
+ is_read: boolean | null;
+ has_attachments: boolean | null;
+ web_link: string | null;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ subgraph deployed: poll.msMailReceive.v{version} activity / legacy coroutine
+ D0[setup_service returns params] --> D1[fetch_ids: GET base/mailFolders/folder/messages $select $top 25 + $filter or $orderby]
+ D1 -- baseline_only --> D2[return events empty, seen_ids = current]
+ D1 --> D3[new_ids = current - prior_seen]
+ D3 --> D4[per id: fetch_detail GET base/messages/id $select -> _summarize + id]
+ D4 --> D5[post_emit: mark read if mark_as_read, failures logged]
+ D5 --> D6[return events, seen_ids = current]
+ end
+ subgraph canvas Run: execute override
+ C0[broadcast waiting status] --> C1[baseline fetch_ids, failure treated as empty]
+ C1 --> C2[sleep poll_interval]
+ C2 --> C3[fetch_ids; new_ids = current - seen]
+ C3 -- none --> C4[seen = current] --> C2
+ C3 -- some --> C5[pick next iter new_ids; seen = current]
+ C5 --> C6[fetch_detail + post_emit + track usage read 1] --> C7[return success envelope with result = detail]
+ C2 -- CancelledError --> C8[return success false, Cancelled by user]
+ end
+ T[every Graph call: ensure_fresh_microsoft_token -> httpx GET with Bearer; status >= 400 raises NodeUserError]
+```
+
+## Decision Logic
+
+- **Query construction** (`_query`): `$select` =
+ `id,subject,from,toRecipients,receivedDateTime,bodyPreview,body,isRead,
+ hasAttachments,webLink,conversationId`, `$top = 25`. With `only_unread`
+ and / or `from_filter` a `$filter` is sent and `$orderby` is dropped
+ (Graph returns `InefficientFilter` for filter + orderby on different
+ properties without the advanced-query header); with no filter,
+ `$orderby=receivedDateTime desc`. Because the trigger dedups by id it does
+ not depend on ordering.
+- **Dedup / window**: `seen_ids` is rebased to the provider's current window
+ every cycle (both the activity and the coroutine), so a message that
+ leaves the 25-item window and re-enters it later fires again. On the
+ baseline pass nothing is emitted.
+- **Temporal activity** (`as_poll_activity`): `setup_service` failure
+ re-raises (Temporal retry policy owns it); a `fetch_detail` failure skips
+ that id with a warning; `post_emit` failures are swallowed; the result is
+ `{"events": [...], "seen_ids": list(current)}`.
+- **Legacy coroutine** (`_build_poll_coroutine`): setup failure ends the
+ poller; baseline failure logs a warning and treats everything as new on the
+ next cycle; per-cycle exceptions are logged and retried next interval.
+- **Canvas Run** (`execute` override): registers no `event_waiter`; instead
+ it polls inline until the first cycle with new ids, then returns ONE
+ message - `next(iter(new_ids))`, an arbitrary member of the set (the
+ variable is named `newest_id` but set iteration is unordered). The
+ remaining new ids are folded into `seen` and never emitted on that run.
+ Cancellation returns `{success: False, error: "Cancelled by user"}`; any
+ other exception outside the cycle returns `{success: False, error}`.
+- **Auth**: `graph_get_raw` / `mark_message_read_raw` call
+ `ensure_fresh_microsoft_token("owner")` (default user) and issue plain
+ `httpx` requests with a 30 s timeout; no stored tokens ->
+ `PermissionError(provider="microsoft", reason="missing", auth="oauth2")`.
+- **`_clamp_interval`**: non-numeric -> `default_poll_interval` (60);
+ result clamped to 10..3600.
+
+## Side Effects
+
+- **Database writes**: canvas Run records one `api_usage_metrics` row
+ (`service="microsoft_graph"`, action `read`, cost 0.0) when a message
+ fires; the deployed paths record none. Token refresh persists new tokens
+ via `auth_service.store_oauth_tokens`.
+- **Broadcasts**: canvas Run sends `update_node_status(node_id, "waiting",
+ {"message": "Waiting for Outlook mail (polling every Ns)...",
+ "event_type": "ms_mail_received"}, workflow_id=...)`. Deployed status
+ broadcasts come from the trigger manager / `PollingTriggerWorkflow`.
+- **External API calls**: `GET {base}/mailFolders/{folder}/messages`,
+ `GET {base}/messages/{id}`, `PATCH {base}/messages/{id}` (`isRead: true`)
+ on `https://graph.microsoft.com/v1.0` with `Authorization: Bearer`.
+- **Mutation**: `mark_as_read` flips `isRead` on the source mailbox (the
+ only write; best-effort, failure logged at WARNING).
+
+## External Dependencies
+
+- **Credentials**: `MicrosoftCredential` (`id = "microsoft"`, OAuth2,
+ `Mail.ReadWrite` / `Mail.ReadWrite.Shared` scopes; `microsoft_client_id`
+ and `microsoft_client_secret` api-key rows for refresh). Shared-mailbox
+ polling needs Full Access on that mailbox.
+- **Services**: Microsoft Graph v1.0; Temporal when deployed
+ (`TaskQueue.TRIGGERS_POLL`; `register_canary_trigger_type("msMailReceive",
+ "com.opencompany.msmail.message.received")` opts it into
+ `PollingTriggerWorkflow`).
+- **Python packages**: `httpx`, `pydantic`, `temporalio` (activity
+ decorator on the deployed path).
+- **Environment variables**: none read directly.
+
+## Edge cases & known limits
+
+- `$top` is fixed at 25: with `only_unread=true` (default) the window is
+ the 25 most relevant unread messages in Graph's order; a burst of more
+ than 25 new messages between cycles emits only the ones inside the window.
+- Output key is `from`, not the `from_` declared on `MailReceiveOutput` -
+ the model documents the shape but is not enforced on any path (contrast
+ [`msMail`](./msMail.md), whose `read` op emits `from_`).
+- `mark_as_read=true` combined with `only_unread=true` removes fired
+ messages from the next window, which is the stable configuration; with
+ `only_unread=false` and no `from_filter`, the window is the 25 newest
+ messages and old ids churn out as mail arrives.
+- The trigger never downloads attachments; it carries `has_attachments`
+ and `message_id` so a downstream [`msMail`](./msMail.md)
+ `download_attachments` can fetch them.
+- Canvas Run returns one message per run and swallows the rest of that
+ cycle's new ids.
+- `event_type = "ms_mail_received"` is the legacy event-waiter key; the
+ canvas path does not use the event waiter at all.
+
+## Related
+
+- **Consumers**: [`msMail`](./msMail.md) (`reply`, `download_attachments` on the emitted `message_id`)
+- **Sibling pattern**: `googleGmailReceive` (same `PollingTriggerNode` hooks)
+- **Architecture docs**: [Event Framework](../../event_framework.md), [Temporal Architecture](../../TEMPORAL_ARCHITECTURE.md), [Plugin System](../../plugin_system.md)
diff --git a/docs-internal/node-logic-flows/specialized_agents/_pattern.md b/docs-internal/node-logic-flows/specialized_agents/_pattern.md
index 961fe547..7b398d0a 100644
--- a/docs-internal/node-logic-flows/specialized_agents/_pattern.md
+++ b/docs-internal/node-logic-flows/specialized_agents/_pattern.md
@@ -192,14 +192,14 @@ flowchart TD
## Related
-- **Dedicated-path siblings**: [`rlmAgent`](./rlmAgent.md), [`claudeCodeAgent`](./claudeCodeAgent.md)
+- **Dedicated-path siblings**: [`rlmAgent`](./rlm_agent.md), [`claudeCodeAgent`](./claude_code_agent.md)
- **Per-node variants** (short link-style docs):
- [`androidAgent`](./androidAgent.md), [`codingAgent`](./codingAgent.md),
- [`webAgent`](./webAgent.md), [`taskAgent`](./taskAgent.md),
- [`socialAgent`](./socialAgent.md), [`travelAgent`](./travelAgent.md),
- [`toolAgent`](./toolAgent.md), [`productivityAgent`](./productivityAgent.md),
- [`paymentsAgent`](./paymentsAgent.md), [`consumerAgent`](./consumerAgent.md),
- [`autonomousAgent`](./autonomousAgent.md),
- [`orchestratorAgent`](./orchestratorAgent.md), [`aiEmployee`](./aiEmployee.md)
+ [`androidAgent`](./android_agent.md), [`codingAgent`](./coding_agent.md),
+ [`webAgent`](./web_agent.md), [`taskAgent`](./task_agent.md),
+ [`socialAgent`](./social_agent.md), [`travelAgent`](./travel_agent.md),
+ [`toolAgent`](./tool_agent.md), [`productivityAgent`](./productivity_agent.md),
+ [`paymentsAgent`](./payments_agent.md), [`consumerAgent`](./consumer_agent.md),
+ [`autonomousAgent`](./autonomous_agent.md),
+ [`orchestratorAgent`](./orchestrator_agent.md), [`aiEmployee`](./ai_employee.md)
- **Architecture docs**: [Memory Compaction](../../memory_compaction.md),
[Pricing Service](../../pricing_service.md)
diff --git a/docs-internal/node-logic-flows/specialized_agents/aiEmployee.md b/docs-internal/node-logic-flows/specialized_agents/ai_employee.md
similarity index 92%
rename from docs-internal/node-logic-flows/specialized_agents/aiEmployee.md
rename to docs-internal/node-logic-flows/specialized_agents/ai_employee.md
index cce00933..fc9544b7 100644
--- a/docs-internal/node-logic-flows/specialized_agents/aiEmployee.md
+++ b/docs-internal/node-logic-flows/specialized_agents/ai_employee.md
@@ -27,7 +27,7 @@ intrinsic Task Manager -> `execute_chat_agent`.
## Behaviour
-See **[Orchestrator Agent](./orchestratorAgent.md)** for the teammate
+See **[Orchestrator Agent](./orchestrator_agent.md)** for the teammate
expansion details, and **[Generic Specialized Agent Pattern](./_pattern.md)**
for the shared contract.
@@ -39,5 +39,5 @@ for the shared contract.
## Related
- **Pattern doc**: [`_pattern.md`](./_pattern.md)
-- **Sibling team lead**: [`orchestratorAgent`](./orchestratorAgent.md)
+- **Sibling team lead**: [`orchestratorAgent`](./orchestrator_agent.md)
- **Architecture**: [Agent Teams](../../agent_teams.md)
diff --git a/docs-internal/node-logic-flows/specialized_agents/androidAgent.md b/docs-internal/node-logic-flows/specialized_agents/android_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/androidAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/android_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/autonomousAgent.md b/docs-internal/node-logic-flows/specialized_agents/autonomous_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/autonomousAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/autonomous_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/claudeCodeAgent.md b/docs-internal/node-logic-flows/specialized_agents/claude_code_agent.md
similarity index 99%
rename from docs-internal/node-logic-flows/specialized_agents/claudeCodeAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/claude_code_agent.md
index 5bd7d935..b3bab56b 100644
--- a/docs-internal/node-logic-flows/specialized_agents/claudeCodeAgent.md
+++ b/docs-internal/node-logic-flows/specialized_agents/claude_code_agent.md
@@ -179,7 +179,7 @@ flowchart TD
## Related
-- **Dedicated-path siblings**: [`rlmAgent`](./rlmAgent.md)
+- **Dedicated-path siblings**: [`rlmAgent`](./rlm_agent.md)
- **Generic pattern**: [`_pattern.md`](./_pattern.md)
- **Architecture**: [CLI Agent Framework](../../cli_agent_framework.md),
[Claude Code Interactive Mode](../../claude_code_interactive_mode.md),
diff --git a/docs-internal/node-logic-flows/specialized_agents/codexAgent.md b/docs-internal/node-logic-flows/specialized_agents/codex_agent.md
similarity index 98%
rename from docs-internal/node-logic-flows/specialized_agents/codexAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/codex_agent.md
index 2db178ef..bc611196 100644
--- a/docs-internal/node-logic-flows/specialized_agents/codexAgent.md
+++ b/docs-internal/node-logic-flows/specialized_agents/codex_agent.md
@@ -137,6 +137,6 @@ flowchart TD
## Related
-- **Dedicated-path siblings**: [`claudeCodeAgent`](./claudeCodeAgent.md), [`rlmAgent`](./rlmAgent.md)
+- **Dedicated-path siblings**: [`claudeCodeAgent`](./claude_code_agent.md), [`rlmAgent`](./rlm_agent.md)
- **Generic pattern**: [`_pattern.md`](./_pattern.md)
- **Architecture**: [CLI Agent Framework](../../cli_agent_framework.md)
diff --git a/docs-internal/node-logic-flows/specialized_agents/codingAgent.md b/docs-internal/node-logic-flows/specialized_agents/coding_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/codingAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/coding_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/consumerAgent.md b/docs-internal/node-logic-flows/specialized_agents/consumer_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/consumerAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/consumer_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/orchestratorAgent.md b/docs-internal/node-logic-flows/specialized_agents/orchestrator_agent.md
similarity index 98%
rename from docs-internal/node-logic-flows/specialized_agents/orchestratorAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/orchestrator_agent.md
index 08fe4181..98837bd1 100644
--- a/docs-internal/node-logic-flows/specialized_agents/orchestratorAgent.md
+++ b/docs-internal/node-logic-flows/specialized_agents/orchestrator_agent.md
@@ -63,5 +63,5 @@ expansion above.
## Related
- **Pattern doc**: [`_pattern.md`](./_pattern.md)
-- **Sibling team lead**: [`aiEmployee`](./aiEmployee.md)
+- **Sibling team lead**: [`aiEmployee`](./ai_employee.md)
- **Architecture**: [Agent Teams](../../agent_teams.md)
diff --git a/docs-internal/node-logic-flows/specialized_agents/paymentsAgent.md b/docs-internal/node-logic-flows/specialized_agents/payments_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/paymentsAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/payments_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/productivityAgent.md b/docs-internal/node-logic-flows/specialized_agents/productivity_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/productivityAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/productivity_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/rlmAgent.md b/docs-internal/node-logic-flows/specialized_agents/rlm_agent.md
similarity index 98%
rename from docs-internal/node-logic-flows/specialized_agents/rlmAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/rlm_agent.md
index e86fa77e..f22ca351 100644
--- a/docs-internal/node-logic-flows/specialized_agents/rlmAgent.md
+++ b/docs-internal/node-logic-flows/specialized_agents/rlm_agent.md
@@ -115,6 +115,6 @@ flowchart TD
## Related
-- **Dedicated-path siblings**: [`claudeCodeAgent`](./claudeCodeAgent.md)
+- **Dedicated-path siblings**: [`claudeCodeAgent`](./claude_code_agent.md)
- **Generic pattern**: [`_pattern.md`](./_pattern.md)
- **Architecture**: [RLM Service](../../rlm_service.md)
diff --git a/docs-internal/node-logic-flows/specialized_agents/socialAgent.md b/docs-internal/node-logic-flows/specialized_agents/social_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/socialAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/social_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/taskAgent.md b/docs-internal/node-logic-flows/specialized_agents/task_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/taskAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/task_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/toolAgent.md b/docs-internal/node-logic-flows/specialized_agents/tool_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/toolAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/tool_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/travelAgent.md b/docs-internal/node-logic-flows/specialized_agents/travel_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/travelAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/travel_agent.md
diff --git a/docs-internal/node-logic-flows/specialized_agents/vertexCloudTool.md b/docs-internal/node-logic-flows/specialized_agents/vertexCloudTool.md
new file mode 100644
index 00000000..5168f125
--- /dev/null
+++ b/docs-internal/node-logic-flows/specialized_agents/vertexCloudTool.md
@@ -0,0 +1,116 @@
+# Cloud Tool (`vertexCloudTool`)
+
+| Field | Value |
+|------|-------|
+| **Category** | specialized_agents (palette group `tool`; display-only companion of `vertex_managed_agent`) |
+| **Plugin** | [`server/nodes/agent/vertex_cloud_tool/__init__.py::VertexCloudToolNode.info_op`](../../../server/nodes/agent/vertex_cloud_tool/__init__.py); minted, wired, pulsed and fed by [`nodes/agent/vertex_managed_agent/_ops.py`](../../../server/nodes/agent/vertex_managed_agent/_ops.py) (`ensure_cloud_tool_nodes`, `pulse_node`, `record_tool_output`) |
+| **Dispatch** | `BaseNode.execute()` + `@Operation("info")` — but the executor never schedules it (a node wired into an agent's `input-tools` is a sub-node) and the run button is hidden |
+| **Tests** | [`server/tests/nodes/test_vertex_agents.py::TestCloudToolMinting`](../../../server/tests/nodes/test_vertex_agents.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | no - `usable_as_tool = False`, `component_kind = "square"`; excluded from `iter_tool_node_classes` and skipped by `vertex_managed_agent._is_declarable_tool_type` |
+
+## Purpose
+
+The canvas-visible trace of work that happened in Google's cloud. The
+managed agent runs entirely remotely, so when it uses a cloud-side tool
+(sandbox `run_command`, `code_execution`, `google_search`, `url_context`,
+an MCP tool) the parent `vertex_managed_agent` mints one of these nodes per
+distinct tool, wires it into its own `input-tools` handle, and pulses it
+`executing` -> `success` around each use. Clicking the node shows the
+recorded invocation (arguments + result) in the Output panel exactly like a
+locally executed tool. It performs no work itself and is safe to delete.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `output-tool` (source, top) | tools | - | The only handle: connects upward into the agent's bottom `input-tools` (house-shaped tool-node convention). No `input-main`. |
+
+`group = ("tool",)` auto-derives `uiHints.isConfigNode = true`; the class
+adds `hideRunButton`. `component_kind` is `square` (not `tool`) so it
+renders through `SquareNode` without the tool-schema editor panel.
+
+## Parameters
+
+Params model `VertexCloudToolParams` (`extra="ignore"`) — set by the
+minting helper, not meant to be edited by hand. It exists so the node has an
+input schema registered in `NODE_INPUT_MODELS` (plugins on the default empty
+Params are not registered, which leaves the parameter panel schema-less).
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `cloud_tool_key` | string \| null | `null` | no | - | Stable key of the cloud-side tool: `type:<step_type>` (`code_execution_call`, `google_search_call`, `url_context_call`, `mcp_server_tool_call`) or `fn:<name>` for undeclared `function_call` steps |
+| `label` | string \| null | `null` | no | - | Display label (`Code Execution`, `Google Search`, `URL Context`, `MCP Tool`, or the raw function name) |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| (none declared as `main`) | - | `info_op` returns `VertexCloudToolOutput`; the value users actually see in the Output panel is the invocation record written by `record_tool_output`, not this echo |
+
+### Output payload (TypeScript shape)
+
+```ts
+// info_op echo (only if someone executes the node directly)
+{ cloud_tool_key: string | null; label: string | null; message: string }
+
+// what record_tool_output persists as output_0 / broadcasts as node_output
+{
+ tool: string; // display label
+ arguments: unknown; // JSON-safe dump of the call step's arguments
+ result: unknown; // JSON-safe dump of the matching *_result step (or the whole step)
+ is_error: boolean;
+ timestamp: string;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[vertex_managed_agent sees a cloud-side step - live SSE or post-turn sweep] --> B[ensure_cloud_tool_nodes workflow_id, agent_node_id, used key->label]
+ B --> C[get_workflow; existing = vertexCloudTool nodes already edged into agent input-tools, keyed by label]
+ C --> D{label already present?}
+ D -- yes --> E[reuse node id]
+ D -- no --> F[mint id vertexCloudTool-epoch_ms-hex6; add_node op anchored below-left of agent offset_x -60, offset_y 240 + 90*i; add_edge output-tool -> input-tools]
+ F --> G[append node position 0,0 + edge e-minted-agent to workflow.data; save_node_parameters label, cloud_tool_key]
+ G --> H[save_workflow FIRST, then broadcast workflow_ops_apply operations]
+ E --> I[pulse_node executing]
+ H --> I
+ I --> J[matching *_result step: pulse_node success + record_tool_output save_node_output + node_output broadcast]
+ K[direct execute - hidden run button] --> L[info_op echoes cloud_tool_key, label, message]
+```
+
+## Decision Logic
+
+- **Validation**: none in the node. Minting requires a saved workflow (`get_workflow` returns `None` -> no nodes minted, empty map returned).
+- **Branches**: dedupe is by `label` among display nodes already wired to that agent; a key whose label matches an existing node reuses it without a DB write. The live handler memoizes `live_nodes[key]` per run so each key costs one DB round-trip; the post-turn sweep mints only keys the stream missed and pulses them `executing` then `success` back-to-back.
+- **Fallbacks**: `_CLOUD_NOISE_NAMES` (`provision_sandbox`) is never minted; declared local tools are never minted (they are real nodes executed at `requires_action`).
+- **Error paths**: minting/pulsing/recording failures are best-effort — `record_tool_output` logs `exception` and returns without broadcasting when the DB write fails; the agent's sweep wraps everything in `try/except` and logs.
+
+## Side Effects
+
+- **Database writes** (all performed by `_ops`, on behalf of the agent): `workflow.data` nodes + edges rewrite (`save_workflow` with unchanged name/slug/description), `node_parameters` row `{label, cloud_tool_key}` per minted node, `node_outputs` row (`session_id "default"`, `output_0`) per recorded invocation.
+- **Broadcasts**: `workflow_ops_apply` `{workflow_id, caller_node_id, operations}` (each `add_node` op carries `minted_id` so backend status broadcasts glow the exact node the frontend creates), `node_status` `executing` / `success` with message "Used by Vertex agent", `node_output`.
+- **External API calls / File I/O / Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: none.
+- **Services**: `services.workflow_ops` (`add_node`, `add_edge`, `anchored`), `StatusBroadcaster`, `services.plugin.deps.get_database`.
+- **Task queue**: `TaskQueue.REST_API` (never actually dispatched). Annotations: `readonly`.
+
+## Edge cases & known limits
+
+- Deleting the node is safe, but the next run that uses the same cloud tool mints it again.
+- Persisted position is the `{0, 0}` placeholder; the anchored position exists only in the broadcast op. If no client is connected to apply the op and auto-save, the node reloads at the canvas origin.
+- Dedupe is label-based, so two distinct keys sharing a label collapse into one node; conversely two agents on the same canvas each get their own copies (dedupe is scoped to edges targeting the minting agent).
+- `label` is `node.data.label`, which the user can F2-rename; a renamed display node no longer dedupes and a fresh one is minted beside it.
+- Because the node sits on `input-tools`, `_is_declarable_tool_type` must skip it or the agent would declare a function tool with an empty schema; the exclusion is by `component_kind == "square"` + `usable_as_tool = False`, not by type string.
+- Recorded outputs use `session_id = "default"` regardless of the run's session, matching what the Output panel fetches.
+
+## Related
+
+- **Owner**: [`vertex_managed_agent`](./vertex_managed_agent.md) (only producer of these nodes).
+- **Same minting pattern**: [`agentBuilder`](../ai_tools/agentBuilder.md) (workflow-ops push broadcast).
+- **Architecture docs**: [workflow_ops_protocol.md](../../workflow_ops_protocol.md), [status_broadcaster.md](../../status_broadcaster.md).
diff --git a/docs-internal/node-logic-flows/specialized_agents/vertex_agent_admin.md b/docs-internal/node-logic-flows/specialized_agents/vertex_agent_admin.md
new file mode 100644
index 00000000..3bd95d59
--- /dev/null
+++ b/docs-internal/node-logic-flows/specialized_agents/vertex_agent_admin.md
@@ -0,0 +1,131 @@
+# Vertex Agent Admin (`vertex_agent_admin`)
+
+| Field | Value |
+|------|-------|
+| **Category** | specialized_agents (palette group `agent` — deliberately not `tool`, which would auto-derive a bogus `isConfigNode` hint) |
+| **Plugin** | [`server/nodes/agent/vertex_agent_admin/__init__.py::VertexAgentAdminNode`](../../../server/nodes/agent/vertex_agent_admin/__init__.py) — four `@Operation`s (`create_op` / `list_op` / `get_op` / `delete_op`) selected by the `operation` parameter via `BaseNode.execute()`; shared helpers in [`nodes/agent/_vertex.py`](../../../server/nodes/agent/_vertex.py) |
+| **Dispatch** | Plain `ActionNode`, `component_kind = "square"`; not an agent loop, no `SpecializedAgentBase`, no edge walking |
+| **Tests** | [`server/tests/nodes/test_vertex_agents.py::TestVertexAgentAdmin`](../../../server/tests/nodes/test_vertex_agents.py) |
+| **Skill (if any)** | [`server/skills/vertex_agent/vertex-agent-admin-skill/SKILL.md`](../../../server/skills/vertex_agent/vertex-agent-admin-skill/SKILL.md) names it in `allowed-tools`, but see Dual-purpose |
+| **Dual-purpose tool** | no - `usable_as_tool = False` (lifecycle CRUD including delete is operator-facing, not LLM-callable); `iter_tool_node_classes` never yields it |
+
+## Purpose
+
+Operator-facing lifecycle CRUD for **custom managed agents** on the Gemini
+Enterprise Agent Platform (Agents API): create a custom agent on top of the
+prebuilt Antigravity base agent with its own system instruction and
+built-in cloud tool set, list the project's agents, inspect one, or delete
+one. The resulting `agent_id` is what a [`vertex_managed_agent`](./vertex_managed_agent.md)
+node puts in its `agent` parameter. Creation is a long-running operation
+(~2-3 minutes the first time, seconds afterwards); the Python SDK blocks
+until it resolves.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data via templates (e.g. an `agent_id` produced upstream) |
+
+`usable_as_tool` is `False` and `component_kind` is `square`, so the base
+class does not hide the canvas handles and no `output-tool` handle is
+synthesized.
+
+## Parameters
+
+Params model `VertexAgentAdminParams` (`extra="ignore"`):
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | enum `create` \| `list` \| `get` \| `delete` | `list` | no | - | Selects the `@Operation` |
+| `project_id` | string | `""` | no | - | GCP project id (ADC auth). Empty -> stored `AIza` Gemini key |
+| `agent_id` | string \| null | `null` | required by `create` / `get` / `delete` (`NodeUserError` when blank) | `operation: [create, get, delete]` | Custom agent id ("lowercase letters, numbers, hyphens" per the description; not validated locally) |
+| `description` | string \| null | `null` | no | `operation: [create]` | Agent description (omitted from the create call when empty) |
+| `system_instruction` | string \| null (3 rows) | `null` | no | `operation: [create]` | Agent system instruction (omitted when empty) |
+| `base_agent` | string | `antigravity-preview-05-2026` | no | `operation: [create]` | Base managed agent; an empty string falls back to the default |
+| `tools` | list of `code_execution` \| `filesystem` \| `google_search` \| `url_context` | `["code_execution"]` | no | `operation: [create]` | Built-in cloud tools, sent as `[{"type": <name>}, ...]` |
+| `location` | string | `global` | no | group `options` | Passed to the enterprise client only (ignored with an API key) |
+
+No `api_key` field and **no auto-injection**: the type is not in
+`AI_MODEL_TYPES`, so `_client` calls `resolve_gemini_api_key_from_store()`
+(`auth.get_api_key("gemini", "default")`, exceptions -> `""`) whenever
+`project_id` is empty.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `VertexAgentAdminOutput` (`extra="allow"`) in the standard envelope; unset fields are dropped at serialization |
+
+### Output payload (TypeScript shape)
+
+```ts
+// create / get
+{ operation: 'create' | 'get'; agent: Record<string, unknown>; timestamp: string }
+// list
+{ operation: 'list'; agents: Array<Record<string, unknown>>; count: number; timestamp: string }
+// delete
+{ operation: 'delete'; deleted: true; agent: { id: string }; timestamp: string }
+```
+
+`agent` records are `model_dump(mode="json", exclude_none=True)` of the SDK
+object (a dict passes through; anything else becomes `{id: str(obj)}`).
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[BaseNode.execute routes params.operation] --> B{operation}
+ B -- create/get/delete --> C[_require_agent_id]
+ C -- blank --> E1[NodeUserError: operation needs an agent_id]
+ B -- list --> D
+ C --> D[_client: project_id ? ADC enterprise client : stored gemini key]
+ D -- no project_id and key not AIza --> E2[NodeUserError: need project id or AIza key]
+ D --> F{operation}
+ F -- create --> G[broadcast executing: Creating agent ... ~2-3 min]
+ G --> H[agents.create id, base_agent, tools, description?, system_instruction? - blocking LRO]
+ F -- list --> I[agents.list -> response.agents or list of response]
+ F -- get --> J[agents.get id]
+ F -- delete --> K[agents.delete id]
+ H & I & J & K -- genai error --> E3[raise_as_user_error -> NodeUserError with 400-char detail]
+ H & I & J & K -- other exception --> E4[propagate - full traceback]
+ H --> L[operation, agent, timestamp]
+ I --> M[operation, agents, count, timestamp]
+ J --> L
+ K --> N[operation, deleted true, agent id, timestamp]
+```
+
+## Decision Logic
+
+- **Validation**: `agent_id` must be non-blank for `create` / `get` / `delete`; no format check is performed locally (the API rejects bad ids). `list` needs nothing.
+- **Branches**: auth surface — `project_id` set -> `genai.Client(enterprise=True, project, location)` with ADC; otherwise the stored gemini key must start with `AIza` or `build_genai_client` raises `NodeUserError` (`AQ.` keys are rejected). `list` tolerates both a response object exposing `.agents` and an iterable response (a plain dict response yields an empty list).
+- **Fallbacks**: `base_agent` empty -> `DEFAULT_MANAGED_AGENT`; `description` / `system_instruction` are omitted from the create call rather than sent empty.
+- **Error paths**: every SDK exception whose class lives under `google.genai` becomes `NodeUserError("Agent <op> '<id>' failed: <detail>")` (one WARN line); anything else propagates as a genuine error.
+
+## Side Effects
+
+- **Database writes**: none (the `cost={"service": "vertex_agent", ...}` on each operation is inert — no code reads `OperationSpec.cost`).
+- **Broadcasts**: `update_node_status(node_id, "executing", {message: "Creating agent '<id>' (first create takes ~2-3 min)..."})` on `create` only.
+- **External API calls**: `client.aio.agents.create / list / get / delete` on the Agent Platform (enterprise, ADC) or `generativelanguage.googleapis.com` (API key).
+- **File I/O / Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: stored `gemini` API key (read directly from the credential store) or gcloud ADC with `project_id`.
+- **Services**: `services.plugin.deps.get_ai_service().auth` (key lookup), `StatusBroadcaster`.
+- **Python packages**: `google-genai`.
+- **Task queue**: `TaskQueue.REST_API`. Annotations: `destructive`, `open_world`.
+
+## Edge cases & known limits
+
+- `create` blocks the activity for the whole long-running operation; there is no polling, no progress broadcast after the initial message, and the default 10-minute action `start_to_close_timeout` applies (the class does not raise it).
+- `delete` is irreversible and has no confirmation; deleting an agent does not delete past interactions or sandboxes (they expire on their own TTL).
+- `location` is silently ignored on the API-key path.
+- The skill doc's field rules ("1-63 chars, must start with a letter") are documentation only — the node passes `agent_id` through verbatim.
+- The skill names this node in `allowed-tools`, yet the node is not LLM-callable; the skill functions as operator documentation, not as a tool binding.
+- A missing gemini key with an empty `project_id` surfaces as the generic "need a project id or AIza key" `NodeUserError`, not as the annotated credential envelope.
+
+## Related
+
+- **Consumer**: [`vertex_managed_agent`](./vertex_managed_agent.md) runs the agents created here (`agent` parameter).
+- **Skill**: [`vertex-agent-admin-skill`](../../../server/skills/vertex_agent/vertex-agent-admin-skill/SKILL.md).
+- **Architecture docs**: [plugin_system.md](../../plugin_system.md), [agent_architecture.md](../../agent_architecture.md).
diff --git a/docs-internal/node-logic-flows/specialized_agents/vertex_managed_agent.md b/docs-internal/node-logic-flows/specialized_agents/vertex_managed_agent.md
new file mode 100644
index 00000000..ee889618
--- /dev/null
+++ b/docs-internal/node-logic-flows/specialized_agents/vertex_managed_agent.md
@@ -0,0 +1,196 @@
+# Vertex Agent (`vertex_managed_agent`)
+
+| Field | Value |
+|------|-------|
+| **Category** | specialized_agents (palette group `agent`) |
+| **Plugin** | [`server/nodes/agent/vertex_managed_agent/__init__.py::VertexManagedAgentNode.execute_op`](../../../server/nodes/agent/vertex_managed_agent/__init__.py) (dispatch via `BaseNode.execute()` + `@Operation("execute")`; helpers: [`nodes/agent/_vertex.py`](../../../server/nodes/agent/_vertex.py) client/auth/stream, [`vertex_managed_agent/_ops.py`](../../../server/nodes/agent/vertex_managed_agent/_ops.py) cloud-tool node minting, [`nodes/agent/_handles.py`](../../../server/nodes/agent/_handles.py) topology) |
+| **Dispatch** | **Own path** — an `ActionNode` with `component_kind = "agent"`, NOT a `SpecializedAgentBase` subclass; never calls `prepare_agent_call` / `AIService.execute_chat_agent` / `run_native_agent_loop`. The LLM is Google's cloud-hosted managed agent (Interactions API). |
+| **Connection collection** | [`server/services/plugin/edge_walker.py::collect_agent_connections`](../../../server/services/plugin/edge_walker.py) — only `context_data`, `tool_data`, `input_data` are used; the `skill_data` and `task_data` positions are discarded (see Edge cases) |
+| **Tests** | [`server/tests/nodes/test_vertex_agents.py`](../../../server/tests/nodes/test_vertex_agents.py) (`TestVertexManagedAgent`, `TestStreamInteraction`, `TestCloudToolMinting`, `TestChainIdHelpers`) |
+| **Skill (if any)** | [`server/skills/vertex_agent/vertex-agent-skill/SKILL.md`](../../../server/skills/vertex_agent/vertex-agent-skill/SKILL.md) (`allowed-tools: "vertex_managed_agent"`) |
+| **Dual-purpose tool** | yes as a delegation target - tool name `delegate_to_vertex_managed_agent` (declared on the class; `tool_description` is the auto-derived ONE-SHOT delegation text because the class does not override it) |
+
+## Purpose
+
+Runs a Google **managed agent** (default: the prebuilt Antigravity agent,
+`antigravity-preview-05-2026`) through the Gemini Enterprise Agent Platform
+Interactions API and bridges the OpenCompany canvas into it. Connected tool
+nodes are declared to the cloud agent as `function` tools; when the cloud
+agent stops with `status == "requires_action"` the pending calls are
+executed locally through the standard `execute_tool` path (so tool nodes
+glow exactly as they do for the local agent loop) and answered with
+`function_result` inputs on a chained follow-up create. Cloud-side tool
+usage (sandbox commands, `google_search`, `url_context`, `code_execution`,
+MCP tools) is surfaced live as dynamic [`vertexCloudTool`](./vertexCloudTool.md)
+canvas nodes via the workflow-ops protocol. Conversation continuity is the
+Context store on V2 graphs (transcript rendered into the prompt); immutable
+V1 generations keep the recorded Simple Memory chain-id bridge
+(`vertex_interaction_id` / `vertex_environment_id`).
+
+## Inputs (handles)
+
+`std_agent_handles()` + `STD_AGENT_HINTS` (`width 300`, `height 200`,
+`hasSkills`, `requiresContext`); `requires_context = True`.
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` (left 25%) | main | no | Upstream data; auto-prompt fallback when `prompt` is empty (`message` > `text` > `content` > `str(input)`) |
+| `input-context` (left 50%) | context | no (graph normalization pairs the agent with one Context node) | Plain conversation store; when present the run is Context-bound: transcript augments the prompt, a fresh remote interaction starts every firing, `record_turn` saves the exchange |
+| `input-task` (left 75%) | task | no | Walked by the edge walker but the `task_data` tuple slot is **discarded** by this plugin — no task-completion short-circuit exists here |
+| `input-skill` (bottom 25%) | skill | no | Walked but the `skill_data` slot is **discarded** — connected skills / Master Skill entries never reach the cloud agent |
+| `input-tools` (bottom 75%) | tools | no | Tool nodes -> Interactions `function` declarations (ToolNodes, agents for delegation, `usable_as_tool` ActionNodes; display-only types such as `vertexCloudTool` are skipped) |
+| `output-main` (right), `output-top` (top) | main | - | Result payload below |
+
+Legacy `input-memory` edges (immutable V1 generations) still surface as
+`context_data` that is not a Context descriptor; the plugin treats that as
+`memory_data` and reads/writes chain ids on the `simpleMemory` node's
+parameters.
+
+## Parameters
+
+Params model `VertexManagedAgentParams` (`extra="ignore"`). `api_key` is
+deliberately **not** a field: the node type is in `AI_AGENT_TYPES` (hence
+`AI_MODEL_TYPES`), so `node_executor._inject_api_keys` injects the stored
+`gemini` key (via `detect_ai_provider`, which reads `parameters.provider`)
+and the plugin recovers it from `ctx.raw["_raw_parameters"]["api_key"]`
+(`resolve_api_key_from_context` trusts only `AIza`/`AQ.` prefixes).
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `prompt` | string (4 rows, placeholder) | `""` | no (empty prompt AND no usable `input-main` -> `NodeUserError`) | - | User prompt; falls back to upstream input |
+| `agent` | string | `antigravity-preview-05-2026` | no | - | Prebuilt Antigravity agent or a custom agent id created by [`vertex_agent_admin`](./vertex_agent_admin.md) |
+| `project_id` | string | `""` | no | - | GCP project for the enterprise Agent Platform surface (ADC auth). Empty -> stored `AIza` Gemini key |
+| `provider` | Literal `gemini` | `gemini` | no | - | Single-valued on purpose so `detect_ai_provider` / `_inject_api_keys` resolve the gemini credential |
+| `system_instruction` | string \| null (3 rows) | `null` | no | group `options` | Extra system instruction; an "Agent Delegation" section is appended automatically when sub-agents are connected |
+| `location` | string | `global` | no | group `options` | Only used with `project_id` (enterprise client) |
+| `max_turns` | integer, `ge=1, le=100` | `25` | no | group `options` | Cap on `requires_action` tool round-trips per run |
+| `delegation_wait_seconds` | integer, `ge=0, le=1500` | `600` | no | group `options` | How long a bridged `delegate_to_*` call blocks for the child's real answer before falling back to `task_id` + `check_delegated_tasks`; `0` = fire-and-forget |
+| `visualize_cloud_tools` | boolean | `true` | no | group `options` | Mint `vertexCloudTool` canvas nodes for cloud-side tool usage |
+
+Class-level execution contract: `task_queue = AI_HEAVY`,
+`retry_policy = RetryPolicy(maximum_attempts=1)` (cloud turns are not
+idempotent), `start_to_close_timeout = AI_START_TO_CLOSE` (30 min),
+`needs_canvas = True` (nodes/edges must reach `ctx` under Temporal per-tool
+dispatch), annotations `open_world`.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` / `output-top` | object | `VertexManagedAgentOutput` (`extra="allow"`), wrapped in the standard `{success, result, execution_time}` envelope |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ response: string; // interaction.output_text or ""
+ interaction_id: string | null; // null on Context-bound runs (provider bindings never enter node outputs)
+ environment_id: string | null; // null on Context-bound runs
+ status: string | null; // completed | requires_action | failed | cancelled | incomplete | budget_exceeded
+ agent: string;
+ provider: 'gemini';
+ turns: number; // 1 + number of requires_action round-trips executed
+ cloud_tools_used: string[] | null; // sorted display labels (live-minted + post-turn sweep)
+ usage: Record<string, unknown> | null;
+ timestamp: string;
+ warnings: string[] | null; // e.g. "requires_action with no answerable function calls: pending=[...] declared=[...]"
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[execute_op] --> P0[phase initializing]
+ P0 --> B[collect_agent_connections -> context_data, tool_data, input_data]
+ B --> C{is_context?}
+ C -- yes --> C1[SpecializedAgentContextBridge.resolve provider=vertex; memory_data=None]
+ C -- no --> C2[memory_data = context_data - legacy simpleMemory descriptor or None]
+ C1 --> D[prompt = params.prompt or message/text/content/str of input]
+ C2 --> D
+ D -- empty --> E1[NodeUserError: provide a prompt or connect an input]
+ D --> D2[Context: prompt = augment_prompt]
+ D2 --> F[resolve_api_key_from_context + build_genai_client]
+ F -- no project_id and key not AIza --> E2[NodeUserError: need project id or AIza key]
+ F --> G[phase building_tools: _build_function_tools via AIService._build_tool_from_node; inline schema refs; duplicate names -> ensure_unique_tool_names]
+ G --> G2{any connected agent?}
+ G2 -- yes --> G3[declare check_delegated_tasks + append Agent Delegation system text]
+ G2 -- no --> H
+ G3 --> H[visualize? build live SSE handler]
+ H --> I{memory_data node_id?}
+ I -- yes --> I1[phase loading_memory: prev_interaction_id / environment from simpleMemory params]
+ I -- no --> J[environment=remote, no previous id]
+ I1 --> J
+ J --> K[phase invoking_llm + agent_progress turn 1]
+ K --> L[stream_interaction: create background+stream, then non-stream get polled to terminal status]
+ L -- genai error --> L1[raise_as_user_error -> NodeUserError]
+ L1 -- prev id and expired-environment or precondition failure --> L2[wipe chain ids on memory node, retry fresh environment=remote]
+ L1 -- otherwise --> E3[propagate NodeUserError]
+ L --> M{status == requires_action and turn < max_turns?}
+ L2 --> M
+ M -- yes --> N[_pending_function_results_needed: declared, unanswered calls]
+ N -- none --> N1[append warning, break]
+ N -- some --> O[wait = min delegation_wait_seconds, 30 min budget - elapsed - 120 s]
+ O --> Q[for each call: phase executing_tool -> execute_tool -> record_tool_output on the tool node; exception -> function_result is_error]
+ Q --> R[turn += 1, agent_progress, run_turn input=function_results previous_interaction_id=interaction.id]
+ R --> M
+ M -- no --> S[response_text, status, environment_id, usage]
+ N1 --> S
+ S --> T{visualize and workflow_id?}
+ T -- yes --> T1[sweep: ensure_cloud_tool_nodes for keys the stream missed, pulse executing+success, _record_swept_outputs, close dangling glows]
+ T -- no --> U
+ T1 --> U{memory_data?}
+ U -- yes --> U1[phase saving_memory: chain ids only if status resumable; append human/assistant turns window_size]
+ U -- no, context bridge and response --> U2[phase saving_context: record_turn original_prompt, response - best effort]
+ U1 --> V[save_api_usage_metric service=vertex_agent cost=0.0]
+ U2 --> V
+ U --> V
+ V --> W[update_node_status success if completed else warning]
+ W --> X[return payload]
+```
+
+## Decision Logic
+
+- **Validation**: empty prompt with no usable upstream input -> `NodeUserError`; `build_genai_client` raises `NodeUserError` unless `project_id` is set (enterprise client, `location`) or the injected key starts with `AIza` (`AQ.` Vertex Express keys pass `resolve_api_key_from_context` but are rejected here); a stream that ends without an interaction id -> `NodeUserError`.
+- **Tool declaration gate** (`_is_declarable_tool_type`): unknown types (no plugin class) default-allow; `component_kind in {tool, agent}` or `usable_as_tool` declare; everything else (e.g. `vertexCloudTool`) is skipped. `check_delegated_tasks` (`_builtin_check_delegated_tasks`) is declared iff any config's `node_type` is in `AI_AGENT_TYPES`, and it must be declared before the live handler snapshots `declared_names` or a streamed check call would mint a bogus cloud-tool node.
+- **Stale chain retry** (turn 1 only): a `NodeUserError` whose `__cause__` is a genai error matching `is_expired_environment_error` (environment/interaction + not found/expired/invalid) or `is_precondition_failure` ("Precondition check failed"), when a `previous_interaction_id` was sent, wipes `vertex_interaction_id` / `vertex_environment_id` on the memory node (idempotent `mutation_id` `vertex-chain-reset:<execution_id>:<node>:<memory>`) and retries once with `environment="remote"`.
+- **Streaming fallback** (`stream_interaction`): if `interactions.create(background=True, stream=True)` raises a genai error, the client is latched with `_opencompany_stream_unsupported = True` and every later turn of the run uses `create_interaction_and_wait` (background create + `interactions.get` poll every 3 s until a status in `TERMINAL_STATUSES`). The SSE stream is visibility-only; the authoritative resource is always the final non-stream `get`.
+- **requires_action loop**: only calls whose `name` is in `tool_configs` and whose `id` has no matching `function_result` step are executed; cloud-internal calls (`provision_sandbox` noise, `run_command`, ...) are answered server-side. `turn` is capped by `max_turns`; the wait budget leaves 120 s of the 30 min activity for the closing turn, persist and sweep. `delegation_wait_seconds` is attached only for agent-type tools; `execute_tool` then awaits the child inline and a timed-out re-call awaits the existing in-flight task (`_active_delegations` dedupe) instead of duplicating work.
+- **Chain persistence rule**: only `completed` / `requires_action` (`_RESUMABLE_STATUSES`) may overwrite the stored chain ids — persisting a failed/stuck id wedges every later run on 400 Precondition; otherwise the last good pair is kept (environment `remote` is stored as `None`).
+- **Context vs memory precedence**: a Context descriptor wins (`memory_data = None`); Context-bound runs never send `previous_interaction_id` and never expose `interaction_id` / `environment_id` in the output.
+- **Error paths**: any genai SDK exception in a turn -> `NodeUserError("Vertex managed agent interaction failed: <detail[:400]>")`; non-genai exceptions propagate as-is (full traceback). Bridged tool failures never abort the run — they return `{"type": "function_result", ..., "result": {"error": ...}, "is_error": true}` to the cloud agent. Cloud-tool minting failures are logged (`logger.exception`) and swallowed; conversation-save and usage-metric failures are logged and swallowed.
+- **Final status**: `success` only when `status == "completed"`; every other terminal status (including `requires_action` exhausted by `max_turns`) broadcasts node status `warning` with the turn count and `warnings`.
+
+## Side Effects
+
+- **Database reads**: `get_node_parameters` for every connected node (edge walker) and for the legacy memory node; `get_workflow` inside `ensure_cloud_tool_nodes`; `ToolSchema` overrides through `AIService._build_tool_from_node`.
+- **Database writes**: `simpleMemory` node parameters (`vertex_interaction_id`, `vertex_environment_id`, memory turns via `append_memory_turns_atomic` / `update_memory_parameters_atomic`, idempotent `mutation_id` `vertex-memory:<execution_id>:<node>:<memory>`); `agent_conversations` via `SpecializedAgentContextBridge.record_turn` on V2; `api_usage_metrics` row `{service: vertex_agent, operation: interaction, endpoint: interactions.create, resource_count: usage.total_tokens or 1, cost: 0.0}`; `node_outputs` rows (`save_node_output(<tool node>, "default", "output_0", {tool, arguments, result, is_error, timestamp})`) for every bridged local call and every cloud-tool step; `workflow.data` rewrite + `save_node_parameters` for each minted `vertexCloudTool` node (persist-then-broadcast).
+- **Broadcasts**: `update_node_status(executing, phase=...)` for `initializing`, `building_tools`, `loading_memory`, `invoking_llm`, `executing_tool` (also from the live handler for declared and cloud tools), `saving_memory`, `saving_context`; `broadcast_agent_progress(iteration, max_iterations=max_turns)` per turn; `workflow_ops_apply` wire frames `{workflow_id, caller_node_id, operations}` from `_ops`; `node_status` pulses (`executing` / `success`, message "Used by Vertex agent") and `node_output` on display/tool nodes; terminal `success` or `warning`. Bridged tool execution inherits `execute_tool`'s own `executing_tool` broadcasts on the tool node.
+- **External API calls**: `interactions.create` (`background=True`, `stream=True` when supported), `interactions.get` polling, on `generativelanguage.googleapis.com` (`AIza` key) or the enterprise Agent Platform on `aiplatform.googleapis.com` (ADC, `project_id`, `location`).
+- **File I/O / Subprocess**: none directly; bridged local tools may do both.
+
+## External Dependencies
+
+- **Credentials**: stored `gemini` API key auto-injected by `node_executor._inject_api_keys`, OR gcloud Application Default Credentials when `project_id` is set (no OpenCompany credential row involved).
+- **Services**: `AIService._build_tool_from_node`, `services.handlers.tools.execute_tool` (+ `wait_for_delegation`), `services.tool_identity.ensure_unique_tool_names`, `services.plugin.tool.inline_schema_refs`, `services.workflow_ops`, `services.memory.runtime`, `services.cli_agent.context_bridge`, `StatusBroadcaster`.
+- **Python packages**: `google-genai` (`genai.Client`, `client.aio.interactions`, `client.aio.agents`).
+- **Environment variables**: none read by the plugin; ADC discovery is the SDK's (`gcloud auth application-default login`).
+
+## Edge cases & known limits
+
+- **Skills and task input are silently ignored**: `collect_agent_connections` returns a 5-tuple and this plugin unpacks `context_data, _, tool_data, input_data, _` — `input-skill` and `input-task` edges are accepted by the handles but contribute nothing. `STD_AGENT_HINTS.hasSkills` is therefore cosmetic for this node.
+- **Provider fallback trap**: `_inject_api_keys` calls `detect_ai_provider(node_type, params)`, which reads `parameters.provider`; saved params that predate the Literal field fall back to `openai`, the injected key fails the `AIza`/`AQ.` prefix check, and the run raises the "need a project id or AIza key" `NodeUserError` even though a gemini key is stored.
+- **Sandbox continuity differs by graph generation**: the skill doc promises 7-day sandbox/conversation persistence "when a simpleMemory node is connected"; on V2 graphs the standard handles carry no `input-memory` and Context-bound runs start a fresh remote interaction every firing, so only the stored transcript persists — installed packages / created files in the cloud sandbox do not.
+- The `cost={"service": "vertex_agent", "action": "interact"}` on `@Operation` is inert metadata (nothing in `services/` reads `OperationSpec.cost`); the usage row is written manually with `cost: 0.0` — tokens are billed by Google and not priced here.
+- `max_turns` counts the initial turn: `max_turns=1` never answers a `requires_action`.
+- Undeclared cloud-side `function_call` names stop the loop with a warning rather than an error; the payload then reports `status: requires_action` and node status `warning`.
+- `warning` is not one of the usual `success` / `error` node statuses; the canvas treats it as a non-executing terminal state.
+- Minted `vertexCloudTool` nodes are persisted with position `{0, 0}` (the frontend applier resolves the anchored position); an unsaved workflow (`workflow_id` None) skips minting and output recording of cloud steps entirely.
+- Live visibility relies on `step.start` events with `call_id`-joined `*_result` steps; anything the stream misses is reconciled by the post-turn sweep from the final resource, so labels can appear only after the turn ends.
+- Temporal `RetryPolicy(maximum_attempts=1)`: a failed activity is not retried; the deployment's pause-on-failure breaker sees each failure once.
+
+## Related
+
+- **Siblings**: [`vertex_agent_admin`](./vertex_agent_admin.md) (creates the custom agents this node runs), [`vertexCloudTool`](./vertexCloudTool.md) (the display nodes this node mints).
+- **Dedicated-path peers**: [`rlmAgent`](./rlm_agent.md), [`claudeCodeAgent`](./claude_code_agent.md); generic pattern in [`_pattern.md`](./_pattern.md) (not followed here).
+- **Architecture docs**: [agent_architecture.md](../../agent_architecture.md), [agent_delegation.md](../../agent_delegation.md) (blocking-wait contract, `TestDelegationWait`), [agent_context_flow.md](../../agent_context_flow.md), [workflow_ops_protocol.md](../../workflow_ops_protocol.md).
diff --git a/docs-internal/node-logic-flows/specialized_agents/webAgent.md b/docs-internal/node-logic-flows/specialized_agents/web_agent.md
similarity index 100%
rename from docs-internal/node-logic-flows/specialized_agents/webAgent.md
rename to docs-internal/node-logic-flows/specialized_agents/web_agent.md
diff --git a/docs-internal/node-logic-flows/stripe/stripeAction.md b/docs-internal/node-logic-flows/stripe/stripeAction.md
new file mode 100644
index 00000000..dc9d23d2
--- /dev/null
+++ b/docs-internal/node-logic-flows/stripe/stripeAction.md
@@ -0,0 +1,138 @@
+# Stripe (`stripeAction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | payments (class `group = ("payments", "tool")`) |
+| **Backend handler** | [`server/nodes/stripe/stripe_action.py`](../../../server/nodes/stripe/stripe_action.py) (`StripeActionNode`, on `ActionNode`); installer [`_install.py`](../../../server/nodes/stripe/_install.py); credential [`_credentials.py`](../../../server/nodes/stripe/_credentials.py) |
+| **Tests** | [`server/tests/nodes/test_stripe_plugin.py`](../../../server/tests/nodes/test_stripe_plugin.py) |
+| **Skill (if any)** | [`server/skills/payments_agent/stripe-skill/SKILL.md`](../../../server/skills/payments_agent/stripe-skill/SKILL.md) (`allowed-tools: "stripe_action"`) |
+| **Dual-purpose tool** | yes - tool name `stripe_action` |
+
+## Purpose
+
+Run one Stripe CLI command exactly as it would be typed after `stripe ` and
+return the CLI's JSON response. There are no per-resource operations: the
+CLI does its own argument parsing, validation and error reporting, so every
+Stripe resource (customers, charges, payment_intents, refunds, invoices,
+subscriptions, `trigger <event>` and the rest) works through the single
+`command` string. Authentication is the CLI's own `stripe login` state.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Declared, but `hideInputHandle` is auto-set (`usable_as_tool = True`, class does not declare `hide_input_handle`) |
+
+## Parameters
+
+`extra="ignore"` on the model.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `command` | string | `""` | yes (checked at runtime) | - | The Stripe CLI command after `stripe `, split with `shlex.split` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `StripeActionOutput`; `hideOutputHandle` auto-set |
+| `output-tool` | - | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+`extra="allow"`. The operation returns a dict, so `_serialize_result`
+validates it against the model and dumps with `exclude_unset`.
+
+```ts
+{
+ command: string; // the trimmed command that ran
+ success: true;
+ result: unknown | null; // json.loads(stdout), or null when stdout is not JSON
+ stdout: string; // raw stdout, ALWAYS present alongside result (unlike the _shape convention of the other CLI nodes)
+ error?: string; // declared on the model but never populated by the operation
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[params.command.strip] --> B{empty}
+ B -- yes --> E1[RuntimeError command is required]
+ B -- no --> C[ensure_stripe_cli]
+ C -- raised --> E2[RuntimeError Stripe CLI install failed]
+ C -- path --> D[run_cli_command binary, argv=shlex.split cmd, default timeout 30s, inherited env, no cwd]
+ D -- exit != 0 or timeout --> E3[RuntimeError result.error or Stripe CLI invocation failed]
+ D -- ok --> F[Return command, success, result=parsed JSON or null, stdout]
+```
+
+## Decision Logic
+
+- **Validation**: blank `command` raises `RuntimeError`, NOT
+ `NodeUserError`. All three failure paths in this node raise
+ `RuntimeError`, so `BaseNode.execute` treats them as unexpected bugs:
+ `logger.exception` with a full traceback and a generic error envelope
+ rather than the one-line WARN contract the other CLI nodes use.
+- **Binary resolution** (`ensure_stripe_cli`): in-process cache, then
+ `shutil.which("stripe")` (a system install is preferred), then a
+ previously downloaded copy at `<DATA_DIR>/packages/stripe/bin/stripe(.exe)`,
+ then a download of the pinned `1.40.9` release from GitHub releases
+ (`httpx`, 120 s, member extracted from the zip / tar.gz, `chmod +x` on
+ POSIX) under an install lock.
+- **No credential injection**: `run_cli_command` is called without
+ `credential=`, so no `--api-key` is appended. The CLI reads its own
+ `config.toml` (`$XDG_CONFIG_HOME/stripe/` or `~/.config/stripe/`).
+- **Timeout**: the `run_cli_command` default of 30 s - the node passes none.
+ On timeout the process tree is killed and the error is
+ `"<binary> timed out (30.0s)"`.
+- **Result parsing**: `run_cli_command` runs `json.loads` on the whole
+ stdout; non-JSON output leaves `result` as `null` with the text in
+ `stdout`.
+
+## Side Effects
+
+- **Subprocess**: one `stripe` process per execution, inheriting the
+ server's environment and cwd (no `env`, no `cwd` override, so ambient
+ Stripe CLI env vars apply per the CLI's own rules).
+- **Install**: first use may download ~12 MB from
+ `github.com/stripe/stripe-cli/releases` into
+ `<DATA_DIR>/packages/stripe/bin/`.
+- **External API calls**: whatever the Stripe CLI performs for the command;
+ `trigger <event>` causes Stripe to deliver a synthetic webhook to the
+ `stripe listen` daemon (see [`stripeReceive`](./stripeReceive.md)).
+- **Cost metadata**: `cost={"service": "stripe", "action": "run", "count": 1}`.
+- **Broadcasts / DB writes**: none beyond the standard node status.
+
+## External Dependencies
+
+- **Credentials**: `StripeCredential` (`id = "stripe"`, `auth = "custom"`).
+ `resolve()` returns only `{"stripe_webhook_secret": ...}` when the listen
+ daemon has captured one; the action node never reads it. Login state is
+ the CLI's `config.toml`, written by the `stripe_login` WS handler
+ (`stripe login --non-interactive` then `--complete <url>`); the modal badge
+ is the synthetic `cli-managed` marker OAuth row.
+- **Services**: Stripe API via the CLI; GitHub releases for the install.
+- **Python packages**: `httpx` (installer), `pydantic`;
+ `services.events.run_cli_command`.
+- **Environment variables**: `XDG_CONFIG_HOME` (CLI config location);
+ anything the Stripe CLI itself honours.
+
+## Edge cases & known limits
+
+- No `ui_hints`: unlike the other CLI nodes there is no
+ `outputMode: "terminal"`, so text `stdout` renders through the markdown
+ path in the output panel.
+- `stdout` always ships next to `result`, duplicating the JSON as a string.
+- Long-running commands (large `list --limit`, slow network) hit the 30 s
+ default and are reported as a generic failure.
+- `annotations = {"destructive": False, ...}` although refunds, deletes and
+ `trigger` mutate account state.
+- `shlex.split` is POSIX-mode: Windows paths and unbalanced quotes inside
+ `command` raise `ValueError` (generic branch).
+- One Stripe account per install (single CLI config file).
+
+## Related
+
+- **Skills using this as a tool**: [stripe-skill](../../../server/skills/payments_agent/stripe-skill/SKILL.md)
+- **Sibling**: [`stripeReceive`](./stripeReceive.md) - the webhook trigger the skill pairs it with
+- **Architecture docs**: [Stripe Service](../../stripe_service.md), [Plugin System](../../plugin_system.md)
diff --git a/docs-internal/node-logic-flows/stripe/stripeReceive.md b/docs-internal/node-logic-flows/stripe/stripeReceive.md
new file mode 100644
index 00000000..4eaff6e0
--- /dev/null
+++ b/docs-internal/node-logic-flows/stripe/stripeReceive.md
@@ -0,0 +1,178 @@
+# Stripe Receive (`stripeReceive`)
+
+| Field | Value |
+|------|-------|
+| **Category** | payments / trigger (class `group = ("payments", "trigger")`) |
+| **Backend handler** | [`server/nodes/stripe/stripe_receive.py`](../../../server/nodes/stripe/stripe_receive.py) (`StripeReceiveNode`, on `WebhookTriggerNode`); daemon + webhook plumbing in [`_source.py`](../../../server/nodes/stripe/_source.py) (`StripeListenSource`, `StripeWebhookSource`); framework base [`services/events/triggers.py`](../../../server/services/events/triggers.py), [`services/events/webhook.py`](../../../server/services/events/webhook.py), verifier [`services/events/verifiers/stripe.py`](../../../server/services/events/verifiers/stripe.py) |
+| **Tests** | [`server/tests/nodes/test_stripe_plugin.py`](../../../server/tests/nodes/test_stripe_plugin.py) |
+| **Skill (if any)** | none as a tool (the [stripe-skill](../../../server/skills/payments_agent/stripe-skill/SKILL.md) teaches it in prose; its `allowed-tools` names only `stripe_action`) |
+| **Dual-purpose tool** | no (trigger) |
+
+## Purpose
+
+Fire a workflow when Stripe delivers a webhook event. A supervised
+`stripe listen` daemon forwards every event for the logged-in account to
+`POST /webhook/stripe`; the source verifies the `Stripe-Signature` header
+against the `whsec_` secret captured from the daemon's own stderr, shapes the
+payload into a `WorkflowEvent` of type `stripe.<event type>`, and hands it to
+the in-process event waiter. The node contributes the event-type glob, a
+livemode filter, a precondition that starts the daemon on demand, and the
+output reshape.
+
+## Inputs (handles)
+
+None - this is a trigger; it is the head of a run.
+
+## Parameters
+
+`StripeReceiveParams(BaseTriggerParams)`, `extra="ignore"`.
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `event_type_filter` | string | `all` | no | - | `all`, an exact Stripe type, or a `prefix.*` glob. `build_filter` prepends `stripe.` unless the value already starts with it, so users write `charge.*` |
+| `livemode_filter` | `all \| test \| live` | `all` | no | - | Extra filter read from `event.data.livemode` (see Decision Logic for why this does not work end-to-end) |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `StripeReceiveOutput` (the shaped dict from `shape_output`) |
+
+### Output payload (TypeScript shape)
+
+`extra="allow"`. All fields are `Optional` on the model.
+
+```ts
+{
+ event_id: string; // WorkflowEvent.id = Stripe evt_... id (empty string when the payload had none)
+ event_type: string; // WorkflowEvent.type with the "stripe." prefix stripped, e.g. "charge.succeeded"
+ created: number | null; // read from event.data - null in practice (see below)
+ livemode: boolean | null; // read from event.data - null in practice
+ api_version: string | null; // read from event.data - null in practice
+ request_id: string | null; // event.data.request.id or event.data.request - null in practice
+ account: string | null; // event.data.account, else the host part of WorkflowEvent.source ("acct_..." or "default")
+ data: object; // event.data.data when that is a dict, else event.data itself (= Stripe's data object {object, previous_attributes?})
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ L[stripe listen daemon: binary listen --forward-to http://localhost:PYTHON_BACKEND_PORT/webhook/stripe --print-secret] -- stderr whsec_ --> K[store_api_key stripe_webhook_secret]
+ L -- forwards --> W[POST /webhook/stripe]
+ W --> V{StripeCredential.resolve -> stripe_webhook_secret}
+ V -- missing --> R503[503 + Retry-After 5]
+ V -- ok --> H[StripeVerifier: t= and v1= HMAC-SHA256 hex over t.body]
+ H -- header missing / mismatch --> R400[400]
+ H -- ok --> J[json.loads body] -- invalid --> R400
+ J --> S[shape: id=evt id, type=stripe.type, source=stripe://account or default, time=created, data=payload.data or empty, subject=type]
+ S --> Q[source.receive: internal push queue] --> D[event_waiter.dispatch event]
+ D --> M{waiter.event_type == event.type}
+ M -- stripe.webhook vs stripe.charge.succeeded --> N[no match: waiter untouched]
+ subgraph canvas Run / legacy deploy
+ P[_check_precondition] -- daemon not started, not logged in --> E1[error Stripe not connected]
+ P -- daemon start failed --> E2[error Stripe daemon failed to start]
+ P -- ok --> G[event_waiter.register node_type=stripeReceive: event_type=stripe.webhook, filter=build_filter]
+ G --> A[await future] --> O[shape_output]
+ end
+```
+
+## Decision Logic
+
+- **Precondition** (`_check_precondition`, canvas Run only): if the listen
+ source is not `_started`, `has_credential()` (a filesystem sniff for
+ `_api_key` in the CLI's `config.toml`) must be true, else the run returns
+ the error "Stripe not connected. Add Stripe API key in Credentials and
+ connect." Then `source.start()` runs: `ensure_stripe_cli()`, the
+ `DaemonEventSource` credential gate, and `ProcessService.start(name=
+ "stripe-listen", workflow_id="_stripe", working_directory=daemons_dir())`.
+ A failed start returns "Stripe daemon failed to start: <error>". Deploying
+ a Stripe workflow is the demand signal for the daemon; the status refresh
+ never starts it.
+- **Signature verification fails closed**: no captured secret -> HTTP 503
+ with `Retry-After: 5`; missing header, missing `t=` / `v1=`, or no
+ matching `v1=` candidate -> HTTP 400. Multiple `v1=` values are accepted
+ (rotation).
+- **Filter** (`build_filter`): `event_type_filter` is normalised to
+ `stripe.<value>` and matched with `WorkflowEvent.matches_type` (exact, or
+ `prefix.*`; `all` / empty matches everything). `_extra_filter` returns
+ `None` for `livemode_filter=all`, otherwise a predicate comparing
+ `bool(event.data.get("livemode"))` with the target.
+- **Event-key mismatch (load-bearing)**: `StripeReceiveNode.event_type` is
+ derived by `WebhookTriggerNode.__init_subclass__` from
+ `StripeWebhookSource.type = "stripe.webhook"`, and that is the key
+ `event_waiter.register` stores on the waiter. `WebhookSource.handle`
+ dispatches the envelope, whose `type` is `stripe.<stripe type>`, and
+ `event_waiter.dispatch` selects waiters by exact equality
+ `w.event_type == event_type`. As written, a real delivery therefore never
+ resolves a `stripeReceive` waiter on either path. The node is NOT
+ registered with `register_canary_trigger_type` (no call in
+ `nodes/stripe/`), so deployment rides the legacy
+ `TriggerManager.setup_event_trigger` collector, which registers through
+ the same `event_waiter.register` and inherits the same key.
+- **Data-shape mismatch**: `StripeWebhookSource.shape` stores only
+ `payload["data"]` (Stripe's `{object, previous_attributes?}`) in
+ `WorkflowEvent.data`, but `shape_output` and the livemode predicate read
+ `created`, `livemode`, `api_version`, `request` and `account` from that
+ same `event.data`. Those are top-level Stripe event fields, so they resolve
+ to `None`; `livemode_filter=live` rejects every event and
+ `livemode_filter=test` accepts every event; the output `data` falls
+ through to `event.data` itself. The unit tests exercise `shape` and
+ `shape_output` with different envelope shapes, so each passes in isolation.
+- **Fallbacks**: `created` missing or non-integer -> `time = now(UTC)`;
+ `account` missing -> `source = "stripe://default"`; missing `id` -> empty
+ string; missing `type` -> `stripe.unknown`.
+
+## Side Effects
+
+- **Subprocess**: the `stripe listen` daemon (`StripeListenSource`,
+ `process_name = "stripe-listen"`, `workflow_namespace = "_stripe"`, cwd
+ `<DATA_DIR>/daemons/`), supervised by `ProcessService`, which logs its
+ stdout / stderr and broadcasts them to the Terminal tab. `--forward-to`
+ uses `Settings().port` (`PYTHON_BACKEND_PORT`).
+- **Database writes**: `auth_service.store_api_key("stripe_webhook_secret",
+ <whsec_...>, models=[])` whenever a `whsec_` token appears on the daemon's
+ stderr (fire-and-forget task).
+- **Broadcasts**: `update_node_status(..., "waiting", {"event_type":
+ "stripe.webhook", "waiter_id": ...})` from the trigger manager / executor;
+ `make_status_refresh` mirrors `source.status()` plus login state into
+ `broadcaster._status["stripe"]` under broadcast type `stripe_status`.
+- **HTTP**: `POST /webhook/stripe` answered by the router after
+ `handle()`; the source's `receive()` also enqueues the event on its
+ internal push queue (nothing consumes that queue for this source).
+- **WS handlers**: `stripe_connect` / `stripe_disconnect` /
+ `stripe_reconnect` / `stripe_status` (lifecycle factory, `stripe_status`
+ overridden to add `logged_in` / `connected`), `stripe_login`,
+ `stripe_logout`, `stripe_trigger`.
+
+## External Dependencies
+
+- **Credentials**: `StripeCredential` (`id = "stripe"`, `auth = "custom"`) -
+ `resolve()` exposes only `stripe_webhook_secret`; login state is the CLI's
+ own `config.toml` (`$XDG_CONFIG_HOME/stripe/` or `~/.config/stripe/`).
+- **Services**: the Stripe CLI (system PATH preferred, else pinned `1.40.9`
+ download into `<DATA_DIR>/packages/stripe/bin/`); Stripe's webhook
+ delivery through `stripe listen`.
+- **Python packages**: `pydantic`, stdlib `hmac` / `hashlib`, `fastapi`.
+- **Environment variables**: `PYTHON_BACKEND_PORT` (via `Settings().port`),
+ `XDG_CONFIG_HOME`.
+
+## Edge cases & known limits
+
+- `TRIGGER_START_TO_CLOSE` (24 h) bounds the Temporal activity for a
+ canvas Run; there is no shorter wait timeout.
+- Event ids mirror Stripe's `evt_` ids, so retried deliveries carry the same
+ `WorkflowEvent.id`; no dedup is performed in this plugin.
+- Secret race: events forwarded before the `whsec_` line is captured get a
+ 503 and are retried by Stripe / the CLI.
+- One account per install; the daemon is a single global process.
+- No auto-restart on daemon crash - status shows disconnected until the user
+ reconnects.
+- The `stripe_service.md` request-flow diagram documents `data=payload`
+ (the full event); the code stores `payload["data"]`.
+
+## Related
+
+- **Sibling**: [`stripeAction`](./stripeAction.md) (`trigger <event>` is the easiest way to exercise this node)
+- **Architecture docs**: [Stripe Service](../../stripe_service.md), [Event Waiter System](../../event_waiter_system.md), [Event Framework](../../event_framework.md)
diff --git a/docs-internal/node-logic-flows/web_automation/browserHarness.md b/docs-internal/node-logic-flows/web_automation/browserHarness.md
new file mode 100644
index 00000000..1165ec57
--- /dev/null
+++ b/docs-internal/node-logic-flows/web_automation/browserHarness.md
@@ -0,0 +1,146 @@
+# Browser Harness (`browserHarness`)
+
+| Field | Value |
+|------|-------|
+| **Category** | browser / tool (palette group `browser`; sibling of the stable `browser` node, not a replacement) |
+| **Backend handler** | [`server/nodes/browser/browser_harness/__init__.py::BrowserHarnessNode.dispatch`](../../../server/nodes/browser/browser_harness/__init__.py) (dispatch via `BaseNode.execute()` + `@Operation("dispatch")`; plugin folder: [`_service.py`](../../../server/nodes/browser/browser_harness/_service.py) subprocess wrapper + daemon shutdown hook, [`_install.py`](../../../server/nodes/browser/browser_harness/_install.py) uv-tool installer; screenshot persistence shared with `browser` in [`nodes/browser/_screenshots.py`](../../../server/nodes/browser/_screenshots.py)) |
+| **Tests** | [`server/tests/nodes/test_browser_harness.py`](../../../server/tests/nodes/test_browser_harness.py) (`TestBrowserHarnessNode`, `TestBrowserHarnessService`) |
+| **Skill (if any)** | [`server/skills/web_agent/browser-harness-skill/SKILL.md`](../../../server/skills/web_agent/browser-harness-skill/SKILL.md) (`allowed-tools: browserHarness`) |
+| **Dual-purpose tool** | yes - tool name `browser_harness` (`usable_as_tool = True`) |
+
+## Purpose
+
+Drives the user's **real, logged-in Chrome** over raw CDP through the
+`browser-harness` CLI (browser-use/browser-harness, PyPI, alpha). The
+upstream driving model is "the LLM writes Python against ~25 pre-imported
+helpers", so the primary operation is `run_python`: the snippet is piped
+verbatim to the CLI's stdin and executed against helpers such as
+`goto_url`, `click_at_xy`, `capture_screenshot`, `js`, `fill_input`,
+`wait_for_load`, `list_tabs`, `page_info`. The other operations are
+one-helper shortcuts generated as Python text, plus `doctor`, which runs the
+CLI's own Chrome/CDP diagnosis. Reach for it when a task needs the user's
+own profile/session state, canvas- or shadow-DOM-heavy or bot-hostile
+sites, or raw CDP; default to the accessibility-tree `browser` node
+otherwise.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data for template substitution into `code` / `url` / `expression` |
+| `output-tool` (source, synthesized) | tools | no | The class declares only `input-main` + `output-main`; because `usable_as_tool = True` and neither `hide_input_handle` nor `hide_output_handle` is declared, `BaseNode.__init_subclass__` flags both canvas handles hidden and `_metadata_dict` appends an `output-tool` handle to the NodeSpec so the node can be wired to an agent's `input-tools` |
+
+## Parameters
+
+Params model `BrowserHarnessParams` (`extra="ignore"`):
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | enum `run_python` \| `goto` \| `screenshot` \| `js` \| `tabs` \| `doctor` | `run_python` | no | - | `run_python` executes a snippet against the harness helpers; the rest are single-helper shortcuts; `doctor` diagnoses the Chrome/CDP connection |
+| `code` | string (code editor, 8 rows) | `""` | no (but an empty snippet raises `NodeUserError` in `run_code`) | `operation: [run_python]` | Python for `run_python`. Helpers are pre-imported. Print a JSON object as the final line for structured output |
+| `url` | string | `""` | no (required by `goto`, enforced in `_code_for`) | `operation: [goto]` | URL to open |
+| `expression` | string (4 rows) | `""` | no (required by `js`, enforced in `_code_for`) | `operation: [js]` | JavaScript to evaluate in the page |
+| `full_page` | boolean | `false` | no | `operation: [screenshot]` | Capture the full scrollable page |
+| `timeout` | integer, `ge=5, le=600` | `60` | no | - | Script timeout in seconds (applies to every operation except `doctor`, which is fixed at 30 s) |
+
+Generated Python per shortcut (`_code_for`; user strings are embedded with
+`repr()` so quotes/backslashes cannot break out of the generated source):
+
+| Operation | Generated snippet |
+|-----------|-------------------|
+| `goto` | `goto_url(<url!r>)` / `wait_for_load()` / `print(page_info())` |
+| `screenshot` | `p = capture_screenshot(full=<bool>)` / `print(p)` |
+| `js` | `print(js(<expression!r>))` |
+| `tabs` | `print(list_tabs())` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `BrowserHarnessOutput` (`extra="allow"`) wrapped in the standard `{success, result, execution_time}` envelope; as a tool the envelope is unwrapped to the flat object |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ operation: 'run_python' | 'goto' | 'screenshot' | 'js' | 'tabs' | 'doctor';
+ data: {
+ output: string; // full stdout (stderr when stdout was empty, e.g. doctor); capped at 100_000 chars + "...(truncated)"
+ result?: unknown; // present only when the LAST non-empty stdout line parses as JSON
+ screenshot?: FileRef; // screenshot op only: serialized workspace FileRef (kind "image") when the printed path was persisted
+ };
+}
+```
+
+`doctor` always returns `{ output: string }` — exit code 1 is a report, not
+an error.
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[dispatch op] --> B[get_browser_harness_service]
+ B -- binary missing and uv install failed / uv absent --> E1[NodeUserError: uv required]
+ B -- ok --> C{operation}
+ C -- doctor --> D[svc.doctor: run CLI 'doctor', 30 s, exit code ignored]
+ C -- other --> F[_code_for: run_python passes code verbatim, shortcuts generate one-liners]
+ F -- goto without url / js without expression / unknown op --> E2[NodeUserError]
+ F --> G[svc.run_code: empty code -> NodeUserError]
+ G --> H[acquire _operation_lock - one script at a time]
+ H --> I[subprocess.run binary, stdin=code, env + BH_RUNTIME_DIR/BH_TMP_DIR, timeout]
+ I -- TimeoutExpired --> E3[NodeUserError: timed out after N s]
+ I -- FileNotFoundError --> E4[NodeUserError: binary vanished]
+ I -- exit != 0 and stderr matches Chrome hints --> E5[NodeUserError: CDP guidance + tail of stderr]
+ I -- exit != 0 and 'traceback'/'error' in stderr --> E6[NodeUserError: script failed]
+ I -- exit != 0 otherwise --> E7[RuntimeError: exited N]
+ I -- exit 0 --> J[_shape_output: last line JSON -> result, always output]
+ D --> K
+ J --> K{operation == screenshot and data is dict?}
+ K -- yes --> L[persist_screenshot_file: last stdout line must be an absolute path contained under DATA_DIR/daemons/browser-harness, .png/.jpg/.jpeg/.webp, 128 B..25 MiB]
+ L -- persisted --> M[data.screenshot = FileRef]
+ L -- any failure --> N[warning logged, raw output kept]
+ K -- no --> O[BrowserHarnessOutput operation + data]
+ M --> O
+ N --> O
+```
+
+## Decision Logic
+
+- **Validation**: `get_browser_harness_service()` returns `None` when `uv` is not on PATH or `uv tool install` fails (one `NodeUserError`); `goto` without `url` and `js` without `expression` raise `NodeUserError` before any subprocess; empty `code` raises inside `run_code`; an unknown `operation` (unreachable through the Literal) raises `NodeUserError`.
+- **Branches**: `doctor` bypasses `_code_for` entirely and calls the CLI with a `doctor` argv and no stdin, `check=False`; every other operation is a stdin script. The screenshot FileRef branch runs only when `data` is a dict with at least one non-empty output line — the printed path is treated as untrusted process output and must resolve under the harness runtime dir.
+- **Fallbacks**: `_run_sync` returns stderr when stdout is empty (diagnostic verbs write to stderr); `_shape_output` falls back to `{output}` when the last line is not JSON.
+- **Error paths**: stderr containing any of `devtoolsactiveport`, `unreachable`, `is the dedicated automation chrome running`, `chrome://inspect`, `no browser connection`, `connection refused` maps to the CDP guidance `NodeUserError`; stderr containing `traceback` or `error` maps to "script failed" (`NodeUserError`); anything else is a `RuntimeError` (full traceback in the operator log). Cancellation of the awaiting task does **not** release `_operation_lock` until the subprocess finishes (`_to_thread_until_complete`), so a cancelled script cannot overlap the next one on the single daemon/CDP socket.
+
+## Side Effects
+
+- **Database writes**: none from the node (no `cost=` on the operation, no usage tracking). A persisted screenshot writes a file only, no row.
+- **Broadcasts**: none beyond the generic `node_status` updates `BaseNode.execute()` emits.
+- **External API calls**: none directly; the CLI talks to Chrome over CDP.
+- **File I/O**: first use installs into `<DATA_DIR>/packages/browser-harness/tools/` (uv tool venv) and `.../bin/browser-harness[.exe]`; every spawn creates `<DATA_DIR>/daemons/browser-harness/` and `.../tmp/` and pins `BH_RUNTIME_DIR` / `BH_TMP_DIR` there (daemon pid/port/sock, screenshots, daemon log never land in `~/.config/browser-harness`); `screenshot` copies the bytes into the run's workspace media subdir via `write_media(kind="image")` (no workspace on the run -> warning, not persisted).
+- **Subprocess**: `uv tool install --python 3.12 --upgrade browser-harness` (install), then one `browser-harness` CLI process per operation; the CLI auto-starts a detached daemon that holds the single CDP WebSocket and outlives the CLI. The `browser_harness` shutdown hook (`register_shutdown_hook`) reads `<BH_RUNTIME_DIR>/bu.pid` and `kill_tree`s it on FastAPI lifespan shutdown; missing/stale pid files are ignored.
+
+## External Dependencies
+
+- **Credentials**: none.
+- **Services**: `services.plugin.shutdown_hooks`, `services._supervisor.util.kill_tree`, `services.media.workspace.write_media` (through `_screenshots.py`), `core.paths.package_dir` / `daemons_dir`.
+- **Python packages**: `uv` on PATH (install-time only); `browser-harness` (PyPI, alpha; Python 3.12 pinned by the installer).
+- **Environment variables**: sets `BH_RUNTIME_DIR`, `BH_TMP_DIR` on every spawn and `UV_TOOL_DIR` / `UV_TOOL_BIN_DIR` during install; passes `BU_CDP_URL` / `BU_CDP_WS` through untouched (operator override for a dedicated automation Chrome). Chrome must be CDP-reachable: `BU_CDP_URL`/`BU_CDP_WS`, chrome://inspect remote debugging, or a Chrome started with `--remote-debugging-port` (the guidance text names port 9222 because that is the CLI's own probe default, not an OpenCompany port).
+- **Task queue**: `TaskQueue.BROWSER`. Annotations: `destructive`, `open_world`.
+
+## Edge cases & known limits
+
+- `run_python` executes agent-authored Python **outside** any sandbox with the user's real browser attached; annotations say `destructive + open_world` for that reason.
+- One script at a time per backend process (`asyncio.Lock`); parallel tool calls serialize, so a 600 s script blocks every other harness call.
+- `timeout` is ignored by `doctor` (fixed 30 s).
+- Output is capped at 100,000 characters; a snippet that prints large page text loses its trailing JSON line and `result` is then absent.
+- The structured `result` depends purely on the LAST non-empty stdout line parsing as JSON — an extra trailing `print` from the snippet silently demotes the result to `output`.
+- The stderr classification is heuristic: any non-zero exit whose stderr contains the substring `error` becomes a one-WARN-line `NodeUserError` even when the cause is a genuine harness bug.
+- The daemon's own Chrome discovery, IPC (AF_UNIX on POSIX, token-auth TCP loopback on Windows) and screenshot format are upstream behaviour; `full_page` is passed as `capture_screenshot(full=...)` and nothing else about the image is controlled here.
+- `screenshot` persists only when the harness printed an absolute path under `<DATA_DIR>/daemons/browser-harness`; a path anywhere else is refused (warning), so a harness build that writes elsewhere yields no `FileRef`.
+- Upgrades are not automatic once the binary exists: `browser_harness_binary_path` returns the existing binary without re-running `uv tool install --upgrade`.
+
+## Related
+
+- **Skills using this as a tool**: [`browser-harness-skill`](../../../server/skills/web_agent/browser-harness-skill/SKILL.md) (see -> act -> verify loop, helper reference, print-JSON-last convention).
+- **Other nodes that consume this output**: [`canvas`](../ai_tools/canvas.md) displays the persisted `data.screenshot` FileRef; [`browser`](./browser.md) is the stable sibling.
+- **Architecture docs**: [browser_harness.md](../../browser_harness.md), [media_transport.md](../../media_transport.md), [plugin_system.md](../../plugin_system.md).
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.md
index 82f27cfc..efd9f5c4 100644
--- a/docs-internal/node_allowlist.md
+++ b/docs-internal/node_allowlist.md
@@ -60,9 +60,7 @@ Re-enable: drop the entries. The hook + filters are forward-compatible with empt
## What's currently disabled
-| Domain | Why | Hidden from |
-|---|---|---|
-| `email` group + `email` credential category | Himalaya CLI dependency — complex install path, IMAP/SMTP config burden | Palette + credentials |
+Nothing is blocklisted. All four disable lists (`disabled_groups`, `disabled_nodes`, `disabled_credential_categories`, `disabled_skill_folders`) are empty in the shipped `server/config/node_allowlist.json`; the `email` group + credential category that this section once listed as disabled are no longer blocked. The only active list is `enabled_nodes` — the positive allowlist that decides what normal mode shows (dev/pro mode bypasses it). Read the live entry count from the JSON rather than from this doc (51 at the time of writing).
Android service nodes are enabled and connect directly to an agent's
`input-tools` handle. The Android Agent, Android credential category, and
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index c62bd25a..758daa82 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -30,23 +30,25 @@ BaseNode (services/plugin/base.py)
└── ToolNode AI-invoked; flat return shape
```
-Single-file plugins inherit directly from `ActionNode` /
-`TriggerNode` / `ToolNode`. Self-contained plugin folders (telegram,
+Simple plugins inherit directly from `ActionNode` /
+`TriggerNode` / `ToolNode`. Rich plugin folders (telegram,
stripe) layer additional bases from `services.events` underneath them.
-## Five-minute recipe — single file
+## Five-minute recipe — one folder, one `__init__.py`
For nodes with no state, no daemon, no signed webhooks (the common
-case): the canonical single-file recipe code block lives in the
+case): the canonical recipe code block lives in the
cookbook — see
[`server/nodes/README.md` → Five-minute recipe](../server/nodes/README.md#five-minute-recipe).
-It is a single `server/nodes/<group>/<name>.py` declaring a
-`Credential` subclass, a `Params` model, an `Output` model, and one
-`ActionNode` subclass with `type` / `display_name` / `group` /
-`component_kind` / `handles` / `credentials` / `task_queue` /
-`usable_as_tool` / `Params` / `Output` plus one `@Operation` method.
-That's the entire node. On server restart it auto-registers, the
+It is a single folder `server/nodes/<group>/<name>/` whose
+`__init__.py` declares a `Credential` subclass, a `Params` model, an
+`Output` model, and one `ActionNode` subclass with `type` /
+`display_name` / `group` / `component_kind` / `handles` /
+`credentials` / `task_queue` / `usable_as_tool` / `Params` / `Output`
+plus one `@Operation` method. That's the entire node (the folder also
+holds `icon.svg` / `meta.json`, which is why a bare `.py` file is no
+longer the shape). On server restart it auto-registers, the
NodeSpec is emitted at `/api/schemas/nodes/<type>/spec.json`, and it
appears in the Component Palette under its first `group` entry.
diff --git a/docs-internal/node_panels.md b/docs-internal/node_panels.md
index 85a9a5cc..b8eb1fec 100644
--- a/docs-internal/node_panels.md
+++ b/docs-internal/node_panels.md
@@ -23,7 +23,8 @@ Files:
- [client/src/components/parameterPanel/InputSection.tsx](../client/src/components/parameterPanel/InputSection.tsx)
- [client/src/components/parameterPanel/MiddleSection.tsx](../client/src/components/parameterPanel/MiddleSection.tsx)
- [client/src/components/parameterPanel/OutputSection.tsx](../client/src/components/parameterPanel/OutputSection.tsx)
-- [client/src/components/output/OutputPanel.tsx](../client/src/components/output/OutputPanel.tsx) — drag source for connected outputs
+- [client/src/components/output/OutputPanel.tsx](../client/src/components/output/OutputPanel.tsx) — execution-results renderer (no edge walking; see §6)
+- [client/src/utils/parameterVisibility.ts](../client/src/utils/parameterVisibility.ts) — `shouldShowParameter` (shared by MiddleSection + ParameterRenderer)
- [client/src/components/ParameterRenderer.tsx](../client/src/components/ParameterRenderer.tsx) — universal widget
- [client/src/hooks/useParameterPanel.ts](../client/src/hooks/useParameterPanel.ts)
- [client/src/hooks/useDragVariable.ts](../client/src/hooks/useDragVariable.ts)
@@ -51,8 +52,11 @@ Files:
| Monitor (`teamMonitor`) | hidden | shown | hidden |
| Everything else | shown | shown | shown |
-`ParameterPanel.tsx` lines 119–122 compute `showInputSection` / `showOutputSection` and pass them
-to `ParameterPanelLayout`.
+The buckets are not frontend type lists: `ParameterPanel.tsx` (around lines 141–150) reads
+`hideInputSection` / `hideOutputSection` / `hideRunButton` straight off the node's backend
+NodeSpec `uiHints` and passes the derived flags to `ParameterPanelLayout`. A plugin that wants the
+Start / Skill / Monitor shape declares those hints itself (Wave 10.G.5); nothing in the client
+matches on `node.type`.
## 3. Template Variable Naming (drag-and-drop contract)
@@ -116,24 +120,34 @@ When ALL conditions match the parameter renders; otherwise it's hidden.
A parameter without `displayOptions.show` always renders.
-`MiddleSection.shouldShowParameter` (lines 59–81) implements this. The function is internal so
-tests assert it indirectly via component rendering — see
-[client/src/components/parameterPanel/__tests__/MiddleSection.test.tsx](../client/src/components/parameterPanel/__tests__/MiddleSection.test.tsx).
+`shouldShowParameter` in [client/src/utils/parameterVisibility.ts](../client/src/utils/parameterVisibility.ts)
+implements this. It was extracted out of `MiddleSection.tsx` so that `ParameterRenderer` (nested
+`collection` options, ~line 760) can share it and so tests can import it directly —
+[client/src/components/parameterPanel/__tests__/MiddleSection.test.tsx](../client/src/components/parameterPanel/__tests__/MiddleSection.test.tsx)
+exercises the pure function (array membership, scalar equality, AND across keys, type-coercion
+edges). `MiddleSection` applies it in its parameter filter (~line 187).
## 5. Connection Discovery (Input + Output)
-Both `InputSection` and `OutputPanel` walk the workflow's edges to figure out which other nodes
-are linked to the current one. They classify handles into two buckets:
+`InputSection` walks the workflow's edges to figure out which other nodes feed the current one
+(`OutputPanel` no longer does any edge walking — it only renders results). Its `isConfigHandle`
+helper (~line 258) classifies handles into two buckets:
| Handle bucket | Examples | Effect |
|---|---|---|
| Data flow | `input-main`, `input-chat`, `input-task`, `input-teammates` | shown as connected nodes |
-| Config / auxiliary | `input-memory`, `input-tools`, `input-skill`, `input-model` | hidden — they belong to the dedicated UI in `MiddleSection` |
-
-Plus a special case for **config nodes themselves** (e.g. `simpleMemory`, any node whose group
-includes `'memory'` or `'tool'`): when the user is viewing a config node, the panel inherits the
-parent agent's main inputs and labels them `(via Agent Name)` so the user can still drag those
-upstream variables into the config node's parameters.
+| Config / auxiliary | every other `input-*` — `input-context`, `input-tools`, `input-skill`, `input-model` | hidden on agents that declare `uiHints.hasSkills` — they belong to the dedicated UI in `MiddleSection` |
+
+`input-memory` is retired (RFC-0002): `normalize_workflow_graph` rewrites legacy `simpleMemory ->
+input-memory` edges into a Context node plus an ordinary `input-tools` edge, so the handle never
+reaches this code on a normalised graph.
+
+Plus a special case for **config nodes themselves**: a node is a config node when its NodeSpec
+carries `uiHints.isConfigNode === true` (auto-derived on the backend by `_derive_auto_ui_hints` for
+any plugin whose `group` contains `memory` or `tool`; `canvas` opts out explicitly). When the user is
+viewing one, the panel inherits the parent agent's main inputs and labels them `via <Agent Name>` so
+the user can still drag those upstream variables into the config node's parameters. The client never
+inspects group strings for this.
## 6. Output Display (`OutputSection`)
diff --git a/docs-internal/onboarding.md b/docs-internal/onboarding.md
index 4dc586bd..80faf799 100644
--- a/docs-internal/onboarding.md
+++ b/docs-internal/onboarding.md
@@ -2,9 +2,9 @@
## Overview
-The onboarding service provides a multi-step welcome wizard that appears after a user's first launch, guiding them through platform capabilities, key concepts, API key setup, UI layout, and getting started. It is database-backed, skippable, resumable, and replayable from Settings.
+The onboarding service provides a four-step welcome wizard that appears after a user's first launch: what OpenCompany is, how the canvas works, connecting an AI provider, and trying the shipped AI Assistant example. It is database-backed, skippable, resumable, and replayable from Settings. A separate, dismissable **Get Started checklist** (`GetStartedChecklist.tsx`) sits in the corner of the canvas after the wizard and tracks five first-session milestones.
-The frontend is **fully shadcn/ui + Tailwind** — antd was removed from `client/src/`. The wizard composes the project's `Modal` primitive, shadcn `Button` / `ActionButton` / `Card` / `Badge` / `Alert`, and `lucide-react` icons. The step progress indicator is a hand-rolled `<ol>` driven by node-role tokens (no antd `Steps`).
+The frontend is **fully shadcn/ui + Tailwind** — antd was removed from `client/src/`. The wizard composes the project's `Modal` primitive, shadcn `Button` / `ActionButton` / `Card` / `Badge` / `Alert` / `Skeleton`, and `lucide-react` icons. The step progress indicator is a hand-rolled `<ol>` driven by node-role tokens (no antd `Steps`).
## Architecture
@@ -21,10 +21,10 @@ The frontend is **fully shadcn/ui + Tailwind** — antd was removed from `client
│ │ └───────────────┬────────────────────────────────┘ │ │
│ │ │ │ │
│ │ STEPS array (single source of truth in wizard): │ │
-│ │ ┌───────┬───────┬───────┬──────────┬──────────┐ │ │
-│ │ │Step 0 │Step 1 │Step 2 │Step 3 │Step 4 │ │ │
-│ │ │Welcome│Concept│APIKey │Canvas │GetStarted│ │ │
-│ │ └───────┴───────┴───────┴──────────┴──────────┘ │ │
+│ │ ┌─────────┬──────────────┬─────────────────┬────────┐ │ │
+│ │ │Step 0 │Step 1 │Step 2 │Step 3 │ │ │
+│ │ │Welcome │How it works │Connect your AI │Try it │ │ │
+│ │ └─────────┴──────────────┴─────────────────┴────────┘ │ │
│ │ │ │
│ │ Modal (project primitive, Radix-backed) │ │
│ │ + <ol> progress stepper (Tailwind + role tokens) │ │
@@ -37,7 +37,7 @@ The frontend is **fully shadcn/ui + Tailwind** — antd was removed from `client
│ WebSocket (via TanStack Q) │ WebSocket
▼ ▼
┌──────────────────────────────────────────────────────────────┐
-│ server/routers/websocket.py │
+│ server/services/settings/handlers.py │
│ - get_user_settings → returns onboarding_completed, step │
│ - save_user_settings → persists onboarding_completed, step │
│ │
@@ -87,19 +87,21 @@ if "onboarding_step" not in columns:
```
client/src/
├── components/
-│ ├── onboarding/
-│ │ ├── OnboardingWizard.tsx # Main wizard modal orchestrator + STEPS SSOT + <ol> stepper
-│ │ ├── nodeRoleClasses.ts # Shared role→Tailwind-token map for step cards
-│ │ └── steps/
-│ │ ├── WelcomeStep.tsx # Step 0: Platform intro
-│ │ ├── ConceptsStep.tsx # Step 1: Nodes, Edges, Agents, Skills, Modes
-│ │ ├── ApiKeyStep.tsx # Step 2: AI provider key setup
-│ │ ├── CanvasStep.tsx # Step 3: UI layout tour
-│ │ └── GetStartedStep.tsx # Step 4: First workflow tips
-│ └── icons/
-│ └── AIProviderIcons.tsx # Provider SVG icons used by ApiKeyStep
+│ └── onboarding/
+│ ├── OnboardingWizard.tsx # Wizard modal orchestrator + STEPS SSOT + <ol> stepper
+│ ├── GetStartedChecklist.tsx # Post-wizard corner checklist (collapsible, dismissable)
+│ ├── getStartedItems.ts # The five checklist milestones + EXAMPLE_WORKFLOW_NAMES
+│ ├── aiProviderLinks.ts # FEATURED_AI_PROVIDERS: hint + key-page URL per provider id
+│ ├── nodeRoleClasses.ts # Shared role→Tailwind-token map for step cards
+│ ├── steps/
+│ │ ├── WelcomeStep.tsx # Step 0: what OpenCompany is, 2×2 feature grid
+│ │ ├── HowItWorksStep.tsx # Step 1: blocks, agents, chat; Normal/Dev switch
+│ │ ├── ConnectAIStep.tsx # Step 2: provider tiles from the live catalogue
+│ │ └── TryItStep.tsx # Step 3: three-step recipe for the AI Assistant example
+│ └── __tests__/ # ConnectAIStep, GetStartedChecklist, HowItWorksStep, OnboardingWizard
└── hooks/
- └── useOnboarding.ts # State management + TanStack-Query persistence
+ ├── useOnboarding.ts # Wizard state + TanStack-Query persistence
+ └── useGetStarted.ts # Checklist state (which milestones are done, dismissed)
```
## Components
@@ -113,7 +115,7 @@ Custom hook managing the full onboarding lifecycle. Persistence rides the **TanS
```typescript
export const useOnboarding = (
reopenTrigger?: number,
- totalSteps: number = 5, // DEFAULT_TOTAL_STEPS; caller passes STEPS.length
+ totalSteps: number = DEFAULT_TOTAL_STEPS, // 4; the wizard passes STEPS.length
) => {
// Returns (spread of OnboardingState + actions):
// - isVisible: boolean - Whether wizard should render
@@ -130,7 +132,7 @@ export const useOnboarding = (
```
**Key behaviors**:
-- `totalSteps` is a **parameter** (default 5). The wizard owns the step list and passes `STEPS.length`, so the hook never hardcodes the count — it uses `totalSteps` only to detect last-step completion in `nextStep`.
+- `totalSteps` is a **parameter**. The wizard owns the step list and passes `STEPS.length`, so the hook never hardcodes the count — it uses `totalSteps` only to detect last-step completion in `nextStep`. The default only matters if a caller omits it; it matches the shipped wizard.
- Hydrates UI state from `settingsQuery.data` on `isSuccess`: reads `onboarding_completed` / `onboarding_step`. Visibility flips only on first hydration (`prev.hasChecked ? prev.isVisible : !completed`) so a user-closed wizard does not re-open on later query refetches.
- Each navigation (`nextStep` / `prevStep` / `skip` / `complete`) calls `saveSettings.mutate({ onboarding_step, onboarding_completed })` to persist progress.
- Query errors surface as a non-blocking "checked" state (`isLoading=false, hasChecked=true`) so the app continues even if the round-trip failed.
@@ -145,16 +147,16 @@ export const useOnboarding = (
|------|------|-------------|
| `onOpenCredentials` | `() => void` | Opens CredentialsModal (passed from Dashboard) |
| `reopenTrigger` | `number?` | Incrementing counter triggers wizard reopen |
+| `onFinish` | `() => void?` | Called after the last step's button completes the wizard; the Dashboard opens the AI Assistant example and focuses chat. Never called on skip or modal close. |
**`STEPS` is the single source of truth.** The wizard declares a module-scope `STEPS` array of `{ title, render }` entries. Its `.length` feeds the hook's `totalSteps`, the progress indicator renders one node per entry, and the active step's `render` is dispatched by index. Adding a step is a one-line edit to this array.
```typescript
const STEPS = [
- { title: 'Welcome', render: () => <WelcomeStep /> },
- { title: 'Concepts', render: () => <ConceptsStep /> },
- { title: 'API Keys', render: ({ onOpenCredentials }) => <ApiKeyStep onOpenCredentials={onOpenCredentials} /> },
- { title: 'Canvas', render: () => <CanvasStep /> },
- { title: 'Get Started', render: () => <GetStartedStep /> },
+ { title: 'Welcome', render: () => <WelcomeStep /> },
+ { title: 'How it works', render: () => <HowItWorksStep /> },
+ { title: 'Connect your AI', render: ({ onOpenCredentials }) => <ConnectAIStep onOpenCredentials={onOpenCredentials} /> },
+ { title: 'Try it', render: () => <TryItStep /> },
];
```
@@ -163,30 +165,35 @@ const STEPS = [
- Progress indicator: a hand-rolled `<ol>` of step pills. Each pill is a rounded number/`Check` (lucide) badge with one of three statuses — `completed` (filled `bg-primary text-primary-foreground`), `active` (`border-primary text-primary`), `upcoming` (`border-border text-muted-foreground`) — joined by a connector `<div>` (`bg-primary` once passed, else `bg-border`). No antd `Steps`.
- Step content rendered via `STEPS[safeIndex].render({ onOpenCredentials })` inside a scrollable `max-h-[calc(95vh-200px)]` container.
- Footer: shadcn `Button variant="ghost"` "Skip for now" (left) | `Button variant="outline"` "Back" (shown when `currentStep > 0`) + an `ActionButton` on the right.
-- The right-side primary button uses **`ActionButton` intents**, not raw colour hex: `<ActionButton intent="tools">` for "Next" (with `ArrowRight`), `<ActionButton intent="run">` for the final "Start Building" (with `Check`). The pre-antd-removal dracula-purple/green hardcoding is gone.
+- The right-side primary button uses **`ActionButton` intents**, not raw colour hex: `<ActionButton intent="tools">` for "Next" (with `ArrowRight`), `<ActionButton intent="run">` for the final "Open AI Assistant" (with `MessageCircle`), which calls `complete()` and then `onFinish`.
- Only renders when `isVisible && hasChecked && !isLoading`.
### Node-role token map
**Location**: `client/src/components/onboarding/nodeRoleClasses.ts`
-`NODE_ROLE_CLASSES` maps a `NodeRole` (`model | skill | agent | workflow | trigger`) to the matching `--node-X` triplet (`{ card: 'bg-node-X-soft border-node-X-border', text: 'text-node-X' }`). `ConceptsStep` and `GetStartedStep` key their card surfaces off this so the cards track every theme with **no opacity arithmetic at the call site**.
+`NODE_ROLE_CLASSES` maps a `NodeRole` (`model | skill | agent | workflow | trigger`) to the matching `--node-X` triplet (`{ card: 'bg-node-X-soft border-node-X-border', text: 'text-node-X' }`). Every step keys its card surfaces off this so the cards track every theme with **no opacity arithmetic at the call site**.
### Step Components
-All steps are shadcn/Tailwind compositions using `lucide-react` icons (`Card` / `CardContent`, `Badge`, `Alert` / `AlertDescription`, `Button`, plus role tokens). No antd, no `@ant-design/icons`.
+All steps are shadcn/Tailwind compositions using `lucide-react` icons. No antd, no `@ant-design/icons`. The copy is deliberately non-technical (blocks, agents, chat), not node-type vocabulary.
-| Step | Component | Title | Purpose | Primitives used |
-|------|-----------|-------|---------|-----------------|
-| 0 | `WelcomeStep` | Welcome to OpenCompany | Platform intro + 2×2 feature grid | `Card` / `CardContent`, lucide `Rocket` / `Plug` / `Move` / `Zap`, `bg-node-agent-soft` |
-| 1 | `ConceptsStep` | Key Concepts | Nodes, Edges, AI Agents, Skills & Tools, Normal vs Dev Mode | role-token cards via `NODE_ROLE_CLASSES`, lucide `LayoutGrid` / `GitBranch` / `Bot` / `Wrench` / `ArrowLeftRight` |
-| 2 | `ApiKeyStep` | API Key Setup | Provider list + "Open Credentials" button | shadcn `Button`, `Alert variant="info"`, `AIProviderIcons`, lucide `Key` / `ExternalLink` |
-| 3 | `CanvasStep` | Canvas Tour | Visual UI layout diagram + keyboard shortcuts | `Badge`, role-token region tints, lucide `Layout` / `Wrench` / `Terminal` |
-| 4 | `GetStartedStep` | Get Started | Example workflows, quick recipe, tips | `Card` / `CardContent`, `Badge`, role-token cards, lucide `Play` / `FlaskConical` / `BookOpen` / `Settings` |
+| Step | Component | Heading | Purpose | Notable data sources |
+|------|-----------|---------|---------|----------------------|
+| 0 | `WelcomeStep` | Build your own AI team | Platform intro + 2×2 feature grid (agents, drag-and-drop, bring your AI, local and private) | static; `Card` / `CardContent`, role-token cards |
+| 1 | `HowItWorksStep` | See how it works | Three ideas: snap blocks together, agents do the thinking, chat to make it go; explains the Normal / Dev toolbar switch | `useNodeGroups()` — the Normal-mode group labels render live as `Badge`s |
+| 2 | `ConnectAIStep` | Connect your AI (or "You're connected") | Featured provider tiles with "Get a key" links, the remaining AI providers as chips, and the Connect / Manage button | `useCatalogueQuery()` for name, icon and `stored` state; `FEATURED_AI_PROVIDERS` for hint + key URL |
+| 3 | `TryItStep` | Say hello to your first agent | Three-step recipe (open AI Assistant, press Start, say hello) plus "more to explore" cards for Claude Assistant and AI Employee | static |
-**ApiKeyStep** accepts an `onOpenCredentials` prop to link to the existing CredentialsModal without duplicating key input logic. It lists six providers (OpenAI, Anthropic, Google, Groq, OpenRouter, Cerebras) with brand icons from `client/src/components/icons/AIProviderIcons.tsx` (imported as `../../icons/AIProviderIcons`), and closes with an `Alert variant="info"` noting keys can be changed later from the toolbar.
+**ConnectAIStep** takes an `onOpenCredentials` prop so it links to the existing CredentialsModal without duplicating key input. Everything about a provider except its marketing hint and key-page URL comes from the live credential catalogue: `FEATURED_AI_PROVIDERS` (`aiProviderLinks.ts`) lists only `{ id, hint, keyUrl }` for openai, anthropic and gemini, and the step joins that to `useCatalogueQuery().providers` filtered to `category === 'ai'`. Providers not featured render as a chip row with a note that Ollama and LM Studio run locally. While the catalogue loads it shows three `Skeleton` tiles; once any AI provider is `stored` the heading, button label and closing `Alert` all switch to the connected variant.
-**CanvasStep** renders a miniature UI-region diagram whose tints map node groups to regions: toolbar→`workflow`, sidebar→`model`, canvas→`agent`, palette→`skill`, console→`trigger`, each via the `--node-X-soft` / `text-node-X` tokens. The shortcut list (`Ctrl+S` Save, `F2` Rename node, `Delete` Remove node, `Ctrl+C` Copy node) renders as `Badge variant="outline"` mono chips.
+**HowItWorksStep** reads `useNodeGroups()` and renders the labels of every group whose `visibility` is `normal` or `all`, so the "Normal shows just the AI blocks" sentence stays true as groups are added.
+
+### Get Started checklist
+
+**Location**: `client/src/components/onboarding/GetStartedChecklist.tsx`, state in `client/src/hooks/useGetStarted.ts`, items in `getStartedItems.ts`.
+
+A fixed-position card (bottom right, above the console) that appears after the wizard and tracks five milestones: workspace set up (auto-complete), add an AI key, chat with the AI Assistant, build your own workflow (told apart from editing a shipped example via `EXAMPLE_WORKFLOW_NAMES`), and try a theme. Rows flagged `actionable` take a click handler from the Dashboard through the `actions` prop. It collapses to a pill and can be dismissed; dismissal is reversible from Settings → Help.
## Integration Points
@@ -208,6 +215,7 @@ const [onboardingReopenTrigger, setOnboardingReopenTrigger] = React.useState(0);
<OnboardingWizard
onOpenCredentials={() => setCredentialsOpen(true)}
reopenTrigger={onboardingReopenTrigger}
+ onFinish={openAiAssistantAndFocusChat}
/>
```
@@ -217,7 +225,7 @@ const [onboardingReopenTrigger, setOnboardingReopenTrigger] = React.useState(0);
## WebSocket Handlers
-No new handlers were needed. The onboarding system reuses existing generic handlers, accessed through the TanStack Query user-settings layer:
+No new handlers were needed. The onboarding system reuses the generic user-settings handlers (registered from `server/services/settings/handlers.py`), accessed through the TanStack Query user-settings layer:
| Handler | Usage |
|---------|-------|
@@ -233,7 +241,7 @@ No new handlers were needed. The onboarding system reuses existing generic handl
3. `onboarding_completed` defaults to `false`, `onboarding_step` defaults to `0`
4. Wizard opens at step 0
5. User navigates steps -- each transition saves via the save mutation (`save_user_settings`)
-6. On "Start Building" or "Skip for now", `onboarding_completed` set to `true`
+6. On "Open AI Assistant" or "Skip for now", `onboarding_completed` set to `true`; only the former also fires `onFinish`
7. Wizard closes, does not reappear on refresh
### Existing User (Database Migration)
@@ -245,10 +253,10 @@ No new handlers were needed. The onboarding system reuses existing generic handl
### Resume Mid-Wizard
-1. User advances to step 3, closes browser
-2. `onboarding_step = 3` was saved on last navigation
-3. User reopens app, `useOnboarding` reads `step = 3, completed = false`
-4. Wizard opens at step 3
+1. User advances to step 2, closes browser
+2. `onboarding_step = 2` was saved on last navigation
+3. User reopens app, `useOnboarding` reads `step = 2, completed = false`
+4. Wizard opens at step 2
### Replay from Settings
@@ -271,35 +279,38 @@ No new handlers were needed. The onboarding system reuses existing generic handl
| Multiple tabs | Completing in one tab doesn't update others until query refetch |
| Replay from Settings | Resets local state and reopens wizard from step 0 |
| Fresh database (no workflow.db) | Onboarding appears after first settings query resolves |
+| Credential catalogue still loading on step 2 | `Skeleton` tiles; the Connect button is always available |
## Verification Checklist
-1. **Fresh database**: Delete `server/workflow.db` (or the configured DB), start server -- wizard appears
-2. **Step navigation**: Click through all 5 steps -- the `<ol>` stepper updates, Back/Next work
+1. **Fresh database**: Delete `~/.opencompany/workflow.db` (or the configured DB), start server -- wizard appears
+2. **Step navigation**: Click through all 4 steps -- the `<ol>` stepper updates, Back/Next work
3. **Skip**: Click "Skip for now" -- wizard closes, doesn't reappear on refresh
-4. **Resume**: Advance to step 3, close browser, reopen -- wizard resumes at step 3
-5. **Complete**: Finish all steps via "Start Building" -- wizard doesn't reappear
-6. **API Key step**: Click "Open Credentials" button -- CredentialsModal opens
+4. **Resume**: Advance to step 2, close browser, reopen -- wizard resumes at step 2
+5. **Complete**: Finish via "Open AI Assistant" -- wizard doesn't reappear, the AI Assistant example opens with chat focused
+6. **Connect step**: Click "Connect your AI account" -- CredentialsModal opens; after saving a key, the step re-renders as connected
7. **Existing user migration**: With existing `workflow.db` where `examples_loaded=1` -- onboarding does NOT appear
-8. **Theme support**: Switch themes -- role-token cards and region tints adapt correctly
+8. **Theme support**: Switch themes -- role-token cards adapt correctly
9. **Replay**: Open Settings, click "Replay Welcome Guide" -- wizard reopens from step 0
-10. **TypeScript**: `bun run typecheck` (root gate, TypeScript 7) passes clean
+10. **Tests**: `bun run --filter react-flow-client test` runs the four `onboarding/__tests__/` suites; `bun run typecheck` (root gate, TypeScript 7) passes clean
## Key Files
| File | Description |
|------|-------------|
-| `client/src/hooks/useOnboarding.ts` | Onboarding state hook; persists via TanStack-Query user-settings layer |
+| `client/src/hooks/useOnboarding.ts` | Wizard state hook; persists via TanStack-Query user-settings layer |
+| `client/src/hooks/useGetStarted.ts` | Get Started checklist state |
| `client/src/hooks/useUserSettingsQuery.ts` | `useUserSettingsQuery` / `useSaveUserSettingsMutation` (WS-backed) |
| `client/src/components/onboarding/OnboardingWizard.tsx` | Main wizard modal: `STEPS` SSOT + `<ol>` stepper + ActionButton footer |
+| `client/src/components/onboarding/GetStartedChecklist.tsx` | Post-wizard milestone checklist |
+| `client/src/components/onboarding/getStartedItems.ts` | Checklist items + `EXAMPLE_WORKFLOW_NAMES` |
+| `client/src/components/onboarding/aiProviderLinks.ts` | `FEATURED_AI_PROVIDERS` hints and key-page URLs |
| `client/src/components/onboarding/nodeRoleClasses.ts` | `NODE_ROLE_CLASSES` role→token map for step cards |
-| `client/src/components/onboarding/steps/WelcomeStep.tsx` | Step 0: Platform introduction |
-| `client/src/components/onboarding/steps/ConceptsStep.tsx` | Step 1: Key concepts (Nodes, Edges, Agents, Skills, Modes) |
-| `client/src/components/onboarding/steps/ApiKeyStep.tsx` | Step 2: API key setup with Credentials link |
-| `client/src/components/onboarding/steps/CanvasStep.tsx` | Step 3: UI layout diagram + shortcuts |
-| `client/src/components/onboarding/steps/GetStartedStep.tsx` | Step 4: Getting started tips |
-| `client/src/components/icons/AIProviderIcons.tsx` | Provider brand icons used by ApiKeyStep |
-| `client/src/Dashboard.tsx` | Integration: renders wizard + passes replay trigger |
+| `client/src/components/onboarding/steps/WelcomeStep.tsx` | Step 0: what OpenCompany is |
+| `client/src/components/onboarding/steps/HowItWorksStep.tsx` | Step 1: blocks, agents, chat, Normal/Dev switch |
+| `client/src/components/onboarding/steps/ConnectAIStep.tsx` | Step 2: provider tiles from the catalogue + Credentials link |
+| `client/src/components/onboarding/steps/TryItStep.tsx` | Step 3: AI Assistant recipe |
+| `client/src/Dashboard.tsx` | Integration: renders wizard + checklist, passes replay trigger and `onFinish` |
| `client/src/components/ui/SettingsPanel.tsx` | "Replay Welcome Guide" button in Help section |
| `server/models/database.py` | `UserSettings.onboarding_completed`, `onboarding_step` fields |
| `server/core/database.py` | Migration + CRUD for onboarding fields |
@@ -308,6 +319,6 @@ No new handlers were needed. The onboarding system reuses existing generic handl
To add a new onboarding step:
-1. Create `client/src/components/onboarding/steps/NewStep.tsx` composing shadcn primitives + Tailwind tokens + lucide icons (use `NODE_ROLE_CLASSES` for tinted cards). Do NOT introduce antd.
-2. Add a `{ title, render }` entry to the `STEPS` array in `OnboardingWizard.tsx`. Its `.length` automatically updates the hook's `totalSteps` and the progress stepper — no separate count to maintain.
+1. Create `client/src/components/onboarding/steps/NewStep.tsx` composing shadcn primitives + Tailwind tokens + lucide icons (use `NODE_ROLE_CLASSES` for tinted cards). Do NOT introduce antd. Prefer live data (`useCatalogueQuery`, `useNodeGroups`) over hardcoded lists, as steps 1 and 2 do.
+2. Add a `{ title, render }` entry to the `STEPS` array in `OnboardingWizard.tsx`. Its `.length` automatically updates the hook's `totalSteps` and the progress stepper — no separate count to maintain. If the new step is last, the "Open AI Assistant" button and `onFinish` move to it automatically.
3. No backend changes needed (step index is just a number).
diff --git a/docs-internal/performance.md b/docs-internal/performance.md
index dbada76b..d07fb1ae 100644
--- a/docs-internal/performance.md
+++ b/docs-internal/performance.md
@@ -53,7 +53,16 @@ extra ~0.7 s sits entirely in the import phase — "all imports complete"
at 3.29 s vs 1.98 s in the May timeline, and the routers + plugin-walker
segment at 1.83 s vs 0.84 s — because the walker now loads **184**
plugin modules against the **137** it walked in May. Lifespan cost is
-unchanged. The dev-mode rows were never benchmarked before (Vite and
+unchanged.
+
+**Counting rule for every plugin figure in this document.** The numbers
+(137 in May, 152 in July, 184 in September 2026) are the walker's
+*module* count — the `node plugins loaded: N modules` log line from
+`server/nodes/__init__.py`, i.e. `len(nodes._DISCOVERED)`, which
+includes `_*.py` helpers and per-folder submodules. They are **not**
+node-type counts: `len(services.node_registry.NODE_METADATA)` is 147
+today, spread across 37 group folders under `server/nodes/`. Both are
+computed from the tree; neither is hand-maintained here. The dev-mode rows were never benchmarked before (Vite and
uvicorn compete for I/O during a dev boot, so they are not comparable
to the prod numbers), and the first dev boot after a reinstall also
rebuilds Vite's dep cache.
@@ -112,7 +121,7 @@ T+0.00 — port-free begin
├── DI container (0.42 s)
├── Core service imports (0.36 s)
├── AIService import (0.70 s) ← native boundary + lazy history shims
- ├── Routers + plugin walker (0.84 s, 137 plugins)
+ ├── Routers + plugin walker (0.84 s, 137 plugin modules — May count; see counting rule)
└── All imports complete (1.98 s)
T+2.25 — Lifespan startup
├── DB + cache (0.04 s)
@@ -162,7 +171,7 @@ is idle in this window; the cost lives on the frontend. Likely
contributors:
1. **TanStack Query auth-bootstrap retry budget** ([client/src/contexts/AuthContext.tsx](../client/src/contexts/AuthContext.tsx) + [client/src/lib/connectionConfig.ts](../client/src/lib/connectionConfig.ts)). The `AUTH_RETRY` envelope (BASE 50 ms, CAP 4000 ms, MAX_ATTEMPTS 7) covers the typical 4 s backend cold-start window in 4-5 attempts. If the backend finishes mid-retry-cycle, the next jittered draw can land 1-3 s after readiness.
-2. **React Strict Mode dual-mount** in dev. The 100 ms guard in [WebSocketContext.tsx:2554](../client/src/contexts/WebSocketContext.tsx#L2554) absorbs the bulk; remaining cost is React reconciliation + babel-plugin-react-compiler overhead on first render.
+2. **React Strict Mode dual-mount** in dev. The 100 ms `setTimeout` guard in the connect effect at [WebSocketContext.tsx:3558](../client/src/contexts/WebSocketContext.tsx#L3558) absorbs the bulk; remaining cost is React reconciliation + babel-plugin-react-compiler overhead on first render.
3. **PartySocket upgrade handshake**. Sub-100 ms in normal cases; would only matter on slow networks.
To attribute definitively: add `console.time('auth.queryFn')` / `console.timeLog('auth.queryFn')` markers and a corresponding pair around `connect()`. Not blocking — the contract this layer was meant to fix (the +12 s disconnect-reconnect cycle) is resolved.
@@ -195,7 +204,7 @@ optimisations above; sum is what hurts.
| # | Bottleneck | Cost | Class | Notes |
|---|---|---|---|---|
-| 1 | Plugin walker at import time (152 modules under `server/nodes/`; ~2 s warm / ~4.7 s cold, dominated by `nodes/google`'s eager `googleapiclient` import) | ~2 s | Backend | `_HANDLER_REGISTRY` populates via `BaseNode.__init_subclass__` at import. Lazy `googleapiclient` is the cheap win (see follow-ups); full lazy-loading of the walker is the big-blast-radius option. |
+| 1 | Plugin walker at import time (152 modules under `server/nodes/` at the July measurement, 184 today — see the counting rule above; ~2 s warm / ~4.7 s cold, dominated by `nodes/google`'s eager `googleapiclient` import) | ~2 s | Backend | `_HANDLER_REGISTRY` populates via `BaseNode.__init_subclass__` at import. Lazy `googleapiclient` is the cheap win (see follow-ups); full lazy-loading of the walker is the big-blast-radius option. |
| 2 | TanStack Query auth bootstrap retry window | ~3-5 s | Frontend | See "remaining +5 s gap" above. |
| 3 | AIService/native orchestration import graph | ~0.7 s | Backend | Historical May baseline; new agent execution uses native `Message` / `AgentToolSpec` values and provider registration remains lazy. Re-measure before attributing this cost further. |
| 4 | Status-broadcaster refresh (`refresh_all_services`, 2.6 s) | ~2.6 s | Backend | Runs after `Application startup complete`, doesn't block server-ready. WhatsApp + Telegram are the long tails. |
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index bee3b903..f12961d0 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -21,7 +21,7 @@ pitfalls).
The full single-file recipe code block lives in the cookbook — see
[`server/nodes/README.md` → Five-minute recipe](../server/nodes/README.md#five-minute-recipe).
-A single file (`server/nodes/search/acme_search.py`, class
+A single folder (`server/nodes/search/acme_search/__init__.py`, class
`AcmeSearchNode`) declares `type` /
`display_name` / `group` / `component_kind` / `handles` /
`credentials` / `task_queue` / `usable_as_tool` / `Params` / `Output`
@@ -75,7 +75,7 @@ class SpecializedAgentBase(ActionNode, abstract=True):
| `credentials` | Sequence of `Credential` subclasses the node uses. More than one is supported — see [Multi-credential nodes](#multi-credential-nodes). |
| `Params` | Pydantic `BaseModel` — user-facing parameters. Used for both UI rendering and AI tool schemas. |
| `Output` | Pydantic `BaseModel` — runtime output shape. |
-| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. Combined with `component_kind != "model"`, makes the plugin visible to `agentBuilder.add_tool` (catalogue + rebind paths). **Side effect:** setting it auto-sets `hide_input_handle` / `hide_output_handle` to `True` unless the class declares them ([base.py:215](../server/services/plugin/base.py#L215)), so a dual-purpose node that must remain wirable on the canvas has to declare both `False` explicitly. |
+| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. Combined with `component_kind != "model"`, makes the plugin visible to `agentBuilder.add_tool` (catalogue + rebind paths). **Side effect:** setting it auto-sets `hide_input_handle` / `hide_output_handle` to `True` unless the class declares them ([base.py:243-246](../server/services/plugin/base.py#L243)), so a dual-purpose node that must remain wirable on the canvas has to declare both `False` explicitly. |
| `needs_canvas` | `ClassVar[bool]` — when `True`, the F4.B `AgentWorkflow` tool-dispatch forwards the parent workflow's `nodes`/`edges` into the per-tool activity payload. Today only `AgentBuilderNode` opts in (walks edges to resolve its calling agent). |
| `task_queue` | Temporal worker pool. See `TaskQueue` constants. |
| `retry_policy` | `RetryPolicy` dataclass (mirrors `temporalio.common.RetryPolicy`). |
@@ -288,7 +288,7 @@ provider.
**A multi-credential node MUST use imperative operations.** The declarative
`routing=` path resolves `self.credentials[0]`
-([base.py:571](../server/services/plugin/base.py#L571)), so a routed op would
+([base.py:769](../server/services/plugin/base.py#L769)), so a routed op would
authenticate every provider with the first key in the tuple regardless of what
the user picked. `test_plugin_contract.py` only asserts the tuple is non-empty,
so nothing else catches it. `nodes/speech/` has a test asserting neither of its
@@ -397,8 +397,10 @@ on a plugin resolves to a registered class.
| `nodes/twitter/_credentials.py` | `TwitterCredential` | oauth2 | twitterSend / twitterSearch / twitterUser / twitterReceive |
| `nodes/telegram/_credentials.py` | `TelegramCredential` | api_key | telegramSend / telegramReceive |
| `nodes/scraper/_credentials.py` | `ApifyCredential` | api_key (bearer) | apifyActor |
-| `nodes/model/_credentials.py` | `OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai / Ollama / LMStudio` | api_key | 12 native providers and 11 standalone chat-model nodes. Ollama / LM Studio store a local server URL; xAI is agent-selectable but has no standalone node. |
-| `nodes/search/*.py` (inline) | `BraveSearch / Serper / Perplexity` | api_key | single-use search nodes |
+| `nodes/model/_credentials.py` | `OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai / Sarvam / Ollama / LMStudio` | api_key | 13 credential classes covering the 13 agent-selectable providers and the 12 standalone chat-model nodes (`ls server/nodes/model/*_chat_model`). Ollama / LM Studio store a local server URL; xAI is agent-selectable but has no standalone node; `SarvamCredential` also serves the speech / translate plugins. |
+| `nodes/search/<name>/__init__.py` (inline) | `BraveSearch / Serper / Perplexity` | api_key | single-use search nodes |
+
+This table is the Wave 11.E snapshot, not an inventory — later plugins (Stripe, Vercel, GitHub, Cloudflare, gcloud, WhatsApp, WhatsApp Business, Discord, Microsoft, ElevenLabs, Deepgram, DeepL, ...) each ship their own `_credentials.py`. Read the live set from `len(services.plugin.credential.CREDENTIAL_REGISTRY)` (34 at the time of writing).
`GoogleCredential` exposes a `build_credentials()` classmethod that
returns a `google.oauth2.credentials.Credentials` — hand-off to
@@ -485,7 +487,7 @@ AgentWorkflow.run(payload):
2. if kind == "tool_calls":
for each call: execute_activity(f"node.{tool_type}.v{version}")
3. execute_activity("agent.persist_turn") # append memory per turn
- 4. if compaction threshold: execute_activity("agent.compact_memory")
+ 4. if compaction threshold: execute_activity("agent.compact_context")
```
The worker registers the `agent.*` activities alongside the per-type
@@ -634,11 +636,10 @@ if precheck_error:
return error_envelope(precheck_error)
waiter = await event_waiter.register(node_type, node_id, parameters)
-# services/status_broadcaster.py — WS-connect refresh
+# services/status_broadcaster.py — refresh_all_services (runs once at
+# lifespan startup, Wave 11.I; no per-plugin knowledge remains here)
async with asyncio.TaskGroup() as tg:
- tg.create_task(self._refresh_whatsapp_status()) # legacy hardcoded
- # ... future migrations move into the registry too:
- for callback in _SERVICE_REFRESH_CALLBACKS:
+ for callback in list(_SERVICE_REFRESH_CALLBACKS):
tg.create_task(callback(self))
```
@@ -656,9 +657,9 @@ plugin owns one of:
- A duplicate `Output` Pydantic class that the central
`node_output_schemas.NODE_OUTPUT_SCHEMAS` would otherwise pin.
-If none of those apply: a single `<name>.py` in the right folder is
-the whole node. Don't create `_service.py` / `_handlers.py` / etc.
-just because telegram has them.
+If none of those apply: a single `<name>/__init__.py` folder under the
+right group is the whole node. Don't create `_service.py` /
+`_handlers.py` / etc. just because telegram has them.
### Wire format is the contract — not module paths
@@ -669,12 +670,12 @@ long as the registered keys stay the same. The
`server/config/credential_providers.json` declarative config — served
to the frontend via `handle_get_credential_catalogue` and consumed by
`useCatalogueQuery` — is likewise stable across backend reorganisations.
-(The pre-Wave-13 `client/src/components/credentials/providers.tsx`
-static fallback no longer exists; the server catalogue is the single
+(The pre-Wave-13 `providers.tsx` static fallback in the credentials
+component folder no longer exists; the server catalogue is the single
source of truth for the credentials panel.)
This is why the telegram refactor changed zero frontend code despite
-moving 754 lines out of `services/telegram_service.py`.
+moving 754 lines out of the old `telegram_service.py` service module.
## Folder layout
@@ -683,10 +684,12 @@ server/
├── nodes/ # One self-contained folder per plugin (Wave 11.H)
│ ├── __init__.py # pkgutil.walk_packages discovery
│ ├── groups.py # Palette group metadata
-│ ├── agent/ # AI agents (aiAgent, chatAgent + 16 specialized/variant)
+│ ├── agent/ # AI agents — 22 folders (aiAgent, chatAgent, 13 SpecializedAgentBase
+│ │ │ # subclasses, rlm / claude_code / codex, vertex_* variants)
│ │ ├── _handles.py # Shared handle topology helpers
│ │ ├── _inline.py # prepare_agent_call()
│ │ ├── _specialized.py # SpecializedAgentBase
+│ │ ├── _vertex.py # Shared Vertex Agent Engine helpers
│ │ └── <agent>/__init__.py # one folder per agent
│ ├── model/ # AI chat models (12 providers; all agent-capable)
│ │ ├── _base.py # ChatModelBase + ChatModelParams/Output
@@ -698,18 +701,17 @@ server/
│ │ ├── _base.py # CodeExecutorBase
│ │ ├── _nodejs.py # Shared NodeJSClient singleton
│ │ └── <lang>_executor/__init__.py
-│ ├── filesystem/ # file_read / file_modify / shell / fs_search
+│ ├── filesystem/ # file_read / file_modify / shell / fs_search / gallery
│ │ ├── _backend.py # Native workspace-contained filesystem helper
│ │ └── <op>/__init__.py
-│ ├── document/ # http_scraper / parser / chunker / embedding / vector
-│ │ ├── _helpers.py # delegate() wrapper
+│ ├── document/ # http_scraper / parser / chunker / embedding / vector / file_downloader
│ │ └── <stage>/__init__.py
│ ├── google/ # gmail / calendar / drive / sheets / tasks / contacts
│ ├── proxy/ # proxy_request / proxy_config / proxy_status
│ │ └── _usage.py # Shared track_proxy_usage
│ ├── search/ # brave / serper / perplexity / duckduckgo
│ ├── scraper/ # apify / crawlee
-│ ├── tool/ # calculator / currentTime / taskManager / writeTodos
+│ ├── tool/ # calculator / currentTime / taskManager / writeTodos / agent_builder / canvas / data_source / simple_memory
│ ├── trigger/ # webhookTrigger / chatTrigger / taskTrigger
│ ├── workflow/ # start
│ ├── scheduler/ # cronScheduler / timer
@@ -719,14 +721,16 @@ server/
│ ├── email/ # emailSend / emailRead / emailReceive
│ ├── chat/ # chatSend / chatHistory
│ ├── social/ # socialSend / socialReceive
-│ ├── browser/ # browser (agent-browser CLI)
+│ ├── browser/ # browser (agent-browser CLI) / browser_harness (browser-use CDP)
│ ├── utility/ # httpRequest / webhookResponse / console / team_monitor / process_manager
│ ├── text/ # textGenerator / fileHandler
│ ├── location/ # gmaps_create / gmaps_locations / gmaps_nearby_places
-│ └── skill/ # simpleMemory / masterSkill
-│ # Each group folder owns its own
-│ # _credentials.py (Wave 11.E.1) —
-│ # no central credentials package.
+│ ├── skill/ # masterSkill (+ _expander.py; skill/simple_memory is an import shim —
+│ │ # the canonical simpleMemory plugin is nodes/tool/simple_memory/)
+│ └── ... # context / speech / translate / vision / discord / microsoft /
+│ # whatsapp_business / stripe / vercel / github / cloudflare / gcloud —
+│ # `ls server/nodes` is the inventory; each group folder owns its
+│ # own _credentials.py (Wave 11.E.1), no central credentials package.
└── services/
├── plugin/ # Plugin runtime
│ ├── base.py # BaseNode
@@ -809,8 +813,9 @@ All Wave 10 invariants in `test_node_spec.py` still run; Wave 11 invariants in `
`nodes/twitter/_base.py` for client + XDK helpers.
- Wave 11.D.9 — WhatsApp + Social inlined into `nodes/whatsapp/_base.py`
and `nodes/social/_base.py` (full bodies, RPC dispatch via
- `services.whatsapp_service`; renamed from `routers/whatsapp.py` in
- Wave 11.E.2 since it was never an APIRouter).
+ `services.whatsapp_service`; renamed from the misnamed `whatsapp.py` router in
+ Wave 11.E.2 since it was never an APIRouter, and moved again into
+ `nodes/whatsapp/_service.py` in Wave 11.I).
- Wave 11.D.10 — `utility.py` split across 12 plugin files (maps,
text, workflow start, timer, cron, console, team monitor, chat).
- Wave 11.D.11 — Auto-populate trigger registries.
@@ -824,19 +829,21 @@ All Wave 10 invariants in `test_node_spec.py` still run; Wave 11 invariants in `
- F4.B — `AgentWorkflow` child workflow + 3 agent activities behind
`TEMPORAL_AGENT_WORKFLOW_ENABLED` flag (commit `a4d009e`). Tool
calls inside AI agents become per-type activities.
-- Wave 11.E — Declarative credentials: 25 `Credential` subclasses
- (GoogleCredential + GoogleMapsCredential + TwitterCredential +
+- Wave 11.E — Declarative credentials: 25 `Credential` subclasses at
+ the time (GoogleCredential + GoogleMapsCredential + TwitterCredential +
TelegramCredential + ApifyCredential + 12 LLM providers + 3 inline
search credentials + Stripe / Vercel / GitHub / Cloudflare /
- WhatsApp). 29 plugins now declare `credentials = (...)`.
- Agents stay poly-provider (empty tuple).
+ WhatsApp); 29 plugins declared `credentials = (...)`. Today the live
+ numbers are `len(CREDENTIAL_REGISTRY)` (34) and 53 plugin files with a
+ non-empty `credentials` tuple. Agents stay poly-provider (empty tuple).
- Wave 11.E.1 — Modularised credentials into per-domain
`nodes/<group>/_credentials.py` files. `server/credentials/`
directory deleted; auto-discovery rides on node-package import.
- Wave 11.E.2 — Dead-code sweep: fixed 2 broken agent imports,
stripped 13 dead dispatch branches in `tools.py`, deleted duplicate
- `handlers/proxy.py`, moved misnamed `routers/whatsapp.py` →
- `services/whatsapp_service.py`, dedup'd `TRIGGER_NODE_TYPES`.
+ `handlers/proxy.py`, moved the misnamed `whatsapp.py` router →
+ `whatsapp_service.py` under services (now `nodes/whatsapp/_service.py`
+ since Wave 11.I), dedup'd `TRIGGER_NODE_TYPES`.
- Wave 11.E.3 — Inlined the last per-domain handler bodies into
plugins. Deleted 8 fully-orphan handler files (search, code,
telegram, http, filesystem, email, process, todo) and 4
@@ -899,7 +906,7 @@ All Wave 10 invariants in `test_node_spec.py` still run; Wave 11 invariants in `
Phase 2-4 migrate the existing polling and daemon triggers onto
the framework. Telegram is the reference implementation:
~870 lines of telegram-specific code moved out of
- `services/telegram_service.py` (deleted), `routers/websocket.py`
+ the old `telegram_service.py` service module (deleted), `routers/websocket.py`
(7 inline handlers removed), `services/event_waiter.py`
(`build_telegram_filter` + hardcoded registry entry removed),
`services/status_broadcaster.py` (`_refresh_telegram_status`
@@ -911,16 +918,16 @@ All Wave 10 invariants in `test_node_spec.py` still run; Wave 11 invariants in `
changes. Frontend identifies plugin commands by WebSocket message
type strings, not Python module paths.
-`services/handlers/` is now **4 files / ~970 LOC** (down from 16
+`services/handlers/` is now **4 files / ~1,240 LOC** (down from 16
files / 12,800 LOC; `google_auth.py` moved to `nodes/google/_auth_helper.py`
-in Wave 11.I commit D):
+in Wave 11.I commit D; `wc -l server/services/handlers/*.py` for the live figure):
| File | LOC | Purpose |
|---|---|---|
-| `tools.py` | 821 | AI-tool dispatcher, plugin fast-path, agent delegation infrastructure (shared `_delegated_tasks` / `_delegation_results` state). |
-| `triggers.py` | 126 | Generic event-trigger handler for polling triggers (gmailReceive, twitterReceive, etc.). |
-| `todo.py` | 65 | TaskManager / writeTodos invocation surface for AI tool nodes. |
-| `__init__.py` | 23 | Package docstring; nothing imports from `services.handlers` at package level. |
+| `tools.py` | ~1,024 | AI-tool dispatcher, plugin fast-path, agent delegation infrastructure (shared `_delegated_tasks` / `_delegation_results` state). |
+| `triggers.py` | ~123 | Generic event-trigger handler for polling triggers (gmailReceive, twitterReceive, etc.). |
+| `todo.py` | ~75 | TaskManager / writeTodos invocation surface for AI tool nodes. |
+| `__init__.py` | ~19 | Package docstring; nothing imports from `services.handlers` at package level. |
Every domain owns its own code under `nodes/<group>/` — plugin file +
optional `_base.py` / `_inline.py` / `_credentials.py` siblings. No
@@ -1270,7 +1277,7 @@ without any node-specific code in the frontend or in core services:
emits this event after every state change. The frontend's
existing handler in
[`WebSocketContext.tsx`](../client/src/contexts/WebSocketContext.tsx)
- (line 671) invalidates the catalogue query; the modal refetches
+ (`case 'credential_catalogue_updated'`, line 1007) invalidates the catalogue query; the modal refetches
and re-renders. **No new broadcast type, no Zustand entry, no
`case '<provider>_status'`.** Frontend has zero references to any
CLI-managed plugin's name.
@@ -1337,7 +1344,7 @@ the skill icon resolver to find their target:
| Place | Form | Example |
|---|---|---|
| Plugin node `type` | camelCase | `stripeAction` |
-| `visuals.json` key | matches node `type` (camelCase) | `"stripeAction": { "icon": "asset:stripe", ... }` |
+| `visuals.json` key | matches node `type` (camelCase) | `"stripeAction": { "skill": "stripe-skill" }` (icon + color come from the plugin folder's `icon.svg` / `meta.json`; `visuals.json` carries zero `asset:` values post-F1/F7) |
| Plugin `tool_name` ClassVar (snapshot: `tests/fixtures/tool_names_snapshot.json`) | snake_case of node type | `tool_name = "stripe_action"` |
| Skill `allowed-tools` token | matches the LLM tool name above | `allowed-tools: "stripe_action"` |
diff --git a/docs-internal/release_build_pipeline.md b/docs-internal/release_build_pipeline.md
index 9ad940f4..001a1656 100644
--- a/docs-internal/release_build_pipeline.md
+++ b/docs-internal/release_build_pipeline.md
@@ -94,11 +94,11 @@ named `tsgo` — stopped publishing the day before and must not come back.
- `client/vite.config.js` → extend `build` block:
- `target: 'es2022'`
- - `chunkSizeWarningLimit: 600` (down from 1500)
+ - `chunkSizeWarningLimit: 850` (down from 1500; the plan said 600, but `vendor-icons` — lucide + lobehub brand SVGs — is ~830 KB on its own, so the ceiling sits just above it and other chunks still trip it)
- `rollupOptions.output.manualChunks` mapping:
- `vendor-react`: `react`, `react-dom`, `react-hook-form`, `@hookform/resolvers`
- `vendor-flow`: `reactflow`
- - `vendor-radix`: `@radix-ui/*`, `radix-ui`
+ - `vendor-radix`: `radix-ui` (the single umbrella package; no `@radix-ui/*` scoped entries)
- `vendor-icons`: `lucide-react`, `@lobehub/icons`
- `vendor-query`: `@tanstack/react-query`, `@tanstack/query-sync-storage-persister`, `@tanstack/react-query-persist-client`, `@lukemorales/query-key-factory`
- `vendor-markdown`: `react-markdown`, `remark-gfm`, `remark-breaks`, `prismjs`, `react-simple-code-editor`, `@uiw/react-json-view`
@@ -149,11 +149,11 @@ The npm tarball still excludes `__pycache__/` per `package.json` `files` (cross-
- **`company build` layers `.env.dev` first.** `build_command()` calls `cli.config.load_dev_overrides(root)` before the install steps, so the build's `DATA_DIR` matches what the runtime sees. Without it, a repo checkout's `company build` read `DATA_DIR=~/.opencompany` from `.env.template` and installed Temporal under user home, but `company dev` then read `DATA_DIR=.opencompany` from `.env.dev` and re-downloaded into `<repo>/.opencompany/` — a redundant ~114 MB fetch on every fresh clone.
- **Safe for global installs.** `.env.dev` is git-committed for contributors but is NOT in the npm `files` list, so an npm-distributed copy has no `.env.dev` — `load_dev_overrides` is a no-op and everything falls through to the `.env.template` default (`DATA_DIR=~/.opencompany`), matching `company start` / `company daemon`.
-### 5. Wire bundle + compileall into install.js
+### 5. Wire compileall into install.js (the sidecar bundle ships pre-built)
- `scripts/install.js` → after `uv sync`:
- 1. `npm --prefix server/nodejs run build` — produce `dist/index.js`
- 2. `python -m compileall -q -j 0 <COMPILEALL_SOURCE_DIRS>` — same shape as build.py (no `-O`; locked in sync by `cli/tests/test_release_pipeline_config.py`)
+ 1. `uv run python -m compileall -q -j 0 <COMPILEALL_SOURCE_DIRS>` — same shape as build.py (no `-O`; locked in sync by `cli/tests/test_release_pipeline_config.py`)
+- The sidecar is **not** rebuilt at install time: `company build` step `[3/6]` runs `bun run --filter opencompany-nodejs-executor build` before `npm pack`, and `server/nodejs/dist/index.js` rides inside the tarball (the `server/` entry in the root `files` list covers it). Likewise the client is only built by install.js when `client/dist/index.html` is missing.
Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is deterministic).
@@ -171,19 +171,19 @@ Idempotent on re-runs (compileall only rewrites stale pyc; esbuild is determinis
| `server/nodejs/package.json` | + esbuild devDep, build script, change start |
| `server/nodejs/.gitignore` | new — ignore `dist/` |
| `cli/commands/build.py` | + compileall step (`[5/6]`, plain `.pyc` — no `-O`), `COMPILEALL_SOURCE_DIRS` constant |
-| `scripts/install.js` | + sidecar bundle + compileall calls |
+| `scripts/install.js` | + compileall call (sidecar bundle arrives pre-built in the tarball) |
| `server/pyproject.toml` | `[tool.uv] compile-bytecode = true` — `uv sync` compiles `.venv/` site-packages |
| `.github/workflows/predeploy.yml` | + typecheck gate in `build-and-lint`; + `tsc --version` in the cross-OS matrix |
## Verification
1. `bun run --filter react-flow-client typecheck` → <5s, zero errors.
-2. `ANALYZE=1 bun run --filter react-flow-client build` → open `client/dist/stats.html`. Expect: no chunk above 600 KB gz, main < 200 KB gz, `vendor-flow` split.
-3. `cd server/nodejs && npm run build && node dist/index.js` → starts on :5682 in <100ms.
+2. `ANALYZE=1 bun run --filter react-flow-client build` → open `client/dist/stats.html`. Expect: no chunk trips the 850 KB `chunkSizeWarningLimit` (`vendor-icons` is the ~830 KB outlier it is sized for), main < 200 KB gz, `vendor-flow` split.
+3. `cd server/nodejs && bun run build && NODEJS_EXECUTOR_PORT=<port> node dist/index.js` → starts on `NODEJS_EXECUTOR_PORT` (required env; no fallback literal) in <100ms.
4. `cd server && uv run python -m compileall -q -j 0 services` → plain `__pycache__/*.pyc` present (no `.opt-1.pyc` — nothing loads those).
5. Cold-start: clean install + `company start > start.log 2>&1` → `Application startup complete` at ≤+50s (was +66.9s).
6. `npm pack --dry-run` → `server/nodejs/dist/index.js` included; no `__pycache__/`; tarball size ≤ v0.0.76.
-7. Smoke: `company start` → load http://localhost:5678 → run "AI Assistant" example → agent responds.
+7. Smoke: `company start` → load the app URL (`http://localhost:${PYTHON_BACKEND_PORT}`) → run "AI Assistant" example → agent responds.
## Out of scope (future work)
diff --git a/docs-internal/rlm_service.md b/docs-internal/rlm_service.md
index 5adfc1ec..fbadfb75 100644
--- a/docs-internal/rlm_service.md
+++ b/docs-internal/rlm_service.md
@@ -1,6 +1,6 @@
# RLM Service -- Recursive Language Model Agent Integration
-> **Related docs:** [memory_lifecycle.md](./memory_lifecycle.md) for the shared markdown memory format (RLM uses the same simpleMemory surface as aiAgent); [tool_building_pipeline.md](./tool_building_pipeline.md) for how connected tool nodes are bound to the REPL via `ToolBridgeAdapter`.
+> **Related docs:** [agent_context_flow.md](./agent_context_flow.md) for conversation continuity — RLM is a specialized provider, so a connected Context node reaches it through `SpecializedAgentContextBridge` (`services/cli_agent/context_bridge.py`); [tool_building_pipeline.md](./tool_building_pipeline.md) for how connected tool nodes are bound to the REPL via `ToolBridgeAdapter`. [memory_lifecycle.md](./memory_lifecycle.md) describes only the retired V1 markdown memory path.
## Overview
@@ -30,18 +30,18 @@ OpenCompany Node Execution System
================================
[chatTrigger] --input-main--+
-[simpleMemory] --input-memory--+
-[masterSkill] --input-skill--+
+[context] --input-context--+ (RFC-0002 Context node; the retired
+[masterSkill] --input-skill--+ input-memory handle no longer exists)
v
+-----------+
| rlm_agent |
+-----+-----+
|
input-tools handle
- / | \
- [openaiChatModel] [pythonExecutor] [braveSearch]
- (small LM, (tool node, (tool node,
- depth>=1) bridged to bridged to
+ / | \ \
+ [openaiChatModel] [pythonExecutor] [braveSearch] [simpleMemory]
+ (small LM, (tool node, (tool node, (Memory is an
+ depth>=1) bridged to bridged to ordinary tool)
custom_tool) custom_tool)
@@ -203,10 +203,16 @@ These are extracted from the node's `options` object:
preparation helpers, then delegates to the independent RLM service:
```python
-# 1. Collect connected memory, skills, tools, input, and task data
-memory_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(
+# 1. Collect connected context, skills, tools, input, and task data
+# (nodes/agent/rlm_agent/__init__.py:61-72)
+context_data, skill_data, tool_data, input_data, task_data = await collect_agent_connections(
node_id, ctx.raw, database, log_prefix="[RLM Agent]"
)
+# The first element is a Context descriptor on V2 graphs (kind == "context"),
+# or the legacy Memory descriptor on immutable V1 snapshots. The service
+# receives them as separate kwargs: context_data=context_v2, memory_data=legacy.
+context_v2 = context_data if (context_data or {}).get("kind") == "context" else None
+memory_data = context_data if context_data and not context_v2 else None
# 2. Inject task context and strip tools for terminal task notifications
if task_data:
@@ -240,13 +246,14 @@ return await ai_service.rlm_service.execute(node_id, parameters, ...)
| Function | Source | Purpose in RLM |
|----------|--------|----------------|
-| `collect_agent_connections()` | `services/plugin/edge_walker.py` | Discover memory, skills, tools, input, task connections (renamed Wave-11 successor to `handlers/ai.py::_collect_agent_connections`; the old handler file is gone) |
+| `collect_agent_connections()` | `services/plugin/edge_walker.py` | Discover context, skills, tools, input, task connections (renamed Wave-11 successor to `handlers/ai.py::_collect_agent_connections`; the old handler file is gone) |
+| `SpecializedAgentContextBridge` | `services/cli_agent/context_bridge.py` | Context continuity for a connected Context node: `resolve` loads the stored conversation (`rlm/service.py:48-56`), `augment_prompt` renders it into the REPL prompt (`:202-203`), `record_turn(original_prompt, response)` saves the turn (`:230-234`) |
| `prepare_agent_call()` | `nodes/agent/_inline.py` | Shared pre-dispatch helper — collects connections + injects task context + auto-prompt from upstream input |
| `_build_skill_system_prompt()` | `services/ai.py` | Build system prompt from connected skill nodes |
| `is_model_valid_for_provider()` | `services/ai.py` | Validate model name for provider |
| `get_default_model_async()` | `services/ai.py` | Look up default model from DB or config |
| `self.auth.get_api_key()` | AIService | Retrieve API key from credential store |
-| `save_message()` | `memory_store.py` | Persist conversation to memory |
+| `add_message()` | `services/memory_store.py:35` | Legacy V1 only — appends user/assistant turns to the in-memory session store when a V1 `memory_data` descriptor is present (`rlm/service.py:241-246`) |
| `execute_tool()` | `services/handlers/tools.py` | Dispatch tool execution (used by ToolBridgeAdapter) |
| `broadcaster.update_node_status()` | `status_broadcaster.py` | Real-time UI status updates |
@@ -303,20 +310,31 @@ The RLM service broadcasts these phases via WebSocket for UI animations:
---
-## Future Phases
-
-### Delegation Support (Phase 4)
-Add `'rlm_agent'` to:
-- `DEFAULT_TOOL_NAMES` -> `'delegate_to_rlm_agent'`
-- `DEFAULT_TOOL_DESCRIPTIONS` -> ONE-SHOT delegation description
-- `_get_tool_schema()` -> `DelegateToAgentSchema` condition
-- `execute_tool()` dispatch tuple in `handlers/tools.py`
-
-### Frontend (Phase 5)
-- Node definition in `specializedAgentNodes.ts`
-- `AGENT_CONFIGS` entry in `AIAgentNode.tsx`
-- Parameter panel integration in `MiddleSection.tsx` and `InputSection.tsx`
-
-### RLM Skill (Phase 6)
-- `server/skills/rlm_agent/rlm-reasoning-skill/SKILL.md`
-- REPL usage instructions, available functions, decomposition strategies
+## Later phases (all shipped)
+
+The three follow-up phases this doc originally listed as future work have
+landed; the mechanisms differ from the original plan because the intervening
+Wave 11 / Wave 12 D5 refactors removed the surfaces they named.
+
+### Delegation support (was Phase 4)
+`rlm_agent` is delegatable. The `DEFAULT_TOOL_NAMES` /
+`DEFAULT_TOOL_DESCRIPTIONS` dicts no longer exist (locked by
+`tests/test_tool_registry.py`); the delegation identity comes from
+`BaseNode.__init_subclass__`, which stamps `tool_name =
+f"delegate_to_{cls.type}"` on every agent plugin (`services/plugin/base.py:257`).
+`rlm_agent` is listed in both `_AGENT_DELEGATION_TYPES` (`services/ai.py:2510`,
+the `DelegateToAgentSchema` gate) and `AI_AGENT_TYPES` (`server/constants.py:32`,
+the `execute_tool` dispatch gate). It stays on the legacy fire-and-forget path
+— excluded from `AGENT_WORKFLOW_TYPES` because its REPL state is externalised.
+
+### Frontend (was Phase 5)
+There is nothing per-agent to add. `specializedAgentNodes.ts` and the
+`AGENT_CONFIGS` map were retired in Wave 10.D / Wave 11: `AIAgentNode.tsx`
+renders handles / icon / colour / display name from the backend NodeSpec via
+`useNodeSpec(type)`, and the parameter panel is schema-driven from the plugin's
+`Params`. Visuals come from `nodes/agent/rlm_agent/meta.json` (+ `icon.svg` or
+the `visuals.json` fallback).
+
+### RLM skill (was Phase 6)
+`server/skills/rlm_agent/rlm-reasoning-skill/SKILL.md` exists and covers REPL
+usage, the available functions, and decomposition strategies.
diff --git a/docs-internal/speech_provider_rfc.md b/docs-internal/speech_provider_rfc.md
index f41b8634..464c0365 100644
--- a/docs-internal/speech_provider_rfc.md
+++ b/docs-internal/speech_provider_rfc.md
@@ -104,12 +104,12 @@ branches in shared code; this is how we avoid needing any.
### D5 — First multi-credential node in the repo
`credentials = (OpenAICredential, ElevenLabsCredential, …)` with `ctx.connection(params.provider)`.
-Already supported: `_make_connection_factory` ([`base.py:870`](../server/services/plugin/base.py))
+Already supported: `_make_connection_factory` ([`base.py:1134`](../server/services/plugin/base.py))
builds a dict over **all** declared credentials and raises only for undeclared ids. No node uses
this today.
Consequence: the node must use imperative `@Operation` bodies — the declarative `routing=` path
-hardcodes `self.credentials[0]` ([`base.py:566`](../server/services/plugin/base.py)).
+hardcodes `self.credentials[0]` ([`base.py:769`](../server/services/plugin/base.py)).
### D6 — Extract the generic registry rather than copy it
@@ -118,11 +118,11 @@ provider-agnostic. Copying it into `services/speech/` would fork the boot-time-i
logic that exists specifically to keep ~7 s (warm) / ~45 s (cold) of SDK imports off startup.
`services/provider_registry.py`; `services/llm/registry.py` becomes a shim.
-**Success criterion: `server/tests/llm/` passes untouched.** Met — 168 tests, no edits. `_REGISTRY`
+**Success criterion: `server/tests/llm/` passes untouched.** Met — 168 tests at the time, no edits (the suite has since grown; `pytest tests/llm --collect-only -q` is the live count). `_REGISTRY`
survives as an alias bound to the *same dict object* the registry mutates, because several tests
swap provider factories in place through it.
-A companion `services/provider_clients.py` (the lease-counted client cache) was scoped here and
+A companion `provider_clients.py` service (the lease-counted client cache) was scoped here and
deliberately **not** built. See §4: speech makes one HTTP call per node execution, so the cache has
no second consumer and would have earned only a shutdown hook in `main.py`.
@@ -204,8 +204,9 @@ have been the next entry on it.
**Layering rule.** The speech layer takes credential **id strings**, never `Credential` classes.
`nodes/speech/_config.credential_id(provider)` reads the id from JSON, and a test asserts every
registered provider's id resolves in `CREDENTIAL_REGISTRY`. Cross-plugin *credential* imports are
-fine and idiomatic (`from ..model._credentials import OpenAICredential`, exactly what `nodes/sarvam/`
-already does); what stays out is any `services/` module knowing a vendor name.
+fine and idiomatic (`from ..model._credentials import OpenAICredential`, exactly what
+`nodes/translate/` does today and the since-retired `nodes/sarvam/` did before it); what stays
+out is any `services/` module knowing a vendor name.
**No client cache.** `ChatUnifier` keeps a lease-counted LRU because an agent loop makes many model
calls inside one node execution. Speech is the opposite shape -- one HTTP request per execution,
diff --git a/docs-internal/status_broadcaster.md b/docs-internal/status_broadcaster.md
index ea291813..537d78f7 100644
--- a/docs-internal/status_broadcaster.md
+++ b/docs-internal/status_broadcaster.md
@@ -66,7 +66,7 @@ StatusBroadcaster.connect(ws)
|
v
Message loop:
- receive_json -> dispatch to handler in _HANDLERS registry
+ receive_json -> dispatch: MESSAGE_HANDLERS.get(type) or get_ws_handlers().get(type)
send_json -> pushed by broadcaster on state change
ping/pong -> keepalive every 30s from frontend
|
@@ -77,11 +77,11 @@ Frontend unmounts or logs out
StatusBroadcaster.disconnect(ws) -> remove from _connections
```
-Auto-reconnect is handled by `WebSocketContext.tsx`: on disconnect, it schedules a reconnect after 3 seconds with a 100ms mount delay to avoid React Strict Mode double-connect in dev.
+Auto-reconnect is handled by `WebSocketContext.tsx` through PartySocket's `ReconnectingWebSocket` (`partysocket/ws`): jittered exponential backoff (`MIN_DELAY_MS` / `MAX_DELAY_MS` / `GROW_FACTOR` in `client/src/lib/connectionConfig.ts`), message replay, and intentional-close handling (code 1000 stops the reconnect loop). A 100ms mount delay avoids React Strict Mode double-connect in dev.
## Handler Registry
-Handlers are registered via the `@ws_handler` decorator:
+Handlers are plain async functions wrapped by the `@ws_handler` decorator (`services/ws_handler_registry.py`):
```python
@ws_handler()
@@ -91,7 +91,7 @@ async def handle_get_node_parameters(data: Dict, websocket: WebSocket) -> Dict:
return {"success": True, "parameters": params}
```
-The decorator populates a module-level `_HANDLERS: Dict[str, Callable]` map from the function name (`handle_get_node_parameters` -> `"get_node_parameters"`). The dispatcher reads the incoming message's `type` field and looks up the handler.
+The decorator does **not** register anything. It validates the listed required fields, default-injects `{"success": True}`, and wraps exceptions into a `{"success": False, "error": ...}` envelope. Registration is explicit and lives in two places: the core `MESSAGE_HANDLERS` dict in `server/routers/websocket.py` (`"get_node_parameters": handle_get_node_parameters, ...`), and the plugin-side `register_ws_handlers({...})` calls from each `nodes/<plugin>/__init__.py`, which write into the `_WS_REGISTRY` `IdempotentRegistry` in `services/ws_handler_registry.py`. The dispatcher reads the incoming message's `type` field and resolves `MESSAGE_HANDLERS.get(type) or get_ws_handlers().get(type)`. Plugin handlers that can fail user-correctably use `@ws_response` (from `services.plugin.ws`) instead, which keeps the one-WARN-line `NodeUserError` contract.
Live total = `len(MESSAGE_HANDLERS) + len(get_ws_handlers())` -- the `MESSAGE_HANDLERS` dict in `server/routers/websocket.py` plus plugin-registered handlers via `services.ws_handler_registry`. Do not hand-maintain a fixed count here.
@@ -104,11 +104,11 @@ Live total = `len(MESSAGE_HANDLERS) + len(get_ws_handlers())` -- the `MESSAGE_HA
| Tool schemas | `get_tool_schema`, `save_tool_schema`, `delete_tool_schema`, `get_all_tool_schemas` |
| Node execution | `execute_node`, `execute_workflow`, `cancel_execution`, `get_node_output`, `clear_node_output` |
| Triggers / events | `cancel_event_wait`, `get_active_waiters` |
-| Dead letter queue | `get_dlq_entries`, `replay_dlq_entry`, `remove_dlq_entry`, `purge_dlq`, `get_dlq_stats` |
+| Dead letter queue | `get_dlq_entries`, `get_dlq_entry`, `replay_dlq_entry`, `remove_dlq_entry`, `purge_dlq`, `get_dlq_stats` |
| Deployment | `deploy_workflow`, `cancel_deployment`, `get_deployment_status`, `update_deployment_settings` |
-| AI operations | `execute_ai_node`, `get_ai_models`, `test_ai_proxy` |
+| AI operations | `execute_ai_node`, `get_ai_models` |
| API keys | `validate_api_key`, `get_stored_api_key`, `save_api_key`, `delete_api_key` |
-| OAuth flows | `claude_oauth_login`, `twitter_oauth_login`, `twitter_logout`, `google_oauth_login`, `google_logout` |
+| OAuth / CLI login flows | `claude_code_login`, `claude_code_logout` (plugin-registered from `nodes/agent/claude_code_agent/_handlers.py`), `twitter_oauth_login`, `twitter_logout`, `google_oauth_login`, `google_logout` |
| Android | `get_android_devices`, `execute_android_action`, `android_relay_connect`, `android_relay_disconnect`, `android_relay_reconnect` |
| WhatsApp | `whatsapp_status`, `whatsapp_qr`, `whatsapp_send`, `whatsapp_chat_history`, `whatsapp_newsletters`, `whatsapp_diagnostics`, ... |
| Telegram | `telegram_connect`, `telegram_disconnect`, `telegram_status`, `telegram_send`, `telegram_get_me`, `telegram_get_chat` |
@@ -122,7 +122,7 @@ Live total = `len(MESSAGE_HANDLERS) + len(get_ws_handlers())` -- the `MESSAGE_HA
| Agent teams | `create_team`, `add_team_task`, `claim_team_task`, `complete_team_task`, `get_team_messages` |
| Model registry | `get_model_constraints`, `refresh_model_registry` |
-The exact set drifts over time. The canonical count comes from counting `@ws_handler(` occurrences in `server/routers/websocket.py`.
+The exact set drifts over time. The canonical count is `len(MESSAGE_HANDLERS) + len(get_ws_handlers())` at runtime (many handlers now live in `services/credentials/handlers.py`, `services/settings/handlers.py` and `nodes/<plugin>/_handlers.py`, so counting decorators in `websocket.py` undercounts).
## Broadcast Messages (Server -> Clients)
@@ -139,7 +139,7 @@ Broadcasts are sent to all connected clients without a request-response correlat
| `api_key_status` | Credential validation result; also fired by `delete_api_key` to clear `apiKeyStatuses[provider]` | `{provider, data: {valid, hasKey, models, message, timestamp}}` |
| `credential_catalogue_updated` | Credential mutation (save / delete / oauth-disconnect) — wraps `WorkflowEvent` (CloudEvents v1.0) from `services/events/envelope.py`. Outer `type` stays this string for FE back-compat; body's `type` follows `credential.<area>.<action>` (e.g. `credential.api_key.saved`). Frontend `WebSocketContext` invalidates `useCatalogueQuery` via the 300 ms `invalidateCatalogue` debounce. | `{specversion: "1.0", id, source: "opencompany://services/credentials", type, subject: provider, time, data: {provider, customer_id?}}` |
| `node_parameters_updated` | Parameters saved by parameter-panel user, Claude CLI memory bridge, or AgentWorkflow per-turn memory append — wraps `WorkflowEvent` (CloudEvents v1.0) from `services/events/envelope.py`. Body's `type` is `com.opencompany.node.parameters.updated`. `data.source` (`"user"` / `"cli"` / `"agent"`) distinguishes the three emission sites. Replaces the legacy raw-dict broadcast at commit `7c9e873`. Locked by `tests/test_cloudevents_node_parameters.py`. | `{specversion: "1.0", id, source: "opencompany://services/parameters", type: "com.opencompany.node.parameters.updated", subject: node_id, time, data: {node_id, parameters, version, source}}` |
-| `agent_progress` | Agent-loop / AgentWorkflow lifecycle phase (canvas badge "N / max" + phase indicator) — wraps `WorkflowEvent.agent_progress` (CloudEvents v1.0). Emitted from `services/ai.py:execute_agent` (legacy) and via the `agent.broadcast_progress.v1` Temporal activity (F4.B). F4.B fires the full phase set: `starting` (entry, drives `node_status="executing"`), `llm_step` (per iteration), `executing_tool` + `tool_completed` (around each per-type tool activity), `completed` (final, drives `node_status="success"`). The activity optionally drives a raw-dict `update_node_status` alongside the CloudEvents envelope so the canvas-glow color follows the lifecycle without a separate handler — same dual-channel pattern F4.A's `_node_activity` uses. | `{specversion: "1.0", id, source: "opencompany://services/agent", type: "com.opencompany.agent.progress", subject: node_id, time, data: {node_id, iteration, max_iterations, phase?, tool_name?}}` |
+| `agent_progress` | Agent-loop / AgentWorkflow lifecycle phase (canvas badge "N / max" + phase indicator) — wraps `WorkflowEvent.agent_progress` (CloudEvents v1.0). Emitted from `services/ai.py:execute_agent` (legacy) and via the `agent.broadcast_progress` Temporal activity (F4.B). F4.B fires the full phase set: `starting` (entry, drives `node_status="executing"`), `llm_step` (per iteration), `executing_tool` + `tool_completed` (around each per-type tool activity), `completed` (final, drives `node_status="success"`). The activity optionally drives a raw-dict `update_node_status` alongside the CloudEvents envelope so the canvas-glow color follows the lifecycle without a separate handler — same dual-channel pattern F4.A's `_node_activity` uses. | `{specversion: "1.0", id, source: "opencompany://services/agent", type: "com.opencompany.agent.progress", subject: node_id, time, data: {node_id, iteration, max_iterations, phase?, tool_name?}}` |
| `token_usage_update` | AI execution updates token counters | `{session_id, data: {total, threshold, needs_compaction}}` |
| `compaction_starting` | Memory compaction begins | `{session_id, node_id}` |
| `compaction_completed` | Memory compaction ends | `{session_id, success, tokens_before, tokens_after}` |
@@ -210,7 +210,7 @@ Android service nodes (`batteryMonitor`, `wifiAutomation`, etc.) check `androidS
**Frontend** (`WebSocketContext.tsx`):
- 30-second `setInterval` sends `{"type": "ping"}`.
-- On disconnect: schedule reconnect after 3 seconds.
+- On disconnect: PartySocket's `ReconnectingWebSocket` reconnects with jittered exponential backoff (`client/src/lib/connectionConfig.ts`), replaying queued messages; an intentional close (code 1000) stops the loop.
- 100ms mount delay avoids React Strict Mode double-connect in development.
- `isMountedRef` prevents connections after unmount.
- WebSocket is gated on `isAuthenticated` from `AuthContext`: if auth is disabled or not yet loaded, the provider defers connection.
diff --git a/docs-internal/stripe_service.md b/docs-internal/stripe_service.md
index b5b72818..490198f1 100644
--- a/docs-internal/stripe_service.md
+++ b/docs-internal/stripe_service.md
@@ -234,7 +234,7 @@ StripeListenSource.stop()
| `server/routers/webhook.py` | Path-handler arm: consults `WEBHOOK_SOURCES` before falling through to legacy generic dispatch. |
| `server/nodes/visuals.json` | `stripeAction` / `stripeReceive` icon + color (`asset:stripe`, `#635BFF`). |
| `server/nodes/groups.py` | `payments` palette group. |
-| `client/src/assets/icons/stripe.svg` | Stripe icon. |
+| `server/credentials/icons/stripe.svg` | Stripe credential-tile icon, served at `/api/schemas/credentials/stripe/icon`. |
| `server/tests/services/test_events.py` | 18 framework tests (envelope, verifiers, polling/daemon lifecycle, WebhookSource). |
| `server/tests/nodes/test_stripe_plugin.py` | 21 Stripe-specific tests (shape, filter, action passthrough, registrations). |
@@ -837,7 +837,7 @@ End-to-end smoke (requires Stripe CLI installed and a Stripe account):
"create a Stripe test customer with email [email protected]"; the
LLM emits a `stripeAction.run` tool call.
7. **Signature failure.**
- `curl -X POST -H "Stripe-Signature: t=0,v1=garbage" http://localhost:5678/webhook/stripe -d '{}'`
+ `curl -X POST -H "Stripe-Signature: t=0,v1=garbage" http://localhost:${PYTHON_BACKEND_PORT}/webhook/stripe -d '{}'`
returns 400; no event dispatched.
8. **Logout.** Credentials Modal → Disconnect. Confirm
`process_service.list_processes("_stripe_global")` is empty AND
@@ -848,8 +848,8 @@ End-to-end smoke (requires Stripe CLI installed and a Stripe account):
triggers `make_status_refresh` which auto-spawns the daemon.
Unit tests live in [`server/tests/nodes/test_stripe_plugin.py`](../server/tests/nodes/test_stripe_plugin.py)
-(21 tests) and [`server/tests/services/test_events.py`](../server/tests/services/test_events.py)
-(18 framework tests). Run via `pytest server/tests/services/test_events.py
+(20 collected cases at time of writing) and [`server/tests/services/test_events.py`](../server/tests/services/test_events.py)
+(29 framework tests; counts via `pytest --collect-only -q`). Run via `pytest server/tests/services/test_events.py
server/tests/nodes/test_stripe_plugin.py -v`.
## Related Docs
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
index 28d59ccf..a9a933c5 100644
--- a/docs-internal/theme_system.md
+++ b/docs-internal/theme_system.md
@@ -217,7 +217,7 @@ Result by theme (display font / tracking / case):
2. **Whole-store Zustand destructure.** Always `useAppStore((s) => s.x)`, never `{ x } = useAppStore()`.
3. **Ad-hoc opacity arithmetic on role/surface tokens.** Don't inline alpha (`bg-bg-app/10`, `bg-node-agent/30`, `bg-action-run/25`). Tailwind v4 *can* now color-mix `/opacity` on hex tokens, but the discipline is to reference a NAMED token: add/define a `-soft` / `-hover` / `-border` variant, or a `--tint-*` step in base.css, and use it by name.
4. **Hardcoded colours.** No `bg-white`, `bg-black`, `text-gray-500`, `style={{ backgroundColor: '#fff' }}`. Use tokens.
-5. **`useAppTheme()` in new files.** Allowed only for surfaces that need JS-side hex values Tailwind can't express: canvas node components (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`, `GenericNode`), `EdgeConditionEditor`, and the Google Maps SDK consumers (`GoogleMapsPicker`, `MapsPreviewPanel`) — note the map
+5. **`useAppTheme()` in new files.** Allowed only for surfaces that need JS-side hex values Tailwind can't express: canvas node components (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`), `EdgeConditionEditor`, and the Google Maps SDK consumers (`GoogleMapsPicker`, `MapsPreviewPanel`) — note the map
tiles themselves are deliberately left to Google's own styling; `useAppTheme` here covers only
the surrounding chrome. Every other surface uses Tailwind + tokens. New themes contribute to `useAppTheme` via a `THEME_OVERRIDES` entry, never by importing `lightColors` / `darkColors` directly.
6. **Hand-rolled modal backdrops.** Use `<Modal>` from `client/src/components/ui/Modal.tsx`.
@@ -230,12 +230,12 @@ the surrounding chrome. Every other surface uses Tailwind + tokens. New themes c
- **`--node-pulse-color` contract** — executing-node glow color is independent of `--node-color` (the plugin accent). Each decorated skin overrides `--node-pulse-color` to its highest-contrast accent (light/dark deliberately keep the base.css `var(--info)` fallback) (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine `--lapis-bright`, Atomic turquoise, etc.) so the glow stays visible against any canvas background. Defined in [base.css](../client/src/themes/base.css) at `:root`, overridden in each per-theme file. The executing keyframes (`node-pulse` + per-theme `cyber-pulse-exec` / `surv-pulse-exec` / `ren-pulse-exec`) and the per-theme `--pulse-keyframe` / `--pulse-duration` / `--pulse-timing` tokens live in [animations.css](../client/src/themes/animations.css); base.css's `.sq-node[data-executing] .sq-node-box` / `.react-flow__node.executing .{sq-node-box,node}` rule reads `var(--pulse-keyframe, node-pulse)`, so a theme picks its pulse by overriding ONE token (Cyber → `cyber-pulse-exec`, Surveillance → `surv-pulse-exec`, Renaissance → `ren-pulse-exec`) — no high-specificity per-theme animation rule. `node-pulse` is a triple-layer expanding box-shadow (12px ring + 32px mid halo + 56px outer halo) consuming `var(--node-pulse-color)` + the shared `--tint-pulse-*` alphas. Trigger nodes use a separate continuous `.opencompany-trigger-armed` "listening" heartbeat (`trigger-listening` keyframe) while waiting, plus `.opencompany-bolt` on the ⚡ badge — distinct from the one-shot execution pulse. **Never animate `opacity` on whole-node selectors** — it fades the node icon + content, not just the glow.
- **`data-page-hidden` animation pause** — [Dashboard.tsx](../client/src/Dashboard.tsx) mounts a `visibilitychange` listener that toggles `data-page-hidden` on `<html>`; [base.css](../client/src/themes/base.css) declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important; }`. Without this, paused CSS keyframes accumulate frames in the compositor queue while the tab is hidden; on tab return all 50+ executing nodes' triple-layer pulses + Cyber's full-viewport `cyber-flicker` / `cyber-roll` resume simultaneously, stalling the GPU compositor 100-200ms and blocking input dispatch (first-click-feels-frozen pattern). The unpause is deferred via `requestAnimationFrame` so input dispatch wins the frame before composite resumes.
- **Parameter panel theme contract** — MasterSkillEditor, OutputPanel, MiddleSection, ToolSchemaEditor, ParameterPanel removed `useAppTheme()`. Every surface renders against Tailwind tokens + new-contract CSS custom props. Section headers carry the display-typography triplet (`font-display tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)] text-fg-default`); action buttons use `<ActionButton intent="run|stop|save|config|tools">`; backgrounds use `bg-bg-elevated` / `bg-bg-panel` / `bg-bg-input` from the surface tier table above. EditableNodeLabel emits both `sq-node-label` and `node-label` classNames so per-theme typography rules fire under either topology. Per-theme scrollbar webkit rules (`::-webkit-scrollbar-thumb` etc.) declared in all 12 themes — gold (Renaissance), square-cornered (Atomic / Edo / Greek / Wasteland / Plague), metallic (Steampunk), phosphor (Rot), neon (Cyber), REC-red (Surveillance), shadcn neutral (Light / Dark).
-- **Canvas-node class topology alignment** (W26) — TriggerNode, StartNode, ToolkitNode migrated from `.node` (rectangular spec-card) topology to `.sq-node` / `.sq-node-box` (square-icon node) topology so per-theme decorations (Steampunk brass rivets, Edo hanko seal, Surveillance REC LED, Renaissance gold emblem) reach them. Status pips, gear buttons, and React Flow handles on every node component now carry `.sq-node-pip` / `.sq-node-gear` / `.sq-node-handle.in/.out` (square nodes) or `.node-pip` / `.node-gear` / `.node-handle.in/.out` (rectangular nodes — AIAgentNode, GenericNode, TeamMonitorNode). Pip background is data-driven via `data-status="idle | executing | waiting | success | error"` — base.css picks the colour from shadcn semantic tokens; per-theme files override. Inline JS-computed `backgroundColor` / `border` / `animation` on these elements stripped — CSS owns visuals. Cyber's `.node-trigger` rule extended to dual-target both rectangular and square topologies (`.sq-node.node-trigger .sq-node-box`). Orphan `.node-output` rule removed. EditableNodeLabel now emits both `sq-node-label` and `node-label` classNames so per-theme typography rules fire. StartNode reads `nodeColor` from `definition?.defaults?.color` instead of hardcoded `theme.dracula.cyan`.
+- **Canvas-node class topology alignment** (W26) — TriggerNode, StartNode, ToolkitNode migrated from `.node` (rectangular spec-card) topology to `.sq-node` / `.sq-node-box` (square-icon node) topology so per-theme decorations (Steampunk brass rivets, Edo hanko seal, Surveillance REC LED, Renaissance gold emblem) reach them. Status pips, gear buttons, and React Flow handles on every node component now carry `.sq-node-pip` / `.sq-node-gear` / `.sq-node-handle.in/.out` (square nodes) or `.node-pip` / `.node-gear` / `.node-handle.in/.out` (rectangular nodes — AIAgentNode, TeamMonitorNode; the former `GenericNode` was retired with the spec-driven canvas). Pip background is data-driven via `data-status="idle | executing | waiting | success | error"` — base.css picks the colour from shadcn semantic tokens; per-theme files override. Inline JS-computed `backgroundColor` / `border` / `animation` on these elements stripped — CSS owns visuals. Cyber's `.node-trigger` rule extended to dual-target both rectangular and square topologies (`.sq-node.node-trigger .sq-node-box`). Orphan `.node-output` rule removed. EditableNodeLabel now emits both `sq-node-label` and `node-label` classNames so per-theme typography rules fire. StartNode reads `nodeColor` from `definition?.defaults?.color` instead of hardcoded `theme.dracula.cyan`.
- **Audio fix** (W20) — `--sound-pack: chime` typo in `light.css` + `dark.css` was silently falling through to `'none'` (`chime` not in the engine's pack registry), making sound silent for the most-used themes. Renamed `light` → `parchment`, `dark` → `terminal`. Added `Sounds.unlock()` exported from [lib/sound.ts](../client/src/lib/sound.ts) plus a one-shot `pointerdown / keydown / touchstart` capture-phase listener in `useSoundSync()` ([hooks/useSound.ts](../client/src/hooks/useSound.ts)) so the AudioContext resumes on the user's first gesture (Chrome / Safari autoplay policy compliance).
-- **Canvas-node visual contract** (W21) — every node component (`AIAgentNode`, `SquareNode`, `GenericNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`) stripped its inline `background` / `border` / `borderRadius` / `boxShadow` / `animation` props. Each now exposes the per-definition accent hex via `style={{ '--node-color': accentColor }}` on its outer wrapper. Visual styling lives in [base.css](../client/src/themes/base.css) defaults + per-theme overrides; `var(--node-color)` carries the plugin's `visuals.json` accent through CSS without fighting specificity. New `NodeStyle` helper type in [client/src/types/NodeTypes.ts](../client/src/types/NodeTypes.ts) (`React.CSSProperties & Record<\`--${string}\`, string | number>`) makes the inline custom-prop typecheck-clean.
+- **Canvas-node visual contract** (W21) — every node component (`AIAgentNode`, `SquareNode`, `TriggerNode`, `StartNode`, `ToolkitNode`, `TeamMonitorNode`; `GenericNode` at the time, since retired) stripped its inline `background` / `border` / `borderRadius` / `boxShadow` / `animation` props. Each now exposes the per-definition accent hex via `style={{ '--node-color': accentColor }}` on its outer wrapper. Visual styling lives in [base.css](../client/src/themes/base.css) defaults + per-theme overrides; `var(--node-color)` carries the plugin's `visuals.json` accent through CSS without fighting specificity. New `NodeStyle` helper type in [client/src/types/NodeTypes.ts](../client/src/types/NodeTypes.ts) (`React.CSSProperties & Record<\`--${string}\`, string | number>`) makes the inline custom-prop typecheck-clean.
- **Per-theme icons** (W23) — [client/src/assets/icons/themedGlyphs.ts](../client/src/assets/icons/themedGlyphs.ts) ports all 290 SVG glyphs from `design_handoff_machinaos_themes/app/icons.js` (29 keys × 10 themes). [NodeIcon.tsx](../client/src/assets/icons/NodeIcon.tsx) consults `THEMED_GLYPHS[activeTheme][key]` first; falls through to `lucide-react` / `lobehub:` / `asset:` dispatch on miss. Renaissance gets heraldic shields, Cyber wireframe + glow, Plague woodcut hatching, etc. Light + dark themes have no entries — they fall through to existing dispatch.
- **Canvas grid + cursors** (W24) — `--canvas-grid` and `--cursor-default` slots declared in [base.css](../client/src/themes/base.css) and bound to `.canvas-host`. Per-theme grids: Cyber 24px magenta+cyan grid, Surveillance CCTV crosshair + REC overlay, Renaissance fleur-de-lis cartography, Greek key meander, Steampunk brass bolt grid, Atomic mid-century starburst, Wasteland cracked-earth fissures, Rot flagstone, Plague broadsheet red-X. Custom cursors: Cyber crosshair reticle, Surveillance snooper reticle, Renaissance gold-leaf quill.
-- **Decorative HTML primitives** (W25) — [client/src/components/SvgFilterDefs.tsx](../client/src/components/SvgFilterDefs.tsx) mounts a hidden inline `<svg><defs>` at app root exposing `#ink-blot` (Renaissance edge warble), `#noise` (Wasteland turbulence), `#crt` (Cyber chromatic aberration) so per-theme `filter: url(#...)` rules resolve. [client/src/components/ui/DropCap.tsx](../client/src/components/ui/DropCap.tsx) wraps content with `v-display drop-cap` className so the Renaissance `::first-letter` ornament rule fires.
+- **Decorative HTML primitives** (W25) — [client/src/components/SvgFilterDefs.tsx](../client/src/components/SvgFilterDefs.tsx) mounts a hidden inline `<svg><defs>` at app root exposing `#ink-blot` (Renaissance edge warble), `#noise` (Wasteland turbulence), `#crt` (Cyber chromatic aberration) so per-theme `filter: url(#...)` rules resolve. The `DropCap.tsx` wrapper (`v-display drop-cap`) planned alongside it was never retained: no `DropCap` component, `drop-cap` class or `::first-letter` rule exists in the tree today. What survives is the bare `.v-display` display-typography co-class, which ten of the per-theme files style (`cyber.css` glitch-on-hover, `edo.css`, `greek.css`, ...).
- **Token contract**: all 12 themes in [client/src/themes/](../client/src/themes) (2 base + 5 utopian + 5 dystopian; the 10 decorative ones ported from the handoff). 14 CSS files (base + animations + 12 themes), ~4,900+ LOC total.
- **ThemeProvider** ([client/src/contexts/ThemeContext.tsx](../client/src/contexts/ThemeContext.tsx)) — 12-way `ThemeName`, `DARK_FAMILY` ⊃ `{dark, cyber, wasteland, rot, surveillance, steampunk}`, legacy `darkMode` localStorage migration on first load
- **ThemeSwitcher** — DropdownMenu grouped into System / Utopian / Dystopian sections, all 12 themes
@@ -517,7 +517,6 @@ cd client && npx eslint <files>
| [client/src/assets/icons/themedGlyphs.ts](../client/src/assets/icons/themedGlyphs.ts) | Per-theme SVG glyph map (29 keys × 10 themes) — Wave 23 |
| [client/src/assets/icons/NodeIcon.tsx](../client/src/assets/icons/NodeIcon.tsx) | Theme-aware icon resolver (consults THEMED_GLYPHS first) |
| [client/src/components/SvgFilterDefs.tsx](../client/src/components/SvgFilterDefs.tsx) | Inline `<svg><defs>` carrying `#ink-blot` / `#noise` / `#crt` filter IDs — Wave 25 |
-| [client/src/components/ui/DropCap.tsx](../client/src/components/ui/DropCap.tsx) | `v-display drop-cap` wrapper for Renaissance ornament rule — Wave 25 |
| [client/src/types/NodeTypes.ts](../client/src/types/NodeTypes.ts) | `NodeStyle` helper type for inline `--*` custom props — Wave 21 |
| [client/index.html](../client/index.html) | Google Fonts loading (all 12 themes' typefaces) |
| `design_handoff_machinaos_themes/` (external design handoff, not in repo) | Reference HTML mocks + token spec |
diff --git a/docs-internal/tool_building_pipeline.md b/docs-internal/tool_building_pipeline.md
index 976a3a62..d21de0f5 100644
--- a/docs-internal/tool_building_pipeline.md
+++ b/docs-internal/tool_building_pipeline.md
@@ -41,9 +41,12 @@ Replaces the partial explanations previously scattered across
[`collect_agent_connections(node_id, context, database)`](../server/services/plugin/edge_walker.py) walks the workflow edges and returns a 5-tuple per agent:
```
-(memory_data, skill_data, tool_data, input_data, task_data)
+(context_data, skill_data, tool_data, input_data, task_data)
```
+(`edge_walker.py:181-199` — the first element is the Context descriptor from
+`input-context`, or the legacy Memory descriptor on immutable V1 snapshots.)
+
- **`tool_data`** is a list of dicts. Each entry: `{node_id, node_type, parameters, label}`. (The `connected_services` extra belonged to the retired `androidTool` gateway tool — see §7.)
- **MasterSkill expansion** runs at discovery time: a single `masterSkill` connection with `skillsConfig` expands into N individual skill entries, one per enabled skill key.
- **Team-lead expansion** (`orchestrator_agent` / `ai_employee`): agents connected
@@ -158,7 +161,7 @@ tool or crashing.
## 6. Stage 5 — Dispatch (handlers/tools.py)
-[`execute_tool(tool_name, tool_args, config)`](../server/services/handlers/tools.py#L73) at line 73:
+[`execute_tool(tool_name, tool_args, config)`](../server/services/handlers/tools.py#L75) at line 75:
```python
1. broadcaster.update_node_status(node_id, "executing", ...)
@@ -170,13 +173,13 @@ tool or crashing.
4. Return result. Exceptions trigger an "error" broadcast and re-raise.
```
-[`_dispatch_tool`](../server/services/handlers/tools.py#L138) at line 138 is pure routing — no broadcasting. Routes by `config["node_type"]`:
+[`_dispatch_tool`](../server/services/handlers/tools.py#L146) at line 146 is pure routing — no broadcasting. Routes by `config["node_type"]`:
| Pattern | Handler |
|---|---|
| `aiAgent` / `chatAgent` / `<specialized>_agent` | `_execute_delegated_agent` (fire-and-forget background task) |
| `_builtin_check_delegated_tasks` | `_execute_check_delegated_tasks` |
-| `batteryMonitor` / `wifiAutomation` / ... (16 service types) | `_execute_android_service` (snake_case service ID via SERVICE_ID_MAP) |
+| `batteryMonitor` / `wifiAutomation` / ... (16 service types) | `nodes/android/_base.py::execute_android_service_tool` (line 248; imported at `tools.py:227` — snake_case service ID via `SERVICE_ID_MAP` at `_base.py:25`) |
| `whatsappSend` / `whatsappDb` / `pythonExecutor` / ... | Per-plugin `usable_as_tool=True` handler (the plugin's own `execute()` method) |
| `calculatorTool` / `currentTimeTool` / `taskManager` / `writeTodos` | `_execute_<name>` direct implementations |
| `braveSearch` / `serperSearch` / `perplexitySearch` | `handle_<provider>_search` (httpx async, credential resolution, usage tracking) |
@@ -191,8 +194,8 @@ Android service plugins expose their own `tool_name` class variables and
connect directly to `input-tools`. Legacy
`service -> androidTool -> agent` graphs are rewritten on load by
`services/workflow_migrations.normalize_legacy_android_toolkit`, and sub-node
-exclusion keys solely on the AI-agent config handles (`input-memory` /
-`input-tools` / `input-skill` / `input-teammates`) — the
+exclusion keys solely on the AI-agent config handles (`input-context` /
+`input-tools` / `input-skill` / `input-teammates`; `execution/models.py:351-359`) — the
`TOOLKIT_NODE_TYPES` constant is gone.
## 8. Internal delegation identities (`delegate_to_*`)
@@ -210,7 +213,7 @@ class DelegateToAgentSchema(BaseModel):
context: Optional[str] = None
```
-[`_execute_delegated_agent`](../server/services/handlers/tools.py#L317) at line 317:
+[`_execute_delegated_agent`](../server/services/handlers/tools.py#L314) at line 314:
1. Generate a `task_id` (`uuid4().hex`).
2. Spawn `asyncio.create_task(<child agent execute>)` — fire and forget.
@@ -224,10 +227,10 @@ Parent agents see results via three paths — see [agent_delegation.md](./agent_
When `TEMPORAL_PER_TYPE_DISPATCH=true` and the run is happening inside a Temporal workflow, tool calls do NOT go through `execute_tool` directly. Instead:
-1. `agent.prepare_payload.v1` records `llm_engine="native"` and
+1. `agent.prepare_payload` records `llm_engine="native"` and
`message_wire_version=2` for new executions.
2. `AgentWorkflow` (the F4.B child workflow) gets the LLM's tool-calls list
- back from `agent.execute_llm_step.v1`, whose native branch sends `ToolDef`
+ back from `agent.execute_llm_step`, whose native branch sends `ToolDef`
declarations through `ChatUnifier`.
3. For each tool call, the workflow schedules
`f"node.{node_type}.v{version}"` as a Temporal activity on the plugin's
@@ -257,7 +260,7 @@ Some tools bundle a default skill — `writeTodos` ships with `write-todos-skill
```
server/tests/
├── test_status_broadcasts.py # locks execute_tool's lifecycle broadcast contract
-├── test_credential_broadcasts.py # auth tools' CloudEvents envelope
+├── credentials/test_credential_broadcasts.py # auth tools' CloudEvents envelope
├── nodes/test_ai_agents.py # end-to-end agent + tool exercise
└── temporal/test_dispatch.py # F4.A per-type activity dispatch (when flag on)
```
diff --git a/server/constants.py b/server/constants.py
index 978f8dc2..64f3e23e 100644
--- a/server/constants.py
+++ b/server/constants.py
@@ -22,8 +22,8 @@ AI_CHAT_MODEL_TYPES: FrozenSet[str] = frozenset(
"kimiChatModel",
"mistralChatModel",
"sarvamChatModel",
- # Local-server providers (Phase 1 of the LiteLLM adoption — see
- # plans/i-plan-to-implement-nested-orbit.md).
+ # Local-server providers (Ollama / LM Studio speak the OpenAI wire
+ # format; routed through OpenAIProvider with a localhost base_url).
"ollamaChatModel",
"lmstudioChatModel",
]
diff --git a/server/routers/schemas.py b/server/routers/schemas.py
index 36992a95..725ff046 100644
--- a/server/routers/schemas.py
+++ b/server/routers/schemas.py
@@ -2,8 +2,8 @@
Mirrors n8n's static-asset pattern: the editor fetches
``GET /api/schemas/nodes/{node_type}.json`` on demand (no auth required,
-long-cacheable). See docs-internal/schema_source_of_truth_rfc.md for
-the design rationale and docs-internal/schema_source_of_truth_rfc.md
+long-cacheable). See docs-internal/ARCHIVE/schema_source_of_truth_rfc.md for
+the design rationale and docs-internal/ARCHIVE/schema_source_of_truth_rfc.md
for the frontend consumer (useNodeOutputSchemaQuery).
"""
diff --git a/server/routers/websocket.py b/server/routers/websocket.py
index e2bc8c8d..d4953c1f 100644
--- a/server/routers/websocket.py
+++ b/server/routers/websocket.py
@@ -280,7 +280,7 @@ async def handle_get_all_tool_schemas(data: Dict[str, Any], websocket: WebSocket
# ============================================================================
# Node Output Schemas (n8n-style: backend as single source of truth for
# the drag-drop variable panel's "before first run" fallback shape).
-# See docs-internal/schema_source_of_truth_rfc.md.
+# See docs-internal/ARCHIVE/schema_source_of_truth_rfc.md.
# ============================================================================
@@ -1467,7 +1467,7 @@ MESSAGE_HANDLERS: Dict[str, MessageHandler] = {
"delete_tool_schema": handle_delete_tool_schema,
"get_all_tool_schemas": handle_get_all_tool_schemas,
# Node output schemas (Pydantic-backed registry; see
- # docs-internal/schema_source_of_truth_rfc.md).
+ # docs-internal/ARCHIVE/schema_source_of_truth_rfc.md).
"get_node_output_schema": handle_get_node_output_schema,
# Wave 6 Phase 2: unified NodeSpec (input + output + metadata).
"get_node_spec": handle_get_node_spec,
diff --git a/server/services/event_waiter.py b/server/services/event_waiter.py
index c03e2fa5..c48135a5 100644
--- a/server/services/event_waiter.py
+++ b/server/services/event_waiter.py
@@ -65,7 +65,8 @@ class TriggerConfig:
# Registry of supported trigger types (event-based triggers only)
-# Note: cronScheduler is NOT an event-based trigger - it uses APScheduler directly
+# Note: cronScheduler is NOT an event-based trigger - it runs as a Temporal
+# Schedule (nodes/scheduler/cron_scheduler/_workflow.py) and never waits here.
TRIGGER_REGISTRY: Dict[str, TriggerConfig] = {
# Framework-level triggers — not owned by any plugin domain.
"start": TriggerConfig(node_type="start", event_type="deploy_triggered", display_name="Deploy Start"),
diff --git a/server/services/memory/__init__.py b/server/services/memory/__init__.py
index 8df2197a..487b9d5c 100644
--- a/server/services/memory/__init__.py
+++ b/server/services/memory/__init__.py
@@ -6,7 +6,8 @@ storage format / concern owns its own module:
- :mod:`services.memory.markdown` — markdown parse/append/trim
(used by aiAgent / chatAgent / rlm_agent)
- :mod:`services.memory.jsonl` — Anthropic Messages JSONL
- parse/append/trim (used by claude_code_agent's session bridge)
+ parse/append/trim (standalone primitive; no agent consumes it today —
+ claude_code_agent's continuity is claude-native via --continue/--resume)
- :mod:`services.memory.vector_store` — per-session native semantic
store for long-term archival
- :mod:`services.memory.state` — orchestration: clear every store
diff --git a/server/services/node_output_schemas.py b/server/services/node_output_schemas.py
index 3fdcd939..3b2c3bb7 100644
--- a/server/services/node_output_schemas.py
+++ b/server/services/node_output_schemas.py
@@ -7,7 +7,7 @@ HTTP endpoint) to populate the draggable variable list *before* the
workflow has been executed. Once a node has run, the editor prefers
the real execution data over the declared schema (mirrors n8n's
VirtualSchema.vue precedence — see
-docs-internal/schema_source_of_truth_rfc.md).
+docs-internal/ARCHIVE/schema_source_of_truth_rfc.md).
Design notes:
- Models here are **UI-visible shape projections**. They do NOT have to
diff --git a/server/tests/credentials/README.md b/server/tests/credentials/README.md
index 651adbb7..bb33922e 100644
--- a/server/tests/credentials/README.md
+++ b/server/tests/credentials/README.md
@@ -1,6 +1,6 @@
# Credentials Test Suite
-Locks in the invariants enumerated in [docs-internal/credentials_panel.md §5](../../../docs-internal/credentials_panel.md).
+Locks in the invariants enumerated in [docs-internal/ARCHIVE/credentials_panel.md §5](../../../docs-internal/ARCHIVE/credentials_panel.md).
## Run
diff --git a/server/tests/credentials/test_auth_service.py b/server/tests/credentials/test_auth_service.py
index ed4fa732..8ed301e8 100644
--- a/server/tests/credentials/test_auth_service.py
+++ b/server/tests/credentials/test_auth_service.py
@@ -1,6 +1,6 @@
"""Tests for AuthService (single point of access for credentials).
-Locks in invariants 7 and 8 from docs-internal/credentials_panel.md:
+Locks in invariants 7 and 8 from docs-internal/ARCHIVE/credentials_panel.md:
- store_api_key requires models=[]
- Memory cache hit path does not query DB on every call
- clear_cache wipes _api_key_cache, _oauth_cache (one merged cache
diff --git a/server/tests/credentials/test_credentials_database.py b/server/tests/credentials/test_credentials_database.py
index 2d219569..beab17be 100644
--- a/server/tests/credentials/test_credentials_database.py
+++ b/server/tests/credentials/test_credentials_database.py
@@ -1,6 +1,6 @@
"""Tests for CredentialsDatabase (encrypted SQLite storage).
-Locks in the two-table separation (invariants 3 and 8 in docs-internal/credentials_panel.md):
+Locks in the two-table separation (invariants 3 and 8 in docs-internal/ARCHIVE/credentials_panel.md):
- get_api_key for a provider only stored in the OAuth table returns None
- get_oauth_tokens for a provider only stored as API key returns None
- Stored ciphertext is never plaintext
diff --git a/server/tests/credentials/test_encryption.py b/server/tests/credentials/test_encryption.py
index 084a818c..cd249d91 100644
--- a/server/tests/credentials/test_encryption.py
+++ b/server/tests/credentials/test_encryption.py
@@ -1,6 +1,6 @@
"""Tests for EncryptionService (Fernet + PBKDF2).
-Locks in invariant 13 from docs-internal/credentials_panel.md:
+Locks in invariant 13 from docs-internal/ARCHIVE/credentials_panel.md:
- Encryption is reversible for unicode and large payloads
- Tampered ciphertext raises ValueError
- Uninitialized service raises RuntimeError
diff --git a/server/tests/credentials/test_google_oauth.py b/server/tests/credentials/test_google_oauth.py
index e2e5357e..9bd6e66e 100644
--- a/server/tests/credentials/test_google_oauth.py
+++ b/server/tests/credentials/test_google_oauth.py
@@ -1,6 +1,6 @@
"""Tests for GoogleOAuth (Workspace OAuth 2.0 with offline access).
-Locks in invariant 11 from docs-internal/credentials_panel.md:
+Locks in invariant 11 from docs-internal/ARCHIVE/credentials_panel.md:
- Authorization URL contains access_type=offline AND prompt=consent
- State store consumed exactly once
"""
diff --git a/server/tests/credentials/test_oauth_utils.py b/server/tests/credentials/test_oauth_utils.py
index 5a98937b..85e3eb6b 100644
--- a/server/tests/credentials/test_oauth_utils.py
+++ b/server/tests/credentials/test_oauth_utils.py
@@ -1,6 +1,6 @@
"""Tests for runtime OAuth redirect URI derivation.
-Locks in invariant 12 from docs-internal/credentials_panel.md:
+Locks in invariant 12 from docs-internal/ARCHIVE/credentials_panel.md:
- get_redirect_uri strips connection.base_url path and converts ws->http
"""
diff --git a/server/tests/credentials/test_twitter_oauth.py b/server/tests/credentials/test_twitter_oauth.py
index 8c64c213..de792ec7 100644
--- a/server/tests/credentials/test_twitter_oauth.py
+++ b/server/tests/credentials/test_twitter_oauth.py
@@ -1,6 +1,6 @@
"""Tests for TwitterOAuth (PKCE flow).
-Locks in invariants 9 and 10 from docs-internal/credentials_panel.md:
+Locks in invariants 9 and 10 from docs-internal/ARCHIVE/credentials_panel.md:
- PKCE state consumed exactly once
- code_challenge = base64url(sha256(code_verifier))
- Authorization URL contains code_challenge_method=S256
diff --git a/server/tests/credentials/test_websocket_handlers.py b/server/tests/credentials/test_websocket_handlers.py
index 14d90bee..58c99cb9 100644
--- a/server/tests/credentials/test_websocket_handlers.py
+++ b/server/tests/credentials/test_websocket_handlers.py
@@ -4,7 +4,7 @@ We invoke the handler functions directly (rather than spinning up the full FastA
app + DI container) so the suite stays under 30s and doesn't pull in Temporal /
LangChain / native LLM SDKs.
-Locks in invariants 1, 5, 6 from docs-internal/credentials_panel.md:
+Locks in invariants 1, 5, 6 from docs-internal/ARCHIVE/credentials_panel.md:
- WebSocket message types and payload shapes
- Status responses use camelCase hasKey / apiKey (matches the
update_api_key_status broadcaster convention)
diff --git a/server/tests/test_task_queue_coverage.py b/server/tests/test_task_queue_coverage.py
index 30685d4c..68add67e 100644
--- a/server/tests/test_task_queue_coverage.py
+++ b/server/tests/test_task_queue_coverage.py
@@ -17,7 +17,7 @@ assumptions that make that activation safe:
queue — a missing entry silently falls back to ``default_pool_size``
which defeats per-queue sizing.
-See docs-internal/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md §5.
+See docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md §5.
"""
import pytest
@@ -84,7 +84,7 @@ class TestTaskQueueCoverage:
assert TaskQueue.DEFAULT in TaskQueue.ALL
assert len(TaskQueue.ALL) >= 9, (
"TaskQueue.ALL shrank below the 9 queues Wave 16 verified — "
- "update docs-internal/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md "
+ "update docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md "
"if a queue was deliberately removed."
)