machinaos 0.0.76 → 0.0.78

package/server/{services/android → nodes/android/_relay}/client.py

@@ -207,8 +207,8 @@ class RelayWebSocketClient:
     async def _clear_stored_session(self):
         """Clear stored pairing session from database."""
         try:
-            from core.container import container
-            database = container.database()
+            from services.plugin.deps import get_database
+            database = get_database()
 
             await database.clear_android_relay_session()
             logger.debug("[Relay] Cleared stored pairing session")
@@ -368,8 +368,8 @@ class RelayWebSocketClient:
     async def _save_pairing_session(self):
         """Save pairing session to database for auto-reconnect."""
         try:
-            from core.container import container
-            database = container.database()
+            from services.plugin.deps import get_database
+            database = get_database()
 
             await database.save_android_relay_session(
                 relay_url=self.base_url,

package/server/{routers/android.py → nodes/android/_router.py}

@@ -1,16 +1,32 @@
 """Android System Services routes."""
 
-from fastapi import APIRouter, Depends
+import re
+
+from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field
 from typing import Dict, Any
 
-from core.container import container
-from services.android_service import AndroidService
+from ._dispatcher import AndroidService
 from core.logging import get_logger
+from services.plugin.deps import get_android_service
 
 logger = get_logger(__name__)
 router = APIRouter(prefix="/api/android", tags=["android"])
 
+# ADB device IDs: USB serials (alphanumeric), TCP "host:port" (digits + dots
+# + colon), or "emulator-NNNN". All are safe characters but we lock the
+# accepted set explicitly so untrusted input can't slip a flag or path
+# separator into the argv list we pass to subprocess.run. Anything outside
+# `[A-Za-z0-9._:-]` (and longer than 64 chars) is rejected with 400.
+_DEVICE_ID_PATTERN = re.compile(r"^[A-Za-z0-9._:-]{1,64}$")
+
+
+def _validate_device_id(device_id: str) -> str:
+    """Return device_id if it matches the ADB device-id shape, else 400."""
+    if not _DEVICE_ID_PATTERN.fullmatch(device_id):
+        raise HTTPException(status_code=400, detail="invalid device_id")
+    return device_id
+
 
 class AndroidServiceRequest(BaseModel):
     """Request model for Android service execution."""
@@ -24,7 +40,7 @@ class AndroidServiceRequest(BaseModel):
 @router.post("/execute")
 async def execute_android_service(
     request: AndroidServiceRequest,
-    android_service: AndroidService = Depends(lambda: container.android_service())
+    android_service: AndroidService = Depends(get_android_service)
 ):
     """Execute an Android system service action.
 
@@ -57,7 +73,7 @@ async def execute_android_service(
 async def check_device_status(
     android_host: str = "localhost",
     android_port: int = 8888,
-    android_service: AndroidService = Depends(lambda: container.android_service())
+    android_service: AndroidService = Depends(get_android_service)
 ):
     """Check if Android device API is reachable."""
     logger.info(
@@ -77,7 +93,7 @@ async def check_device_status(
 @router.get("/services/{service_id}/actions")
 async def get_service_actions(
     service_id: str,
-    android_service: AndroidService = Depends(lambda: container.android_service())
+    android_service: AndroidService = Depends(get_android_service)
 ):
     """Get available actions for a specific Android service.
 
@@ -105,7 +121,7 @@ async def get_service_actions(
 async def get_action_parameters(
     service_id: str,
     action: str,
-    android_service: AndroidService = Depends(lambda: container.android_service())
+    android_service: AndroidService = Depends(get_android_service)
 ):
     """Get default parameters for a specific service action.
 
@@ -195,9 +211,12 @@ async def setup_port_forwarding(
     device_port: int = 8888
 ):
     """Setup ADB port forwarding for Android device communication."""
+    device_id = _validate_device_id(device_id)
     import subprocess
     try:
         # Setup port forwarding: adb -s device_id forward tcp:local_port tcp:device_port
+        # device_id passes _DEVICE_ID_PATTERN above; subprocess.run is called
+        # with an argv list (no shell), so no further interpolation risk.
         cmd = ["adb", "-s", device_id, "forward", f"tcp:{local_port}", f"tcp:{device_port}"]
 
         result = subprocess.run(
@@ -258,7 +277,7 @@ async def get_relay_connection_status():
     and the paired Android device.
     """
     try:
-        from services.android import get_current_relay_client
+        from ._relay import get_current_relay_client
 
         relay_client = get_current_relay_client()
 

package/server/nodes/browser/browser.py

@@ -3,7 +3,7 @@
 Interactive browser automation via the agent-browser CLI. The plugin
 maps the high-level operation enum to CLI argv, resolves the browser
 binary (system Chrome / Edge / Chromium / bundled), and delegates the
-subprocess invocation to ``services.browser_service``.
+subprocess invocation to ``_service`` (the plugin-private service).
 """
 
 from __future__ import annotations
@@ -317,7 +317,7 @@ class BrowserNode(ActionNode):
 
     @Operation("dispatch")
     async def dispatch(self, ctx: NodeContext, params: BrowserParams) -> BrowserOutput:
-        from services.browser_service import get_browser_service
+        from ._service import get_browser_service
 
         svc = get_browser_service()
         if not svc:

package/server/nodes/code/_base.py

@@ -29,9 +29,13 @@ class CodeExecutorOutput(BaseModel):
 
 
 class CodeExecutorBase(ActionNode, abstract=True):
-    """Subclass and set type / display_name / icon / handler import."""
+    """Subclass and set type / display_name / handler import.
+
+    Visual metadata (icon + color) lives in ``server/nodes/visuals.json``
+    keyed by individual plugin type. The ``_visuals.py`` resolver picks
+    each entry up at NodeSpec emit time; no class-level ClassVars needed.
+    """
 
-    color = "#ffb86c"
     group = ("code", "tool")
     component_kind = "square"
     handles = (

package/server/nodes/code/_claude_code.py

@@ -0,0 +1,134 @@
+"""Legacy single-task Claude Code shim.
+
+Kept for back-compat with any caller that still imports
+`get_claude_code_service()`. New code should call
+`services.cli_agent.AICliService.run_batch("claude", ...)` directly via
+the `claude_code_agent` plugin.
+
+This module:
+  - Builds a single ``ClaudeTaskSpec`` from kwargs
+  - Calls ``AICliService.run_batch("claude", ...)``
+  - Adapts the ``BatchResult`` back into the dict shape the legacy
+    callers expected
+
+Eventually deletable once all imports point at ``cli_agent.service``.
+The hardcoded 300s `wait_for` is gone — ``timeout_seconds`` is now per
+task and configurable.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from core.config import Settings
+from core.logging import get_logger
+
+from services.cli_agent import ClaudeTaskSpec
+from services.cli_agent.service import get_ai_cli_service
+from services.plugin.singleton import ServiceSingleton
+
+logger = get_logger(__name__)
+
+
+class ClaudeCodeService(ServiceSingleton):
+    """Thin shim that adapts to the new AICliService."""
+
+    def __init__(self) -> None:
+        self._session_map: Dict[str, str] = {}  # node_id -> session_id
+
+    async def execute(
+        self,
+        prompt: str,
+        node_id: str = "",
+        model: str = "claude-sonnet-4-6",
+        cwd: Optional[str] = None,
+        allowed_tools: str = "Read,Edit,Bash,Glob,Grep,Write",
+        max_turns: int = 10,
+        max_budget_usd: float = 5.0,
+        system_prompt: Optional[str] = None,
+        timeout_seconds: int = 600,
+    ) -> Dict[str, Any]:
+        """Run a single Claude Code task. Returns legacy dict shape."""
+        if not cwd:
+            cwd = os.path.join(Settings().workspace_base_resolved, "default")
+            os.makedirs(cwd, exist_ok=True)
+
+        # Resume the prior session for this node if we have one
+        resume_session_id = self._session_map.get(node_id) if node_id else None
+
+        task = ClaudeTaskSpec(
+            task_id=f"legacy_{node_id}" if node_id else "legacy",
+            prompt=prompt,
+            model=model,
+            max_turns=max_turns,
+            max_budget_usd=max_budget_usd,
+            allowed_tools=allowed_tools,
+            system_prompt=system_prompt,
+            timeout_seconds=timeout_seconds,
+            resume_session_id=resume_session_id,
+        )
+
+        svc = get_ai_cli_service()
+        workspace_dir = Path(cwd)
+        repo_root = self._find_git_repo(workspace_dir)
+
+        result = await svc.run_batch(
+            "claude",
+            tasks=[task],
+            node_id=node_id or "legacy_node",
+            workflow_id="legacy_workflow",
+            workspace_dir=workspace_dir,
+            broadcaster=None,
+            repo_root=repo_root,
+        )
+
+        if not result.tasks:
+            raise RuntimeError("AICliService returned empty batch")
+
+        sr = result.tasks[0]
+        if not sr.success:
+            raise RuntimeError(sr.error or "claude_code_service: task failed")
+
+        # Persist session_id for future resume
+        if sr.session_id and node_id:
+            self._session_map[node_id] = sr.session_id
+
+        return {
+            "result": sr.response,
+            "session_id": sr.session_id or "",
+            "total_cost_usd": sr.cost_usd,
+            "duration_ms": sr.duration_ms,
+            "num_turns": sr.num_turns,
+            "usage": {
+                "input_tokens": sr.canonical_usage.input_tokens,
+                "output_tokens": sr.canonical_usage.output_tokens,
+                "cache_creation_input_tokens": sr.canonical_usage.cache_write,
+                "cache_read_input_tokens": sr.canonical_usage.cache_read,
+            },
+        }
+
+    def get_session_id(self, node_id: str) -> Optional[str]:
+        return self._session_map.get(node_id)
+
+    def clear_session(self, node_id: str) -> None:
+        self._session_map.pop(node_id, None)
+
+    @staticmethod
+    def _find_git_repo(start: Path) -> Optional[Path]:
+        """Walk up from `start` looking for a `.git` directory."""
+        cur = start.resolve()
+        for _ in range(8):
+            if (cur / ".git").exists():
+                return cur
+            if cur.parent == cur:
+                return None
+            cur = cur.parent
+        return None
+
+
+def get_claude_code_service() -> ClaudeCodeService:
+    """Module-level accessor preserved for legacy callers; delegates to
+    the :class:`ServiceSingleton` mixin's ``instance()`` classmethod."""
+    return ClaudeCodeService.instance()

package/server/nodes/document/embedding_generator.py

@@ -7,7 +7,7 @@ from typing import List, 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 EmbeddingGeneratorParams(BaseModel):
@@ -83,7 +83,7 @@ class EmbeddingGeneratorNode(ActionNode):
             try:
                 from langchain_huggingface import HuggingFaceEmbeddings
             except ImportError:
-                raise RuntimeError(
+                raise NodeUserError(
                     "HuggingFace embeddings unavailable. "
                     "pip install langchain-huggingface sentence-transformers",
                 )
@@ -95,7 +95,7 @@ class EmbeddingGeneratorNode(ActionNode):
             from langchain_ollama import OllamaEmbeddings
             embedder = OllamaEmbeddings(model=model)
         else:
-            raise RuntimeError(f"Unknown provider: {provider}")
+            raise NodeUserError(f"Unknown provider: {provider}")
 
         embeddings = await asyncio.to_thread(embedder.embed_documents, texts)
         dimensions = len(embeddings[0]) if embeddings else 0

package/server/nodes/document/http_scraper.py

@@ -15,7 +15,7 @@ from bs4 import BeautifulSoup
 from pydantic import BaseModel, ConfigDict, Field
 
 from core.logging import get_logger
-from services.plugin import ActionNode, NodeContext, Operation, TaskQueue
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
 
 logger = get_logger(__name__)
 
@@ -130,7 +130,7 @@ class HttpScraperNode(ActionNode):
     async def scrape(self, ctx: NodeContext, params: HttpScraperParams) -> HttpScraperOutput:
         url = params.url
         if not url:
-            raise RuntimeError("URL is required")
+            raise NodeUserError("URL is required")
 
         iteration_mode = params.iteration_mode
         link_selector = params.link_selector or 'a[href$=".pdf"]'
@@ -140,7 +140,7 @@ class HttpScraperNode(ActionNode):
         urls_to_fetch = []
         if iteration_mode == 'date':
             if not params.start_date or not params.end_date:
-                raise RuntimeError("start_date/end_date required for date mode")
+                raise NodeUserError("start_date/end_date required for date mode")
             placeholder = params.date_placeholder or '{date}'
             start = datetime.strptime(params.start_date, "%Y-%m-%d")
             end = datetime.strptime(params.end_date, "%Y-%m-%d")

package/server/nodes/document/vector_store.py

@@ -13,7 +13,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
 
 
 class VectorStoreParams(BaseModel):
@@ -70,7 +70,7 @@ async def _chroma_op(operation: str, params: Dict[str, Any], collection: str) ->
     try:
         import chromadb
     except ImportError:
-        raise RuntimeError("ChromaDB unavailable. pip install chromadb")
+        raise NodeUserError("ChromaDB unavailable. pip install chromadb")
 
     persist_dir = params.get('persist_dir', './data/vectors')
     client = chromadb.PersistentClient(path=persist_dir)
@@ -126,7 +126,7 @@ async def _qdrant_op(operation: str, params: Dict[str, Any], collection: str) ->
         from qdrant_client import QdrantClient
         from qdrant_client.models import Distance, PointStruct, VectorParams
     except ImportError:
-        raise RuntimeError("Qdrant client unavailable. pip install qdrant-client")
+        raise NodeUserError("Qdrant client unavailable. pip install qdrant-client")
 
     url = params.get('qdrant_url', 'http://localhost:6333')
     client = QdrantClient(url=url)
@@ -188,7 +188,7 @@ async def _pinecone_op(operation: str, params: Dict[str, Any], collection: str)
 
     api_key = params.get('pinecone_api_key', '')
     if not api_key:
-        raise RuntimeError("Pinecone API key required")
+        raise NodeUserError("Pinecone API key required")
 
     pc = Pinecone(api_key=api_key)
     index = pc.Index(collection)
@@ -271,7 +271,7 @@ class VectorStoreNode(ActionNode):
         elif backend == 'pinecone':
             result = await _pinecone_op(operation, p, collection)
         else:
-            raise RuntimeError(f"Unknown backend: {backend_raw}")
+            raise NodeUserError(f"Unknown backend: {backend_raw}")
 
         result['backend'] = backend
         result['collection_name'] = collection

package/server/nodes/email/__init__.py

@@ -1 +1,11 @@
-"""Plugins for the 'email' palette group. See ../__init__.py for the package layout."""
+"""Plugins for the 'email' palette group.
+
+Self-registers the trigger filter builder for ``emailReceive`` so the
+central ``services/event_waiter.py`` carries no plugin-specific code.
+"""
+
+from services.event_waiter import register_filter_builder
+
+from ._filters import build_filter as build_email_filter
+
+register_filter_builder("emailReceive", build_email_filter)

package/server/nodes/email/_filters.py

@@ -0,0 +1,21 @@
+"""Email event-trigger filter builder (Wave 11.I, milestone K).
+
+Moved verbatim from ``services/event_waiter.build_email_filter``.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict
+
+
+def build_filter(params: Dict) -> Callable[[Dict], bool]:
+    """Build filter for email events (Himalaya IMAP polling)."""
+    folder_filter = params.get('folder', 'INBOX')
+
+    def matches(data: Dict) -> bool:
+        if folder_filter and folder_filter != 'all':
+            if data.get('folder', '') != folder_filter:
+                return False
+        return True
+
+    return matches

package/server/{services/himalaya_service.py → nodes/email/_himalaya.py}

@@ -14,24 +14,20 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from core.logging import get_logger
+from services.plugin.singleton import ServiceSingleton
 
 logger = get_logger(__name__)
 
 
-class HimalayaService:
-    """Manages Himalaya CLI configuration and execution."""
+class HimalayaService(ServiceSingleton):
+    """Manages Himalaya CLI configuration and execution.
 
-    _instance: Optional["HimalayaService"] = None
+    Inherits ``instance`` / ``reset_instance`` from
+    :class:`ServiceSingleton`."""
 
     def __init__(self):
         self._binary_path: Optional[str] = None
 
-    @classmethod
-    def get_instance(cls) -> "HimalayaService":
-        if cls._instance is None:
-            cls._instance = cls()
-        return cls._instance
-
     async def ensure_binary(self) -> str:
         """Detect himalaya binary in PATH. Returns path or raises."""
         if self._binary_path:
@@ -265,4 +261,4 @@ class HimalayaService:
 
 def get_himalaya_service() -> HimalayaService:
     """Get singleton instance."""
-    return HimalayaService.get_instance()
+    return HimalayaService.instance()

package/server/{services/email_service.py → nodes/email/_service.py}

@@ -8,11 +8,12 @@ from pathlib import Path
 from typing import Any, Dict, Optional, Set
 
 from core.logging import get_logger
+from services.plugin.singleton import ServiceSingleton
 
 logger = get_logger(__name__)
 
 _CONFIG: Optional[Dict] = None
-_CONFIG_PATH = Path(__file__).parent.parent / "config" / "email_providers.json"
+_CONFIG_PATH = Path(__file__).resolve().parents[2] / "config" / "email_providers.json"
 
 
 def _load_config() -> Dict:
@@ -23,14 +24,9 @@ def _load_config() -> Dict:
     return _CONFIG
 
 
-class EmailService:
-    _instance: Optional["EmailService"] = None
-
-    @classmethod
-    def get_instance(cls) -> "EmailService":
-        if cls._instance is None:
-            cls._instance = cls()
-        return cls._instance
+class EmailService(ServiceSingleton):
+    """Plugin-owned email orchestrator. Inherits ``instance`` /
+    ``reset_instance`` from :class:`ServiceSingleton`."""
 
     @property
     def config(self) -> Dict:
@@ -46,7 +42,7 @@ class EmailService:
 
     @property
     def himalaya(self):
-        from services.himalaya_service import get_himalaya_service
+        from ._himalaya import get_himalaya_service
         return get_himalaya_service()
 
     def _provider_preset(self, name: str) -> Dict:
@@ -61,8 +57,8 @@ class EmailService:
         Stored custom keys (email_imap_host, email_smtp_port, etc.) are used when
         the provider is 'custom' or when a preset field is empty.
         """
-        from core.container import container
-        auth = container.auth_service()
+        from services.plugin.deps import get_auth_service
+        auth = get_auth_service()
 
         provider = params.get("provider") or await auth.get_api_key("email_provider") or self.defaults.get("provider")
         preset = self._provider_preset(provider)
@@ -184,4 +180,4 @@ class EmailService:
 
 
 def get_email_service() -> EmailService:
-    return EmailService.get_instance()
+    return EmailService.instance()

package/server/nodes/email/email_read.py

@@ -120,5 +120,5 @@ class EmailReadNode(ActionNode):
     @Operation("query", cost={"service": "email", "action": "imap", "count": 1})
     async def query(self, ctx: NodeContext, params: EmailReadParams) -> Any:
         # Body inlined from handlers/email.py (Wave 11.D.1).
-        from services.email_service import get_email_service
+        from ._service import get_email_service
         return await get_email_service().read(params.model_dump())

package/server/nodes/email/email_receive.py

@@ -6,11 +6,13 @@ IMAP polling for new mail via Himalaya CLI. Thin delegation to
 
 from __future__ import annotations
 
-from typing import Any, Dict, Literal, Optional
+from typing import Any, Dict, Literal, Optional, Set
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from services.plugin import NodeContext, Operation, TaskQueue, TriggerNode
+from services.plugin import (
+    NodeContext, Operation, PollingTriggerNode, TaskQueue,
+)
 
 
 class EmailReceiveParams(BaseModel):
@@ -35,23 +37,70 @@ class EmailReceiveOutput(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class EmailReceiveNode(TriggerNode):
+class EmailReceiveNode(PollingTriggerNode):
     type = "emailReceive"
     display_name = "Email Receive"
     subtitle = "IMAP Polling"
     group = ("email", "trigger")
     description = "Polling trigger for new emails via IMAP"
     component_kind = "trigger"
+    # Wave 11.I, milestone K: ``event_type`` ClassVar lets
+    # ``event_waiter._auto_populate_from_plugins`` backfill
+    # TRIGGER_REGISTRY without a hardcoded entry in event_waiter.
+    event_type = "email_received"
     handles = (
         {"name": "output-main", "kind": "output", "position": "right",
          "label": "Output", "role": "main"},
     )
     task_queue = TaskQueue.TRIGGERS_POLL
-    mode = "polling"
+    # Email keeps its 30s lower bound (legacy floor in
+    # config/email_providers.json). Gmail uses the default (10, 3600).
+    poll_interval_clamp = (30, 3600)
 
     Params = EmailReceiveParams
     Output = EmailReceiveOutput
 
+    # ---- PollingTriggerNode hooks (deployment-mode loop) -------------
+    #
+    # The Run-button path lives in ``execute()`` below and stays
+    # bespoke: it broadcasts ``waiting`` status, dispatches via
+    # event_waiter, and returns after the first new email. The
+    # deployment loop owned by ``PollingTriggerNode`` drains
+    # continuously via the deployment manager's queue and uses the
+    # four hooks below.
+
+    async def setup_service(self, params: Dict[str, Any]) -> Any:
+        from ._service import get_email_service
+
+        svc = get_email_service()
+        creds = await svc.resolve_credentials(params)
+        cfg = svc.resolve_poll_params(params)
+        return svc, creds, cfg["folder"], cfg.get("mark_as_read", False)
+
+    async def fetch_ids(self, service: Any, params: Dict[str, Any]) -> Set[str]:
+        svc, creds, folder, _mark = service
+        return await svc.poll_ids(creds, folder)
+
+    async def fetch_detail(
+        self, service: Any, msg_id: str, params: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        svc, creds, folder, _mark = service
+        return await svc.fetch_detail(creds, msg_id, folder)
+
+    async def post_emit(
+        self, service: Any, msg_id: str, params: Dict[str, Any]
+    ) -> None:
+        svc, creds, folder, mark = service
+        if not mark:
+            return
+        try:
+            d = svc.defaults
+            await svc.himalaya.flag_message(
+                creds, msg_id, d.get("flag"), d.get("flag_action"), folder,
+            )
+        except Exception:
+            pass
+
     async def execute(
         self,
         node_id: str,
@@ -68,7 +117,7 @@ class EmailReceiveNode(TriggerNode):
         import asyncio
         import time
         from datetime import datetime
-        from services.email_service import get_email_service
+        from ._service import get_email_service
         from services.status_broadcaster import get_status_broadcaster
         from services import event_waiter
 

package/server/nodes/email/email_send.py

@@ -54,5 +54,5 @@ class EmailSendNode(ActionNode):
     @Operation("send", cost={"service": "email", "action": "send", "count": 1})
     async def send(self, ctx: NodeContext, params: EmailSendParams) -> Any:
         # Body inlined from handlers/email.py (Wave 11.D.1).
-        from services.email_service import get_email_service
+        from ._service import get_email_service
         return await get_email_service().send(params.model_dump(by_alias=False))

package/server/nodes/filesystem/shell.py

@@ -2,11 +2,21 @@
 
 from __future__ import annotations
 
+import re
 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
+
+
+# Bash chain-operators (` && ` / ` || `) are explicitly rejected by the
+# Nushell parser. Detect them up-front so the LLM gets a corrective
+# message ("use `;` or `try { … }`") instead of nu's
+# ``shell_andand`` / ``shell_oror`` parse error two layers down.
+# Surrounding spaces ensure we don't flag valid nu syntax accidentally
+# (closure params `|x|` never carry spaces around the pipe pair).
+_BASH_CHAIN_RE = re.compile(r"\s(\&\&|\|\|)\s")
 
 
 class ShellParams(BaseModel):
@@ -51,6 +61,19 @@ class ShellNode(ActionNode):
         from ._backend import get_backend
 
         log = get_logger(__name__)
+
+        # Pre-flight: catch the most common bash-style chain mistake before
+        # Nushell's parser does, so the LLM sees an actionable hint instead
+        # of ``nu::parser::shell_andand``. Documented in
+        # ``server/skills/terminal/shell-skill/SKILL.md``.
+        if (m := _BASH_CHAIN_RE.search(params.command)):
+            op = m.group(1)
+            replacement = "; (sequential)" if op == "&&" else "try { … } catch { … }"
+            raise NodeUserError(
+                f"Nushell does not support `{op}`. Use `{replacement}` instead. "
+                "See shell-skill: https://www.nushell.sh/book/control_flow.html"
+            )
+
         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