Skip to content

Self-improving AI Employees for everyone

docs: align TEMPORAL_ARCHITECTURE, plugin_system, RFC, CLAUDE.md with F1/F2/F4

trohitgef1b7cb4e6b1
diff --git a/CLAUDE.md b/CLAUDE.md
index c551c2b1..b7e00980 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -587,13 +587,43 @@ The frontend uses a layered cache + slice-subscription model so cold refreshes a
- Applies to `SquareNode`, `AIAgentNode`, `TriggerNode`, `GenericNode`, `ToolkitNode`, `StartNode`, `TeamMonitorNode`. Add new node components the same way.
- Reference: https://reactflow.dev/learn/advanced-use/performance
-### Icon + color — central `visuals.json` registry, single source of truth
-- Every node's icon and color live in [server/nodes/visuals.json](./server/nodes/visuals.json) — `{nodeType: {icon, color, skill?}}`. The `skill` field optionally points at the teaching skill folder (reverse map for the "teach this node" case).
-- The handler at [server/nodes/_visuals.py](./server/nodes/_visuals.py) exposes `get_icon(node_type)` / `get_color(node_type)`. `BaseNode._metadata_dict` consults it at registration time. Node plugin classes do **not** declare `icon = ...` or `color = ...` themselves (a subclass MAY override by setting the class attr — explicit value wins).
-- Wire format (used by the frontend resolver at [client/src/assets/icons/index.ts](./client/src/assets/icons/index.ts)): `asset:<key>` (filesystem SVG, keyed by filename without `.svg`, auto-indexed via `import.meta.glob`), `<lib>:<brand>` (NPM icon package, e.g. `lobehub:Claude`), `data:` / URL passthrough, or plain emoji.
-- Frontend renders via the single `<NodeIcon icon className />` primitive in [client/src/assets/icons/NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx). It dispatches lib-component / `<img>` / text branches and **does not apply parent color** — that would mono-tint lobehub `.Color` brand SVGs (their paths use `currentColor`). Sites that want a tinted backdrop set `style={{ color: brandColor }}` on the parent + `bg-tint-soft` / `border-tint`.
-- SKILL.md icon/color is resolved by `SkillLoader._parse_skill_metadata` from the first node in `allowed-tools` via the same handler. Skills with a node target carry no inline icon/color. **Orphan skills** (personality, memory operators, autonomous patterns — no node target) keep inline `metadata.icon` and `metadata.color` since the resolver returns nothing for them.
-- **Do not** ship inline data URIs from the backend, do not maintain frontend override tables, do not declare `icon`/`color` on a node class (use visuals.json), do not declare them in SKILL.md when the skill targets a node.
+### Icon + color — per-plugin folder + visuals.json fallback (post-RFC F1 + F2)
+
+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).
+
+**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/&lt;group&gt;/&lt;plugin&gt;/meta.json](./server/nodes/) — co-located plugin color (F2 / RFC §6.6).
+
+**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`)
+- `<lib>:<brand>` — NPM icon package, e.g. `lobehub:Claude`
+- `data:` / URL passthrough — inline SVG or remote
+- plain emoji / short text — rendered as-is
+
+**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.
+
+**Frontend rendering:**
+- Single `<NodeIcon icon className />` primitive at [client/src/assets/icons/NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx) dispatches lib-component / `<img>` / text branches.
+- Does **not** apply parent `color` — would mono-tint lobehub `.Color` brand SVGs whose paths use `currentColor`. Sites that want a tinted backdrop set `style={{ color: brandColor }}` on the parent + `bg-tint-soft` / `border-tint`.
+- SKILL.md icon/color resolves via `SkillLoader._parse_skill_metadata` from the first node in `allowed-tools` using the same handler chain. Orphan skills (personality, memory operators, autonomous patterns — no node target) keep inline `metadata.icon` and `metadata.color`.
+
+**Do not:**
+- Ship inline data URIs from the backend.
+- Maintain frontend override tables.
+- Declare `icon`/`color` on a node class (use icon.svg + meta.json, or visuals.json for fallback cases).
+- Declare them in SKILL.md when the skill targets a node.
## Key Files & Components
@@ -1629,18 +1659,26 @@ server/nodes/document/
Workflows execute via Temporal for durability and horizontal scaling. Temporal is an always-on service (like WhatsApp) started unconditionally by `npm run start` and `npm run dev`.
-**Architecture**: Each workflow node executes as an independent Temporal activity:
+**Architecture**: Three dispatch paths, gated by settings flags (see [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md)):
+
+| Path | Trigger | Behavior |
+|---|---|---|
+| Legacy single activity (`execute_node_activity`) | Default | Every node routed through one dispatcher; WebSocket round-trip back to FastAPI. |
+| 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). Foundation for future `TemporalWorkerPool` per-queue routing. |
+| Agent-as-child-workflow (`AgentWorkflow`) | `TEMPORAL_AGENT_WORKFLOW_ENABLED=true` (F4.B infra, commit `a4d009e`) | aiAgent / chatAgent / 12 specialized agents / 2 team leads become Temporal child workflows. LLM step = activity. Tool calls = per-type activities. `deep_agent` / `rlm_agent` / `claude_code_agent` keep single-activity execution (externalised loops). |
+
- **Per-node retry** - Failed nodes retry independently (up to 3 attempts)
- **Per-node timeout** - Long AI nodes don't block short nodes (10 min default)
- **Horizontal scaling** - Activities distributed across worker pool
-- **Connection pooling** - Shared aiohttp session for WebSocket execution
-- **Activity heartbeats** - `activity.heartbeat()` fires on every non-matching WebSocket broadcast inside the read loop (`services/temporal/activities.py`), keeping long-running DeepAgent/browser operations alive. Without this, the 2-min `heartbeat_timeout` would kill activities that normally run 5-10 minutes. Connection config: `heartbeat=30`, `receive_timeout=540`.
+- **Activity heartbeats** - Legacy path: `activity.heartbeat()` on every non-matching WebSocket broadcast in the read loop (`services/temporal/activities.py`). Per-type path: heartbeats at pipeline-stage boundaries inside `BaseNode.as_activity()`. Both keep long-running DeepAgent/browser operations alive past the 2-min `heartbeat_timeout`.
**Configuration** (`.env`):
```env
TEMPORAL_SERVER_ADDRESS=localhost:7233
TEMPORAL_NAMESPACE=default
TEMPORAL_TASK_QUEUE=machina-tasks
+TEMPORAL_PER_TYPE_DISPATCH=false # F4.A flag (default off)
+TEMPORAL_AGENT_WORKFLOW_ENABLED=false # F4.B flag (default off)
```
**Temporal Server** (`temporal-server` global CLI):
@@ -1697,11 +1735,15 @@ python -m services.temporal.worker
- Android service nodes and skill nodes filtered by type
**Key Files**:
-- `services/temporal/workflow.py` - MachinaWorkflow orchestrator (FIRST_COMPLETED pattern)
-- `services/temporal/activities.py` - Class-based activities with aiohttp pooling + per-message heartbeats in WebSocket read loop
-- `services/temporal/worker.py` - TemporalWorkerManager + `run_standalone_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/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
+- `services/plugin/base.py::BaseNode.as_activity()` - Per-type activity body for F4.A (mirrors the legacy pipeline)
**Runtime Configuration**: Worker heartbeating is disabled via `Runtime(worker_heartbeat_interval=None)` to avoid warnings on older Temporal server versions.
@@ -2360,7 +2402,7 @@ const createNodeTypes = () => {
};
```
-The dispatch keys off `spec.componentKind` (a backend-declared string), never `spec.type`. Specialized agent visuals (icon, color, handles, subtitle, width, height) all come from the spec. Icons + colours live in [`server/nodes/visuals.json`](./server/nodes/visuals.json) — not in the frontend component.
+The dispatch keys off `spec.componentKind` (a backend-declared string), never `spec.type`. Specialized agent visuals (icon, color, handles, subtitle, width, height) all come from the spec. Icons live as `icon.svg` in the plugin folder (served via `/api/schemas/nodes/<type>/icon`); colors live as `meta.json` in the plugin folder (post-F2). [`server/nodes/visuals.json`](./server/nodes/visuals.json) is the fallback registry for emoji / `lobehub:<brand>` icons + the skill reverse-map.
### AI Agent vs Zeenie
@@ -2484,7 +2526,7 @@ Child broadcasts its own status updates (executing, success, error)
### Specialized AI Agents
-The system ships specialized agent variants — each is a folder under [`server/nodes/agent/`](./server/nodes/agent/) with `__init__.py` declaring a `SpecializedAgentBase` subclass. Authoritative list: glob that folder. Per-type display name / subtitle / description live on the plugin class; icon + colour live in [`server/nodes/visuals.json`](./server/nodes/visuals.json). Do not maintain a hand-list of agent types in this doc — it drifts on every plugin add.
+The system ships specialized agent variants — each is a folder under [`server/nodes/agent/`](./server/nodes/agent/) with `__init__.py` declaring a `SpecializedAgentBase` subclass. Authoritative list: glob that folder. Per-type display name / subtitle / description live on the plugin class; icon comes from `<plugin>/icon.svg` (or visuals.json emoji fallback); color comes from `<plugin>/meta.json` (post-F2). Do not maintain a hand-list of agent types in this doc — it drifts on every plugin add.
Standard handle topology (declared on `SpecializedAgentBase` via `std_agent_handles()`):
- **Left**: `input-main` (Input, 30%), `input-memory` (Memory, 55%), `input-task` (Task, 85%)
@@ -3885,7 +3927,7 @@ class MyTool(ToolNode): # or SpecializedAgentBase for an agent
async def run(self, ctx, params): ...
```
-`BaseNode.__init_subclass__` registers the class into `NODE_METADATA`, `_DIRECT_MODELS`, `NODE_OUTPUT_SCHEMAS`, `_HANDLER_REGISTRY`, and `_NODE_CLASS_REGISTRY` on import. NodeSpec emits at `GET /api/schemas/nodes/<type>/spec.json`. The frontend auto-discovers via `useNodeSpec` + `componentKind` dispatch (see "Spec-driven component design" above). Icon + colour go in [`server/nodes/visuals.json`](./server/nodes/visuals.json).
+`BaseNode.__init_subclass__` registers the class into `_NODE_CLASS_REGISTRY` (first), then into `NODE_METADATA`, `_DIRECT_MODELS`, `NODE_OUTPUT_SCHEMAS`, and `_HANDLER_REGISTRY` on import. The class-registry-first order matters: `_metadata_dict` calls `get_plugin_icon_path(cls.type)` which goes through `get_node_class()`. NodeSpec emits at `GET /api/schemas/nodes/<type>/spec.json`. The frontend auto-discovers via `useNodeSpec` + `componentKind` dispatch (see "Spec-driven component design" above). Icon goes in `<plugin>/icon.svg` (or `visuals.json` for emoji / library brand); color goes in `<plugin>/meta.json` (or `visuals.json` legacy fallback).
**Cross-cutting edits that are still required (small):**
- New specialized agent: add the agent's `type` string to the delegation-check tuple in [`server/services/handlers/tools.py:execute_tool()`](./server/services/handlers/tools.py) (~line 224) so the parent agent's `delegate_to_*` tool finds it. Also update `AI_AGENT_TYPES` frozenset in [`server/constants.py`](./server/constants.py) — used for legacy delegation checks. Both are flagged as tech debt; see "remaining tribal arrays" note.
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index 454373eb..9ad4898a 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -2,7 +2,15 @@
## Overview
-Each workflow node executes as an **independent Temporal activity** with its own isolated context, enabling horizontal scaling across distributed workers.
+Each workflow node executes as a **Temporal activity** with its own isolated context, enabling horizontal scaling across distributed workers. The orchestrator dispatches in one of three ways depending on settings flags:
+
+| Dispatch | Trigger | Use case |
+|---|---|---|
+| **Legacy single activity** (`execute_node_activity`) | Default | Every node routed through one dispatcher activity. WebSocket round-trip back to the FastAPI server. Stable since Wave 11. |
+| **Per-type activity** (`node.{type}.v{version}`) | `TEMPORAL_PER_TYPE_DISPATCH=true` | Each plugin gets its own `@activity.defn`. Per-plugin retry / timeout / heartbeat configs apply. Worker pool can later specialise per `cls.task_queue` (browser / code-exec / ai-heavy / ...). Shipped in F4.A (commit `8261b05`). |
+| **Agent-as-child-workflow** (`AgentWorkflow`) | `TEMPORAL_AGENT_WORKFLOW_ENABLED=true` | AI Agents (aiAgent, chatAgent, 12 specialized agents, 2 team leads) run as Temporal child workflows. Each LLM turn = activity; each tool call = per-type activity. Mirrors Temporal's AI Cookbook canonical pattern. F4.B infrastructure shipped (commit `a4d009e`); per-agent migrations follow. |
+
+`deep_agent`, `rlm_agent`, `claude_code_agent` are intentionally excluded from AgentWorkflow — their externalised loops (deepagents package / RLM REPL / Claude CLI `--resume`) require single-process state continuity.
## System Architecture
@@ -14,27 +22,30 @@ Each workflow node executes as an **independent Temporal activity** with its own
| Workflow: MachinaWorkflow (orchestrator only) |
| - Parses graph structure from React Flow |
| - Filters config nodes (tools, memory, services) |
- | - Schedules node activities (FIRST_COMPLETED pattern) |
+ | - Resolves activity per node (legacy / per-type / agent-wf) |
+ | - Schedules activities (FIRST_COMPLETED pattern) |
| - Collects results and routes outputs to dependent nodes |
+---------------------------------------------------------------+
|
- Activity Queue (distributed to workers)
- +--------+ +--------+ +--------+ +--------+
- | Node A | | Node B | | Node C | | Node D |
- +--------+ +--------+ +--------+ +--------+
- | | | |
- v v v v
- +----------+ +----------+ +----------+ +----------+
- | Worker 1 | | Worker 2 | | Worker 3 | | Worker N |
- | aiAgent | | timer | | console | | http |
- +----------+ +----------+ +----------+ +----------+
- | | | |
- +----------+-----------+-----------+
+ Activity / child-workflow scheduling
+ +--------+ +--------+ +--------+ +----------------+
+ | Node A | | Node B | | Node C | | AgentWorkflow | (F4.B child wf)
+ +--------+ +--------+ +--------+ +----------------+
+ | | | |
+ v v v v
+ +----------+ +----------+ +----------+ +-----------------------+
+ | Worker 1 | | Worker 2 | | Worker 3 | | LLM step + tool steps |
+ | aiAgent | | timer | | console | | (per-type activities) |
+ +----------+ +----------+ +----------+ +-----------------------+
+ | | | |
+ +----------+-----------+--------------+
|
- v WebSocket
+ v
+ In-process call (F4.A) OR
+ WebSocket round-trip (legacy)
+----------------+
| MachinaOs |
- | /ws/internal |
+ | workflow_svc |
+----------------+
```
@@ -125,11 +136,19 @@ while True:
completed.add(node_id)
continue
- handle = workflow.start_activity(
- "execute_node_activity",
+ # F4.A: resolve to per-type name + queue when the flag is on,
+ # else fall back to the legacy single dispatcher.
+ activity_name, activity_queue = self._resolve_activity(node_type)
+ start_kwargs = dict(
args=[context],
start_to_close_timeout=timedelta(minutes=10),
+ heartbeat_timeout=timedelta(minutes=2),
+ retry_policy=retry_policy,
)
+ if activity_queue is not None:
+ start_kwargs["task_queue"] = activity_queue
+
+ handle = workflow.start_activity(activity_name, **start_kwargs)
running[node_id] = handle
if not running:
@@ -140,43 +159,37 @@ while True:
outputs[done_id] = result
```
-### 3. Activity Executes Node via WebSocket
+### 3. Activity executes the node
+
+**Legacy path** (`execute_node_activity`): The activity round-trips through the local WebSocket back to FastAPI, which dispatches to the plugin handler. This was the only path before F4.A.
+
+**Per-type path** (`node.{type}.v{version}`, F4.A): The activity body lives on the plugin class via `BaseNode.as_activity()` and calls `workflow_service.execute_node(...)` **directly** — no WebSocket round-trip. Same DI container (the worker shares the FastAPI process), same broadcasting + parameter-fetch pipeline. Each plugin class declares its own `start_to_close_timeout` / `retry_policy` / `heartbeat_timeout` so they're applied at activity definition time. See `server/services/plugin/base.py:as_activity`.
```python
-async def execute_node_activity(self, context: Dict) -> Dict:
- node_id = context["node_id"]
- node_type = context["node_type"]
-
- # Execute via WebSocket to MachinaOs
- async with self.session.ws_connect(
- self.ws_url,
- heartbeat=30,
- receive_timeout=540, # 9 min, fits within start_to_close_timeout=10min
- ) as ws:
- await ws.send_json({
- "type": "execute_node",
- "node_id": node_id,
- "node_type": node_type,
- "parameters": context["node_data"],
- ...
- })
-
- # Wait for matching response, heartbeat on every non-matching broadcast
- async for msg in ws:
- if msg.type == aiohttp.WSMsgType.TEXT:
- response = json.loads(msg.data)
- if response.get("request_id") == request_id:
- return response
- # Broadcasts (status updates, tool glow) are natural heartbeat points
- activity.heartbeat(f"Waiting for {node_id}")
+# F4.A per-type activity body (server/services/plugin/base.py)
[email protected](name=f"node.{cls.type}.v{cls.version}")
+async def _node_activity(context: Dict[str, Any]) -> Dict[str, Any]:
+ # ... pre_executed / disabled checks ...
+ broadcaster = container.status_broadcaster()
+ await broadcaster.update_node_status(node_id, "executing", ..., workflow_id=...)
+
+ workflow_service = container.workflow_service()
+ result = await workflow_service.execute_node(
+ node_id=node_id, node_type=cls.type,
+ parameters=node_data,
+ nodes=context.get("nodes", []), edges=context.get("edges", []),
+ session_id=context.get("session_id", "default"),
+ workflow_id=workflow_id,
+ outputs=context.get("inputs", {}),
+ )
+ # ... broadcast success/error, return result ...
```
**Heartbeat strategy (critical for long-running activities):**
-The 2-minute `heartbeat_timeout` would kill DeepAgent or browser activities that routinely run 5-10 minutes. The fix: `activity.heartbeat()` fires on every non-matching WebSocket message inside the read loop. Since the server broadcasts status updates, tool glow events, and progress messages continuously during execution, these broadcasts serve as natural heartbeat points -- the activity stays alive for as long as *anything* is happening on the WebSocket.
+The 2-minute `heartbeat_timeout` would kill DeepAgent or browser activities that routinely run 5-10 minutes. Both dispatch paths emit `activity.heartbeat()` at progress points — legacy on every non-matching WebSocket message, per-type at the start of each pipeline stage.
-Start/end heartbeats alone are not enough. Without per-message heartbeats, any operation longer than 2 minutes triggers `TIMEOUT_TYPE_HEARTBEAT` and Temporal retries (or fails) the activity.
+In the legacy path the server broadcasts status updates, tool-glow events, and progress messages continuously during execution, so the WS-read-loop heartbeats keep the activity alive for as long as anything is happening. Start/end heartbeats alone are not enough — any operation longer than 2 minutes would trigger `TIMEOUT_TYPE_HEARTBEAT` and Temporal would retry (or fail) the activity.
## Connection Pooling
@@ -229,20 +242,61 @@ Add more workers = handle more concurrent nodes
### Specialized Worker Pools (Future)
+F4.A laid the infrastructure (per-type dispatch with `task_queue=cls.task_queue` on `BaseNode`) but the single `TemporalWorkerManager` still polls one queue. Wiring `TemporalWorkerPool` in `main.py` is the deferred follow-up:
+
```
-Queue: machina-tasks-cpu Queue: machina-tasks-gpu
- | |
- +----+----+ +----+----+
- v v v v
-+-------+ +-------+ +-------+ +-------+
-|CPU | |CPU | |GPU | |GPU |
-|Worker | |Worker | |Worker | |Worker |
-|timer | |http | |aiAgent| |aiAgent|
-+-------+ +-------+ +-------+ +-------+
-
-Route AI nodes to GPU workers, light nodes to CPU workers
+Queue: rest-api Queue: ai-heavy Queue: code-exec
+ | | |
++----+----+ +----+----+ +----+----+
+| Worker | | Worker | | Worker |
+| gmail | | aiAgent | | python |
+| brave | | chatA | | js exec |
+| twitter | | deepA | | ts exec |
++---------+ +---------+ +---------+
+
+Plugin classes already declare cls.task_queue. When the pool wires
+in, `MachinaWorkflow._resolve_activity` starts returning
+(activity_name, cls.task_queue) instead of (activity_name, None).
```
+Per-queue defaults (concurrency caps in `services/temporal/worker.py:TemporalWorkerPool.DEFAULT_CONCURRENCY`):
+
+| Queue | Default concurrency | Use case |
+|---|---|---|
+| `machina-default` | 20 | Catch-all |
+| `rest-api` | 50 | Lightweight HTTP calls |
+| `ai-heavy` | 4 | LLM agent loops |
+| `code-exec` | 10 | Python / JS / TS sandboxes |
+| `triggers-poll` | 100 | Gmail polling, etc. |
+| `triggers-event` | 100 | Event-waiter triggers |
+| `android` | 10 | ADB / relay ops |
+| `browser` | 4 | Playwright / agent-browser |
+| `messaging` | 20 | WhatsApp / Telegram |
+
+### Agent-as-child-workflow (F4.B)
+
+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):
+ loop until "final" or max_iterations:
+ 1. execute_activity("agent.execute_llm_step.v1") -> {kind, content|calls}
+ 2. 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:
+ 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.
+
+`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).
+
## Config Node Filtering
Certain nodes provide configuration rather than executing:
@@ -252,17 +306,17 @@ Certain nodes provide configuration rather than executing:
CONFIG_HANDLES = {"input-tools", "input-memory", "input-model", "input-skill", "input-task", "input-teammates"}
# Trigger node types - event listeners, never scheduled as blocking activities
+# Authoritative list: server/constants.py WORKFLOW_TRIGGER_TYPES (frozenset).
TRIGGER_NODE_TYPES = frozenset([
- "start", "cronScheduler", "webhookTrigger", "whatsappReceive",
- "workflowTrigger", "chatTrigger", "taskTrigger",
+ "webhookTrigger", "whatsappReceive", "workflowTrigger",
+ "chatTrigger", "taskTrigger",
"twitterReceive", "googleGmailReceive", "telegramReceive",
+ "emailReceive",
])
-# Android service types (connect to androidTool)
-ANDROID_SERVICE_TYPES = {
- "batteryMonitor", "locationService", "deviceState",
- "systemInfo", "appList", "appLauncher",
-}
+# Android service types (connect to androidTool) -- authoritative list
+# in server/constants.py ANDROID_SERVICE_NODE_TYPES (16 entries since
+# Wave 11.I).
```
Config nodes are:
diff --git a/docs-internal/plugin_authoring_rfc.md b/docs-internal/plugin_authoring_rfc.md
index 5eef3726..bd82f5ed 100644
--- a/docs-internal/plugin_authoring_rfc.md
+++ b/docs-internal/plugin_authoring_rfc.md
@@ -33,7 +33,7 @@ Three problems compound today:
## 4. Non-goals
- No new pytest invariants beyond what already exists.
-- No wiring of per-node Temporal activity dispatch in `temporal/workflow.py` (Wave 11.F gap — separate sprint).
+- ~~No wiring of per-node Temporal activity dispatch in `temporal/workflow.py` (Wave 11.F gap — separate sprint).~~ **Shipped post-RFC as F4.A (commit `8261b05`).**
- No capability-mixin implementation (mention as future direction only).
- No entry-point-based third-party plugin loading.
- No edits to `themedGlyphs.ts` (UI chrome, not plugin media).
@@ -101,7 +101,10 @@ A new plugin in group `X` checks `nodes/X/_base.py` for a domain base first; inh
- The activity's WebSocket read loop calls `activity.heartbeat()` every 30s (`activities.py:220-242`). Long-running plugins (DeepAgent, browser automation) survive past the 2-min `heartbeat_timeout`.
- `Worker.graceful_shutdown_timeout = timedelta(seconds=30)` — explicit shutdown window honoring SIGTERM (`worker.py`).
-**Documented gap:** per-node activity dispatch (Wave 11.F intent) is partially wired. `as_activity()` registers per-type activities but `temporal/workflow.py:177-183` still schedules the legacy `"execute_node_activity"` name. Functionally equivalent today (one activity dispatches by `node_type`); migration tracked separately.
+**Status (F4):** per-node activity dispatch shipped behind a settings flag:
+
+- **F4.A** (commit `8261b05`, `TEMPORAL_PER_TYPE_DISPATCH`): orchestrator resolves `node.{type}.v{version}` per plugin via the registry; `BaseNode.as_activity()` returns a full pipeline-replacement activity that calls `workflow_service.execute_node()` in-process (skipping the legacy WS round-trip). All per-type activities register alongside the legacy `execute_node_activity` so flag-off is byte-identical. Per-queue routing (`cls.task_queue`) waits for `TemporalWorkerPool` to be wired in `main.py`.
+- **F4.B** (commit `a4d009e`, `TEMPORAL_AGENT_WORKFLOW_ENABLED`): `AgentWorkflow` Temporal child workflow + 3 activities (`agent.execute_llm_step.v1`, `agent.persist_turn.v1`, `agent.compact_memory.v1`). When enabled, the orchestrator schedules `AgentWorkflow` for the 15 migrating agent types instead of an activity; tool calls inside the loop become per-type activities. `deep_agent` / `rlm_agent` / `claude_code_agent` stay single-activity (externalised loops). Per-agent orchestrator-dispatch wiring lands in a follow-up commit.
### 6.4 CloudEvents broadcast contract
@@ -290,11 +293,11 @@ Per-batch verification: `pytest tests/test_node_spec.py -x && pytest tests/test_
## 10. Open questions
-None blocking. Three follow-ups deferred:
+None blocking. Status of the three original follow-ups:
-1. Migrate node colors from `visuals.json` to per-plugin `meta.json` (matches icon co-location for color).
-2. Capability mixins (`RequiresOAuth`, `SupportsStreaming`) per Prefect's pattern.
-3. Per-node Temporal activity dispatch in `temporal/workflow.py` (Wave 11.F gap).
+1. ✅ **Migrate node colors from `visuals.json` to per-plugin `meta.json`** — Shipped (F2, commits `796d365` + `637de1e`). 113 plugin folders ship `meta.json`. Resolver: `get_plugin_meta(type, 'color')` falls through to `get_color()` for legacy entries.
+2. **Capability mixins** (`RequiresOAuth`, `SupportsStreaming`) — Still deferred (F3).
+3. ✅ **Per-node Temporal activity dispatch + AgentWorkflow** — Shipped behind flags (F4.A `8261b05` + F4.B infra `a4d009e`). Per-agent orchestrator wiring for the 15 migrating types is a separate follow-up commit.
## 11. Verification
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index ef82df70..dd041a7e 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -401,41 +401,91 @@ response = await ai_service.execute_chat_agent(ctx.node_id, **kwargs)
auto-prompt fallback + team-lead teammate injection. Plugin-specific
logic stays in the `execute_op` method.
-### Temporal per-node activities (Wave 11.F)
+### Temporal per-node activities (Wave 11.F → F4.A wiring)
Every `BaseNode` subclass exposes `cls.as_activity()`, a Temporal
`@activity.defn`-decorated callable with name
-`node.{type}.v{version}`. Collect them for worker registration:
+`node.{type}.v{version}`. As of F4.A (commit `8261b05`) these
+activities are **wired into the orchestrator** behind
+`TEMPORAL_PER_TYPE_DISPATCH` (default off):
+
+- Flag OFF: orchestrator schedules legacy `execute_node_activity`
+ (status quo since Wave 11; WS round-trip back to FastAPI).
+- Flag ON: orchestrator schedules `f"node.{cls.type}.v{cls.version}"`.
+ The per-type activity body runs the full pipeline (broadcast +
+ pre-executed / disabled checks + parameter fetch + `instance.execute()`)
+ via `workflow_service.execute_node()` — **no WebSocket round-trip**
+ because the worker shares the FastAPI process.
+
+`TemporalWorkerManager._worker` registers BOTH the legacy activity AND
+every per-type activity (~1.6s startup cost). Per-queue routing
+(`task_queue=cls.task_queue`) waits for `TemporalWorkerPool` to be
+wired in `main.py`; the orchestrator currently passes `task_queue=None`
+so per-type activities still poll the single default queue.
```python
-from services.temporal.plugin_activities import (
- collect_plugin_activities,
- distinct_task_queues,
-)
+# Worker collection patterns (both supported).
+
+# All per-type activities (no queue filter; what TemporalWorkerManager uses today):
+from services.temporal.plugin_activities import collect_plugin_activities
+activities = collect_plugin_activities()
-# Single-queue workers:
-activities = collect_plugin_activities(task_queue="ai-heavy")
-worker = Worker(client, task_queue="ai-heavy", activities=activities, ...)
+# Filter by declared queue (for future TemporalWorkerPool):
+ai_heavy = collect_plugin_activities(task_queue="ai-heavy")
+worker = Worker(client, task_queue="ai-heavy", activities=ai_heavy, ...)
-# Multi-queue pool (one worker per queue):
+# Multi-queue pool (future enhancement — class exists, not started yet):
from services.temporal.worker import TemporalWorkerPool
pool = TemporalWorkerPool(client) # defaults to all declared queues
await pool.start()
```
-Queue distribution (current state):
+### Temporal agent workflows (F4.B)
+
+`TEMPORAL_AGENT_WORKFLOW_ENABLED` (default off, commit `a4d009e`)
+flips agent dispatch from activity to **child workflow**. The
+`AgentWorkflow` class in `services/temporal/agent_workflow.py` orchestrates the agent loop:
+
+```
+AgentWorkflow.run(payload):
+ loop until "final" or max_iterations:
+ 1. execute_activity("agent.execute_llm_step.v1") -> kind + content/calls
+ 2. if kind == "tool_calls":
+ for each call: execute_activity(f"node.{tool_type}.v{version}")
+ 3. execute_activity("agent.persist_turn.v1") # append memory per turn
+ 4. if compaction threshold: execute_activity("agent.compact_memory.v1")
+```
+
+Three new activities (`agent.execute_llm_step.v1`,
+`agent.persist_turn.v1`, `agent.compact_memory.v1`) registered
+alongside the per-type activities.
+
+**Agents that migrate** (15): `aiAgent`, `chatAgent`, 12 specialized
+agents (`android_agent`, `coding_agent`, `web_agent`, `task_agent`,
+`social_agent`, `travel_agent`, `tool_agent`, `productivity_agent`,
+`payments_agent`, `consumer_agent`, `autonomous_agent`), 2 team
+leads (`orchestrator_agent`, `ai_employee`).
+
+**Agents that stay as single activities** (3): `deep_agent`,
+`rlm_agent`, `claude_code_agent`. Their internal session state
+(deepagents package / RLM REPL / Claude CLI `--resume` with stable
+`cwd`) requires single-process continuity that would break across
+activity boundaries.
+
+Queue distribution (live count via
+`distinct_task_queues()` and `len(_NODE_CLASS_REGISTRY)`):
-| Queue | Plugins | Default concurrency |
+| Queue | Use case | Default concurrency |
|---|---|---|
-| `ai-heavy` | 28 | 4 |
-| `rest-api` | 21 | 50 |
-| `machina-default` | 25 | 20 |
-| `android` | 16 | 10 |
-| `messaging` | 7 | 20 |
-| `triggers-event` | 5 | 100 |
-| `triggers-poll` | 4 | 100 |
-| `code-exec` | 3 | 10 |
-| `browser` | 2 | 4 |
+| `ai-heavy` | LLM agent loops | 4 |
+| `rest-api` | Lightweight HTTP / Google / Twitter | 50 |
+| `machina-default` | Catch-all | 20 |
+| `android` | ADB / relay ops | 10 |
+| `messaging` | WhatsApp / Telegram | 20 |
+| `triggers-event` | Push-based triggers | 100 |
+| `triggers-poll` | Polling triggers (Gmail, etc.) | 100 |
+| `code-exec` | Python / JS / TS sandboxes | 10 |
+| `browser` | Playwright / agent-browser | 4 |
Env overrides: `TEMPORAL_<QUEUE>_CONCURRENCY` (e.g.
`TEMPORAL_AI_HEAVY_CONCURRENCY=8`).
@@ -732,7 +782,14 @@ All Wave 10 invariants in `test_node_spec.py` still run; Wave 11 invariants in `
- Wave 11.D.11 — Auto-populate trigger registries.
- Wave 11.D.12 — Fast-path contract invariants.
- Wave 11.D.13 — Sunset empty bulk files + dead dispatch.
-- Wave 11.F — Per-plugin Temporal activities + worker pools.
+- Wave 11.F — Per-plugin Temporal activities (`BaseNode.as_activity()`)
+ + `TemporalWorkerPool` class.
+- F4.A — Orchestrator wired to per-type dispatch behind
+ `TEMPORAL_PER_TYPE_DISPATCH` flag (commit `8261b05`). Closes the
+ Wave 11.F orchestrator gap.
+- F4.B — `AgentWorkflow` child workflow + 3 agent activities behind
+ `TEMPORAL_AGENT_WORKFLOW_ENABLED` flag (commit `a4d009e`). Tool
+ calls inside AI agents become per-type activities.
- Wave 11.E — Declarative credentials: 18 `Credential` subclasses
(GoogleCredential + GoogleMapsCredential + TwitterCredential +
TelegramCredential + ApifyCredential + 10 LLM providers + 3 inline