Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: sweep — align all docs with post-F4.B + F7 + CloudEvents shipped state
trohitg134e7a8f57b1
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 aFollowing 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/<group>/<plugin>/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/<group>/<plugin>/icon.svg](./server/nodes/) — shared plugin icon (Phase 9 / RFC §6.5).+- [server/nodes/<group>/<plugin>/icon_<nodeType>.svg](./server/nodes/whatsapp/) — per-node-type icon (post-F7 closure; whatsapp uses 3).- [server/nodes/<group>/<plugin>/meta.json](./server/nodes/) — co-located plugin color (F2 / RFC §6.6).+- [server/credentials/icons/<provider>.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 disableddiff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.mdindex 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.mdindex 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:TemporalWorWhen `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.mdindex 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, daregistry['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 Patterndiff --git a/docs-internal/cli_agent_canonical_patterns_rfc.md b/docs-internal/cli_agent_canonical_patterns_rfc.mdindex 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 runcompletes — 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.mdindex 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).## Overviewdiff --git a/docs-internal/node_creation.md b/docs-internal/node_creation.mdindex 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.mdindex 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:<key> fallback that originally lived in tier 3 is dead post-F7 — visuals.json carries zero `asset:` entries. Color resolves via per-plugin `meta.json` (F2) → `visuals.json` legacy fallback (currently empty — all 117 plugins ship `meta.json`).### 6.7 Doc rewrites — what changes wherediff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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"