Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(workflow): document UUID id / slug / name split (Wave 14)
trohitg46aeae3bc1ad
diff --git a/CLAUDE.md b/CLAUDE.mdindex 1e8f0208..d428ea1f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1471,7 +1471,7 @@ Residential proxy provider management with geo-targeting, session control, and a- **typescriptExecutor**: **Dual-purpose node** - Execute TypeScript code via persistent Node.js server with type safety, syntax-highlighted editor and console output. Works as workflow node OR AI Agent tool (`typescript_code`).### Filesystem & Shell Nodes (4 nodes)-Dual-purpose tool nodes wrapping `deepagents.backends.LocalShellBackend`. Per-workflow workspace from execution context (`context["workspace_dir"]` = `~/.machina/workspaces/<workflow_id>/`). Fallback uses `Settings().workspace_base_dir` (never `os.getcwd()`).+Dual-purpose tool nodes wrapping `deepagents.backends.LocalShellBackend`. Per-workflow workspace from execution context (`context["workspace_dir"]` = `~/.machina/workspaces/<workflow_slug>/` post-Wave-14; the slug is the human-readable form `AI_Assistant_1`, see "Workflow Naming" section). Fallback uses `Settings().workspace_base_dir` (never `os.getcwd()`).**Path safety**: `nodes/filesystem/_backend.py` exposes `normalize_virtual_path()` which uses `pathlib.PureWindowsPath` (host-OS independent) to strip Windows drives, POSIX root, and UNC anchors uniformly, then delegates to `deepagents.backends.utils.validate_path` for `..`/`~` rejection. Wired into `file_read`, `file_modify`, and `fs_search` so LLM-emitted paths in any flavour (`C:\foo`, `/tmp/foo`, `\\server\share\x`, `foo\bar`) all map to a virtual path under the workspace. `virtual_mode=True` only sandboxes filesystem ops — `execute()` itself is never path-restricted (deepagents documents this).@@ -2024,7 +2024,7 @@ Console logs are persisted to SQLite database and loaded on page refresh.### Per-Workflow Workspace DirectoryEach workflow execution gets a persistent workspace directory where nodes save output files and AI agents (especially Deep Agent) access them via filesystem tools.-**Directory**: `~/.machina/workspaces/<workflow_id>/`+**Directory**: `~/.machina/workspaces/<workflow_slug>/` (Wave 14 — keyed by the human-readable slug, not the UUID; see "Workflow naming" below).**Configuration** (`server/core/config.py`):```python@@ -2032,11 +2032,12 @@ workspace_base_dir: str = Field(default="data/workspaces", env="WORKSPACE_BASE_D```**How it works:**-- `workflow.py` creates the workspace dir and injects `workspace_dir` into the execution context+- `workflow.py` creates the workspace dir and injects `workspace_dir` into the execution context. The dir name is the `workflow_slug` resolved from the DB (falls back to `"default"` for one-off Runs without a saved row).- `fileDownloader` saves to `{workspace_dir}/downloads/` by default- Code executors (Python/JS/TS) receive `workspace_dir` in their execution namespace- Deep Agent uses `FilesystemBackend(root_dir=workspace_dir, virtual_mode=True)` -- its filesystem tools (`read_file`, `write_file`, `edit_file`, `ls`, `glob`, `grep`) operate within the workspace- `virtual_mode=True` sandboxes paths to prevent traversal outside workspace+- Rename follows the workflow: when the user renames a workflow, `save_workflow` recomputes the slug and `os.rename`s the workspace dir to match (existing files preserved).**Key Files:**| File | Description |@@ -2047,6 +2048,27 @@ workspace_base_dir: str = Field(default="data/workspaces", env="WORKSPACE_BASE_D| `server/services/handlers/code.py` | `workspace_dir` available in Python/JS/TS execution || `server/nodes/filesystem/_backend.py` | `NushellBackend(root_dir=workspace_dir, virtual_mode=True)` for the file/shell plugins |+### Workflow Naming (Wave 14)+The workflow record carries three identity fields with strict separation:++| Field | Carrier | Stable? | Surfaces |+|---|---|---|---|+| `Workflow.id` | opaque 32-hex UUID (`uuid.uuid4().hex`) | yes — never changes on rename | FK target (`Execution.workflow_id`), `EventWorkflowId` Search Attribute in Temporal Visibility, `WorkflowEvent.workflow_id` CloudEvents extension, `log_context(workflow_id=...)`, Redis cache keys, `DeploymentManager._deployments` dict key, frontend `useAppStore.currentWorkflow.id` |+| `Workflow.name` | free-form display ("AI Assistant") | mutable | sidebar, parameter panel, exported JSON |+| `Workflow.slug` | `<Sanitized_Name>_<N>` (`AI_Assistant_1`) | mutable, recomputed on rename | `~/.machina/workspaces/<slug>/`, Temporal start id (`<slug>_<uuid8>` visible in Temporal Web UI), cron Schedule IDs, export filenames |++Single source of truth: [`server/services/workflow_naming.py`](./server/services/workflow_naming.py) — `slugify_name` (via `python-slugify` for Unicode transliteration, emoji strip, case preservation, length cap), `next_available_slug(name, database, *, exclude_id=None)` (fill-gap counter; pass `exclude_id=workflow_id` on rename so the row doesn't bump itself), `new_workflow_id()` (bare hex UUID).++**Rename path** — there is NO dedicated rename endpoint. The frontend's auto-save chain (`TopToolbar` inline edit → `updateWorkflow({name})` → debounced save → REST `POST /api/database/workflows` → `services.workflow_storage.handlers.handle_save_workflow`) IS the rename path. When `name` changes between saves, the handler (1) allocates a fresh slug via `next_available_slug`, (2) `database.rename_workflow` updates name + slug atomically (id UUID stays put), (3) renames the on-disk workspace dir via `Path.rename()`, (4) broadcasts a CloudEvents `workflow.renamed` envelope (`broadcaster.broadcast_workflow_lifecycle("renamed", workflow_id=..., name=..., slug=..., old_slug=...)`) so other tabs invalidate their workflows query.++**Invariants** (locked by `tests/services/test_workflow_naming.py` + `test_workflow_rename.py` — 42 tests):+- First creation always gets `_1` suffix (no bare-base slugs).+- Fill-gap: deleted `AI_Assistant_2` slot is reused on next "AI Assistant" creation.+- Renaming `AI Assistant` → `AI Assistant!` (same slug base) keeps `_1` via `exclude_id` (no self-bump).+- UNIQUE constraint on `slug` is the final collision guard; `IntegrityError` indicates a race the caller should retry.+- Non-ASCII names transliterate via `text-unidecode` ("日本語" → "Ri_Ben_Yu"); fall back to `Workflow_N` only when slug is empty after sanitize.+- No backfill migration — the slug column is required on every save. Existing DBs must be rebuilt.+### Execution System- **Supported Components**: AI models, location services, Android automation, WhatsApp messaging, HTTP requests, webhooks- **Android Integration**: ADB-based device control with 17 service nodes across monitoring, apps, automation, sensors, and mediadiff --git a/docs-internal/DESIGN.md b/docs-internal/DESIGN.mdindex 35c70d02..d0e120e2 100644--- a/docs-internal/DESIGN.md+++ b/docs-internal/DESIGN.md@@ -451,7 +451,9 @@ class ExecutionContext:edges: List[Dict] # Edge definitions# Workspace (per-workflow filesystem for nodes and agents)- workspace_dir: str # Absolute path to data/workspaces/<workflow_id>/+ workspace_dir: str # Absolute path to data/workspaces/<workflow_slug>/+ # (Wave 14 — keyed by the human-readable slug,+ # not the UUID id; see CLAUDE.md "Workflow Naming")# Execution Progressexecution_order: List[List[str]] # Computed layersdiff --git a/docs-internal/claude_code_interactive_mode.md b/docs-internal/claude_code_interactive_mode.mdindex b61a53c0..578e3e8e 100644--- a/docs-internal/claude_code_interactive_mode.md+++ b/docs-internal/claude_code_interactive_mode.md@@ -311,7 +311,8 @@ was the wrong default).[`nodes/agent/claude_code_agent/_skills.py::materialise_skills`](../server/nodes/agent/claude_code_agent/_skills.py)writes one `SKILL.md` tree per connected-and-enabled skill under`<workspace_dir>/.claude/skills/<name>/`. The workspace dir-(`~/.machina/workspaces/<workflow_id>/`) is already passed via+(`~/.machina/workspaces/<workflow_slug>/` — Wave 14 keys it by the+human-readable slug, not the UUID id) is already passed via`--add-dir`, and per the skills spec's[Automatic discovery from parent and nested directories](https://code.claude.com/docs/en/skills#automatic-discovery-from-parent-and-nested-directories)rule, claude scans `.claude/skills/` inside every `--add-dir` path.@@ -361,7 +362,7 @@ skill-injection channel — workspace-dir + live-watch is canonical.**Workspace dir — routed via `--add-dir`.**[`AICliService.run_batch`](../server/services/cli_agent/service.py)splices the per-workflow workspace-(`~/.machina/workspaces/<workflow_id>/`, injected into `ctx.raw` by+(`~/.machina/workspaces/<workflow_slug>/`, injected into `ctx.raw` by`workflow.py:_get_workspace_dir`) into each task's `add_dir` listright after `task_list` is built — `interactive_argv` already emits`--add-dir <path>` per entry. Runs BEFORE the pool/non-pool branchdiff --git a/docs-internal/workflow-schema.md b/docs-internal/workflow-schema.mdindex b641d857..a7219fc3 100644--- a/docs-internal/workflow-schema.md+++ b/docs-internal/workflow-schema.md@@ -24,17 +24,24 @@ A workflow JSON document contains:"title": "Workflow","description": "A workflow automation definition containing nodes and connections","type": "object",- "required": ["id", "name", "nodes", "edges", "createdAt", "lastModified"],+ "required": ["id", "name", "slug", "nodes", "edges", "createdAt", "lastModified"],"properties": {"id": {"type": "string",- "pattern": "^workflow_[0-9]+$"+ "description": "Stable system UUID — 32 lowercase hex chars (uuid.uuid4().hex). Never changes on rename. FK target for cross-table refs + Temporal Search Attributes + CloudEvents extension + log context.",+ "pattern": "^[0-9a-f]{32}$"},"name": {"type": "string",+ "description": "Free-form display name (sidebar label, parameter panel).","minLength": 1,"maxLength": 100},+ "slug": {+ "type": "string",+ "description": "Human-readable identifier (e.g. AI_Assistant_1). Derived from name via services.workflow_naming.next_available_slug. Mutable on rename — recomputed + propagated to workspace dir + Temporal Web UI prefix + cron Schedule IDs. UNIQUE across active workflows.",+ "pattern": "^[A-Za-z0-9]+(_[0-9]+)?$"+ },"nodes": {"type": "array","items": { "$ref": "#/definitions/node" }