Self-improving AI Employees for everyone
Chat Trigger (chatTrigger)
| Field | Value |
|---|---|
| Category | workflow / trigger / utility |
| Backend handler | Plugin server/nodes/trigger/chat_trigger/__init__.py (ChatTriggerNode). Deployed generations register its filter with WorkflowControlWorkflow, which receives Signals and starts graph runs with the trigger pre-executed. The base TriggerNode.execute event-waiter wait is the direct execution path; its @Operation("wait") body is a stub. Standalone legacy deployments retain TriggerListenerWorkflow. |
| Tests | server/tests/nodes/test_workflow_triggers.py, server/tests/services/chat/test_handlers.py, server/tests/services/chat/test_stop.py, server/tests/temporal/test_controller_accumulator.py |
| Skill (if any) | none |
| Dual-purpose tool | no |
Purpose
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/services/chat/events.py
emits a CloudEvents WorkflowEvent (type: com.opencompany.chat.message.received,
source opencompany://services/chat) via dispatch.emit, never broadcast to
sockets. chatTrigger is canary-registered (register_canary_trigger_type).
For a generation with a durable controller, DeploymentManager sends
register_trigger; the controller retains its filter and graph context rather
than starting a separate listener. dispatch.emit discovers the controller
through Temporal Visibility and sends on_event. The controller filters each
registered trigger, queues the accepted event and starts a child
MachinaWorkflow when producer admission is open. Deployments without a
durable controller keep the standalone TriggerListenerWorkflow route.
A matching session_id (or 'default') makes the payload the trigger's
pre-executed 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 into the same thread. See
Normal mode → Talk.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
| (none) | - | - | Trigger nodes have no inputs. |
Parameters
| 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. 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)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | The chat event payload (see below). |
Output payload
services/chat/handlers.py::handle_send_chat_message builds the event as:
{
message: string;
timestamp: string; // ISO 8601; the client's, else the server's time (UTC)
session_id: string;
message_id: string; // the saved message's id
run_id?: string; // the chat run the message started, when one did
}
Wrapped in the standard envelope, whose stable id is the run id when there is
one, otherwise the saved message id. Redelivery of that same envelope keeps its
identity; the controller's deduplication key is <listener_id>:<event_id>.
A run spawned from it claims that chat run (MachinaWorkflow,
machina-chat-run-v1) and passes run_scope to every node, so
chatReply saves its answer as the run's reply.
See chat_protocol.md.
Logic Flow
flowchart TD
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 ledger: save the message,<br/>and its run when a chat trigger answers the session]
W --> Q[services/chat/events.py dispatch.emit<br/>WorkflowEvent com.opencompany.chat.message.received]
Q --> R[WorkflowControlWorkflow receives on_event Signal<br/>legacy standalone listener retains its route]
R --> K[match event type, deduplicate<br/>and queue accepted trigger event]
K --> A{producer admission open?}
A -- no --> B[retain event until Resume]
B --> A
A -- yes --> 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]
S -- no match --> D[consume this trigger's rejected event]
Decision Logic
- Filter (
ChatTriggerNode.build_filter):
Soif session_id and session_id != 'default': return event.get('session_id') == session_id return Truesession_id='default'(the frontend default) is a wildcard - the trigger fires for every chat message regardless of which session the user is in. - Controlled Stop: suspends admission on the owning generation. It does
not cancel the trigger, withdraw its accepted event or terminalize the chat
run. Already admitted work drains before
pausedis acknowledged; Resume releases the same continuation or pending event. See Chat protocol → Controlled Stop acknowledgement. - Direct-path cancellation: the event-waiter path can yield
success=False, error="Cancelled by user". Reset/Clear and legacy terminal chat Stop retain their separate lifecycle behavior.
Side Effects
- Database writes: none while it fires. (
send_chat_messagekeeps the message in the session's thread first, with its chat run, throughservices/chat/ledger.admit_message, stamped with the live generation, and announceschat.updated.) On a workflow Reset itsreset_execution_stateclears the workflow's own thread (session = the workflow id, never a customsession_idanother workflow may share), aschatReply's does: the conversation ended with the generation. It matters for a graph with a trigger and no reply yet, such as the one Turn on Talk resets before its new reply node runs. - Broadcasts: the producer emits a CloudEvents
WorkflowEventviadispatch.emit(Temporal Signal fan-out only:broadcast=False, since the envelope carries the owner's text). The controller (or legacy listener) emits firing-pulse status viabroadcast_trigger_status_activityaround child admission. Chat-run events are delivered only to authorized session subscribers; generation control status is broadcast separately. - External API calls: none.
- File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: none.
- Services: chat ledger/thread,
services.events.dispatch, Temporal controller and graph execution,services.status_broadcaster; the direct event-waiter path usesservices.event_waiter. - Python packages: Temporal Python SDK for deployed execution; the plugin's filter/output logic uses the base node framework.
- Environment variables: none.
Edge cases & known limits
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.- Distinct registered
chatTriggernodes with the same session ID can all match a message: the first graph run to claim tracks the chat run and the others run untracked. Existing listener ids use the workflow slug and display-label slug, so duplicate trigger labels/types can collide before registration; this remains a naming limitation. 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.
- For a workflow's session,
send_chat_messagefirst reads the latest control. While it runs, starts or resumes, the response saysdelivery: "now"; a versioned Resume still holds producer admission until descendants are released. While it is paused or pausing, an event accepted by the controller stays queued for Resume (delivery: "queued"). In any other state the handler answersnot_runningand neither saves nor dispatches the message. Session'default'is saved and dispatched as before, so a message there is stored even when nochatTriggeris waiting. A workflow's message starts a chat run only when a deployedchatTriggeraccepts its session; while a run is live the next message is refused withrun_in_progress. Controlled Stop keeps that lane occupied and its run/reply ids unchanged; legacy Stop can withdraw a queued message and release the lane. - The controller applies the Event Accumulator mechanics to accepted events: pending-key deduplication, bounded recent keys, FIFO overflow pages in the existing queue store, and queued-event carry through continue-as-new. Processing remains immediate when admission is open; there is no inactivity batching. Deduplication of completed historical events is bounded, not an indefinite exactly-once guarantee.
dispatch.emituses eventually consistent Visibility discovery and logs unavailable clients, query failures and Signal failures. Saving the message and returningdeliverydoes not guarantee the Signal was accepted; no durable ingress outbox was added. Once Temporal accepts the Signal, replay and the controller's rollover fences preserve its accepted pending event. A repeatedclient_message_idreturns the original message/run without redispatching, so client resend is not an ingress recovery mechanism.- A control request timeout leaves
pausingintact and lets status reconciliation continue; it does not cancel the current tool. Intentionally stopped controlled chat runs are protected from watchdog age expiry and get a fresh timeout window after successful Resume.
Related
- Skills using this as a tool: none.
- Sibling triggers:
webhookTrigger,taskTrigger. - Answers into the thread:
chatReply. - Architecture docs: Event Waiter System, Status Broadcaster, Normal mode → Talk, Temporal Workflow Control, Temporal Workflow Messaging Patterns