Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
fix(nodes): NodeUserError + Windows shim + skill clarifications
trohitge2f151ecbd36
diff --git a/server/nodes/filesystem/file_modify.py b/server/nodes/filesystem/file_modify.pyindex fb9ed252..31236775 100644--- a/server/nodes/filesystem/file_modify.py+++ b/server/nodes/filesystem/file_modify.py@@ -6,7 +6,7 @@ from typing import Any, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field-from services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue_WRITE = {"displayOptions": {"show": {"operation": ["write"]}}}@@ -56,7 +56,7 @@ class FileModifyNode(ActionNode):from ._backend import get_backend, normalize_virtual_pathif not params.file_path:- raise RuntimeError("file_path is required")+ raise NodeUserError("file_path is required")backend = get_backend(params.model_dump(), ctx.raw)file_path = normalize_virtual_path(params.file_path)@@ -78,24 +78,24 @@ class FileModifyNode(ActionNode):try:result = await asyncio.to_thread(_do_write)except (OSError, ValueError) as e:- raise RuntimeError(str(e)) from e+ raise NodeUserError(str(e)) from eif result.error:- raise RuntimeError(result.error)+ raise NodeUserError(result.error)return {"operation": "write", "file_path": result.path or file_path}if params.operation == "edit":if not params.old_string:- raise RuntimeError("old_string is required for edit")+ raise NodeUserError("old_string is required for edit")result = await asyncio.to_thread(backend.edit, file_path, params.old_string, params.new_string,replace_all=params.replace_all,)if result.error:- raise RuntimeError(result.error)+ raise NodeUserError(result.error)return {"operation": "edit","file_path": result.path or file_path,"occurrences": result.occurrences,}- raise RuntimeError(f"Unknown operation: {params.operation}")+ raise NodeUserError(f"Unknown operation: {params.operation}")diff --git a/server/nodes/filesystem/file_read.py b/server/nodes/filesystem/file_read.pyindex 6da7e8ce..33c87e12 100644--- a/server/nodes/filesystem/file_read.py+++ b/server/nodes/filesystem/file_read.py@@ -6,7 +6,7 @@ from typing import Any, Optionalfrom pydantic import BaseModel, ConfigDict, Field-from services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueueclass FileReadParams(BaseModel):@@ -49,11 +49,16 @@ class FileReadNode(ActionNode):from ._backend import get_backend, normalize_virtual_pathif not params.file_path:- raise RuntimeError("file_path is required")+ raise NodeUserError("file_path is required")backend = get_backend(params.model_dump(), ctx.raw)file_path = normalize_virtual_path(params.file_path)- content = await asyncio.to_thread(- backend.read, file_path,- offset=params.offset, limit=params.limit,- )+ try:+ content = await asyncio.to_thread(+ backend.read, file_path,+ offset=params.offset, limit=params.limit,+ )+ except (FileNotFoundError, IsADirectoryError, ValueError) as e:+ # File doesn't exist / is a directory / bad offset — the+ # LLM should retry with corrected input, not fail the run.+ raise NodeUserError(str(e)) from ereturn {"content": content, "file_path": file_path}diff --git a/server/nodes/filesystem/fs_search.py b/server/nodes/filesystem/fs_search.pyindex 19c4cc58..8a96ad30 100644--- a/server/nodes/filesystem/fs_search.py+++ b/server/nodes/filesystem/fs_search.py@@ -6,7 +6,7 @@ from typing import Any, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field-from services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueueclass FsSearchParams(BaseModel):@@ -61,7 +61,7 @@ class FsSearchNode(ActionNode):if params.mode == "glob":if not params.pattern:- raise RuntimeError("pattern is required for glob mode")+ raise NodeUserError("pattern is required for glob mode")matches = await asyncio.to_thread(backend.glob_info, params.pattern, path=path,)@@ -74,12 +74,12 @@ class FsSearchNode(ActionNode):if params.mode == "grep":if not params.pattern:- raise RuntimeError("pattern is required for grep mode")+ raise NodeUserError("pattern is required for grep mode")result = await asyncio.to_thread(backend.grep_raw, params.pattern, path=path,)if isinstance(result, str):- raise RuntimeError(result)+ raise NodeUserError(result)return {"path": path,"pattern": params.pattern,@@ -87,4 +87,4 @@ class FsSearchNode(ActionNode):"count": len(result),}- raise RuntimeError(f"Unknown mode: {params.mode}")+ raise NodeUserError(f"Unknown mode: {params.mode}")diff --git a/server/nodes/filesystem/shell.py b/server/nodes/filesystem/shell.pyindex 1fb73f34..7c1253ad 100644--- a/server/nodes/filesystem/shell.py+++ b/server/nodes/filesystem/shell.py@@ -52,8 +52,14 @@ class ShellNode(ActionNode):log = get_logger(__name__)backend = get_backend(params.model_dump(), ctx.raw)+ # "non-blocking" here only meant the asyncio event loop isn't+ # blocked (the call is offloaded via ``to_thread``). The+ # subprocess itself is still awaited — long-running commands+ # are killed at ``timeout`` and must use ``process_manager``+ # instead. Logging the bare command + timeout to avoid+ # misleading users into thinking shell runs daemons.log.info(- "[Shell] Executing (non-blocking): %s (timeout=%ds)",+ "[Shell] Executing: %s (timeout=%ds)",params.command[:200], params.timeout,)result = await asyncio.to_thread(diff --git a/server/nodes/twitter/twitter_search.py b/server/nodes/twitter/twitter_search.pyindex b5c81713..bd596b0c 100644--- a/server/nodes/twitter/twitter_search.py+++ b/server/nodes/twitter/twitter_search.py@@ -23,8 +23,16 @@ class TwitterSearchParams(BaseModel):query: str = Field(default="",description=(- "Twitter search query (operators: keywords, hashtags, @mentions, "- "from:user, -exclude, OR, lang:, has:*, is:*)"+ "X / Twitter search query for /2/tweets/search/recent. "+ "MUST include at least one STANDALONE term: a keyword, "+ "quoted \"phrase\", #hashtag, @mention, from:user, to:user, "+ "or url:domain. "+ "Operators like lang:, -is:retweet, is:reply, has:media, "+ "has:links are CONJUNCTION-REQUIRED -- they only work when "+ "combined with a standalone term. Operator-only queries "+ "(e.g. '-is:retweet lang:en' or 'has:media') return HTTP 400. "+ "Valid: 'python -is:retweet', '\"machine learning\" lang:en', "+ "'from:elonmusk -is:retweet', '#ai has:media'."),)max_results: int = Field(diff --git a/server/nodes/utility/process_manager.py b/server/nodes/utility/process_manager.pyindex 25026b22..9cb6b879 100644--- a/server/nodes/utility/process_manager.py+++ b/server/nodes/utility/process_manager.py@@ -6,7 +6,7 @@ from typing import Any, Dict, Literal, Optionalfrom pydantic import BaseModel, ConfigDict, Field-from services.plugin import ActionNode, NodeContext, Operation, TaskQueue+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue_START = {"displayOptions": {"show": {"operation": ["start"]}}}@@ -74,9 +74,14 @@ class ProcessManagerNode(ActionNode):"""Raise on service-level failure envelopes so the pluginwrapper returns success=False instead of burying a``{"success": False, "error": "..."}`` inside the result dict.++ ``NodeUserError`` (vs ``RuntimeError``) so the framework logs+ a single WARN line — these are user/LLM-correctable+ (process-not-found, command-not-found, bad cwd, ...), not+ server bugs warranting a stack trace."""if isinstance(response, dict) and response.get("success") is False:- raise RuntimeError(response.get("error") or "process operation failed")+ raise NodeUserError(response.get("error") or "process operation failed")return responseif op == "start":@@ -96,7 +101,7 @@ class ProcessManagerNode(ActionNode):return {"processes": svc.list_processes(workflow_id)}if op == "get_output":return _unwrap(svc.get_output(name, workflow_id, params.stream, params.tail, 0))- raise RuntimeError(f"Unknown operation: {op}")+ raise NodeUserError(f"Unknown operation: {op}")def _clean(val: str) -> str:diff --git a/server/nodes/visuals.json b/server/nodes/visuals.jsonindex 16bee2e8..b17e07b8 100644--- a/server/nodes/visuals.json+++ b/server/nodes/visuals.json@@ -297,7 +297,7 @@"processManager": {"icon": "⚙️","color": "#bd93f9",- "skill": "bash-skill"+ "skill": "process-manager-skill"},"productivity_agent": {"icon": "⏰",@@ -318,7 +318,7 @@},"pythonExecutor": {"icon": "asset:python",- "skill": "agentic-loop-skill"+ "skill": "python-skill"},"rlm_agent": {"icon": "🧠",diff --git a/server/services/plugin/__init__.py b/server/services/plugin/__init__.pyindex 124b052e..acf48e36 100644--- a/server/services/plugin/__init__.py+++ b/server/services/plugin/__init__.py@@ -25,7 +25,7 @@ Temporal integration (11.F): every subclass exposesfrom __future__ import annotations-from services.plugin.base import BaseNode+from services.plugin.base import BaseNode, NodeUserErrorfrom services.plugin.action import ActionNodefrom services.plugin.trigger import TriggerNodefrom services.plugin.tool import ToolNode@@ -49,6 +49,7 @@ from services.plugin.interceptor import Interceptor, InterceptorChain__all__ = ["BaseNode",+ "NodeUserError","ActionNode","TriggerNode","ToolNode",diff --git a/server/services/plugin/base.py b/server/services/plugin/base.pyindex 5cd844d3..d147f98a 100644--- a/server/services/plugin/base.py+++ b/server/services/plugin/base.py@@ -41,6 +41,19 @@ from services.plugin.scaling import (logger = get_logger(__name__)+class NodeUserError(Exception):+ """Raised by an operation when the failure is *expected and+ user-correctable* (bad ``old_string`` for an edit, missing required+ field, unknown enum value, ...). The framework converts it to a+ structured ``{success: False, error: ...}`` response and logs at+ WARN level without a stack trace — these are not server bugs, they+ are signals the LLM (or user) should retry with different input.++ Use plain ``RuntimeError`` / ``Exception`` only for genuinely+ unexpected failures that warrant a stacktrace in the operator log.+ """++# Sentinel used by Params-less nodes so .model_validate({}) works.class _EmptyParams(BaseModel):pass@@ -251,6 +264,15 @@ class BaseNode:return self._wrap_error(start_time=start_time, error=str(e), error_type="PermissionDeniedError")+ except NodeUserError as e:+ # Expected, user-correctable: log a single WARN line so it+ # shows up in operator logs, but skip the traceback — the+ # LLM gets the message in the structured response and can+ # retry with corrected input.+ logger.warning("[%s] %s op %s: %s", self.type, op_name, type(e).__name__, e)+ return self._wrap_error(+ start_time=start_time, error=str(e), error_type="NodeUserError"+ )except Exception as e:logger.exception("[%s] operation %s failed", self.type, op_name)return self._wrap_error(start_time=start_time, error=str(e), error_type=type(e).__name__)diff --git a/server/services/process_service.py b/server/services/process_service.pyindex 81c22e2c..64245f4b 100644--- a/server/services/process_service.py+++ b/server/services/process_service.py@@ -102,6 +102,24 @@ class ProcessService:await self.stop(name, workflow_id)argv = shlex.split(command)+ # Resolve argv[0] to an absolute path. Canonical idiom in this+ # codebase (browser_service, claude_code_service, claude_oauth,+ # himalaya_service): shutil.which honours PATHEXT on Windows so+ # `npm` -> `C:\...\npm.cmd`. Without this, asyncio.create_subprocess_exec+ # fails with `WinError 2` because CreateProcessW does not apply+ # PATHEXT to a bare argv[0]. CreateProcessW launches .cmd/.bat+ # directly when given an absolute path, so no `cmd /c` wrap is+ # needed.+ resolved = shutil.which(argv[0]) if argv else None+ if resolved is None:+ return {+ "success": False,+ "error": (+ f"Command not found: '{argv[0] if argv else ''}'. "+ "Check spelling or ensure the binary is on PATH."+ ),+ }+ argv[0] = resolvedenv = {**os.environ, "PYTHONUNBUFFERED": "1"}from core.config import Settingsworkspace_base = Path(Settings().workspace_base_resolved).resolve()diff --git a/server/skills/social_agent/twitter-search-skill/SKILL.md b/server/skills/social_agent/twitter-search-skill/SKILL.mdindex 48f6fb7b..e13e17f4 100644--- a/server/skills/social_agent/twitter-search-skill/SKILL.md+++ b/server/skills/social_agent/twitter-search-skill/SKILL.md@@ -4,7 +4,7 @@ description: Search for recent tweets on Twitter/X using keywords, hashtags, menallowed-tools: twitter_searchmetadata:author: machina- version: "2.0"+ version: "2.1"category: social---@@ -28,6 +28,34 @@ Search for tweets matching a query. Returns enriched tweet data via X API v2 exp| query | string | Yes | Search query (supports operators) || max_results | integer | No | Number of results (10-100, default: 10) |+### Query Rules (X API constraint — required reading)++**Every query must contain at least one STANDALONE term.** Operator-only queries return HTTP 400 from X.++- **Standalone (can stand alone as the whole query)**: keyword, `"quoted phrase"`, `#hashtag`, `@mention`, `from:user`, `to:user`, `url:domain`, `context:`.+- **Conjunction-required (must be combined with a standalone term)**: `lang:`, `is:retweet` / `-is:retweet`, `is:reply` / `-is:reply`, `is:quote`, `has:links`, `has:media`, `has:images`, `has:videos`, plain `-negation` of any keyword.++**HTTP 400 — these queries fail:**++| Bad query | Why |+|---|---|+| `lang:en` | conjunction-required operator alone |+| `-is:retweet` | negation alone |+| `-is:retweet lang:en` | two conjunction-required operators, zero standalone |+| `has:media` | conjunction-required alone |+| `is:reply` | conjunction-required alone |++**Valid — these have at least one standalone term:**++| Good query | Standalone anchor |+|---|---|+| `python -is:retweet` | keyword `python` |+| `"machine learning" lang:en` | quoted phrase |+| `from:elonmusk -is:retweet` | `from:` |+| `#ai has:media` | hashtag |+| `@OpenAI lang:en` | mention |+| `url:"github.com" -is:retweet` | `url:` |+### Query OperatorsThe X API v2 supports advanced search operators:@@ -199,13 +227,14 @@ Each tweet includes rich data. The `display_text` field has t.co links replaced## Guidelines-1. **Query length**: Keep queries concise for better results-2. **Max results**: Minimum 10, maximum 100 per request (X API v2 constraint)-3. **Recent tweets only**: X API v2 free/basic tier searches recent tweets (last 7 days)-4. **Rate limits**: Be mindful of API rate limits when searching repeatedly-5. **Combine operators**: Use multiple operators for precise filtering-6. **Exclude retweets**: Add `-is:retweet` to get original content only-7. **Language filter**: Add `lang:en` to filter by language+1. **Always include a standalone term** (keyword / phrase / hashtag / mention / `from:` / `to:` / `url:`) — see "Query Rules" above. Operator-only queries fail with HTTP 400.+2. **Max results**: Minimum 10, maximum 100 per request (X API v2 constraint).+3. **Recent tweets only**: X API v2 free/basic tier searches recent tweets (last 7 days).+4. **Rate limits**: Be mindful of API rate limits when searching repeatedly.+5. **Combine operators on a base term**: e.g., `python -is:retweet lang:en has:links` — the `python` keyword anchors all three filters.+6. **Exclude retweets**: append `-is:retweet` to a keyword query (e.g. `python -is:retweet`). Cannot stand alone.+7. **Language filter**: append `lang:en` to a keyword/`from:`/hashtag query (e.g. `"openai" lang:en`). Cannot stand alone.+8. **Media filter**: append `has:media` / `has:images` / `has:videos` to a keyword query. Cannot stand alone.## Common Use Cases@@ -222,3 +251,9 @@ Each tweet includes rich data. The `display_text` field has t.co links replaced1. Connect the **Twitter Search** node to an AI Agent's `input-tools` handle2. Ensure Twitter is connected (authenticated via OAuth in Credentials Modal)3. Your X Developer account must have appropriate API access level++## References++- [X API — Build a query](https://docs.x.com/x-api/posts/search/integrate/build-a-query)+- [X API — Operators reference](https://docs.x.com/x-api/posts/search/integrate/operators)+- [X API — /2/tweets/search/recent](https://docs.x.com/x-api/posts/search-recent-posts)diff --git a/server/skills/terminal/shell-skill/SKILL.md b/server/skills/terminal/shell-skill/SKILL.mdindex 759d9e91..3077c146 100644--- a/server/skills/terminal/shell-skill/SKILL.md+++ b/server/skills/terminal/shell-skill/SKILL.md@@ -4,7 +4,7 @@ description: Execute short-lived shell commands inside the per-workflow workspacallowed-tools: "shell"metadata:author: machina- version: "4.0"+ version: "4.1"category: execution---@@ -15,6 +15,24 @@ Execute short-lived shell commands in the workflow workspace. **The shell is [NuExternal binaries on `PATH` (`npm`, `node`, `python`, `git`, `pwd`, etc.) are available — Nu invokes them as external commands automatically.+**GNU coreutils (`sed`, `awk`, `head`, `tail`, `grep`, `cut`, `sort`, `uniq`, `wc`, `tr`, `xargs`, `find`) are NOT in PATH on Windows** and will fail with `Command not found`. Use Nushell builtins or switch tools — see the table below.++## Check the host before reaching for external tools++Don't burn turns on trial-and-error (`sed not found` → retry with `awk` → `awk not found` → ...). Detect the host **once** at the start of a task that needs platform-sensitive binaries, then branch:++```nu+# `$nu.os-info.name` is "windows" | "linux" | "macos" | "android" | ...+let os = $nu.os-info.name+```++Then either:+1. **Skip the shell entirely.** For reading / editing / searching files, the right answer almost always is `file_read` / `file_modify` / `fs_search` — they are path-sandboxed and platform-agnostic by construction.+2. **Use Nu builtins.** `open`, `lines`, `first`, `last`, `find`, `glob`, `length`, `save`, `cp`, `mv`, `rm`, `mkdir` exist on every host.+3. **Probe before invoking external CLIs.** `if (which sed | is-empty) { ... } else { sed ... }` — but at that point, `file_read` / `file_modify` is shorter and works everywhere.++**Rule of thumb**: if your command starts with `sed` / `awk` / `head` / `tail` / `grep`, stop and reach for `file_read` or `fs_search` instead. You almost never need a host check — you need the dedicated tool.+## shell_execute Tool### Schema@@ -56,6 +74,15 @@ External binaries on `PATH` (`npm`, `node`, `python`, `git`, `pwd`, etc.) are av| `for f in *.py; do ...` | `glob '*.py' \| each { \|f\| ... }` || `*` glob in argv (auto-expand) | wrap in quotes or use `glob` || `~/path` | `('~/path' \| path expand)` |+| `sed -n '1,N p' file` | `open file --raw \| lines \| first N` *(prefer `file_read` with `limit`)* |+| `head -n N file` | `open file --raw \| lines \| first N` |+| `tail -n N file` | `open file --raw \| lines \| last N` |+| `sed -i 's/a/b/' file` | use `file_modify` (edit op) — not the shell |+| `grep 'pat' file` | `open file --raw \| find 'pat'` *(prefer `fs_search`)* |+| `grep -r 'pat' src/` | use `fs_search` (grep mode) |+| `wc -l file` | `open file --raw \| lines \| length` |+| `find . -name '*.py'` | `glob '**/*.py'` |+| `xargs cmd` | `each { \|x\| cmd $x }` |### Short-circuit "and-then" (the `&&` replacement)@@ -111,8 +138,10 @@ Use **A** for "run these in order regardless of outcome", **B/C** when you must## Guidelines1. **Never use `&&`, `||`, backticks, `$VAR`, or `>` redirection.** Use the Nushell equivalent on the right side of the table above.-2. **One command (or `;`-chain) per call.** No multi-line scripts; if you need control flow, use `if` / `try` / `each` inline.-3. **Short-lived only.** If the command runs longer than ~30s or is a daemon, switch to `process_manager`.-4. **Don't pre-detect the OS.** Nu syntax is identical on Windows, macOS, Linux — write one command, not platform branches.-5. **Quote glob patterns** (`'*.py'`) so Nu's `glob` builtin expands them, not the caller.-6. **Capture command exit code** with `do { … } | complete` if you need to branch on success/failure.+2. **Never invoke GNU coreutils** (`sed`, `awk`, `head`, `tail`, `grep`, `find`, `wc`, `cut`, `sort`, `uniq`, `xargs`, `tr`). They are not on Windows. For peeking at a file, use **`file_read`** (line-numbered, `offset`/`limit` aware); for searching, use **`fs_search`** (grep mode).+3. **Check the host first** when an external CLI is unavoidable. `let os = $nu.os-info.name` once, then gate by `windows` / `linux` / `macos`. Don't loop "try → fail → retry".+4. **One command (or `;`-chain) per call.** No multi-line scripts; if you need control flow, use `if` / `try` / `each` inline.+5. **Short-lived only.** `shell_execute` *always* awaits completion — a small `timeout` does **not** make it run in the background, it just kills the command after N seconds. If the command runs longer than ~30s, opens a port, watches files, or is described as "dev server / watcher / daemon" (`npm run dev`, `vite`, `tsx watch`, `python -m http.server`, ...), use **`process_manager`** instead. Trying to "fire and forget" with `timeout=2` will kill the process the moment the port comes up.+6. **Nu syntax is host-agnostic.** Builtins (`ls`, `open`, `glob`, `lines`, `save`, `cp`, ...) work the same everywhere. You only need the host check for *external* tools.+7. **Quote glob patterns** (`'*.py'`) so Nu's `glob` builtin expands them, not the caller.+8. **Capture command exit code** with `do { … } | complete` if you need to branch on success/failure.