machinaos 0.0.52 → 0.0.53

package/.env.template

@@ -46,6 +46,9 @@ TEMPORAL_SERVER_ADDRESS=localhost:7233
 TEMPORAL_NAMESPACE=default
 TEMPORAL_TASK_QUEUE=machina-tasks
 
+# Per-workflow workspace (nodes save files here, agents access via filesystem tools)
+WORKSPACE_BASE_DIR=data/workspaces
+
 # Logging
 LOG_LEVEL=INFO
 LOG_FORMAT=text

package/README.md

@@ -3,6 +3,7 @@
 <a href="https://www.npmjs.com/package/machinaos" target="_blank"><img src="https://img.shields.io/npm/v/machinaos.svg" alt="npm version"></a>
 <a href="https://opensource.org/licenses/MIT" target="_blank"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 <a href="https://discord.gg/c9pCJ7d8Ce" target="_blank"><img src="https://img.shields.io/discord/1455977012308086895?logo=discord&logoColor=white&label=Discord" alt="Discord"></a>
+<a href="https://deepwiki.com/trohitg/MachinaOS" target="_blank"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
 
 Personal AI Assistant/Co-Employees that Perform Human Like Tasks. Connect AI Assistant to your email, calendar, messages, phone, and more.
 
@@ -134,3 +135,149 @@ Join our [Discord](https://discord.gg/NHUEQVSC) for help, feedback, and updates.
 ## License
 
 MIT
+
+---
+
+## Nerdy Docs
+
+A contributor's map to the codebase. This section tells you *where things live* and *where to start reading* when you want to add a feature. For the full architecture tour, use the [DeepWiki badge](https://deepwiki.com/trohitg/MachinaOS) at the top of this README or browse [docs-internal/](docs-internal/).
+
+### System Overview
+
+[![System Overview](docs/diagrams/system-overview.svg)](https://raw.githubusercontent.com/trohitg/MachinaOS/main/docs/diagrams/system-overview.svg)
+
+At a glance:
+
+- **96 workflow nodes** across 21 categories (AI, agents, social, Android, Google Workspace, documents, code, proxies, utilities)
+- **10 LLM providers** via a hybrid native SDK + LangChain architecture
+- **15 specialized AI agents** with the Agent Teams delegation pattern
+- **89 WebSocket handlers** replacing most REST endpoints
+- **49 built-in skills** across 10 categories, editable in-UI with SKILL.md defaults on disk
+- **Three execution modes** with automatic fallback: Temporal distributed, Redis parallel, sequential
+
+### How Workflows Execute
+
+[![Execution Flow](docs/diagrams/execution-flow.svg)](https://raw.githubusercontent.com/trohitg/MachinaOS/main/docs/diagrams/execution-flow.svg)
+
+[WorkflowService](server/services/workflow.py) is a thin facade that routes each run through one of three execution modes. Every run has an isolated `ExecutionContext` with no shared global state, orchestrated by Conductor's decide pattern (`_workflow_decide` under a Redis `SETNX` lock). Layers are computed via Kahn's algorithm and each layer runs via `asyncio.gather()`. Results are cached by input hash (Prefect pattern), failed nodes go to a Dead Letter Queue, and a `RecoverySweeper` handles crashes via heartbeats.
+
+Deep dives: [DESIGN.md](docs-internal/DESIGN.md) - [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) - [event_waiter_system.md](docs-internal/event_waiter_system.md)
+
+### AI Agent System
+
+[![AI Agent Routing](docs/diagrams/ai-agent-routing.svg)](https://raw.githubusercontent.com/trohitg/MachinaOS/main/docs/diagrams/ai-agent-routing.svg)
+
+AI execution splits into two paths. `execute_chat()` for direct chat completions prefers the native SDK layer in [services/llm/](server/services/llm/) (10 providers, lazy imports, normalized `LLMResponse`), falling back to LangChain for Groq and Cerebras. `execute_agent()` and `execute_chat_agent()` always use LangChain + LangGraph because tool-calling, state graphs, and the checkpointer have no native equivalent today. Team leads (`orchestrator_agent`, `ai_employee`) auto-inject `delegate_to_<type>` tools for every agent connected to their `input-teammates` handle.
+
+Deep dives: [agent_architecture.md](docs-internal/agent_architecture.md) - [native_llm_sdk.md](docs-internal/native_llm_sdk.md) - [agent_teams.md](docs-internal/agent_teams.md) - [memory_compaction.md](docs-internal/memory_compaction.md)
+
+### Repository Map
+
+| Directory | What lives here | Start reading |
+|---|---|---|
+| `client/src/nodeDefinitions/` | 96 workflow node definitions (TypeScript) | [node_creation.md](docs-internal/node_creation.md) |
+| `client/src/components/` | React Flow canvas, parameter panel, modals | [CLAUDE.md](CLAUDE.md) |
+| `server/services/` | WorkflowService, NodeExecutor, AI service | [DESIGN.md](docs-internal/DESIGN.md) |
+| `server/services/handlers/` | One handler per node type (dispatch targets) | [node_creation.md](docs-internal/node_creation.md) |
+| `server/services/llm/` | Native LLM SDK layer (10 providers) | [native_llm_sdk.md](docs-internal/native_llm_sdk.md) |
+| `server/services/execution/` | Decide pattern, DLQ, recovery, conditions | [DESIGN.md](docs-internal/DESIGN.md) |
+| `server/services/temporal/` | Distributed execution via Temporal | [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) |
+| `server/routers/websocket.py` | 89 WebSocket handlers | [status_broadcaster.md](docs-internal/status_broadcaster.md) |
+| `server/core/` | Cache, encryption, DI container, config | [credentials_encryption.md](docs-internal/credentials_encryption.md) |
+| `server/skills/` | 49 skill SKILL.md files in 10 folders | [GUIDE.md](server/skills/GUIDE.md) |
+| `server/config/` | llm_defaults.json, pricing.json, model_registry.json | [pricing_service.md](docs-internal/pricing_service.md) |
+| `docs-internal/` | In-repo architecture deep dives (28 files) | Index below |
+
+### How to Contribute
+
+[![Node Anatomy](docs/diagrams/node-anatomy.svg)](https://raw.githubusercontent.com/trohitg/MachinaOS/main/docs/diagrams/node-anatomy.svg)
+
+The diagram above shows the full lifecycle of a workflow node from TypeScript definition to Python handler. Use these recipes as a starting point:
+
+**Add a workflow node**
+- Node definition: `client/src/nodeDefinitions/<yourCategory>.ts`
+- Backend handler: `server/services/handlers/<your_handler>.py`
+- Register in: `server/services/node_executor.py` registry
+- Guide: [node_creation.md](docs-internal/node_creation.md)
+
+**Add an LLM provider**
+- OpenAI-compatible (DeepSeek, Kimi, Mistral pattern): config-only in `server/config/llm_defaults.json`
+- Custom-SDK provider: new file in `server/services/llm/providers/`, branch in `factory.py`
+- Frontend node: `client/src/nodeDefinitions/aiModelNodes.ts`
+- Guide: [native_llm_sdk.md](docs-internal/native_llm_sdk.md)
+
+**Add a dual-purpose tool (workflow node + AI tool)**
+- Mark node `group: ['category', 'tool']`
+- Pydantic schema in `server/services/ai.py` (`_get_tool_schema`)
+- Dispatch in `server/services/handlers/tools.py`
+- Guide: [dual_purpose_tool_node_creation.md](docs-internal/dual_purpose_tool_node_creation.md)
+
+**Add a specialized AI agent**
+- `client/src/nodeDefinitions/specializedAgentNodes.ts`
+- Add to `SPECIALIZED_AGENT_TYPES` in `server/constants.py`
+- Register in `server/services/node_executor.py`
+- Guide: [specialized_agent_node_creation.md](docs-internal/specialized_agent_node_creation.md)
+
+**Add a skill**
+- New folder under `server/skills/<category>/`
+- Create `SKILL.md` with YAML frontmatter + markdown body
+- Guide: [GUIDE.md](server/skills/GUIDE.md)
+
+**Add an event-based trigger**
+- Register in `TRIGGER_REGISTRY` in `server/services/event_waiter.py`
+- Add a filter builder in the same file
+- Frontend node with `group: ['category', 'trigger']`
+- Guide: [event_waiter_system.md](docs-internal/event_waiter_system.md)
+
+**Integrate a new external service with OAuth**
+- Reference implementation: Google Workspace (7 nodes sharing one OAuth connection)
+- Guide: [new_service_integration.md](docs-internal/new_service_integration.md)
+
+### Local Dev Quick Reference
+
+```bash
+npm run dev            # start frontend + backend + Temporal + WhatsApp
+npm run stop           # stop everything
+npx tsc --noEmit       # typecheck client (from client/)
+python -m pytest       # run backend tests (from server/)
+npm run build          # production build
+```
+
+Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.md](docs-internal/SCRIPTS.md)
+
+<details>
+<summary><b>Full Documentation Index</b></summary>
+
+| Document | Description |
+|---|---|
+| [DESIGN.md](docs-internal/DESIGN.md) | Execution engine architecture, design patterns, execution modes |
+| [TEMPORAL_ARCHITECTURE.md](docs-internal/TEMPORAL_ARCHITECTURE.md) | Distributed execution via Temporal activities |
+| [workflow-schema.md](docs-internal/workflow-schema.md) | Workflow JSON schema and full node catalog (96 nodes) |
+| [ROADMAP.md](docs-internal/ROADMAP.md) | Implementation status and completed phases |
+| [SETUP.md](docs-internal/SETUP.md) | Development environment setup |
+| [SCRIPTS.md](docs-internal/SCRIPTS.md) | npm/shell scripts reference |
+| [server-readme.md](docs-internal/server-readme.md) | Python backend architecture and API |
+| [agent_architecture.md](docs-internal/agent_architecture.md) | AI Agent / Chat Agent skill and tool discovery |
+| [agent_delegation.md](docs-internal/agent_delegation.md) | How delegated agents share context and memory |
+| [agent_teams.md](docs-internal/agent_teams.md) | Agent Teams pattern with `input-teammates` handle |
+| [native_llm_sdk.md](docs-internal/native_llm_sdk.md) | Native LLM SDK layer and provider protocol |
+| [rlm_service.md](docs-internal/rlm_service.md) | Recursive Language Model agent via REPL |
+| [claude_code_agent_architecture.md](docs-internal/claude_code_agent_architecture.md) | Claude Code SDK integration as a specialized agent |
+| [autonomous_agent_creation.md](docs-internal/autonomous_agent_creation.md) | Autonomous agents with Code Mode patterns |
+| [event_waiter_system.md](docs-internal/event_waiter_system.md) | Push-based trigger waiters |
+| [status_broadcaster.md](docs-internal/status_broadcaster.md) | WebSocket broadcaster and 89 handlers |
+| [credentials_encryption.md](docs-internal/credentials_encryption.md) | Fernet + PBKDF2 credentials system |
+| [memory_compaction.md](docs-internal/memory_compaction.md) | Token tracking and model-aware compaction |
+| [pricing_service.md](docs-internal/pricing_service.md) | LLM and API cost tracking |
+| [proxy_service.md](docs-internal/proxy_service.md) | Residential proxy provider management |
+| [ci_cd.md](docs-internal/ci_cd.md) | GitHub Actions workflows |
+| [node_creation.md](docs-internal/node_creation.md) | How to create new nodes |
+| [ai_tool_node_creation.md](docs-internal/ai_tool_node_creation.md) | Creating dedicated AI Agent tool nodes |
+| [specialized_agent_node_creation.md](docs-internal/specialized_agent_node_creation.md) | Creating specialized AI agent nodes |
+| [dual_purpose_tool_node_creation.md](docs-internal/dual_purpose_tool_node_creation.md) | Dual-purpose workflow + tool nodes |
+| [new_service_integration.md](docs-internal/new_service_integration.md) | External service integration guide |
+| [cli_services_integration.md](docs-internal/cli_services_integration.md) | CLI service lifecycle management |
+| [onboarding.md](docs-internal/onboarding.md) | Welcome wizard and replay |
+| [Skill Creation Guide](server/skills/GUIDE.md) | How to create new skills |
+
+</details>

package/bin/cli.js

@@ -14,10 +14,6 @@ const COMMANDS = {
   stop: 'Stop all running services',
   build: 'Build the project for production',
   clean: 'Clean build artifacts',
-  'docker:up': 'Start with Docker Compose',
-  'docker:down': 'Stop Docker Compose services',
-  'docker:build': 'Build Docker images',
-  'docker:logs': 'View Docker logs',
   help: 'Show this help message',
   version: 'Show version number',
 };
@@ -41,8 +37,6 @@ Examples:
   machina start -v       # Production with full logs
   machina dev            # Development with hot-reload
   machina build          # Build for production
-  machina docker:up      # Start with Docker
-
 Documentation: https://docs.zeenie.xyz/
 `);
 }