Mission Control — automation and the internals (part 5)
Part 5 of the Mission Control page, for anyone working on it: the board automation engine and the events it fires on, the bridge that lets the app's own automation react to a board event, the workflow-engine nodes that poll a board, where the local data mirror lives, and the command surface an agent or script drives.
On this page
What it is
This is part 5 of the Mission Control page. It is the how-it-is-built half: the automation engine and the internals behind a board.
Where to find it
Automations are configured against a board inside Mission Control; the rest of this part is reached from code or the command line rather than from a screen.
How it behaves
Board automation engine (Phase 5C)
Phase 5C adds an event-driven automation engine that fires action chains when board data changes. The sync service snapshots board state before each sync, diffs after, and emits typed BoardEvent objects (27 event types: item_created, item_deleted, item_restored, item_archived, item_unarchived, item_name_changed, item_status_changed, item_assigned, item_due_date_passed, item_moved_to_group, item_column_changed, date_approaching, schedule, sprint_started, sprint_ended, comment_added, approval_changed, webhook_received, column_created, column_renamed, column_deleted, link_created, link_deleted, session_completed, group_created, group_deleted, group_renamed). The automation engine matches events against user-defined rules in pm_board_automations and dispatches action chains through the existing Omniscio automation dispatcher.
Condition evaluation: each rule carries a conditionConfig — either { method: 'always' } (fire unconditionally, zero overhead) or { method: 'conditions', root: ConditionGroup } (recursive AND/OR tree of column conditions). After a trigger matches, the engine evaluates the condition tree against the triggering item's column values before dispatching actions. Ten operators: equals, not_equals, contains, not_contains, greater_than, less_than, is_empty, is_not_empty, in_list, not_in_list. Cross-board conditions (scope: 'linked') resolve linked items via connect_boards columns. Safety limits: max 3 nesting depth, max 10 conditions, max 3 cross-board refs, 5-second timeout. On evaluation failure, the rule is skipped (fail-closed — the action does NOT fire). The ConditionBuilder UI (ConditionBuilder.tsx, ConditionGroupNode.tsx, ConditionRuleRow.tsx) renders a visual AND/OR tree editor inside the AutomationBuilder modal.
Safety controls: master toggle (pmAutomationsEnabled, default off), event dedup (SQLite pm_automation_processed_events with 7-day retention), 5-second per-rule cooldown, condition evaluation with safety limits, stop-on-match, and always-persist run records (even on failure).
A due-date checker (pm-due-date-checker) runs every 15 minutes, scans date columns for overdue items, and feeds item_due_date_passed events into the engine. Twelve pm.* action types are defined in ActionType (src/shared/types/automations.ts): pm.move-item, pm.set-column-value, pm.update-linked-status, pm.add-comment, pm.create-item, pm.create-subitem, pm.duplicate-item, pm.notify, pm.spawn-session, pm.log-time, pm.on-result, and pm.if-else (conditional control flow). A session that pm.spawn-session starts is linked to the item whose event fired the rule (when that item exists on the event's own board), so the item's card shows it as the item's session; a board-level or scheduled run spawns an unlinked session as before.
CLI routes: GET/POST/PATCH/DELETE /pm/automations — all auth-gated and rate-limited; POST/PATCH are Zod-validated via parseBodyOr400, while GET and DELETE validate params with manual checks only. IPC: 6 channels for CRUD + presets + run history, all Zod-validated with push on mutation. Thirty-three preset templates in four categories — notify (status-done-notify, assigned-to-me-inbox, done-notify-creator, date-approaching-reminder, column-changed-notify, milestone-completion-notify, session-done-notify), organize (new-item-assign, due-date-overdue-move, bug-triage, review-request-notify, new-item-subtask-checklist, done-duplicate-to-review, moved-in-progress-kickoff, team-auto-assign, batch-status-update, sprint-end-cleanup), escalate (blocked-create-session, stale-issue-alert, overdue-escalation, sla-breach-alert, priority-escalation), automate (sprint-rollover, date-approaching-ai-prep, new-item-ai-plan, recurring-task, approval-done-move, approval-rejected-notify, status-changed-comment, done-update-linked-status, session-done-log-and-comment, ai-sprint-retrospective, ai-risk-analysis). Six presets are AI-powered (isAiPowered: true): blocked-create-session, date-approaching-ai-prep, new-item-ai-plan, overdue-escalation, ai-sprint-retrospective, ai-risk-analysis. The PresetGallery renders an "AI" badge next to AI-powered presets via rendererT('presetGallery.aiLabel').
Not in this change (follow-up): a dependencies_resolved event type (requires dependency-tracking infrastructure that does not yet exist) and per-event-type notification muting (mutedEventTypes on notification preferences). Both are planned as separate follow-up work.
Per-rule approval: non-cost-bearing rules default to approval_status = 'approved', while cost-bearing rules (those whose action triggers isCostBearingAction) auto-gate to pending_approval without an explicit parameter. A cost-bearing step counts anywhere in the chain, including inside a pm.if-else / pm.on-result branch at any depth, and under the pm.* underscore spelling the engine also runs (pm.spawn_session). Approve and reject are final decisions on a pending rule, so a rule that was never held (no cost-bearing step) answers 409 "already resolved" from the approval route by design. Pending rules are excluded from listActiveBoardAutomations() until approved. A pm-automation-approval inbox source surfaces pending rules in the unified inbox (gated on missionControlEnabled + pmAutomationsEnabled). IPC channels: pm:board-automation:pending-list (cross-board pending query) and pm:board-automation:set-approval (approve/reject).
Feature gating: registered as 'pm-automations' in UNRELEASED_FEATURES with status 'in-development'. The renderer UI (Phase 5F) lives in src/plugins/mission-control/web/features/automations/ (AutomationsPage, AutomationBuilder, PresetGallery, TriggerPicker, ActionPicker, RunHistoryPanel, and more).
- Contract: pm-automation-contract.md
- Key files:
src/main/services/pm/automation/pm-automation-service.ts(engine),src/main/services/pm/automation/pm-condition-evaluator.ts(condition tree evaluator),src/main/services/pm/pm-board-diff.ts(diff),src/main/services/pm/date-scanning/pm-due-date-checker.ts(cron),src/main/services/pm/automation/pm-automation-queries.ts(CRUD),src/main/services/pm/automation/pm-automation-presets.ts(presets),src/main/ipc/pm-automation-handlers.ts(IPC),src/main/services/cli/cli-server-pm-automation-routes.ts(CLI)
PM event channel bridge
Bridges PM board events into the channel automation engine (automations table), adding a fourth trigger type on_pm_event alongside on_message, manual, and on_session_state. This lets users create channel automations like "when a task goes overdue, nudge me in inbox" using the same rules UI as any other automation.
How it works: the PM sync service calls bridgePmEventsToChannelAutomations(events) fire-and-forget after each sync. The bridge checks both automationsEnabled and pmAutomationsEnabled, queries listEnabledPmEventAutomations() (channel automations with triggerType: 'on_pm_event'), matches events against each rule's PmEventConfig (event type + board scope + optional board/column filter), enforces a 5-second per-rule cooldown, deduplicates within a batch using bridge:-prefixed keys, and dispatches through dispatchActionChain() passing the BoardEvent as v2 trigger data so actions can read itemId/boardId from ctx.trigger. Errors are caught per-automation and never propagate to the sync pipeline.
Three v2 actions for PM-triggered automations:
pm.update-linked-status— updates a column value on the triggering item (readsitemIdfromctx.trigger; skips gracefully if no trigger context)pm.add-comment— adds a comment/update to the triggering item (same trigger skip behavior)pm.create-item— creates a new item on a specified board (does NOT require trigger context)
Four preset templates in the channel automation presets: Overdue Task Nudge (pm-overdue-nudge), Status Change Update (pm-status-changed-update), Comment on New Items (pm-new-item-comment, v2), Assignment Notification (pm-assignment-alert).
Architecture notes: the bridge is SEPARATE from the board automation engine (Phase 5C) — board automations use pm_board_automations table, channel bridge uses the automations table with pm_event_config column. The dispatchActionChain function accepts an optional v2TriggerData parameter that populates trigger on the v2 action context.
- Contract: pm-automation-contract.md (§ PM event channel bridge)
- Key files:
src/main/services/pm/pm-event-channel-bridge.ts(bridge),src/main/services/automation/v2/dispatcher.ts(v2TriggerData),src/main/services/automation/v2/actions/pm-update-linked-status.ts,pm-add-comment.ts,pm-create-item.ts(actions),src/main/services/automation/legacy/automation-presets.ts(presets),src/main/db/migrations/20260720203018-add-pm-event-config-to-automations.ts(migration)
Workflow Engine Nodes (Phase 5H)
Phase 5H integrates PM boards into the Workflow Engine with a poll-based trigger and five action nodes. The trigger watcher polls all synced boards every 60 seconds, computing deltas to fire workflows. The actions proxy writes through to the Mission Control backend via pmAuthedFetch.
Trigger node (trigger.pm_item): configurable event filter (item_status_changed, item_assigned, item_created, item_overdue), optional boardId/columnId scoping. First tick establishes a baseline (no false-fires on start). Dedup by pm-trigger:boardId:itemId:event:value. Kill switch: AMC_DISABLE_PM_WORKFLOW_TRIGGER.
Action nodes:
action.pm_create_item— create an item on a board (title, group, column values via JSON)action.pm_transition— set a column value (status transition)action.pm_comment— add an update/comment to an itemaction.pm_assign— assign a person to an item (writes the board's people column as{ids:[memberId]})action.pm_search— search items by name/text (reads from local SQLite mirror)
Architecture: nodes are auto-registered via Vite's import.meta.glob('./nodes/*-node.ts'). Side effects route through WorkflowEnginePorts (never raw DB/fetch from a node). 'pm' is added to WORKFLOW_TRIGGER_SOURCES and renders as "PM Board" in the run-history viewer.
- Contract: pm-workflow-nodes-contract.md
- Key files:
src/main/services/workflow-engine/pm-item-trigger.ts(watcher),src/main/services/workflow-engine/nodes/pm-*-node.ts(6 node files),src/main/services/workflow-engine/ports.ts(port implementations),src/main/services/workflow-engine/types.ts(port interface)
Related
- Mission Control — the overview page this continues.
- mc-automations.md — the automation engine on its own page.
- monday-cloud.md — the integration that connects a hosted board service instead.
Last verified 2026-10-30