machinaos 0.0.76 → 0.0.78

package/server/services/events/triggers.py

@@ -0,0 +1,118 @@
+"""Generic TriggerNode base classes backed by EventSources.
+
+Plugins subclass :class:`WebhookTriggerNode` and declare:
+
+    type, display_name, group, ...      (standard plugin metadata)
+    webhook_source: ClassVar[Type[WebhookSource]]
+    Params, Output                      (Pydantic models)
+    shape_output(event)  (optional)     reshape WorkflowEvent -> Output dict
+    _check_precondition() (optional)    return error str if not ready
+    _extra_filter(params) (optional)    additional filter on top of event_type
+
+The base provides:
+    - event_type derived from webhook_source.type
+    - build_filter combining CloudEvents type-glob + _extra_filter
+    - execute() with precheck + shape passthrough
+    - the standard Operation("wait") stub
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, ClassVar, Dict, Optional, Type
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from services.plugin import NodeContext, Operation, TaskQueue, TriggerNode
+
+from .envelope import WorkflowEvent
+from .webhook import WebhookSource
+
+
+class BaseTriggerParams(BaseModel):
+    """Default Params for WebhookTriggerNode subclasses. Subclass and add
+    provider-specific filters."""
+
+    event_type_filter: str = Field(
+        default="all",
+        description=(
+            "Event type to match. 'all' for every event, exact name, "
+            "or wildcard prefix (e.g. 'foo.*')."
+        ),
+    )
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class WebhookTriggerNode(TriggerNode):
+    """TriggerNode whose events arrive through a :class:`WebhookSource`.
+
+    The framework owns the wait/dispatch flow; subclasses describe only
+    the differences from the generic shape.
+    """
+
+    webhook_source: ClassVar[Optional[Type[WebhookSource]]] = None
+    # Auto-prepended to ``event_type_filter`` so users can type "charge.*"
+    # instead of "stripe.charge.*". Empty disables the convenience.
+    event_type_prefix: ClassVar[str] = ""
+    mode: ClassVar[str] = "event"
+    task_queue: ClassVar[str] = TaskQueue.TRIGGERS_EVENT
+    Params: ClassVar[Type[BaseModel]] = BaseTriggerParams
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if cls.webhook_source is not None and not getattr(cls, "event_type", ""):
+            cls.event_type = cls.webhook_source.type
+
+    def build_filter(self, params: BaseModel) -> Callable[[Any], bool]:
+        type_filter = (getattr(params, "event_type_filter", "") or "all").strip()
+        if (
+            type_filter
+            and type_filter != "all"
+            and self.event_type_prefix
+            and not type_filter.startswith(self.event_type_prefix)
+        ):
+            type_filter = self.event_type_prefix + type_filter
+        extras = self._extra_filter(params)
+
+        def matches(event: Any) -> bool:
+            ev = event if isinstance(event, WorkflowEvent) else WorkflowEvent(**event)
+            if not ev.matches_type(type_filter):
+                return False
+            return extras(ev) if extras else True
+
+        return matches
+
+    def _extra_filter(self, params: BaseModel) -> Optional[Callable[[WorkflowEvent], bool]]:
+        """Override for filters beyond event-type matching (e.g. livemode)."""
+        return None
+
+    async def _check_precondition(self) -> Optional[str]:
+        """Override to short-circuit. Return error string or None."""
+        return None
+
+    async def execute(
+        self,
+        node_id: str,
+        parameters: Dict[str, Any],
+        context,
+    ) -> Dict[str, Any]:
+        err = await self._check_precondition()
+        if err:
+            return self._wrap_error(start_time=time.time(), error=err)
+        result = await super().execute(node_id, parameters, context)
+        if result.get("success"):
+            event = result.get("result") or {}
+            ev = event if isinstance(event, WorkflowEvent) else WorkflowEvent(**event)
+            result["result"] = self.shape_output(ev)
+        return result
+
+    def shape_output(self, event: WorkflowEvent) -> Dict[str, Any]:
+        """Default: dump the CloudEvent. Override for provider-shaped output."""
+        return event.model_dump(mode="json")
+
+    @Operation("wait")
+    async def wait(self, ctx: NodeContext, params: BaseModel):
+        raise NotImplementedError(
+            "Event triggers return via TriggerNode.execute, not the op body"
+        )

package/server/services/events/verifiers/__init__.py

@@ -0,0 +1,25 @@
+"""Webhook signature verifiers — pluggable HMAC schemes per provider.
+
+Each verifier is a stateless class with one method:
+
+    verify(headers, body, secret) -> None    # raises ValueError on mismatch
+
+Plugins reference verifier classes directly; there's no string-keyed
+registry to avoid (yet another) lookup table.
+"""
+
+from __future__ import annotations
+
+from .base import WebhookVerifier
+from .hmac_basic import HmacVerifier
+from .stripe import StripeVerifier
+from .standard_webhooks import StandardWebhooksVerifier
+from .github import GitHubVerifier
+
+__all__ = [
+    "WebhookVerifier",
+    "HmacVerifier",
+    "StripeVerifier",
+    "StandardWebhooksVerifier",
+    "GitHubVerifier",
+]

package/server/services/events/verifiers/base.py

@@ -0,0 +1,28 @@
+"""Webhook verifier base — single-method contract."""
+
+from __future__ import annotations
+
+from typing import Mapping
+
+
+class WebhookVerifier:
+    """Abstract base. Each provider's signature scheme is one subclass."""
+
+    @classmethod
+    def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+        """Raise ``ValueError`` if the request is not authentic.
+
+        ``headers`` is case-insensitive at the caller's discretion;
+        verifiers handle the lookup themselves to stay defensive.
+        ``body`` is the raw request bytes (signed payload).
+        ``secret`` is the provider-issued signing secret.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def _header(headers: Mapping[str, str], name: str) -> str:
+        target = name.lower()
+        for k, v in headers.items():
+            if k.lower() == target:
+                return v
+        return ""

package/server/services/events/verifiers/github.py

@@ -0,0 +1,25 @@
+"""GitHub webhook signature verifier.
+
+Header: ``X-Hub-Signature-256: sha256=<hex_hmac>``
+Algorithm: HMAC-SHA256 of the secret over the raw body, hex-encoded.
+Reference: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Mapping
+
+from .base import WebhookVerifier
+
+
+class GitHubVerifier(WebhookVerifier):
+    @classmethod
+    def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+        sig = cls._header(headers, "x-hub-signature-256")
+        if not sig.startswith("sha256="):
+            raise ValueError("X-Hub-Signature-256 missing or malformed")
+        expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(expected, sig):
+            raise ValueError("X-Hub-Signature-256 mismatch")

