Skip to content

Self-improving AI Employees for everyone

docs: purge drifted claims from the node-creation doc set

trohitgf23290f88699
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index 248245ac..99069bc4 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -63,6 +63,7 @@ server/nodes/<provider>/
├── _credentials.py # ApiKeyCredential subclass
├── _source.py # DaemonEventSource + WebhookSource subclasses
├── _handlers.py # WS_HANDLERS via make_lifecycle_handlers()
+├── _install.py # ensure_<provider>_cli() auto-downloader
├── <provider>_action.py # ActionNode + AI tool — uses run_cli_command
└── <provider>_receive.py # WebhookTriggerNode subclass
```
@@ -90,17 +91,19 @@ reused:
1. **Marker-token write after CLI login completes.** The plugin
writes synthetic strings to `auth_service.store_oauth_tokens`
- with the provider id matching the catalogue's `status_hook`. The
- strings exist purely to flip
- `auth_service.get_oauth_tokens(status_hook) is not None` true,
- which the catalogue handler at
+ with the provider id matching the catalogue entry's key. CLI-managed
+ providers set **no** `status_hook` — the catalogue handler at
[`server/routers/websocket.py:handle_get_credential_catalogue`](../server/routers/websocket.py)
- uses to set `provider.stored = true`. **Same API path Google's
+ resolves them through its `kind == "oauth"` fallback, which keys
+ `auth_service.get_oauth_tokens(provider_id) is not None` off the
+ provider id directly to set `provider.stored = true` (the
+ `status_hook` branch is only for providers that declare one:
+ google / twitter / telegram). **Same storage API path Google's
OAuth callback uses** — no new abstraction.
```python
await auth_service.store_oauth_tokens(
- provider="stripe", # matches status_hook in catalogue JSON
+ provider="stripe", # matches the provider id (catalogue key) — no status_hook needed
access_token="cli-managed", # marker; CLI owns the real auth
refresh_token="cli-managed",
)
@@ -182,7 +185,7 @@ walker does on startup), these registrations happen automatically:
|---|---|---|
| Node class registration | `_NODE_CLASS_REGISTRY` | `BaseNode.__init_subclass__` on class definition |
| Metadata + Pydantic schemas | `NODE_METADATA`, `_DIRECT_MODELS`, `NODE_OUTPUT_SCHEMAS` | same |
-| Handler dispatch | `_PLUGIN_HANDLERS` (merged into `NodeExecutor`) | same |
+| Handler dispatch | `_HANDLER_REGISTRY` (imported into `NodeExecutor` as `_PLUGIN_HANDLERS`) | same |
| Auto-derived `uiHints.isConfigNode: True` | `NODE_METADATA[type]['uiHints']` | `_metadata_dict` runs `_derive_auto_ui_hints(cls.group)` for every plugin in a `('memory', 'tool')` group. Plugin `ui_hints = {...}` always wins. Tells the frontend that the node's panel inherits its parent's main inputs. See [plugin_system.md → Auto-derived uiHints](./plugin_system.md#auto-derived-uihints). |
| Credentials | `CREDENTIAL_REGISTRY` | `Credential.__init_subclass__` when `_credentials.py` is imported |
| Trigger registry + filter builders | `event_waiter.TRIGGER_REGISTRY`, `FILTER_BUILDERS` | back-fill from `TriggerNode` subclasses on first lookup |
@@ -218,9 +221,11 @@ What you **do** still write:
plugin count via `glob server/nodes/**/__init__.py`; invariant total
via `pytest --collect-only`. `services/handlers/` shrank from
12.8K → 1.1K LOC.
-- **Wave 11.H** — Self-contained plugin folders. Five generic
- registries replace per-plugin hardcoding in core. Telegram is the
- reference.
+- **Wave 11.H** — Self-contained plugin folders. Six generic
+ registries replace per-plugin hardcoding in core (five at 11.H;
+ `register_router` landed in 11.I), plus newer `register_*`
+ entrypoints for webhook sources / option loaders / OAuth callback
+ paths / canary trigger types. Telegram is the reference.
- **Wave 12** — Generalized event framework
([`services/events/`](../server/services/events/)). `EventSource`
hierarchy + CloudEvents-shaped envelope + verifier registry +
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index 5887a1ff..d5aeb062 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -21,7 +21,8 @@ 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 self-contained folder (`AcmeSearchNode`) declares `type` /
+A single file (`server/nodes/search/acme_search.py`, class
+`AcmeSearchNode`) declares `type` /
`display_name` / `group` / `component_kind` / `handles` /
`credentials` / `task_queue` / `usable_as_tool` / `Params` / `Output`
plus one `@Operation` method, and nothing else.
@@ -34,7 +35,7 @@ plus one `@Operation` method, and nothing else.
- `_NODE_CLASS_REGISTRY` indexes the class itself so Temporal workers
and tool dispatch can look it up by type.
- NodeSpec emits automatically via
- `GET /api/schemas/nodes/exampleSearch/spec.json`.
+ `GET /api/schemas/nodes/acmeSearch/spec.json`.
- `_PLUGIN_HANDLERS` merge in `NodeExecutor` makes it runnable.
- The node appears in the Component Palette under its group
(search + tool) at the next browser reload.
@@ -704,8 +705,8 @@ server/
## Contract invariants
-`server/tests/test_plugin_contract.py` — 16 invariants enforced on
-every CI run. Examples:
+`server/tests/test_plugin_contract.py` — contract invariants enforced
+on every CI run (live count via `pytest --collect-only`). Examples:
- Non-empty `type` / `display_name` / `group` per class.
- `Params` + `Output` must be Pydantic `BaseModel` subclasses.
diff --git a/server/nodes/README.md b/server/nodes/README.md
index 94ddfb88..15153901 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -141,7 +141,7 @@ these first before writing new code:
|---|---|---|
| `agent/` | `_inline.prepare_agent_call` | One-shot pre-dispatch for every agent (memory + skill + tool + teammate collection) |
| `agent/` | `_specialized.SpecializedAgentBase` | Base for 13 specialized agents |
-| `model/` | `_base.ChatModelBase` | 9 chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` |
+| `model/` | `_base.ChatModelBase` | 11 chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` |
| `android/` | `_base.AndroidServiceBase` | 16 Android services inherit; payload translation + `SERVICE_ID_MAP` lives on this base |
| `android/` | `_base.execute_android_toolkit` / `execute_android_service_tool` | AI-tool dispatchers — called from `services/handlers/tools.py` for the toolkit aggregator + direct service tool branches |
| `code/` | `_base.CodeExecutorBase` + `_nodejs.NodeJSClient` | Python/JS/TS executors; `monty_executor/` is sandboxed Python via `pydantic-monty` (enforced limits + opt-in capabilities) |
@@ -182,7 +182,7 @@ from ._credentials import TwitterCredential # shared with 3 sibling
| `nodes/twitter/` | `TwitterCredential` (OAuth2 + PKCE) | twitter_send / _search / _user / _receive |
| `nodes/telegram/` | `TelegramCredential` (bot token + owner chat id) | telegram_send / _receive |
| `nodes/scraper/` | `ApifyCredential` (Bearer) | apify_actor |
-| `nodes/model/` | 10 LLM classes (`OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai`) | 9 chat models |
+| `nodes/model/` | 12 LLM classes (`OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / Xai / Ollama / LMStudio`) | 11 chat models |
| `nodes/search/` | `BraveSearch / Serper / Perplexity` inlined in each plugin file | single-use per plugin |
Declare inline only when genuinely single-use (see
@@ -199,8 +199,9 @@ wiring beyond the import statement.
## Contract invariants
-`server/tests/test_plugin_contract.py` enforces 16 invariants on
-every plugin. Common ones you'll trip:
+`server/tests/test_plugin_contract.py` enforces the contract
+invariants on every plugin (live count via `pytest --collect-only`).
+Common ones you'll trip:
- `type` / `display_name` / `group` must be non-empty.
- `Params` + `Output` must be Pydantic `BaseModel` subclasses.
@@ -267,6 +268,16 @@ package's `__init__.py` — the consumer never imports your folder.
All six are idempotent (same callable / class for the same key is a
no-op; conflicts raise `ValueError`).
+These six are the core self-contained-folder set; newer concerns have
+their own generic `register_*` entrypoints in the same spirit —
+`services.events.register_webhook_source`,
+`services.ws_handler_registry.register_option_loader` /
+`register_oauth_callback_path`,
+`services.deployment.canary_registry.register_canary_trigger_type`,
+`services.deployment.poll_registry.register_poll_coroutine_factory`,
+`services.plugin.edge_walker.register_master_skill_expander`, and
+`services.plugin.social_provider_registry.register_social_send_handler`.
+
**Register, don't edit the consumer.** Never edit `event_waiter.py`,
`status_broadcaster.py`, or `routers/websocket.py` to add a plugin's
handler / filter / refresh — call the matching `register_*` from your