Skip to content

Self-improving AI Employees for everyone

feat(writeTodos): editable Current Todos panel + parameter-panel layout fixes

trohitg4d01d7b8253c
diff --git a/CLAUDE.md b/CLAUDE.md
index 9e385227..922edb0a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -923,7 +923,7 @@ if skill_type == 'masterSkill':
- **currentTimeTool**: Get current date/time with timezone support
- **duckduckgoSearch**: DuckDuckGo web search (free, uses `ddgs` library, no API key required)
- **taskManager**: Task management tool for AI agents to create, track, and manage tasks
-- **writeTodos**: Structured task list planning for complex multi-step operations. Connects to any agent's `input-tools` handle. Dual output (`tool` + `main`), dracula purple `#bd93f9`. Backed by `TodoService` singleton (`server/services/todo_service.py`) with JSON-based per-session state keyed by workflow_id. Schema: `WriteTodosSchema` with `TodoItem`/`TodoStatus` Pydantic enum (`pending` | `in_progress` | `completed`). Handler broadcasts `phase: "todo_update"` via WebSocket for real-time UI; `formatTodoOutput()` in `OutputDisplayPanel.tsx` renders as a checklist. Skill: `server/skills/assistant/write-todos-skill/SKILL.md` teaches the plan-work-update loop.
+- **writeTodos**: Structured task list planning for complex multi-step operations. Connects to any agent's `input-tools` handle. Dual output (`tool` + `main`), dracula purple `#bd93f9`. Backed by `TodoService` singleton (`server/services/todo_service.py`) with JSON-based per-session state keyed by workflow_id. Schema: `WriteTodosSchema` with `TodoItem`/`TodoStatus` Pydantic enum (`pending` | `in_progress` | `completed`). Handler broadcasts `phase: "todo_update"` via WebSocket for real-time UI; `formatTodoOutput()` in `OutputDisplayPanel.tsx` renders as a checklist. Skill: `server/skills/assistant/write-todos-skill/SKILL.md` teaches the plan-work-update loop. **Parameter panel = editable Current Todos manager** — `uiHints.isTodoEditor` routes `MiddleSection` to [`client/src/components/parameterPanel/TodoEditor.tsx`](./client/src/components/parameterPanel/TodoEditor.tsx) instead of the empty generic-params card. It reads/writes the LIVE TodoService list (keyed `workflow_id` → `node_id`, so all writeTodos nodes in one workflow share one list) via the `get_todos` / `set_todos` WS handlers, with add / remove / edit-text / click-to-cycle-status. Both the tool's `write` op and manual panel edits emit the typed `todos_updated` CloudEvent through the centralized `services.events.dispatch.emit`; the FE handler refreshes the `['todos', session_key]` query live. Self-contained plugin folder `server/nodes/tool/write_todos/` (`__init__.py` + `_handlers.py` + `_events.py`).
#### Dual-Purpose Search Nodes (workflow node + AI tool)
Search API nodes that work BOTH as standalone workflow nodes AND as AI Agent tools. When connected to `input-tools`, the LLM fills the node's parameter schema.
@@ -1513,7 +1513,7 @@ Dual-purpose tool nodes wrapping `deepagents.backends.LocalShellBackend`. Per-wo
| `server/skills/terminal/` | Skills: shell-skill (Nushell), process-manager-skill, bash-skill, powershell-skill, wsl-skill |
### Process Manager Node (1 node)
-Cross-platform process manager for long-running subprocesses (dev servers, watchers, build tools). Uses `asyncio.create_subprocess_exec` with full system PATH (`env={**os.environ}`). Output streams to Terminal tab via `broadcast_terminal_log()` and persists to log files in the workspace.
+Cross-platform process manager for long-running subprocesses (dev servers, watchers, build tools). Uses `asyncio.create_subprocess_exec` with full system PATH (`env={**os.environ}`). Output streams to Terminal tab via `broadcast_terminal_log()` and persists to log files in the workspace. **Captured lines are ANSI-stripped at the source** — `process_service._read_stream` runs each decoded line through `core.ansi.strip_ansi` (a thin wrapper over **`click.unstyle`**, a declared dep) before the log-file write / Terminal broadcast / `get_output` / `line_handler`, so colour + cursor/erase codes from `vite`/`npm`/`git`/etc. don't render as garbage (`[36m…[39m`). The `shell` node strips its `stdout` the same way. `click.unstyle` was chosen over `rich.Text.from_ansi` because rich line-normalizes and drops trailing newlines; `click.unstyle` is byte-faithful except for the stripped escapes.
- **processManager**: **Dual-purpose node** - Start, stop, restart, and manage long-running processes. Works as workflow node OR AI Agent tool (`process_manager`). Operations: start, stop, restart, list, send_input, get_output. Max concurrent processes configurable in Settings (default: 10).
diff --git a/client/src/components/parameterPanel/MiddleSection.tsx b/client/src/components/parameterPanel/MiddleSection.tsx
index d5415e73..a55f5e87 100644
--- a/client/src/components/parameterPanel/MiddleSection.tsx
+++ b/client/src/components/parameterPanel/MiddleSection.tsx
@@ -29,6 +29,7 @@ import { ActionButton } from '@/components/ui/action-button';
import ParameterRenderer from '../ParameterRenderer';
import ToolSchemaEditor from './ToolSchemaEditor';
import MasterSkillEditor from './MasterSkillEditor';
+import TodoEditor from './TodoEditor';
import { useAppStore } from '../../store/useAppStore';
import { useWebSocket, CompactionStats } from '../../contexts/WebSocketContext';
import { useUserSettingsQuery } from '../../hooks/useUserSettingsQuery';
@@ -182,6 +183,7 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
// it's now permanently dead.
const isSkillNode = false;
const isToolNode = hints.isToolPanel === true;
+ const isTodoEditorNode = hints.isTodoEditor === true;
const isAgentWithSkills = hints.hasSkills === true;
const { data: userSettings } = useUserSettingsQuery();
@@ -512,8 +514,9 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
return (
<div className="relative flex h-full flex-1 flex-col overflow-hidden">
- {/* Description - hide for code editor nodes (Python, Skill) and masterSkill */}
- {!needsCodeEditorLayout && !isMasterSkillNode && (
+ {/* Description - hide for code editor nodes (Python, Skill), masterSkill,
+ and the todo editor (each renders its own full-panel header). */}
+ {!needsCodeEditorLayout && !isMasterSkillNode && !isTodoEditorNode && (
<div className="shrink-0 border-b border-border-default bg-bg-panel px-6 pt-4 pb-2">
<p className="m-0 text-base leading-[1.5] text-fg-muted">
{nodeDefinition.description}
@@ -534,6 +537,8 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
nodeId={nodeId}
/>
</div>
+ ) : isTodoEditorNode ? (
+ <TodoEditor nodeId={nodeId} />
) : (
<>
{/* Parameters */}
@@ -541,7 +546,7 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
className={cn(
'box-border min-h-0 w-full overflow-x-hidden p-6',
needsCodeEditorLayout
- ? 'flex flex-[3] flex-col overflow-y-hidden'
+ ? 'flex flex-[3] flex-col overflow-y-auto'
: 'block flex-1 overflow-y-auto',
)}
>
@@ -549,7 +554,13 @@ const MiddleSection: React.FC<MiddleSectionProps> = ({
<div
className={cn(
'box-border rounded-md border border-border-default bg-bg-elevated p-4 shadow-sm',
- needsCodeEditorLayout ? 'flex h-full flex-col' : 'block h-auto',
+ // ``min-h-full`` (not ``h-full``): the card fills the region when
+ // content is short (so the code editor's flex-1 stretches) but
+ // GROWS when a node has extra params (e.g. montyExecutor's
+ // timeout / max_memory / capabilities) so the last field can't
+ // bleed past the card border. The container scrolls instead of
+ // clipping (``overflow-y-auto`` above).
+ needsCodeEditorLayout ? 'flex min-h-full flex-col' : 'block h-auto',
)}
>
{/* All Parameters - standard n8n style */}
diff --git a/client/src/components/parameterPanel/TodoEditor.tsx b/client/src/components/parameterPanel/TodoEditor.tsx
new file mode 100644
index 00000000..a68bf0b4
--- /dev/null
+++ b/client/src/components/parameterPanel/TodoEditor.tsx
@@ -0,0 +1,221 @@
+/**
+ * TodoEditor — editable Current Todos manager for the writeTodos node.
+ *
+ * Replaces the empty generic-params card ("Todos — No properties") in the
+ * parameter panel's middle section. Sourced from the LIVE workflow todos in
+ * the backend TodoService (keyed by the open workflow, node_id fallback) via
+ * the `get_todos` / `set_todos` WS handlers — NOT from `parameters.todos`.
+ *
+ * Because TodoService keys by workflow, all writeTodos nodes in one workflow
+ * share a single list (surfaced in the header). The list updates live when an
+ * agent calls the write_todos tool mid-run (the `todos_updated` CloudEvent
+ * lands in this query's cache via WebSocketContext).
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { CheckCircle2, Circle, CircleDot, Plus, Trash2 } from 'lucide-react';
+
+import { Input } from '@/components/ui/input';
+import { Badge } from '@/components/ui/badge';
+import { ActionButton } from '@/components/ui/action-button';
+import { cn } from '@/lib/utils';
+import { useWebSocket } from '../../contexts/WebSocketContext';
+import { useAppStore } from '../../store/useAppStore';
+
+type TodoStatus = 'pending' | 'in_progress' | 'completed';
+
+interface ServerTodo {
+ content: string;
+ status: TodoStatus;
+}
+
+interface TodoRow extends ServerTodo {
+ /** Transient client id for stable React keys — not persisted. */
+ id: string;
+}
+
+const STATUS_ORDER: TodoStatus[] = ['pending', 'in_progress', 'completed'];
+
+const STATUS_META: Record<TodoStatus, { Icon: typeof Circle; cls: string; label: string }> = {
+ pending: { Icon: Circle, cls: 'text-muted-foreground', label: 'Pending' },
+ in_progress: { Icon: CircleDot, cls: 'text-warning', label: 'In progress' },
+ completed: { Icon: CheckCircle2, cls: 'text-success', label: 'Completed' },
+};
+
+let _seq = 0;
+const nextId = () => `todo-${++_seq}`;
+
+const toRows = (todos: ServerTodo[]): TodoRow[] =>
+ todos.map((t) => ({ id: nextId(), content: t.content ?? '', status: (t.status as TodoStatus) ?? 'pending' }));
+
+const cycle = (s: TodoStatus): TodoStatus => STATUS_ORDER[(STATUS_ORDER.indexOf(s) + 1) % STATUS_ORDER.length];
+
+interface Props {
+ nodeId: string;
+}
+
+const TodoEditor: React.FC<Props> = ({ nodeId }) => {
+ const { sendRequest, isReady } = useWebSocket();
+ const currentWorkflowId = useAppStore((s) => s.currentWorkflow?.id);
+ const queryClient = useQueryClient();
+
+ // Session key mirrors the backend write op (`workflow_id or node_id`).
+ const sessionKey = currentWorkflowId ?? nodeId;
+
+ const { data: serverTodos } = useQuery<ServerTodo[]>({
+ queryKey: ['todos', sessionKey],
+ queryFn: async () => {
+ const resp = await sendRequest<{ todos?: ServerTodo[] }>('get_todos', {
+ workflow_id: currentWorkflowId,
+ node_id: nodeId,
+ });
+ return resp?.todos ?? [];
+ },
+ enabled: isReady,
+ staleTime: 0,
+ });
+
+ const [rows, setRows] = useState<TodoRow[]>([]);
+ // While a row's content input is focused we must NOT let an incoming
+ // server/broadcast sync overwrite it mid-type (same clobber lesson as the
+ // credentials Default-Parameters fix).
+ const editingRef = useRef<string | null>(null);
+
+ // Sync local rows from the server query — only when not actively editing.
+ useEffect(() => {
+ if (editingRef.current !== null) return;
+ setRows(toRows(serverTodos ?? []));
+ }, [serverTodos]);
+
+ // Persist the current rows (filtering empties — TodoService.write drops
+ // empty-content items, so we match that and never send blank rows).
+ const persist = useCallback(
+ (next: TodoRow[]) => {
+ setRows(next);
+ const payload: ServerTodo[] = next
+ .filter((r) => r.content.trim() !== '')
+ .map((r) => ({ content: r.content.trim(), status: r.status }));
+ // Optimistic cache update so other consumers (and a reopen) see it now.
+ queryClient.setQueryData(['todos', sessionKey], payload);
+ void sendRequest('set_todos', {
+ workflow_id: currentWorkflowId,
+ node_id: nodeId,
+ todos: payload,
+ }).catch(() => {
+ // Non-fatal: a failed save leaves the optimistic UI; the next
+ // get_todos / todos_updated reconciles. Surface nothing noisy here.
+ });
+ },
+ [queryClient, sendRequest, currentWorkflowId, nodeId, sessionKey],
+ );
+
+ const addTodo = useCallback(() => {
+ // New row is local-only until it has content (empty rows aren't persisted).
+ const row: TodoRow = { id: nextId(), content: '', status: 'pending' };
+ editingRef.current = row.id;
+ setRows((prev) => [...prev, row]);
+ }, []);
+
+ const deleteTodo = useCallback(
+ (id: string) => {
+ persist(rows.filter((r) => r.id !== id));
+ },
+ [rows, persist],
+ );
+
+ const cycleStatus = useCallback(
+ (id: string) => {
+ persist(rows.map((r) => (r.id === id ? { ...r, status: cycle(r.status) } : r)));
+ },
+ [rows, persist],
+ );
+
+ const editContent = useCallback((id: string, content: string) => {
+ setRows((prev) => prev.map((r) => (r.id === id ? { ...r, content } : r)));
+ }, []);
+
+ const commitContent = useCallback(
+ (id: string) => {
+ editingRef.current = null;
+ // Drop a still-empty new row on blur; otherwise persist the edit.
+ const next = rows.filter((r) => r.id !== id || r.content.trim() !== '');
+ persist(next);
+ },
+ [rows, persist],
+ );
+
+ const counts = rows.reduce(
+ (acc, r) => {
+ acc[r.status] += 1;
+ return acc;
+ },
+ { pending: 0, in_progress: 0, completed: 0 } as Record<TodoStatus, number>,
+ );
+
+ return (
+ <div className="flex flex-1 flex-col overflow-hidden p-4">
+ <div className="mb-3 flex flex-wrap items-center gap-2">
+ <span className="font-display tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)] text-fg-default shrink-0">
+ Current Todos
+ </span>
+ <Badge variant="secondary" className="min-w-0 truncate normal-case tracking-normal">
+ {counts.completed} done · {counts.in_progress} active · {counts.pending} pending
+ </Badge>
+ <ActionButton intent="save" onClick={addTodo} className="ml-auto h-8 shrink-0">
+ <Plus className="h-3.5 w-3.5" />
+ Add
+ </ActionButton>
+ </div>
+
+ <p className="mb-3 text-xs text-muted-foreground">
+ Live todo list for this workflow (shared by every Write Todos node in the workflow).
+ </p>
+
+ <div className="flex min-h-0 flex-1 flex-col gap-2 overflow-y-auto">
+ {rows.length === 0 ? (
+ <div className="flex flex-1 flex-col items-center justify-center gap-3 py-10 text-center">
+ <CircleDot className="h-6 w-6 text-muted-foreground" />
+ <p className="text-sm text-muted-foreground">No todos yet. Add one to start planning.</p>
+ <ActionButton intent="save" onClick={addTodo} className="h-8">
+ <Plus className="h-3.5 w-3.5" />
+ Add todo
+ </ActionButton>
+ </div>
+ ) : (
+ rows.map((row) => {
+ const meta = STATUS_META[row.status];
+ const { Icon } = meta;
+ return (
+ <div key={row.id} className="flex items-center gap-2 rounded-md border border-border bg-muted/40 p-2">
+ <button
+ type="button"
+ onClick={() => cycleStatus(row.id)}
+ title={`${meta.label} — click to cycle`}
+ className={cn('inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md hover:bg-accent', meta.cls)}
+ >
+ <Icon className="h-4 w-4" />
+ </button>
+ <Input
+ value={row.content}
+ placeholder="Describe a task…"
+ onChange={(e) => editContent(row.id, e.target.value)}
+ onFocus={() => {
+ editingRef.current = row.id;
+ }}
+ onBlur={() => commitContent(row.id)}
+ className={cn('h-8 min-w-0 flex-1', row.status === 'completed' && 'line-through text-muted-foreground')}
+ />
+ <ActionButton intent="stop" onClick={() => deleteTodo(row.id)} className="h-8 w-8 shrink-0 justify-center p-0" aria-label="Delete todo">
+ <Trash2 className="h-3.5 w-3.5" />
+ </ActionButton>
+ </div>
+ );
+ })
+ )}
+ </div>
+ </div>
+ );
+};
+
+export default TodoEditor;
diff --git a/client/src/contexts/WebSocketContext.tsx b/client/src/contexts/WebSocketContext.tsx
index 7810fc49..01cc1e98 100644
--- a/client/src/contexts/WebSocketContext.tsx
+++ b/client/src/contexts/WebSocketContext.tsx
@@ -756,6 +756,21 @@ export const WebSocketProvider: React.FC<{ children: React.ReactNode }> = ({ chi
break;
}
+ case 'todos_updated': {
+ // CloudEvents-typed todo-list change from
+ // server/nodes/tool/write_todos/_events.py, emitted via the
+ // centralized dispatcher on both the write_todos tool run AND
+ // manual edits from the Current Todos panel (set_todos). Refresh
+ // the open panel's ['todos', session_key] query so it reflects the
+ // new list live, across clients, without polling.
+ const event = data as WorkflowEvent<{ session_key?: string; todos?: unknown[] }>;
+ const sessionKey = event?.data?.session_key || event?.subject;
+ if (sessionKey) {
+ queryClient.setQueryData(['todos', sessionKey], event?.data?.todos ?? []);
+ }
+ break;
+ }
+
case 'plugin_connection_status': {
// CloudEvents-typed connection-status envelope (Wave 12 B1-B3).
// Backend dual-emits today: the legacy raw wire key
diff --git a/client/src/types/INodeProperties.ts b/client/src/types/INodeProperties.ts
index 66f45aba..367762d5 100644
--- a/client/src/types/INodeProperties.ts
+++ b/client/src/types/INodeProperties.ts
@@ -201,6 +201,9 @@ export interface INodeUIHints {
isMemoryPanel?: boolean;
/** MiddleSection: surface the ToolSchemaEditor for connected services. */
isToolPanel?: boolean;
+ /** MiddleSection: render the editable Current Todos manager (writeTodos)
+ * instead of the plain params list. */
+ isTodoEditor?: boolean;
/** MiddleSection: render the team-monitor panel. */
isMonitorPanel?: boolean;
/** Special-case panel for gmaps_create with map preview. */
diff --git a/docs-internal/node-logic-flows/ai_tools/writeTodos.md b/docs-internal/node-logic-flows/ai_tools/writeTodos.md
index 3ad0a92a..a092c7e3 100644
--- a/docs-internal/node-logic-flows/ai_tools/writeTodos.md
+++ b/docs-internal/node-logic-flows/ai_tools/writeTodos.md
@@ -18,6 +18,31 @@ state over WebSocket so the UI can render a live checklist. Storage is an
in-process `TodoService` singleton keyed by `workflow_id` (or `node_id` as
fallback).
+## Parameter-panel editor (editable Current Todos)
+
+The node's middle section is an **editable** Current Todos manager, not the empty
+generic-params card. `uiHints.isTodoEditor` (declared on the plugin) routes
+`MiddleSection` to [`client/src/components/parameterPanel/TodoEditor.tsx`](../../../client/src/components/parameterPanel/TodoEditor.tsx).
+
+- **Source of truth = the live `TodoService` list** (same `workflow_id` → `node_id`
+ key as the `write` op), NOT `parameters.todos`. Because the key is the workflow,
+ every writeTodos node in one workflow shares one list (surfaced in the panel).
+- **Read / write WS handlers** (self-registered from the plugin folder via
+ `register_ws_handlers`, see `server/nodes/tool/write_todos/_handlers.py`):
+ - `get_todos` `{workflow_id?, node_id?}` → `{todos, session_key}` (TanStack
+ Query key `['todos', session_key]`, fetched on open).
+ - `set_todos` `{workflow_id?, node_id?, todos}` → `{success, todos}`; replaces
+ the list via `TodoService.write` (same validation/normalisation as the tool).
+- **Edits**: add / remove / inline edit content / click-to-cycle status; optimistic
+ cache update + `set_todos`. While a row's content input is focused, incoming
+ remote updates are suppressed so they can't clobber an in-progress edit.
+- **Live updates**: both the tool `write` op AND `set_todos` emit the typed
+ `todos_updated` CloudEvent via the centralized `services.events.dispatch.emit`
+ (`server/nodes/tool/write_todos/_events.py`); the FE `todos_updated` case in
+ `WebSocketContext` writes the inner `todos` into `['todos', session_key]`. This
+ is a plain CloudEvent (NOT a `node_status` "executing" broadcast), so a manual
+ edit never makes the canvas node glow.
+
## Inputs (handles)
| Handle | Connection type | Required | Purpose |
diff --git a/server/nodes/tool/write_todos/__init__.py b/server/nodes/tool/write_todos/__init__.py
index 9a44ac21..9a4a8e90 100644
--- a/server/nodes/tool/write_todos/__init__.py
+++ b/server/nodes/tool/write_todos/__init__.py
@@ -73,7 +73,7 @@ class WriteTodosNode(ToolNode):
{"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
{"name": "output-tool", "kind": "output", "position": "top", "label": "Tool", "role": "tools"},
)
- ui_hints = {"isToolPanel": True, "hideRunButton": True}
+ ui_hints = {"isToolPanel": True, "hideRunButton": True, "isTodoEditor": True}
annotations = {"destructive": False, "readonly": False, "open_world": False}
task_queue = TaskQueue.DEFAULT
@@ -100,6 +100,20 @@ class WriteTodosNode(ToolNode):
workflow_id=ctx.workflow_id,
)
+ # Typed todos_updated CloudEvent via the centralized dispatcher so an
+ # open Current Todos panel refreshes live during the run. (The
+ # node_status broadcast above drives canvas glow; this drives the
+ # panel's ['todos', session_key] query — same wire frame the panel's
+ # manual set_todos edits emit.)
+ from ._events import dispatch_todos_updated
+
+ await dispatch_todos_updated(
+ session_key=session_key,
+ todos=stored,
+ node_id=ctx.node_id,
+ workflow_id=ctx.workflow_id,
+ )
+
get_logger(__name__).info(
"[WriteTodos] Updated %d todos (session=%s)",
len(stored),
@@ -116,3 +130,13 @@ class WriteTodosNode(ToolNode):
"todos": stored,
"count": len(stored),
}
+
+
+# --- self-registration on import -------------------------------------------
+# The parameter-panel Current Todos editor reads/writes the live TodoService
+# state through these WS handlers (self-contained plugin-folder pattern —
+# core router needs no edit). See nodes/telegram/__init__.py for the template.
+from services.ws_handler_registry import register_ws_handlers # noqa: E402
+from ._handlers import WS_HANDLERS # noqa: E402
+
+register_ws_handlers(WS_HANDLERS)
diff --git a/server/nodes/tool/write_todos/_events.py b/server/nodes/tool/write_todos/_events.py
new file mode 100644
index 00000000..f77b9de8
--- /dev/null
+++ b/server/nodes/tool/write_todos/_events.py
@@ -0,0 +1,76 @@
+"""CloudEvents factory + centralized dispatch for the writeTodos plugin.
+
+Plugin-scoped per RFC plugin_authoring_rfc.md §6.4 — the typed event
+factory lives in the plugin folder, mirroring
+``nodes/telegram/_events.py``. Emission goes through the centralized
+``services.events.dispatch.emit`` (the same path
+``dispatch_telegram_message_received`` uses), NOT a direct
+``status_broadcaster.broadcast`` call — ``emit`` fans the envelope out to
+any running Temporal consumers AND to in-process WS clients uniformly.
+
+A ``todos_updated`` frame fires whenever the workflow's todo list
+changes — both when the agent calls the ``write_todos`` tool mid-run and
+when a user edits the list from the parameter panel (``set_todos`` WS
+handler). It is deliberately NOT a ``node_status`` "executing" broadcast:
+a manual edit must not make the canvas node glow as if it were running.
+The frontend routes the ``todos_updated`` wire key to refresh the open
+Current Todos panel.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from services.events.envelope import WorkflowEvent
+
+# Wire-routing key the FE switch dispatches on (outer WS frame ``type``).
+_TODOS_UPDATED_WIRE_KEY = "todos_updated"
+
+
+def todos_updated(
+ *,
+ session_key: str,
+ todos: List[dict],
+ node_id: Optional[str] = None,
+ workflow_id: Optional[str] = None,
+) -> WorkflowEvent:
+ """Todo-list-changed envelope. ``subject`` is the session key (the
+ workflow the list is shared under) so the FE can route the update to
+ the right ``['todos', session_key]`` query."""
+ data: Dict[str, Any] = {
+ "session_key": session_key,
+ "todos": todos,
+ "node_id": node_id,
+ "workflow_id": workflow_id,
+ }
+ return WorkflowEvent(
+ source="machinaos://nodes/write_todos",
+ type="com.machinaos.todos.updated",
+ subject=session_key,
+ data=data,
+ )
+
+
+async def dispatch_todos_updated(
+ *,
+ session_key: str,
+ todos: List[dict],
+ node_id: Optional[str] = None,
+ workflow_id: Optional[str] = None,
+) -> None:
+ """Emit the typed ``todos_updated`` CloudEvent via the centralized
+ dispatcher (``services.events.dispatch.emit``)."""
+ from services.events.dispatch import emit
+
+ await emit(
+ todos_updated(
+ session_key=session_key,
+ todos=todos,
+ node_id=node_id,
+ workflow_id=workflow_id,
+ ),
+ wire_routing_key=_TODOS_UPDATED_WIRE_KEY,
+ )
+
+
+__all__ = ["dispatch_todos_updated", "todos_updated"]
diff --git a/server/nodes/tool/write_todos/_handlers.py b/server/nodes/tool/write_todos/_handlers.py
new file mode 100644
index 00000000..8721e03b
--- /dev/null
+++ b/server/nodes/tool/write_todos/_handlers.py
@@ -0,0 +1,72 @@
+"""WebSocket handlers for the writeTodos plugin.
+
+Owned by the plugin folder; the package ``__init__`` registers the
+:data:`WS_HANDLERS` dict into ``services.ws_handler_registry`` so the
+core router needs no edit (same self-containment pattern as
+``nodes/telegram/_handlers.py``).
+
+These give the parameter-panel Current Todos editor a read/write path
+into the live ``TodoService`` state, which is keyed by ``workflow_id``
+(``node_id`` fallback) — the same precedence the ``write`` op uses, so
+the panel sees exactly what the agent wrote at runtime.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from fastapi import WebSocket
+
+from services.plugin.ws import ws_response
+
+from ._events import dispatch_todos_updated
+
+
+def _session_key(data: Dict[str, Any]) -> str:
+ """Mirror the write op's keying precedence
+ (``__init__.py``: ``ctx.workflow_id or ctx.node_id or "default"``)."""
+ return data.get("workflow_id") or data.get("node_id") or "default"
+
+
+@ws_response
+async def handle_get_todos(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Return the current todo list for the open workflow (node_id fallback)."""
+ from services.todo_service import get_todo_service
+
+ session_key = _session_key(data)
+ return {
+ "success": True,
+ "todos": get_todo_service().get(session_key),
+ "session_key": session_key,
+ }
+
+
+@ws_response
+async def handle_set_todos(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Replace the workflow's todo list (panel edits) and broadcast the change.
+
+ ``TodoService.write`` validates + normalises each item (drops anything
+ but ``content``/``status``, coerces unknown statuses to ``pending``),
+ so the returned ``stored`` list is the canonical state.
+ """
+ from services.todo_service import get_todo_service
+
+ session_key = _session_key(data)
+ stored = get_todo_service().write(session_key, data.get("todos", []) or [])
+
+ await dispatch_todos_updated(
+ session_key=session_key,
+ todos=stored,
+ node_id=data.get("node_id"),
+ workflow_id=data.get("workflow_id"),
+ )
+ return {"success": True, "todos": stored, "session_key": session_key}
+
+
+WS_HANDLERS = {
+ "get_todos": handle_get_todos,
+ "set_todos": handle_set_todos,
+}
+
+
+__all__ = ["WS_HANDLERS", "handle_get_todos", "handle_set_todos"]
diff --git a/server/tests/nodes/test_write_todos_handlers.py b/server/tests/nodes/test_write_todos_handlers.py
new file mode 100644
index 00000000..966b4c8c
--- /dev/null
+++ b/server/tests/nodes/test_write_todos_handlers.py
@@ -0,0 +1,78 @@
+"""writeTodos parameter-panel WS handlers (get_todos / set_todos).
+
+The Current Todos editor reads/writes the live TodoService state through
+these handlers. They key by ``workflow_id`` (``node_id`` fallback) —
+mirroring the ``write`` op — and ``set_todos`` normalises through
+``TodoService.write`` (drops non-dict items, coerces unknown statuses to
+``pending``).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from nodes.tool.write_todos._handlers import handle_get_todos, handle_set_todos
+from services.todo_service import get_todo_service
+
+
[email protected](autouse=True)
+def _no_dispatch(monkeypatch):
+ """Stub the centralized dispatch so the handler test doesn't depend on
+ Temporal Visibility / the WS broadcaster being wired."""
+
+ async def _noop(**_kwargs):
+ return None
+
+ monkeypatch.setattr("nodes.tool.write_todos._handlers.dispatch_todos_updated", _noop)
+
+
+async def test_set_then_get_round_trips_and_normalises():
+ wf = "test-wf-round-trip"
+ get_todo_service().clear(wf)
+
+ set_resp = await handle_set_todos(
+ {
+ "workflow_id": wf,
+ "todos": [
+ {"content": "first", "status": "in_progress"},
+ {"content": "second", "status": "bogus_status"}, # coerced -> pending
+ {"status": "completed"}, # no content -> dropped
+ "not-a-dict", # dropped
+ ],
+ },
+ None,
+ )
+
+ assert set_resp["success"] is True
+ assert set_resp["session_key"] == wf
+ assert set_resp["todos"] == [
+ {"content": "first", "status": "in_progress"},
+ {"content": "second", "status": "pending"},
+ ]
+
+ get_resp = await handle_get_todos({"workflow_id": wf}, None)
+ assert get_resp["success"] is True
+ assert get_resp["todos"] == set_resp["todos"]
+
+
+async def test_session_key_falls_back_to_node_id():
+ node_id = "writeTodos-test-node"
+ get_todo_service().clear(node_id)
+
+ await handle_set_todos(
+ {"node_id": node_id, "todos": [{"content": "node-scoped", "status": "pending"}]},
+ None,
+ )
+ # No workflow_id -> keyed by node_id; get with the same fallback resolves it.
+ get_resp = await handle_get_todos({"node_id": node_id}, None)
+ assert get_resp["session_key"] == node_id
+ assert get_resp["todos"] == [{"content": "node-scoped", "status": "pending"}]
+
+
+async def test_get_unknown_session_returns_empty():
+ resp = await handle_get_todos({"workflow_id": "never-written"}, None)
+ assert resp["success"] is True
+ assert resp["todos"] == []
diff --git a/server/tests/test_node_spec.py b/server/tests/test_node_spec.py
index 1b21cab1..f922e086 100644
--- a/server/tests/test_node_spec.py
+++ b/server/tests/test_node_spec.py
@@ -892,6 +892,9 @@ class TestNodeSpecContractInvariants:
"isMasterSkillEditor",
"isMemoryPanel",
"isToolPanel",
+ # writeTodos: render the editable Current Todos manager in the
+ # middle section (in addition to isToolPanel).
+ "isTodoEditor",
"isMonitorPanel",
"showLocationPanel",
"isAndroidToolkit",