Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: describe Normal mode and the approval gate
trohitga30bc4aeafd5
diff --git a/CLAUDE.md b/CLAUDE.mdindex 0f2de582..7afccd4f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -13,6 +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` 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, consumer Connectors), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` 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** (toggled by Dashboard's `visibilitychange` listener; 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). |@@ -740,7 +741,7 @@ Workflows execute via Temporal for durability and horizontal scaling, gated by `Execution routing falls back Temporal → sequential; the Temporal dev server + embedded worker are managed in-process under `server/services/temporal/` (pooch-downloaded CLI, single `temporal server start-dev` process, gRPC `TEMPORAL_FRONTEND_GRPC_PORT` + Web UI `TEMPORAL_UI_PORT`, SQLite at `~/.opencompany/temporal.db`). Full architecture, dispatch matrix, per-node + agent-loop lifecycle, the F4.B `agent.*` activities (unsuffixed since the AgentWorkflow fold; read the live set from `collect_agent_activities()` rather than a hardcoded count), heartbeat semantics, delegation input contract, the worker tuning recipe, and all `.env` tunables live in [docs-internal/TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md).-**Months-long durability contract (July 2026).** Running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. Load-bearing invariants: (1) `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` stays `false` (debug-only sweep; even enabled, any control row in the shared `WORKFLOW_CONTROL_ACTIVE_STATES` — including `resetting` — vetoes it). (2) New child workflow starts carry **no** `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so lifetime caps silently terminated paused runs; liveness comes from activity heartbeats (30s beat / 2min timeout), never from workflow lifetime caps. Removing/adding start options or retry policies on recorded commands requires a `workflow.patched(...)` guard (the only two live markers are `machina-conditional-edges-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py`). (3) Every long-lived workflow loop must continue-as-new under history pressure (`is_continue_as_new_suggested()` + a soft cap) — Temporal hard-terminates around ~51,200 history events; `WorkflowControlWorkflow` carries triggers/queued events/seen-ids/control state across rollovers, so controller handles are addressed **by workflow id only, never run_id-pinned**. (4) `dispatch.emit` skips controllers whose `ControlEventTypes` Search Attribute doesn't match the event (absent attribute = legacy match-all). (5) The Temporal lifecycle is owned by [services/temporal/lifecycle.py](./server/services/temporal/lifecycle.py) (`main.py` only schedules it): dev-server supervision + resident watchdog (`TEMPORAL_HEALTH_MONITOR_INTERVAL_SECONDS`), worker crash-restarts that REBUILD the single-use SDK `Worker` per attempt (manager + every pool queue worker), and the boot-time `reconcile_active_controls_on_boot` pass (converges crash-stranded `starting` rows, re-arms running/paused generations from the persisted graph snapshot). (6) **Recovery policies** (env-driven, defaults in `.env.template`; full semantics in [temporal-workflow-control.md → Recovery policies](./docs-internal/temporal-workflow-control.md)): `WORKFLOW_CONTROL_CRASH_RECOVERY=pause` — after a kill/crash (dirty-bit marker cleared only by graceful teardown) boot recovers running generations as **paused** so the user consciously resumes; `WORKFLOW_CONTROL_MISSING_CONTROLLER=pause` — a killed/vanished controller converges the generation to paused and **Resume rebuilds the controller** (`WorkflowIdConflictPolicy.USE_EXISTING`, re-arm from snapshot) instead of forcing a state-archiving Reset; `WORKFLOW_CONTROL_PAUSE_ON_FAILURE=true` — repeatedly-failing trigger-spawned runs pause their deployment via the `workflow_control.pause_on_failure` activity (circuit breaker; trips only after `WORKFLOW_CONTROL_PAUSE_ON_FAILURE_THRESHOLD` (default 3) failures inside a rolling `_WINDOW_SECONDS` (default 600) so one node hiccup never pauses anything; Resume resets the streak; manual canvas runs never qualify). Temporal's native Pause/Unpause (server 1.28+) is deliberately NOT used — no Python SDK surface, and it halts workflow-task dispatch so a natively-paused controller couldn't process the resume Update. (7) **Workflow-scoped event delivery**: an envelope whose `workflow_id` is set by its producer's call site reaches only that workflow's consumers (`dispatch.emit` narrows both Visibility clauses by `EventWorkflowId`); chat is the first scoped producer — the decision lives in `routers/websocket.py`, the narrowing in core dispatch, and plugin `_events.py` factories only plumb the field (see [event_framework.md](./docs-internal/event_framework.md)). (8) **Canvas editability is the server-owned `can_edit` capability** emitted by `serialize_control` (paused = editable; starting/running/transitional = locked); the FE renders it via `lib/canvasLock.ts` + Dashboard's `guardCanvasEdit` and never re-derives the rule from state strings (see [temporal-workflow-control.md → Canvas editability](./docs-internal/temporal-workflow-control.md)). Locked by `tests/temporal/test_durability_hardening.py` + `test_worker_restart.py`.+**Months-long durability contract (July 2026).** Running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. Load-bearing invariants: (1) `TEMPORAL_TERMINATE_RUNNING_ON_STARTUP` stays `false` (debug-only sweep; even enabled, any control row in the shared `WORKFLOW_CONTROL_ACTIVE_STATES` — including `resetting` — vetoes it). (2) New child workflow starts carry **no** `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so lifetime caps silently terminated paused runs; liveness comes from activity heartbeats (30s beat / 2min timeout), never from workflow lifetime caps. Removing/adding start options or retry policies on recorded commands requires a `workflow.patched(...)` guard (the live markers are `machina-conditional-edges-v1` and `machina-run-record-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py`; verify with `grep -rn "workflow.patched(" server/services/temporal`). (3) Every long-lived workflow loop must continue-as-new under history pressure (`is_continue_as_new_suggested()` + a soft cap) — Temporal hard-terminates around ~51,200 history events; `WorkflowControlWorkflow` carries triggers/queued events/seen-ids/control state across rollovers, so controller handles are addressed **by workflow id only, never run_id-pinned**. (4) `dispatch.emit` skips controllers whose `ControlEventTypes` Search Attribute doesn't match the event (absent attribute = legacy match-all). (5) The Temporal lifecycle is owned by [services/temporal/lifecycle.py](./server/services/temporal/lifecycle.py) (`main.py` only schedules it): dev-server supervision + resident watchdog (`TEMPORAL_HEALTH_MONITOR_INTERVAL_SECONDS`), worker crash-restarts that REBUILD the single-use SDK `Worker` per attempt (manager + every pool queue worker), and the boot-time `reconcile_active_controls_on_boot` pass (converges crash-stranded `starting` rows, re-arms running/paused generations from the persisted graph snapshot). (6) **Recovery policies** (env-driven, defaults in `.env.template`; full semantics in [temporal-workflow-control.md → Recovery policies](./docs-internal/temporal-workflow-control.md)): `WORKFLOW_CONTROL_CRASH_RECOVERY=pause` — after a kill/crash (dirty-bit marker cleared only by graceful teardown) boot recovers running generations as **paused** so the user consciously resumes; `WORKFLOW_CONTROL_MISSING_CONTROLLER=pause` — a killed/vanished controller converges the generation to paused and **Resume rebuilds the controller** (`WorkflowIdConflictPolicy.USE_EXISTING`, re-arm from snapshot) instead of forcing a state-archiving Reset; `WORKFLOW_CONTROL_PAUSE_ON_FAILURE=true` — repeatedly-failing trigger-spawned runs pause their deployment via the `workflow_control.pause_on_failure` activity (circuit breaker; trips only after `WORKFLOW_CONTROL_PAUSE_ON_FAILURE_THRESHOLD` (default 3) failures inside a rolling `_WINDOW_SECONDS` (default 600) so one node hiccup never pauses anything; Resume resets the streak; manual canvas runs never qualify). Temporal's native Pause/Unpause (server 1.28+) is deliberately NOT used — no Python SDK surface, and it halts workflow-task dispatch so a natively-paused controller couldn't process the resume Update. (7) **Workflow-scoped event delivery**: an envelope whose `workflow_id` is set by its producer's call site reaches only that workflow's consumers (`dispatch.emit` narrows both Visibility clauses by `EventWorkflowId`); chat is the first scoped producer — the decision lives in `routers/websocket.py`, the narrowing in core dispatch, and plugin `_events.py` factories only plumb the field (see [event_framework.md](./docs-internal/event_framework.md)). (8) **Canvas editability is the server-owned `can_edit` capability** emitted by `serialize_control` (paused = editable; starting/running/transitional = locked); the FE renders it via `lib/canvasLock.ts` + Dashboard's `guardCanvasEdit` and never re-derives the rule from state strings (see [temporal-workflow-control.md → Canvas editability](./docs-internal/temporal-workflow-control.md)). Locked by `tests/temporal/test_durability_hardening.py` + `test_worker_restart.py`.**Temporal tracing ownership is strict.** Register the SDK `TracingInterceptor` exactly once on the shared `Client.connect(...)`; the Python SDK automatically prepends compatible client interceptors to every worker. Never repeat `TracingInterceptor` in `Worker(..., interceptors=...)`. Worker lists contain the distinct `ObservabilityWorkerInterceptor` and plugin-specific worker interceptors only. Exact paired `StartActivity` / `RunActivity` / `CompleteWorkflow` console spans with identical Temporal identities indicate duplicate instrumentation, not duplicate execution; use Temporal Event History and the `node.<type>.execute` application span to verify actual attempts. See the tracing and debugging sections in [TEMPORAL_ARCHITECTURE.md](./docs-internal/TEMPORAL_ARCHITECTURE.md) and [errors.md](./docs-internal/errors.md).@@ -1355,7 +1356,7 @@ if "examples_loaded" not in columns:## Onboarding Service-Multi-step welcome wizard shown on first launch — database-backed (`UserSettings.onboarding_completed` + `onboarding_step`), skippable, resumable, replayable from Settings, and auto-skipped for existing users (migration sets `onboarding_completed=1` where `examples_loaded=1`). Built with shadcn primitives (no antd). Full step list, key files, replay flow, and how to add a step are in **[Onboarding Service](./docs-internal/onboarding.md)**.+Multi-step welcome wizard shown on first launch of the workflow editor (it lives in `Dashboard.tsx`, so with Normal mode on it first appears when Dev mode opens) — database-backed (`UserSettings.onboarding_completed` + `onboarding_step`), skippable, resumable, replayable from Settings, and auto-skipped for existing users (migration sets `onboarding_completed=1` where `examples_loaded=1`). Built with shadcn primitives (no antd). Full step list, key files, replay flow, and how to add a step are in **[Onboarding Service](./docs-internal/onboarding.md)**.## AI Chat Model Development Guide@@ -2491,6 +2492,8 @@ 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`, `generate_employee_setup`, `cancel_employee_setup`, `hire_employee`, `start_employee` (see [normal_mode.md](./docs-internal/normal_mode.md)) |+| **Approvals** | `list_approvals`, `decide_approval` (the `approvalGate` node's drafts) |#### Broadcast Messages (Server -> All Clients)| Message Type | Description |@@ -2500,6 +2503,9 @@ Updated `client_left` and presence handlers use `has_real_android_devices()` ins| `node_output` | Node execution output data || `agent_progress` | CloudEvents v1.0 envelope (type=`com.opencompany.agent.progress`) — per-step agent-loop iteration count, drives the live "N / max" badge on AI Agent canvas nodes || `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` |+| `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 || `workflow_status` | Workflow execution progress |diff --git a/README.md b/README.mdindex 01619193..ceadb90b 100644--- a/README.md+++ b/README.md@@ -75,10 +75,10 @@ https://github.com/user-attachments/assets/3d25e9a3-f7b9-4760-8b9a-6de1e5a19cad[](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/how-it-works.svg)-1. **Hire.** Drop an AI Employee onto the canvas. That is the lead.-2. **Build the team.** Connect a few specialist agents to it and give each one the tools for its part of the job: email, browser, code, messaging, payments, and so on.-3. **Start.** The team runs in the background and wakes up when something happens: a new email, a customer message, a scheduled time.-4. **Review.** Watch it work on the canvas, read what it remembers, and change how it does things by editing its skills in plain text.+1. **Hire.** Describe the job in plain words on the Home screen. OpenCompany drafts the new employee's setup (the apps it uses, when it works, what it checks with you first); adjust it and press Hire. Or switch to Dev mode and drop an AI Employee onto the canvas.+2. **Build the team.** In Dev mode, connect a few specialist agents to it and give each one the tools for its part of the job: email, browser, code, messaging, payments, and so on.+3. **Start.** The team runs in the background and wakes up when something happens: a new email, a customer message, a scheduled time. If you ask it to, it shows you each reply to approve before it goes out.+4. **Review.** Watch it work from its card on Home or on the canvas, read what it remembers, and change how it does things by editing its skills in plain text.[](https://raw.githubusercontent.com/zeenie-ai/OpenCompany/main/docs/diagrams/default-workflows.svg)@@ -120,7 +120,7 @@ Nothing here is a black box. What an employee learns lives in its memory, its no- **Models** from OpenAI, Anthropic, Google, xAI, DeepSeek, Kimi, Mistral, Groq, Cerebras, Sarvam, and OpenRouter, or run local models with Ollama and LM Studio for free.- **Speech and translation**, so employees can listen, talk, and work in other languages.- **78 skills** that ship ready to use, and a place to drop your own.-- **Built to keep running.** Employees survive restarts, pause and resume from the canvas, and catch up on missed schedules. Your API keys are stored encrypted on your machine. Add a login for shared or cloud use; one command deploys to Google Cloud.+- **Built to keep running.** Employees survive restarts, pause and resume from Home or the canvas, and catch up on missed schedules. Your API keys are stored encrypted on your machine. Add a login for shared or cloud use; one command deploys to Google Cloud.- **A canvas you will want to look at**, with 12 visual themes.## For Developersdiff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.mdindex ac655fde..a1195acd 100644--- a/docs-internal/TEMPORAL_ARCHITECTURE.md+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md@@ -654,7 +654,7 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa**Months-long durability contract**: running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. Mechanisms, each replay-patch-guarded where it changes recorded commands:-- **No lifetime caps on new child runs.** Trigger/cron-spawned `MachinaWorkflow` runs, agent children, and delegated-task runners previously carried 1-2h `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so any pause longer than the cap silently terminated the run (and a timed-out delegated runner skipped its compensation: leaked permit + stuck task row). New executions start children unbounded (no patch marker was retained for this change; the only live `workflow.patched` markers in the tree are `machina-conditional-edges-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py` — verify with `grep -rn "workflow.patched(" server/services/temporal`). Liveness is the activity layer's job: node activities heartbeat every 30s against a 2-minute `heartbeat_timeout`; their `start_to_close` is a generous 24h ceiling, not 10 minutes. The subagent-permit wait uses `PERMIT_WAIT_RETRY` (unlimited attempts) so a queued delegation waits as long as admission takes instead of failing after ~3h.+- **No lifetime caps on new child runs.** Trigger/cron-spawned `MachinaWorkflow` runs, agent children, and delegated-task runners previously carried 1-2h `execution_timeout`/`run_timeout` — Temporal's timeout timers keep ticking through a cooperative pause, so any pause longer than the cap silently terminated the run (and a timed-out delegated runner skipped its compensation: leaked permit + stuck task row). New executions start children unbounded (no patch marker was retained for this change; the live `workflow.patched` markers in the tree are `machina-conditional-edges-v1` and `machina-run-record-v1` in `services/temporal/workflow.py` and `machina-trigger-listener-node-filter` in `services/temporal/trigger_listener_workflow.py` — verify with `grep -rn "workflow.patched(" server/services/temporal`. `machina-run-record-v1` gates the `workflow_runs.record_completion` activity that trigger-spawned runs schedule when they finish, for Normal mode's "done today"; see [normal_mode.md](./normal_mode.md#done-today)). Liveness is the activity layer's job: node activities heartbeat every 30s against a 2-minute `heartbeat_timeout`; their `start_to_close` is a generous 24h ceiling, not 10 minutes. The subagent-permit wait uses `PERMIT_WAIT_RETRY` (unlimited attempts) so a queued delegation waits as long as admission takes instead of failing after ~3h.- **History-pressure continue-as-new everywhere.** Temporal terminates any workflow around ~51,200 history events. `WorkflowControlWorkflow` (which multiplexes all of a deployment's triggers into one history) now rolls over on `is_continue_as_new_suggested()` / a 10K-event soft cap, carrying trigger specs, per-trigger provider `seen_ids` (written back into the spec after every poll cycle), queued push events, the bounded dedup baseline, and the control state — a rollover works mid-pause too, since a paused controller still accretes signal history. `TriggerListenerWorkflow`/`PollingTriggerWorkflow` gained the same pressure check (the old `_processed_count >= 16_000` gate was unreachable: real spawns cost ~15-25 events each, and polling counted only emitted events while a quiet mailbox burned ~11 events/cycle — dead in ~3 days at the 60s default). Poll intervals are clamped to a 30s floor on the patched path. Because run ids change on rollover, **controller handles are addressed by workflow id only, never run_id-pinned** (`_controller_handle`, manager `register_trigger`).- **dispatch.emit controller narrowing.** Controllers advertise their push event types via the `ControlEventTypes` keyword-list Search Attribute (upserted as triggers register); `dispatch.emit` skips controllers with no matching trigger instead of signalling every running controller with every platform event (each unmatched signal was ~4 immutable history events — one busy deployment burned every other controller's rollover budget). Controllers without the attribute (pre-upgrade histories) keep match-all behaviour.- **Boot-time reconcile** (`reconcile_active_controls_on_boot`, called from the lifecycle module after workers start): runs the lazy `_reconcile_control` over every active control row, converges `starting` rows a crash left behind (controller alive with triggers registered → `running`; alive-but-empty for a graph that declares triggers → `failed` + controller closed; vanished → `failed`), and re-arms the process-local half of running/paused generations from the persisted graph snapshot — DeploymentManager state, in-process collectors for non-canary trigger types, cron pause posture. Idempotent by construction (controller `register_trigger` keyed by listener id, legacy starts use `USE_EXISTING`, cron creation preserves server-owned pause state).diff --git a/docs-internal/design-system/components/canvas/ModeToggle.prompt.md b/docs-internal/design-system/components/canvas/ModeToggle.prompt.mdindex 6f2aa1b6..22651287 100644--- a/docs-internal/design-system/components/canvas/ModeToggle.prompt.md+++ b/docs-internal/design-system/components/canvas/ModeToggle.prompt.md@@ -1,4 +1,4 @@-Normal/Dev segmented toggle from the toolbar (Normal = AI components only; Dev = everything).+Normal/Dev segmented toggle from the toolbar and the Home header: switches between Normal mode (Home) and Dev mode (the workflow editor). With Normal mode turned off (`VITE_NORMAL_MODE=false`) it filters the palette instead (Normal = AI components only; Dev = everything). The app's version is `client/src/components/shell/ModeToggle.tsx`.```jsxconst [mode, setMode] = React.useState('normal');diff --git a/docs-internal/event_framework.md b/docs-internal/event_framework.mdindex aef2dd2f..f6ebee27 100644--- a/docs-internal/event_framework.md+++ b/docs-internal/event_framework.md@@ -242,7 +242,11 @@ query is guaranteed to match nothing — once per save/mutation. They call`get_status_broadcaster().broadcast({...})` directly instead, which is the samepattern `nodes/telegram/_events.py` uses for status. The CloudEvents envelope,`source`, `type`, `subject` and `data` are identical either way, so the wire-contract the frontend sees does not change.+contract the frontend sees does not change. Normal mode's two events follow+the same rule: `employee_lifecycle` (`com.opencompany.employee.*`, in+`services/employees/events.py`) and `approval_lifecycle`+(`com.opencompany.approval.*`, in `nodes/workflow/approval_gate/_events.py`,+identity only). See [normal_mode.md](./normal_mode.md#wire-contract).Rule of thumb: **if no `register_canary_trigger_type` call names your eventtype, broadcast it directly.** Reach for `emit` only when a Temporal workflowdiff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.mdindex 99f9b403..ef3338e6 100644--- a/docs-internal/frontend_architecture.md+++ b/docs-internal/frontend_architecture.md@@ -11,7 +11,8 @@ Post-migration (2026-04-14). Single source of truth for the current frontend.- **shadcn/ui** via the canonical CLI (`bun x shadcn@latest add` — bun's `npx` equivalent; npm is not part of the toolchain). All primitives live under [client/src/components/ui/](../client/src/components/ui/) as first-class repo files we can edit.- **Radix UI** is the primitive engine shadcn uses (Dialog, Accordion, Select, Switch, Tabs, Tooltip, Popover, Dropdown, AlertDialog, Collapsible, Progress, Slider, Label, Checkbox).- **Forms**: react-hook-form + zod via shadcn's `Form` composition. Per-form schemas live colocated with the form (e.g. `credentials/panels/schemas/email.ts`); tiny forms use inline zod.-- **Toasts**: `sonner` imported directly at call-sites. The shadcn `<Toaster />` wrapper (at [components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx)) is patched to read our `ThemeContext` instead of `next-themes`.+- **Toasts**: `sonner` imported directly at call-sites. The shadcn `<Toaster />` wrapper (at [components/ui/sonner.tsx](../client/src/components/ui/sonner.tsx)) is patched to read our `ThemeContext` instead of `next-themes`. Normal mode has a second toaster, one bottom-centre pill at a time (`pillToast()` in [features/home/ui/pillToast.tsx](../client/src/features/home/ui/pillToast.tsx)).+- **Two screens**: Normal mode (Home, [features/home/](../client/src/features/home/)) and Dev mode (the workflow editor, `Dashboard.tsx`), both lazy chunks switched by the app shell in [app/](../client/src/app/). See [Normal Mode](./normal_mode.md).- **State**: TanStack Query for server state, Zustand for UI-only state, plain `useState`/`useReducer` for local. No global redux store.- **WebSocket realtime** via `WebSocketContext`; chat/node/workflow events are push-based, never polled.- **antd is gone.** `styled-components` is gone. `@ant-design/icons` is gone. Icons come from `lucide-react`.@@ -50,11 +51,25 @@ Not present (intentionally): antd, `@ant-design/icons`, styled-components, emoti```client/src/-├── App.tsx # Root: syncs ThemeContext -> <html data-theme>/class, mounts Toaster-├── main.tsx # Providers (QueryClient, Theme, Auth, WebSocket) + renders <App/>-├── Dashboard.tsx # Canvas workspace (React Flow + top-level panels)+├── App.tsx # Root: SVG filter defs, ProtectedRoute -> AppShell, both Toasters+├── main.tsx # Providers (QueryClient, ShellThemeProvider, Auth, WebSocket) + renders <App/>+├── Dashboard.tsx # Dev mode: canvas workspace (React Flow + top-level panels), a lazy chunk├── ParameterPanel.tsx # Per-node inspector (Phase 6 will schema-drive this)│+├── app/ # The shell around both screens+│ ├── AppShell.tsx # .app-frame, boot effects, Settings / Credentials dialogs+│ ├── ShellModeSwitch.tsx # Lazy Home / editor screens + preloadHome / preloadEditor+│ ├── ShellThemeProvider.tsx # ThemeProvider with baseOnly while Home shows+│ ├── useShellActions.ts # enterNormal / enterDev (the only way to switch)+│ ├── shellTransition.ts # The fade-out / swap choreography+│ └── useModeShortcut.ts / useCurrentWorkflowSync.ts / usePageActivitySync.ts / useUIDefaultsOnce.ts+│+├── features/home/ # Normal mode (see docs-internal/normal_mode.md)+│ ├── HomeShell.tsx # Sidebar + header + current view + Settings + orb stage+│ ├── sidebar/ header/ hire/ employee/ settings/ approvals/ data/ state/ ui/+│ ├── genui/ # Setup-screen pipeline; only its index.ts is importable (ESLint)+│ └── orb/ # orb.ts (state + lifecycle), orbEngine.ts (three.js, own chunk)+│├── index.css # Tailwind v4 @import + @theme inline tokens + RF/scrollbar chrome│├── components/@@ -123,13 +138,15 @@ client/src/│ │ └── steps/ # WelcomeStep / HowItWorksStep / ConnectAIStep / TryItStep│ ││ ├── icons/ # AI provider icons (SVG data URIs)+│ ├── brand/Logo.tsx # OcMark / OcWordmark / OcLogo (inline SVG, --lg-* palette, intro + pulse)+│ ├── shell/ModeToggle.tsx # The Normal / Dev switch (editor toolbar + Home header)│ ├── auth/ # Login page + protected route│ ├── SquareNode.tsx, StartNode.tsx, TriggerNode.tsx, AIAgentNode.tsx, ToolkitNode.tsx, TeamMonitorNode.tsx│ │ # React Flow nodes with lucide icons│ └── APIKeyValidator.tsx # Shadcn Input + Button + Tooltip composition│├── contexts/-│ ├── ThemeContext.tsx # isDarkMode + toggleTheme+│ ├── ThemeContext.tsx # theme (on the page) / chosenTheme, setTheme with the circular reveal, baseOnly│ ├── AuthContext.tsx # JWT user state│ └── WebSocketContext.tsx # Single source of truth for WS state + handlers│@@ -148,7 +165,7 @@ client/src/│ └── useCopyPaste.ts / useRename.ts│├── store/-│ ├── useAppStore.ts # UI state (sidebar, palette, pro mode, persisted)+│ ├── useAppStore.ts # UI state (sidebar, palette, shellMode, pro mode, persisted)│ └── useCredentialRegistry.ts # UI-only: selectedId + paletteOpen + query│├── styles/@@ -181,11 +198,18 @@ client/src/│ ├── workflowOps.ts # applyOperations for backend workflow-ops batches│ ├── canvasLock.ts # Server-owned can_edit capability -> canvas lock│ ├── sound.ts # WebAudio sound engine (10 packs)+│ ├── motion.ts # The one place Web Animations start: --dur-* / --ease-* tokens,+│ │ # 1 ms under reduced motion or a hidden page, no loops then+│ ├── pageActivity.ts / useReducedMotion.ts # Whether anyone can see the page; the motion preference+│ ├── debouncedInvalidate.ts # Trailing-edge query invalidation (broadcast bursts)│ └── utils.ts # cn() = clsx + tailwind-merge (shadcn convention)├── schemas/workflowSchema.ts # Structural pre-flight for workflow export (backend is the schema authority)├── stores/│ ├── nodeStatusStore.ts # Per-workflow node statuses (slice-subscribed Zustand)-│ └── canvasDockStore.ts # Docked Canvas sidebar state+│ ├── canvasDockStore.ts # Docked Canvas sidebar state+│ ├── workflowControlStore.ts # Mirror of workflow control statuses for Home (written from WebSocketContext)+│ ├── shellDialogsStore.ts # Settings / Credentials dialog flags (lifted out of Dashboard)+│ └── workflowSettingsStore.ts # Editor settings (auto-save etc.) read by the shell├── test/ # Vitest setup.ts, builders.ts, providers.tsx, README.md├── themes/ # base.css + animations.css + 12 per-theme CSS files├── types/ # INodeProperties, NodeTypes, etc.@@ -475,7 +499,7 @@ This is the rule that keeps the data layer schema-driven instead of imperatively| Owns | What goes here | Examples ||---|---|---|| **TanStack Query** | Anything the server has authoritative state for. List / single-record / settings reads. Mutations that change server state. | `useWorkflowsQuery`, `useNodeParamsQuery`, `useUserSettingsQuery`, `useCatalogueQuery`, `useSaveWorkflowMutation`, `useSaveNodeParamsMutation`, `useSaveUserSettingsMutation` |-| **Zustand** | UI-only state that survives navigation. The active edit buffer for the current workflow. Sidebar/panel visibility flags. | `useAppStore.currentWorkflow` (mutable buffer), `sidebarVisible`, `proMode`, `renamingNodeId`, `useCredentialRegistry.selectedId` |+| **Zustand** | UI-only state that survives navigation. The active edit buffer for the current workflow. Sidebar/panel visibility flags. | `useAppStore.currentWorkflow` (mutable buffer), `sidebarVisible`, `shellMode`, `proMode`, `renamingNodeId`, `useCredentialRegistry.selectedId`, Home's `useHomeStore` || **`useState` / `useReducer`** | Per-component transient state. Form-field drafts. Hover/focus. | text-input drafts, dropdown-open, inline-edit toggles || **`WebSocketContext`** | Raw WS connection, `sendRequest`, push-only broadcast slices (workflow progress, android/whatsapp/twitter status, console/terminal logs). The provider value is `useMemo`'d so unrelated state changes do not re-render every consumer. Exposes `isConnected` (socket open) and `isReady` (open + pending-send queue drained); gate catalogue/spec queries on `isReady`. `drainPendingSends(ws)` runs synchronously, then `setIsReady(true)` fires immediately; terminal/chat/console history restore is fire-and-forget in the background (Wave 32 removed the init-burst gate and the hardcoded `probeApiKey` loop). Catalogue invalidation routes through `invalidateCatalogue(queryClient)` ([`hooks/useCatalogueQuery.ts`](../client/src/hooks/useCatalogueQuery.ts)) which debounces the refetch on a 300 ms trailing edge, so an oauth burst or multi-service reconnect collapses to one refetch instead of N. | `androidStatus`, `consoleLogs`, broadcast streams || **`stores/nodeStatusStore.ts`** (Zustand) | Per-workflow node-execution statuses -- moved out of WebSocketContext so a status tick does not cascade through the React tree. `useNodeStatus(id)` is a slice selector; only the affected node's consumers re-render. Mirror this pattern for any new high-frequency push state. | `allStatuses[workflowId][nodeId]`, `currentWorkflowId` |diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.mdindex 24e5a7db..c008d78d 100644--- a/docs-internal/node-logic-flows/README.md+++ b/docs-internal/node-logic-flows/README.md@@ -242,6 +242,7 @@ match its doc here, and each doc must still describe what the code does.### workflow_triggers+- [Approval (`approvalGate`)](./workflow_triggers/approvalGate.md)- [Chat Trigger (`chatTrigger`)](./workflow_triggers/chatTrigger.md)- [Cron Scheduler (`cronScheduler`)](./workflow_triggers/cronScheduler.md)- [Start (`start`)](./workflow_triggers/start.md)diff --git a/docs-internal/node-logic-flows/workflow_triggers/approvalGate.md b/docs-internal/node-logic-flows/workflow_triggers/approvalGate.mdnew file mode 100644index 00000000..5f022860--- /dev/null+++ b/docs-internal/node-logic-flows/workflow_triggers/approvalGate.md@@ -0,0 +1,158 @@+# Approval (`approvalGate`)++| Field | Value |+|------|-------|+| **Category** | workflow |+| **Backend handler** | [`server/nodes/workflow/approval_gate/__init__.py`](../../../server/nodes/workflow/approval_gate/__init__.py) - `ApprovalGateNode`; dispatched via `BaseNode.execute()` + the `@Operation("request")` method |+| **Tests** | [`server/tests/services/approvals/test_approval_gate.py`](../../../server/tests/services/approvals/test_approval_gate.py) |+| **Skill (if any)** | none |+| **Dual-purpose tool** | no - `usable_as_tool = False`, so no agent can approve its own draft |++## Purpose++Holds a draft until the owner sends or discards it. A Normal-mode employee+with "Ask me before sending anything" on answers through+`agent -> approvalGate -> reply`: the gate records the agent's draft (who it+goes to, what it says), shows it on the employee's card in Home, and waits.+Send lets the draft, or the owner's edit of it, through to the reply node;+Discard, expiry or a Reset lets nothing through. Hire builds this wiring+(`services/employees/builder.py`); the node is also usable by hand in the+editor. Feature overview: [Normal mode](../../normal_mode.md).++## Inputs (handles)++| Handle | Connection type | Required | Purpose |+|--------|-----------------|----------|---------|+| `input-main` | main | yes | The agent's reply (drives the `draft` template) and the trigger's data (the recipient) |++## Parameters++| Name | Type | Default | Required | displayOptions.show | Description |+|------|------|---------|----------|---------------------|-------------|+| `channel` | string | `""` | no | - | The app the reply goes out through (shown on the card) |+| `recipient` | string | `""` | no | - | Who the reply goes to, from the trigger (ints such as Telegram chat ids are coerced) |+| `recipient_label` | string | `""` | no | - | How the card names the recipient |+| `subject` | string | `""` | no | - | Subject line, for email |+| `draft` | string | `""` | no | - | The message waiting for approval (capped at 20,000 characters) |+| `context_excerpt` | string | `""` | no | - | The message being answered, shown above the draft (capped at 2,000) |+| `max_length` | int | `20000` | no | - | Longest edit the channel accepts (1-20,000) |+| `timeout_hours` | int | `168` | no | - | Hours before the draft expires (1-720) |++## Outputs (handles)++| Handle | Shape | Description |+|--------|-------|-------------|+| `output-main` | object | The decision (see below); fails closed |++### Output payload (TypeScript shape)++```ts+{+ approved: boolean;+ status: 'approved' | 'discarded' | 'expired' | 'cancelled' | 'skipped';+ skipped: boolean;+ text: string; // the sent text (the edit if there was one); "" unless approved+ subject: string; // "" unless approved+ recipient: string; // "" unless approved+ recipient_label: string; // "" unless approved+ approval_id: string | null;+ edited: boolean;+}+```++The reply node reads `{{<gate label>.text}}` and `{{<gate label>.recipient}}`,+and its incoming edge carries `{"field": "result.approved", "operator": "is_true"}`+(`services/approvals/contract.py::approved_edge_condition`), so nothing is sent+unless the owner approved. The recipient always comes from the run's trigger,+never from the agent's text.++## Logic Flow++```mermaid+flowchart TD+ A[Receive params] --> B{draft empty or NO_REPLY?}+ B -- yes --> S[Return skipped, no row]+ B -- no --> C[Idempotency key: activity identity on Temporal, execution + node + inputs fingerprint in-process]+ C --> D[get_or_create approval_requests row]+ D -- created --> E[Broadcast approval_lifecycle requested]+ D --> F{row pending?}+ E --> F+ F -- no --> O[Return the outcome]+ F -- yes --> G[Show node status waiting]+ G --> H{expired?}+ H -- yes --> X[Settle expired, broadcast] --> O+ H -- no --> I{worker shutting down?}+ I -- yes --> W[Raise NodeWaitInterrupted: Temporal retries the attempt]+ I -- no --> J[Wait for a notification or POLL_SECONDS, re-read the row] --> F+```++## Decision Logic++- **Validation**: parameters are coerced and capped by the Params validators;+ `extra="ignore"`.+- **Branches**: an empty draft, or exactly `NO_REPLY`, returns+ `status: "skipped"` and creates no row. The agent answers `NO_REPLY` when+ nothing should go out; the gate's own incoming edge also carries+ `result.response != NO_REPLY`.+- **Identity**: `t:{workflow_id}:{run_id}:{activity_id}` inside a Temporal+ activity, so a retry after a restart re-attaches to the same draft;+ `p:{execution}:{node}:{sha256(outputs)[:16]}` in-process, where one+ execution id can span several runs of a deployment.+- **Waiting**: a process-local waiter (`services/approvals/waiter.py`) wakes+ the gate the moment `decide_approval` settles the row; it also re-reads+ the row every `POLL_SECONDS` (10) to see decisions made in another process+ and expiry.+- **Error paths**: a worker shutting down mid-wait raises `NodeWaitInterrupted`,+ which `BaseNode.as_activity` turns into a retryable `ApplicationError`. On+ the in-process path there is no retry, and the run fails as for any error.++## Side Effects++- **Database writes**: one `approval_requests` row per draft+ ([`server/models/approvals.py`](../../../server/models/approvals.py)): the+ recipient, draft, final text, status, revision and expiry. Decisions are+ compare-and-swap on `revision`.+- **Broadcasts**: `approval_lifecycle` (CloudEvents type+ `com.opencompany.approval.{requested|decided|expired|cancelled}`, subject =+ approval id). Identity only, never the message body or the recipient; the+ card refetches through `list_approvals`. Node status `waiting` while it waits.+- **External API calls**: none.+- **File I/O**: none.+- **Subprocess**: none.++## External Dependencies++- **Credentials**: none.+- **Services**: the approvals package+ ([`server/services/approvals/`](../../../server/services/approvals/)):+ store, waiter, listeners, reconcile, queries, contract.+- **Python packages**: `temporalio` (activity identity and worker shutdown).+- **Environment variables**: none.++## Edge cases & known limits++- Runs on `TaskQueue.TRIGGERS_EVENT` with a 24-hour `start_to_close` and+ unlimited retries (`maximum_attempts=0`); expiry, not the retry policy,+ ends a wait. Each waiting draft holds one slot on that queue's worker.+- A Reset cancels the workflow's pending drafts (`reset_execution_state`), and+ deleting the workflow removes its rows (workflow-deleted hook).+- Rows left pending by a crashed process are cancelled by+ `reconcile_once`, which `list_approvals` runs: local rows created before+ this process started, and Temporal rows whose generation is no longer live.+- Deciding while the employee is paused is allowed; the response carries+ `will_send_on_resume: true` and the card says so.++## Related++- **WebSocket handlers**+ ([`_handlers.py`](../../../server/nodes/workflow/approval_gate/_handlers.py)):+ `list_approvals {workflow_id?, status?, limit <= 100}` returns the owner's+ drafts, per-workflow pending counts and `server_time`;+ `decide_approval {approval_id, decision: "send" | "discard", text?, subject?, decision_key}`+ is idempotent per `decision_key` and validates edits against `max_length`.+ Errors: `already_decided`, `expired`, `cancelled`, `not_found`, `invalid_request`.+- **Other nodes that consume this output**: the reply node of the app that+ received the message (`whatsappSend`, `telegramSend`, `discordSend`,+ `googleGmail`, `msMail`, `whatsappBusinessSend`).+- **Architecture docs**: [Normal mode](../../normal_mode.md),+ [Plugin System](../../plugin_system.md).diff --git a/docs-internal/node_allowlist.md b/docs-internal/node_allowlist.mdindex ece31687..1cf4c889 100644--- a/docs-internal/node_allowlist.md+++ b/docs-internal/node_allowlist.md@@ -101,7 +101,8 @@ Read via `services.node_allowlist.get_node_allowlist_service().get_config()` —| File | Filter ||---|---|-| `client/src/components/ui/ComponentPalette.tsx` | `if (isBlocked(name, groups)) return false; if (!proMode && !isAllowed(name)) return false;` |+| `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)` || `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.mdnew file mode 100644index 00000000..6d4b060b--- /dev/null+++ b/docs-internal/normal_mode.md@@ -0,0 +1,259 @@+# Normal mode ("Home")++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.++**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+up in Home too, with details derived from their graph.++| Layer | Where |+|---|---|+| Shell (screen switch, mode toggle, theme rule) | [client/src/app/](../client/src/app/), [components/shell/ModeToggle.tsx](../client/src/components/shell/ModeToggle.tsx) |+| Home UI | [client/src/features/home/](../client/src/features/home/) |+| 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) |++The design reference is the `design_handoff_opencompany_home/` bundle (kept+out of git). Where its token values differ from the repo's, the repo wins.++## Switching screens++- **Flag**: `featureFlags.normalMode` ([lib/featureFlags.ts](../client/src/lib/featureFlags.ts))+ is on by default; `VITE_NORMAL_MODE=false` turns Home off. The app then+ opens straight into the editor, and the toolbar's Normal/Dev switch goes back+ to filtering the component palette.+- **State**: `useAppStore.shellMode` (`'normal' | 'dev'`), persisted as+ `ui_shell_mode`. While that key is unset it comes from the old palette+ choice: `ui_pro_mode === 'true'` starts in Dev.+- **Switching** goes through `enterNormal` / `enterDev` in+ [app/useShellActions.ts](../client/src/app/useShellActions.ts), never+ `setShellMode` directly. `enterDev({workflowId})` settles unsaved editor work+ first (saves it when auto-save is on, asks otherwise), opens the workflow and+ preloads the editor chunk; `enterNormal` preloads Home. Then+ [app/shellTransition.ts](../client/src/app/shellTransition.ts) fades the+ current screen out and swaps. Requests during a switch coalesce. The toggle+ lives in the editor toolbar and the Home header; Ctrl/Cmd+Shift+D toggles too.+- **Screens are lazy chunks** ([app/ShellModeSwitch.tsx](../client/src/app/ShellModeSwitch.tsx)),+ so ReactFlow stays out of a Normal-mode session and Home out of a Dev one.+- **App-level concerns** live in [app/AppShell.tsx](../client/src/app/AppShell.tsx)+ rather than in `Dashboard`: the `.app-frame`, boot effects (current workflow,+ sound sync, page activity, UI defaults, the shortcut), and the Settings and+ Credentials dialogs.+- **Themes**: Home shows only light and dark.+ [app/ShellThemeProvider.tsx](../client/src/app/ShellThemeProvider.tsx) passes+ `baseOnly` to `ThemeProvider` while Home is showing, so a stylized theme+ chosen in the editor appears as its family's base (Atomic as light, Cyber as+ dark) and applies again in Dev mode. See [Theme System](./theme_system.md).++## The Home screen++[features/home/](../client/src/features/home/):++| Folder | Contents |+|---|---|+| `HomeShell.tsx` | Sidebar, header, the current view (hire or one employee), Settings, the connect dialog, the orb's stage |+| `sidebar/`, `header/` | The team list, New employee, the profile row; the view title, mode toggle and theme button |+| `hire/` | The hero, the composer, starter jobs |+| `genui/` | The setup draft under the composer (below) |+| `employee/` | One employee's card: status, the current task, apps, "done today", Start / Pause / Resume, the drafts waiting for the owner |+| `settings/` | Profile and Connectors, 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 |+| `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, 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+shows as "Needs you". Motion goes through [lib/motion.ts](../client/src/lib/motion.ts),+which reads the `--dur-*` / `--ease-*` tokens, runs at 1 ms under reduced+motion and while the page is hidden ([lib/pageActivity.ts](../client/src/lib/pageActivity.ts)),+and never starts loops then. Toasts are a second sonner toaster+(`ui/pillToast.tsx`): one bottom-centre pill at a time.++### The orb++A 3D version of the logo drawn behind Home's content+([orb/orbEngine.ts](../client/src/features/home/orb/orbEngine.ts), a port of+the design prototype's scene on current three.js; loaded in its own chunk the+first time it runs). [orb/orb.ts](../client/src/features/home/orb/orb.ts) holds+what the engine reads each frame (the slot to fill, an energy target, a spike)+and its lifecycle: leaving Home keeps the renderer, the app shell disposes it.+`OrbStage` is the canvas host below the header; each view's `OrbSlot` reserves+the square the orb glides into. The composer sets the energy target (focused,+holding text, a setup being written); a hire, a theme or mode switch, a connect+and a task change spike it. Without WebGL, under reduced motion, or after a+lost WebGL context, the slot shows the static mark.++## Hiring++### 1. The setup screen++`generate_employee_setup {job, refine?, history?, draft_token}`+([services/employees/setup.py](../server/services/employees/setup.py)):++- **The server builds every message** ([setup_prompt.py](../server/services/employees/setup_prompt.py)):+ a preamble, the component catalogue, and a context block+ ([context.py](../server/services/employees/context.py)) with the connected+ and connectable apps, the team's names, the owner profile, the local time and+ whether an AI model is set up. A change request carries the latest reply+ plus at most two earlier turns, within a character budget.+- **Model choice** ([llm.py](../server/services/employees/llm.py)): a local+ provider when the owner prefers local AI, else the global default provider+ when it has a key, else the first usable provider, else the first saved+ endpoint. Calls go through `ChatUnifier` with a deadline (longer for local+ models). One retry when the reply was cut off or cannot be salvaged. Usage is+ recorded for every call.+- **One request in flight per owner**: a newer `draft_token` cancels the older+ 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`.++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+[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+same way on both sides. Only what `genui/index.ts` exports (`HireDraftPanel`,+`useHireComposer`, `DraftMessagePreview`) leaves the folder: ESLint refuses+imports of its internal modules.++### 2. Hire++`hire_employee` ([hire.py](../server/services/employees/hire.py)) takes a+`HireEmployeeRequest` ([hire_request.py](../server/services/employees/hire_request.py);+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`;+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,+ its trigger / reply / notify-owner / tool nodes with parameter templates,+ and a `side_effects` class. Apps the registry does not know are recorded as+ unsupported, named in the instructions, and never block a start;+3. builds the graph ([builder.py](../server/services/employees/builder.py),+ pure): one trigger (an app event, a schedule on `cronScheduler`, or manual+ chat), one `aiAgent` whose system message comes from+ [prompt.py](../server/services/employees/prompt.py), always-on tools (web+ search, todos, clock, plus memory when the owner allows it) and the apps'+ tools, delivery, and an "Activity log" console node. With "Ask me before+ sending anything" on, a reply goes through `approvalGate`, and tools that+ send or spend money are left off. Every node type must pass+ `node_allowlist.is_hire_allowed` ([Node Allowlist](./node_allowlist.md));+ node types never come from the payload;+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}`+ and, when every app is connected and an AI model exists, starts the+ employee in the background.++### 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`.++Automatic pauses now record why: `WorkflowControlExecution.pause_reason`+(`failures` from the circuit breaker, `recovery` after a crash,+`controller_missing`) and `pause_detail`, emitted by `serialize_control` and+cleared on resume. Home shows such an employee as "Needs attention". See+[Temporal Workflow Control](./temporal-workflow-control.md#recovery-policies).++## Asking before sending++With the rule on, a reply waits in an `approvalGate` until the owner decides+on the employee's card. The gate stores the draft in `approval_requests`,+wakes the moment it is decided, survives restarts (its idempotency key finds+the same row on every attempt), expires after `timeout_hours`, and fails+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).++## "Done today"++Every trigger-spawned run that finishes writes a `workflow_run_records` row+([runs.py](../server/services/employees/runs.py)): on Temporal from the+`workflow_runs.record_completion` activity, scheduled at the end of+`MachinaWorkflow.run` behind the `machina-run-record-v1` patch; in-process+from `DeploymentManager`. The count starts at local midnight in the owner's+timezone, and rows are pruned after 35 days.++## Settings++- **Profile**: `profile_full_name`, `profile_call_name`, `profile_role`,+ `profile_preferences`, `profile_timezone` (written from `Intl` on save),+ `memory_across_chats` and `prefer_local_ai` on `UserSettings`, normalised on+ save by [services/settings/profile.py](../server/services/settings/profile.py).+ Every hire reads them into its instructions.+- **Connectors**: the providers in `config/credential_providers.json` that+ declare a `consumer_category` (`messages`, `organize`, `business`, `ai`) and a+ short `description`. The catalogue adds `connected`, which differs from+ `stored` for providers with a `connected_check` (WhatsApp's live pairing, the+ IMAP/SMTP account's keys).++## Wire contract++WebSocket requests (snake_case; failures come back as `success: false` with an+`error` code):++| Type | Payload | Response |+|---|---|---|+| `list_employees` | `{}` | `{employees}` |+| `get_employee` | `{workflow_id}` | the summary plus `description`, `job`, `plan`, `rules`, `choices`, `trigger_text`, `last_run`, `latest_report` |+| `generate_employee_setup` | `{job, refine?, history?, draft_token}` | `{draft_token, reply, provider, model, usage, retried, finish_reason, apps}` |+| `cancel_employee_setup` | `{draft_token}` | `{cancelled}` |+| `hire_employee` | `HireEmployeeRequest` | `{employee, started, missing_apps, needs_ai, unsupported_apps, warnings, idempotent}` |+| `start_employee` | `{workflow_id, expected_revision, idempotency_key}` | as `start_workflow` |+| `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)):++| 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, 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 |++## Tests++Server: `tests/services/employees/`, `tests/services/approvals/`,+`tests/test_edge_condition_parity.py`, `tests/test_genui_catalog_sync.py`,+`tests/test_hire_payload_contract.py`, `tests/test_node_allowlist_hire.py`,+`tests/test_user_settings_profile_fields.py`,+`tests/test_credential_catalogue_consumer_fields.py`,+`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`.++## Known gaps++- An employee's latest report is not captured yet (`latest_report` is always+ empty).+- `list_employees` is not filtered per owner (multi-user mode shares one+ store anyway; see [Authentication](./authentication.md)).+- OAuth sign-in is not opened ahead of the request, so a browser may block+ the popup.+- Each waiting draft holds one `triggers-event` worker slot.+- A manual-chat employee cannot be given work from Home yet; the setup prompt+ steers towards app and schedule triggers.diff --git a/docs-internal/onboarding.md b/docs-internal/onboarding.mdindex 80faf799..fbfbdec3 100644--- a/docs-internal/onboarding.md+++ b/docs-internal/onboarding.md@@ -2,7 +2,7 @@## Overview-The onboarding service provides a four-step welcome wizard that appears after a user's first launch: what OpenCompany is, how the canvas works, connecting an AI provider, and trying the shipped AI Assistant example. It is database-backed, skippable, resumable, and replayable from Settings. A separate, dismissable **Get Started checklist** (`GetStartedChecklist.tsx`) sits in the corner of the canvas after the wizard and tracks five first-session milestones.+The onboarding service provides a four-step welcome wizard that appears after a user's first launch: what OpenCompany is, how the canvas works, connecting an AI provider, and trying the shipped AI Assistant example. It is database-backed, skippable, resumable, and replayable from Settings. The wizard is part of the workflow editor (`Dashboard.tsx`), so with Normal mode on it first appears when Dev mode opens; Normal mode's first screen is Home itself ([normal_mode.md](./normal_mode.md)). A separate, dismissable **Get Started checklist** (`GetStartedChecklist.tsx`) sits in the corner of the canvas after the wizard and tracks five first-session milestones.The frontend is **fully shadcn/ui + Tailwind** — antd was removed from `client/src/`. The wizard composes the project's `Modal` primitive, shadcn `Button` / `ActionButton` / `Card` / `Badge` / `Alert` / `Skeleton`, and `lucide-react` icons. The step progress indicator is a hand-rolled `<ol>` driven by node-role tokens (no antd `Steps`).diff --git a/docs-internal/temporal-workflow-control.md b/docs-internal/temporal-workflow-control.mdindex 14cafa8c..4619eed8 100644--- a/docs-internal/temporal-workflow-control.md+++ b/docs-internal/temporal-workflow-control.md@@ -213,6 +213,14 @@ that Resume relies on.every knob is evaluated on the activity side so flipping config nevertouches recorded workflow commands.+**Why an automatic pause happened.** Each of the three records it on the+control row: `pause_reason` is `failures` (the circuit breaker),+`recovery` (crash recovery) or `controller_missing`, with a readable+`pause_detail`. `serialize_control` emits both; a transition back to+`running` (Resume, reconcile, restore) clears them. Only server-side calls+can set a reason; a `pause_workflow` from a socket cannot. Normal mode shows+such an employee as "Needs attention" ([normal_mode.md](./normal_mode.md)).+## Canvas editability (`can_edit` capability)Whether a workflow's canvas may be edited is a **server-owned capability**,diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.mdindex 71c9e2c9..dacdc44e 100644--- a/docs-internal/theme_system.md+++ b/docs-internal/theme_system.md@@ -126,6 +126,38 @@ Six tokens for canvas identity: `agent / model / skill / tool / trigger / workflConsumed as `var(--code-*)` in [index.css](../client/src/index.css) (`.code-editor-container`, `.console-json-output`, the `.chat-markdown` dark overrides) and exposed as Tailwind utilities (`text-code-tag`, `bg-code-bg`, …) via the `@theme inline` bridge; the `OutputPanel` `@uiw/react-json-view` viewer reads the same vars. This **replaced the old global dracula-hardcoded `--prism-*` block and the dead `getPrismTokenCSS()` helper** — code/JSON now paints in each theme's palette instead of one dracula scheme everywhere. (`prismjs` is still the tokenizer; only the colours moved to `--code-*`.)+### Home (Normal mode) tokens++Normal mode ([normal_mode.md](./normal_mode.md)) adds its own steps, all in+[base.css](../client/src/themes/base.css) unless noted, and bridged in+`index.css` like the rest:++- **Motion**: `--ease-spring | overshoot | reveal` and the choreography+ durations (`--dur-intro`, `--dur-view-swap`, `--dur-panel-in/-out`,+ `--dur-toast-in/-hold/-out`, `--dur-mode-in/-out`, `--dur-theme-reveal`,+ `--dur-glow`, `--dur-pip-loop`, …). Read only through+ [lib/motion.ts](../client/src/lib/motion.ts), whose fallbacks mirror+ base.css.+- **Radii**: `--radius-row | card | panel | draft | composer`, multiples of each+ theme's `--radius-lg`, so square themes stay square.+- **Type and layout**: `--text-meta | row | lead | title | hero` (with+ `--tracking-hero`, `--leading-hero`), and the Home layout constants+ (`--w-home-sidebar`, `--h-home-header`, `--w-composer`, the orb slot sizes,+ the Settings dialog size).+- **Status**: `--status-{working,ready,paused,attention,waiting}-{dot,fill,border,ink}`+ for the employee pills and dots. The dot is the raw role colour; light.css+ keeps the paused dot at the design's mid grey.+- **Per family** (light.css / dark.css): `--shadow-float | popover | dialog`,+ the logo palette `--lg-*`, and the node-role `-fill / -edge / -hover / -ink`+ variants.++Home shows only the two base themes: `ThemeProvider`'s `baseOnly` (set by+`app/ShellThemeProvider.tsx` while Home is showing) renders a chosen stylized+theme as its family's base, and the pre-paint script in `index.html` applies+the same rule to the first frame. `setTheme(next, { reveal: true, origin })`+grows the new theme as a circle from `origin` (View Transitions), falls back+to a short colour fade, and is instant under reduced motion.+## Migration recipeThe single most important rule from the design handoff: