Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: align TEMPORAL_ARCHITECTURE, plugin_system, RFC, CLAUDE.md with F1/F2/F4
trohitgef1b7cb4e6b1
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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/<group>/<plugin>/icon.svg](./server/nodes/) — co-located plugin icon (Phase 9 / RFC §6.5).+- [server/nodes/<group>/<plugin>/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`):```envTEMPORAL_SERVER_ADDRESS=localhost:7233TEMPORAL_NAMESPACE=defaultTEMPORAL_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 agentasync 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.mdindex 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] = handleif 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 FilteringCertain 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.mdindex 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. Verificationdiff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex 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-specificlogic 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 TemporalWorkerPoolpool = TemporalWorkerPool(client) # defaults to all declared queuesawait 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