Skip to content

Self-improving AI Employees for everyone

docs(home): document Talk, the talk line, simpler hiring and the Agent Builder

trohitgbffcdf0b306c
diff --git a/CLAUDE.md b/CLAUDE.md
index 39a30f63..51abe884 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -13,7 +13,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[UI Migration Plan](./docs-internal/ARCHIVE/ui_migration_plan.md)** | *Archived.* antd → shadcn/ui migration completion log (Waves 1–10). Current state lives in [Frontend Architecture](./docs-internal/frontend_architecture.md) and [Theme System](./docs-internal/theme_system.md). |
| **[Temporal Cleanup & Resilience Plan (Waves 15-18)](./docs-internal/ARCHIVE/TEMPORAL_CLEANUP_AND_RESILIENCE_PLAN.md)** | *Archived — all four waves shipped.* 15 dead-code retirement (Redis-Streams branch in event_waiter, APScheduler cron stack, orphaned `connection_status` factory), 16 per-queue task routing (`TemporalWorkerPool`), 17 resilience hardening (cron `catchup_window`, SDK interceptors, `DEPLOYMENT_MODE`, periodic heartbeats; the one-shot LLM-step retry it records was later reverted to unlimited-with-backoff), 18 worker performance tuning. Current settings live in [Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md). |
| **[Node Allowlist](./docs-internal/node_allowlist.md)** | Single-config UI visibility — `server/config/node_allowlist.json` controls which nodes / credential categories / skill folders show in the UI. Five lists with two enforcement tiers (mode-gated allowlist + absolute blocklist). `useNodeAllowlist` hook exposes `isVisible` / `isBlocked` / `isAllowed` / `isCredentialCategoryDisabled` / `isSkillFolderDisabled`. Adding a new disabled domain = single JSON edit, no code change. |
-| **[Normal Mode (Home)](./docs-internal/normal_mode.md)** | The owner-facing landing screen: describe a job, an LLM on the server drafts a setup screen (a JSON UI spec the client parses, normalises and renders from a fixed catalogue), and Hire builds, validates, saves and starts one workflow per AI employee (`services/employees/`, graph built from `config/employee_apps.json` plus the owner's skill library and a Canvas node, and checked against `node_allowlist.json` `enabled_nodes`). Covers the screen switch (`app/`, `shellMode` / `ui_shell_mode`, `VITE_NORMAL_MODE=false` kill switch, Home shows light/dark only), the employee card, the `approvalGate` "ask me before sending" step, run records for "done today" (`machina-run-record-v1`), automatic-pause reasons, Settings (Profile fields; usage-only Billing via `get_employee_usage`; Skills, the user-skills library each new hire copies onto a Skills node; consumer Connectors with `publisher` / `verified`; Plugins, the starter bundles in `hire/starters.json`; the last three share one catalog page), the Workspace dock (an employee's Canvas board, named by the summary's `canvas_node_id`; a live Browser tab with user takeover, shared with Dev mode; Mobile shows the managed local Android phone), the "Web browser" app (read-only under "ask me first" through the tool's `ask_first_params`; while the agent waits in `request_user` the summary's `browser_request` shows Needs you and Help in browser), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` broadcasts. |
+| **[Normal Mode (Home)](./docs-internal/normal_mode.md)** | The owner-facing landing screen: describe a job, an LLM on the server drafts a setup screen (a JSON UI spec the client parses, normalises and renders from a fixed catalogue), and Hire builds, validates, saves and starts one workflow per AI employee (`services/employees/`, graph built from `config/employee_apps.json` plus the owner's skill library and a Canvas node, and checked against `node_allowlist.json` `enabled_nodes`). Covers the screen switch (`app/`, `shellMode` / `ui_shell_mode`, `VITE_NORMAL_MODE=false` kill switch, Home shows light/dark only), the employee card, the `approvalGate` "ask me before sending" step, run records for "done today" (`machina-run-record-v1`), automatic-pause reasons, Settings (Profile fields; usage-only Billing via `get_employee_usage`; Skills, the user-skills library each new hire copies onto a Skills node; consumer Connectors with `publisher` / `verified`; Plugins, the starter bundles in `hire/starters.json`; the last three share one catalog page), the Workspace dock (an employee's Canvas board, named by the summary's `canvas_node_id`; a live Browser tab with user takeover, shared with Dev mode; Mobile shows the managed local Android phone), the "Web browser" app (read-only under "ask me first" through the tool's `ask_first_params`; while the agent waits in `request_user` the summary's `browser_request` shows Needs you and Help in browser), Talk on the employee page (a thread over the chat session whose id is the workflow id, rows written only through `services/chat_thread.py`; the talk line is chatTrigger → an agent → `chatReply` "Reply in Chat": a chat hire's own agent is its talk agent, other hires get a "Talk with {name}" agent sharing the worker's tools and skills with its own Context, and schedule hires also "Post to Talk"), Turn on Talk (for talk `off`) and Apply (while the summary's `pending_changes` is true) via `enable_employee_talk` / `apply_employee_changes`, each a restart on the saved graph through `services/deployment/restart.py`, self-extension from Talk through the Agent Builder within the Hire rule (`services/employees/policy.py`), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` / `chat.updated` broadcasts. |
| **[Theme System](./docs-internal/theme_system.md)** | 12-way visual theme system — 2 base (light, dark) + 5 utopian (renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion) in **hex + `color-mix()`**; `@theme inline` bridge maps `--color-X: var(--X)` (no `hsl()` wrapper); per-theme files own the colour hex, base.css owns the shared `--tint-*` alpha scale; action role tokens (incl. `-ink` readable text), **per-theme `--code-*` syntax tokens** (tier 6 — the code editor, console/output JSON viewers, and chat code blocks paint in each theme's own palette: keyword→trigger, string→success, number→agent, function→model, on an adaptive dark/light code surface; replaced the global dracula `--prism-*` block + dead `getPrismTokenCSS`; the `OutputPanel` JSON viewer reads the same vars), per-theme `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-component decorative ornaments (panel textures + canvas decorations + node pseudo-element overlays + theme-specific keyframes), **canvas-node visual contract via `--node-color` CSS custom property** (no inline `background` / `border` on node components — base.css + per-theme CSS owns visuals; `NodeStyle` helper type at [types/NodeTypes.ts](./client/src/types/NodeTypes.ts) makes the inline custom-prop typecheck-clean), **`--node-pulse-color` separate from `--node-color`** so executing-node glow uses each theme's highest-contrast accent regardless of plugin accent (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine, etc.), **`data-page-hidden` animation pause** (set by `app/usePageActivitySync.ts`, mounted in `AppShell` on both screens, while the tab is hidden or the window is blurred; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyph system** (290 inline SVG glyph strings across 29 keys × 10 themes via [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts) + theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **decorative HTML primitives** (`<SvgFilterDefs>` mounting `#ink-blot` / `#noise` / `#crt` filter IDs at app root, `<DropCap>` wrapper for Renaissance ornament rule), **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), **per-theme scrollbar webkit rules** in all 12 themes, 9-event WebAudio sound system (10 packs via `--sound-pack` token + `useSound()` hook + global hover delegate + sonner toast monkey-patch + `withSound()` HOC + `Sounds.unlock()` gesture-unlock for AudioContext autoplay-policy compliance), `@media (prefers-reduced-motion: reduce)` accessibility, 30 ms throttle on `type` / `hover`, migration recipe, anti-patterns. Read this before adding a new theme, migrating a component to the new contract, or adding a canvas-node component. |
| **[Design System Bundle](./docs-internal/design-system/IMPLEMENTATION.md)** | Canonical, vendored design-system reference (extracted from this repo; see its `IMPLEMENTATION.md` for the contract). Tokens are **hex + `color-mix()`** (`tokens/{colors,typography,spacing,motion,fonts,base}.css`) — the format the live codebase standardizes on. Includes 34 reference components (`components/`, inline-style reference only — recreate in Tailwind/shadcn idioms), full-app UI kit (`ui_kits/opencompany/index.html`), 12-theme docs (`guidelines/THEMES.md`), **the merged handoff brief (`HANDOFF.md` — glow-ladder traps, step-edge contract, toolbar layout traps, canvas-layer asymmetries, plus the recorded product amendments)**, and **the panel×theme fidelity target (`reference-mockup/Panel Theme Matrix.dc.html` — 17 panels × 12 themes, open in a browser)**. `reference/themes/` no longer vendors CSS snapshots — it points at the authoritative [client/src/themes/](./client/src/themes/). Copy token values verbatim; do not re-derive by eye. Pairs with [Theme System](./docs-internal/theme_system.md). |
| **[Schema Source of Truth RFC](./docs-internal/ARCHIVE/schema_source_of_truth_rfc.md)** | *Archived — shipped.* Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons; `VITE_NODESPEC_BACKEND` defaults on and the frontend node definitions are gone. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<plugin>/__init__.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. Current reference: [Plugin System](./docs-internal/plugin_system.md). |
@@ -655,7 +655,7 @@ The project uses WebSocket as the primary communication method between frontend
- `server/routers/websocket.py` - WebSocket endpoint; the live handler set is the `MESSAGE_HANDLERS` dict plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain a count here.
- `server/services/status_broadcaster.py` - Connection management and broadcasting
-**Canvas mutations from the backend** -- any handler that needs to add / move / delete nodes or edges (auto-add-skill on tool connect, Agent Builder runtime tools called by the LLM mid-execution, future workflow-template features) returns a workflow-ops batch (`{operations: [...]}`) and the frontend applies it through `applyOperations` in [client/src/lib/workflowOps.ts](./client/src/lib/workflowOps.ts). Backend builders live in [server/services/workflow_ops.py](./server/services/workflow_ops.py). Two delivery modes: request/response (frontend-driven, e.g. auto-skill) and push broadcast (`send_custom_event('workflow_ops_apply', ...)`, picked up by `useWorkflowOpsListener`). Full spec: [docs-internal/workflow_ops_protocol.md](./docs-internal/workflow_ops_protocol.md).
+**Canvas mutations from the backend** -- any handler that needs to add / move / delete nodes or edges (auto-add-skill on tool connect, Agent Builder runtime tools called by the LLM mid-execution, future workflow-template features) returns a workflow-ops batch (`{operations: [...]}`) and the frontend applies it through `applyOperations` in [client/src/lib/workflowOps.ts](./client/src/lib/workflowOps.ts). Backend builders live in [server/services/workflow_ops.py](./server/services/workflow_ops.py). Two delivery modes: request/response (frontend-driven, e.g. auto-skill) and push broadcast (`workflow_ops_apply`, sent by `services/workflow_ops.broadcast_workflow_ops` and picked up by `useWorkflowOpsListener`). A server-side change to a saved workflow (Turn on Talk, the Agent Builder) goes through `services/workflow_storage/mutate.apply_graph_additions`, which writes the nodes, edges and parameter rows in one transaction and pushes `workflow_ops_apply` with `persisted: true`; editors adopt the server's ids without saving (`useSavedGraphSync` also updates the workflow the app store holds while Home shows). Full spec: [docs-internal/workflow_ops_protocol.md](./docs-internal/workflow_ops_protocol.md).
## Implemented Node Types
@@ -987,7 +987,7 @@ const [selectedConsoleId, setSelectedConsoleId] = useState<string>('');
```
#### Chat Message Persistence
-Chat messages are persisted to SQLite database and survive server restarts.
+Chat messages are persisted to SQLite database and survive server restarts. A workflow's session id is its workflow id (`"default"` with no workflow open), and Home shows the same thread as Talk on the employee's page. Every row is written through [`services/chat_thread.py`](./server/services/chat_thread.py) (`record_chat_message` / `clear_chat_thread`), which stamps the session's live generation and broadcasts the identity-only `chat.updated`; agents answer into the thread through the `chatReply` ("Reply in Chat") node.
**Database Model** (`server/models/database.py`):
```python
@@ -995,6 +995,7 @@ class ChatMessage(SQLModel, table=True):
__tablename__ = "chat_messages"
id: Optional[int] = Field(default=None, primary_key=True)
session_id: str = Field(default="default", index=True, max_length=255)
+ execution_id: Optional[str] # the generation (root_execution_id) it was written in
role: str = Field(max_length=20) # 'user' or 'assistant'
message: str = Field(max_length=50000)
created_at: datetime
@@ -1003,13 +1004,14 @@ class ChatMessage(SQLModel, table=True):
**WebSocket Handlers** (`server/routers/websocket.py`):
| Handler | Description |
|---------|-------------|
-| `send_chat_message` | Send message to chat, optionally targeting specific node via `node_id` |
-| `get_chat_messages` | Retrieve chat history for session |
+| `send_chat_message` | Save the message and dispatch it to the workflow's chatTriggers. A workflow session answers `delivery: "now"` (running / starting / resuming) or `"queued"` (paused / pausing, runs on Resume); in any other state `not_running`, saving nothing |
+| `get_chat_messages` | A session's messages, oldest first: `{id, role, message, timestamp, run_key}` (UTC-offset timestamps; `run_key` = the generation). The latest generation only (none after a Reset), unless `all_generations` (Home's thread spans restarts) |
| `clear_chat_messages` | Clear all messages for session |
+| `save_chat_message` | Save one message with the given role |
**Database Methods** (`server/core/database.py`):
-- `add_chat_message(session_id, role, message)` - Add message to database
-- `get_chat_messages(session_id, limit)` - Get messages with pagination
+- `add_chat_message(session_id, role, message, execution_id=None)` - Add message to database
+- `get_chat_messages(session_id, limit=None, execution_id=None)` - Newest `limit` messages, oldest first, optionally of one generation
- `clear_chat_messages(session_id)` - Delete all messages for session
#### Console Log Persistence
@@ -2508,7 +2510,7 @@ Updated `client_left` and presence handlers use `has_real_android_devices()` ins
| **Usage/Compaction** | `get_api_usage_summary`, `get_compaction_stats`, `configure_compaction`, `get_provider_usage_summary` |
| **Agent Teams** | `create_team`, `get_team`, `get_team_status`, `dissolve_team`, `add_team_task`, `claim_team_task`, `complete_team_task`, `get_team_tasks`, `send_team_message`, `get_team_messages` |
| **Model Registry** | `get_model_constraints`, `refresh_model_registry` |
-| **Employees (Normal mode)** | `list_employees`, `get_employee`, `get_employee_usage`, `generate_employee_setup`, `cancel_employee_setup`, `hire_employee`, `start_employee` (see [normal_mode.md](./docs-internal/normal_mode.md)) |
+| **Employees (Normal mode)** | `list_employees`, `get_employee`, `get_employee_usage`, `generate_employee_setup`, `cancel_employee_setup`, `hire_employee`, `start_employee`, `enable_employee_talk`, `apply_employee_changes` (see [normal_mode.md](./docs-internal/normal_mode.md)) |
| **Approvals** | `list_approvals`, `decide_approval` (the `approvalGate` node's drafts) |
#### Broadcast Messages (Server -> All Clients)
@@ -2521,6 +2523,7 @@ Updated `client_left` and presence handlers use `has_real_android_devices()` ins
| `agent_capability` | CloudEvents v1.0 envelope (`com.opencompany.agent.(skill|tool).*`) — exact-agent capability lifecycle with deterministic Temporal IDs, `(source,id)` deduplication, sanitized data, and an optional exact target node |
| `employee_lifecycle` | CloudEvents v1.0 envelope (type=`com.opencompany.employee.{hired,updated,removed}`, subject = workflow id) — Home's team list; `updated` is coalesced to one per second per employee, control changes go out at once |
| `approval_lifecycle` | CloudEvents v1.0 envelope (type=`com.opencompany.approval.{requested,decided,expired,cancelled}`) — identity only, never the draft or the recipient; the card refetches via `list_approvals` |
+| `chat.updated` | CloudEvents v1.0 envelope (type=`com.opencompany.chat.updated`, data `{workflow_id, session_id, role}`) — sent directly (not `dispatch.emit`) by `services/chat_thread.py` after every chat insert and clear; identity only, Home's thread and the editor's chat pane refetch via `get_chat_messages` |
| `workflow_lifecycle` | CloudEvents v1.0 envelope for workflow stages (`deployment.*`, `lock.*`, `execution.*`, `imported`, `renamed`, `created`, `deleted`) — other tabs invalidate their workflow lists |
| `deployment_snapshot` | CloudEvents v1.0 envelope (type=`workflow.deployment.snapshot`) — pushed once per WS connect from `broadcaster._send_deployment_snapshot`; lets the FE reconcile stale `deploymentStatus.isRunning=true` after a backend restart wiped `DeploymentManager._deployments`. Empty list is meaningful (forces reset). |
| `variable_update` | Single variable value change |
@@ -2780,7 +2783,7 @@ This function:
- **Typed SDK error → `LLMError` → `NodeUserError`**: Native providers normalize SDK failures into structured `LLMError` values carrying category, retryability, HTTP status, provider code, request ID, and retry-after metadata. `ChatUnifier` translates them at the execution boundary into a user-safe `NodeUserError`; `BaseNode.execute()` logs that at WARN with one line and no stack trace. Unexpected exceptions retain the full-traceback path. In-process agent turns retry only errors marked retryable, while Temporal owns activity retries and disables the inner retry loop.
- **Plugin extraction (Wave 11.I)**: every plugin's WS handlers, OAuth client, FastAPI router, and lifecycle service live entirely under `nodes/<plugin>/`. Eight plugin domains migrated this round (whatsapp / twitter / google-workspace / android / browser / email / code / credential-validation-scaffold for maps+apify+ollama+lmstudio) follow the telegram pattern. `routers/websocket.py` shrunk from ~3,785 to ~2,977 LOC (-808). Three plugin routers (`routers/twitter.py`, `routers/google.py`, `routers/android.py`) moved into `nodes/<plugin>/_router.py` and mount via the plugin-router loop in `main.py`; the explicit `app.include_router(<plugin>.router)` calls and `from routers import <plugin>` imports in `main.py` are gone. **`register_router(router, name=...)` is the new sibling helper to `register_ws_handlers` (same file: `services/ws_handler_registry.py`)** — the generic registry set has grown since (the Plugin System row at the top of this file gives the `grep` for the live list). **`Credential.validate(data) -> dict` + `Credential._probe(api_key) -> ProbeResult` is the new shared validator scaffold** in `services/plugin/credential.py` — replaces the per-router `_SPECIAL_PROVIDER_VALIDATORS` dict; one `_LLMApiKey._probe` method serves all 10 cloud LLM providers, dedicated `_probe` overrides handle Maps + Apify, `_LocalLLM.validate` overrides for Ollama / LM Studio's 2-storage edge case. **`tests/test_plugin_self_containment.py` locks the contract** with 10 invariant classes (forbidden-imports / no-router-outside-nodes / per-plugin self-registration / registry-API sanity / stale-paths-absent / main.py-does-not-mount / WS_HANDLERS-non-empty / plugin-folder-has-node-file / typed-event-factories / package-imports-cleanly); same `inspect.getsource` introspection style as `test_credential_broadcasts.py`. Wire format unchanged — frontend WS message-type strings (`whatsapp_status`, `twitter_oauth_login`, `google_oauth_status`, `android_relay_connect`, etc.) and HTTP route paths (`/api/twitter/callback`, `/api/google/callback`, `/api/android/*`) are byte-identical post-migration.
- **Typed CloudEvents factory pattern for new broadcasts** (b6aecd3): every new server→FE lifecycle broadcast follows the recipe locked by `broadcast_credential_event`, `broadcast_agent_progress`, and `broadcast_agent_capability`. (1) Add a typed factory — convention: `source = "opencompany://services/<area>"`, reverse-DNS `type = "com.opencompany.<area>.<event>"`, and `subject = <exact primary entity id>`. Put snake_case workflow/execution scope inside `data`; CloudEvents extension attribute names MUST be lowercase-alphanumeric, so the historical top-level `workflow_id`/`trigger_node_id`/`correlation_id` fields are compatibility debt and are forbidden on new contracts. (2) Add a broadcaster wrapper that emits `broadcast({type: "<wire_key>", data: event.model_dump(mode="json", exclude_none=True)})`. (3) FE validates `specversion`, ID/source/type, subject ownership, and event-specific payload invariants, deduplicates by `(source,id)`, then writes only the exact scoped entity. (4) Add contract tests in `test_events.py` and keep `tests/test_status_broadcasts.py`'s raw-callsite allowlist empty. Raw `node_status` remains allowed only as the established high-frequency latest-state/reconnect projection paired with a typed lifecycle occurrence; it is not the event of record.
-- **Plugin-folder location for plugin-specific CloudEvents factories** (RFC §6.4): when a typed event is owned by one plugin (telegram, whatsapp, android, email, google, master_skill, agent_builder, webhook_trigger, chat_trigger, agent), the factory + `broadcast_<event>` wrapper live in [`server/nodes/<plugin>/_events.py`](./server/nodes), NOT on `WorkflowEvent` / `StatusBroadcaster` directly. Telegram's [`_events.py`](./server/nodes/telegram/_events.py) is the canonical template — `broadcast_telegram_status` constructs the envelope via a plain factory function and calls `get_status_broadcaster().broadcast(...)` itself. Latest example: [`server/nodes/skill/master_skill/_events.py`](./server/nodes/skill/master_skill/_events.py) (`broadcast_skill_lifecycle("created" \| "updated" \| "deleted" \| "content_saved", name=..., **data_extra)`) — replaces four raw-dict broadcasts in `handle_create_user_skill` / `handle_update_user_skill` / `handle_delete_user_skill` / `handle_save_skill_content` (the last one was previously silent). FE routes wire key `skill_lifecycle` to invalidate `userSkills` + `folderSkills` queries and drop the `skillContent` cache on delete + content_saved so the Master Skill panel refreshes live across every connected client. Cross-cutting events (credential, workflow_lifecycle, agent_progress, agent_capability, node_parameters_updated) keep their `WorkflowEvent` classmethods + `StatusBroadcaster` wrappers — only plugin-scoped events move to the plugin folder.
+- **Plugin-folder location for plugin-specific CloudEvents factories** (RFC §6.4): when a typed event is owned by one plugin (telegram, whatsapp, android, email, google, master_skill, webhook_trigger, chat_trigger, agent), the factory + `broadcast_<event>` wrapper live in [`server/nodes/<plugin>/_events.py`](./server/nodes), NOT on `WorkflowEvent` / `StatusBroadcaster` directly. Telegram's [`_events.py`](./server/nodes/telegram/_events.py) is the canonical template — `broadcast_telegram_status` constructs the envelope via a plain factory function and calls `get_status_broadcaster().broadcast(...)` itself. Latest example: [`server/nodes/skill/master_skill/_events.py`](./server/nodes/skill/master_skill/_events.py) (`broadcast_skill_lifecycle("created" \| "updated" \| "deleted" \| "content_saved", name=..., **data_extra)`) — replaces four raw-dict broadcasts in `handle_create_user_skill` / `handle_update_user_skill` / `handle_delete_user_skill` / `handle_save_skill_content` (the last one was previously silent). FE routes wire key `skill_lifecycle` to invalidate `userSkills` + `folderSkills` queries and drop the `skillContent` cache on delete + content_saved so the Master Skill panel refreshes live across every connected client. Cross-cutting events (credential, workflow_lifecycle, agent_progress, agent_capability, node_parameters_updated) keep their `WorkflowEvent` classmethods + `StatusBroadcaster` wrappers — only plugin-scoped events move to the plugin folder. A core service's own event keeps its factory beside it, so core never imports a plugin `_events.py`: `services/workflow_ops.py` (`workflow_ops_apply`) and `services/chat_thread.py` (`chat.updated`).
- **Operator-metadata fields in credential panels** (f746ddf): when a credential panel needs a non-credential follow-up field (e.g. Telegram bot token + owner chat id), declare it as a second entry in the provider's `fields` array in `server/config/credential_providers.json`. The first field stays the validate/connect target; subsequent fields render below as plain text inputs via `SecondaryFieldRow` in `ApiKeyPanel.tsx` (shadcn `Input` + `Label` + `<ActionButton intent="save">`). Each field carries an optional `help` slot (`FieldDef.help` / `ServerFieldDef.help`) for always-visible explanatory text under the input. Save writes via `panel.actions.save(field.key, value)` → `auth_service.store_api_key` (which is permissive about provider string). The credential class must declare the new key in `extra_fields` (`Credential` subclass attribute) so the storage layer accepts it. Reference: `telegram_owner_chat_id` field.
- **Telegram owner detection — three layers** (f746ddf): the bot owner is captured by THREE independent paths so the realistic setup flows all converge to a working state. (1) **Explicit field**: secondary `FieldDef` in the credentials modal lets the user paste their Telegram user ID directly (recommended; works without DM'ing the bot). (2) **Pre-poll peek** in `connect()` via `_capture_owner_from_pending_updates()` — calls `bot.get_updates(timeout=0)` BEFORE `start_polling(drop_pending_updates=True)` discards the queue, scans for any historical private DM, captures + persists atomically. (3) **Atomic write-through in `_on_message_received`** — persists FIRST, sets in-memory ONLY on success. Invariant: "in-memory has owner ⇒ DB has owner" so a process restart can re-capture cleanly. Failure logged at `ERROR` with `exc_info=True` (was `WARNING` previously, masking persist failures). The lazy fallback in `telegram_send.py` (read DB → `service.set_owner`) sits on top of all three.
- **Supervisor Job Object loud-failure (cli/tree.py + cli/supervisor.py)** (8a64eb9): the Windows process-tree mechanism depends entirely on a Job Object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` (no fallback — `start_new_session` is POSIX-only). `pywin32>=308` is a hard supervisor dependency on Windows; the declaration in the root `pyproject.toml` (where `opencompany-cli` lives — `cli/pyproject.toml` was removed as a stale duplicate) carries an inline comment so future maintainers don't drop it. `_JobObject.__init__` splits failures into explicit `ImportError` (with reinstall command) and `Exception` (with `repr`) branches — both write to `stderr` instead of swallowing. `_JobObject.add()` verifies enrollment via `win32job.IsProcessInJob(handle, self._handle)` after assignment; on mismatch it queries `IsProcessInJob(handle, None)` so the warning explicitly names the wrapper-job hypothesis (npm / bun / conhost wrappers occasionally place us in their own non-nesting Job). `supervisor._spawn_once` checks `add_to_job` return value and emits a yellow `WARN: pid=N not enrolled in Job Object` per child if False. Without these guards, a stale pywin32 install or a wrapping Job Object silently leaks orphan Python processes on every Ctrl-C and they accumulate to the point of holding SQLite locks that block subsequent backend startup.
diff --git a/README.md b/README.md
index 134d7b10..e66704b1 100644
--- a/README.md
+++ b/README.md
@@ -121,7 +121,7 @@ Runs payment operations through Stripe and reacts the moment a payment event hap
- **They remember.** An employee keeps facts, preferences, and decisions in a memory you can open and edit.
- **They pick up where they left off.** Every new message, task, or scheduled run continues the same conversation instead of starting from zero. When the conversation gets long, the employee writes itself a summary and carries on from it.
-- **They add tools when they need them.** Mid-task, an employee can look at its own team, add a tool, attach a skill, or bring in another specialist, and the change stays.
+- **They add tools when they need them.** Ask an employee on its Talk page to take on something new, and it can add a tool or learn a skill from your library, within the rules you hired it with (nothing that sends or spends while it asks you first). A new tool works in that conversation right away; press Apply on its page to make an addition part of all its work.
- **They check their own work.** The lead reviews every result from the team and sends it back if it is not right, before it ever reaches you.
- **You coach them.** Skills are short plain-text playbooks. Edit one and the employee follows it on its next turn. Settings > Skills keeps your library of them, and every new hire starts with the ones you have switched on.
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index 86cd7c99..f1f13cba 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -402,8 +402,10 @@ AgentWorkflow.run(context):
if payload["auto_rebind_tools"] is True:
execute_activity("agent.refresh_tools", {operations: …})
translates add_node ops with component_kind=="tool" OR
- usable_as_tool=True (minus chat-model plugins) into the
- same tool_payload shape prepare_agent_payload emits.
+ usable_as_tool=True (minus chat-model plugins and the
+ Skills node, masterSkill, which is tool-kind but feeds
+ input-skill) into the same tool_payload shape
+ prepare_agent_payload emits.
Reuses ai_service._build_tool_from_node + get_node_class,
yielding fresh AgentToolSpec / ToolDef declarations.
tools.extend(refresh_result["tools"])
@@ -452,7 +454,7 @@ Which graph a firing runs depends on the deployment kind. Controlled generations
**Delegation input contract (input-vs-config separation).** The LLM's `{task, context}` args are per-invocation *input*, not node configuration, and travel as the child workflow input's `invocation` field. `prepare_agent_payload` applies it AFTER its config resolution (`{**node_data, **db_params}` — DB wins for config liveness): `task` → system_message, `context`-or-`task` → prompt — the same semantics as the legacy `handlers.tools._execute_delegated_agent`. Stored node parameters (including the empty default `prompt` the frontend persists on drop) therefore never override the delegated task. A call with both fields empty is rejected at the parent's call boundary (tool-error message to the LLM, no child spawn). Bypass agents dispatched as plain activities (any type outside `AGENT_WORKFLOW_TYPES`: `rlm_agent` / `claude_code_agent` / `vertex_managed_agent`) instead receive the remap directly in `node_data` — their per-type activity consumes `node_data` verbatim with no DB re-merge.
-**Canvas-aware tools** opt into receiving the parent workflow's `nodes`/`edges` by declaring `needs_canvas: ClassVar[bool] = True` on their `BaseNode` subclass. The F4.B tool dispatch reads this via `services.node_registry.get_node_class(node_type).needs_canvas` and forwards `context.get("nodes")` / `context.get("edges")` into `tool_payload`; default plugins keep the empty-canvas optimisation. Today only `agentBuilder` opts in (it walks edges to resolve its calling agent and mutates the canvas). Operations inside agentBuilder reload via `database.get_workflow(workflow_id)` so in-run duplicate detection sees mutations from earlier calls in the same workflow run — see [agent_builder section in CLAUDE.md](../CLAUDE.md).
+**Canvas-aware tools** opt into receiving the parent workflow's `nodes`/`edges` by declaring `needs_canvas: ClassVar[bool] = True` on their `BaseNode` subclass. The F4.B tool dispatch reads this via `services.node_registry.get_node_class(node_type).needs_canvas` and forwards `context.get("nodes")` / `context.get("edges")` into `tool_payload`; default plugins keep the empty-canvas optimisation. Today only `agentBuilder` opts in: `add_tool` compares the run's canvas with the saved graph, so a tool saved earlier but missing from the generation's snapshot comes back as an `add_node` op to bind, with nothing saved. Its calling agent is the `invoking_agent_node_id` this dispatch supplies, else `parent_node_id`, never an edge walk. Operations inside agentBuilder reload via `database.get_workflow(workflow_id)` so in-run duplicate detection sees mutations from earlier calls in the same workflow run — see the [agentBuilder card](./node-logic-flows/ai_tools/agentBuilder.md).
`collect_agent_activities()` registers the agent activities — read the live set
from that function rather than trusting a count here, which drifts on every
@@ -462,7 +464,7 @@ addition. Seven are the core loop activities:
|---|---|
| `agent.prepare_payload` | Resolves the DB-backed payload (provider / model / system_message / user_prompt / `AgentToolSpec`-derived tool definitions / memory_node_id / memory_content / memory_window_size / max_iterations / thinking_config / compaction_threshold / tool_result_max_chars / transcript_budget_bytes / context_pressure_version / auto_rebind_tools), and leaves credential resolution at the LLM activity boundary. Reads `UserSettings.agent_recursion_limit`, `auto_rebind_tools_after_canvas_change`, `tool_result_max_chars`, `max_concurrent_subagents` and `max_delegation_depth`. Recording the three transcript-pressure keys here is what lets a history recorded before them replay the original rules. Applies the optional `invocation` field (delegation children) after config resolution — per-invocation input always beats stored parameters. |
| `agent.execute_llm_step` | One LLM turn. The native branch decodes Message Wire V2, rebuilds `ToolDef` values, calls `run_native_llm_step(ChatUnifier, ...)` with SDK retries disabled, heartbeats while awaiting the provider, and returns the exact assistant message + tool calls + normalized usage. Guards against un-invokable payloads: post-filter system-only message lists raise `ApplicationError(type="EmptyAgentPrompt", non_retryable=True)`. |
-| `agent.refresh_tools` | Translates `workflow_ops` add_node ops (`component_kind="tool"` OR `usable_as_tool=True`) into fresh `AgentToolSpec`-derived `tool_payload` entries via `_build_tool_from_node`. Workflow extends `tools` + `tool_index` from the result. |
+| `agent.refresh_tools` | Translates `workflow_ops` add_node ops (`component_kind="tool"` OR `usable_as_tool=True`; never a chat model or the Skills node) into fresh `AgentToolSpec`-derived `tool_payload` entries via `_build_tool_from_node`. Workflow extends `tools` + `tool_index` from the result. |
| `agent.persist_turn` | Appends the latest human/assistant exchange to memory markdown, trims the window, broadcasts `node.parameters.updated`. |
| `agent.compact_context` | The shared client-side summarizer, run under transcript pressure (step 6 above). Not best-effort: after the activity's retries a failure ends the run with `CompactionError`, because past that point the transcript could only grow until the provider rejected it. |
| `agent.store_output` | Writes `output_main` / `output_top` / `output_0` so downstream nodes resolve `{{aiAgent.response}}` via `ParameterResolver`. |
diff --git a/docs-internal/agent_architecture.md b/docs-internal/agent_architecture.md
index f5e330ac..e230f3c5 100644
--- a/docs-internal/agent_architecture.md
+++ b/docs-internal/agent_architecture.md
@@ -210,20 +210,22 @@ Result Limit. See [memory_compaction.md](memory_compaction.md) and
### Hot rebind after canvas mutation
-When `agentBuilder` (the only canvas-mutating tool today) spawns a new node mid-run via `add_tool` / `add_skill` / `add_subagent`, the operation returns a `workflow_ops` batch in its result's `operations` field. The loop detects the field, calls `rebind_from_operations(ops)`, and extends the bound tool surface so the LLM can invoke the new tool in the very next iteration — no Run-stop-Run cycle.
+When `agentBuilder` (the only canvas-mutating tool today) adds a tool (`add_tool`) or a teammate (`add_subagent`) mid-run, it saves the change (`apply_graph_additions`) and returns the saved `workflow_ops` batch in its result's `operations` field. The loop detects the field, calls `rebind_from_operations(ops)`, and extends the bound tool surface so the LLM can invoke the new tool in the very next iteration — no Run-stop-Run cycle. A deployed run starts from the generation's frozen snapshot, so a tool saved in an earlier run can be missing from a later one; `add_tool` then returns that saved node alone (a bind-only batch, nothing saved) for the loop to bind. `add_skill` returns no operations: a skill is not bound as a tool, and a merge into an existing Skills node applies from the next run.
Closure responsibilities:
- **`_rebind_from_operations(ops) -> List[AgentToolSpec]`** (in
`execute_agent` / `execute_chat_agent`): filter ops for `add_node` with the
plugin class's `component_kind == "tool"` OR `usable_as_tool=True`
- (excluding `component_kind == "model"`), synthesize a `tool_info` dict,
+ (excluding `component_kind == "model"`, and the Skills node, whose
+ `uiHints.isMasterSkillEditor` marks it: tool-kind, but it feeds
+ `input-skill`), skip a node already bound, synthesize a `tool_info` dict,
call `self._build_tool_from_node(tool_info)`, and return the new specs. Tool
configs get folded into the captured `tool_configs` dict so
`tool_executor` can dispatch the new call.
- The closure is gated on the user toggle: `UserSettings.auto_rebind_tools_after_canvas_change` (default `True`). When off, the LLM is told "Available on your next turn" in the operation summary and the closure isn't wired.
-For the F4.B Temporal path, the in-process closure is replaced by the `agent.refresh_tools` activity; see [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md).
+For the F4.B Temporal path, the in-process closure is replaced by the `agent.refresh_tools` activity, which applies the same filter and also binds agent delegates; see [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md). It cannot see what the run already holds, so re-adding a tool added earlier in the same run makes `AgentWorkflow` report a duplicate tool name (the tool stays callable).
### Where it's called
diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.md
index c9dfb4c4..b1c311e7 100644
--- a/docs-internal/event_framework.md
+++ b/docs-internal/event_framework.md
@@ -215,7 +215,11 @@ Plugin-specific events (e.g. `com.opencompany.telegram.message.received`)
live in `nodes/<plugin>/_events.py`. Cross-cutting factories
(`credential`, `oauth_completed`, `agent_progress`, `agent_capability`, `task_completed`,
`workflow_lifecycle`, `deployment_snapshot`, `team_event`,
-`node_parameters_updated`) stay in `services/events/envelope.py`.
+`node_parameters_updated`) stay in `services/events/envelope.py`. A core
+service that owns its event keeps the factory beside it, so core code never
+imports a plugin's `_events.py`: `services/chat_thread.py` (`chat_updated`)
+and `services/workflow_ops.py` (`workflow_ops_applied`, sent by
+`broadcast_workflow_ops`).
See RFC §6.4 for the classification rule + the canonical
`telegram/_events.py` example.
@@ -243,6 +247,23 @@ the Browser plugin's `browser_updated`, `browser_profiles_updated` and
`browser_runtime` (`com.opencompany.browser.*`, in `nodes/browser/_events.py`;
identity and state only, never a URL, a page title or cookie data).
+Two core events follow it too. `chat.updated` (`com.opencompany.chat.updated`,
+in `services/chat_thread.py`) goes out after every chat row insert and clear,
+with data `{workflow_id, session_id, role}` (`role` null for a clear,
+`workflow_id` null for session `"default"`): identity only, so Home's thread
+and the editor's chat pane refetch through `get_chat_messages`. The
+workflow-ops push `workflow_ops_apply` (`com.opencompany.workflow.ops.applied`,
+built and sent by `services/workflow_ops.broadcast_workflow_ops`) is the one
+whose frame is the event's flat data,
+`{workflow_id, caller_node_id, operations, persisted?}`, the shape
+`useWorkflowOpsListener` reads.
+`persisted: true` marks a batch the server already saved
+(`services/workflow_storage/mutate.apply_graph_additions`: Turn on Talk, the
+Agent Builder); its ops carry the server's ids and full parameter rows, and
+editors adopt them without saving. (The Vertex managed agent's cloud-tool
+nodes still send their own frame of the same shape, never persisted.) See
+[workflow_ops_protocol.md](./workflow_ops_protocol.md#persisted-batches).
+
Rule of thumb: **if no `register_canary_trigger_type` call names your event
type, broadcast it directly.** Reach for `emit` only when a Temporal workflow
has to receive it. `tests/nodes/test_context_events.py` locks this for Context
diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.md
index b72daed8..dd377c38 100644
--- a/docs-internal/node-logic-flows/README.md
+++ b/docs-internal/node-logic-flows/README.md
@@ -96,6 +96,7 @@ that a retired node remains registered.
### chat_utility
- [Chat History (`chatHistory`)](./chat_utility/chatHistory.md)
+- [Reply in Chat (`chatReply`)](./chat_utility/chatReply.md)
- [Chat Send (`chatSend`)](./chat_utility/chatSend.md)
- [Console (`console`)](./chat_utility/console.md)
- [File Handler (`fileHandler`)](./chat_utility/fileHandler.md)
diff --git a/docs-internal/node-logic-flows/ai_tools/agentBuilder.md b/docs-internal/node-logic-flows/ai_tools/agentBuilder.md
index 92f3b0d1..bea00d83 100644
--- a/docs-internal/node-logic-flows/ai_tools/agentBuilder.md
+++ b/docs-internal/node-logic-flows/ai_tools/agentBuilder.md
@@ -3,41 +3,50 @@
| Field | Value |
|------|-------|
| **Category** | ai_tools (dedicated AI tool, group `("tool", "ai")`) |
-| **Backend handler** | [`server/nodes/tool/agent_builder/__init__.py`](../../../server/nodes/tool/agent_builder/__init__.py) — `AgentBuilderNode`, dispatched via `BaseNode.execute()` + one `@Operation` per canvas mutation (`inspect_canvas` / `add_tool` / `add_skill` / `add_subagent` / `create_workflow`) |
-| **Tests** | [`server/tests/nodes/test_ai_tools.py`](../../../server/tests/nodes/test_ai_tools.py) |
+| **Backend handler** | [`server/nodes/tool/agent_builder/__init__.py`](../../../server/nodes/tool/agent_builder/__init__.py) — `AgentBuilderNode`, dispatched via `BaseNode.execute()` + one `@Operation` per action (`inspect_canvas` / `add_tool` / `add_skill` / `add_subagent` / `create_workflow`) |
+| **Tests** | [`test_agent_builder.py`](../../../server/tests/nodes/test_agent_builder.py) (editor-built workflows), [`test_agent_builder_employee.py`](../../../server/tests/nodes/test_agent_builder_employee.py) (hired employees), [`test_agent_builder_atomic_ops.py`](../../../server/tests/nodes/test_agent_builder_atomic_ops.py) (ledger, retries), [`test_rebind_filters.py`](../../../server/tests/services/test_rebind_filters.py) |
| **Skill (if any)** | [`server/skills/assistant/agent-builder-skill/SKILL.md`](../../../server/skills/assistant/agent-builder-skill/SKILL.md) |
| **Dual-purpose tool** | tool-only — `ToolNode` exposed to the LLM as `agent_builder` (`tool_name` class attr) |
## Purpose
-Runtime canvas-mutation tool. Wired to an AI agent's `input-tools` handle, it
-lets the LLM inspect the live workflow canvas and grow its own toolset mid-run:
-spawn tool nodes, enable skills on a Master Skill, add delegate agents (team
-leads only), or create a fresh workflow. One node, one `Params` model with an
-`operation: Literal[...]` discriminator, five `@Operation` methods — the LLM
-sees ONE tool with a select-style `operation` field. Each mutation persists to
-the DB and pushes a `workflow_ops_apply` event so the React Flow canvas updates
-live.
+Lets the agent it is wired to inspect the workflow canvas and add to it while
+it runs: tools, skills, and (team leads only) teammates. One node, one
+`Params` model with an `operation: Literal[...]` discriminator, five
+`@Operation` methods; the LLM sees one tool with a select-style `operation`
+field.
+
+Every change is saved through
+[`services/workflow_storage/mutate.py`](../../../server/services/workflow_storage/mutate.py)
+`apply_graph_additions`, the server's one path for growing a saved workflow
+(Turn on Talk uses it too): one transaction, canonical ids, labels unique
+against the graph, the edge handles of
+[`services/graph_build.py`](../../../server/services/graph_build.py), real
+`NodeParameter` rows, and a `workflow_ops_apply` push with `persisted: true`
+so an open editor adopts the change without saving it.
+
+On a hired employee (the workflow has an employee row) it applies the rule
+Hire applies, [`services/employees/policy.py`](../../../server/services/employees/policy.py),
+which is how an employee extends itself from Talk.
## Inputs (handles)
| Handle | Connection type | Required | Purpose |
|--------|-----------------|----------|---------|
-| `input-main` | main | no | Passive node - connect `output-tool` to an AI Agent's `input-tools`. Operations walk `ctx.edges` (via `needs_canvas = True`) to resolve the calling agent and mutate the canvas. |
+| `input-main` | main | no | Passive node — connect `output-tool` to an AI agent's `input-tools`. `needs_canvas = True` hands the run's canvas to the tool call, which `add_tool` compares with the saved graph. |
## Parameters
-The `AgentBuilderParams` model fields ARE the LLM-provided tool args (no
-separate `toolName` / `toolDescription` node params — those live on the class
-as `tool_name` / `tool_description`). `model_config = ConfigDict(extra="ignore")`.
+The `AgentBuilderParams` model fields ARE the LLM-provided tool args.
+`model_config = ConfigDict(extra="ignore")`.
| Name | Type | Default | Required | displayOptions.show | Description |
|------|------|---------|----------|---------------------|-------------|
| `operation` | enum | `inspect_canvas` | no | - | One of `inspect_canvas`, `add_tool`, `add_skill`, `add_subagent`, `create_workflow` |
-| `node_type` | string | `""` | no | `operation == add_tool` | Tool node type to spawn (must be a registered `component_kind="tool"` or `usable_as_tool=True` node, minus the allowlist blocklist) |
-| `skill_folder` | string | `""` | no | `operation == add_skill` | Skill folder name under `server/skills/**` |
-| `agent_type` | string | `""` | no | `operation == add_subagent` | Agent node type to spawn as a teammate (caller must be a team lead) |
-| `workflow_name` | string | `""` | no | `operation == create_workflow` | Display name (create_workflow is currently disabled) |
+| `node_type` | string | `""` | no | `operation == add_tool` | Tool node type, from `available_tools` |
+| `skill_name` | string | `""` | no | `operation == add_skill` | Skill name (SKILL.md frontmatter `name`, or a library skill's name), from `available_skills` |
+| `agent_type` | string | `""` | no | `operation == add_subagent` | Agent node type to add as a teammate (caller must be a team lead) |
+| `workflow_name` | string | `""` | no | `operation == create_workflow` | Display name (create_workflow is disabled) |
| `workflow_description` | string | `""` | no | `operation == create_workflow` | Optional one-line description |
## Outputs (handles)
@@ -51,15 +60,20 @@ as `tool_name` / `tool_description`). `model_config = ConfigDict(extra="ignore")
```ts
{
operation?: string;
+ // One plain sentence on an employee refusal: the agent passes it on.
summary?: string;
- operations?: Array<Record<string, unknown>>; // workflow-ops batch applied
+ // add_tool / add_subagent: the ops this call saved (as announced), plus a
+ // saved tool the calling agent's run lacks. The agent loop binds every tool
+ // add_node here. Empty for add_skill.
+ operations?: Array<Record<string, unknown>>;
// inspect_canvas extras:
nodes?: Array<{ id; type; label; key_params }>;
edges?: Array<{ source; target; source_handle; target_handle }>;
- you?: { node_id: string; incoming: unknown[]; outgoing: unknown[] };
- available_tools?: Array<{ type; display_name; description }>;
+ you?: { node_id: string; incoming: unknown[]; outgoing: unknown[] } | null;
+ employee?: { asks_first: boolean; agents: string[] }; // hired employees only
+ available_tools?: Array<{ type; display_name; description; app?; connected?; read_only? }>;
available_agents?: Array<{ type; display_name; description }>;
- available_skills?: Array<{ folder; name; description }>;
+ available_skills?: Array<{ name; description }>;
// create_workflow extras:
workflow_id?: string;
}
@@ -69,64 +83,119 @@ as `tool_name` / `tool_description`). `model_config = ConfigDict(extra="ignore")
```mermaid
flowchart TD
- A[BaseNode.execute -> operation method] --> R{operation}
- R -- inspect_canvas --> I[reload canvas from DB<br/>resolve caller via input-tools edge<br/>build node/edge summaries + tool/agent/skill catalogues]
- R -- add_tool --> T{node_type allowed + not already wired?}
- T -- no --> Tn[Return summary, operations=empty]
- T -- yes --> Top[mint node id + add_node + add_edge ops]
- R -- add_skill --> S{masterSkill wired?}
- S -- yes --> Sy[toggle skill in skills_config via set_node_parameters]
- S -- no --> Sn[spawn masterSkill node + edge with skill enabled]
- R -- add_subagent --> G{caller is team lead + agent_type allowed + not dup?}
- G -- no --> Gn[Return summary, operations=empty]
- G -- yes --> Gop[mint node id + add_node + add_edge to input-teammates]
- R -- create_workflow --> C[disabled: return summary, no-op]
- Top --> B[_broadcast: persist to DB + broadcast_workflow_ops]
- Sy --> B
- Sn --> B
- Gop --> B
- B --> Z[Return AgentBuilderOutput summary + operations]
- I --> Z
- Tn --> Z
- Gn --> Z
- C --> Z
+ A[BaseNode.execute -> operation method] --> C[caller = ctx.raw invoking_agent_node_id or parent_node_id<br/>canvas = saved workflow.data<br/>employee = employee row for the workflow]
+ C --> R{operation}
+ R -- inspect_canvas --> I[canvas + key params from rows<br/>catalogues: registry for an editor-built workflow,<br/>policy-allowed tools + library and Discover skills for an employee]
+ R -- add_tool --> T{allowed?<br/>registry catalogue / policy.check_tool}
+ T -- no --> Tn[summary = reason, operations = empty]
+ T -- yes --> Tp[targets: caller, or the employee's worker + talk agent<br/>plan: new node, or edges from the existing one]
+ Tp --> S[apply_graph_additions<br/>ledger key = tool call id scoped to the run]
+ S --> Tb{saved tool missing from this run?}
+ Tb -- yes --> Tbo[prepend a bind-only add_node]
+ R -- add_skill --> K{found? library first, then offered built-ins<br/>employee: policy.check_skill, Discover only}
+ K -- no --> Kn[summary = reason]
+ K -- yes --> Kp[merge into each target's Skills node row<br/>wire the shared one to a target without one, else a new Skills node]
+ Kp --> S
+ R -- add_subagent --> G{editor-built, caller a team lead,<br/>type allowed, not a team lead}
+ G -- no --> Gn[summary = reason]
+ G -- yes --> Gp[agent + its Context + output-top -> input-teammates]
+ Gp --> S
+ R -- create_workflow --> W[disabled: summary only]
```
## Decision Logic
-- **Caller resolution**: walks edges for `source == self_id && targetHandle == input-tools`; falls back to self as caller (standalone Run).
-- **Live canvas reload**: `_load_live_canvas` re-reads `workflow.data` from the DB so successive ops in the same run see each other's mutations (the per-tool `ctx` snapshot is frozen at MachinaWorkflow start).
-- **Allowlist gating**: `_allowed_tool_types` / `_allowed_subagent_types` honor `node_allowlist.json` (`disabled_nodes` / `disabled_groups`); `_DENIED_TOOL_TYPES` (`agentBuilder`, `masterSkill`) are never spawnable (recursion guard).
-- **Idempotency**: `add_tool` / `add_subagent` / `add_skill` are no-ops (empty `operations`) when the target is already wired/enabled, surfacing the existing node id in the summary.
-- **add_subagent gate**: only team leads (`orchestrator_agent`, `ai_employee`) may spawn delegates; cannot spawn another team lead.
-- **create_workflow disabled**: `_CREATE_WORKFLOW_ENABLED = False` short-circuits with a "temporarily disabled" summary; the implementation body is intact for one-line re-enable.
-- **Summary suffix**: depends on `ctx.raw["auto_rebind_tools"]` (UserSettings) — "Available immediately" when auto-rebind is on, else "Available on your next turn" (the native agent loop compiles its tool list at turn start, so a mid-run mutation is callable next turn unless auto-rebind refreshes that list in place).
+- **Caller**: `ctx.raw["invoking_agent_node_id"]` (Temporal) or
+ `ctx.raw["parent_node_id"]` (every path), never guessed from edges: one
+ Agent Builder node can serve several agents. In an editor-built workflow
+ the caller is the target, so with none nothing is added ("Only an agent can
+ ask me to add things."); a hired employee's targets are its worker and talk
+ agent from `node_roles`, and the caller only when neither is in the saved
+ graph.
+- **Saved graph**: operations read `workflow.data` fresh, so calls in one run
+ see each other. A workflow that is not saved, or whose caller is not in the
+ saved graph yet, gets "Save the workflow first".
+- **Ledger**: the mutation id is `agent-builder:<execution_id>:<tool_call_id>`
+ (the request's hash when the runtime passes no call id). Every mutating call
+ goes through `apply_graph_additions`, even with nothing to add, so a retried
+ call replays the first attempt's result (and announces it again) instead of
+ adding twice.
+- **Editor-built workflow**: tools from `_allowed_tool_types()` (ToolNodes and
+ `usable_as_tool` plugins, no chat models, minus `agentBuilder` /
+ `masterSkill` / `taskManager` and the allowlist's `disabled_nodes` /
+ `disabled_groups`); skills from the SkillLoader registry outside
+ `disabled_skill_folders`, plus the owner's library. The target is the
+ caller.
+- **Hired employee**: targets are the worker and the talk agent
+ (`node_roles["agent"]`, `["talk_agent"]`). `check_tool` decides tools
+ (registry app tools and the tools every hire gets; nothing that sends or
+ spends while asking first, the browser read-only then; hire allowlist;
+ connected apps); the Clock gets the owner's `profile_timezone`.
+ `check_skill` refuses `skill` and `*-personality`; skills come from the
+ library (all of it, on or off for new hires) and the Discover folder
+ (`server/skills/employee/`), text copied in. `add_subagent` is refused.
+- **One tool of a type per agent**: a target that has one keeps it; the rest
+ get the caller's (else any target's) by a new edge; a new node only when no
+ target has one.
+- **Bind-only**: a deployed run starts from the generation's frozen snapshot.
+ A tool saved earlier (an earlier message) but missing from this run's canvas
+ comes back as an `add_node` op with the saved id and row, and nothing is
+ saved or announced, so the agent can call it now instead of hearing
+ "already wired".
+- **Skills**: each target's Skills node gets the entry; a target without one
+ is wired to the shared node (never a second: two on one agent collide on
+ the Skill tool's own entry), else a new Skills node (`Skills` for an
+ employee, `Master Skill` otherwise). An enabled skill changes nothing. A
+ built-in keeps no text in an editor-built workflow (edits to its SKILL.md
+ apply); a library skill always carries its text (the runtime's fallback
+ reads files only).
+- **When it works**: a tool is bound for the rest of the calling agent's run
+ (`auto_rebind_tools`, on by default; summary "Available immediately" / "You
+ can use it now", else "Available on your next turn"). A skill merged into an
+ existing Skills node applies from the next run; a new node or edge after a
+ restart (Apply, on an employee's page).
+- **add_subagent**: team leads only (`orchestrator_agent`, `ai_employee`),
+ never another team lead; one teammate per type except repeatable `aiAgent`.
+ The new agent gets its own Context (`context_of`) and an `output-top` →
+ `input-teammates` edge.
+- **create_workflow**: `_CREATE_WORKFLOW_ENABLED = False`.
## Side Effects
-- **Database writes**: `_persist_canvas_mutation` applies `add_node` / `add_edge` / `set_node_parameters` ops to `workflow.data` via `database.get_workflow` + `database.save_workflow` (adopts the BE-minted `minted_id` so FE/BE node ids align). `create_workflow` (when enabled) persists a fresh workflow row.
-- **Broadcasts**: `broadcast_workflow_ops` (in `_events.py`) emits a flat `workflow_ops_apply` WS frame consumed by the frontend `useWorkflowOpsListener` hook. NOT a `dispatch.emit` event (no Temporal/event_waiter consumer for canvas mutations). A `WorkflowEvent` envelope (`com.opencompany.workflow.ops.applied`) is constructed for parity but not put on the wire today.
-- **External API calls**: none.
-- **File I/O**: reads `server/skills/**` to validate skill folders (`_skill_folder_exists`) and catalogue skills.
-- **Subprocess**: none.
+- **Database writes**: `apply_graph_additions` — `workflow.data` gains nodes
+ and edges, new nodes get fresh `NodeParameter` rows, Skills rows are merged,
+ and a `RuntimeMutation` ledger row is written, all in one transaction.
+- **Broadcasts**: `workflow_ops_apply` with `persisted: true`
+ (`services.workflow_ops.broadcast_workflow_ops`), then the graph-changed
+ listeners (`notify_graph_changed`: Home's employee summary, with its
+ pending-changes notice). A bind-only result announces nothing.
+- **External API calls**: none. Connection state is read for employees
+ (`services.employees.connections`).
+- **File I/O**: reads SKILL.md files through the SkillLoader.
## External Dependencies
-- **Credentials**: none.
-- **Services**: `database` (via `services.plugin.deps.get_database`), `NodeAllowlistService`, `SkillLoader`, `services.node_registry.registered_node_classes`, `services.workflow_ops`, `services.workflow_naming`.
+- **Services**: `database`, `services.workflow_storage.mutate`,
+ `services.graph_build`, `services.employees` (`store`, `policy`, `apps`,
+ `connections`), `NodeAllowlistService`, `SkillLoader`,
+ `services.node_registry`.
- **Python packages**: stdlib only.
-- **Environment variables**: none.
## Edge cases & known limits
-- `create_workflow` is disabled behind `_CREATE_WORKFLOW_ENABLED`; the operation returns a guidance summary and performs no mutation.
-- Mid-run mutations are not callable in the SAME turn unless the user's "Auto-Rebind Tools After Canvas Changes" toggle is on (default) — otherwise the LLM must wait for its next turn.
-- `inspect_canvas` is read-only and emits no `operations`.
-- Persist failures are logged at WARN (`exc_info=True`) and do not abort the broadcast — the canvas may diverge from the DB if persistence fails mid-mutation.
-- The `workflow_ops_apply` wire format is flat (`{workflow_id, caller_node_id, operations}`) for FE back-compat, not the CloudEvents envelope.
+- A saved change reaches the current run only through the rebind (tools),
+ and other runs of a deployed workflow only after a restart; skills merged
+ into an existing Skills node apply from the next run.
+- On the Temporal path, calling `add_tool` again in the same run for a tool
+ added earlier in that run returns it to bind again, and `AgentWorkflow`
+ reports the duplicate tool name (the tool stays callable). The in-process
+ loop skips a node it already bound.
+- Roles for tools an employee adds are not recorded in `node_roles`.
+- A Dev canvas Run with unsaved edits cannot be changed ("Save the workflow
+ first").
## Related
- **Sibling tools**: [`calculatorTool`](./calculatorTool.md), [`currentTimeTool`](./currentTimeTool.md), [`duckduckgoSearch`](./duckduckgoSearch.md), [`taskManager`](./taskManager.md), [`writeTodos`](./writeTodos.md)
- **Skill using this tool**: [`agent-builder-skill/SKILL.md`](../../../server/skills/assistant/agent-builder-skill/SKILL.md)
-- **Architecture docs**: [Workflow Ops Protocol](../../workflow_ops_protocol.md), [Agent Architecture](../../agent_architecture.md), [Node Creation Guide](../../node_creation.md)
+- **Architecture docs**: [Workflow Ops Protocol](../../workflow_ops_protocol.md), [Agent Architecture](../../agent_architecture.md), [Normal Mode](../../normal_mode.md), [Node Creation Guide](../../node_creation.md)
diff --git a/docs-internal/node-logic-flows/chat_utility/chatReply.md b/docs-internal/node-logic-flows/chat_utility/chatReply.md
new file mode 100644
index 00000000..f2949637
--- /dev/null
+++ b/docs-internal/node-logic-flows/chat_utility/chatReply.md
@@ -0,0 +1,136 @@
+# Reply in Chat (`chatReply`)
+
+| Field | Value |
+|------|-------|
+| **Category** | chat_utility (group `("chat",)`) |
+| **Backend handler** | [`server/nodes/chat/chat_reply/__init__.py`](../../../server/nodes/chat/chat_reply/__init__.py) — `ChatReplyNode`; dispatch via `BaseNode.execute()` + `@Operation("reply")` |
+| **Tests** | [`server/tests/nodes/test_chat_reply.py`](../../../server/tests/nodes/test_chat_reply.py) |
+| **Skill (if any)** | - |
+| **Dual-purpose tool** | no |
+
+## Purpose
+
+Posts an answer into the chat thread of the workflow it runs in, as the
+assistant. A workflow's thread is the chat session whose id is the workflow
+id: the owner reads it in Talk on the employee's Home page and in the
+editor's chat pane. It is the last step of a talk line (a `chatTrigger`
+feeds an agent, which answers through this node), and, labelled "Post to
+Talk", it puts a schedule worker's reports in the thread. The Hire builder,
+Turn on Talk and the shipped example workflows wire it after an agent, with
+`message` set to `{{<agent label key>.response}}` and the edge condition
+`result.response neq NO_REPLY`. See [Normal mode → Talk](../../normal_mode.md#talk).
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | The agent whose answer it posts. The answer is read through the `message` template, not through connected outputs: the node is not in `NodeExecutor._NEEDS_CONNECTED_OUTPUTS`. |
+
+`hide_output_handle = True`, so it renders as a sink with only `input-main`,
+like `console`. It does not carry console's `isConsoleSink` hint.
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `message` | string (3 rows, placeholder `{{agent.response}}`) | `""` | no | - | The text to post, usually a template such as `{{aiagent.response}}`. A whole-value template keeps the upstream value's type, so a dict or list arrives as-is and is posted as JSON text; `None` becomes empty. |
+
+`model_config = ConfigDict(extra="ignore")`.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| (no output handle) | object | `hide_output_handle = True`; the op still returns the payload below |
+
+### Output payload (TypeScript shape)
+
+```ts
+// ChatReplyOutput (model_config extra="allow")
+{
+ posted: boolean; // false when there was nothing to post
+ message?: string; // the trimmed text, when posted
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Receive params: message coerced to text] --> B[text = message.strip]
+ B --> C{empty, or exactly NO_REPLY?}
+ C -- yes --> D[Return posted=false: nothing written or broadcast]
+ C -- no --> E{ctx.workflow_id set?}
+ E -- no --> F[Raise NodeUserError: save the workflow first]
+ E -- yes --> G[services.chat_thread.record_chat_message<br/>session = workflow id, role = assistant]
+ G --> H{row saved?}
+ H -- no --> I[Raise RuntimeError: the reply could not be saved]
+ H -- yes --> J[broadcast chat.updated]
+ J --> K[Return posted=true + message]
+```
+
+## Decision Logic
+
+- **Coercion** (`field_validator(mode="before")` on `message`): `None` -> `""`,
+ a dict or list -> `json.dumps(..., ensure_ascii=False, default=str)`,
+ anything else -> `str(...)`.
+- **Nothing to say**: after trimming, an empty text or exactly `NO_REPLY`
+ (`services.approvals.contract.NO_REPLY`, what an agent answers when it has
+ nothing to send) posts nothing and succeeds with `posted: false`. The edges
+ the builders wire into the node carry the same `result.response neq NO_REPLY`
+ condition, so normally the node does not run then at all.
+- **Generation**: `record_chat_message` stamps the row with the latest
+ control's `root_execution_id` (`chat_thread.chat_execution_id`; none when
+ nothing was started since the last Reset). The editor's chat pane reads the
+ latest generation only, so a row without the stamp would not show there
+ while one is live; Home's Talk reads every generation and draws a restart
+ divider where the stamp changes.
+- **Error paths**: no `ctx.workflow_id` raises
+ `NodeUserError("Reply in Chat posts to the workflow's chat: save the workflow first.")`
+ (one WARN line, no traceback); a row the database did not save
+ (`record_chat_message` returns false) raises
+ `RuntimeError("The reply could not be saved to the chat")`, and nothing is
+ announced.
+
+## Side Effects
+
+- **Database writes**: one `chat_messages` row: `session_id` = the workflow id,
+ `role` = `assistant`, `message` = the trimmed text, `execution_id` = the
+ live generation.
+- **Broadcasts**: `chat.updated` (CloudEvents `com.opencompany.chat.updated`,
+ data `{workflow_id, session_id, role: "assistant"}`), sent directly through
+ the status broadcaster, not `services.events.dispatch.emit`. Home's thread
+ query and the editor's chat pane refetch on it.
+- **External API calls**: none.
+- **File I/O**: none.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: none.
+- **Services**: `services.chat_thread` (`record_chat_message`), the database
+ (`services.plugin.deps.get_database`), `StatusBroadcaster`.
+- **Python packages**: stdlib only (`json`).
+- **Environment variables**: none.
+
+## Edge cases & known limits
+
+- A thread is per workflow, not per user.
+- An agent that serves several triggers posts every answer through its Reply
+ in Chat node, whichever trigger started the run: the shipped AI Employee and
+ Claude Assistant examples (fed by Chat and Telegram) put their Telegram
+ answers in the thread too.
+- Not an AI tool (`usable_as_tool` is off): an agent cannot call it; an answer
+ reaches it only through the main edge.
+- Allowed for Hire by `node_allowlist.json` `enabled_nodes`; the test file
+ checks that, together with `agentBuilder`.
+
+## Related
+
+- **Other nodes**: [`chatTrigger`](../workflow_triggers/chatTrigger.md) (the
+ owner's messages in), [`console`](./console.md) (the other sink Hire adds,
+ "Activity log"), [`chatSend`](./chatSend.md) (an external chat backend,
+ unrelated to this thread).
+- **Architecture docs**: [Normal mode → Talk](../../normal_mode.md#talk),
+ [Status Broadcaster](../../status_broadcaster.md),
+ [Event Framework → UI-only lifecycle events](../../event_framework.md#ui-only-lifecycle-events-broadcast-directly-never-through-emit).
diff --git a/docs-internal/node-logic-flows/workflow_triggers/chatTrigger.md b/docs-internal/node-logic-flows/workflow_triggers/chatTrigger.md
index 9792500a..4358ac14 100644
--- a/docs-internal/node-logic-flows/workflow_triggers/chatTrigger.md
+++ b/docs-internal/node-logic-flows/workflow_triggers/chatTrigger.md
@@ -10,7 +10,8 @@
## Purpose
-Fires when the user sends a message from the Console Panel chat tab. The
+Fires when the user sends a chat message: from the editor's chat pane
+(Console Panel chat tab), or from Talk on an employee's Home page. The
producer [`server/nodes/trigger/chat_trigger/_events.py`](../../../server/nodes/trigger/chat_trigger/_events.py)
emits a CloudEvents `WorkflowEvent` (`type: com.opencompany.chat.message.received`)
via `dispatch.emit`. `chatTrigger` is canary-registered
@@ -21,6 +22,16 @@ node whose `session_id` matches (or is `'default'`) receives the event and emits
it as output. This is the primary way a user feeds an interactive prompt into an
`aiAgent` or `chatAgent`.
+A workflow's chat session id is the workflow id. Home's Talk and the editor's
+chat pane send with `session_id` = that id (`'default'` only when the editor
+has no workflow open), and `send_chat_message` then scopes the event to the
+workflow (`EventWorkflowId`), so only that workflow's listeners receive it.
+The trigger of a talk line (a chat hire's "Chat" trigger, or the "Talk"
+trigger that Hire and Turn on Talk add beside another worker) has
+`session_id` set to the workflow id, and its agent answers through
+[`chatReply`](../chat_utility/chatReply.md) into the same thread. See
+[Normal mode → Talk](../../normal_mode.md#talk).
+
## Inputs (handles)
| Handle | Connection type | Required | Purpose |
@@ -31,7 +42,7 @@ it as output. This is the primary way a user feeds an interactive prompt into an
| Name | Type | Default | Required | displayOptions.show | Description |
|------|------|---------|----------|---------------------|-------------|
-| `session_id` | string | `default` | no | - | Matches the `session_id` on the incoming chat event. If set to `default`, the filter accepts every event. Otherwise it only accepts events with the same `session_id`. |
+| `session_id` | string | `default` | no | - | Matches the `session_id` on the incoming chat event. If set to `default`, the filter accepts every event. Otherwise it only accepts events with the same `session_id`. Talk lines built by Hire and Turn on Talk use the workflow id. |
| `placeholder` | string | `Type a message...` | no | - | Frontend display only - not used by the handler. |
## Outputs (handles)
@@ -42,16 +53,13 @@ it as output. This is the primary way a user feeds an interactive prompt into an
### Output payload
-The exact shape depends on how the dispatcher in
-`routers/websocket.py::send_chat_message` builds the event, but the
-documented fields surfaced to downstream nodes are:
+`routers/websocket.py::handle_send_chat_message` builds the event as:
```ts
{
message: string;
- timestamp: string; // ISO 8601
+ timestamp: string; // ISO 8601; the client's, else the server's time (UTC)
session_id: string;
- node_id?: string; // Optional - set when the client targets a specific chatTrigger
}
```
@@ -61,7 +69,10 @@ Wrapped in the standard envelope.
```mermaid
flowchart TD
- P[chat tab sends message] --> Q[_events.py dispatch.emit<br/>WorkflowEvent com.opencompany.chat.message.received]
+ P[chat pane or Home Talk sends a message] --> V{workflow session with no<br/>controller to read it?}
+ V -- yes --> X[not_running: nothing saved or sent]
+ V -- no --> W[chat_thread.record_chat_message]
+ W --> Q[_events.py dispatch.emit<br/>WorkflowEvent com.opencompany.chat.message.received]
Q --> R[TriggerListenerWorkflow receives via Temporal Signal]
R --> S[ChatTriggerNode.build_filter:<br/>if session_id != 'default' require exact match]
S -- match --> T[spawn child MachinaWorkflow<br/>trigger pre-executed with event payload]
@@ -83,8 +94,10 @@ flowchart TD
## Side Effects
-- **Database writes**: none in the trigger plugin itself. (The chat message
- is separately persisted by `send_chat_message` via `database.add_chat_message`.)
+- **Database writes**: none in the trigger plugin itself. (`send_chat_message`
+ keeps the message in the session's thread first, through
+ `services/chat_thread.record_chat_message`, which stamps the live generation
+ and broadcasts `chat.updated`.)
- **Broadcasts**: the producer emits a CloudEvents `WorkflowEvent` via
`dispatch.emit` (Temporal Signal fan-out + in-process WS broadcast). The
`TriggerListenerWorkflow` emits firing-pulse status via
@@ -105,17 +118,25 @@ flowchart TD
- `session_id='default'` behaves as a wildcard; setting a unique session ID
per trigger is the only way to scope messages to a specific node.
- When multiple `chatTrigger` nodes exist with the same session ID, all of
- them fire for a matching message.
+ them fire for a matching message, so one message starts one run per
+ trigger. Hire and Turn on Talk never add a second trigger on a workflow's
+ own session: a chat hire's "Chat" trigger is already its talk line.
- The handler has no timeout; it waits forever until an event arrives or
the run is cancelled.
-- The chat message's persistence to the DB happens in the WebSocket handler
- BEFORE the event is dispatched, so even if no `chatTrigger` is waiting
- the message is still stored in `chat_messages`.
+- For a workflow's session, `send_chat_message` first reads the latest
+ control. While it runs, starts or resumes, the message goes now (response
+ `delivery: "now"`); while it is paused or pausing, the controller keeps it
+ and starts a run on Resume (`delivery: "queued"`). In any other state the
+ handler answers `not_running` and neither saves nor dispatches the message.
+ Session `'default'` is saved and dispatched as before, so a message there is
+ stored even when no `chatTrigger` is waiting.
## Related
- **Skills using this as a tool**: none.
- **Sibling triggers**: [`webhookTrigger`](./webhookTrigger.md),
[`taskTrigger`](./taskTrigger.md).
+- **Answers into the thread**: [`chatReply`](../chat_utility/chatReply.md).
- **Architecture docs**: [Event Waiter System](../../event_waiter_system.md),
- [Status Broadcaster](../../status_broadcaster.md)
+ [Status Broadcaster](../../status_broadcaster.md),
+ [Normal mode → Talk](../../normal_mode.md#talk)
diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.md
index 766ad6cc..4a61bdc6 100644
--- a/docs-internal/node_allowlist.md
+++ b/docs-internal/node_allowlist.md
@@ -90,15 +90,19 @@ Builder catalogue; historical explicit nodes remain compatible.
## agentBuilder integration
-`agentBuilder` honors the same allowlist when surfacing its spawnable catalogue (`inspect_canvas.available_tools` / `available_agents` / `available_skills`) and rejecting `add_tool` / `add_subagent` / `add_skill` calls:
+`agentBuilder` honors the same allowlist when surfacing its catalogue (`inspect_canvas.available_tools` / `available_agents` / `available_skills`) and refusing `add_tool` / `add_subagent` / `add_skill` calls. Which lists apply depends on the workflow.
+
+In a workflow built in the editor:
| Allowlist field | agentBuilder filter |
|---|---|
-| `disabled_nodes` | Excluded from `_allowed_tool_types()` + `_allowed_subagent_types()` — the LLM can't spawn or list the type. |
+| `disabled_nodes` | Excluded from `_allowed_tool_types()` + `_allowed_subagent_types()` — the LLM can't add or list the type. |
| `disabled_groups` | Excluded from both sets via plugin `group` tuple intersection (any matching entry hides every plugin in the group). |
-| `disabled_skill_folders` | Excluded from `_catalogue_skills()` — the LLM doesn't see folders the operator marked. Match is on the SkillMetadata path ancestor (e.g. `disabled_skill_folders: ["android_agent"]` blocks every skill under `server/skills/android_agent/`). |
+| `disabled_skill_folders` | Built-in skills under a marked folder are neither listed nor added. Match is on the SkillMetadata path ancestor (e.g. `disabled_skill_folders: ["android_agent"]` blocks every skill under `server/skills/android_agent/`). |
+
+On a hired employee (the workflow has an employee row), every tool goes through `services/employees/policy.py`, the rule Hire applies: `enabled_nodes` counts too (`is_hire_allowed`), besides the blocklists, the "ask me first" rule, and the app's connection. So a hire can only ever be given what Hire itself could build into one.
-Read via `services.node_allowlist.get_node_allowlist_service().get_config()` — same singleton the UI hook hits. Adding a node to `disabled_nodes` once propagates to BOTH the UI palette AND the LLM's spawnable surface.
+Read via `services.node_allowlist.get_node_allowlist_service().get_config()` — same singleton the UI hook hits. Adding a node to `disabled_nodes` once propagates to BOTH the UI palette AND the LLM's catalogue.
## Filter call sites
@@ -106,6 +110,7 @@ Read via `services.node_allowlist.get_node_allowlist_service().get_config()` —
|---|---|
| `client/src/components/ui/ComponentPalette.tsx` | `if (isBlocked(name, groups)) return false; if (!showAll && !isAllowed(name)) return false;` where `showAll = featureFlags.normalMode \|\| proMode` |
| `server/services/employees/builder.py` | every node Hire builds must pass `is_hire_allowed(node_type)` |
+| `server/nodes/tool/agent_builder/__init__.py` | the blocklists in an editor-built workflow; `policy.check_tool` (`is_hire_allowed` and the rest of Hire's rule) on a hired employee |
| `client/src/components/credentials/CredentialsModal.tsx` | `providers.filter(p => !isCredentialCategoryDisabled(p.category))` + same for `categories` |
| `client/src/components/parameterPanel/MasterSkillEditor.tsx` | `(foldersQuery.data ?? []).filter(f => !isSkillFolderDisabled(f.name))` |
diff --git a/docs-internal/normal_mode.md b/docs-internal/normal_mode.md
index 687a75b6..42284bdf 100644
--- a/docs-internal/normal_mode.md
+++ b/docs-internal/normal_mode.md
@@ -4,8 +4,9 @@ Normal mode is the landing screen for owners who are not technical. They
describe a job in plain words, an LLM on the server drafts a setup screen for
a new AI employee, they adjust it and press **Hire**, and the server builds,
saves and starts a workflow that does the job. Each employee appears in a
-sidebar with a live status card. The workflow editor is **Dev mode**, one
-switch away.
+sidebar with a live status card, and the owner talks to them on their page
+(Talk), where they can also be asked to take on new tools and skills. The
+workflow editor is **Dev mode**, one switch away.
**One employee is one workflow.** The workflow id is the employee id and the
workflow's name is the employee's name. Workflows created in the editor show
@@ -18,6 +19,8 @@ up in Home too, with details derived from their graph.
| Setup-screen pipeline (parse, normalise, render) | [client/src/features/home/genui/](../client/src/features/home/genui/) |
| Employees service (list, setup, hire, start, run records) | [server/services/employees/](../server/services/employees/) |
| Approvals (the "ask me first" step) | [server/services/approvals/](../server/services/approvals/), node [approvalGate](./node-logic-flows/workflow_triggers/approvalGate.md) |
+| Talk (the chat thread and the talk line) | [server/services/chat_thread.py](../server/services/chat_thread.py), [services/employees/talk.py](../server/services/employees/talk.py), node [chatReply](./node-logic-flows/chat_utility/chatReply.md) |
+| Growing a saved employee (Turn on Talk, the Agent Builder, Apply) | [server/services/graph_build.py](../server/services/graph_build.py), [services/employees/policy.py](../server/services/employees/policy.py), [services/workflow_storage/mutate.py](../server/services/workflow_storage/mutate.py), [services/deployment/restart.py](../server/services/deployment/restart.py), node [agentBuilder](./node-logic-flows/ai_tools/agentBuilder.md) |
| Built-in skills offered to new hires (Settings > Skills > Discover) | [server/skills/employee/](../server/skills/employee/) |
The design reference is the `design_handoff_opencompany_home/` bundle (kept
@@ -61,18 +64,19 @@ is the reference.
| Folder | Contents |
|---|---|
-| `HomeShell.tsx` | Sidebar, header, the current view (hire or one employee), the Workspace dock, Settings, the connect dialog, the orb's stage |
+| `HomeShell.tsx` | Sidebar, header, the current view (hire or one employee), the Workspace dock, Settings, the connect dialog, the guided Connect an AI model dialog, the orb's stage, and under an employee's page a line saying whether they ask first |
| `sidebar/`, `header/` | The team list, New employee, the profile row; the view title, the Workspace pill, mode toggle and theme button |
-| `hire/` | The hero, the composer, and the starter bundles (`starters.json`), which the template chips and Settings > Plugins both read |
-| `genui/` | The setup draft under the composer (below) |
-| `employee/` | One employee's card: status, the current task, apps, "done today", Start / Pause / Resume, Watch live, the drafts waiting for the owner |
+| `hire/` | The hero, the composer, the template chips, the hire notice (`HireNotice.tsx`), and the starter bundles (`starters.json`), which the chips and Settings > Plugins both read |
+| `genui/` | The setup draft under the composer, and the hire itself, from a setup or a starter (below) |
+| `employee/` | One employee's page: the card (status, the current task, apps, "done today", Start / Pause / Resume, Watch live, the drafts waiting for the owner, and a More menu with Open in Dev mode), then Talk (below). The card and the message box share one main action (`useEmployeeControl`, `PrimaryActionButton`) |
+| `connectAI/` | The guided Connect an AI model dialog (below) |
| `workspace/` | The Workspace dock (below), its header pill, and its Canvas tab, which loads in its own chunk |
| `settings/` | The Settings pages (Profile, Billing, Skills, Connectors, Plugins), the shared catalog page the last three build on, and `ConnectDialog` (the editor's credential panel for one provider, in its compact variant) |
| `approvals/` | The drafts query, the decide mutation (optimistic), the approval broadcast listener |
-| `data/` | zod-parsed queries for employees, connectors and the profile; `presentation.ts` maps server state to pills and actions without deriving new rules |
+| `data/` | zod-parsed queries for employees, connectors and the profile; `talk.ts`, the thread and its mutations; `presentation.ts` maps server state to pills, actions and the message box's mode without deriving new rules |
| `orb/` | The 3D orb (below) |
-| `ui/` | Small shared pieces (avatar, status dot and pill, app mark) and the pill toast |
-| `state/homeStore.ts` | UI state only: the view, the sidebar, Settings, the Workspace dock, one-shot glow and pulse signals |
+| `ui/` | Small shared pieces (avatar, status dot and pill, app mark), the pill toast, and `useAutoGrow` (the composer's and the message box's growing text area) |
+| `state/homeStore.ts` | UI state only: the view, the sidebar, Settings, the Connect an AI model dialog, the last hire's notice, the Workspace dock, one-shot glow and pulse signals |
Status comes from the server: an employee summary is `working`, `ready`,
`paused` or `attention` (an automatic pause, see below), and a pending draft
@@ -167,17 +171,35 @@ the team.
call, and `cancel_employee_setup` cancels explicitly. The payload field is
`draft_token` because `request_id` is the WebSocket correlation id.
- **Privacy**: neither the job nor the reply is ever logged.
-- **Errors**: `no_ai_provider` (the composer opens Connectors on AI),
- `timeout`, `provider_error`, `unparseable`, `cancelled`, `busy`,
- `invalid_request`.
+- **Apps**: the response's `apps` maps each app the reply mentions to its
+ AppRef plus `can_trigger` (the app can start the work), so the screen can
+ offer "When something new arrives in Gmail" without its own copy of the app
+ registry.
+- **No preferred trigger**: every employee can be talked to on Home, so in
+ the prompt one that works when the owner messages them is as good as any.
+ The Hire button's `trigger` carries a schedule's time as one of the
+ catalogue's `trigger.times`.
+- **Errors**: `no_ai_provider` (the guided Connect an AI model dialog opens,
+ below; the owner's words stay in the draft, which is sent again by itself
+ once a model is connected), `timeout`, `provider_error`, `unparseable`,
+ `cancelled`, `busy`, `invalid_request`.
+
+A template chip under the composer fills the box with its starter's job for
+the owner to read, change and send; it never sends by itself. While the box
+still holds that job as written, the chip shows as picked with the starter's
+summary and **Hire now** (see [One-click starters](#one-click-starters)).
+While the model writes, the draft panel shows one honest line, "Writing their
+setup…", with the time so far and Cancel, and after `SLOW_AFTER_SECONDS` a
+note that some models take a few minutes. The screen's layout JSON is shown
+in development builds only.
The reply is a flat JSON UI spec. The client parses, repairs and normalises it
and renders it from a fixed component catalogue
([genui/](../client/src/features/home/genui/): `catalog.ts`, `parse.ts`,
`normalize.ts`, `expressions.ts`, `render.tsx`). The normaliser keeps the
root a vertical stack, enforces a tree, guarantees one Hire button, one
-change button and the "Ask me before sending anything" toggle (on by default),
-and caps sizes. The server mirrors the catalogue in
+change button, the "Ask me before sending anything" toggle (on by default)
+and one `Schedule` (below), and caps sizes. The server mirrors the catalogue in
[config/genui_catalog.json](../server/config/genui_catalog.json);
`server/tests/test_genui_catalog_sync.py` keeps the two in step, and a shared
corpus of bad model replies (`genui/__fixtures__/replies.json`) is parsed the
@@ -185,6 +207,20 @@ same way on both sides. Only what `genui/index.ts` exports (`HireDraftPanel`,
`useHireComposer`, `DraftMessagePreview`) leaves the folder: ESLint refuses
imports of its internal modules.
+**When they work.** Every screen shows one `Schedule` after the routine. The
+normaliser inserts it (the catalogue marks it `inserted`, so the model is
+never offered it) and binds it to `/trigger` (`state_paths.trigger`). It starts
+as the Hire button's `trigger`, else a new message in the app the routine's
+first "When" step names, else the owner messaging them, snapped to what the
+server builds: a known kind, a frequency, a time from `trigger.times` (the
+builder's `SCHEDULE_TIMES`; `test_genui_catalog_sync.py` holds them equal), and
+a weekday or day of the month. It reads as one sentence in the card's words
+("Every weekday at 08:00"). Edit offers the owner messaging them, a schedule,
+or a new message in any app whose `can_trigger` is true; a change rewrites the
+routine's "When" step, and the hire payload reads `/trigger` before the
+button's params. `render.tsx` labels the routine "Their routine" and its steps
+in plain words (When, They, Using, Then).
+
### 2. Hire
`hire_employee` ([hire.py](../server/services/employees/hire.py)) takes a
@@ -193,7 +229,10 @@ the client's `HIRE_PAYLOAD_KEYS` must match, locked by
`test_hire_payload_contract.py`) and:
1. checks size and shape, then the idempotency key: the same key with the same
- payload returns the employee already hired, a different payload `conflict`;
+ payload returns the employee already hired, a different payload `conflict`,
+ and one whose first attempt is still building `busy`. A row a failed attempt
+ left behind is resumed, and so is one still marked building after
+ `BUILDING_STALE_AFTER` (the server stopped mid-way);
2. resolves the apps it names through the app registry
([config/employee_apps.json](../server/config/employee_apps.json),
[apps.py](../server/services/employees/apps.py)): each app's provider,
@@ -205,8 +244,19 @@ the client's `HIRE_PAYLOAD_KEYS` must match, locked by
chat), one `aiAgent` whose system message comes from
[prompt.py](../server/services/employees/prompt.py), always-on tools (web
search, todos, clock, a Canvas, plus memory when the owner allows it) and
- the apps' tools, the owner's skill library, delivery, and an "Activity
- log" console node. The instructions ask the employee to put finished
+ the apps' tools, the owner's skill library, delivery, an "Activity
+ log" console node, and Talk ([the talk line](#the-talk-line)). Which tools
+ and skills a hire may have is
+ [policy.py](../server/services/employees/policy.py)'s rule, the same one
+ the Agent Builder applies later. A schedule is recorded as it will run, in
+ the owner's time (`cronScheduler` runs only at `SCHEDULE_TIMES`, in a short
+ list of zones), with a warning when that is not what the owner asked for.
+ Ids, labels and edges come from
+ [services/graph_build.py](../server/services/graph_build.py), shared with
+ every server-side graph writer, and
+ `tests/fixtures/employee_builder_snapshot.json` pins the output
+ (`UPDATE_BUILDER_SNAPSHOT=1` rewrites it). The instructions ask the
+ employee to put finished
work the owner will want to look at later on its Canvas, and to leave
routine replies off it. The library is every skill that is on in Settings > Skills. It goes
on one Skills node (`masterSkill`) with each skill's text copied in, so a
@@ -225,17 +275,34 @@ the client's `HIRE_PAYLOAD_KEYS` must match, locked by
4. validates it with `validate_workflow` and saves it with
[persist_new_workflow](../server/services/workflow_storage/persist.py)
(shared with workflow import);
-5. answers `{employee, started, missing_apps, needs_ai, unsupported_apps, warnings, idempotent}`
+5. records on the row the apps the graph actually uses (`built.app_ids`), so
+ an app the hire named but left out (a tool that sends while they ask
+ first) never shows as one to connect; summaries read apps off the graph
+ the same way;
+6. answers `{employee, started, missing_apps, needs_ai, unsupported_apps, warnings, idempotent}`
and, when every app is connected and an AI model exists, starts the
- employee in the background.
+ employee in the background. Errors: `invalid_request`, `too_large`,
+ `conflict`, `busy`, `not_allowed`, `build_failed`, `save_failed`.
+
+On the client ([genui/useHire.ts](../client/src/features/home/genui/useHire.ts))
+every successful hire lands on the new employee's page, with a glow in the
+sidebar and a toast. The response's `warnings` show there once as the hire
+notice ("A few notes on {Name}'s setup", `hire/HireNotice.tsx`), until the
+owner dismisses it or opens another view; `needs_ai` opens Connect an AI
+model; every error code has plain words (`busy`: they are still being set
+up).
### 3. Start, pause, resume
`start_employee {workflow_id, expected_revision, idempotency_key}`
([start.py](../server/services/employees/start.py)) refuses with
-`missing_apps` or `needs_ai`, moves the agent onto a usable model, and calls
-`start_saved_workflow`, the same start path the editor uses. Pause and Resume
-are the editor's `pause_workflow` / `resume_workflow`.
+`missing_apps` or `needs_ai`, moves every agent the employee has (the worker
+and the agent it talks to the owner through, `node_roles` `agent` and
+`talk_agent`) onto a usable model, and calls `start_saved_workflow`, the same
+start path the editor uses. One that stopped after a problem is reset first
+(`reset_if_failed`); the reset moves its control revision on, so the revision
+the card sent is checked here instead. Pause and Resume are the editor's
+`pause_workflow` / `resume_workflow`.
Automatic pauses now record why: `WorkflowControlExecution.pause_reason`
(`failures` from the circuit breaker, `recovery` after a crash,
@@ -243,6 +310,216 @@ Automatic pauses now record why: `WorkflowControlExecution.pause_reason`
cleared on resume. Home shows such an employee as "Needs attention". See
[Temporal Workflow Control](./temporal-workflow-control.md#recovery-policies).
+### One-click starters
+
+Each starter bundle in `hire/starters.json` (Receptionist on WhatsApp, Inbox
+assistant on Gmail, Social media helper every week, Daily briefer every
+weekday morning) carries a `hire` block, the starter's own setup: names to
+pick an unused one from, the role, a one-line description, the routine, what
+starts the work and the app it answers through (`hire/templates.ts` parses it
+with zod). **Hire now**, on a picked chip or as Hire on a Settings > Plugins
+card, puts the starter's skills in the library (switching on any that are
+off), then hires that setup as it stands with "Ask me before sending
+anything" on (`genui/useStarterHire.ts`, `starterHirePayload` in
+`genui/hirePayload.ts`). It shares the one hire slot with the setup screen
+and lands like any hire. `test_home_catalog_contract.py` builds every starter
+that way and fails when one loses an app it names or the way it starts.
+
+### Connecting an AI model
+
+[connectAI/ConnectAIDialog.tsx](../client/src/features/home/connectAI/ConnectAIDialog.tsx)
+is the guided dialog for an owner who has never made an API key. It lists the
+featured providers of onboarding's Connect your AI step
+(`components/onboarding/aiProviderLinks.ts`: a hint and the page where the key
+is made), with names, marks and connected state from the credential
+catalogue. Picking one opens that provider's own panel, compact, with a link
+to its key page, and the dialog closes once the provider connects; "See all
+AI models" opens Settings > Connectors on AI. `homeStore.openConnectAI()`
+opens it when a setup answers `no_ai_provider`, after a hire that answers
+`needs_ai`, from the card's Connect an AI model, and when Start is refused
+with `needs_ai`. The key-page links live in `aiProviderLinks.ts`, not in the
+credential catalogue.
+
+## Talk
+
+The owner talks to an employee on its page. The conversation is the chat
+session whose id is the employee's workflow id, the thread the editor's chat
+pane also shows for that workflow (there, only the live generation). Every
+row goes through
+[services/chat_thread.py](../server/services/chat_thread.py): the owner's
+messages from `send_chat_message`, answers and reports from the
+[chatReply](./node-logic-flows/chat_utility/chatReply.md) ("Reply in Chat")
+node. Each row is stamped with the live generation, and each insert or clear
+is announced as `chat.updated`.
+
+### On the employee's page
+
+[employee/EmployeeTalk.tsx](../client/src/features/home/employee/EmployeeTalk.tsx)
+sits under the card: the thread, then a message box pinned to the bottom of
+the page (`HomeShell`'s scroll area is a column the view fills). Its queries
+and mutations are in [data/talk.ts](../client/src/features/home/data/talk.ts).
+
+- **The thread** is `get_chat_messages` with `all_generations: true` (the
+ newest `THREAD_LIMIT` messages), so it spans restarts. Where a message's
+ `run_key` (its generation) differs from the one before, a divider reads
+ "{Name} restarted — they start fresh from here". The owner's messages sit on
+ the right; answers carry the avatar and render as markdown (`ThreadMarkdown`,
+ in its own chunk). An empty thread offers suggestion chips that fill the box.
+ The list is an `aria-live` log. It refetches on `chat.updated`, after a
+ runtime reset, and when the socket reopens.
+- **The box** follows the control state the way `send_chat_message` does
+ (`talkMode` in `presentation.ts`):
+ - *send* (running, starting, resuming): a message shows at once
+ ("Sending…") and goes to the employee. "Thinking…" then holds the box
+ until an answer arrives. `useReplyWait` follows the talk agent's node
+ status in `nodeStatusStore` (for any workflow, not only the one open in
+ Dev mode) and gives up after `PICKUP_WAIT_MS` if the agent never starts,
+ `REPLY_WAIT_MS` while it works, or `SETTLE_WAIT_MS` after it stops, then
+ says "No answer from {Name} yet." Holding the box matters: overlapping
+ runs would each save over the other's conversation.
+ - *queue* (paused, pausing): one message waits for Resume ("Your message is
+ waiting…"), and the box holds until the employee runs again.
+ - *start* (never started, ready, resetting, failed): no box; a line says
+ they can't read messages, beside the card's main action (Start, or what
+ they are missing).
+ - A refused message leaves the thread and its text goes back in the box;
+ `not_running` (the state moved meanwhile) says "{Name} isn't running" and
+ refetches the team.
+- **Turn on Talk**: an employee whose `talk.state` is `off` (hired before
+ Talk, or built in Dev mode) shows Turn on Talk instead of the thread. An
+ `AlertDialog` confirms first, since it restarts them, and says so when drafts
+ are waiting (a restart cancels them). `unsupported` gets a note that their
+ setup has no way to answer.
+- **Pending changes**: while `pending_changes` is true, a notice above the box
+ reads "{Name} has new abilities for this conversation. Apply to make them
+ part of all their work (restarts {name}; the conversation continues after a
+ divider)." Its Apply (`ActionButton intent="config"`) calls
+ `apply_employee_changes`.
+- **Asking first**: under the page, a line says whether the employee asks
+ before sending anything on the owner's behalf (the summary's `asks_first`).
+
+### The talk line
+
+A run keeps only the firing trigger's downstream nodes plus their tools and
+config, so a line started by the owner's messages runs on those alone and
+never disturbs the work path ([talk.py](../server/services/employees/talk.py)):
+
+```
+chatTrigger (session_id = workflow id) -> agent -> chatReply ("Reply in Chat")
+```
+
+- **A chat hire** (the owner gives them work by messaging them): its own
+ "Chat" trigger and agent are the line, and Hire adds Reply in Chat after the
+ agent. No second chat trigger is added: two on one session would start two
+ runs per message.
+- **App-event and schedule hires** get a line beside the worker: a "Talk" chat
+ trigger on the workflow's session; a "Talk with {Name}" agent of the
+ worker's type, on its provider and model, with the prompt `{{talk.message}}`
+ and instructions written for Talk; its own Context (a conversation is never
+ shared); the worker's tools and Skills node, when it has one, wired to it
+ too (the same nodes, so Memory, the checklist, the Canvas and the skills are
+ shared); and its Reply in Chat.
+- **Schedule hires** also get "Post to Talk", a Reply in Chat fed by the
+ worker, so its routine reports land in the thread. When the app the reports
+ go out through can't be used yet, the hire's warning says they are in Talk
+ meanwhile.
+- **The Agent Builder**: the agent that answers the owner (a chat hire's
+ agent, or the talk agent) gets the `agentBuilder` tool. A worker that
+ strangers write to (a public app trigger) never has it.
+- Answers and reports go out only when the agent had something to say: the
+ edge into Reply in Chat carries `result.response neq NO_REPLY`.
+- The talk agent's instructions use prompt.py's `talk` delivery: the answer
+ goes straight to the owner, and it may add tools and skills with
+ `agent_builder` when the owner asks, but nothing that sends or spends while
+ they ask to check first.
+- The parts join `node_roles`: `talk_trigger`, `talk_agent`, `talk_context`,
+ `talk_reply`, `builder`, `report_post`. A chat hire's talk trigger, agent
+ and Context are its `trigger`, `agent` and `context`.
+- Labels are "Talk", "Talk with {Name}", "Reply in Chat", "Post to Talk" and
+ "Agent Builder", numbered when a label is taken ("Talk 2"). A new trigger's
+ label is also kept unique by `node_label_slug`, since a deployment registers
+ one listener per trigger label slug.
+
+`talk_state` reads a graph: `on` when a chat trigger feeds an agent (any
+registered agent type) that answers through Reply in Chat; `off` when one step
+adds it, either a chat trigger feeding an agent with no reply yet, or no chat
+trigger and an `aiAgent` / `chatAgent` a talk agent can copy; `unsupported`
+otherwise (a chat trigger that feeds no agent counts here). While a
+generation is live the summary reads the running snapshot, whose node ids are
+the ones that report status; otherwise the saved graph. `talk.agent_node_id`
+is the agent that answers, and it joins `watch_node_ids`.
+
+### Turn on Talk and Apply
+
+Both live in [handlers.py](../server/services/employees/handlers.py), run one
+at a time per employee, and answer with the employee's fresh summary, which
+the client puts in the team cache.
+
+- **`enable_employee_talk`** plans the line (`plan_talk_line`), adds it
+ through `apply_graph_additions` (one transaction; an editor with the
+ workflow open adopts it), records its roles on a hired row
+ (`store.merge_node_roles`), and restarts the employee on the saved graph. A
+ hired employee's talk agent gets instructions written again from its hire,
+ the Agent Builder, and, for a schedule worker, Post to Talk. A workflow built
+ in Dev mode gets a talk agent with the worker's own instructions plus a note
+ that this is Talk (`talk_addendum`), and neither extra. Talk already on
+ succeeds without a restart unless saved changes are waiting.
+- **`apply_employee_changes`** restarts the employee on the latest saved
+ graph.
+
+A restart is `restart_with_latest_graph`
+([services/deployment/restart.py](../server/services/deployment/restart.py)):
+running → Reset, then Start again (ends running); paused or failed → Reset
+(ends ready, and the next Start takes the saved graph); ready or never
+started → nothing to do; starting, pausing, resuming or resetting →
+`conflict`. The same idempotency key reports the restart it already made. A
+Reset clears the workflow's Context conversations (hence the divider), drops
+messages queued while paused, and cancels the drafts waiting for the owner.
+
+`pending_changes` is true while a generation is live (starting, running,
+pausing, paused, resuming) and the saved graph, put through Start's own
+normalization, differs from its snapshot in anything a run takes from it:
+nodes (id, type, label key, disabled) and edges (ends, handles, condition).
+Positions, edge ids and list order don't count, so moving a node in Dev mode
+is not a change; that is why `control.graph_hash` can't answer it. The
+summary refreshes after every save: `save_workflow` and
+`apply_graph_additions` notify the graph-changed listeners
+([services/workflow_storage/listeners.py](../server/services/workflow_storage/listeners.py)),
+where Normal mode registers its coalesced summary refresh.
+
+### Adding tools and skills from Talk
+
+The agent that answers the owner extends the employee with the
+[Agent Builder](./node-logic-flows/ai_tools/agentBuilder.md) when the owner
+asks, within the rule Hire applies
+([policy.py](../server/services/employees/policy.py)):
+
+- **Tools**: the ones every hire gets (web search, checklist, clock, Memory,
+ Canvas) and the app registry's. While "Ask me before sending anything" is
+ on, nothing that sends or spends, except a tool with `ask_first_params` in
+ that form (the browser, read-only). Every type must pass `is_hire_allowed`,
+ and an app's tool needs the app connected. A refusal is one plain sentence
+ the agent passes on.
+- **Skills**: from the owner's library (Settings > Skills, on or off for new
+ hires) and the Discover folder (`server/skills/employee/`), with their text
+ copied in; never `skill` or a `*-personality` skill.
+- **No teammates**: `add_subagent` is refused for a hired employee.
+- A new tool is wired to both the worker and the talk agent. A skill goes on
+ the Skills node they share, else on a new one wired to both.
+
+What goes live when:
+
+- A tool is callable at once in the conversation that asked for it: the agent
+ loop binds it for the rest of that run (`auto_rebind_tools_after_canvas_change`
+ in user settings, on by default).
+- A skill added to an existing Skills node applies from the next message:
+ node parameters are read live.
+- Everything else waits for a restart, because a live generation's runs take
+ their nodes and edges from its snapshot: the worker gets a new tool, and a
+ new Skills node starts working, after Apply. Meanwhile `pending_changes`
+ shows the notice. On a later message the talk agent can ask for the tool
+ again, which binds the saved node without adding a second one.
+
## Asking before sending
With the rule on, a reply waits in an `approvalGate` until the owner decides
@@ -253,6 +530,13 @@ closed: nothing is sent unless it was approved, and the recipient always comes
from the run's trigger. Full contract:
[approvalGate](./node-logic-flows/workflow_triggers/approvalGate.md).
+The same rule limits what an employee may add to itself from Talk (nothing
+that sends or spends; see [Adding tools and skills from Talk](#adding-tools-and-skills-from-talk)),
+and a talk agent that asks first is told it cannot send or spend anything for
+the owner, only write it for them to send. The summary's `asks_first` is the
+hire's rule (for a workflow built in Dev mode, whether it has an approval
+gate), shown in a line under the employee's page.
+
## "Done today"
Every trigger-spawned run that finishes writes a `workflow_run_records` row
@@ -296,11 +580,13 @@ changing page clears it.
employee's Skills node carries. `DISCOVER_SKILL_FOLDER` in
`features/home/data/skills.ts` names the folder.
- **Plugins**: starter bundles, from `features/home/hire/starters.json`, the
- same list the composer's template chips send. A bundle is a job, the apps it
- needs (named in the job, since the job is all the setup model reads), and
- its skills.
- - *Install* adds the bundle's skills to the library, switching on any that
- are off. It then starts a hire from the job on the hire view.
+ same list the composer's template chips read. A bundle is a job, the apps it
+ needs (named in the job, since the job is all the setup model reads), its
+ skills, and its own setup (`hire`).
+ - *Hire* adds the bundle's skills to the library, switching on any that
+ are off, then hires the starter as it stands and shows the new employee
+ (see [One-click starters](#one-click-starters)). A bundle can be hired
+ again, so Discover offers Hire on every card.
- A bundle counts as installed when all its skills are in the library;
nothing else is stored.
@@ -341,24 +627,31 @@ WebSocket requests (snake_case; failures come back as `success: false` with an
| Type | Payload | Response |
|---|---|---|
-| `list_employees` | `{}` | `{employees}`; each summary's `canvas_node_id` is its Canvas board: the one it was hired with, else the graph's first Canvas node, else null. `browser_request` is a browser waiting for the owner (`{node_id, reason, since}`), else null |
+| `list_employees` | `{}` | `{employees}`; each summary's `canvas_node_id` is its Canvas board: the one it was hired with, else the graph's first Canvas node, else null. `browser_request` is a browser waiting for the owner (`{node_id, reason, since}`), else null. `talk` is `{state: "on" \| "off" \| "unsupported", agent_node_id}` (the agent that answers the owner, which also joins `watch_node_ids`). `asks_first` is the hire's "ask me first" rule (built in Dev mode: whether it has an approval gate). `pending_changes` is true when the saved graph's structure differs from the live generation's snapshot |
| `get_employee` | `{workflow_id}` | the summary plus `description`, `job`, `plan`, `rules`, `choices`, `trigger_text`, `last_run`, `latest_report` |
| `get_employee_usage` | `{}` | `{tasks_this_month}` (successful runs since the 1st, owner's timezone, whole team) |
-| `generate_employee_setup` | `{job, refine?, history?, draft_token}` | `{draft_token, reply, provider, model, usage, retried, finish_reason, apps}` |
+| `generate_employee_setup` | `{job, refine?, history?, draft_token}` | `{draft_token, reply, provider, model, usage, retried, finish_reason, apps}`; `apps` maps each app the reply mentions to its AppRef plus `can_trigger` |
| `cancel_employee_setup` | `{draft_token}` | `{cancelled}` |
-| `hire_employee` | `HireEmployeeRequest` | `{employee, started, missing_apps, needs_ai, unsupported_apps, warnings, idempotent}` |
+| `hire_employee` | `HireEmployeeRequest` | `{employee, started, missing_apps, needs_ai, unsupported_apps, warnings, idempotent}`; errors include `busy` while the same key's first attempt is still building |
| `start_employee` | `{workflow_id, expected_revision, idempotency_key}` | as `start_workflow` |
+| `enable_employee_talk` | `{workflow_id, idempotency_key}` | `{employee}`. Errors: `invalid_request`, `not_found`, `unsupported`, `conflict` (a start, pause, resume or reset is under way, or the graph changed meanwhile), `restart_failed`; the last three carry `employee` too |
+| `apply_employee_changes` | `{workflow_id, idempotency_key}` | `{employee}`: running ends running, paused or failed ends ready, ready is left alone. Errors: `invalid_request`, `not_found`, `conflict`, `restart_failed` (the last two with `employee`) |
+| `send_chat_message` | `{message, role: "user", session_id: <workflow_id>, timestamp}` | `{timestamp, delivery}`: `"now"` while running, starting or resuming; `"queued"` while paused or pausing (it runs on Resume). In any other state `not_running`, and nothing is saved or sent. Session `"default"` works as before, with no `delivery` |
+| `get_chat_messages` | `{session_id, limit?, all_generations?}` | `{messages}`, oldest first, each `{id, role, message, timestamp, run_key}`. Timestamps carry their UTC offset; `run_key` is the generation the row was written in. Without `all_generations`, only the latest generation's rows (none after a Reset; every row when the workflow was never started) |
| `list_approvals` | `{workflow_id?, status?, limit <= 100}` | `{approvals, counts, server_time}` |
| `decide_approval` | `{approval_id, decision, text?, subject?, decision_key}` | `{approval, will_send_on_resume}` |
-Broadcasts, all CloudEvents envelopes broadcast directly (no Temporal
-consumer; see [Event Framework](./event_framework.md#ui-only-lifecycle-events-broadcast-directly-never-through-emit)):
+Broadcasts, all CloudEvents events broadcast directly (no Temporal
+consumer; see [Event Framework](./event_framework.md#ui-only-lifecycle-events-broadcast-directly-never-through-emit));
+every frame but `workflow_ops_apply` carries the whole envelope:
| Wire key | Type | Notes |
|---|---|---|
| `employee_lifecycle` | `com.opencompany.employee.{hired,updated,removed}` | Subject is the workflow id; `updated` is coalesced to one per second per employee, except control changes and browser control changes (each agent step, and the wait for the owner), which go out at once |
| `approval_lifecycle` | `com.opencompany.approval.{requested,decided,expired,cancelled}` | Identity only, never the message or the recipient |
| `workflow_lifecycle` | gains `created` and `deleted` stages | So open editors refresh their workflow lists |
+| `chat.updated` | `com.opencompany.chat.updated` | Sent after every chat insert and clear (`services/chat_thread.py`). Data `{workflow_id, session_id, role}`, identity only: `role` is null for a clear, `workflow_id` null for session `"default"`. Home's thread and the editor's chat pane refetch |
+| `workflow_ops_apply` | `com.opencompany.workflow.ops.applied` | The frame is the event's flat data, `{workflow_id, caller_node_id, operations, persisted?}`, not the envelope. `persisted: true` marks a batch the server already saved (`apply_graph_additions`: Turn on Talk, the Agent Builder), whose ops carry the server's ids; editors adopt it without saving. See [Workflow Operations Protocol](./workflow_ops_protocol.md#persisted-batches) |
## Tests
@@ -368,10 +661,24 @@ Server: `tests/services/employees/`, `tests/services/approvals/`,
`tests/test_user_settings_profile_fields.py`,
`tests/test_credential_catalogue_consumer_fields.py`,
`tests/test_home_catalog_contract.py` (the starter bundles and the Discover
-folder against each other and the app registry),
+folder against each other and the app registry, and each starter built with
+"ask me first" on),
`tests/temporal/test_machina_run_record.py` (including replay of a pre-patch
-history). Client: `features/home/**/__tests__`, `app/__tests__`,
-`contexts/__tests__/themePrePaint.test.ts`.
+history). Talk and growing a saved employee: `tests/services/employees/`
+(`test_talk.py`, `test_enable_talk.py`, `test_apply_changes.py`,
+`test_policy.py`, and `test_builder_snapshot.py` against
+`tests/fixtures/employee_builder_snapshot.json`),
+`tests/services/test_chat_thread.py`, `tests/nodes/test_chat_reply.py`,
+`tests/services/test_graph_build.py`, `tests/services/test_graph_additions.py`,
+`tests/services/test_graph_listeners.py`,
+`tests/services/test_deployment_restart.py`,
+`tests/nodes/test_agent_builder_employee.py`. Client:
+`features/home/**/__tests__` (including `talk.test.tsx`, `thread.test.ts`,
+`connectAI.test.tsx`), `app/__tests__`,
+`contexts/__tests__/themePrePaint.test.ts`,
+`contexts/__tests__/webSocketActions.test.tsx` (`chat.updated`, the editor
+chat's rollback), `lib/__tests__/workflowOps.test.ts` and
+`hooks/__tests__/useWorkflowOpsListener.test.ts` (persisted batches).
## Known gaps
@@ -387,8 +694,9 @@ history). Client: `features/home/**/__tests__`, `app/__tests__`,
because deleting a workflow deletes its run records.
- Connectors has no custom (MCP) connector.
- Skill library changes reach only new hires: an employee keeps the skills it
- was hired with, and one hired before the library existed has none. The
- library is shared across users in multi-user mode, like the team list.
+ was hired with, and one hired before the library existed has none, until
+ the owner asks them in Talk to add one. The library is shared across users
+ in multi-user mode, like the team list.
- An employee hired before Canvas has no Canvas node, so its
`canvas_node_id` is null. Adding one in Dev mode fills it in.
- The Workspace's Android tab has no live mirror yet. Browser now uses the
@@ -404,5 +712,34 @@ history). Client: `features/home/**/__tests__`, `app/__tests__`,
there. This predates the Workspace and applies to the editor's Memory
and Data Source tools as well. Fixing it moves existing memories to a
different owner, so it needs its own change.
-- A manual-chat employee cannot be given work from Home yet; the setup prompt
- steers towards app and schedule triggers.
+- The talk agent has its own conversation: it cannot see the worker's
+ exchanges with customers or the text of its routine reports. The two share
+ Memory, the Canvas, the checklist and the skills.
+- A tool added from Talk works at once only in the talk agent's current run.
+ The next message is a new run from the live generation's snapshot, which
+ lacks it until the agent asks the Agent Builder for it again (that binds
+ the saved node, bind-only). The worker gets it only after Apply.
+- Messages queued while paused each start a run on Resume; the page allows
+ one queued message at a time.
+- Turn on Talk and Apply reset the employee: its Context conversations start
+ fresh (the thread's divider says so), messages queued while paused are
+ dropped, and drafts waiting for the owner are cancelled (the confirmation
+ and the notice warn about those).
+- A Dev editor holding unsaved edits made before a server-side change (Turn on
+ Talk, the Agent Builder) can still overwrite it on its next save, because
+ saves carry no revision check. Adopting persisted batches narrows the
+ window.
+- Pre-existing: with Temporal disabled, deployed chat triggers never fire,
+ and a canvas Run of a `chatTrigger` waits forever.
+- An example workflow whose agent serves several triggers posts all of that
+ agent's answers into the thread: AI Employee and Claude Assistant answer
+ Telegram through the same agent.
+- Threads are per workflow, not per user.
+- A chat trigger with a custom `session_id` still counts as Talk `on`, though
+ Home's messages (session = the workflow id) never reach it.
+- Turn on Talk on a chat hire made before Talk adds Reply in Chat and the
+ Agent Builder but leaves the worker's instructions as they were, so they do
+ not mention the `agent_builder` tool.
+- A schedule in a time zone `cronScheduler` does not list runs in a zone with
+ the same offset at hire time (else UTC, shifted), so it drifts across
+ daylight-saving changes.
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index 9a98cb57..428a3e0f 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -78,7 +78,7 @@ class SpecializedAgentBase(ActionNode, abstract=True):
| `Params` | Pydantic `BaseModel` — user-facing parameters. Used for both UI rendering and AI tool schemas. |
| `Output` | Pydantic `BaseModel` — runtime output shape. |
| `usable_as_tool` | `ActionNode` flag — mints a ToolNode adapter for AI invocation. Combined with `component_kind != "model"`, makes the plugin visible to `agentBuilder.add_tool` (catalogue + rebind paths). **Side effect:** setting it auto-sets `hide_input_handle` / `hide_output_handle` to `True` unless the class declares them (`BaseNode.__init_subclass__` in [base.py](../server/services/plugin/base.py), which does the same for `component_kind == "tool"`), and `_metadata_dict` adds an `output-tool` handle. The frontend (`SquareNode`) reads the hide flags only when a spec declares no handles; a spec with handles renders exactly what it declares. So a dual-purpose node that must stay wirable on the canvas declares `input-main` / `output-main` in `handles`; setting the flags `False` alone does not add them. |
-| `needs_canvas` | `ClassVar[bool]` — when `True`, the F4.B `AgentWorkflow` tool-dispatch forwards the parent workflow's `nodes`/`edges` into the per-tool activity payload. Today only `AgentBuilderNode` opts in (walks edges to resolve its calling agent). |
+| `needs_canvas` | `ClassVar[bool]` — when `True`, the F4.B `AgentWorkflow` tool-dispatch forwards the parent workflow's `nodes`/`edges` into the per-tool activity payload. Today only `AgentBuilderNode` opts in: `add_tool` compares the run's canvas with the saved graph, so a tool saved earlier but missing from the running snapshot is handed back to be bound. Its calling agent comes from `invoking_agent_node_id` / `parent_node_id`, not from edges. |
| `task_queue` | Temporal worker pool. See `TaskQueue` constants. |
| `retry_policy` | `RetryPolicy` dataclass (mirrors `temporalio.common.RetryPolicy`). |
| `start_to_close_timeout` / `heartbeat_timeout` | Per-node Temporal knobs. |
diff --git a/docs-internal/status_broadcaster.md b/docs-internal/status_broadcaster.md
index a0b5da8c..7f758dd0 100644
--- a/docs-internal/status_broadcaster.md
+++ b/docs-internal/status_broadcaster.md
@@ -152,24 +152,32 @@ Broadcasts are sent to all connected clients without a request-response correlat
| `compaction_completed` | Memory compaction ends | `{session_id, success, tokens_before, tokens_after}` |
| `context.updated` | A conversation durably saved (`save_conversation` upsert), or cleared from the panel / workflow Reset — emitted from the store's save boundary via `register_conversation_listener`, so every writer (in-process loop, Temporal LLM activity, specialized-provider bridge) is covered without call-site code. Frontend invalidates `['agentContext']`. | `{specversion: "1.0", id, source: "opencompany://nodes/context", type: "com.opencompany.context.updated", subject: agent_node_id, time, data: {workflow_id, generation, agent_node_id, message_count}}` |
| `memory.updated` | A durable Memory mutation (remember / update / forget / clear) from either writer — the agent's tool call or the panel handlers. Frontend invalidates `['memoryItems']` + `['memoryItem']`. | `{specversion: "1.0", id, source: "opencompany://nodes/simple_memory", type: "com.opencompany.memory.updated", subject: memory_node_id, time, data: {workflow_id, memory_node_id, operation}}` |
+| `chat.updated` | A chat row added or a thread cleared, sent after every insert and clear by `services/chat_thread.py` (`record_chat_message` / `clear_chat_thread`), the one write path for chat rows: `send_chat_message`, `save_chat_message`, `clear_chat_messages` and the `chatReply` node all go through it. Frontend invalidates Home's thread (`queryKeys.chatThread.bySession`) and reloads the editor's chat pane when the session is the open workflow's. | `{specversion: "1.0", id, source: "opencompany://services/chat_thread", type: "com.opencompany.chat.updated", subject: session_id, time, data: {workflow_id, session_id, role}}` (`workflow_id` null for session `"default"`, `role` null for a clear) |
+| `workflow_ops_apply` | A workflow-ops batch for open editors, sent by the core factory `services/workflow_ops.broadcast_workflow_ops`. `services/workflow_storage/mutate.apply_graph_additions` (Turn on Talk, the Agent Builder) sends every batch it saved with `persisted: true`: the ops carry the server's node and edge ids, positions and full parameter rows, and editors adopt them without saving. The Vertex managed agent's cloud-tool nodes send the same frame from `nodes/agent/vertex_managed_agent/_ops.py`, not persisted. See [workflow_ops_protocol.md](./workflow_ops_protocol.md#persisted-batches). | The event's flat data, not the envelope: `{workflow_id, caller_node_id, operations, persisted?}` (the event is built as `com.opencompany.workflow.ops.applied`) |
| `browser_updated` | A Browser profile's control state changes (`idle` / `agent` / `awaiting_user` / `user`), from `nodes/browser/_session.py`. Identity and state only; the live viewer reads the details over `/ws/browser`. Frontend opens the Dev dock on its Browser tab when the open workflow's browser reaches `awaiting_user`. | `{specversion: "1.0", id, source: "opencompany://nodes/browser", type: "com.opencompany.browser.updated", subject: session_id, time, data: {workflow_id, node_id, session_id, state, revision}}` |
| `browser_profiles_updated` | A Browser profile is added, renamed, deleted or gets new logins. Frontend invalidates `['browserProfiles']` (the Credentials "Web browser" panel). | `{specversion: "1.0", id, source: "opencompany://nodes/browser", type: "com.opencompany.browser.profiles.updated", subject: "profiles", time, data: {revision}}` |
| `browser_runtime` | Chrome for Testing download progress (`BROWSER_RUNTIME=testing` only; `_install_chrome.py`). No frontend case; the viewer polls `browser_runtime_status` while it waits. | `{specversion: "1.0", id, source: "opencompany://nodes/browser", type: "com.opencompany.browser.runtime.progress", subject: component, time, data: {component, phase, percent, version, error}}` |
-`context.updated` and `memory.updated` call
-`get_status_broadcaster().broadcast(...)` directly rather than
+`context.updated`, `memory.updated`, `chat.updated` and `workflow_ops_apply`
+call `get_status_broadcaster().broadcast(...)` directly rather than
`services.events.dispatch.emit`. `emit` exists to reach Temporal consumers and
pays a Visibility `ListWorkflowExecutions` query to find them; no node type
registers a canary consumer for `com.opencompany.context.*` /
-`com.opencompany.memory.*`, so that query can only ever match nothing — once
-per save. Same pattern as `nodes/telegram/_events.py`. See
+`com.opencompany.memory.*` / `com.opencompany.chat.updated` /
+`com.opencompany.workflow.ops.*`, so that query can only ever match nothing —
+once per save. Same pattern as `nodes/telegram/_events.py`. See
[event_framework.md → UI-only lifecycle events](./event_framework.md).
-Payloads are identity + count only — no message bodies, no item content —
-because `StatusBroadcaster.broadcast()` fans out to **every** connected socket with no
+The `context.updated`, `memory.updated` and `chat.updated` payloads are
+identity only (plus a count, an operation or a role) — no message bodies, no
+item content — because
+`StatusBroadcaster.broadcast()` fans out to **every** connected socket with no
per-workflow filtering. The panels refetch through the authorized
`get_agent_context` / `list_memory_items` handlers, which is where ownership
-is enforced.
+is enforced; chat views refetch through `get_chat_messages`, which reads a
+session by id (threads are per workflow, not per user). `workflow_ops_apply`
+is the exception: it carries the ops themselves, parameter rows included,
+because an editor applies them as they arrive.
## Execution correlation IDs
diff --git a/docs-internal/workflow_ops_protocol.md b/docs-internal/workflow_ops_protocol.md
index 888e4388..22d73046 100644
--- a/docs-internal/workflow_ops_protocol.md
+++ b/docs-internal/workflow_ops_protocol.md
@@ -3,7 +3,8 @@
The standard wire format any backend service uses to mutate the React
Flow canvas. A service returns `{operations: [...]}`; the frontend
walks the list with a single applier (`client/src/lib/workflowOps.ts`)
-that creates / removes nodes + edges and persists parameter changes.
+that creates / removes nodes + edges and saves parameter rows, unless
+the server already saved the batch (see [Persisted batches](#persisted-batches)).
**Why a protocol**: keeps domain rules in the backend (visuals.json
lookups, plugin-registry checks, canonical config shapes) without
@@ -30,9 +31,9 @@ ids that later ops reference via `client_ref` placeholders.
| Type | Required | Optional | Purpose |
|---|---|---|---|
-| `add_node` | `client_ref`, `node_type`, `parameters` | `label`, `position`, `minted_id` | Create a new node + persist its initial params. `client_ref` is a batch-local id later ops can target. When `minted_id` is set (BE hot-spawn path — `agentBuilder` mints upfront so status broadcasts route to the same React Flow id), the FE applier adopts the supplied id verbatim instead of calling `newId()`. |
-| `add_edge` | `source`, `target` | `source_handle`, `target_handle` | Wire two nodes. `source` / `target` are either existing node ids (string) or `{client_ref}` references. |
-| `set_node_parameters` | `node_id`, `parameters` | -- | Shallow-merge `parameters` into the node's existing params via `saveNodeParameters`. |
+| `add_node` | `client_ref`, `node_type`, `parameters` | `label`, `position`, `minted_id`, `data` | Create a new node + save its initial params. `client_ref` is a batch-local id later ops can target. When `minted_id` is set (a server-side writer allocated the id, so status broadcasts route to the same React Flow id), the FE applier adopts it verbatim instead of minting one. `data` is node data beyond the label (a Context's `systemManaged` / `agentNodeId` link to its agent). |
+| `add_edge` | `source`, `target` | `source_handle`, `target_handle`, `edge_id`, `condition` | Wire two nodes. `source` / `target` are either existing node ids (string) or `{client_ref}` references. `edge_id` is the server's id for an edge it saved; the applier adopts it. `condition` gates the edge (saved as `edge.data.condition`). |
+| `set_node_parameters` | `node_id`, `parameters` | -- | `parameters` is the node's WHOLE row: the applier saves it with `saveNodeParameters`, which replaces the row, so an op that is not persisted must carry every parameter to keep. In a persisted batch it is the server's merged row, and nothing is saved. |
| `delete_node` | `node_id` | -- | Remove node; edges to/from it cascade-delete. |
| `delete_edge` | `edge_id` | -- | Remove a single edge. |
| `move_node` | `node_id`, `position` | -- | Reposition without changing identity. |
@@ -73,7 +74,40 @@ the same batch.
has no rollback. Backend services should write op sequences that are
robust to partial application.
- **Not a diff reconciler**: re-applying a batch is not assumed safe.
- The protocol is a one-shot mutation wire format.
+ The protocol is a one-shot mutation wire format. Persisted batches are
+ the exception: they are applied idempotently (below).
+
+## Persisted batches
+
+A server-side writer that changes a saved workflow goes through
+`services/workflow_storage/mutate.py::apply_graph_additions`: one
+transaction appends the nodes and edges to `workflow.data`, writes a fresh
+parameter row for each new node, merges into existing rows (a Skills
+node's `skills_config`), and records a ledger row keyed by the caller's
+mutation id, so a retry returns the first result instead of adding twice.
+After the commit it pushes the batch with `persisted: true`:
+
+```json
+{"type": "workflow_ops_apply",
+ "data": {"workflow_id": "7", "caller_node_id": "7:aiAgent:2",
+ "operations": [...], "persisted": true}}
+```
+
+The ops carry the server's node ids (`minted_id`), edge ids (`edge_id`),
+absolute positions, node `data`, edge `condition`, and full parameter rows.
+An editor adopts them as they are:
+
+- nothing is saved: the server wrote the nodes, edges and rows itself (an
+ editor that re-saved a row would REPLACE it, which is how a hire's copied
+ library skills used to be wiped);
+- ids the canvas already has are skipped, because the same batch can
+ arrive twice (a retried write announces it again);
+- `set_node_parameters` goes to the parameter cache, not the graph.
+
+Unlike `save_workflow` this never replaces the graph, so it cannot drop what
+an editor saved meanwhile. An editor holding unsaved changes made before the
+push can still overwrite it on its next save (saves carry no revision check);
+adopting the batch into the editor's working copy narrows that window.
## Backend usage
@@ -122,7 +156,9 @@ failures (toast, log, retry, etc.).
| Service | Trigger | Module |
|---|---|---|
| Auto-add Skill on tool connect | WS request `evaluate_auto_skill` (frontend on edge connect/disconnect) | `server/services/auto_skill.py` |
-| Agent Builder runtime tools | WS broadcast `workflow_ops_apply` (backend, mid-execution) + DB persist via `database.save_workflow` so subsequent runs and in-run reload see the mutation | `server/nodes/tool/agent_builder/__init__.py` |
+| Agent Builder runtime tools | `apply_graph_additions`, then the persisted `workflow_ops_apply` push (mid-execution, from the agent's tool call) | `server/nodes/tool/agent_builder/__init__.py` |
+| Turn on Talk (any employee on Home, hired or built in Dev mode) | `apply_graph_additions`, then the persisted push | `server/services/employees/handlers.py` |
+| Vertex managed agent cloud-tool nodes | whole-graph `database.save_workflow`, then a push that is NOT persisted (the editor saves the parameter rows) | `server/nodes/agent/vertex_managed_agent/_ops.py` |
## Two delivery modes
@@ -136,13 +172,24 @@ directions:
* **Push broadcast** (Agent Builder pattern). Backend code (often
inside an LLM tool execution) calls
- `services.status_broadcaster.send_custom_event('workflow_ops_apply',
- {workflow_id, caller_node_id, operations})`. The frontend's
- `useWorkflowOpsListener` hook (mounted in `Dashboard`) subscribes
- via `WebSocketContext.addEventListener('workflow_ops_apply', ...)`,
- filters by current `workflow_id`, and pipes ops through
- `applyOperations`. Events targeting other workflows surface as a
- sonner toast with a "Switch" action.
+ `services.workflow_ops.broadcast_workflow_ops(workflow_id=...,
+ caller_node_id=..., operations=..., persisted=...)`, which sends the
+ flat `{workflow_id, caller_node_id, operations, persisted?}` frame;
+ `apply_graph_additions` calls it for every batch it saves. Two
+ frontend listeners subscribe through
+ `addEventListener('workflow_ops_apply', ...)`:
+ - `useWorkflowOpsListener` (mounted in `Dashboard`) applies a batch
+ for the open workflow to the canvas: a persisted one by adopting it
+ (`addSavedNodes` / `addSavedEdges`), any other through
+ `applyOperations`. A batch for another workflow shows a toast,
+ "{Name} updated their tools" (the name from the workflow list).
+ - `useSavedGraphSync` (mounted in the app shell, so it also runs while
+ Home is showing) adopts a persisted batch into the app store's
+ working copy of the workflow the editor holds
+ (`adoptSavedOperations`), leaving the unsaved flag alone, and puts
+ its parameter rows in the parameter cache. A workflow left open in
+ Dev while an employee changes it from Talk then keeps the server's
+ additions, and the editor's next save cannot drop them.
## Adding a new consumer
@@ -152,9 +199,13 @@ directions:
* Request/response: add a thin `@ws_handler` that returns
`{success: True, operations: [...]}`. On the frontend send the
WS request and pipe the result into `applyOperations`.
- * Push broadcast: call `send_custom_event('workflow_ops_apply',
- {workflow_id, caller_node_id, operations})`. No frontend code
- -- the existing listener handles it.
+ * Push broadcast, for a change to a saved workflow: describe it as
+ `services.graph_build.GraphAdditions` and call
+ `apply_graph_additions`, which saves it and pushes the persisted
+ batch. No frontend code -- the existing listeners handle it.
+ * Push broadcast of a batch the server did not save: call
+ `broadcast_workflow_ops(...)`; the editor applies it and saves the
+ parameter rows.
3. If you need a new op type, follow the steps in the docstring of
`server/services/workflow_ops.py` (mirror the TypedDict in TS,
add an apply branch, document here).