Skip to content

Self-improving AI Employees for everyone

feat: browser system Chrome, shell non-blocking, deep agent todos, pydantic fix

trohitgbdccc576bec8
diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml
index b7c55c05..19d41541 100644
--- a/.github/actions/setup/action.yml
+++ b/.github/actions/setup/action.yml
@@ -51,4 +51,4 @@ runs:
echo "npm: $(npm --version)"
echo "Python: $(python --version)"
echo "uv: $(uv --version)"
- echo "temporal-server: $(temporal-server --version 2>/dev/null || echo 'installed')"
+ echo "temporal-server: $(temporal --version 2>/dev/null || echo 'installed')"
diff --git a/bin/cli.js b/bin/cli.js
index 1df425e5..3bb44c2e 100755
--- a/bin/cli.js
+++ b/bin/cli.js
@@ -114,7 +114,7 @@ function doctor() {
console.log(' Additional checks:');
const checks = [
['uv', getVersion('uv --version')],
- ['temporal-server', getVersion('temporal-server --version')],
+ ['temporal-server', getVersion('temporal --version')],
];
for (const [name, ver] of checks) {
console.log(ver ? ` ${name}: ${ver}` : ` ${name}: Not Found`);
diff --git a/client/src/nodeDefinitions/browserNodes.ts b/client/src/nodeDefinitions/browserNodes.ts
index 9f1dbc8d..2fa134a3 100644
--- a/client/src/nodeDefinitions/browserNodes.ts
+++ b/client/src/nodeDefinitions/browserNodes.ts
@@ -77,6 +77,8 @@ export const browserNodes: Record<string, INodeTypeDescription> = {
{ name: 'Wait', value: 'wait', description: 'Wait for an element to appear' },
{ name: 'Scroll', value: 'scroll', description: 'Scroll the page' },
{ name: 'Select', value: 'select', description: 'Select a dropdown option' },
+ { name: 'Console Logs', value: 'console', description: 'Get browser console output (log, warn, error)' },
+ { name: 'Page Errors', value: 'errors', description: 'Get JavaScript errors from the page' },
{ name: 'Batch', value: 'batch', description: 'Execute multiple commands' },
],
description: 'Browser operation to perform',
@@ -182,6 +184,52 @@ export const browserNodes: Record<string, INodeTypeDescription> = {
default: true,
description: 'Open browser in visible (headed) mode instead of headless',
},
+ {
+ displayName: 'Auto Connect',
+ name: 'autoConnect',
+ type: 'boolean',
+ default: false,
+ description: 'Auto-discover and connect to an already-running Chrome instance (reuses auth state)',
+ },
+ {
+ displayName: 'Browser',
+ name: 'browser',
+ type: 'options',
+ default: 'chrome',
+ options: [
+ { name: 'Google Chrome', value: 'chrome', description: 'System-installed Google Chrome (auto-detected)' },
+ { name: 'Microsoft Edge', value: 'edge', description: 'System-installed Microsoft Edge (auto-detected)' },
+ { name: 'Chromium', value: 'chromium', description: 'System-installed Chromium (auto-detected)' },
+ { name: 'Bundled Chromium', value: 'bundled_explicit', description: 'Use agent-browser built-in Chromium (no system browser)' },
+ { name: 'Custom Path', value: 'custom', description: 'Specify a custom executable path' },
+ ],
+ description: 'Which browser to use for automation',
+ },
+ {
+ displayName: 'Browser Path',
+ name: 'executablePath',
+ type: 'string',
+ default: '',
+ placeholder: '/usr/bin/google-chrome or C:\\...\\chrome.exe',
+ description: 'Custom browser executable path',
+ displayOptions: { show: { browser: ['custom'] } },
+ },
+ {
+ displayName: 'New Window',
+ name: 'newWindow',
+ type: 'boolean',
+ default: true,
+ description: 'Open a new browser window instead of a tab in an existing instance',
+ displayOptions: { show: { browser: ['chrome', 'edge', 'chromium', 'custom'] } },
+ },
+ {
+ displayName: 'Chrome Profile',
+ name: 'chromeProfile',
+ type: 'string',
+ default: '',
+ placeholder: 'Default',
+ description: 'Chrome profile name to reuse login state (e.g., Default, Profile 1)',
+ },
{
displayName: 'Action Delay (ms)',
name: 'actionDelay',
diff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.md
index a6eb6839..9aa6f7cf 100644
--- a/docs-internal/DESIGN.md
+++ b/docs-internal/DESIGN.md
@@ -11,6 +11,9 @@ Related docs:
- [rlm_service.md](rlm_service.md) - Recursive Language Model agent execution
- [proxy_service.md](proxy_service.md) - residential proxy provider management
- [workflow-schema.md](workflow-schema.md) - workflow JSON schema and node catalog
+- [current_system_architecture_analysis.md](current_system_architecture_analysis.md) - current frontend, backend, serving, and extension model audit
+- [production_scale_architecture_research.md](production_scale_architecture_research.md) - source-backed research for a 1000+ node production architecture
+- [config_driven_node_platform.md](config_driven_node_platform.md) - target config-driven node and panel platform design
---
diff --git a/docs-internal/config_driven_node_platform.md b/docs-internal/config_driven_node_platform.md
new file mode 100644
index 00000000..eb242973
--- /dev/null
+++ b/docs-internal/config_driven_node_platform.md
@@ -0,0 +1,687 @@
+# Config-Driven Node Platform Design
+
+Last reviewed: 2026-04-12
+
+## Purpose
+
+This document proposes a config-driven node platform for MachinaOs that makes it easy to:
+
+- add new nodes without disturbing existing ones
+- generate parameter panels from config
+- generate docs and help panels from config
+- version nodes safely
+- keep execution modular across frontend and backend
+
+This is the implementation-facing design that translates the research in [production_scale_architecture_research.md](production_scale_architecture_research.md) into a concrete platform model for this repo.
+
+---
+
+## Design Goals
+
+### Primary goals
+
+- one canonical source of truth for node metadata
+- config-first onboarding for most new nodes
+- strict separation between node spec and node runtime
+- version-safe workflow compatibility
+- modular extension points
+- generated or mostly generated panels
+
+### Non-goals
+
+- removing support for advanced programmatic nodes
+- forcing every node into the same UI chrome
+- rewriting the whole repo in one step
+
+---
+
+## Current Problem
+
+Today, MachinaOs already has good building blocks:
+
+- typed node properties on the frontend
+- grouped node definitions
+- backend handler registry
+- workflow execution abstraction
+
+But the platform lacks a canonical contract that can drive everything from one place. The result is hidden coupling across:
+
+- palette registration
+- node rendering family selection
+- parameter forms
+- credentials requirements
+- backend runtime dispatch
+- validation
+- docs/help
+
+For a large node catalog, that coupling is the main maintenance cost.
+
+---
+
+## Core Proposal
+
+Introduce a versioned `NodeSpec` resource as the canonical contract for most nodes.
+
+### High-level rule
+
+For most nodes:
+
+- add one spec file
+- let the frontend generate the node entry and panels
+- let the backend bind the spec to a generic or specialized runtime
+
+For advanced nodes:
+
+- add one spec file
+- add one runtime module
+- register through an extension point
+
+The spec still remains canonical even when a custom runtime exists.
+
+---
+
+## Canonical `NodeSpec`
+
+### Resource shape
+
+The platform should treat a node as a versioned resource, similar to a CRD-style manifest.
+
+Example:
+
+```json
+{
+ "$schema": "https://machinaos.dev/schema/node-spec/v1",
+ "apiVersion": "nodes.machinaos.dev/v1",
+ "kind": "NodeSpec",
+ "metadata": {
+ "name": "gmail.send",
+ "version": "2.1.0",
+ "displayName": "Send Gmail",
+ "category": "google",
+ "tags": ["email", "action", "google"]
+ },
+ "spec": {
+ "class": "declarative",
+ "family": "square",
+ "description": "Send an email using Gmail.",
+ "icon": "gmail",
+ "ports": {
+ "inputs": [
+ {
+ "id": "main",
+ "type": "main",
+ "required": true
+ }
+ ],
+ "outputs": [
+ {
+ "id": "main",
+ "type": "main",
+ "schemaRef": "#/$defs/output"
+ }
+ ]
+ },
+ "credentials": [
+ {
+ "provider": "google_oauth",
+ "required": true,
+ "scopes": ["https://www.googleapis.com/auth/gmail.send"]
+ }
+ ],
+ "parametersSchema": {
+ "type": "object",
+ "required": ["to", "subject", "body"],
+ "properties": {
+ "to": {
+ "type": "string",
+ "format": "email",
+ "title": "To"
+ },
+ "subject": {
+ "type": "string",
+ "title": "Subject"
+ },
+ "body": {
+ "type": "string",
+ "title": "Body"
+ }
+ }
+ },
+ "uiSchema": {
+ "ui:order": ["to", "subject", "body"],
+ "body": {
+ "ui:widget": "textarea",
+ "ui:options": {
+ "rows": 8
+ }
+ }
+ },
+ "runtime": {
+ "runner": "http_action",
+ "workerType": "http",
+ "timeoutMs": 30000,
+ "retryPolicy": "standard",
+ "requestTemplate": {
+ "provider": "gmail",
+ "operation": "send_message"
+ }
+ },
+ "docs": {
+ "summary": "Send an email with Gmail.",
+ "examples": [
+ "Order confirmation email",
+ "Status notification email"
+ ]
+ }
+ }
+}
+```
+
+### Why this shape
+
+This splits the node into stable concerns:
+
+- `metadata` for identity and discovery
+- `parametersSchema` for validation and defaults
+- `uiSchema` for panel rendering hints
+- `runtime` for execution binding
+- `docs` for generated help surfaces
+
+---
+
+## Spec Fields That Matter
+
+### `metadata`
+
+Use for:
+
+- stable node identity
+- display label
+- search tags
+- category grouping
+- version pinning
+
+### `spec.class`
+
+Allowed initial values:
+
+- `declarative`
+- `programmatic`
+
+This determines whether the node can be executed by a generic runner or needs a custom module.
+
+### `spec.family`
+
+Use for visual family selection rather than hardcoding long type lists in `Dashboard.tsx`.
+
+Examples:
+
+- `trigger`
+- `square`
+- `agent`
+- `toolkit`
+- `model`
+- `monitor`
+
+### `ports`
+
+This should replace the current pattern where some connection semantics are encoded partly in node definitions and partly in visual conventions.
+
+### `parametersSchema`
+
+Use JSON Schema for:
+
+- types
+- required fields
+- defaults
+- enums
+- numeric limits
+- schema composition
+- validation annotations
+
+### `uiSchema`
+
+Use a separate UI-oriented schema for:
+
+- control order
+- widget type
+- grouping
+- help text
+- placeholders
+- textarea sizing
+- hidden fields
+- advanced sections
+
+### `runtime`
+
+This binds the node to a runner or worker capability. It should answer:
+
+- who executes the node
+- where it executes
+- which retry policy applies
+- which request template or adapter is used
+
+### `docs`
+
+Use for:
+
+- human-readable summary
+- example use cases
+- link to provider documentation
+- migration notes
+
+---
+
+## Frontend Design
+
+### Palette generation
+
+The node palette should be generated from the loaded `NodeSpec` registry. The palette should not need custom code for most new nodes.
+
+Palette fields from spec:
+
+- display name
+- icon
+- category
+- tags
+- maturity
+- keywords
+
+### Node chrome generation
+
+The frontend should choose node chrome from `spec.family`, not from a long switch statement over many individual node IDs.
+
+Mapping example:
+
+- `family=trigger` -> trigger-style node
+- `family=agent` -> agent-style node
+- `family=square` -> square node
+- `family=model` -> model-style node
+
+This keeps the visual system bounded even as the catalog grows.
+
+### Inspector generation
+
+The parameter panel should primarily render from:
+
+- `parametersSchema`
+- `uiSchema`
+- runtime status from execution services
+
+This keeps the inspector generic and dramatically reduces node-specific frontend branching.
+
+### Additional generated panels
+
+The following panels should also derive mostly from the same spec:
+
+- credentials panel
+- outputs/help panel
+- validation panel
+- docs/examples panel
+
+That is the system change required to make "all other panels" easy to extend as well.
+
+---
+
+## Backend Design
+
+### Spec registry
+
+The backend should load node specs from a registry directory or package set at startup.
+
+Recommended layout:
+
+```text
+server/
+ node_specs/
+ google/
+ http/
+```
+
+The backend registry should expose:
+
+- lookup by name
+- lookup by name and version
+- category listings
+- compatibility metadata
+
+### Runtime registry
+
+The backend should keep a runtime registry separate from the node spec registry.
+
+Example runtime providers:
+
+- `http_action`
+- `http_trigger`
+- `llm_agent`
+- `browser_session`
+- `filesystem_action`
+- `code_runner`
+- `social_trigger`
+
+The spec says what the node is. The runtime provider says how it executes.
+
+### Execution boundary
+
+The execution path should become:
+
+1. load workflow
+2. resolve node version
+3. load `NodeSpec`
+4. validate parameters against schema
+5. bind to runtime provider
+6. execute in the correct worker class
+
+This is cleaner than importing many handlers directly into a large central executor module.
+
+---
+
+## Extension Points
+
+Following the research-backed modularity model, MachinaOs should expose narrow extension points.
+
+Recommended extension points:
+
+### `NodeSpecProvider`
+
+Adds one or more node specs to the registry.
+
+### `RuntimeProvider`
+
+Registers a runner for a `runtime.runner` or `workerType`.
+
+### `CredentialProvider`
+
+Registers credential types, validation rules, and acquisition UX.
+
+### `InspectorRendererProvider`
+
+Adds custom inspector widgets only when plain schema generation is not enough.
+
+### `OutputRendererProvider`
+
+Adds result viewers for special output types.
+
+### `ValidationRuleProvider`
+
+Adds extra rules beyond schema validation.
+
+### `DocsProvider`
+
+Adds or enriches generated docs and examples.
+
+The main rule is that each extension point should be addition-oriented and small.
+
+---
+
+## Declarative And Programmatic Nodes
+
+### Declarative nodes
+
+Use for:
+
+- CRUD APIs
+- REST integrations
+- SaaS actions
+- simple utility actions
+
+Implementation style:
+
+- manifest only
+- generic runner
+- no custom frontend code
+
+### Programmatic nodes
+
+Use for:
+
+- triggers
+- browser automation
+- code execution
+- stream processors
+- specialized agent runtimes
+
+Implementation style:
+
+- manifest plus custom runtime module
+- optional custom panel widgets
+- still versioned through the same `NodeSpec`
+
+This avoids forcing simple nodes to pay the complexity tax of advanced ones.
+
+---
+
+## Versioning Rules
+
+### Required platform behavior
+
+1. New workflows should use the latest stable node version by default.
+2. Existing workflows should stay pinned to the version they were saved with.
+3. Major breaking changes should create a new node version, not silently mutate old behavior.
+4. Migration helpers should be explicit and reversible.
+
+### Suggested fields
+
+Add explicit compatibility metadata:
+
+- `metadata.version`
+- `spec.replaces`
+- `spec.compatibility.minWorkflowVersion`
+- `spec.compatibility.featureFlags`
+
+This is directly informed by n8n-style version pinning and CRD-style versioned resources.
+
+---
+
+## Generated Panels Model
+
+The platform should treat UI panels as generated views over the same spec.
+
+### Palette panel
+
+Generated from:
+
+- metadata
+- icon
+- category
+- tags
+
+### Parameter panel
+
+Generated from:
+
+- `parametersSchema`
+- `uiSchema`
+- runtime status
+
+### Credentials panel
+
+Generated from:
+
+- `credentials[]`
+
+### Output panel
+
+Generated from:
+
+- output port schema
+- output renderer bindings
+
+### Docs panel
+
+Generated from:
+
+- `docs.summary`
+- `docs.examples`
+- provider links
+- version info
+
+### Validation panel
+
+Generated from:
+
+- schema validation
+- extension-point validation rules
+
+Once these are all driven from the same spec, new node addition becomes genuinely low-touch.
+
+---
+
+## Suggested Package Boundaries
+
+### Frontend
+
+```text
+client/src/
+ node-specs/
+ node-registry/
+ node-families/
+ panels/
+ runtime-status/
+```
+
+### Backend
+
+```text
+server/
+ node_specs/
+ runtimes/
+ http/
+ llm/
+ browser/
+ filesystem/
+ social/
+ registry/
+ compiler/
+ execution/
+```
+
+### Shared
+
+If the repo wants stronger type safety across stacks, extract shared contracts:
+
+```text
+packages/
+ node-spec-contract/
+```
+
+This package should define:
+
+- `NodeSpec` schema types
+- workflow IR types
+- validation helpers
+
+---
+
+## Suggested Migration Path From The Current Repo
+
+### Phase 0: Introduce the contract
+
+- add `NodeSpec` schema
+- add registry loaders
+- do not change execution yet
+
+### Phase 1: Make frontend metadata spec-driven
+
+- generate palette from spec
+- generate basic inspector from schema
+- map visual family from spec
+
+### Phase 2: Make backend resolution spec-driven
+
+- load node specs in backend
+- validate parameters via schema
+- map to existing handlers through a compatibility adapter
+
+### Phase 3: Introduce generic declarative runners
+
+- implement `http_action`
+- implement `http_trigger`
+- migrate simple nodes first
+
+### Phase 4: Split worker pools by capability
+
+- pull node execution out of the universal runtime path
+- use queues or Temporal task queues per capability
+
+### Phase 5: Remove legacy central registries
+
+- shrink `Dashboard.tsx` type mapping
+- shrink `NodeExecutor` handler registry
+- keep only advanced runtime modules
+
+This sequence reduces migration risk because it does not require a flag-day rewrite.
+
+---
+
+## Adding A New Node In The Target System
+
+### Declarative node flow
+
+1. Add one `NodeSpec` JSON file.
+2. Register or reuse a runtime runner such as `http_action`.
+3. The palette, parameter panel, docs panel, and credentials panel appear automatically.
+4. Existing nodes are untouched.
+
+### Programmatic node flow
+
+1. Add one `NodeSpec` JSON file.
+2. Add one runtime module implementing the runtime interface.
+3. Register it through `RuntimeProvider`.
+4. Add a custom widget only if the default panels are insufficient.
+
+That is the modularity target.
+
+---
+
+## Runtime Interface Sketch
+
+```ts
+export interface RuntimeProvider {
+ id: string;
+ workerType: string;
+ canRun(spec: NodeSpec): boolean;
+ validate?(spec: NodeSpec): ValidationIssue[];
+ execute(input: RuntimeExecutionInput): Promise<RuntimeExecutionResult>;
+}
+```
+
+The important point is not the exact TypeScript shape. The important point is that:
+
+- node specs are data
+- runtimes are modules
+- the registry binds them together
+
+---
+
+## Summary
+
+The config-driven design is the missing platform boundary in the current MachinaOs architecture.
+
+The target state should be:
+
+- spec-first node catalog
+- generated panels from `parametersSchema` and `uiSchema`
+- runtime binding through narrow extension points
+- declarative nodes by default
+- programmatic nodes only when needed
+- version pinning for workflow compatibility
+
+That is the architecture that makes new node addition easy without disturbing existing nodes.
+
+---
+
+## Source References
+
+- [n8n Choose Node Building Approach](https://docs.n8n.io/integrations/creating-nodes/plan/choose-node-method/)
+- [n8n Node Versioning](https://docs.n8n.io/integrations/creating-nodes/build/reference/node-versioning/)
+- [JSON Schema Reference](https://json-schema.org/understanding-json-schema)
+- [JSON Schema Dialect and Vocabulary Declaration](https://json-schema.org/understanding-json-schema/reference/schema)
+- [Backstage Extension Points](https://backstage.io/docs/backend-system/architecture/extension-points/)
+- [Backstage Modules](https://backstage.io/docs/next/backend-system/architecture/modules)
+- [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/api-extension/custom-resources/)
+- [Kubernetes CRD Structural Schema Guide](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
+- [react-jsonschema-form uiSchema](https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema/)
diff --git a/docs-internal/current_system_architecture_analysis.md b/docs-internal/current_system_architecture_analysis.md
new file mode 100644
index 00000000..dfb45c2b
--- /dev/null
+++ b/docs-internal/current_system_architecture_analysis.md
@@ -0,0 +1,591 @@
+# Current System Architecture Analysis
+
+Last reviewed: 2026-04-12
+
+## Purpose
+
+This document captures the current architecture of the MachinaOs codebase as it exists in this repository today. It focuses on:
+
+- The frontend application and how it is composed
+- The backend services that serve and execute workflows
+- The current runtime and deployment topology
+- The current node and panel extension model
+- The architectural limits that matter for a future 1000+ node system
+
+This is a code-audit document, not a target-state RFC. For the researched target architecture, see:
+
+- [production_scale_architecture_research.md](production_scale_architecture_research.md)
+- [config_driven_node_platform.md](config_driven_node_platform.md)
+
+---
+
+## Executive Summary
+
+MachinaOs is currently a split-stack workflow platform with a React Flow SPA on the frontend and a FastAPI backend that acts as:
+
+- auth service
+- workflow persistence layer
+- orchestration layer
+- node execution gateway
+- realtime event bus
+- background service host
+
+The system already contains several production-oriented ideas:
+
+- dependency injection on the backend
+- separated execution modes
+- optional Temporal integration
+- Redis-backed parallel execution
+- encrypted credential storage
+- a separate Node.js execution surface
+
+However, the platform is still organized around a few high-coupling modules:
+
+- `client/src/Dashboard.tsx`
+- `client/src/contexts/WebSocketContext.tsx`
+- `server/routers/websocket.py`
+- `server/services/node_executor.py`
+
+Those files are carrying too many responsibilities. That is the main reason the current system is workable for a mid-sized node catalog but will become expensive to extend and risky to scale to:
+
+- 1000+ nodes in one graph
+- 1000+ supported node types
+- high-throughput concurrent executions
+- low-memory runtime requirements
+
+---
+
+## Audit Scope
+
+The findings in this document are based on the repository structure and the following core paths:
+
+- `client/src/main.tsx`
+- `client/src/App.tsx`
+- `client/src/Dashboard.tsx`
+- `client/src/contexts/WebSocketContext.tsx`
+- `client/src/ParameterPanel.tsx`
+- `client/src/nodeDefinitions/*`
+- `client/src/types/INodeProperties.ts`
+- `server/main.py`
+- `server/routers/websocket.py`
+- `server/routers/database.py`
+- `server/services/workflow.py`
+- `server/services/node_executor.py`
+- `scripts/dev.js`
+- `scripts/start.js`
+- `scripts/serve-client.js`
+- `client/nginx.conf`
+- `package.json`
+- `pnpm-workspace.yaml`
+
+---
+
+## Repository Shape
+
+At a high level the repo is organized like this:
+
+| Path | Role |
+| --- | --- |
+| `client/` | React + Vite + React Flow authoring UI |
+| `server/` | FastAPI backend, orchestration, execution, persistence |
+| `server/nodejs/` | separate JS/TS execution microservice |
+| `scripts/` | local startup, production start, build, clean, stop |
+| `workflows/` | sample or exportable workflow payloads |
+| `docs-internal/` | internal engineering design notes |
+| `docs-MachinaOs/` | public-facing docs site content |
+
+There is also an important workspace mismatch:
+
+- `pnpm-workspace.yaml` includes `client` and `server/nodejs`
+- root `package.json` only declares `client` under `workspaces`
+
+That mismatch is not fatal, but it is a sign that the repo topology and package-management topology are not fully aligned.
+
+---
+
+## Runtime Topology
+
+### Development and local production start
+
+The root scripts orchestrate multiple long-running processes rather than one monolithic server:
+
+- frontend
+- backend
+- optional WhatsApp RPC/API service
+- Temporal server
+
+The dev script in `scripts/dev.js` will typically launch:
+
+- Vite or a static client server on `3000`
+- FastAPI on `3010`
+- WhatsApp API if enabled
+- Temporal if enabled
+
+The production start script in `scripts/start.js` uses the built client and launches:
+
+- static file server from `scripts/serve-client.js`
+- FastAPI backend
+- WhatsApp API if enabled
+- Temporal if not already running
+
+### Production reverse proxy
+
+FastAPI does not directly serve the SPA. The `client/nginx.conf` file shows the intended production topology:
+
+- `/` serves static frontend files
+- `/api/` proxies to backend port `3010`
+- `/webhook/` proxies to backend port `3010`
+- `/ws/` proxies WebSocket traffic to backend port `3010`
+- `/health` proxies to backend port `3010`
+
+That means the real product surface is multi-process and multi-surface. Running the Python backend alone is not the same thing as serving the app.
+
+### Runtime topology diagram
+
+```mermaid
+flowchart LR
+ Browser["Browser"] --> Nginx["Nginx or serve-client.js"]
+ Nginx -->|Static assets| Client["React/Vite SPA"]
+ Nginx -->|/api /ws /webhook| Backend["FastAPI backend"]
+
+ Backend --> DB["SQLModel / SQLite or DB"]
+ Backend --> Cache["Redis / SQLite / memory cache"]
+ Backend --> Creds["Encrypted credentials DB"]
+ Backend --> FS["Per-workflow workspace filesystem"]
+
+ Backend --> Temporal["Temporal server"]
+ Backend --> NodeJS["server/nodejs service"]
+ Backend --> WhatsApp["WhatsApp RPC/API"]
+```
+
+---
+
+## Frontend Architecture
+
+### Boot path
+
+The frontend boot sequence is straightforward:
+
+1. `client/src/main.tsx`
+2. `client/src/App.tsx`
+3. `client/src/Dashboard.tsx`
+
+`main.tsx` wraps the app in:
+
+- `ThemeProvider`
+- `AuthProvider`
+- `WebSocketProvider`
+
+`App.tsx` then applies Ant Design theming and a `ProtectedRoute`, and renders `Dashboard`.
+
+### Dashboard is the shell
+
+`client/src/Dashboard.tsx` is effectively the application shell and the primary orchestration surface for the authoring UI. It wires together:
+
+- `ReactFlow`
+- node type registration
+- edge type registration
+- component palette
+- workflow sidebar
+- top toolbar
+- parameter panels
+- console panel
+- credentials modal
+- onboarding flow
+- settings panel
+- execution result modal
+
+This gives the app a low-routing, workspace-centric UX, but it also means most UI composition pressure lands in one file.
+
+### State model
+
+The frontend currently uses a mixed state model:
+
+- React Flow local state for nodes and edges
+- Zustand in `client/src/store/useAppStore.ts` for workflow/session/application state
+- WebSocket context state for live status and async request tracking
+- `localStorage` for some UI preferences and local persistence
+
+This hybrid is pragmatic, but it means state boundaries are not fully normalized. The most important asymmetry is this:
+
+- graph topology lives primarily in the frontend
+- node parameters are stored server-side and fetched on demand
+
+That is why the frontend often needs both graph state and server-fetched parameter state to render a complete node experience.
+
+### Node type system
+
+The frontend already has a fairly rich metadata model in `client/src/types/INodeProperties.ts`:
+
+- typed inputs and outputs
+- property schemas
+- validation hints
+- credentials metadata
+- resource/operation metadata
+
+But the current system is still code-first rather than manifest-first:
+
+- node definitions are spread across many files in `client/src/nodeDefinitions/`
+- `client/src/nodeDefinitions/index.ts` is not the single source of truth for all nodes
+- `Dashboard.tsx` still contains a large classification cascade that maps node types to visual components
+
+The visual mapping currently depends on:
+
+- explicit type lists
+- category constants
+- fallback group checks
+
+That makes the renderer flexible, but it also means adding a new node can require touching multiple frontend modules even if the node itself is simple.
+
+### Parameter and panel system
+
+`client/src/ParameterPanel.tsx` shows that the platform already wants parameter panels to be semi-generated:
+
+- it fetches node definitions
+- it loads parameters from backend state
+- it renders a structured panel layout
+
+That is a good foundation. But panel behavior is still not fully config-driven because:
+
+- special cases still exist per node family
+- execution behavior is directly wired into the panel
+- node visuals, parameter forms, docs/help, execution affordances, and some result handling still span multiple files
+
+### Realtime communication model
+
+The most important frontend architecture choice is `client/src/contexts/WebSocketContext.tsx`.
+
+It currently handles:
+
+- request/response style operations
+- realtime broadcasts
+- execution status
+- parameter updates
+- variable updates
+- Android status
+- WhatsApp status
+- deployment status
+- console logs
+- terminal logs
+- long-running trigger waits
+
+In practice this acts as both:
+
+- a broadcast event bus
+- a client-side RPC transport
+
+That gives the app a single integration pipe, but it also creates a large contract surface and a high-coupling failure domain.
+
+### Frontend strengths
+
+- React Flow is already isolated enough to support a richer editor
+- node definitions have a meaningful metadata model
+- custom node families already exist
+- the shell is feature-rich and supports workflow-centric operation
+- WebSocket status scoping already includes workflow-aware patterns
+
+### Frontend weaknesses for 1000+ nodes
+
+- `Dashboard.tsx` is too central
+- `WebSocketContext.tsx` is too central
+- broad graph state can still fan out rerenders
+- node visual mapping is type-list heavy
+- node metadata is not fully manifest-driven
+- execution, config, docs, and UI state are still partially intertwined
+
+---
+
+## Backend Architecture
+
+### Application startup
+
+`server/main.py` is the backend entrypoint and lifecycle host. The backend uses a DI container from `server/core/container.py` and initializes a broad set of services at startup:
+
+- primary database
+- cache service
+- encrypted credentials database
+- encryption service
+- event waiter integration
+- APScheduler
+- execution recovery sweeper
+- cleanup service
+- compaction service
+- model registry
+- agent team service
+- proxy service
+- optional Temporal client, executor, and embedded worker
+
+This is a real backend service host, not just a thin API layer.
+
+### API and router boundaries
+
+The backend request surface is split across routers, with the most important ones being:
+
+- `server/routers/auth.py`
+- `server/routers/database.py`
+- `server/routers/workflow.py`
+- `server/routers/webhook.py`
+- `server/routers/websocket.py`
+- `server/routers/nodejs_compat.py`
+
+The routes fall into four broad buckets:
+
+1. authentication and session management
+2. workflow and parameter persistence
+3. node and workflow execution
+4. realtime control and broadcast traffic
+
+### Workflow execution facade
+
+`server/services/workflow.py` is a thin facade that delegates to specialized modules:
+
+- node execution
+- parameter resolution
+- deployment lifecycle
+- parallel orchestration
+- optional Temporal orchestration
+
+The service selects between execution modes:
+
+- Temporal when enabled and connected
+- Redis-backed parallel execution
+- sequential fallback
+
+That is one of the stronger parts of the current design. The selection logic is explicit and the fallback behavior is clear.
+
+### Node execution model
+
+`server/services/node_executor.py` uses a registry-style dispatch table. That is better than a giant if/else chain, but the current registry is still code-heavy:
+
+- many node types are explicitly bound in Python
+- a large number of handlers are imported at module load
+- node behavior is primarily code-bound rather than spec-bound
+
+This means new nodes are still expensive because they usually require:
+
+- frontend node metadata
+- frontend visual or category wiring
+- backend handler import
+- backend registry entry
+- often supporting parameter and validation changes
+
+### Realtime control plane
+
+`server/routers/websocket.py` is currently the main control plane for a large portion of the app. It handles:
+
+- node parameter CRUD
+- tool schema CRUD
+- node execution
+- status fetches
+- variable fetches
+- API key workflows
+- status broadcasts
+- long-running node interactions
+
+This is functional, but it means the WebSocket router is carrying too much write-path responsibility. For a large production system this creates problems in:
+
+- observability
+- API evolution
+- permission boundaries
+- backpressure control
+- compatibility across clients
+
+### Storage model
+
+The backend uses multiple storage layers with distinct roles:
+
+- primary workflow/application data via SQLModel/SQLAlchemy
+- cache via Redis when enabled, otherwise SQLite or in-memory fallback
+- encrypted credentials in a dedicated credentials database
+- filesystem workspaces under `data/workspaces/<workflow_id>`
+
+That separation is directionally correct. It allows the system to keep:
+
+- metadata in durable DB storage
+- execution caching in a faster layer
+- secrets under a distinct protection model
+- generated artifacts on the filesystem
+
+### Backend strengths
+
+- DI-based service initialization
+- clear execution mode fallbacks
+- optional Temporal integration already exists
+- execution cache and recovery patterns exist
+- credentials are not co-mingled with general app state
+- per-workflow workspace directories are already supported
+
+### Backend weaknesses for 1000+ nodes and high concurrency
+
+- `server/routers/websocket.py` is too broad
+- `server/services/node_executor.py` is too registry-heavy and code-driven
+- many node handlers live in one runtime domain
+- the backend is still the universal coordination surface for too many responsibilities
+- large outputs can still end up too close to live runtime memory and websocket transport
+
+---
+
+## Execution Modes Today
+
+MachinaOs already contains three execution strategies:
+
+1. Temporal distributed execution
+2. local parallel execution backed by Redis-enabled orchestration
+3. sequential fallback
+
+This is documented in more detail in [DESIGN.md](DESIGN.md) and [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md).
+
+### Current execution flow
+
+```mermaid
+flowchart TD
+ WF["WorkflowService.execute_workflow"] --> T{"Temporal enabled and connected?"}
+ T -->|Yes| TEMP["TemporalExecutor"]
+ T -->|No| R{"Redis enabled?"}
+ R -->|Yes| PAR["WorkflowExecutor"]
+ R -->|No| SEQ["Sequential walk"]
+
+ TEMP --> NE["Node execution in activities"]
+ PAR --> NE2["Node execution via NodeExecutor"]
+ SEQ --> NE3["Node execution via NodeExecutor"]
+```
+
+The existence of these three modes is useful because it means the repo is not architecturally locked into a single local-only execution pattern.
+
+---
+
+## Serving and Auth Model
+
+### Auth shape
+
+The current system uses session/cookie-oriented auth with FastAPI middleware and frontend `ProtectedRoute` checks.
+
+Operationally, this means deployment correctness depends on:
+
+- cookies being forwarded correctly
+- CORS being configured correctly
+- WebSocket upgrades carrying the same auth assumptions
+
+### Why this matters
+
+This serving model can fail in subtle ways:
+
+- the UI loads because static assets work
+- REST may partially work
+- WebSocket upgrades may fail or downgrade
+- the app then appears alive while core workflow operations are broken
+
+This is a normal risk in split frontend/backend systems, but it is worth stating explicitly because realtime workflow apps are especially sensitive to proxy and session drift.
+
+---
+
+## Current Node Extensibility Model
+
+Today, adding a new node usually means touching both stacks.
+
+### Frontend additions typically require
+
+1. a node definition entry in `client/src/nodeDefinitions/*`
+2. exports or aggregation updates
+3. possible updates to type-group lists
+4. possible updates to the node-to-component mapping cascade in `Dashboard.tsx`
+5. possible panel-specific behavior
+
+### Backend additions typically require
+
+1. a handler function
+2. handler import wiring
+3. registration in `NodeExecutor._build_handler_registry()`
+4. any validation or runtime dependency changes
+
+### Consequence
+
+This is modular at the file level, but not yet modular at the platform level. A true platform-level extension model would let most nodes be added as manifests plus a generic runner, instead of as coordinated multi-file code changes.
+
+---
+
+## Current Architectural Risks
+
+### 1. Oversized composition points
+
+The frontend and backend each have at least one oversized orchestration module:
+
+- `Dashboard.tsx`
+- `WebSocketContext.tsx`
+- `websocket.py`
+- `node_executor.py`
+
+These become merge hotspots and make reasoning about behavior harder over time.
+
+### 2. WebSocket as universal transport
+
+The current WebSocket layer is doing too much. That is manageable in a smaller product, but it becomes problematic when:
+
+- multiple client versions coexist
+- permissions need finer granularity
+- background processing grows
+- observability requirements rise
+
+### 3. Node metadata is not yet canonical
+
+There is no single canonical, versioned, manifest-first `NodeSpec` that drives:
+
+- palette
+- forms
+- docs
+- credentials
+- execution binding
+- validation
+
+The current platform has pieces of that model, but not the full contract.
+
+### 4. Large-graph editor pressure
+
+React Flow itself can support large graphs, but the current app structure will feel pressure from:
+
+- broad updates to nodes and edges
+- central dashboard coordination
+- potentially heavy node components
+- lack of first-class collapse/subflow boundaries
+
+### 5. Runtime memory growth risk
+
+The current system already has per-workflow workspaces and execution caches, which is good. But without a stronger artifact-first execution model, large outputs can still leak toward:
+
+- in-memory output stores
+- websocket payloads
+- frontend result state
+
+---
+
+## Immediate Conclusions
+
+The current architecture is a strong prototype-to-product foundation, especially because it already includes:
+
+- an execution facade
+- optional durable orchestration
+- separate storage responsibilities
+- a metadata-rich node system
+
+But it is not yet a clean large-scale node platform. The main missing ingredient is a canonical, versioned, config-driven node contract that both frontend and backend can consume.
+
+That is the boundary where the current design should evolve:
+
+- from code-first node registration
+- to spec-first node registration
+
+and:
+
+- from one large WebSocket-centric control plane
+- to clearer API, event, and worker boundaries
+
+---
+
+## Recommended Follow-up Reading
+
+- [DESIGN.md](DESIGN.md)
+- [TEMPORAL_ARCHITECTURE.md](TEMPORAL_ARCHITECTURE.md)
+- [node_creation.md](node_creation.md)
+- [workflow-schema.md](workflow-schema.md)
+- [production_scale_architecture_research.md](production_scale_architecture_research.md)
+- [config_driven_node_platform.md](config_driven_node_platform.md)
diff --git a/docs-internal/production_scale_architecture_research.md b/docs-internal/production_scale_architecture_research.md
new file mode 100644
index 00000000..22360d19
--- /dev/null
+++ b/docs-internal/production_scale_architecture_research.md
@@ -0,0 +1,651 @@
+# Production-Scale Workflow Architecture Research
+
+Last researched: 2026-04-12
+
+## Goal
+
+This document summarizes source-backed research for a production-scale MachinaOs architecture that can support:
+
+- very large workflow graphs
+- high runtime throughput
+- low memory pressure
+- durable and recoverable execution
+- easy addition of new nodes
+- easy addition of new configuration panels without disturbing existing nodes
+
+This document is intentionally source-driven. Where it recommends a MachinaOs-specific design, that recommendation is an inference synthesized from the cited systems and the current codebase.
+
+Related docs:
+
+- [current_system_architecture_analysis.md](current_system_architecture_analysis.md)
+- [config_driven_node_platform.md](config_driven_node_platform.md)
+
+---
+
+## Research Method
+
+The source set for this document was restricted to official or primary documentation where possible:
+
+- Temporal official docs
+- Conductor official docs
+- React Flow official docs
+- n8n official docs
+- JSON Schema official docs
+- Backstage official docs
+- Kubernetes official docs
+- react-jsonschema-form official docs
+
+Why this source set:
+
+- Temporal and Conductor represent production workflow orchestration patterns
+- React Flow represents the graph authoring surface currently used in MachinaOs
+- n8n is a strong reference for node platform ergonomics
+- JSON Schema and `uiSchema` cover config-driven validation and form generation
+- Backstage provides a trustworthy extension-point model
+- Kubernetes CRDs provide a strong versioned declarative API reference
+
+---
+
+## What Trusted Production Systems Actually Do
+
+### 1. Durable orchestrators separate orchestration from execution
+
+Temporal's core model is durable execution. Workflow logic is durable and resumable, while workers execute application code outside the Temporal server. This separation is important because it prevents the orchestrator from becoming the place where business logic, IO, and long-lived in-process state all pile up.
+
+MachinaOs inference:
+
+- the control plane should orchestrate workflow state
+- specialized workers should execute node logic
+- the control plane should not become the long-running execution host for every node type
+
+Source:
+
+- [Temporal Docs](https://docs.temporal.io/)
+
+### 2. Large-scale workflow engines use worker-task queue architectures
+
+Conductor's architecture documentation is explicit that workflows execute through worker-task queues, where each task type has its own queue and workers poll or receive work for the task types they know how to execute.
+
+Conductor also documents the metrics that should drive scaling:
+
+- queue depth
+- worker throughput
+- queue wait time
+
+MachinaOs inference:
+
+- worker pools should scale by capability and queue health, not by a single giant process
+- node execution should be partitioned by execution class such as HTTP, browser, LLM, social, filesystem, and triggers
+
+Sources:
+
+- [Conductor Architecture Overview](https://conductor-oss.github.io/conductor/devguide/architecture/index.html)
+- [Conductor Workers](https://conductor-oss.github.io/conductor/devguide/concepts/workers.html)
+- [Conductor Scaling Workers](https://conductor-oss.github.io/conductor/devguide/how-tos/Workers/scaling-workers.html)
+
+### 3. Large graph editors do not try to render everything equally
+
+React Flow's own performance guidance highlights the main problems for large node graphs:
+
+- unnecessary rerenders
+- over-subscribing to the full nodes array
+- expensive custom node components
+- large visible trees
+
+React Flow also provides an expand/collapse example that keeps the full graph model while rendering only the visible portion.
+
+MachinaOs inference:
+
+- large workflows need subflows, collapse, and visibility-aware rendering
+- layout work and expensive graph transforms should move off the main thread
+- node components should be cheap and memoized
+
+Sources:
+
+- [React Flow Performance](https://reactflow.dev/learn/advanced-use/performance)
+- [React Flow Expand and Collapse](https://reactflow.dev/examples/layout/expand-collapse)
+- [React Flow Auto Layout](https://reactflow.dev/examples/layout/auto-layout)
+
+### 4. Productive node platforms are declarative first, programmatic second
+
+n8n's node creation docs are unusually clear:
+
+- use declarative nodes for most REST integrations
+- use programmatic nodes for triggers, non-REST protocols, transformations, and advanced behavior
+- version nodes so existing workflows keep using the version they were built with
+
+MachinaOs inference:
+
+- most node additions should be declarative manifests
+- only a smaller subset should require custom runtime code
+- node versioning must be first-class before the catalog gets large
+
+Sources:
+
+- [Choose your node building approach](https://docs.n8n.io/integrations/creating-nodes/plan/choose-node-method/)
+- [Node base file](https://docs.n8n.io/integrations/creating-nodes/build/reference/node-base-files/)
+- [Node versioning](https://docs.n8n.io/integrations/creating-nodes/build/reference/node-versioning/)
+
+### 5. Config-driven platforms need separate validation and UI contracts
+
+JSON Schema is well suited for declaring data structure, validation, defaults, and composition. It also supports explicit dialect declaration using `$schema`, which matters when a platform wants long-term compatibility.
+
+`uiSchema` exists because data validation and UI rendering are different concerns. JSON Schema says what is valid; `uiSchema` says how to render and organize it.
+
+MachinaOs inference:
+
+- node parameter contracts should use JSON Schema
+- panel layout and rendering hints should use a separate UI-oriented schema
+- the platform should version both
+
+Sources:
+
+- [JSON Schema Reference](https://json-schema.org/understanding-json-schema)
+- [JSON Schema Dialect and Vocabulary Declaration](https://json-schema.org/understanding-json-schema/reference/schema)
+- [react-jsonschema-form uiSchema](https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema/)
+
+### 6. Stable modular systems prefer narrow extension points
+
+Backstage's backend system emphasizes extension points with small interfaces rather than one large global plugin API. It also recommends exposing multiple focused extension points instead of a single large surface.
+
+MachinaOs inference:
+
+- node extensibility should expose several narrow interfaces
+- different platform concerns should not be bundled into one registry
+
+Sources:
+
+- [Backstage Extension Points](https://backstage.io/docs/backend-system/architecture/extension-points/)
+- [Backstage Backend Architecture](https://backstage.io/docs/backend-system/architecture/index/)
+- [Backstage Modules](https://backstage.io/docs/next/backend-system/architecture/modules)
+
+### 7. Versioned declarative APIs work best with structural schemas
+
+Kubernetes CRDs are a strong precedent for:
+
+- versioned resource definitions
+- structural schemas
+- explicit spec and status separation
+- independent controllers that reconcile declared state
+
+MachinaOs inference:
+
+- node manifests should be versioned resources, not ad hoc JSON blobs
+- workflow specs should be validated structurally
+- runtime status should be kept separate from node spec
+
+Sources:
+
+- [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/api-extension/custom-resources/)
+- [Extend the Kubernetes API with CRDs](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
+- [CRD Versioning](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning)
+
+---
+
+## The Three Different "1000+ Node" Problems
+
+The phrase "1000+ nodes" actually describes three different scale problems. They should not be solved with one technique.
+
+### Problem A: 1000+ nodes in one authoring graph
+
+This is a frontend/editor problem.
+
+Main design response:
+
+- subflows
+- collapse and expand
+- viewport-aware rendering
+- lightweight node chrome
+- background layout workers
+
+### Problem B: 1000+ runtime steps in a workflow execution
+
+This is an orchestration and execution problem.
+
+Main design response:
+
+- compile workflow JSON into an execution IR
+- partition work into executable stages
+- dispatch work to specialized worker pools
+- persist metadata and artifact references, not large inline payloads
+
+### Problem C: 1000+ node types in the product catalog
+
+This is a platform and extensibility problem.
+
+Main design response:
+
+- versioned canonical `NodeSpec`
+- declarative nodes for most integrations
+- small programmatic runtime interface for advanced nodes
+- generated panels and docs from spec metadata
+
+If those three problem classes are blurred together, the resulting architecture tends to become overcomplicated and underperforming.
+
+---
+
+## Recommended Target Architecture For MachinaOs
+
+This section is the MachinaOs-specific recommendation inferred from the sources above and from the current repository structure.
+
+### High-level planes
+
+MachinaOs should be split conceptually into five planes:
+
+1. Authoring plane
+2. Control plane
+3. Execution plane
+4. Artifact plane
+5. Observability plane
+
+### Plane responsibilities
+
+#### Authoring plane
+
+Owns:
+
+- React Flow editor
+- palette
+- inspector panels
+- docs/help surfaces
+- validation display
+- execution view and trace navigation
+
+Does not own:
+
+- orchestration
+- business execution
+- secret storage
+
+#### Control plane
+
+Owns:
+
+- workflow validation
+- workflow compilation
+- deployment records
+- run lifecycle
+- scheduling
+- authn/authz
+- audit and policy
+
+Recommended technologies and boundaries:
+
+- HTTP or gRPC command surface
+- WebSocket or SSE for subscriptions
+- durable workflow orchestrator
+
+#### Execution plane
+
+Owns:
+
+- task execution
+- IO
+- provider-specific adapters
+- retries at the worker boundary
+- side effects
+
+Recommended shape:
+
+- stateless workers
+- workers partitioned by capability
+
+#### Artifact plane
+
+Owns:
+
+- large outputs
+- attachments
+- traces
+- generated files
+- intermediate data snapshots when needed
+
+Recommended rule:
+
+- large outputs should be stored by reference, not pushed inline through the whole stack
+
+#### Observability plane
+
+Owns:
+
+- metrics
+- logs
+- traces
+- run timeline
+- queue health
+- worker health
+
+Recommended rule:
+
+- the app should be able to answer why a run is slow, stuck, retried, or memory-heavy without reading raw process logs
+
+---
+
+## Target Topology Diagram
+
+```mermaid
+flowchart LR
+ User["User / Browser"] --> UI["Authoring UI"]
+
+ UI -->|Commands| API["Control Plane API"]
+ UI -->|Live updates| Events["Realtime events"]
+
+ API --> Compiler["Workflow compiler"]
+ Compiler --> Orchestrator["Durable orchestrator"]
+
+ Orchestrator --> Q1["Task queue: http"]
+ Orchestrator --> Q2["Task queue: llm"]
+ Orchestrator --> Q3["Task queue: browser"]
+ Orchestrator --> Q4["Task queue: filesystem"]
+ Orchestrator --> Q5["Task queue: trigger/social"]
+
+ Q1 --> W1["HTTP workers"]
+ Q2 --> W2["LLM workers"]
+ Q3 --> W3["Browser workers"]
+ Q4 --> W4["Filesystem workers"]
+ Q5 --> W5["Trigger/social workers"]
+
+ W1 --> Artifacts["Artifact store"]
+ W2 --> Artifacts
+ W3 --> Artifacts
+ W4 --> Artifacts
+ W5 --> Artifacts
+
+ API --> Metadata["Workflow metadata DB"]
+ API --> Secrets["Secrets / credentials store"]
+ Orchestrator --> RunState["Run state / history"]
+ Events --> Obs["Metrics / logs / traces"]
+```
+
+---
+
+## Performance Strategy For High Runtime And Low Memory
+
+### 1. Compile workflows before executing them
+
+Do not execute raw editor JSON directly if the goal is production-scale efficiency.
+
+Compile the workflow graph into an execution IR that resolves:
+
+- validated node versions
+- port compatibility
+- parameter defaults
+- subflow boundaries
+- retry policy inheritance
+- worker capability bindings
+
+Benefits:
+
+- less work during execution
+- better caching keys
+- more stable observability
+- more predictable failure surfaces
+
+### 2. Partition worker pools by capability
+
+Do not put all node execution into one generic worker pool.
+
+Suggested capability pools:
+
+- `http`
+- `llm`
+- `browser`
+- `filesystem`
+- `social`
+- `trigger`
+- `code`
+- `document`
+
+Benefits:
+
+- better autoscaling
+- better isolation
+- lower memory fragmentation
+- fewer dependency conflicts
+
+### 3. Treat large outputs as artifacts
+
+Large outputs should not stay inline across:
+
+- worker memory
+- orchestrator payloads
+- websocket broadcasts
+- frontend node state
+
+Preferred pattern:
+
+- keep a small metadata envelope in run state
+- store large content in filesystem or object storage
+- pass references and previews downstream when possible
+
+### 4. Use queue metrics to scale
+
+Conductor's metrics guidance maps well to MachinaOs. The minimum useful autoscaling signals are:
+
+- queue depth
+- queue wait time
+- task completion rate
+- worker saturation
+
+This is a more trustworthy scaling method than using CPU alone.
+
+### 5. Prefer durable orchestration over homegrown long-running state machines
+
+MachinaOs already includes Temporal integration. The most conservative production recommendation is:
+
+- keep Temporal as the durable orchestration backbone
+- avoid inventing a third orchestration model in parallel
+
+This is especially important for:
+
+- retries
+- backoff
+- long-running agents
+- waiting states
+- human-in-the-loop interactions
+- resumability
+
+---
+
+## Editor Strategy For Large Graphs
+
+### Required design moves
+
+1. Subflows as first-class nodes
+2. Collapse and expand at group and subflow boundaries
+3. Viewport-aware rendering
+4. Memoized node and edge components
+5. Avoid broad subscriptions to full graph arrays
+6. Move layout work off the main thread
+
+### Recommended editor model
+
+- store the complete graph model
+- render only visible nodes and edges
+- keep collapsed regions summarized
+- calculate layout in a worker or background thread
+
+This follows the shape React Flow's guidance pushes toward.
+
+### UX consequence
+
+Users should not need to visually manipulate a 1000-node flat canvas. The system should encourage structure:
+
+- groups
+- folders
+- packages
+- subflows
+- reusable templates
+
+That is a system design decision, not just a UI optimization.
+
+---
+
+## Node Platform Strategy
+
+### Canonical object: `NodeSpec`
+
+The platform should use a versioned, manifest-first `NodeSpec` as the canonical source of truth for most nodes.
+
+The `NodeSpec` should capture:
+
+- identity
+- version
+- category
+- ports
+- parameters schema
+- UI schema
+- credentials needs
+- docs/help metadata
+- runtime binding
+- retry and timeout defaults
+- compatibility and feature flags
+
+### Node classes
+
+MachinaOs should explicitly separate two node classes:
+
+#### Declarative nodes
+
+Use for:
+
+- REST-style integrations
+- parameterized utility nodes
+- many CRUD-style SaaS integrations
+- nodes whose behavior can be expressed through templates, mappings, and standard runners
+
+Expected share:
+
+- most of the catalog
+
+#### Programmatic nodes
+
+Use for:
+
+- triggers
+- browser automation
+- code execution
+- streaming or long-lived IO
+- complex transforms
+- highly specialized runtimes
+
+Expected share:
+
+- minority of the catalog
+
+This mirrors n8n's advice and aligns with how production node platforms avoid code sprawl.
+
+---
+
+## Panel Strategy
+
+To make new node addition easy, panel generation must become spec-driven too.
+
+The following UI surfaces should be generated primarily from spec metadata:
+
+- palette entries
+- inspector form
+- credentials picker
+- input and output docs
+- validation panel
+- inline help
+- node docs panel
+- examples panel
+
+This is the practical meaning of "all other panels should also be easy to configure".
+
+Without that, the platform still has hidden coupling even if execution becomes config-driven.
+
+---
+
+## Modularity Model
+
+Backstage's extension-point guidance is a strong pattern to follow here. MachinaOs should expose narrow extension points instead of one central mutable registry.
+
+Recommended extension points:
+
+- `NodeSpecProvider`
+- `RuntimeProvider`
+- `CredentialProvider`
+- `InspectorRendererProvider`
+- `OutputRendererProvider`
+- `ValidationRuleProvider`
+- `DocsProvider`
+
+Each should stay small. Adding a new node should usually install data into existing extension points, not require touching a large central switchboard.
+
+---
+
+## Proposed Production Choice For MachinaOs
+
+If the goal is to choose one production direction instead of inventing another orchestration model, the cleanest combination is:
+
+- Temporal for durable orchestration and waiting states
+- queue-specialized workers for node execution
+- JSON Schema plus `uiSchema` for node configuration contracts
+- React Flow only as the authoring and graph visualization layer
+- Backstage-style extension points for modularity
+- CRD-like versioned `NodeSpec` resources for compatibility
+
+This combination is source-aligned and fits the current repo better than a full rewrite.
+
+---
+
+## Tradeoffs
+
+### What this architecture improves
+
+- resilience
+- worker isolation
+- scaling clarity
+- node onboarding ergonomics
+- compatibility and versioning
+- observability
+
+### What it costs
+
+- more explicit platform boundaries
+- a compilation step
+- more infrastructure than a single process
+- a real contract for node specs and versioning
+- migration work from the current code-first node model
+
+These are good costs if the goal is a trustworthy production system instead of a fast-growing monolith.
+
+---
+
+## Recommended Next Steps For This Repo
+
+1. Make one versioned `NodeSpec` the canonical source of truth for node metadata.
+2. Reduce the WebSocket surface so it is primarily for subscriptions, not universal write traffic.
+3. Split `Dashboard.tsx` and `WebSocketContext.tsx` into smaller bounded modules.
+4. Introduce subflows and collapse as first-class editor concepts.
+5. Create explicit worker capability pools and corresponding queue names.
+6. Move large outputs to an artifact-first model.
+7. Pin workflow runs to node versions and preserve backward compatibility for saved workflows.
+
+---
+
+## Source Bibliography
+
+All links below are the primary sources used for this document.
+
+- [Temporal Docs](https://docs.temporal.io/)
+- [Conductor Architecture Overview](https://conductor-oss.github.io/conductor/devguide/architecture/index.html)
+- [Conductor Workers](https://conductor-oss.github.io/conductor/devguide/concepts/workers.html)
+- [Conductor Scaling Workers](https://conductor-oss.github.io/conductor/devguide/how-tos/Workers/scaling-workers.html)
+- [React Flow Performance](https://reactflow.dev/learn/advanced-use/performance)
+- [React Flow Expand and Collapse](https://reactflow.dev/examples/layout/expand-collapse)
+- [React Flow Auto Layout](https://reactflow.dev/examples/layout/auto-layout)
+- [n8n Choose Node Building Approach](https://docs.n8n.io/integrations/creating-nodes/plan/choose-node-method/)
+- [n8n Node Base File Reference](https://docs.n8n.io/integrations/creating-nodes/build/reference/node-base-files/)
+- [n8n Node Versioning](https://docs.n8n.io/integrations/creating-nodes/build/reference/node-versioning/)
+- [JSON Schema Reference](https://json-schema.org/understanding-json-schema)
+- [JSON Schema Dialect and Vocabulary Declaration](https://json-schema.org/understanding-json-schema/reference/schema)
+- [Backstage Backend Architecture](https://backstage.io/docs/backend-system/architecture/index/)
+- [Backstage Extension Points](https://backstage.io/docs/backend-system/architecture/extension-points/)
+- [Backstage Modules](https://backstage.io/docs/next/backend-system/architecture/modules)
+- [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/api-extension/custom-resources/)
+- [Kubernetes CRD Structural Schema Guide](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
+- [Kubernetes CRD Versioning](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning)
+- [react-jsonschema-form uiSchema](https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema/)
diff --git a/package.json b/package.json
index 3885bb02..6ac7a2ee 100644
--- a/package.json
+++ b/package.json
@@ -66,9 +66,9 @@
"client:start": "cd client && npm run start",
"python:start": "cd server && uv run uvicorn main:app --host 127.0.0.1 --port 3010 --log-level warning",
"python:daemon": "cd server && uv run uvicorn main:app --host 0.0.0.0 --port 3010 --log-level warning",
- "temporal:start": "temporal-server api",
- "temporal:stop": "temporal-server stop",
- "temporal:status": "temporal-server status",
+ "temporal:start": "temporal api",
+ "temporal:stop": "temporal stop",
+ "temporal:status": "temporal status",
"temporal:worker": "cd server && uv run python -m services.temporal.worker",
"whatsapp:start": "edgymeow start",
"whatsapp:stop": "edgymeow stop",
@@ -96,9 +96,9 @@
"concurrently": "^9.2.1",
"cross-env": "^7.0.3",
"rimraf": "^6.0.1",
- "temporal-server": "^0.0.9",
+ "temporal-server": "^0.0.10",
"agent-browser": "latest",
- "edgymeow": "^0.0.19"
+ "edgymeow": "^0.0.18"
},
"pnpm": {
"peerDependencyRules": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4789a772..d3d71896 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -10,7 +10,7 @@ importers:
dependencies:
agent-browser:
specifier: latest
- version: 0.25.3
+ version: 0.25.4
concurrently:
specifier: ^9.2.1
version: 9.2.1
@@ -18,14 +18,14 @@ importers:
specifier: ^7.0.3
version: 7.0.3
edgymeow:
- specifier: ^0.0.19
- version: 0.0.19
+ specifier: ^0.0.18
+ version: 0.0.18
rimraf:
specifier: ^6.0.1
version: 6.1.2
temporal-server:
- specifier: ^0.0.9
- version: 0.0.9
+ specifier: ^0.0.10
+ version: 0.0.10
client:
dependencies:
@@ -1702,8 +1702,8 @@ packages:
resolution: {integrity: sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==}
engines: {node: '>= 6.0.0'}
- resolution: {integrity: sha512-9qdD8Fe22fXHB9nEfWzZ31/16EjeHBbXXue44SoJt+8LpyZS07dV/aQR2B2LevLL8eCneJBOhqvEBP2lP0NwJw==}
+ resolution: {integrity: sha512-vl4tzDAk5+pJ2g8eMWWzZOLJ2yevJDN3YQ1gcSdN3GKPI0RwNr+T/2PxqSxsipiREu0oid2yxFJIoQ6NMrq/fQ==}
hasBin: true
@@ -2245,8 +2245,8 @@ packages:
resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
engines: {node: '>= 0.4'}
- resolution: {integrity: sha512-i5poUpZGPrCnaK5D10PlVg91fHdrpqdjwr7dV/MMlbDFHU2YhRWfZ91g6/+NjvcclMqs5ILU8OFWlIujYBGslw==}
+ resolution: {integrity: sha512-+iWozBpK7zOdOqvlFK9AaWKENzcaLdMzSOnivKIg5ynCIBMxUlUoTnGlwt6m8HpG4d30iI3OWA9jtyO4lBlS/A==}
engines: {node: '>=18.0.0'}
hasBin: true
@@ -4172,8 +4172,8 @@ packages:
resolution: {integrity: sha512-rzS0heiNf8Xn7/mpdSVVSMAWAoy9bfb1WOTYC78Z0UQKeKa/CWS8FOq0lKGNa8DWKAn9gxjCvMLYc5PGXYlK2A==}
engines: {node: '>= 0.8.0'}
- resolution: {integrity: sha512-mbgC8EX5wXHTVScx7hCHDnJoi5cMpihK3cfx56LqRfg7Wdx6CsOY/3LAUaA9RFLZVjbegAbl/+RgS8tceB82SA==}
+ resolution: {integrity: sha512-8aDRZSn2Fxusa+/Vh2hIbX+aOvM5x7NQl6mtdLRBvTVVQsINcYGf/TjFD6na3xPos0bWQlTZr7S8+kq1kazh8Q==}
engines: {node: '>=18.0.0'}
hasBin: true
@@ -6237,7 +6237,7 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
@@ -6895,7 +6895,7 @@ snapshots:
es-errors: 1.3.0
gopd: 1.2.0
dependencies:
chalk: 5.6.2
commander: 11.1.0
@@ -9488,7 +9488,7 @@ snapshots:
to-buffer: 1.2.2
xtend: 4.0.2
dependencies:
chalk: 5.6.2
commander: 11.1.0
diff --git a/scripts/install.js b/scripts/install.js
index cb595eb0..3af69c5a 100755
--- a/scripts/install.js
+++ b/scripts/install.js
@@ -118,14 +118,14 @@ if (uvVersion) {
}
}
-// Check/Install temporal-server (global CLI)
-let temporalVersion = getVersion('temporal-server --version');
+// Check/Install temporal-server (global CLI, binary name: temporal)
+let temporalVersion = getVersion('temporal --version');
if (temporalVersion) {
console.log(` temporal-server: ${temporalVersion}`);
} else {
console.log(' temporal-server: not found, installing...');
run('npm install -g temporal-server');
- temporalVersion = getVersion('temporal-server --version');
+ temporalVersion = getVersion('temporal --version');
if (temporalVersion) {
console.log(` temporal-server: ${temporalVersion}`);
} else {
diff --git a/scripts/start.js b/scripts/start.js
index d4ef398c..c95abd3a 100755
--- a/scripts/start.js
+++ b/scripts/start.js
@@ -49,11 +49,11 @@ async function main() {
ensureEnvFile();
// Check if Temporal is already running via CLI
- // (temporal-server api exits immediately if already up, which triggers
+ // (temporal api exits immediately if already up, which triggers
// --kill-others and kills all services)
let temporalRunning = false;
try {
- const status = execSync('temporal-server status', { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
+ const status = execSync('temporal status', { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
temporalRunning = /running|UP/i.test(status);
} catch {
temporalRunning = false;
diff --git a/server/config/model_registry.json b/server/config/model_registry.json
index d3df9c59..6175adfc 100644
--- a/server/config/model_registry.json
+++ b/server/config/model_registry.json
@@ -1,5 +1,5 @@
{
- "_generated": "2026-04-10T20:32:20.583411+00:00",
+ "_generated": "2026-04-11T22:43:55.565493+00:00",
"_source": "openrouter",
"_model_count": 350,
"models": {
@@ -119,7 +119,6 @@
"frequency_penalty",
"include_reasoning",
"logit_bias",
- "logprobs",
"max_tokens",
"presence_penalty",
"reasoning",
@@ -132,7 +131,6 @@
"tool_choice",
"tools",
"top_k",
- "top_logprobs",
"top_p"
]
},
@@ -184,7 +182,6 @@
"frequency_penalty",
"include_reasoning",
"logit_bias",
- "logprobs",
"max_tokens",
"presence_penalty",
"reasoning",
@@ -197,7 +194,6 @@
"tool_choice",
"tools",
"top_k",
- "top_logprobs",
"top_p"
]
},
@@ -2307,7 +2303,7 @@
"provider": "openai",
"local_id": "gpt-5.2-chat",
"context_length": 128000,
- "max_output_tokens": 16384,
+ "max_output_tokens": 32000,
"input_price_per_mtok": 1.75,
"output_price_per_mtok": 14.0,
"supports_thinking": true,
@@ -3112,7 +3108,7 @@
"provider": "openai",
"local_id": "gpt-5.1-codex-mini",
"context_length": 400000,
- "max_output_tokens": 100000,
+ "max_output_tokens": 128000,
"input_price_per_mtok": 0.25,
"output_price_per_mtok": 2.0,
"supports_thinking": true,
@@ -4590,7 +4586,6 @@
"logit_bias",
"logprobs",
"max_tokens",
- "min_p",
"presence_penalty",
"repetition_penalty",
"response_format",
@@ -5037,7 +5032,7 @@
"provider": "openai",
"local_id": "gpt-5-nano",
"context_length": 400000,
- "max_output_tokens": 128000,
+ "max_output_tokens": 0,
"input_price_per_mtok": 0.05,
"output_price_per_mtok": 0.4,
"supports_thinking": true,
@@ -5158,9 +5153,9 @@
"provider": "openai",
"local_id": "gpt-oss-20b",
"context_length": 131072,
- "max_output_tokens": 131072,
+ "max_output_tokens": 0,
"input_price_per_mtok": 0.03,
- "output_price_per_mtok": 0.11,
+ "output_price_per_mtok": 0.14,
"supports_thinking": true,
"thinking_type": "effort",
"temperature_range": [
@@ -6338,7 +6333,7 @@
"name": "Anthropic: Claude Sonnet 4",
"provider": "anthropic",
"local_id": "claude-sonnet-4",
- "context_length": 200000,
+ "context_length": 1000000,
"max_output_tokens": 64000,
"input_price_per_mtok": 3.0,
"output_price_per_mtok": 15.0,
@@ -6939,7 +6934,7 @@
"provider": "openai",
"local_id": "gpt-4.1",
"context_length": 1047576,
- "max_output_tokens": 32768,
+ "max_output_tokens": 0,
"input_price_per_mtok": 2.0,
"output_price_per_mtok": 8.0,
"supports_thinking": false,
@@ -7331,10 +7326,10 @@
"name": "Mistral: Mistral Small 3.1 24B",
"provider": "mistralai",
"local_id": "mistral-small-3.1-24b-instruct",
- "context_length": 131072,
- "max_output_tokens": 131072,
- "input_price_per_mtok": 0.03,
- "output_price_per_mtok": 0.11,
+ "context_length": 128000,
+ "max_output_tokens": 0,
+ "input_price_per_mtok": 0.35,
+ "output_price_per_mtok": 0.56,
"supports_thinking": false,
"thinking_type": "none",
"temperature_range": [
@@ -7347,10 +7342,7 @@
"max_tokens",
"presence_penalty",
"repetition_penalty",
- "response_format",
"seed",
- "stop",
- "structured_outputs",
"temperature",
"top_k",
"top_p"
@@ -7818,7 +7810,7 @@
"provider": "anthropic",
"local_id": "claude-3.7-sonnet",
"context_length": 200000,
- "max_output_tokens": 64000,
+ "max_output_tokens": 128000,
"input_price_per_mtok": 3.0,
"output_price_per_mtok": 15.0,
"supports_thinking": true,
@@ -9215,8 +9207,8 @@
"local_id": "llama-3.2-11b-vision-instruct",
"context_length": 131072,
"max_output_tokens": 16384,
- "input_price_per_mtok": 0.049,
- "output_price_per_mtok": 0.049,
+ "input_price_per_mtok": 0.245,
+ "output_price_per_mtok": 0.245,
"supports_thinking": false,
"thinking_type": "none",
"temperature_range": [
@@ -9270,15 +9262,15 @@
"top_p"
]
},
- "cohere/command-r-08-2024": {
- "id": "cohere/command-r-08-2024",
- "name": "Cohere: Command R (08-2024)",
+ "cohere/command-r-plus-08-2024": {
+ "id": "cohere/command-r-plus-08-2024",
+ "name": "Cohere: Command R+ (08-2024)",
"provider": "cohere",
- "local_id": "command-r-08-2024",
+ "local_id": "command-r-plus-08-2024",
"context_length": 128000,
"max_output_tokens": 4000,
- "input_price_per_mtok": 0.15,
- "output_price_per_mtok": 0.6,
+ "input_price_per_mtok": 2.5,
+ "output_price_per_mtok": 10.0,
"supports_thinking": false,
"thinking_type": "none",
"temperature_range": [
@@ -9301,15 +9293,15 @@
"top_p"
]
},
- "cohere/command-r-plus-08-2024": {
- "id": "cohere/command-r-plus-08-2024",
- "name": "Cohere: Command R+ (08-2024)",
+ "cohere/command-r-08-2024": {
+ "id": "cohere/command-r-08-2024",
+ "name": "Cohere: Command R (08-2024)",
"provider": "cohere",
- "local_id": "command-r-plus-08-2024",
+ "local_id": "command-r-08-2024",
"context_length": 128000,
"max_output_tokens": 4000,
- "input_price_per_mtok": 2.5,
- "output_price_per_mtok": 10.0,
+ "input_price_per_mtok": 0.15,
+ "output_price_per_mtok": 0.6,
"supports_thinking": false,
"thinking_type": "none",
"temperature_range": [
@@ -9798,15 +9790,15 @@
"top_p"
]
},
- "openai/gpt-4o": {
- "id": "openai/gpt-4o",
- "name": "OpenAI: GPT-4o",
+ "openai/gpt-4o-2024-05-13": {
+ "id": "openai/gpt-4o-2024-05-13",
+ "name": "OpenAI: GPT-4o (2024-05-13)",
"provider": "openai",
- "local_id": "gpt-4o",
+ "local_id": "gpt-4o-2024-05-13",
"context_length": 128000,
- "max_output_tokens": 16384,
- "input_price_per_mtok": 2.5,
- "output_price_per_mtok": 10.0,
+ "max_output_tokens": 4096,
+ "input_price_per_mtok": 5.0,
+ "output_price_per_mtok": 15.0,
"supports_thinking": false,
"thinking_type": "none",
"temperature_range": [
@@ -9833,15 +9825,15 @@
"web_search_options"
]
},
- "openai/gpt-4o:extended": {
- "id": "openai/gpt-4o:extended",
- "name": "OpenAI: GPT-4o (extended)",
+ "openai/gpt-4o": {
+ "id": "openai/gpt-4o",
+ "name": "OpenAI: GPT-4o",
"provider": "openai",
- "local_id": "gpt-4o:extended",
+ "local_id": "gpt-4o",
"context_length": 128000,
- "max_output_tokens": 64000,
- "input_price_per_mtok": 6.0,
- "output_price_per_mtok": 18.0,
+ "max_output_tokens": 16384,
+ "input_price_per_mtok": 2.5,
+ "output_price_per_mtok": 10.0,
"supports_thinking": false,
"thinking_type": "none",
"temperature_range": [
@@ -9853,6 +9845,7 @@
"frequency_penalty",
"logit_bias",
"logprobs",
+ "max_completion_tokens",
"max_tokens",
"presence_penalty",
"response_format",
@@ -9867,15 +9860,15 @@
"web_search_options"
]
},
- "openai/gpt-4o-2024-05-13": {
- "id": "openai/gpt-4o-2024-05-13",
- "name": "OpenAI: GPT-4o (2024-05-13)",
+ "openai/gpt-4o:extended": {
+ "id": "openai/gpt-4o:extended",
+ "name": "OpenAI: GPT-4o (extended)",
"provider": "openai",
- "local_id": "gpt-4o-2024-05-13",
+ "local_id": "gpt-4o:extended",
"context_length": 128000,
- "max_output_tokens": 4096,
- "input_price_per_mtok": 5.0,
- "output_price_per_mtok": 15.0,
+ "max_output_tokens": 64000,
+ "input_price_per_mtok": 6.0,
+ "output_price_per_mtok": 18.0,
"supports_thinking": false,
"thinking_type": "none",
"temperature_range": [
@@ -9887,7 +9880,6 @@
"frequency_penalty",
"logit_bias",
"logprobs",
- "max_completion_tokens",
"max_tokens",
"presence_penalty",
"response_format",
diff --git a/server/main.py b/server/main.py
index 4d90d8e0..69bfce59 100644
--- a/server/main.py
+++ b/server/main.py
@@ -20,6 +20,7 @@ try:
except ImportError:
pass # Windows - uvloop not available, use default asyncio
+import asyncio
from datetime import datetime
from contextlib import asynccontextmanager
@@ -31,7 +32,6 @@ from contextlib import asynccontextmanager
_startup_log("Importing FastAPI...")
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import ORJSONResponse
_startup_log("Importing DI container + all services...")
from core.container import container
@@ -128,7 +128,6 @@ async def lifespan(app: FastAPI):
logger.info("Execution recovery sweeper started")
# Start WebSocket logging handler to broadcast logs to frontend
- import asyncio
loop = asyncio.get_running_loop()
setup_websocket_logging(loop)
logger.info("WebSocket logging handler started")
@@ -186,50 +185,76 @@ async def lifespan(app: FastAPI):
# Record startup time for health reporting
set_startup_time()
- # Initialize Temporal if enabled
- temporal_worker_manager = None
+ # Initialize Temporal in the background - do NOT block lifespan startup.
+ # scripts/start.js launches the Python backend and temporal-server concurrently,
+ # so on fresh startup temporal-server may take several seconds to become reachable.
+ # Blocking the lifespan here would delay FastAPI HTTP serving and cascade into
+ # frontend ERR_CONNECTION_REFUSED on /api/auth/status. Instead, yield fast and
+ # let Temporal init happen in a background task. WorkflowService falls back to
+ # parallel/sequential execution until Temporal is ready.
+ app.state.temporal_worker_manager = None
+ temporal_init_task: asyncio.Task | None = None
+
if settings.temporal_enabled:
- _startup_log(f"[Temporal] Connecting to {settings.temporal_server_address}...")
- from services.temporal import TemporalClientWrapper, TemporalExecutor
+ from services.temporal import TemporalExecutor
from services.temporal.worker import TemporalWorkerManager
logger.info(
- "Initializing Temporal integration",
+ "Scheduling Temporal initialization in background",
server_address=settings.temporal_server_address,
namespace=settings.temporal_namespace,
task_queue=settings.temporal_task_queue,
)
+ _startup_log(f"[Temporal] Init scheduled for {settings.temporal_server_address}")
- # Connect Temporal client (retries up to 10 times to allow temporal-server startup)
- temporal_client_wrapper = container.temporal_client()
- temporal_client = await temporal_client_wrapper.connect(retries=10, delay=3.0)
-
- if temporal_client is not None:
- # Create and set the Temporal executor on WorkflowService
- temporal_executor = TemporalExecutor(
- client=temporal_client,
- task_queue=settings.temporal_task_queue,
- )
- container.workflow_service().set_temporal_executor(temporal_executor)
+ async def _init_temporal_background() -> None:
+ """Connect, wire executor, start worker. Retries every 3s until connected.
- # Start embedded Temporal worker
- temporal_worker_manager = TemporalWorkerManager(
- client=temporal_client,
- task_queue=settings.temporal_task_queue,
- )
- await temporal_worker_manager.start()
-
- _startup_log("[Temporal] Worker started, execution engine ready")
- logger.info("Temporal integration initialized successfully")
- else:
- _startup_log("[Temporal] Server not reachable, using local execution")
- logger.warning(
- f"Temporal server not reachable at {settings.temporal_server_address}. "
- "Falling back to local parallel/sequential execution. "
- "Start Temporal server and restart to enable durable workflows."
- )
- # Start background reconnect loop (tries every 30s)
- await temporal_client_wrapper.start_background_reconnect(interval=30.0)
+ This task is the single source of truth for Temporal lifecycle during
+ startup. It replaces the previous blocking-connect + background-reconnect
+ split, which blocked the lifespan for up to 30s and left the executor
+ unwired after an initial failed connect.
+ """
+ temporal_client_wrapper = container.temporal_client()
+ attempt = 0
+ while True:
+ attempt += 1
+ client = await temporal_client_wrapper.connect(retries=1, delay=0)
+ if client is not None:
+ try:
+ temporal_executor = TemporalExecutor(
+ client=client,
+ task_queue=settings.temporal_task_queue,
+ )
+ container.workflow_service().set_temporal_executor(temporal_executor)
+
+ worker_manager = TemporalWorkerManager(
+ client=client,
+ task_queue=settings.temporal_task_queue,
+ )
+ await worker_manager.start()
+ app.state.temporal_worker_manager = worker_manager
+
+ _startup_log(
+ f"[Temporal] Worker started, execution engine ready (attempt {attempt})"
+ )
+ logger.info(
+ "Temporal integration initialized successfully",
+ attempts=attempt,
+ )
+ return
+ except Exception as exc:
+ logger.error(
+ "Temporal executor/worker setup failed; will retry",
+ error=str(exc),
+ )
+ # Drop the client so the next iteration reconnects cleanly.
+ await temporal_client_wrapper.disconnect()
+ await asyncio.sleep(3.0)
+
+ temporal_init_task = asyncio.create_task(
+ _init_temporal_background(), name="temporal-init"
+ )
else:
_startup_log("[Temporal] Disabled")
@@ -241,12 +266,24 @@ async def lifespan(app: FastAPI):
# Stop WebSocket logging handler
shutdown_websocket_logging()
- # Stop Temporal worker if running
- if temporal_worker_manager is not None:
- await temporal_worker_manager.stop()
- logger.info("Temporal worker stopped")
+ # Cancel Temporal init task if it's still trying to connect.
+ if temporal_init_task is not None and not temporal_init_task.done():
+ temporal_init_task.cancel()
+ try:
+ await temporal_init_task
+ except (asyncio.CancelledError, Exception):
+ pass
+
+ # Stop Temporal worker if it successfully started.
+ worker_manager = getattr(app.state, "temporal_worker_manager", None)
+ if worker_manager is not None:
+ try:
+ await worker_manager.stop()
+ logger.info("Temporal worker stopped")
+ except Exception as exc:
+ logger.warning(f"Temporal worker stop raised: {exc}")
- # Disconnect Temporal client (also cancels background reconnect)
+ # Disconnect Temporal client.
if settings.temporal_enabled:
try:
temporal_client_wrapper = container.temporal_client()
@@ -265,6 +302,10 @@ async def lifespan(app: FastAPI):
from services.android.manager import close_relay_client
await close_relay_client(clear_stored_session=False)
+ # Shut down agent-browser daemon (prevents orphaned processes and EBUSY file locks)
+ from services.browser_service import shutdown_browser_service
+ await shutdown_browser_service()
+
# Stop cleanup service
if cleanup_service is not None:
await cleanup_service.stop()
@@ -286,7 +327,6 @@ app = FastAPI(
version="3.0.0",
description="Modern workflow automation backend with AI and Maps integration",
lifespan=lifespan,
- default_response_class=ORJSONResponse
)
# Add exception handler middleware BEFORE CORS to catch all errors
diff --git a/server/models/nodes.py b/server/models/nodes.py
index c8665d75..55149589 100644
--- a/server/models/nodes.py
+++ b/server/models/nodes.py
@@ -73,6 +73,22 @@ class ChatAgentParams(BaseNodeParams):
api_key: Optional[str] = Field(default=None, alias="apiKey")
+class SpecializedAgentParams(BaseNodeParams):
+ """Parameters for all specialized agent nodes (same structure as AIAgentParams)."""
+ type: Literal[
+ "android_agent", "coding_agent", "web_agent", "task_agent",
+ "social_agent", "travel_agent", "tool_agent", "productivity_agent",
+ "payments_agent", "consumer_agent", "autonomous_agent",
+ "orchestrator_agent", "ai_employee", "rlm_agent", "claude_code_agent",
+ "deep_agent",
+ ]
+ prompt: str = ""
+ provider: str = "openai"
+ model: str = ""
+ system_message: Optional[str] = Field(default="", alias="systemMessage")
+ api_key: Optional[str] = Field(default=None, alias="apiKey")
+
+
class SimpleMemoryParams(BaseNodeParams):
"""Parameters for simple memory node."""
type: Literal["simpleMemory"]
@@ -320,7 +336,7 @@ class ChatHistoryParams(BaseNodeParams):
# AI Nodes
AINodeParams = Annotated[
- Union[AIChatModelParams, AIAgentParams, ChatAgentParams, SimpleMemoryParams],
+ Union[AIChatModelParams, AIAgentParams, ChatAgentParams, SpecializedAgentParams, SimpleMemoryParams],
Field(discriminator="type")
]
@@ -371,7 +387,7 @@ ChatNodeParams = Annotated[
KnownNodeParams = Annotated[
Union[
# AI
- AIChatModelParams, AIAgentParams, ChatAgentParams, SimpleMemoryParams,
+ AIChatModelParams, AIAgentParams, ChatAgentParams, SpecializedAgentParams, SimpleMemoryParams,
# Maps
CreateMapParams, GmapsLocationsParams, GmapsNearbyPlacesParams,
# WhatsApp
diff --git a/server/routers/whatsapp.py b/server/routers/whatsapp.py
index cf0e472a..cedcefaf 100644
--- a/server/routers/whatsapp.py
+++ b/server/routers/whatsapp.py
@@ -81,11 +81,13 @@ class RPCClient:
self._event_handler = handler
async def connect(self):
- # 2 second timeout for initial connection (fail fast if Go service not running)
+ # 5 second timeout for initial connection (fail fast if Go service not running).
+ # The WebSocket handshake to the Go service can take 2-3s on Windows,
+ # especially on cold start when Defender is scanning the binary.
logger.info(f"[WhatsApp RPC] Connecting to {self.url}...")
self.ws = await asyncio.wait_for(
websockets.connect(self.url, ping_interval=30, max_size=100*1024*1024),
- timeout=2.0
+ timeout=5.0
)
self._connected = True
logger.info("[WhatsApp RPC] WebSocket connected, starting receive loop")
diff --git a/server/services/agents/adapters.py b/server/services/agents/adapters.py
index c768b0ba..4635bcc5 100644
--- a/server/services/agents/adapters.py
+++ b/server/services/agents/adapters.py
@@ -57,9 +57,12 @@ class ToolAdapter:
executable.append(
ToolAdapter._wrap(tool, config, workflow_id, broadcaster)
)
+ logger.info("[DeepAgent] Built tool: %s (node=%s, type=%s)",
+ tool.name, config.get('node_id'), tool_info.get('node_type'))
except Exception as e:
logger.warning("[DeepAgent] Failed to build tool from %s: %s",
tool_info.get("node_type"), e)
+ logger.info("[DeepAgent] %d tool(s) ready", len(executable))
return executable
@staticmethod
@@ -67,10 +70,16 @@ class ToolAdapter:
"""Replace placeholder func with a real async executor."""
tool_name = tool.name
tool_node_id = config.get('node_id')
+ tool_node_type = config.get('node_type', '')
async def _execute(**kwargs) -> Any:
+ import time
from services.handlers.tools import execute_tool
+ logger.info("[DeepAgent] Tool call: %s (type=%s) args=%s",
+ tool_name, tool_node_type, {k: str(v)[:200] for k, v in kwargs.items()})
+ t0 = time.time()
+
if tool_node_id and broadcaster:
await broadcaster.update_node_status(
tool_node_id, "executing",
@@ -81,15 +90,19 @@ class ToolAdapter:
cfg = {**config, 'workflow_id': workflow_id}
try:
result = await execute_tool(tool_name, kwargs, cfg)
+ elapsed = time.time() - t0
+ logger.info("[DeepAgent] Tool done: %s (%.2fs) success=%s",
+ tool_name, elapsed, result.get('success', True) if isinstance(result, dict) else True)
if tool_node_id and broadcaster:
await broadcaster.update_node_status(
tool_node_id, "success",
- {"message": f"{tool_name} completed"},
+ {"message": f"{tool_name} completed ({elapsed:.1f}s)"},
workflow_id=workflow_id,
)
return result
except Exception as e:
- logger.error("[DeepAgent] Tool %s failed: %s", tool_name, e)
+ elapsed = time.time() - t0
+ logger.error("[DeepAgent] Tool failed: %s (%.2fs) error=%s", tool_name, elapsed, e)
if tool_node_id and broadcaster:
await broadcaster.update_node_status(
tool_node_id, "error",
diff --git a/server/services/agents/service.py b/server/services/agents/service.py
index 616b679e..315ef0b1 100644
--- a/server/services/agents/service.py
+++ b/server/services/agents/service.py
@@ -115,6 +115,15 @@ class DeepAgentService:
workspace_dir = parameters.get('workspace_dir', '')
executable_tools = await ToolAdapter._build_tools_async(tool_data, build_tool_fn, workflow_id, broadcaster, workspace_dir)
+ # If write_todos tool is connected, add planning instructions to system message
+ has_todos = any(t.get('node_type') == 'writeTodos' for t in (tool_data or []))
+ if has_todos:
+ system_message += (
+ "\n\nYou have a `write_todos` tool. For any task with 3+ steps, "
+ "ALWAYS call write_todos first to plan, then update it after each step "
+ "(mark completed, set next in_progress). The user sees your progress live."
+ )
+
# === Convert teammates via SubAgentAdapter ===
subagents = SubAgentAdapter.convert(teammates) if teammates else None
diff --git a/server/services/browser_service.py b/server/services/browser_service.py
index 96b06338..6c74d617 100644
--- a/server/services/browser_service.py
+++ b/server/services/browser_service.py
@@ -87,6 +87,10 @@ class BrowserService:
headed: bool = False,
user_agent: Optional[str] = None,
proxy: Optional[str] = None,
+ executable_path: Optional[str] = None,
+ auto_connect: bool = False,
+ chrome_profile: Optional[str] = None,
+ new_window: bool = False,
) -> Dict[str, Any]:
"""Execute an agent-browser command and return parsed JSON output.
@@ -101,6 +105,14 @@ class BrowserService:
]
if headed:
argv.append("--headed")
+ if auto_connect:
+ argv.append("--auto-connect")
+ if executable_path:
+ argv.extend(["--executable-path", executable_path])
+ if new_window:
+ argv.extend(["--args", "--new-window"])
+ if chrome_profile:
+ argv.extend(["--profile", chrome_profile])
if user_agent:
argv.extend(["--user-agent", user_agent])
if proxy:
@@ -193,3 +205,25 @@ def get_browser_service() -> Optional[BrowserService]:
if cmd:
_instance = BrowserService(cmd)
return _instance
+
+
+async def shutdown_browser_service() -> None:
+ """Close all browser sessions via `agent-browser close --all`.
+
+ Called during FastAPI lifespan shutdown. This is the daemon's intended
+ cleanup API -- it stops the background process and releases file locks.
+ """
+ svc = get_browser_service()
+ if not svc:
+ return
+ try:
+ await asyncio.to_thread(
+ subprocess.run,
+ [*svc._prefix, "close", "--all"],
+ timeout=5,
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ logger.info("agent-browser daemon shut down")
+ except Exception as e:
+ logger.debug("agent-browser shutdown skipped: %s", e)
diff --git a/server/services/handlers/browser.py b/server/services/handlers/browser.py
index f5f58d56..cd3aeb30 100644
--- a/server/services/handlers/browser.py
+++ b/server/services/handlers/browser.py
@@ -4,11 +4,84 @@ Maps operation + parameters to CLI arguments, calls service, wraps response.
"""
import json
+import shutil
+import sys
import time
-from typing import Any, Dict
+from typing import Any, Dict, Optional
+from core.logging import get_logger
from services.browser_service import get_browser_service
+logger = get_logger(__name__)
+
+
+# PATH-based names for shutil.which() (Linux/macOS/Windows where on PATH).
+_BROWSER_PATH_NAMES = {
+ "chrome": ["google-chrome", "google-chrome-stable", "chrome"],
+ "edge": ["microsoft-edge", "microsoft-edge-stable", "msedge"],
+ "chromium": ["chromium", "chromium-browser"],
+}
+
+# Windows registry App Paths keys (how Selenium/Playwright find browsers).
+_BROWSER_REGISTRY_KEYS = {
+ "chrome": "chrome.exe",
+ "edge": "msedge.exe",
+ "chromium": "chrome.exe",
+}
+
+
+def _find_browser_via_registry(exe_name: str) -> Optional[str]:
+ """Find a browser executable via the Windows App Paths registry.
+
+ This is the standard method used by Selenium and Playwright.
+ HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\<exe>
+ """
+ try:
+ import winreg
+ for hive in (winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER):
+ try:
+ key = winreg.OpenKey(
+ hive,
+ rf"SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\{exe_name}",
+ )
+ path, _ = winreg.QueryValueEx(key, "")
+ winreg.CloseKey(key)
+ if path:
+ return path
+ except OSError:
+ continue
+ except ImportError:
+ pass
+ return None
+
+
+def _resolve_browser(selection: str, custom_path: str) -> Optional[str]:
+ """Resolve a browser dropdown selection to an executable path.
+
+ Tries shutil.which (PATH) first, then Windows registry App Paths.
+ Returns None for 'bundled' (let agent-browser use its own Chrome).
+ """
+ if selection in ("bundled", "bundled_explicit") or not selection:
+ return None
+ if selection == "custom":
+ return custom_path or None
+
+ # Try PATH first (works on Linux/macOS where browsers are on PATH)
+ for name in _BROWSER_PATH_NAMES.get(selection, []):
+ path = shutil.which(name)
+ if path:
+ return path
+
+ # On Windows, query the registry (standard App Paths lookup)
+ if sys.platform == "win32":
+ reg_name = _BROWSER_REGISTRY_KEYS.get(selection)
+ if reg_name:
+ path = _find_browser_via_registry(reg_name)
+ if path:
+ return path
+
+ return None
+
async def handle_browser(
node_id: str,
@@ -29,11 +102,26 @@ async def handle_browser(
)
timeout = int(parameters.get("timeout") or 30)
headed = bool(parameters.get("headed", True))
+ auto_connect = bool(parameters.get("autoConnect", False))
+ browser_sel = parameters.get("browser", "chrome")
+ # "bundled" was the old default before system Chrome became default.
+ # Upgrade it to "chrome". Users who explicitly want bundled pick "bundled_explicit".
+ if not browser_sel or browser_sel == "bundled":
+ browser_sel = "chrome"
+ custom_path = (parameters.get("executablePath") or "").strip()
+ executable_path = _resolve_browser(browser_sel, custom_path)
+ logger.info("[Browser] browser=%s executable=%s", browser_sel, executable_path)
+ new_window = bool(parameters.get("newWindow", True)) and executable_path is not None
+ chrome_profile = (parameters.get("chromeProfile") or "").strip() or None
user_agent = (parameters.get("userAgent") or "").strip() or None
proxy = (parameters.get("proxy") or "").strip() or None
action_delay = int(parameters.get("actionDelay") or 0)
- run_kw = dict(headed=headed, user_agent=user_agent, proxy=proxy)
+ run_kw = dict(
+ headed=headed, user_agent=user_agent, proxy=proxy,
+ executable_path=executable_path, auto_connect=auto_connect,
+ chrome_profile=chrome_profile, new_window=new_window,
+ )
try:
# Native pacing via agent-browser's wait command
@@ -88,6 +176,10 @@ def _build_args(op: str, p: Dict[str, Any]) -> list:
return ["scroll", p.get("direction") or "down", str(p.get("amount") or 500)]
case "select":
return ["select", _req_sel(s), p.get("value") or ""]
+ case "console":
+ return ["console"]
+ case "errors":
+ return ["errors"]
case _:
raise ValueError(f"Unknown operation: {op}")
diff --git a/server/services/handlers/filesystem.py b/server/services/handlers/filesystem.py
index 4924a449..5ce4c4fe 100644
--- a/server/services/handlers/filesystem.py
+++ b/server/services/handlers/filesystem.py
@@ -4,8 +4,12 @@ Uses deepagents.backends.LocalShellBackend methods:
read() -> str, write() -> WriteResult, edit() -> EditResult,
ls_info() -> list[FileInfo], glob_info() -> list[FileInfo],
grep_raw() -> list[GrepMatch] | str, execute() -> ExecuteResponse.
+
+All backend calls are synchronous (subprocess.run / file I/O), so they
+run via asyncio.to_thread() to avoid blocking the event loop.
"""
+import asyncio
import os
from typing import Any, Dict
@@ -22,7 +26,7 @@ def _get_backend(parameters: Dict[str, Any], context: Dict[str, Any] = None):
root = param_dir or ctx_dir or os.getcwd()
logger.info("[Filesystem] root=%s (param=%s, context=%s, fallback_cwd=%s)",
root, param_dir, ctx_dir, os.getcwd())
- return LocalShellBackend(root_dir=root, virtual_mode=True)
+ return LocalShellBackend(root_dir=root, virtual_mode=True, inherit_env=True)
async def handle_file_read(
@@ -35,7 +39,7 @@ async def handle_file_read(
try:
backend = _get_backend(parameters, context)
- content = backend.read(file_path, offset=int(parameters.get('offset', 0)), limit=int(parameters.get('limit', 100)))
+ content = await asyncio.to_thread(backend.read, file_path, offset=int(parameters.get('offset', 0)), limit=int(parameters.get('limit', 100)))
return {
"success": True, "node_id": node_id,
"result": {"content": content, "file_path": file_path},
@@ -58,7 +62,7 @@ async def handle_file_modify(
if operation == 'write':
content = parameters.get('content', '')
- result = backend.write(file_path, content)
+ result = await asyncio.to_thread(backend.write, file_path, content)
if result.error:
return {"success": False, "node_id": node_id, "error": result.error}
return {
@@ -73,7 +77,7 @@ async def handle_file_modify(
if not old_string:
return {"success": False, "node_id": node_id, "error": "old_string is required for edit"}
- result = backend.edit(file_path, old_string, new_string, replace_all=replace_all)
+ result = await asyncio.to_thread(backend.edit, file_path, old_string, new_string, replace_all=replace_all)
if result.error:
return {"success": False, "node_id": node_id, "error": result.error}
return {
@@ -97,7 +101,14 @@ async def handle_shell(
try:
timeout = int(parameters.get('timeout', 30))
backend = _get_backend(parameters, context)
- result = backend.execute(command, timeout=timeout)
+ logger.info("[Shell] Executing (non-blocking): %s (timeout=%ds)", command[:200], timeout)
+ result = await asyncio.to_thread(backend.execute, command, timeout=timeout)
+ if result.exit_code == 124:
+ logger.warning("[Shell] Timed out after %ds: %s", timeout, command[:100])
+ elif result.exit_code != 0:
+ logger.warning("[Shell] Non-zero exit (%d): %s -> %s", result.exit_code, command[:100], result.output[:300])
+ else:
+ logger.info("[Shell] Completed: exit=%d len=%d", result.exit_code, len(result.output))
return {
"success": True, "node_id": node_id,
"result": {
@@ -108,6 +119,7 @@ async def handle_shell(
},
}
except Exception as e:
+ logger.error("[Shell] Failed: %s -> %s", command[:100], e)
return {"success": False, "node_id": node_id, "error": str(e)}
@@ -123,7 +135,7 @@ async def handle_fs_search(
backend = _get_backend(parameters, context)
if mode == 'ls':
- entries = backend.ls_info(path)
+ entries = await asyncio.to_thread(backend.ls_info, path)
return {
"success": True, "node_id": node_id,
"result": {"path": path, "entries": [dict(e) for e in entries], "count": len(entries)},
@@ -132,7 +144,7 @@ async def handle_fs_search(
elif mode == 'glob':
if not pattern:
return {"success": False, "node_id": node_id, "error": "pattern is required for glob mode"}
- matches = backend.glob_info(pattern, path=path)
+ matches = await asyncio.to_thread(backend.glob_info, pattern, path=path)
return {
"success": True, "node_id": node_id,
"result": {"path": path, "pattern": pattern, "matches": [dict(m) for m in matches], "count": len(matches)},
@@ -142,7 +154,7 @@ async def handle_fs_search(
if not pattern:
return {"success": False, "node_id": node_id, "error": "pattern is required for grep mode"}
file_filter = parameters.get('file_filter') or None
- result = backend.grep_raw(pattern, path=path, glob=file_filter)
+ result = await asyncio.to_thread(backend.grep_raw, pattern, path=path, glob=file_filter)
# grep_raw returns list[GrepMatch] or str (error message)
if isinstance(result, str):
return {"success": False, "node_id": node_id, "error": result}
diff --git a/server/services/temporal/activities.py b/server/services/temporal/activities.py
index 85602ab0..17c4987a 100644
--- a/server/services/temporal/activities.py
+++ b/server/services/temporal/activities.py
@@ -175,7 +175,15 @@ class NodeExecutionActivities:
Each call creates a new WebSocket connection from the session's pool,
avoiding race conditions when multiple activities run concurrently.
+
+ Heartbeats are sent both on incoming non-matching messages AND on a
+ 30-second timer. This is critical for long-running nodes (DeepAgent,
+ browser, AI multi-tool) where the backend may be processing internally
+ without broadcasting any WS messages for minutes. Without the periodic
+ timer, the 2-minute heartbeat_timeout would cancel the activity even
+ though the node is actively executing.
"""
+ import asyncio
import json
import uuid
@@ -205,27 +213,34 @@ class NodeExecutionActivities:
async with self.session.ws_connect(
self.ws_url,
heartbeat=30,
- receive_timeout=540,
+ receive_timeout=None, # No receive timeout — we handle liveness via heartbeats
) as ws:
await ws.send_json(message)
- # Wait for response with matching request_id
- # Heartbeat on every non-matching message to stay alive during
- # long-running operations (DeepAgent, browser, AI multi-tool loops)
- async for msg in ws:
+ # Read loop with periodic heartbeat timer.
+ # ws.receive() may block for minutes if the backend is doing
+ # heavy processing without broadcasting. The 30s timeout ensures
+ # we heartbeat at least every 30s regardless of message traffic.
+ while True:
+ try:
+ msg = await asyncio.wait_for(ws.receive(), timeout=30.0)
+ except asyncio.TimeoutError:
+ # No message in 30s — node is still running, send heartbeat
+ activity.heartbeat(f"Waiting for {node_id} ({node_type})")
+ continue
+
if msg.type == aiohttp.WSMsgType.TEXT:
response = json.loads(msg.data)
if response.get("request_id") == request_id:
activity.logger.debug(f"Got response for {node_id}: success={response.get('success')}")
return response
+ # Non-matching message (broadcast to other clients) — heartbeat
activity.heartbeat(f"Waiting for {node_id}")
elif msg.type == aiohttp.WSMsgType.ERROR:
raise Exception(f"WebSocket error: {ws.exception()}")
- elif msg.type == aiohttp.WSMsgType.CLOSED:
+ elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.CLOSING):
raise Exception("WebSocket closed unexpectedly")
- raise Exception(f"No response for request {request_id}")
-
except aiohttp.ClientError as e:
raise Exception(f"WebSocket connection error: {e}")
diff --git a/server/services/temporal/client.py b/server/services/temporal/client.py
index 8b0137b8..d3e96a46 100644
--- a/server/services/temporal/client.py
+++ b/server/services/temporal/client.py
@@ -22,7 +22,6 @@ class TemporalClientWrapper:
self.namespace = namespace
self._client: Optional[Client] = None
self._runtime: Optional[Runtime] = None
- self._reconnect_task: Optional[asyncio.Task] = None
@property
def client(self) -> Optional[Client]:
@@ -87,29 +86,8 @@ class TemporalClientWrapper:
)
return None
- async def start_background_reconnect(self, interval: float = 30.0) -> None:
- """Start a background task that periodically tries to reconnect."""
- if self._reconnect_task is not None:
- return
-
- async def _reconnect_loop():
- while True:
- await asyncio.sleep(interval)
- if self._client is not None:
- continue
- logger.info("Attempting Temporal reconnect...")
- client = await self.connect(retries=1, delay=0)
- if client:
- logger.info("Temporal reconnected successfully")
- break
-
- self._reconnect_task = asyncio.create_task(_reconnect_loop())
-
async def disconnect(self) -> None:
"""Disconnect from the Temporal server."""
- if self._reconnect_task is not None:
- self._reconnect_task.cancel()
- self._reconnect_task = None
if self._client is not None:
self._client = None
logger.info("Disconnected from Temporal server")
diff --git a/server/skills/assistant/assistant-personality/SKILL.md b/server/skills/assistant/assistant-personality/SKILL.md
index 6f27dfb4..e27ebd8f 100644
--- a/server/skills/assistant/assistant-personality/SKILL.md
+++ b/server/skills/assistant/assistant-personality/SKILL.md
@@ -1,9 +1,9 @@
---
name: assistant-personality
-description: General AI assistant with helpful, harmless, and honest responses. Use as the default personality for conversations.
+description: General AI assistant with task planning via write_todos, helpful and honest responses.
metadata:
author: machina
- version: "1.0"
+ version: "2.0"
category: assistant
icon: "✨"
color: "#D97706"
@@ -19,6 +19,17 @@ You are a helpful, harmless, and honest AI assistant. Your goal is to assist use
2. **Honesty**: Be truthful about your capabilities and limitations
3. **Safety**: Avoid generating harmful, illegal, or unethical content
+## Task Planning
+
+When a request involves **3 or more steps**, use the `write_todos` tool to plan and track your work before acting:
+
+1. **Plan first** -- call `write_todos` with a list of actionable steps, mark the first `in_progress`
+2. **Work, then update** -- after each step, call `write_todos` again to mark it `completed` and the next `in_progress`
+3. **Revise as you go** -- add new tasks, remove irrelevant ones, reword as needed
+4. **Complete all** -- keep working until every task is `completed`
+
+For simple requests (1-2 steps), skip the todo list and respond directly.
+
## Communication Style
- Be concise but thorough
@@ -31,17 +42,7 @@ You are a helpful, harmless, and honest AI assistant. Your goal is to assist use
When responding to users:
1. Understand the intent behind their question
-2. Provide the most helpful response possible
-3. Include relevant context or caveats
-4. Suggest follow-up questions if appropriate
-
-## Examples
-
-User: "What's the weather like?"
-Response: I don't have access to real-time weather data. However, I can help you find weather information if you tell me your location, or you can use a weather service like weather.com.
-
-User: "Help me write an email"
-Response: I'd be happy to help you write an email. Could you tell me:
-- Who is the recipient?
-- What is the purpose of the email?
-- What tone would you like (formal, casual, etc.)?
+2. For complex tasks: plan with `write_todos` first, then execute step by step
+3. For simple questions: respond directly
+4. Include relevant context or caveats
+5. Suggest follow-up actions if appropriate
diff --git a/server/skills/coding_agent/shell-skill/SKILL.md b/server/skills/coding_agent/shell-skill/SKILL.md
index 6f625e80..3e45cdb4 100644
--- a/server/skills/coding_agent/shell-skill/SKILL.md
+++ b/server/skills/coding_agent/shell-skill/SKILL.md
@@ -60,7 +60,9 @@ Execute shell commands with timeout control. Uses deepagents LocalShellBackend.
1. Set appropriate timeouts for long-running commands
2. Exit code 0 means success, non-zero means failure
-3. Check `truncated` flag -- output may be cut if too large
-4. Use absolute paths when possible
-5. Chain commands with `&&` for sequential execution
-6. Avoid interactive commands that require user input
+3. Exit code 124 means the command timed out
+4. Check `truncated` flag -- output may be cut if too large
+5. Use absolute paths when possible
+6. Chain commands with `&&` for sequential execution
+7. Avoid interactive commands that require user input
+8. **Do NOT start background servers or daemons** (e.g. `python -m http.server`, `npm start`, `start /B`). The shell waits for the process to exit -- daemons will hang until timeout. Use short-lived commands only.
diff --git a/server/skills/web_agent/browser-skill/SKILL.md b/server/skills/web_agent/browser-skill/SKILL.md
index aca7ffd1..89cd0982 100644
--- a/server/skills/web_agent/browser-skill/SKILL.md
+++ b/server/skills/web_agent/browser-skill/SKILL.md
@@ -1,10 +1,10 @@
---
name: browser-skill
-description: Interactive browser automation - navigate, click, type, fill forms, take screenshots, get accessibility snapshots.
+description: Interactive browser automation - navigate, click, type, fill forms, take screenshots, get accessibility snapshots. Supports system Chrome/Edge via auto-detection.
allowed-tools: browser
metadata:
author: machina
- version: "1.0"
+ version: "2.0"
category: web
icon: "🌐"
color: "#8be9fd"
@@ -26,7 +26,7 @@ Use the **snapshot -> act -> snapshot** loop:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
-| operation | string | Yes | One of: navigate, click, type, fill, screenshot, snapshot, get_text, get_html, eval, wait, scroll, select |
+| operation | string | Yes | One of: navigate, click, type, fill, screenshot, snapshot, get_text, get_html, eval, wait, scroll, select, console, errors |
| url | string | navigate | URL to open |
| selector | string | click/type/fill/get_text/get_html/wait/select | CSS selector or `@eN` ref from snapshot |
| text | string | type | Text to type keystroke by keystroke |
@@ -110,22 +110,61 @@ Select a dropdown option.
{"operation": "select", "selector": "@e5", "value": "option-value"}
```
-## Stealth / Anti-Detection
+### console
+Get browser console output (log, warn, error messages).
+```json
+{"operation": "console"}
+```
+Returns `{"messages": [{"text": "hello", "type": "log"}, ...]}`.
+
+### errors
+Get JavaScript errors from the page.
+```json
+{"operation": "errors"}
+```
+Returns `{"errors": [...]}`.
+
+## Using Your Real Browser
+
+By default the browser node uses a bundled Chromium. To use your system browser (with existing logins, extensions, etc.), select it in the **Browser** dropdown under Advanced:
-The browser node supports configurable settings to reduce bot detection:
+| Option | Description |
+|--------|-------------|
+| **Bundled Chrome** | Default. Downloads and uses its own Chromium. |
+| **Google Chrome** | Auto-detected from system PATH or Windows registry. |
+| **Microsoft Edge** | Auto-detected from system PATH or Windows registry. |
+| **Chromium** | Auto-detected from system PATH or Windows registry. |
+| **Custom Path** | Manually specify an executable path. |
+
+Browser detection uses `shutil.which()` on Linux/macOS (PATH lookup) and the Windows App Paths registry (`HKLM\...\App Paths\chrome.exe`) -- the same method Selenium and Playwright use. No hardcoded paths.
+
+### Additional options
+
+- **New Window**: Opens a new browser window instead of a tab in an existing instance. On by default when using a system browser. Only visible for non-bundled browsers.
+- **Chrome Profile**: Reuse login state from a named Chrome profile (e.g. `Default`, `Profile 1`).
+- **Auto Connect**: Attach to an already-running Chrome with remote debugging:
+ ```
+ chrome --remote-debugging-port=9222
+ ```
+
+### Lifecycle
+
+The browser daemon auto-starts on first use and persists between commands (for session reuse). It is automatically shut down when MachinaOs stops -- no manual cleanup needed.
+
+## Stealth / Anti-Detection
-- **Action Delay**: Set `actionDelay` (ms) in node parameters to add a native wait before each action. Simulates human pacing.
-- **User Agent**: Set `userAgent` to a custom string to override the default Chrome user agent.
-- **Proxy**: Set `proxy` to route all browser traffic through a proxy (e.g. `http://user:pass@host:port`).
+These settings reduce bot detection. Configure them in the node's Advanced section, not as tool arguments.
-These are configured in the node's Advanced section, not as tool arguments.
+- **Action Delay**: Native wait (ms) before each action. Set 500-2000ms for bot-protected sites.
+- **User Agent**: Custom user-agent string to override Chrome default.
+- **Proxy**: Route all browser traffic through a proxy (e.g. `http://user:pass@host:port`).
## Tips
-- Always use `snapshot` first to discover element refs before interacting.
+- Always `snapshot` first to discover `@eN` element refs before interacting.
- Prefer `@eN` refs over CSS selectors -- they are stable across the session.
- Use `fill` for form inputs (clears first), `type` for search boxes (keystroke events).
-- Use `screenshot` to visually verify the page state when uncertain.
-- Use `wait` before interacting with elements that load dynamically.
+- Use `screenshot` to visually verify page state when uncertain.
+- Use `wait` before interacting with dynamically loaded elements.
- Use `eval` sparingly -- prefer snapshot + click/fill for most tasks.
-- Set `actionDelay` to 500-2000ms when interacting with bot-protected sites.
+- Select **Google Chrome** or **Microsoft Edge** in the Browser dropdown to use your real browser with existing logins.