Skip to content

Self-improving AI Employees for everyone

docs: sweep — align all docs with post-F4.B + F7 + CloudEvents shipped state

trohitg134e7a8f57b1
diff --git a/CLAUDE.md b/CLAUDE.md
index b7e00980..bea7f470 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -592,25 +592,36 @@ The frontend uses a layered cache + slice-subscription model so cold refreshes a
Following the plugin authoring RFC §6.5 / §6.6, icons and colors live co-located in the plugin folder; `visuals.json` is the fallback registry for emoji / library icons and the skill reverse-map.
**Icon resolution** (`BaseNode._metadata_dict` → `services/plugin/base.py`):
-1. **Per-plugin `icon.svg`** in the plugin folder. If present, `_metadata_dict` emits the URL `/api/schemas/nodes/{type}/icon` (backend-served via `GET /api/schemas/nodes/{type}/icon`). 27 plugins ship this today.
-2. Fallback: **`visuals.json` `icon`** field — emoji (`"🤖"`), `lobehub:<brand>`, or `asset:<key>` for plugins without a co-located icon.svg (telegram / whatsapp / stripe + emoji-only plugins).
+1. **Per-node-type icon** — `<plugin_folder>/icon_<nodeType>.svg`. Lets multi-node-per-plugin folders serve distinct icons per node type (whatsapp has `icon_whatsappSend.svg` / `icon_whatsappReceive.svg` / `icon_whatsappDb.svg` in one shared folder).
+2. **Shared plugin icon** — `<plugin_folder>/icon.svg`. The standard Phase 9 contract; one icon for the whole folder (telegram / stripe / browser / search / google / etc.).
+3. Fallback: **`visuals.json` `icon`** field — emoji (`"🤖"`) or `lobehub:<brand>`. Post-F1/F7 there are **zero `asset:<key>` entries** in visuals.json.
+
+When tier 1 or 2 hits, `_metadata_dict` emits the URL `/api/schemas/nodes/{type}/icon`. The endpoint serves the SVG with `Content-Type: image/svg+xml` and a long cache header.
+
+**Credential icon resolution** (F7 — `Credential.get_icon_path` → `services/plugin/credential.py`):
+1. **Central catalogue** — `server/credentials/icons/<provider>.svg` (10 brand icons today).
+2. **Co-located fallback** — `<credential_class_folder>/credential_<id>.svg` (none today; available for plugin-scoped credentials).
+3. Endpoint `GET /api/schemas/credentials/{provider}/icon` serves the SVG; `credential_providers.json` `icon_ref` entries use the URL form for the 10 migrated providers.
**Color resolution** (F2 — per-plugin `meta.json`):
1. **Per-plugin `meta.json`** in the plugin folder — `{"color": "#xxxxxx"}`. 113 plugin folders ship this today (mirrors icon co-location).
2. Fallback: **`visuals.json` `color`** field. Only legacy entries that haven't been migrated rely on this; post-F2 visuals.json has zero `color` fields.
**Files:**
-- [server/nodes/visuals.json](./server/nodes/visuals.json) — fallback registry. Post-F1/F2 shape: `{nodeType: {icon?, skill?}}` (107 entries, no color, no `asset:<key>` for plugins with icon.svg).
-- [server/nodes/_visuals.py](./server/nodes/_visuals.py) — `get_icon`, `get_color`, `get_plugin_icon_path`, **`get_plugin_meta(node_type, key)`** (F2 resolver).
-- [server/nodes/&lt;group&gt;/&lt;plugin&gt;/icon.svg](./server/nodes/) — co-located plugin icon (Phase 9 / RFC §6.5).
+- [server/nodes/visuals.json](./server/nodes/visuals.json) — fallback registry. Post-F1/F2/F7 shape: `{nodeType: {icon?, skill?}}` (103 entries — **zero color fields, zero `asset:<key>` values**; only emoji + `lobehub:<brand>` icons + skill reverse-map remain).
+- [server/nodes/_visuals.py](./server/nodes/_visuals.py) — `get_icon`, `get_color`, `get_plugin_icon_path` (per-node-type tier + shared fallback), **`get_plugin_meta(node_type, key)`** (F2 resolver).
+- [server/nodes/&lt;group&gt;/&lt;plugin&gt;/icon.svg](./server/nodes/) — shared plugin icon (Phase 9 / RFC §6.5).
+- [server/nodes/&lt;group&gt;/&lt;plugin&gt;/icon_&lt;nodeType&gt;.svg](./server/nodes/whatsapp/) — per-node-type icon (post-F7 closure; whatsapp uses 3).
- [server/nodes/&lt;group&gt;/&lt;plugin&gt;/meta.json](./server/nodes/) — co-located plugin color (F2 / RFC §6.6).
+- [server/credentials/icons/&lt;provider&gt;.svg](./server/credentials/icons/) — credential brand icons (F7).
**Wire format** (frontend resolver at [client/src/assets/icons/index.ts](./client/src/assets/icons/index.ts)):
- `/api/schemas/nodes/<type>/icon` — backend-served plugin icon (prefixed with `API_CONFIG.PYTHON_BASE_URL` in dev)
-- `asset:<key>` — bundled SVG keyed by filename without `.svg` (auto-indexed via `import.meta.glob`)
+- `/api/schemas/credentials/<provider>/icon` — backend-served credential icon (F7)
- `<lib>:<brand>` — NPM icon package, e.g. `lobehub:Claude`
- `data:` / URL passthrough — inline SVG or remote
- plain emoji / short text — rendered as-is
+- `asset:<key>` — dead defensive code in the resolver. No `asset:<key>` values exist in visuals.json or `credential_providers.json` after F7 closure; the bundled `client/src/assets/icons/` directory was reduced to the resolver + `themedGlyphs.ts` (30 SVGs + 7 group barrels deleted at commit `f2366db`).
**Latent Phase 6 bug fix (commit `95249a1`):** `BaseNode.__init_subclass__` previously called `_metadata_dict()` BEFORE `register_node_class(cls)`, so `get_plugin_icon_path` couldn't resolve the plugin via `get_node_class()`. The URL emission silently fell through to `visuals.json`'s `asset:<key>`. Swapping the two register calls activates the URL path as intended.
@@ -1738,8 +1749,8 @@ python -m services.temporal.worker
- `services/temporal/workflow.py` - MachinaWorkflow orchestrator (FIRST_COMPLETED pattern, `_resolve_activity` dispatch)
- `services/temporal/activities.py` - Legacy `execute_node_activity` (WebSocket round-trip path)
- `services/temporal/plugin_activities.py` - `collect_plugin_activities` → per-type activities for F4.A
-- `services/temporal/agent_workflow.py` - `AgentWorkflow` child workflow for F4.B agent loops
-- `services/temporal/agent_activities.py` - F4.B activities: `agent.execute_llm_step.v1`, `agent.persist_turn.v1`, `agent.compact_memory.v1`
+- `services/temporal/agent_workflow.py` - `AgentWorkflow` child workflow for F4.B agent loops; its first step calls `agent.prepare_payload.v1` to resolve the DB-backed payload, then loops LLM steps + tool dispatch + per-turn persist + compaction
+- `services/temporal/agent_activities.py` - F4.B activities (5 total): `agent.execute_llm_step.v1`, `agent.persist_turn.v1`, `agent.compact_memory.v1`, `agent.prepare_payload.v1`, `agent.broadcast_progress.v1` (the last emits CloudEvents-shaped `agent_progress` per LLM turn)
- `services/temporal/worker.py` - TemporalWorkerManager (registers MachinaWorkflow + AgentWorkflow + activities) + `run_standalone_worker()` + `TemporalWorkerPool` (multi-queue, future enhancement)
- `services/temporal/executor.py` - TemporalExecutor interface matching WorkflowExecutor
- `services/temporal/client.py` - Client wrapper with runtime heartbeat disabled
diff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.md
index 9bbb1eea..823ac8d2 100644
--- a/docs-internal/DESIGN.md
+++ b/docs-internal/DESIGN.md
@@ -50,15 +50,21 @@ workflow.execute(workflow_id, workflow_data)
### 1. Temporal Distributed (primary production mode)
-When `TEMPORAL_ENABLED=true` and the Temporal server is reachable, every workflow node executes as an independent Temporal activity on the `machina-tasks` task queue.
+When `TEMPORAL_ENABLED=true` and the Temporal server is reachable, every workflow node executes through Temporal. Three dispatch paths coexist (gated by settings flags shipped in F4):
+
+| Path | Trigger | Behavior |
+|---|---|---|
+| **Legacy single activity** (`execute_node_activity`) | Default | Every node routes through one dispatcher; WS round-trip back to FastAPI. Stable since Wave 11. |
+| **Per-type activity** (`node.{type}.v{version}`) | `TEMPORAL_PER_TYPE_DISPATCH=true` (F4.A, commit `8261b05`) | Each plugin gets its own `@activity.defn` via `BaseNode.as_activity()`. Per-plugin retry / timeout / heartbeat configs apply. Direct call to `workflow_service.execute_node()` (no WS round-trip; worker shares FastAPI process). |
+| **Agent-as-child-workflow** (`AgentWorkflow`) | `TEMPORAL_AGENT_WORKFLOW_ENABLED=true` (F4.B, commits `a4d009e` + `0459131`) | 15 migrating agent types (aiAgent / chatAgent / 12 specialized / 2 team leads) run as Temporal child workflows. LLM steps + tool calls become activities. `deep_agent` / `rlm_agent` / `claude_code_agent` stay single-activity (externalised session state). |
- Per-node retries (3 attempts by default) and per-node timeouts (10 min default)
- Horizontal scaling via worker pool
-- Connection pooling via shared `aiohttp` session for WebSocket-based node execution
+- Connection pooling via shared `aiohttp` session for WebSocket-based node execution (legacy path only — per-type and AgentWorkflow paths call workflow_service in-process)
- Pure orchestrator in `services/temporal/workflow.py` using `asyncio.wait(FIRST_COMPLETED)` so dependent nodes start immediately when their specific dependency completes
-- Class-based activities in `services/temporal/activities.py` with lifecycle hooks
+- Class-based activities in `services/temporal/activities.py` (legacy) + `services/temporal/agent_activities.py` (5 F4.B activities: `execute_llm_step`, `persist_turn`, `compact_memory`, `prepare_payload`, `broadcast_progress`)
-See [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md) for full details.
+See [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md) for the full matrix + canonical pseudo-code.
### 2. Parallel Local (Redis)
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index 9ad4898a..7a93b512 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -278,21 +278,34 @@ Per-queue defaults (concurrency caps in `services/temporal/worker.py:TemporalWor
When `TEMPORAL_AGENT_WORKFLOW_ENABLED=true` and the node type is in the migrating set (`aiAgent` / `chatAgent` / 12 specialized agents / 2 team leads), the orchestrator schedules `AgentWorkflow` as a child workflow instead of an activity. Inside the workflow:
```
-AgentWorkflow.run(payload):
+AgentWorkflow.run(context):
+ 0. execute_activity("agent.prepare_payload.v1")
+ resolves the DB-backed payload (provider / model / api_key /
+ tool schemas / memory / system_message / compaction threshold)
+ from the canvas context. Temporal workflows must be deterministic,
+ so DB lookups + edge walking + tool schema build live in this
+ activity rather than the workflow body.
loop until "final" or max_iterations:
- 1. execute_activity("agent.execute_llm_step.v1") -> {kind, content|calls}
- 2. if kind == "tool_calls":
+ 1. execute_activity("agent.broadcast_progress.v1")
+ emits CloudEvents-shaped `agent_progress` for the canvas badge
+ (one per turn, `type="com.machinaos.agent.progress"`).
+ 2. execute_activity("agent.execute_llm_step.v1") -> {kind, content|calls}
+ 3. if kind == "tool_calls":
for each call:
execute_activity(f"node.{tool_node_type}.v{version}")
append tool_results to messages
- 3. execute_activity("agent.persist_turn.v1") # append memory per turn
- 4. if token_total >= compaction_threshold:
+ 4. execute_activity("agent.persist_turn.v1") # append memory per turn
+ emits CloudEvents `node_parameters_updated` via the broadcaster
+ wrapper (`source_hint="agent"`).
+ 5. if token_total >= compaction_threshold:
execute_activity("agent.compact_memory.v1")
replace messages with summary
```
Each LLM step is one activity, each tool call is one per-type activity (the same activities F4.A registered). Failures of tool activities surface as error messages back to the LLM (matching today's LangGraph behaviour); the agent loop continues.
+**Broadcasts inside the loop** wrap `WorkflowEvent` (CloudEvents v1.0) per RFC §6.4: `agent_progress` events (`com.machinaos.agent.progress`) and `node_parameters_updated` events (`com.machinaos.node.parameters.updated`) flow through the `StatusBroadcaster.broadcast_agent_progress` and `StatusBroadcaster.broadcast_node_parameters_updated` wrappers respectively. The latter is reused by the legacy `routers/websocket.py:handle_save_node_parameters` (user-source) and `services/cli_agent/service.py:_persist_memory` (cli-source) — all three emission sites share the same envelope, distinguished by `source_hint` (`"user"` / `"cli"` / `"agent"`).
+
`deep_agent`, `rlm_agent`, `claude_code_agent` are NOT migrated — their internal session state (`deepagents` package / RLM REPL / Claude CLI `--resume` with stable `cwd`) requires single-process continuity and would break across activity boundaries.
References: [Temporal AI Cookbook](https://docs.temporal.io/ai-cookbook), [`temporal-community/temporal-ai-agent`](https://github.com/temporal-community/temporal-ai-agent), [`temporalio.contrib.openai_agents`](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents).
diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.md
index 33fbc436..f83faac1 100644
--- a/docs-internal/agent_architecture.md
+++ b/docs-internal/agent_architecture.md
@@ -710,6 +710,17 @@ registry['rlm_agent'] = partial(handle_rlm_agent, ai_service=self.ai_service, da
registry['claude_code_agent'] = partial(handle_claude_code_agent, ...)
```
+### Temporal dispatch routing (post-F4)
+
+Two settings flags route agent execution through different Temporal paths (see [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md) for the full matrix):
+
+| Flag | Off (default) | On |
+|---|---|---|
+| `TEMPORAL_PER_TYPE_DISPATCH` | Every node routes through the legacy `execute_node_activity` single dispatcher (WS round-trip to the FastAPI handler). | Each node routes through its per-type activity `node.{type}.v{version}` registered via `BaseNode.as_activity()`. Per-plugin retry / timeout / heartbeat configs apply. |
+| `TEMPORAL_AGENT_WORKFLOW_ENABLED` | All 15 specialized + 2 base agents (`aiAgent` / `chatAgent`) run inside `execute_node_activity` (LangGraph loop in-activity). | The 15 migrating agent types become Temporal **child workflows** (`AgentWorkflow`). LLM steps + tool calls become activities; `agent.prepare_payload.v1` resolves the DB-backed payload as the workflow's first step. `deep_agent` / `rlm_agent` / `claude_code_agent` stay on the F4.A per-type activity path (externalised session state). |
+
+Today both flags default to `false`; the wiring is shipped (F4.A at `8261b05`, F4.B infrastructure at `a4d009e`, per-agent dispatch at `0459131`) but production rollout awaits canary verification on a Temporal dev cluster.
+
**Team leads** (`orchestrator_agent`, `ai_employee`) use the same `handle_chat_agent` routing but add an `input-teammates` handle. Connected agents become `delegate_to_<type>` tools automatically via `_collect_teammate_connections()`. See [agent_teams.md](agent_teams.md).
### RLM Agent Pattern
diff --git a/docs-internal/cli_agent_canonical_patterns_rfc.md b/docs-internal/cli_agent_canonical_patterns_rfc.md
index a15ef3b1..e55d6def 100644
--- a/docs-internal/cli_agent_canonical_patterns_rfc.md
+++ b/docs-internal/cli_agent_canonical_patterns_rfc.md
@@ -524,6 +524,14 @@ runs (Closes I-6).** Three coupled mechanisms:
simpleMemory parameter panel refetches the moment the run
completes — mirrors the manual save broadcast in
[`routers/websocket.py:handle_save_node_parameters`](../server/routers/websocket.py).
+ Post-commit `7c9e873`, all three emission sites (Claude CLI
+ `_persist_memory`, parameter-panel save, F4.B AgentWorkflow
+ per-turn) wrap [`WorkflowEvent.node_parameters_updated`](../server/services/events/envelope.py)
+ (CloudEvents v1.0, `type="com.machinaos.node.parameters.updated"`)
+ via the shared
+ [`StatusBroadcaster.broadcast_node_parameters_updated`](../server/services/status_broadcaster.py)
+ wrapper. `data.source` (`"user"` / `"cli"` / `"agent"`) marks the
+ origin; locked by `tests/test_cloudevents_node_parameters.py`.
5. **Parallel-batch guard.** `len(tasks) > 1` with memory wired raises
`NodeUserError` at handler entry — concurrent `--resume <UUID>`
diff --git a/docs-internal/new_service_integration.md b/docs-internal/new_service_integration.md
index 5eafe650..c0055dcb 100644
--- a/docs-internal/new_service_integration.md
+++ b/docs-internal/new_service_integration.md
@@ -5,7 +5,7 @@
This guide provides a comprehensive walkthrough for integrating new external services (like Google Workspace, Slack, Notion, etc.) into MachinaOs. It covers OAuth authentication, database models, API handlers, frontend nodes, and AI Agent tool integration.
-> **Wave 6 update (April 2026):** the **Frontend Node Definitions** step (#4 below) has shrunk dramatically. Parameter schemas, validation, conditional visibility, and dynamic-option dispatch now live on the backend via Pydantic + the NodeSpec contract. The legacy frontend `nodeDefinitions/*.ts` `properties` arrays are still active until Phase 3e flips `VITE_NODESPEC_BACKEND` ON, but new integrations should follow the [Wave 6 recommended recipe](./node_creation.md#wave-6-recommended-recipe-backend-first) in the node creation guide so they ship through the new path automatically.
+> **Backend-first is canonical (post-Wave-6 / Wave-11).** Parameter schemas, validation, conditional visibility, dynamic-option dispatch, icons, and colors all live on the backend. The legacy frontend `nodeDefinitions/*.ts` files no longer exist. Follow the [canonical plugin recipe](./node_creation.md) — every node is one Python file (or self-contained folder) under `server/nodes/<group>/<plugin>/`. The frontend reads `NodeSpec` via [`client/src/lib/nodeSpec.ts`](../client/src/lib/nodeSpec.ts) and adapts via [`adapters/nodeSpecToDescription.ts`](../client/src/adapters/nodeSpecToDescription.ts). Credential icons are also backend-served via `GET /api/schemas/credentials/{provider}/icon` (F7); plugin icons via `GET /api/schemas/nodes/{type}/icon` (Phase 6 / RFC §6.5).
## Overview
diff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.md
index 722f7951..ce5b6b1e 100644
--- a/docs-internal/node_creation.md
+++ b/docs-internal/node_creation.md
@@ -64,8 +64,12 @@ class MyOutput(BaseModel):
class MyNode(ActionNode):
type = "myNode"
display_name = "My Node"
- icon = "asset:my"
- color = "#abcdef"
+ # Icon + color: drop `icon.svg` into this plugin folder + create
+ # `meta.json` with `{"color": "#abcdef"}`. For multi-node folders
+ # (one folder, multiple node classes — telegram / whatsapp / stripe),
+ # use `icon_<nodeType>.svg` for per-node-type icons; the resolver
+ # picks per-node first, falling back to shared `icon.svg`. emoji /
+ # lobehub:<brand> live in `visuals.json` for icon-only entries.
group = ("search", "tool")
description = "Brief description for palette + AI tool."
component_kind = "square"
diff --git a/docs-internal/plugin_authoring_rfc.md b/docs-internal/plugin_authoring_rfc.md
index bd82f5ed..6b1fc1d7 100644
--- a/docs-internal/plugin_authoring_rfc.md
+++ b/docs-internal/plugin_authoring_rfc.md
@@ -120,7 +120,7 @@ A new plugin in group `X` checks `nodes/X/_base.py` for a domain base first; inh
**Two factory tiers — plugin-specific factories live in the plugin folder.**
-- **Cross-cutting factories** stay in `server/services/events/envelope.py`. These are parametrized by plugin name and serve any plugin: `credential`, `oauth_completed`, `connection_status`, `agent_progress`, `task_completed`, `workflow_lifecycle`, `deployment_snapshot`, `team_event`.
+- **Cross-cutting factories** stay in `server/services/events/envelope.py`. These are parametrized by plugin name and serve any plugin: `credential`, `oauth_completed`, `connection_status`, `agent_progress`, `task_completed`, `workflow_lifecycle`, `deployment_snapshot`, `team_event`, **`node_parameters_updated`** (added post-RFC at `7c9e873` — replaces 3 legacy raw-dict emission sites: parameter-panel save, Claude CLI memory bridge, AgentWorkflow per-turn memory; distinguished by `source_hint`).
- **Plugin-specific factories** live in the plugin folder's `_events.py`. The plugin alone owns its event types, data payloads, and broadcaster wrappers. Examples: `telegram_message_received`, `stripe_payment_succeeded`, `whatsapp_group_invite`. Today these are mixed into central `envelope.py` (`WorkflowEvent.message(plugin, direction, data)` is parametrized but lives centrally); a migration step (Phase 5b) moves the plugin-specific ones out.
**Plugin event author rule** (canonical four-step pattern for a new plugin-owned event type):
@@ -205,7 +205,7 @@ A factory is **cross-cutting** if either (a) its `type` is the same shape across
- Simplify `_metadata_dict` lines 206-207: `icon = get_icon(cls.type)`, `color = get_color(cls.type)`.
- Remove docstring sentence about the optional override (lines 199-203).
-Audit confirmed: 0 of 122 plugins set these attributes; `visuals.json` covers 100% of types. Branch is dead. `_metadata_dict` then computes icon as the API URL `f"/api/schemas/nodes/{cls.type}/icon"` when an `icon.svg` exists in the plugin folder, falling back to `get_icon(cls.type)` from `visuals.json` for emoji/library entries.
+Audit confirmed at RFC time: 0 of 122 plugins set the dead class-attr `icon`/`color`. Post-Phase-8 plugin count: 113 plugin folders (live count via `glob server/nodes/**/__init__.py`). `_metadata_dict` resolves icon in three tiers (RFC §6.5 + F7 closure): per-node-type `<plugin>/icon_<nodeType>.svg` → shared `<plugin>/icon.svg` → `visuals.json` emoji / `lobehub:<brand>`. The asset:&lt;key&gt; fallback that originally lived in tier 3 is dead post-F7 — visuals.json carries zero `asset:` entries. Color resolves via per-plugin `meta.json` (F2) → `visuals.json` legacy fallback (currently empty — all 117 plugins ship `meta.json`).
### 6.7 Doc rewrites — what changes where
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index dd041a7e..0b2195f4 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -47,8 +47,10 @@ class ExampleOutput(BaseModel):
class ExampleSearchNode(ActionNode):
type = "exampleSearch"
display_name = "Example Search"
- icon = "asset:example"
- color = "#abcdef"
+ # Icon + color are NOT declared on the class. Drop `icon.svg` into
+ # the plugin folder; create `meta.json` with `{"color": "#abcdef"}`.
+ # `_metadata_dict` resolves both at registration time via the
+ # central handler in server/nodes/_visuals.py.
group = ("search", "tool")
description = "Example search via external API"
component_kind = "square"
diff --git a/docs-internal/schema_source_of_truth_rfc.md b/docs-internal/schema_source_of_truth_rfc.md
index 0ba98bf8..7499f5e8 100644
--- a/docs-internal/schema_source_of_truth_rfc.md
+++ b/docs-internal/schema_source_of_truth_rfc.md
@@ -20,7 +20,7 @@ Wave 3 proved the pattern for output schemas. Wave 6 generalises it to the **ful
- **Input schemas** — [server/services/node_input_schemas.py](../server/services/node_input_schemas.py) registers Pydantic input models across every node type — live count via `len(_DIRECT_MODELS)` — auto-expanding `SpecializedAgentParams` and `AndroidServiceParams` via Literal union introspection.
- **NodeSpec envelope** — [server/services/node_spec.py](../server/services/node_spec.py) assembles `{type, displayName, icon, group, description, version, inputs (JSON Schema), outputs (JSON Schema, reuses Wave 3), credentials, uiHints}` fusing three sources of truth.
- **Display metadata** — [server/models/node_metadata.py](../server/models/node_metadata.py) carries one entry per input-modeled type — live size via `len(NODE_METADATA)`. The only new server-side data file.
-- **Endpoints** — alongside the Wave 3 `/nodes/{type}.json` output endpoint: `GET /api/schemas/nodes/{type}/spec.json`, `/nodes/{type}/input.json`, `/nodes/specs` (list), all with 24h `Cache-Control`. WS mirrors: `get_node_spec`, `list_node_specs`.
+- **Endpoints** — alongside the Wave 3 `/nodes/{type}.json` output endpoint: `GET /api/schemas/nodes/{type}/spec.json`, `/nodes/{type}/input.json`, `/nodes/specs` (list), all with 24h `Cache-Control`. WS mirrors: `get_node_spec`, `list_node_specs`. **Icon endpoints (RFC §6.5 + F7):** `GET /api/schemas/nodes/{type}/icon` serves the plugin's co-located `icon.svg` (or per-node-type `icon_<nodeType>.svg` for multi-node folders like whatsapp); `GET /api/schemas/credentials/{provider}/icon` serves the credential brand icon from `server/credentials/icons/<provider>.svg`. Both with long cache headers.
- **loadOptionsMethod dispatch** — [server/services/node_option_loaders/](../server/services/node_option_loaders/) generalises the WhatsApp-only pattern to a registry. Adding a new dynamic-option loader = one-line registration. `POST /api/schemas/nodes/options/{method}` + WS `load_options`.
- **Node-groups index** — `GET /api/schemas/nodes/groups` returns `{group: [node_type, ...]}` derived from every NodeSpec's `group` array — live count via `len(NODE_GROUPS)` — replacing the hand-rolled `*_NODE_TYPES` arrays scattered across 6 frontend files.
- **Pydantic Field hints** — authors encode `displayOptions.show`/`.hide`, `loadOptionsMethod`, `placeholder`, `validation`, `typeOptions` via `Field(json_schema_extra={...})`. Currently ~36 rules encoded across TwitterSend/User, TelegramSend, HttpRequest, WhatsAppSend, SocialSend, Gmail, Calendar.
diff --git a/docs-internal/status_broadcaster.md b/docs-internal/status_broadcaster.md
index c45c9beb..02bab37f 100644
--- a/docs-internal/status_broadcaster.md
+++ b/docs-internal/status_broadcaster.md
@@ -138,7 +138,8 @@ Broadcasts are sent to all connected clients without a request-response correlat
| `workflow_status` | Workflow start / progress / complete | `{executing, current_node, progress}` |
| `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: "machinaos://services/credentials", type, subject: provider, time, data: {provider, customer_id?}}` |
-| `node_parameters_updated` | Parameters saved by another client | `{node_id, parameters}` |
+| `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.machinaos.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: "machinaos://services/parameters", type: "com.machinaos.node.parameters.updated", subject: node_id, time, data: {node_id, parameters, version, source}}` |
+| `agent_progress` | Per-turn LangGraph / AgentWorkflow progress (canvas badge "N / max") — wraps `WorkflowEvent.agent_progress` (CloudEvents v1.0). Emitted from inside `services/ai.py:execute_agent` (legacy path) and via the `agent.broadcast_progress.v1` Temporal activity (F4.B AgentWorkflow path). | `{specversion: "1.0", id, source: "machinaos://services/agent", type: "com.machinaos.agent.progress", subject: node_id, time, data: {node_id, iteration, max_iterations, phase?}}` |
| `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}` |
diff --git a/docs-internal/stripe_service.md b/docs-internal/stripe_service.md
index c3fe8a52..1fb3f0f1 100644
--- a/docs-internal/stripe_service.md
+++ b/docs-internal/stripe_service.md
@@ -244,7 +244,10 @@ class StripeCredential(Credential):
id = "stripe"
display_name = "Stripe"
category = "Payments"
- icon = "asset:stripe"
+ # Icon resolved per-plugin via nodes/stripe/icon.svg (Phase 9 +
+ # F7 closure). Credential brand icon lives at
+ # server/credentials/icons/stripe.svg and is served by
+ # GET /api/schemas/credentials/stripe/icon (F7).
auth = "custom"
docs_url = "https://stripe.com/docs/cli"
diff --git a/server/nodes/README.md b/server/nodes/README.md
index bd5d5363..b1337671 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -43,10 +43,16 @@ class AcmeOutput(BaseModel):
count: int = 0
-# 4. The node. (Icon + color are NOT declared here — add an entry
-# {"acmeSearch": {"icon": "asset:acme", "color": "#abcdef"}} to
-# server/nodes/visuals.json instead. BaseNode resolves both via
-# the central handler at server/nodes/_visuals.py.)
+# 4. The node. (Icon + color are NOT declared on the class.
+# Icon: drop `icon.svg` into THIS plugin folder. For per-node-type
+# icons in multi-node folders (telegram / whatsapp / stripe),
+# use `icon_<nodeType>.svg`. The resolver picks per-node first,
+# falling back to shared `icon.svg`. Emoji / `lobehub:<brand>`
+# entries live in `server/nodes/visuals.json` for plugins
+# without a co-located SVG.
+# Color: create `meta.json` with `{"color": "#abcdef"}` in this folder.
+# BaseNode._metadata_dict resolves both at registration time via the
+# central handler at server/nodes/_visuals.py.)
class AcmeSearchNode(ActionNode):
type = "acmeSearch"
display_name = "Acme Search"