Self-improving AI Employees for everyone
Write Todos (writeTodos)
| Field | Value |
|---|---|
| Category | ai_tools (tool-only ToolNode; group ("tool", "ai")) |
| Backend handler | server/nodes/tool/write_todos/__init__.py — WriteTodosNode, dispatched via BaseNode.execute() + the @Operation("write") method (logic inlined; the standalone services/handlers/todo.py::handle_write_todos / execute_write_todos still exist but are no longer the dispatch path) |
| Service | server/services/todo_service.py::TodoService |
| Tests | server/tests/nodes/test_ai_tools.py |
| Skill (if any) | server/skills/assistant/write-todos-skill/SKILL.md |
| Dual-purpose tool | ToolNode - tool name write_todos |
Purpose
Lets an AI Agent maintain a structured, per-session checklist while working
on a multi-step task. Each call replaces the entire todo list for the
session with the new snapshot the agent produces, then broadcasts the new
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.
- Source of truth = the live
TodoServicelist (sameworkflow_id→node_idkey as thewriteop), NOTparameters.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, seeserver/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 viaTodoService.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
writeop ANDset_todosemit the typedtodos_updatedCloudEvent via the centralizedservices.events.dispatch.emit(server/nodes/tool/write_todos/_events.py); the FEtodos_updatedcase inWebSocketContextwrites the innertodosinto['todos', session_key]. This is a plain CloudEvent (NOT anode_status"executing" broadcast), so a manual edit never makes the canvas node glow.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream data (declared but not consumed by the write op) |
Parameters
The WriteTodosParams model field IS the LLM-provided tool arg (no separate
toolName / toolDescription node params — those live on the class as
tool_name / tool_description).
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
todos |
Array<TodoItem> |
[] |
no | - | Full replacement snapshot. TodoItem = {id?: string, content: string, status: 'pending' | 'in_progress' | 'completed'}. A JSON-encoded string is coerced to a list by the _coerce_todos field_validator(mode="before") (handles Gemini stringified-array args). |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-tool |
object | Tool result returned to the LLM (WriteTodosOutput has extra="allow", so the dict below passes through) |
Output payload (TypeScript shape)
{
message: string; // "Updated todo list (<N> items)"
todos: Array<{ id?: string; content: string; status: string }>; // the validated list (NOT a JSON string)
count: number; // len(stored)
}
Note: the op returns the validated todos LIST, not a JSON string. The
pre-fix format_for_llm() call that stringified this leaked a raw JSON string
into the key, which the WriteTodosOutput contract now rejects — the
LLM-facing serialization happens downstream.
Logic Flow
flowchart TD
A[BaseNode.execute -> write ctx params] --> D[session_key = ctx.workflow_id OR ctx.node_id OR default]
D --> E[service = get_todo_service singleton]
E --> F[service.write session_key todos dumped from params.todos]
F --> G[Per-item validation inside TodoService]
G --> I{broadcaster on ctx.raw?}
I -- yes --> J[await broadcaster.update_node_status node_id executing<br/>data.phase = todo_update<br/>data.todos = stored<br/>workflow_id]
I -- no --> K[skip]
J --> M[dispatch_todos_updated CloudEvent via services.events.dispatch.emit]
K --> M
M --> L[Return message + todos list + count]
Decision Logic
- Session key:
workflow_idif truthy, elsenode_id, else literal"default". - Empty / malformed items dropped:
- Non-dict entries: skipped silently.
content.strip() == "": skipped silently.statusnot in{pending, in_progress, completed}: coerced to"pending".
- Full replacement semantics: each call overwrites
_store[session_key]entirely - there is no merge / append. Agents are expected to send the complete snapshot. - Broadcast guarded:
update_node_statusis called only when bothbroadcasterandnode_idare truthy, so direct invocations without a broadcaster still succeed silently. - Status
"executing"(not"success"): the broadcast uses the status string"executing"withdata.phase = "todo_update", which the frontend uses to refresh the checklist without moving the node out of its current execution state.
Side Effects
- In-memory state writes:
TodoService._store[session_key] = json.dumps(validated). State persists for the lifetime of the Python process only. - Database writes: none.
- Broadcasts (two per successful write):
StatusBroadcaster.update_node_status(node_id, "executing", {"phase": "todo_update", "todos": [...]}, workflow_id=...)— drives the canvas glow; only when a broadcaster is present onctx.raw.dispatch_todos_updated(...)— typedtodos_updatedCloudEvent (com.opencompany.todos.updated) viaservices.events.dispatch.emit(server/nodes/tool/write_todos/_events.py), refreshing the open Current Todos panel's['todos', session_key]query. Fires unconditionally.
- External API calls: none.
- File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: none.
- Services:
TodoServicesingleton (get_todo_service());StatusBroadcasterviacontext['broadcaster']. - Python packages: stdlib
jsononly. - Environment variables: none.
Edge cases & known limits
- Process-local state: a server restart clears every todo list. Horizontal scaling never shares state across workers.
- No TTL / cleanup: sessions accumulate forever in
_storeunlessTodoService.clear(session_key)is called explicitly (no caller does this today). - All validation silent: dropping an item with empty content or coercing an invalid status never produces a warning in the return payload - only a DEBUG log line.
- Broadcast failures bubble up: the
writeop awaitsupdate_node_status; if the broadcaster raises, the exception bubbles up toBaseNode.execute()(notry/exceptinside the op). todosreturned as a list, not a JSON string: the Output contract declarestodos: Optional[list]; returning a stringified list is rejected byBaseNode._serialize_result.- Content is trimmed (
.strip()) but otherwise not sanitised - markdown or HTML in content survives untouched.
Related
- Sibling tools:
calculatorTool,currentTimeTool,duckduckgoSearch,taskManager,agentBuilder - Skill using this tool:
write-todos-skill/SKILL.md - Architecture docs: Status Broadcaster, Agent Architecture