Skip to content

Self-improving AI Employees for everyone

fix(nodes): NodeUserError + Windows shim + skill clarifications

trohitge2f151ecbd36
diff --git a/server/nodes/filesystem/file_modify.py b/server/nodes/filesystem/file_modify.py
index 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, Optional
from 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_path
if 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 e
if 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.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
-from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
class FileReadParams(BaseModel):
@@ -49,11 +49,16 @@ class FileReadNode(ActionNode):
from ._backend import get_backend, normalize_virtual_path
if 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 e
return {"content": content, "file_path": file_path}
diff --git a/server/nodes/filesystem/fs_search.py b/server/nodes/filesystem/fs_search.py
index 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, Optional
from pydantic import BaseModel, ConfigDict, Field
-from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
class 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.py
index 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.py
index 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.py
index 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, Optional
from 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 plugin
wrapper 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 response
if 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.json
index 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__.py
index 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 exposes
from __future__ import annotations
-from services.plugin.base import BaseNode
+from services.plugin.base import BaseNode, NodeUserError
from services.plugin.action import ActionNode
from services.plugin.trigger import TriggerNode
from 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.py
index 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.py
index 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] = resolved
env = {**os.environ, "PYTHONUNBUFFERED": "1"}
from core.config import Settings
workspace_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.md
index 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, men
allowed-tools: twitter_search
metadata:
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 Operators
The 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 replaced
1. Connect the **Twitter Search** node to an AI Agent's `input-tools` handle
2. 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.md
index 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 workspac
allowed-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 [Nu
External 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
## Guidelines
1. **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.