package/server/services/events/verifiers/hmac_basic.py

@@ -0,0 +1,32 @@
+"""Generic HMAC-SHA256 verifier — fallback for providers whose scheme
+is "single header carrying hex HMAC of the raw body".
+
+Subclasses customise :attr:`header_name` and (optionally)
+:attr:`signature_prefix`. The default reads ``X-Signature-256`` and
+expects a bare hex digest.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import ClassVar, Mapping
+
+from .base import WebhookVerifier
+
+
+class HmacVerifier(WebhookVerifier):
+    header_name: ClassVar[str] = "X-Signature-256"
+    signature_prefix: ClassVar[str] = ""  # e.g. "sha256=" for some providers
+
+    @classmethod
+    def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+        sig = cls._header(headers, cls.header_name)
+        if not sig:
+            raise ValueError(f"{cls.header_name} header missing")
+        if cls.signature_prefix and not sig.startswith(cls.signature_prefix):
+            raise ValueError(f"{cls.header_name} missing prefix {cls.signature_prefix!r}")
+        provided = sig[len(cls.signature_prefix):]
+        expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(expected, provided):
+            raise ValueError(f"{cls.header_name} mismatch")

package/server/services/events/verifiers/standard_webhooks.py

@@ -0,0 +1,47 @@
+"""Standard Webhooks (Svix) signature verifier.
+
+Spec: https://www.standardwebhooks.com/
+Headers: ``webhook-id``, ``webhook-timestamp``, ``webhook-signature``
+Signed payload: ``f"{webhook-id}.{webhook-timestamp}.{raw_body}"``
+Algorithm: HMAC-SHA256 of the secret (b64-decoded after the ``whsec_`` prefix
+is stripped) over the signed payload, base64-encoded.
+``webhook-signature`` may carry multiple space-separated ``v1,<sig>`` entries
+to support secret rotation.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from typing import Mapping
+
+from .base import WebhookVerifier
+
+
+class StandardWebhooksVerifier(WebhookVerifier):
+    @classmethod
+    def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+        msg_id = cls._header(headers, "webhook-id")
+        timestamp = cls._header(headers, "webhook-timestamp")
+        sig_header = cls._header(headers, "webhook-signature")
+        if not (msg_id and timestamp and sig_header):
+            raise ValueError("Standard Webhooks headers missing")
+
+        if secret.startswith("whsec_"):
+            key = base64.b64decode(secret[len("whsec_"):])
+        else:
+            key = secret.encode()
+
+        signed = f"{msg_id}.{timestamp}.".encode() + body
+        expected = base64.b64encode(
+            hmac.new(key, signed, hashlib.sha256).digest()
+        ).decode()
+
+        candidates: list[str] = []
+        for part in sig_header.split():
+            if "," in part:
+                _, value = part.split(",", 1)
+                candidates.append(value)
+        if not any(hmac.compare_digest(expected, c) for c in candidates):
+            raise ValueError("Standard Webhooks signature mismatch")

