Skip to content

Self-improving AI Employees for everyone

docs(contributing): point-first recipes, testing section, and stale-guide fixes

trohitg4434fa03c077
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2db660c8..929fdcf8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,11 +17,11 @@ See [SETUP.md](docs-internal/SETUP.md) for environment setup and [SCRIPTS.md](do
At a glance:
-- **~118 workflow nodes** across 26 categories (AI, agents, social, Android, Google Workspace, email, browser, documents, code, proxies, utilities; one self-contained plugin folder per node under `server/nodes/<group>/`)
+- **115+ workflow nodes** across ~30 palette groups (live count: glob `server/nodes/**/__init__.py`; group list: `server/nodes/groups.py`; one self-contained plugin folder per node under `server/nodes/<group>/`)
- **12 LLM providers** via a hybrid native SDK + LangChain architecture (11 chat-model nodes; xAI native-chat-only)
-- **16 specialized AI agents** with the Agent Teams delegation pattern
+- **Specialized AI agents** with the Agent Teams delegation pattern — SSOT is the `AI_AGENT_TYPES` frozenset in `server/constants.py`, which spans the base/specialized/team-lead agents plus the CLI-backed (`claude_code_agent`, `rlm_agent`) and Vertex-hosted (`vertex_managed_agent`) variants; `codex_agent` is a sibling CLI-agent plugin
- **WebSocket-first API** replacing most REST endpoints (live handler count = `MESSAGE_HANDLERS` + plugin registries)
-- **63 built-in skills** across 12 categories, editable in-UI with SKILL.md defaults on disk
+- **65+ built-in skills**, editable in-UI with SKILL.md defaults on disk (live count: glob `server/skills/**/SKILL.md`)
- **Three execution modes** with automatic fallback: Temporal distributed, Redis parallel, sequential
## How Workflows Execute
@@ -30,7 +30,7 @@ At a glance:
[WorkflowService](server/services/workflow.py) is a thin facade that routes each run through one of three execution modes. Every run has an isolated `ExecutionContext` with no shared global state, orchestrated by Conductor's decide pattern (`_workflow_decide` under a Redis `SETNX` lock). Layers are computed via Kahn's algorithm and each layer runs via `asyncio.gather()`. Results are cached by input hash (Prefect pattern), failed nodes go to a Dead Letter Queue, and a `RecoverySweeper` handles crashes via heartbeats.
-Deep dives: [DESIGN.md](docs-internal/DESIGN.md) - [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) - [event_waiter_system.md](docs-internal/event_waiter_system.md)
+Deep dives: [DESIGN.md](docs-internal/DESIGN.md) - [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) - [event_framework.md](docs-internal/event_framework.md)
## AI Agent System
@@ -38,7 +38,7 @@ Deep dives: [DESIGN.md](docs-internal/DESIGN.md) - [TEMPORAL_ARCHITECTURE.md](do
AI execution splits into two paths. `execute_chat()` for direct chat completions delegates every provider to the native SDK layer in [services/llm/](server/services/llm/) via `ChatUnifier` (12 providers, lazy imports, normalized `LLMResponse`; Groq, Cerebras, and the local servers ride the OpenAI-compatible client with a custom `base_url` — the old chat-path LangChain fallback is retired). `execute_agent()` and `execute_chat_agent()` build a LangChain chat model (`ChatOpenAI` / `ChatAnthropic` / etc.) and drive it through `_run_agent_loop` — a plain async `for iteration in range(max):` that calls `chat_model.ainvoke`, dispatches any `tool_calls`, appends `ToolMessage` results, and loops. Team leads (`orchestrator_agent`, `ai_employee`) auto-inject `delegate_to_<type>` tools for every agent connected to their `input-teammates` handle. The RLM Agent uses a REPL-based recursive language model pattern. Long-running activities (browser automation, claude_code_agent) stay alive across Temporal's 2-minute heartbeat window via per-message `activity.heartbeat()` calls in the WebSocket read loop.
-Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [native_llm_sdk.md](docs-internal/native_llm_sdk.md) - [agent_teams.md](docs-internal/agent_teams.md) - [memory_compaction.md](docs-internal/memory_compaction.md)
+Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [native_llm_sdk.md](docs-internal/native_llm_sdk.md) - [agent_teams.md](docs-internal/agent_teams.md) - [memory_compaction.md](docs-internal/memory_compaction.md) - [cli_agent_framework.md](docs-internal/cli_agent_framework.md)
## Repository Map
@@ -53,8 +53,10 @@ Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [nati
| `server/services/temporal/` | Distributed execution via Temporal | [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) |
| `server/routers/websocket.py` | WebSocket endpoint + core `MESSAGE_HANDLERS` (plugins register more via `ws_handler_registry`) | [status_broadcaster.md](docs-internal/status_broadcaster.md) |
| `server/core/` | Cache, encryption, DI container, config | [credentials_encryption.md](docs-internal/credentials_encryption.md) |
-| `server/skills/` | 63 skill SKILL.md files across 12 folders | [GUIDE.md](server/skills/GUIDE.md) |
-| `server/config/` | llm_defaults.json, pricing.json, model_registry.json, email_providers.json, google_apis.json | [pricing_service.md](docs-internal/pricing_service.md) |
+| `server/skills/` | Skill SKILL.md files, one folder per agent domain (live count: glob `server/skills/**/SKILL.md`) | [GUIDE.md](server/skills/GUIDE.md) |
+| `server/config/` | llm_defaults.json, pricing.json, model_registry.json, email_providers.json, google_apis.json, credential_providers.json, ai_cli_providers.json, node_allowlist.json | [pricing_service.md](docs-internal/pricing_service.md), [node_allowlist.md](docs-internal/node_allowlist.md) |
+| `server/tests/` | Contract-test invariants + per-category node tests + `NodeTestHarness` | [tests/nodes/_harness.py](server/tests/nodes/_harness.py), [tests/credentials/README.md](server/tests/credentials/README.md) |
+| `client/src/` (styling + themes) | Tailwind tokens, shadcn primitives, the 12-theme contract | [frontend_architecture.md](docs-internal/frontend_architecture.md), [theme_system.md](docs-internal/theme_system.md) |
| `docs-internal/` | In-repo architecture deep dives (50+ files) | Index below |
## How to Contribute Features
@@ -64,40 +66,62 @@ Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [nati
The diagram above shows the full lifecycle of a workflow node: one self-contained Python plugin folder that auto-registers on import and renders itself on the frontend with zero TypeScript edits. Use these recipes as a starting point:
**Add a workflow node**
-- Author a plugin folder: `server/nodes/<category>/<node>/__init__.py` — subclasses `BaseNode` (or `ActionNode` / `TriggerNode` / `ToolNode`), declares Pydantic `Params`/`Output` + `@Operation` methods; auto-registers on import
-- Add a contract test: `server/tests/nodes/test_<category>.py`
-- Guide: [plugin_system.md](docs-internal/plugin_system.md) + [server/nodes/README.md](server/nodes/README.md)
+- Start at [node_creation.md](docs-internal/node_creation.md) (the decision tree routes action / trigger / tool / dual-purpose / agent work), copy the recipe from [server/nodes/README.md](server/nodes/README.md), and reach for [plugin_system.md](docs-internal/plugin_system.md) as the deep reference
+- One plugin folder: `server/nodes/<category>/<node>/__init__.py` — subclasses `ActionNode` / `TriggerNode` / `ToolNode`, declares Pydantic `Params`/`Output` + `@Operation` methods; auto-registers on import, zero frontend edits
+- Icon = `icon.svg` in the folder, color = `meta.json` (never class attributes); raise `NodeUserError` for user-correctable failures
+- Add a behavioral test in `server/tests/nodes/test_<category>.py` (the invariant suites cover the contract automatically — see Testing below)
**Add an LLM provider**
-- OpenAI-compatible (DeepSeek, Kimi, Mistral pattern): config-only in `server/config/llm_defaults.json`
-- Custom-SDK provider: new file in `server/services/llm/providers/` that calls `register_provider(ProviderSpec(...))` at module bottom (lazy factory + `sdk_exception_refs`)
-- Backend plugin: `server/nodes/model/<provider>_chat_model/__init__.py`
-- Guide: [native_llm_sdk.md](docs-internal/native_llm_sdk.md)
+- Guide: [native_llm_sdk.md](docs-internal/native_llm_sdk.md) → "Adding a New Provider"
+- OpenAI-compatible (DeepSeek, Kimi, Mistral pattern): config-only in `server/config/llm_defaults.json` + the compat list in `services/llm/providers/_compat.py`
+- Custom-SDK provider: new file in `server/services/llm/providers/` that calls `register_provider(ProviderSpec(...))` at module bottom (lazy factory + `sdk_exception_refs`; never touch the legacy `factory.py`)
+- Chat-model node plugin: `server/nodes/model/<provider>_chat_model/__init__.py`; for agent-dropdown exposure also extend the `provider` Literal in `nodes/agent/{ai_agent,chat_agent,_specialized}` and `detect_ai_provider` in `server/constants.py`
**Add a dual-purpose tool (workflow node + AI tool)**
-- Plugin folder under `server/nodes/<category>/<name>/` with `group: ['category', 'tool']` and `usable_as_tool = True`
-- Pydantic `Params` doubles as the LLM-visible tool schema (no separate `_get_tool_schema` entry)
-- Guide: [node_creation.md](docs-internal/node_creation.md)
+- Guide: [node_creation.md](docs-internal/node_creation.md); live references: the whatsapp / twitter / stripe folders
+- Plugin folder with `group: ['category', 'tool']` and `usable_as_tool = True`; the Pydantic `Params` doubles as the LLM-visible tool schema (keep it flat — no nested models / `$defs`)
+- If you give the tool a short `tool_name` that isn't `<snake_case_of_node_type>` AND ship a paired skill, add a `visuals.json` alias entry keyed by the tool name carrying **icon and color** — otherwise the Master Skill row renders blank (locked by `server/tests/test_skill_icon_resolution.py`)
**Add a specialized AI agent**
+- Guide: [node_creation.md](docs-internal/node_creation.md) + [agent_architecture.md](docs-internal/agent_architecture.md)
- Add the plugin under `server/nodes/agent/<name>/` (extends `SpecializedAgentBase` from `server/nodes/agent/_specialized.py`)
-- Add the agent's `type` string to `AI_AGENT_TYPES` in `server/constants.py` and to the delegation-check tuple in `server/services/handlers/tools.py::execute_tool()` so parent agents' `delegate_to_*` tools find it (both flagged as tech debt)
-- Guide: [node_creation.md](docs-internal/node_creation.md)
+- Single cross-cutting edit: add the agent's `type` string to the `AI_AGENT_TYPES` frozenset in `server/constants.py` — delegation dispatch imports that frozenset, nothing else to update
+- CLI-backed agents (Claude Code / Codex shape) follow [cli_agent_framework.md](docs-internal/cli_agent_framework.md); Vertex-hosted agents follow the `vertex_managed_agent` plugin
**Add a skill**
-- New folder under `server/skills/<category>/`
-- Create `SKILL.md` with YAML frontmatter + markdown body
-- Guide: [GUIDE.md](server/skills/GUIDE.md)
+- Guide: [GUIDE.md](server/skills/GUIDE.md) (folder structure, SKILL.md frontmatter, and the tool-naming contract that drives the skill's icon)
+- New folder under `server/skills/<domain>/<skill-name>/SKILL.md` with YAML frontmatter + markdown body
-**Add an event-based trigger**
-- Author a `TriggerNode` plugin under `server/nodes/<category>/<name>/`
-- Canary path (Wave 12, preferred): `register_canary_trigger_type(node_type, cloudevent_type)` + emit `WorkflowEvent`s via `dispatch.emit` from the plugin's `_events.py`
-- Legacy path (non-canary types only): register in `TRIGGER_REGISTRY` + add a filter builder in `server/services/event_waiter.py`
-- Guides: [event_framework.md](docs-internal/event_framework.md), [node_creation.md](docs-internal/node_creation.md), [event_waiter_system.md](docs-internal/event_waiter_system.md) (legacy)
+**Add an event source / trigger (Wave 12)**
+- Guides: [node_creation.md](docs-internal/node_creation.md) → Wave 12 recipe (authoring) → [event_framework.md](docs-internal/event_framework.md) (Temporal routing + ops) → [stripe_service.md](docs-internal/stripe_service.md) (the reference implementation)
+- Pick the source shape: `DaemonEventSource` (CLI daemon), `WebhookSource` + `WebhookTriggerNode` (signed webhooks, with a verifier from `services.events.verifiers`), or `PollingEventSource` (API polling)
+- Register via `register_canary_trigger_type(node_type, cloudevent_type)` + emit `WorkflowEvent`s via `dispatch.emit` from the plugin's `_events.py`; plugin-owned filters go through `register_filter_builder` — never hand-edit `event_waiter.py` ([event_waiter_system.md](docs-internal/event_waiter_system.md) is historical, pre-Wave-11)
-**Integrate a new external service with OAuth**
-- Reference implementation: Google Workspace (7 nodes sharing one OAuth connection)
-- Guide: [new_service_integration.md](docs-internal/new_service_integration.md)
+**Integrate a CLI-managed-auth service (Stripe / Vercel / GitHub shape)**
+- Guide: [node_creation.md](docs-internal/node_creation.md) → "CLI-managed auth" recipe; references: [stripe_service.md](docs-internal/stripe_service.md) (two-step browser OAuth), [vercel_service.md](docs-internal/vercel_service.md) (device-flow variant), [github_service.md](docs-internal/github_service.md) (gh owns auth entirely)
+- The external CLI owns the real tokens; the plugin writes marker tokens via `auth_service.store_oauth_tokens(provider, "cli-managed", "cli-managed")` and broadcasts the generic `credential_catalogue_updated` event — zero per-provider frontend code
+- `_install.py` auto-downloads the pinned CLI binary into the shared packages tree
+
+**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)
+
+**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)
+
+**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
+- New themes follow theme_system.md → "Adding a new theme" (per-theme CSS file + tokens; no component code changes — that is the contract)
+- New backend uiHint flags need two frontend-side edits: `INodeProperties.ts` + the `known` set in `server/tests/test_node_spec.py`
+
+## Testing Your Contribution
+
+- **Contract invariants run automatically.** `server/tests/test_plugin_contract.py` and `test_node_spec.py` iterate every registered plugin and assert the declared shape — a new node is covered the moment it imports. `test_plugin_self_containment.py` enforces the no-cross-plugin-imports rule; `test_skill_icon_resolution.py` asserts every skill resolves an icon.
+- **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.
## Local Dev Quick Reference
@@ -130,9 +154,15 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.
| [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 |
+| [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 |
-| [event_waiter_system.md](docs-internal/event_waiter_system.md) | Push-based trigger waiters |
+| [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 |
+| [event_waiter_system.md](docs-internal/event_waiter_system.md) | Push-based trigger waiters *(historical, pre-Wave-11 — canvas-Run path only)* |
| [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 |
@@ -142,9 +172,18 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.
| [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 |
| [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 guide |
+| [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)* |
| [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 |
+| [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 |
+| [performance.md](docs-internal/performance.md) | Cold-start measurements, optimisation history, anti-patterns |
+| [release_build_pipeline.md](docs-internal/release_build_pipeline.md) | npm-distribution build pipeline (tsgo, esbuild sidecar, bytecode) |
| [Skill Creation Guide](server/skills/GUIDE.md) | How to create new skills |
## Community
diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.md
index b3e0377c..444a632b 100644
--- a/docs-internal/agent_architecture.md
+++ b/docs-internal/agent_architecture.md
@@ -40,7 +40,7 @@ WorkflowService.execute_node() server/services/workflow.py
|
v
NodeExecutor._dispatch() server/services/node_executor.py
- Handler registry lookup via functools.partial
+ Plugin handler registry lookup (plain dict: self._handlers.get(node_type))
Dispatches via BaseNode.execute() to the agent plugin's execute_op()
(server/nodes/agent/<plugin>/__init__.py — Wave 11 deleted handle_ai_agent /
handle_chat_agent; agent logic moved into the plugin folder)
@@ -80,7 +80,7 @@ Result broadcast via WebSocket
| `client/src/hooks/useExecution.ts` | Frontend execution trigger, sends nodes + edges |
| `server/routers/websocket.py` | WebSocket handler `handle_execute_node()` |
| `server/services/workflow.py` | Facade, builds context, delegates to NodeExecutor |
-| `server/services/node_executor.py` | Handler registry, dispatches via `functools.partial` |
+| `server/services/node_executor.py` | Plugin handler registry, plain dict dispatch (`self._handlers.get(node_type)`) |
| `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`) |
@@ -394,14 +394,16 @@ shared keyword bundle; `_specialized.py` is the single body shared by all
chat-agent-path specialized agents. Glob `server/nodes/agent/` for the
authoritative agent list, or read `AI_AGENT_TYPES` in
[`server/constants.py`](../server/constants.py) — do not hand-maintain a
-count here. As of this writing `AI_AGENT_TYPES` lists 17 entries: the two
-base agents (`aiAgent`, `chatAgent`), 11 specialized agents
+count here. The frozenset currently spans: the two
+base agents (`aiAgent`, `chatAgent`), the specialized agents
(`android_agent`, `coding_agent`, `web_agent`, `task_agent`, `social_agent`,
`travel_agent`, `tool_agent`, `productivity_agent`, `payments_agent`,
-`consumer_agent`, `autonomous_agent`) plus the 2 team leads
-(`orchestrator_agent`, `ai_employee`), and the 2 CLI/REPL agents that bypass
-the standard loop (`rlm_agent`, `claude_code_agent`). `codex_agent` is a
-sibling plugin folder on the same CLI-agent path.
+`consumer_agent`, `autonomous_agent`), the 2 team leads
+(`orchestrator_agent`, `ai_employee`), the 2 CLI/REPL agents that bypass
+the standard loop (`rlm_agent`, `claude_code_agent`), and
+`vertex_managed_agent` (Vertex-hosted, own dispatch path). `codex_agent` is
+a sibling plugin folder on the same CLI-agent path but is not in the
+frozenset.
### Temporal dispatch routing
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index fb3f03f7..ffdd363b 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -184,9 +184,10 @@ Each Phase-A milestone has a verification command:
| 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 |
-Full test surface lands in Phase A9. Phase B (plugin `_events.py`
-modules) + Phase C (Temporal trigger-waiter migration) + Phase D
-(admin handlers + DLQ) build on this foundation.
+Full test surface landed in Phase A9. Phase B (plugin `_events.py`
+modules), Phase C (Temporal trigger-waiter migration), and Phase D
+(admin handlers; the custom DLQ table was dropped — see the status
+table and the section below) built on this foundation.
## Failure inspection — no separate DLQ table
@@ -200,7 +201,7 @@ inspection surface:
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.
-Wave 12 D3 (pending) adds thin WS handlers that wrap these Visibility queries for the FE admin surface, so operators can inspect failed runs without leaving the OpenCompany UI.
+Wave 12 D3 (shipped — see the status table) added thin WS handlers (`list_canary_listeners` / `list_canary_schedules` / `get_workflow_failure_history`) that wrap these Visibility queries for the FE admin surface, so operators can inspect failed runs without leaving the OpenCompany UI.
## Wave 13 fixes
diff --git a/docs-internal/native_llm_sdk.md b/docs-internal/native_llm_sdk.md
index a202a7d4..92e947d8 100644
--- a/docs-internal/native_llm_sdk.md
+++ b/docs-internal/native_llm_sdk.md
@@ -21,16 +21,27 @@ server/services/llm/
|-- __init__.py Public API exports
|-- protocol.py Message, ToolDef, ToolCall, Usage, LLMResponse, LLMProvider (Protocol)
|-- config.py ProviderConfig, PROVIDER_CONFIGS (built from llm_defaults.json)
-|-- factory.py create_provider() lazy-import factory, NATIVE_PROVIDERS set
+|-- registry.py ProviderSpec + register_provider() — the live provider entry point;
+| sdk_exception_refs are lazy "module:Class" strings resolved at except time
+|-- unifier.py ChatUnifier — the dispatch facade execute_chat delegates every provider to;
+| translates typed SDK errors -> NodeUserError
+|-- vertex.py Vertex / Agent-Platform key handling
+|-- factory.py LEGACY — create_provider()/NATIVE_PROVIDERS no longer consulted by ai.py
|-- messages.py filter_empty_messages, is_valid_message_content
`-- providers/
|-- __init__.py
|-- anthropic.py AnthropicProvider (anthropic SDK)
|-- openai.py OpenAIProvider (openai SDK)
|-- gemini.py GeminiProvider (google-genai SDK)
- `-- openrouter.py OpenRouterProvider (extends OpenAIProvider with headers)
+ |-- openrouter.py OpenRouterProvider (extends OpenAIProvider with headers)
+ `-- _compat.py Registers the 8 OpenAI-compatible providers (xai, deepseek, kimi,
+ mistral, groq, cerebras, ollama, lmstudio) via base_url specs
```
+Each provider module calls `register_provider(ProviderSpec(...))` at module
+bottom — that side-effect IS the registration contract; there is no central
+provider list to edit.
+
## Supported Providers
The native layer currently supports **12 providers**, grouped by implementation:
@@ -100,7 +111,7 @@ Ollama and LM Studio expose an OpenAI-compatible `/v1` HTTP API, so they ride th
**Both servers must have a model loaded** for the probe to return entries. The validator's "no models loaded" message is symmetric across providers.
-**Runtime path** — `execute_chat()` and `execute_agent()` read `{provider}_proxy` via `auth.get_api_key()` and pass it as `proxy_url` to `create_provider()`. `OpenAIProvider.__init__` overrides `kwargs["base_url"]` with the user's URL and forces `api_key="ollama"` (the documented placeholder for unauthenticated local servers). The openai SDK then sends `POST {user_url}/chat/completions` — **traffic stays on the user's machine, never reaches api.openai.com**.
+**Runtime path** — `execute_chat()` and `execute_agent()` read `{provider}_proxy` via `auth.get_api_key()` and pass it as `proxy_url` into the provider build (`ChatUnifier` -> `spec.factory(...)`). `OpenAIProvider.__init__` overrides `kwargs["base_url"]` with the user's URL and forces `api_key="ollama"` (the documented placeholder for unauthenticated local servers). The openai SDK then sends `POST {user_url}/chat/completions` — **traffic stays on the user's machine, 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.
@@ -145,40 +156,32 @@ class LLMResponse:
Downstream code never special-cases a provider SDK shape.
-## Factory and Lazy Imports
+## Registry, Unifier, and Lazy Imports
-Each provider is imported only when first used to avoid loading large SDKs at startup:
+Providers self-register and are imported only when first used, so no SDK
+loads at startup (locked by `tests/llm/test_lazy_sdk_imports.py`):
```python
-# server/services/llm/factory.py
-def create_provider(provider: str, api_key: str, *, proxy_url: Optional[str] = None) -> LLMProvider:
- if provider == "anthropic":
- from services.llm.providers.anthropic import AnthropicProvider
- return AnthropicProvider(api_key, proxy_url=proxy_url)
-
- if provider == "openai":
- from services.llm.providers.openai import OpenAIProvider
- return OpenAIProvider(api_key, proxy_url=proxy_url)
-
- if provider == "gemini":
- from services.llm.providers.gemini import GeminiProvider
- return GeminiProvider(api_key, proxy_url=proxy_url)
-
- if provider == "openrouter":
- from services.llm.providers.openrouter import OpenRouterProvider
- return OpenRouterProvider(api_key, proxy_url=proxy_url)
-
- # OpenAI-compatible providers: reuse OpenAIProvider with base_url from config
- from services.llm.config import get_provider_config
- config = get_provider_config(provider)
- if config and config.base_url:
- from services.llm.providers.openai import OpenAIProvider
- return OpenAIProvider(api_key, base_url=config.base_url, proxy_url=proxy_url)
-
- raise ValueError(f"Unknown provider: {provider}")
+# server/services/llm/providers/anthropic.py — bottom of the module
+register_provider(
+ ProviderSpec(
+ name="anthropic",
+ factory=lambda api_key, **kw: AnthropicProvider(api_key, **kw), # lazy: class imported here only
+ sdk_exception_refs=("anthropic:APIError",), # "module:Class" string, resolved at except time
+ )
+)
```
-`is_native_provider(name)` is the gate used by `AIService.execute_chat()` to choose the native path vs LangChain fallback.
+At call time `ChatUnifier.chat(provider=...)` looks the spec up via
+`registry.get_provider(name)` and invokes `spec.factory(...)`. The unifier
+also owns error translation: typed SDK exceptions (resolved lazily from
+`sdk_exception_refs` via `pkgutil.resolve_name`) become `NodeUserError`
+with a user-correctable message. There is no per-provider branch anywhere
+in `ai.py`.
+
+`factory.py` (`create_provider` / `is_native_provider` / `NATIVE_PROVIDERS`)
+is **legacy** — it still exists on disk but is no longer consulted by
+`ai.py`; do not extend it.
## Config-Driven Base URLs
@@ -211,7 +214,7 @@ Adding a new OpenAI-compatible provider is a pure config change:
}
```
-No new provider class, no new import. The factory's fallback branch picks up `base_url` and reuses `OpenAIProvider`.
+No new provider class, no new import. `providers/_compat.py` registers a spec whose factory reuses `OpenAIProvider` with the config's `base_url`.
## Native Path vs LangChain Path
@@ -223,17 +226,15 @@ execute_agent(parameters, node_id) -> LangChain chat model +
execute_chat_agent(parameters, node_id) -> LangChain chat model + _run_agent_loop
```
-**`execute_chat()` routing:**
+**`execute_chat()` routing (no per-provider branch, no LangChain fallback):**
```
node_type / model selects provider
|
v
-is_native_provider(provider)?
+ChatUnifier.chat(provider=...)
|
- +-- yes --> create_provider(...) -> provider.chat(...) -> LLMResponse
- |
- +-- no --> self.create_model(...) -> chat_model.invoke(...) -> extract to LLMResponse shape
+ +--> registry.get_provider(name) -> spec.factory(...) -> provider.chat(...) -> LLMResponse
```
**`execute_agent()` and `execute_chat_agent()` routing:**
@@ -349,7 +350,7 @@ AI providers support optional proxy-based authentication — requests route thro
**Configuration:** proxy URLs are stored in the credentials DB under the `{provider}_proxy` pattern (e.g., `anthropic_proxy`, `openai_proxy`). Falls back to direct API key if no proxy configured. This is the SAME mechanism the native Ollama / LM Studio path uses (see "Local LLM Providers" above) — the validator persists the user's server URL under `{provider}_proxy`, and at runtime it carries into `OpenAIProvider`'s `base_url`.
-**Native path:** `create_provider(name, api_key, proxy_url=url)`. **LangChain path:** `create_model()` sets `base_url`:
+**Native chat path:** `proxy_url` flows through `ChatUnifier` into `spec.factory(...)`. **LangChain agent path:** `create_model()` sets `base_url`:
```python
def create_model(self, provider: str, api_key: str, model: str,
@@ -404,30 +405,31 @@ class ProviderDefaults(SQLModel, table=True):
# server/nodes/model/openrouter_chat_model/__init__.py
class OpenRouterChatModel(ChatModelBase):
type = "openrouterChatModel"
- metadata = NodeMetadata(
- display_name="OpenRouter",
- icon="lobehub:openrouter", # asset:<key>, lobehub:<brand>, or emoji
- color="#6366F1",
- component_kind="model", # routes to SquareNode in Dashboard.tsx
- )
+ display_name = "OpenRouter"
+ component_kind = "model" # routes to SquareNode via COMPONENT_BY_KIND
class Params(ChatModelBase.Params):
# provider-specific overrides; everything else inherits from ChatModelBase
...
```
+Icon and color are NOT class attributes (removed in F1): drop `icon.svg` in
+the plugin folder or add a `visuals.json` entry (`"openrouterChatModel":
+{"icon": "lobehub:openrouter"}`), and put the color in the folder's
+`meta.json`.
+
**Backend steps:**
1. **OpenAI-compatible provider** (DeepSeek, Kimi, Mistral pattern):
- Add an entry to `llm_defaults.json` with `base_url`, `default_model`, `detection_patterns`, `max_output_tokens._default`, `context_length._default`, `temperature_range`.
- - Add the provider name to `NATIVE_PROVIDERS` in `factory.py` if you want `execute_chat()` to route natively.
+ - Add the provider name to the compat list in `services/llm/providers/_compat.py` — its import loop calls `register_provider(ProviderSpec(...))` for every listed name.
- The LangChain agent path needs no Python branching — `create_model()` reuses `ChatOpenAI` with `base_url` from `llm_defaults.json`.
2. **Custom-SDK provider** (Anthropic, Gemini pattern):
- Create `services/llm/providers/<name>.py` implementing the `LLMProvider` protocol.
- - Add a branch in `create_provider()` in `factory.py`.
- - Add the provider name to the dedicated-provider set and `NATIVE_PROVIDERS`.
+ - At module bottom call `register_provider(ProviderSpec(name=..., factory=..., sdk_exception_refs=("sdk_module:ErrorClass",)))` — the lazy factory + string exception refs keep the SDK unimported until first use (never import the SDK at registration; locked by `tests/llm/test_lazy_sdk_imports.py`).
- Add a config entry in `llm_defaults.json` (no `base_url` needed if the SDK handles URLs itself).
+ - Do NOT touch `factory.py` — it is legacy and no longer consulted.
3. **Credentials + agent exposure:**
- Add a `Credential` subclass in `server/nodes/model/_credentials.py` — surfaces in the Credentials Modal automatically.
@@ -440,8 +442,10 @@ class OpenRouterChatModel(ChatModelBase):
| `server/nodes/model/<provider>_chat_model/__init__.py` | Plugin entry — metadata + Params + auto-registers |
| `server/nodes/model/_credentials.py` | `Credential` subclass per provider |
| `server/config/llm_defaults.json` | base_url + supported_params + temperature constraints (no hardcoded URLs in Python) |
-| `server/services/llm/providers/<provider>.py` | Native SDK provider (Protocol-based) |
-| `server/services/ai.py` | Routing: native chat path + LangChain agent path |
+| `server/services/llm/providers/<provider>.py` | Native SDK provider (Protocol-based) + `register_provider(ProviderSpec)` at module bottom |
+| `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/ai.py` | Routing: native chat path (via ChatUnifier) + LangChain agent path |
| `client/src/Dashboard.tsx` | Generic `COMPONENT_BY_KIND` dispatch — no per-provider entry needed |
## Related Docs
diff --git a/docs-internal/new_service_integration.md b/docs-internal/new_service_integration.md
index 0843c377..745164a9 100644
--- a/docs-internal/new_service_integration.md
+++ b/docs-internal/new_service_integration.md
@@ -1,5 +1,14 @@
# New Service Integration Guide
+> **⚠️ HISTORICAL — do not follow these steps.** This guide predates
+> Wave 11 and is preserved only as background for reading old code.
+>
+> **Current path for a new service integration:**
+> - Node authoring recipe + decision tree → [node_creation.md](./node_creation.md)
+> - Full plugin reference (credentials, `Connection` facade, six `register_*` hooks, Wave 12 event framework) → [plugin_system.md](./plugin_system.md)
+> - Live OAuth reference implementation → [server/nodes/google/](../server/nodes/google/) (`_oauth.py`, `_router.py`, `_option_loaders.py`, `_auth_helper.py`)
+> - CLI-managed-auth variant (Stripe / Vercel / GitHub shape) → [node_creation.md → CLI-managed auth](./node_creation.md) + [stripe_service.md](./stripe_service.md)
+
> **⚠️ Pre-Wave-11 — historical reference only.**
> Node authoring now happens on the backend: each node is a Python plugin in a self-contained folder under `server/nodes/<category>/<plugin>/__init__.py` that emits a `NodeSpec`. The frontend reads specs via [client/src/lib/nodeSpec.ts](../client/src/lib/nodeSpec.ts) + [adapters/nodeSpecToDescription.ts](../client/src/adapters/nodeSpecToDescription.ts). See [plugin_system.md](./plugin_system.md) and [server/nodes/README.md](../server/nodes/README.md) for the current model. The snippets below that reference `client/src/nodeDefinitions/*` are kept for historical context.
>
@@ -33,6 +42,8 @@ The sections below detail each step using Google Workspace as the reference inte
## Architecture Pattern
+> **Historical diagram.** The "Node Definitions (calendarNodes)" frontend box below no longer exists — node schemas are backend NodeSpec (rendered via `useNodeSpec`), and the credentials modal renders from `server/config/credential_providers.json`.
+
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend │
@@ -524,6 +535,8 @@ async def handle_{operation1}(
## Step 7: AI Tool Schemas
+> **Historical — superseded.** Dual-purpose nodes no longer add schemas to `_get_tool_schema()`: the plugin's Pydantic `Params` class IS the LLM-visible tool schema (`usable_as_tool = True`), and `services/handlers/{service}.py` dispatcher modules no longer exist (logic lives in the plugin's `@Operation` methods). `_get_tool_schema` survives only for delegation schemas. Do not follow this step.
+
Add Pydantic schemas in `server/services/ai.py`:
```python
@@ -768,10 +781,7 @@ Use this checklist when adding a new service:
- [ ] **Frontend Nodes** — none. The `NodeSpec` emitted by the plugin drives the palette, canvas component, and parameter panel automatically (see [node_creation.md](./node_creation.md)).
-- [ ] **AI Tool Integration** (`server/services/ai.py`, `server/services/handlers/tools.py`)
- - [ ] Add Pydantic schemas in `_get_tool_schema()`
- - [ ] Add dispatchers in `execute_tool()`
- - [ ] Add handler functions
+- [ ] **AI Tool Integration** — *(historical; superseded)* set `usable_as_tool = True` on the plugin class; its Pydantic `Params` IS the LLM tool schema. No `_get_tool_schema()` entry, no `execute_tool()` dispatcher, no handler functions.
- [ ] **Output Schemas** (`server/services/node_output_schemas.py`)
- [ ] Add a Pydantic model per node type, register in `NODE_OUTPUT_SCHEMAS`
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index b96ea7a9..f8ef6939 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -66,8 +66,7 @@ class SpecializedAgentBase(ActionNode, abstract=True):
| `type` | Node type string. Matches workflow JSON + registry key. |
| `version` | Int, bumped on breaking changes. Activity name includes it. |
| `display_name` / `subtitle` / `description` | Palette + panel header. |
-| `icon` | `asset:<key>` / `<lib>:<brand>` / URL / emoji. |
-| `color` | Hex or Dracula token. |
+| *(icon / color)* | **Not class attributes** (removed in F1 — declaring them has no effect). Icon: co-located `icon.svg` (or a `visuals.json` entry for emoji / `lobehub:<brand>`); color: co-located `meta.json` `{"color": "#..."}`. Wire format on the NodeSpec stays `asset:<key>` / `<lib>:<brand>` / URL / emoji. |
| `group` | Tuple of palette groupings (first is primary). |
| `component_kind` | Frontend dispatch: `square` / `trigger` / `agent` / `tool` / `model` / `start` / `generic`. |
| `handles` | React Flow handle topology (`input-main`, `output-main`, …). |
@@ -112,6 +111,8 @@ Practical rules for plugin authors:
Defense in depth below the plugin layer: the SQLAlchemy engine in `core/database.py` sets `json_serializer=lambda obj: json.dumps(to_jsonable_python(obj, fallback=str))` (`pydantic_core.to_jsonable_python` — official arbitrary-object → JSON coercion), so every JSON column on the engine tolerates dataclasses / datetimes / enums / sets even if a payload bypasses Output validation. Locked by `tests/test_output_contract.py`.
+**Error convention — `NodeUserError` vs bare `Exception`.** For any failure the user (or the calling LLM) can correct — missing required field, unknown enum value, bad path, service not running — raise `NodeUserError("...")` (exported from `services.plugin`). `BaseNode.execute()` catches it specially: one WARN line in the operator log (no traceback) plus a structured `{success: False, error_type: "NodeUserError", error: ...}` envelope, and the shared Temporal retry policy treats it as **non-retryable** (`services/plugin/scaling.py`) so a bad input doesn't burn three activity attempts. Reserve bare `Exception` / `RuntimeError` for genuine server bugs — those keep the full `logger.exception` traceback.
+
### Auto-derived uiHints
`BaseNode._metadata_dict` (`server/services/plugin/base.py`) calls
@@ -1209,7 +1210,7 @@ without any node-specific code in the frontend or in core services:
API.** Plugin writes synthetic strings (e.g. `"cli-managed"`) on
login completion. The catalogue's existing per-provider `stored`
check at
- [`routers/webhook.py:handle_get_credential_catalogue`](../server/routers/websocket.py)
+ [`routers/websocket.py:handle_get_credential_catalogue`](../server/routers/websocket.py)
uses
`auth_service.get_oauth_tokens(status_hook) is not None` —
identical to Google's OAuth-callback path. The synthetic tokens
diff --git a/server/nodes/README.md b/server/nodes/README.md
index 00511448..d7855d47 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -100,7 +100,9 @@ Match the palette group. Current folders (see
[`groups.py`](./groups.py) for the canonical list):
```
-agent/ — AI agents (ai_agent, chat_agent + 16 specialized/variant incl. 2 team leads)
+agent/ — AI agents (ai_agent, chat_agent + specialized/variant folders incl. 2 team leads,
+ CLI agents (claude_code, codex, rlm) and Vertex agents; SSOT: AI_AGENT_TYPES
+ in server/constants.py + the folder glob)
model/ — LLM chat models (openai, anthropic, gemini, …)
android/ — Android device services
google/ — Google Workspace (gmail / calendar / drive / sheets / …)
@@ -373,6 +375,13 @@ Full reference: [docs-internal/plugin_system.md → "Self-contained plugin folde
`_serialise_tool_result`) expects JSON-compatible data. Likewise
return real lists/dicts, not pre-stringified JSON — LLM-facing
serialization is the dispatcher's job.
+- **Raise `NodeUserError` for user-correctable failures.** Missing
+ required field, unknown enum value, bad path, sidecar not running —
+ `raise NodeUserError("...")` (exported from `services.plugin`) gives
+ the user/LLM a clean one-line WARN + structured envelope with no
+ traceback, and the shared Temporal retry policy skips retries for it
+ (`services/plugin/scaling.py`). Bare `Exception` is for genuine
+ server bugs only — it keeps the full `logger.exception` traceback.
- **Coerce LLM-stringified JSON args at the Params boundary.** Gemini
(and others) sometimes pass array/object tool args as JSON-encoded
strings. Fields that can receive them declare a
@@ -432,11 +441,12 @@ Added in Wave 11 (Mar 2026):
concurrency.
- **11.G** (this doc): Cookbook.
-End state: `services/handlers/` is **4 files / 1.1K LOC** (down from
+End state: `services/handlers/` is **4 files / ~1K LOC** (down from
16 / 12.8K). Only cross-cutting orchestration remains there:
`tools.py` (AI-tool dispatch + agent delegation), `triggers.py`
-(generic event-trigger handler), `google_auth.py` (shared OAuth
-helper), and a 23-line package docstring.
+(generic event-trigger handler), `todo.py` (writeTodos shim), and the
+package docstring (`__init__.py`). The former `google_auth.py` shared
+OAuth helper was retired into `nodes/google/_auth_helper.py`.
Plan + full migration history:
[plugin_system.md](../../docs-internal/plugin_system.md).
diff --git a/server/skills/GUIDE.md b/server/skills/GUIDE.md
index c4165024..eaed1ba0 100644
--- a/server/skills/GUIDE.md
+++ b/server/skills/GUIDE.md
@@ -10,59 +10,43 @@ Skills are organized in subfolders under `server/skills/`:
server/skills/
├── GUIDE.md # This file
├── assistant/ # General-purpose assistant skills
-│ ├── assistant-personality/SKILL.md
-│ ├── compaction-skill/SKILL.md
-│ ├── humanify-skill/SKILL.md
-│ ├── memory-skill/SKILL.md
-│ ├── subagent-skill/SKILL.md
-│ └── task-manager/SKILL.md
+│ advisor, agent-builder-skill, assistant-personality, compaction-skill,
+│ humanify-skill, memory-skill, subagent-skill, task-manager, write-todos-skill
├── android_agent/ # Android device control skills
-│ ├── personality/SKILL.md
-│ ├── battery-skill/SKILL.md
-│ ├── wifi-skill/SKILL.md
-│ ├── bluetooth-skill/SKILL.md
-│ ├── location-skill/SKILL.md
-│ ├── app-launcher-skill/SKILL.md
-│ ├── app-list-skill/SKILL.md
-│ ├── audio-skill/SKILL.md
-│ ├── screen-control-skill/SKILL.md
-│ ├── camera-skill/SKILL.md
-│ ├── motion-skill/SKILL.md
-│ └── environmental-skill/SKILL.md
+│ personality + one skill per Android service node (battery, wifi,
+│ bluetooth, location, app-launcher, app-list, audio, screen-control,
+│ camera, motion, environmental)
├── autonomous/ # Autonomous agent patterns
-│ ├── code-mode-skill/SKILL.md
-│ ├── agentic-loop-skill/SKILL.md
-│ ├── progressive-discovery-skill/SKILL.md
-│ ├── error-recovery-skill/SKILL.md
-│ └── multi-tool-orchestration-skill/SKILL.md
+│ code-mode-skill, agentic-loop-skill, progressive-discovery-skill,
+│ error-recovery-skill, multi-tool-orchestration-skill
+├── cloudflare/ # cloudflare-skill (cf CLI)
├── coding_agent/ # Code execution skills
-│ ├── python-skill/SKILL.md
-│ └── javascript-skill/SKILL.md
+│ python-skill, javascript-skill, monty-skill, file-read-skill,
+│ file-modify-skill, fs-search-skill
+├── github/ # github-skill (gh CLI)
+├── payments_agent/ # stripe-skill
├── productivity_agent/ # Google Workspace skills
-│ ├── gmail-skill/SKILL.md
-│ ├── calendar-skill/SKILL.md
-│ ├── drive-skill/SKILL.md
-│ ├── sheets-skill/SKILL.md
-│ ├── tasks-skill/SKILL.md
-│ └── contacts-skill/SKILL.md
+│ google-gmail-skill, google-calendar-skill, google-drive-skill,
+│ google-sheets-skill, google-tasks-skill, google-contacts-skill
+├── rlm_agent/ # rlm-reasoning-skill
├── social_agent/ # Social messaging skills
-│ ├── whatsapp-send-skill/SKILL.md
-│ ├── whatsapp-db-skill/SKILL.md
-│ ├── twitter-send-skill/SKILL.md
-│ ├── twitter-search-skill/SKILL.md
-│ └── twitter-user-skill/SKILL.md
-├── task_agent/ # Task management skills
-│ ├── timer-skill/SKILL.md
-│ └── cron-scheduler-skill/SKILL.md
-├── travel_agent/ # Location and maps skills
-│ ├── geocoding-skill/SKILL.md
-│ └── nearby-places-skill/SKILL.md
+│ whatsapp-send-skill, whatsapp-db-skill, twitter-send-skill,
+│ twitter-search-skill, twitter-user-skill
+├── task_agent/ # Scheduling skills (timer-skill, cron-scheduler-skill)
+├── terminal/ # Shell skills (shell, bash, powershell, wsl, process-manager)
+├── travel_agent/ # geocoding-skill, nearby-places-skill
+├── vercel/ # vercel-skill (Vercel CLI)
+├── vertex_agent/ # vertex-agent-skill, vertex-agent-admin-skill
└── web_agent/ # Web automation skills
- ├── web-search-skill/SKILL.md
- └── http-request-skill/SKILL.md
+ browser-skill, browser-harness-skill, http-request-skill, apify-skill,
+ crawlee-scraper-skill, proxy-config-skill, duckduckgo-search-skill,
+ brave-search-skill, serper-search-skill, perplexity-search-skill
```
-Each top-level folder (e.g. `assistant`, `android`) appears as an option in the Master Skill node's folder dropdown. Skills inside are discovered recursively via `SKILL.md` files.
+The tree above is a snapshot — the source of truth is the live glob
+`server/skills/*/*/SKILL.md`.
+
+Each top-level folder (e.g. `assistant`, `android_agent`) appears as an option in the Master Skill node's folder dropdown. Skills inside are discovered recursively via `SKILL.md` files.
## Creating a New Skill
@@ -118,7 +102,7 @@ Provide usage guidelines, examples, and constraints.
- Lowercase letters and numbers only
- Words separated by single hyphens
- No consecutive hyphens
-- Examples: `my-skill`, `web-search-skill`, `code-skill`
+- Examples: `my-skill`, `brave-search-skill`, `python-skill`
- Invalid: `My_Skill`, `my--skill`, `MySkill`
### Tool naming — snake_case ↔ camelCase contract