package/server/services/events/verifiers/stripe.py

@@ -0,0 +1,42 @@
+"""Stripe webhook signature verifier.
+
+Header format: ``Stripe-Signature: t=<unix_ts>,v1=<hex_hmac>[,v1=<rotated>]``
+Signed payload: ``f"{timestamp}.{raw_body}"``  (HMAC-SHA256, hex)
+Reference: https://stripe.com/docs/webhooks/signatures
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Mapping
+
+from .base import WebhookVerifier
+
+
+class StripeVerifier(WebhookVerifier):
+    @classmethod
+    def verify(cls, headers: Mapping[str, str], body: bytes, secret: str) -> None:
+        sig_header = cls._header(headers, "stripe-signature")
+        if not sig_header:
+            raise ValueError("Stripe-Signature header missing")
+
+        timestamp = ""
+        candidates: list[str] = []
+        for part in sig_header.split(","):
+            if "=" not in part:
+                continue
+            k, v = part.split("=", 1)
+            k = k.strip()
+            v = v.strip()
+            if k == "t":
+                timestamp = v
+            elif k == "v1":
+                candidates.append(v)
+        if not timestamp or not candidates:
+            raise ValueError("Stripe-Signature missing t= or v1= component")
+
+        signed = f"{timestamp}.".encode() + body
+        expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
+        if not any(hmac.compare_digest(expected, c) for c in candidates):
+            raise ValueError("Stripe-Signature mismatch")

package/server/services/events/webhook.py

@@ -0,0 +1,105 @@
+"""WebhookSource — push source backed by an HTTP POST to /webhook/{path}.
+
+Plugins subclass and declare:
+
+    class MyWebhook(WebhookSource):
+        path = "myprovider"
+        verifier = MyVerifier        # WebhookVerifier subclass (optional)
+        secret_field = "my_webhook_secret"  # extra field on the credential
+
+        async def shape(self, request, body, payload) -> WorkflowEvent: ...
+
+A single edit to ``routers/webhook.py`` consults :data:`WEBHOOK_SOURCES`
+before the legacy generic dispatch path. No plugin name is hardcoded
+in the router.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import ClassVar, Dict, Optional, Type
+
+from fastapi import HTTPException, Request
+
+from core.logging import get_logger
+
+from .envelope import WorkflowEvent
+from .push import PushEventSource
+from .verifiers import WebhookVerifier
+
+logger = get_logger(__name__)
+
+
+WEBHOOK_SOURCES: Dict[str, "WebhookSource"] = {}
+
+
+def register_webhook_source(source: "WebhookSource") -> None:
+    """Idempotent: same instance for the same path is a no-op; conflicts raise."""
+    existing = WEBHOOK_SOURCES.get(source.path)
+    if existing is not None and existing is not source:
+        raise ValueError(
+            f"Webhook path {source.path!r} already registered to {type(existing).__name__}"
+        )
+    WEBHOOK_SOURCES[source.path] = source
+
+
+class WebhookSource(PushEventSource):
+    """Base for HTTP-webhook event sources.
+
+    Subclass contract:
+        path:           URL fragment under /webhook/
+        verifier:       WebhookVerifier subclass (or None to skip verification)
+        secret_field:   credential extra-field name holding the signing secret
+        shape():        turn the verified request into a WorkflowEvent
+    """
+
+    path: ClassVar[str] = ""
+    verifier: ClassVar[Optional[Type[WebhookVerifier]]] = None
+    secret_field: ClassVar[Optional[str]] = None
+
+    async def _resolve_secret(self) -> Optional[str]:
+        if self.secret_field is None or self.credential is None:
+            return None
+        try:
+            secrets = await self.credential.resolve()
+        except PermissionError:
+            return None
+        return secrets.get(self.secret_field)
+
+    async def shape(self, request: Request, body: bytes, payload: dict) -> WorkflowEvent:
+        """Override to map the verified payload into a CloudEvent."""
+        return WorkflowEvent(
+            source=f"webhook://{self.path}",
+            type=f"webhook.{self.path}",
+            data=payload,
+        )
+
+    async def handle(self, request: Request) -> WorkflowEvent:
+        """Called by the webhook router. Verifies signature, parses the
+        body, shapes the event, dispatches into ``event_waiter``, and
+        returns the event for logging / response shaping."""
+        body = await request.body()
+        if self.verifier is not None:
+            secret = await self._resolve_secret()
+            if not secret:
+                logger.warning(
+                    "[%s] no signing secret available; accepting unverified event",
+                    self.type or self.path,
+                )
+            else:
+                try:
+                    self.verifier.verify(dict(request.headers), body, secret)
+                except ValueError as e:
+                    raise HTTPException(status_code=400, detail=str(e))
+
+        try:
+            payload = json.loads(body.decode() or "{}")
+        except (json.JSONDecodeError, UnicodeDecodeError) as e:
+            raise HTTPException(status_code=400, detail=f"invalid JSON body: {e}")
+
+        event = await self.shape(request, body, payload)
+        await self.receive(event)
+
+        from services import event_waiter
+        event_waiter.dispatch(self.type, event)
+        return event

package/server/services/handlers/tools.py

@@ -145,8 +145,19 @@ async def _dispatch_tool(tool_name: str, tool_args: Dict[str, Any],
     node_type = config.get('node_type', '')
     node_params = config.get('parameters', {})
 
-    # Execution context available to all tool handlers (workspace, etc.)
-    context = {'workspace_dir': config.get('workspace_dir', '')}
+    # Execution context for tool handlers. Includes canvas state
+    # (nodes/edges/workflow_id) that callers (chat_tool_executor in
+    # ai.py / rlm adapter / deepagents adapter) plumb in via `config`.
+    # Tools that need canvas awareness (e.g. agentBuilder.inspect_canvas)
+    # read these via NodeContext.nodes / .edges / .workflow_id; tools
+    # that don't simply ignore them.
+    context = {
+        'workspace_dir': config.get('workspace_dir', ''),
+        'nodes': config.get('nodes', []),
+        'edges': config.get('edges', []),
+        'workflow_id': config.get('workflow_id'),
+        'parent_node_id': config.get('parent_node_id'),
+    }
 
     logger.info("[Tool] Executing '%s' (node_type=%s, workspace=%s)", tool_name, node_type, context['workspace_dir'])
 
@@ -201,10 +212,12 @@ async def _dispatch_tool(tool_name: str, tool_args: Dict[str, Any],
         from nodes.android._base import execute_android_service_tool
         return await execute_android_service_tool(tool_args, config)
 
-    # taskManager: dispatcher shares state with the agent-delegation
+    # taskManager: dispatcher reads through to the agent-delegation
     # tracking dicts (_delegated_tasks / _delegation_results) defined
-    # below in this module, so the operation matrix stays here.
+    # below in this module. The operation matrix moved to the plugin
+    # (Wave 11.I, milestone O).
     if node_type == 'taskManager':
+        from nodes.tool.task_manager import _execute_task_manager
         return await _execute_task_manager(tool_args, config)
 
     # proxyConfig: 10-operation matrix lives on the plugin
@@ -242,34 +255,11 @@ async def _dispatch_tool(tool_name: str, tool_args: Dict[str, Any],
 
 
 # _execute_duckduckgo_search: Wave 11.C moved logic to
-# nodes/search/duckduckgo_search.py DuckDuckGoSearchNode.search(), but
-# some contract tests patch sys.modules['ddgs'] and call the flat
-# function directly. The shim below preserves the old (args, config) ->
-# dict signature so those tests stay plumbing-only.
-async def _execute_duckduckgo_search(
-    args: Dict[str, Any],
-    config: Dict[str, Any] = None,
-) -> Dict[str, Any]:
-    """Back-compat wrapper around the plugin search path."""
-    config = config or {}
-    query = str(args.get("query", "")).strip()
-    if not query:
-        return {"error": "No search query provided"}
-    max_results = int(config.get("max_results", args.get("max_results", 5)))
-    provider = config.get("provider", "duckduckgo")
-    from ddgs import DDGS
-    raw = list(DDGS().text(query, max_results=max_results))
-    results = [
-        {
-            "title": item.get("title", ""),
-            "snippet": item.get("body", ""),
-            "url": item.get("href", ""),
-        }
-        for item in raw
-    ]
-    return {"query": query, "provider": provider, "results": results}
-
-
+# nodes/search/duckduckgo_search.py DuckDuckGoSearchNode.search(). Wave
+# 11.I milestone O moved the flat (args, config) -> dict shim used by
+# contract tests to tests/nodes/_compat.py -- production code never
+# called it.
+#
 # Wave 11.D.9: _execute_whatsapp_{send,db} deleted. WhatsApp tool execution
 # now routes through the plugin fast-path (nodes/whatsapp/*.py).
 
@@ -779,160 +769,12 @@ async def _execute_check_delegated_tasks(args: Dict[str, Any],
     }
 
 
-async def _execute_task_manager(
-    tool_args: Dict[str, Any],
-    config: Dict[str, Any]
-) -> Dict[str, Any]:
-    """Execute task manager operations.
-
-    Dual-purpose: works as AI tool (LLM fills args) or workflow node (uses params).
-
-    Operations:
-    - list_tasks: List all active and completed delegated tasks
-    - get_task: Get status details for a specific task
-    - mark_done: Remove a task from active tracking
-
-    Args:
-        tool_args: Arguments from LLM tool call (operation, task_id, status_filter)
-        config: Tool configuration with node parameters
-
-    Returns:
-        Dict with operation results
-    """
-    # Merge tool_args with node parameters (tool_args takes precedence)
-    params = config.get('parameters', {})
-    operation = tool_args.get('operation') or params.get('operation', 'list_tasks')
-    task_id = tool_args.get('task_id') or params.get('task_id')
-    status_filter = tool_args.get('status_filter') or params.get('status_filter')
-    database = config.get('database')
-
-    logger.debug(f"[TaskManager] Operation: {operation}, task_id: {task_id}, filter: {status_filter}")
-
-    if operation == 'list_tasks':
-        # Collect all tasks from _delegated_tasks and _delegation_results
-        tasks = []
-
-        # Active tasks from asyncio.Task tracking
-        for tid, task in _delegated_tasks.items():
-            if task.done():
-                try:
-                    if task.cancelled():
-                        status = 'cancelled'
-                    elif task.exception():
-                        status = 'error'
-                    else:
-                        status = 'completed'
-                except Exception:
-                    status = 'completed'
-            else:
-                status = 'running'
-
-            tasks.append({
-                'task_id': tid,
-                'status': status,
-                'active': True
-            })
-
-        # Completed tasks from in-memory cache
-        for tid, result in _delegation_results.items():
-            if tid not in [t['task_id'] for t in tasks]:
-                tasks.append({
-                    'task_id': tid,
-                    'status': result.get('status', 'completed'),
-                    'agent_name': result.get('agent_name'),
-                    'result_summary': str(result.get('result', ''))[:200],
-                    'active': False
-                })
-
-        # Apply status filter
-        if status_filter:
-            tasks = [t for t in tasks if t.get('status') == status_filter]
-
-        return {
-            'success': True,
-            'operation': 'list_tasks',
-            'tasks': tasks,
-            'count': len(tasks),
-            'running': sum(1 for t in tasks if t.get('status') == 'running'),
-            'completed': sum(1 for t in tasks if t.get('status') == 'completed'),
-            'errors': sum(1 for t in tasks if t.get('status') == 'error')
-        }
-
-    elif operation == 'get_task':
-        if not task_id:
-            return {'success': False, 'error': 'task_id is required for get_task operation'}
-
-        # Use existing get_delegated_task_status for detailed lookup
-        result = await get_delegated_task_status(task_ids=[task_id], database=database)
-        tasks = result.get('tasks', [])
-
-        if not tasks:
-            return {
-                'success': False,
-                'error': f'Task {task_id} not found',
-                'task_id': task_id
-            }
-
-        task_info = tasks[0]
-        return {
-            'success': True,
-            'operation': 'get_task',
-            'task_id': task_id,
-            'status': task_info.get('status'),
-            'agent_name': task_info.get('agent_name'),
-            'result': task_info.get('result'),
-            'error': task_info.get('error')
-        }
-
-    elif operation == 'mark_done':
-        if not task_id:
-            return {'success': False, 'error': 'task_id is required for mark_done operation'}
-
-        # Remove from active tracking
-        removed = False
-        if task_id in _delegated_tasks:
-            del _delegated_tasks[task_id]
-            removed = True
-        if task_id in _delegation_results:
-            del _delegation_results[task_id]
-            removed = True
-
-        return {
-            'success': True,
-            'operation': 'mark_done',
-            'task_id': task_id,
-            'removed': removed,
-            'message': f'Task {task_id} marked as done and removed from tracking' if removed else f'Task {task_id} was not in active tracking'
-        }
-
-    return {'success': False, 'error': f'Unknown operation: {operation}'}
-
-
-async def handle_task_manager(
-    node_id: str,
-    node_type: str,
-    parameters: Dict[str, Any],
-    context: Dict[str, Any]
-) -> Dict[str, Any]:
-    """Handle taskManager as workflow node.
-
-    Wrapper for _execute_task_manager that conforms to the standard
-    workflow node handler signature.
-
-    Args:
-        node_id: The node ID
-        node_type: Should be 'taskManager'
-        parameters: Node parameters (operation, task_id, status_filter)
-        context: Execution context
-
-    Returns:
-        Task manager operation results
-    """
-    config = {
-        'parameters': parameters,
-        'database': context.get('database')
-    }
-    return await _execute_task_manager({}, config)
+# _execute_task_manager + handle_task_manager: Wave 11.I milestone O moved
+# the operation matrix to nodes/tool/task_manager.py. The plugin reads
+# through to the delegation registry (``_delegated_tasks`` /
+# ``_delegation_results`` / ``get_delegated_task_status``) which still
+# lives in this module -- delegation lifecycle is genuine cross-cutting
+# framework state. ``handle_task_manager`` had no callers and was deleted.
 
 
 # =============================================================================