machinaos 0.0.76 → 0.0.78

package/server/services/ws_handler_registry.py

@@ -1,34 +1,53 @@
-"""WebSocket handler registry for plugin-owned messages.
-
-Mirrors the pattern used by :data:`services.node_registry._HANDLER_REGISTRY`
-(plugin nodes self-register via ``BaseNode.__init_subclass__``) but for
-side-channel WebSocket commands like ``telegram_connect``,
-``whatsapp_status``, etc.
-
-Each ``nodes/<group>/__init__.py`` calls :func:`register_ws_handlers`
-with a dict of ``message_type -> async handler``; the central WebSocket
-router reads :func:`get_ws_handlers` at dispatch time and merges the
-result into its own legacy ``MESSAGE_HANDLERS`` table.
-
-No hardcoded plugin names anywhere in the router.  Adding a new
-plugin's WS surface is a one-line registration call inside that
-plugin's package.
+"""Plugin self-registration registries.
+
+Three sibling concerns share this file because they're the same pattern
+(idempotent dict + collision check) for the same audience (plugin
+``__init__.py`` modules wiring themselves into the framework):
+
+1. **WebSocket handlers** — ``register_ws_handlers({type: handler})``
+   for side-channel commands like ``telegram_connect``,
+   ``whatsapp_status``. Read by ``routers/websocket.py`` at dispatch
+   time and merged into ``MESSAGE_HANDLERS``.
+
+2. **HTTP routers** — ``register_router(APIRouter, name="<plugin>")``
+   for plugin-owned routes (OAuth callbacks, webhook receivers,
+   direct-API endpoints). Read by ``server.main`` after plugin discovery
+   and ``app.include_router(...)``'d.
+
+3. **Option loaders** — ``register_option_loader(method_name, fn)`` for
+   dynamic-options dropdowns wired through the
+   ``loadOptionsMethod`` Pydantic field metadata. Read by
+   :func:`dispatch_load_options` (here in this module) and the matching
+   WS handler in ``routers/websocket.py``.
+
+No hardcoded plugin names anywhere in the central router or main.py.
+Adding a new plugin's WS / HTTP / option-loader surface is one
+registration call inside that plugin's package.
 """
 
 from __future__ import annotations
 
 import logging
-from typing import Any, Awaitable, Callable, Dict
+from typing import Any, Awaitable, Callable, Dict, List
+
+from fastapi import APIRouter, WebSocket
 
-from fastapi import WebSocket
+from services.plugin.registry import IdempotentRegistry
 
 logger = logging.getLogger(__name__)
 
 WSHandler = Callable[[Dict[str, Any], WebSocket], Awaitable[Dict[str, Any]]]
+LoadOptionsFn = Callable[[Dict[str, Any]], Awaitable[List[Dict[str, Any]]]]
 
-_REGISTRY: Dict[str, WSHandler] = {}
+_WS_REGISTRY: IdempotentRegistry[str, WSHandler] = IdempotentRegistry("ws_handler")
+_ROUTER_REGISTRY: IdempotentRegistry[str, APIRouter] = IdempotentRegistry("router")
+_OPTION_LOADER_REGISTRY: IdempotentRegistry[str, LoadOptionsFn] = IdempotentRegistry(
+    "option_loader"
+)
 
 
+# ---- WebSocket handlers --------------------------------------------------
+
 def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:
     """Publish a batch of ``message_type -> handler`` mappings.
 
@@ -37,14 +56,7 @@ def register_ws_handlers(handlers: Dict[str, WSHandler]) -> None:
     ``ValueError`` to surface plugin namespace collisions early.
     """
     for msg_type, handler in handlers.items():
-        existing = _REGISTRY.get(msg_type)
-        if existing is not None and existing is not handler:
-            raise ValueError(
-                f"WS handler for message_type '{msg_type}' is already registered "
-                f"by {existing.__module__}.{existing.__qualname__}; refusing to "
-                f"overwrite with {handler.__module__}.{handler.__qualname__}"
-            )
-        _REGISTRY[msg_type] = handler
+        _WS_REGISTRY.register(msg_type, handler)
 
 
 def get_ws_handlers() -> Dict[str, WSHandler]:
@@ -53,9 +65,80 @@ def get_ws_handlers() -> Dict[str, WSHandler]:
     Returns a fresh dict so callers can mutate without affecting the
     registry (e.g. ``MESSAGE_HANDLERS = {**core, **get_ws_handlers()}``).
     """
-    return dict(_REGISTRY)
+    return dict(_WS_REGISTRY.items())
 
 
 def list_registered_types() -> list[str]:
     """For diagnostics / startup logging."""
-    return sorted(_REGISTRY.keys())
+    return sorted(_WS_REGISTRY.keys())
+
+
+# ---- HTTP routers --------------------------------------------------------
+
+def register_router(router: APIRouter, *, name: str) -> None:
+    """Publish a plugin-owned ``APIRouter`` for inclusion at app startup.
+
+    ``name`` is the plugin folder name — used for diagnostics and
+    collision detection. Same idempotency contract as the WS side: the
+    same router for the same name is a no-op; a different router for an
+    existing name raises ``ValueError`` so plugin-name collisions fail
+    at import time, not request time.
+    """
+    _ROUTER_REGISTRY.register(name, router)
+
+
+def get_routers() -> List[APIRouter]:
+    """Snapshot of registered routers in registration order."""
+    return _ROUTER_REGISTRY.values()
+
+
+def list_registered_routers() -> List[str]:
+    """For diagnostics / startup logging."""
+    return sorted(_ROUTER_REGISTRY.keys())
+
+
+# ---- Option loaders ------------------------------------------------------
+
+def register_option_loader(method_name: str, fn: LoadOptionsFn) -> None:
+    """Publish a ``loadOptionsMethod`` async loader.
+
+    ``method_name`` is the string declared on Pydantic ``Field`` metadata
+    via ``json_schema_extra={"loadOptionsMethod": "..."}`` (e.g.
+    ``gmailLabels``, ``whatsappGroups``). Same idempotency contract as
+    the WS / router registries: the same callable for the same method
+    is a no-op; a different callable raises ``ValueError`` so plugin
+    namespace clashes fail at import time.
+    """
+    _OPTION_LOADER_REGISTRY.register(method_name, fn)
+
+
+def get_option_loader(method_name: str) -> LoadOptionsFn | None:
+    """Look up a registered loader. ``None`` when the method is unknown."""
+    return _OPTION_LOADER_REGISTRY.get(method_name)
+
+
+def list_registered_option_methods() -> List[str]:
+    """For diagnostics / startup logging."""
+    return sorted(_OPTION_LOADER_REGISTRY.keys())
+
+
+async def dispatch_load_options(
+    method: str, params: Dict[str, Any] | None = None
+) -> List[Dict[str, Any]]:
+    """Look up and invoke a registered loader.
+
+    Returns an empty list when the method isn't registered (matches
+    n8n's tolerant fallback -- the dropdown stays empty rather than
+    erroring out).
+    """
+    loader = _OPTION_LOADER_REGISTRY.get(method)
+    if loader is None:
+        return []
+    return await loader(params or {})
+
+
+def list_load_options_methods() -> List[str]:
+    """Stable alphabetised list of registered method names. The editor
+    prefetches this once on boot so it knows which ``loadOptionsMethod``
+    values are wired."""
+    return list_registered_option_methods()

package/server/skills/GUIDE.md

@@ -110,7 +110,7 @@ Provide usage guidelines, examples, and constraints.
 |-------|----------|-------------|
 | `name` | Yes | Lowercase, hyphens only. Must match pattern `^[a-z0-9]+(-[a-z0-9]+)*$` |
 | `description` | Yes | One-line summary shown in skill lists and to the LLM |
-| `allowed-tools` | No | Space-delimited list of tool names. The first that resolves to a known node is the skill's visual source — its icon/color come from `server/nodes/visuals.json` via the `_visuals` handler. |
+| `allowed-tools` | No | Space-delimited list of LLM-facing tool names (snake_case, e.g. `stripe_action`, `apify_actor`, `whatsapp_send`). The first token whose snake→camel conversion (`stripe_action` → `stripeAction`) matches a node `type` in `server/nodes/visuals.json` becomes the skill's visual source — its icon/color come from that entry via the `_visuals` handler. **Convention:** the LLM tool name MUST be the snake_case form of the node type (e.g. `stripeAction` → `stripe_action`). The same string goes into `services/ai.py` `DEFAULT_TOOL_NAMES` so the LLM and the skill agree on the name. Mismatching the snake_case (e.g. `stripe_cli` for a `stripeAction` node) silently breaks icon resolution. |
 | `metadata` | No | Arbitrary key-value pairs (author, version, category). **Don't set `icon`/`color` for skills that target a node** — those are resolved from the target node's `visuals.json` entry so the skill always mirrors the canvas. Skills with no node target (personality skills, memory operators, autonomous patterns) **may** set inline `icon` and `color` — they're the only visual source for those. |
 
 ### Name Format Rules
@@ -121,6 +121,21 @@ Provide usage guidelines, examples, and constraints.
 - Examples: `my-skill`, `web-search-skill`, `code-skill`
 - Invalid: `My_Skill`, `my--skill`, `MySkill`
 
+### Tool naming — snake_case ↔ camelCase contract
+
+Three places have to agree for a skill's icon to render correctly:
+
+| Place | Form | Example |
+|---|---|---|
+| Plugin node `type` (in `<plugin>.py`) | camelCase | `stripeAction` |
+| `server/nodes/visuals.json` key | camelCase (= node type) | `"stripeAction": { "icon": "asset:stripe", ... }` |
+| `server/services/ai.py` `DEFAULT_TOOL_NAMES` value | snake_case (LLM tool name) | `"stripeAction": "stripe_action"` |
+| Skill `allowed-tools` | snake_case (matches the LLM tool name) | `allowed-tools: "stripe_action"` |
+
+The skill resolver (`SkillLoader._parse_skill_metadata`) takes each `allowed-tools` token, runs snake→camel (`stripe_action` → `stripeAction`), and looks it up in `visuals.json`. If the conversion doesn't equal the node type, no icon resolves and the skill renders without one.
+
+**Common pitfall:** picking a "creative" LLM tool name that doesn't snake-back to the node type. For example, calling a `stripeAction` node's tool `stripe_cli` (because it wraps a CLI) breaks the convention — `stripe_cli` snakes to `stripeCli`, not `stripeAction`, so `visuals.json` lookup fails. Stick to `<node_type_in_snake_case>` unless you're prepared to also add an alias entry to `visuals.json`.
+
 ## Optional Supporting Files
 
 Skills can include additional files that are loaded alongside the main instructions:

package/server/skills/assistant/agent-builder-skill/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: agent-builder-skill
+description: How to use the Agent Builder tool's five canvas-mutation operations to inspect and grow your own toolset / skills / teammates / workflows mid-execution
+allowed-tools: "agentBuilder"
+metadata:
+  author: machina
+  version: "2.0"
+  category: autonomous
+---
+
+# Agent Builder
+
+You are connected to an **Agent Builder** node. It exposes ONE
+LLM-callable tool, `agentBuilder`, which dispatches to FIVE
+canvas-mutation operations via the `operation` field:
+
+| `operation` value | Purpose |
+|---|---|
+| `inspect_canvas` | Read-only view of nodes, edges, and what's already wired to you. ALWAYS call this first. |
+| `add_tool` | Spawn a tool node + wire it to your `input-tools` handle. |
+| `add_skill` | Toggle a skill on your Master Skill (auto-creates one if missing). |
+| `add_subagent` | Team-leads only -- spawn a delegate agent + wire to your `input-teammates`. |
+| `create_workflow` | Persist a fresh empty workflow + return its id. Doesn't switch the user's view. |
+
+Every call is `agentBuilder({operation: "<one-of-above>", ...op-specific-fields})`. There are no separate tools.
+
+## The cardinal rule
+
+**Call `agentBuilder({operation: "inspect_canvas"})` BEFORE any
+mutation operation.** Without it you cannot tell whether a tool /
+skill / subagent is already wired and will create duplicates.
+Workflow becomes cluttered and your tool list confused.
+
+The `inspect_canvas` summary tells you:
+- which tools are already connected to your `input-tools`
+- whether a Master Skill is wired to your `input-skill` (and what
+  skills it has enabled)
+- whether you have any teammate delegates (`input-teammates`)
+
+Pick the smallest action that solves the problem. If the tool you
+need is already on your canvas, USE IT -- don't add a duplicate.
+
+## Soft-reload semantics (important)
+
+LangGraph binds your tool list at the start of each invocation.
+Tools / skills / teammates added mid-run **do NOT become callable
+in the current run**. They become available on your **next
+invocation** (next chat message, next workflow trigger, next call).
+
+Each mutation returns a summary ending in "available on your next
+turn". Take this literally. Do NOT loop trying to call something
+you just added -- it isn't there yet. Tell the user what you added
+and that they can use it on the next message.
+
+## Operation reference
+
+### `operation: "inspect_canvas"`
+
+No additional fields. Returns:
+```json
+{
+  "operation": "inspect_canvas",
+  "nodes": [{ "id", "type", "label", "key_params" }, ...],
+  "edges": [{ "source", "target", "source_handle", "target_handle" }, ...],
+  "you": {
+    "node_id": "agent-1",
+    "incoming": [...], "outgoing": [...]
+  },
+  "summary": "5 nodes, 1 tool(s) wired to you (httpRequest), no skills."
+}
+```
+
+API keys, prompts, and other secrets are **stripped** from
+`key_params`. Only safe planner-relevant fields surface
+(`provider`, `model`, `operation`, `url`, `query`).
+
+### `operation: "add_tool"`
+
+Required field: `node_type` (string).
+
+Spawns a tool node and wires it to your `input-tools`. Allowed
+types are anything registered with `component_kind="tool"` --
+typically things like `httpRequest`, `braveSearch`,
+`pythonExecutor`, etc. (NOT `agentBuilder` itself; NOT
+`masterSkill`, which is managed via `add_skill` instead.)
+
+If the tool has a paired teaching skill, the auto-add-skill
+handler enables it too -- no separate `add_skill` call needed.
+
+### `operation: "add_skill"`
+
+Required field: `skill_folder` (string).
+
+Enables a skill on your Master Skill. If you don't have a Master
+Skill connected to `input-skill` yet, one is created and wired for
+you. The skill folder must exist under `server/skills/**`
+(e.g. `http-request-skill`, `memory-skill`, `python-skill`).
+
+The skill's `SKILL.md` instructions become part of your system
+message on your next turn.
+
+### `operation: "add_subagent"`
+
+Required field: `agent_type` (string).
+
+**Team-leads only** (`orchestrator_agent`, `ai_employee`,
+`deep_agent`). Spawns a specialized agent (`coding_agent`,
+`web_agent`, `task_agent`, etc.) and wires it to your
+`input-teammates` handle. The new agent appears as a
+`delegate_to_<name>` tool on your next turn.
+
+The new agent starts with empty configuration -- the user will
+need to set its provider/model after the run. Mention this in your
+response.
+
+### `operation: "create_workflow"`
+
+Required field: `workflow_name` (string).
+Optional field: `workflow_description` (string).
+
+Persists a fresh empty workflow with a single Start node and
+returns its `workflow_id`. The user's current view does NOT
+change; the frontend toasts a "Switch" link.
+
+Use sparingly. Prefer mutating the current workflow over creating
+new ones. Good cases for `create_workflow`:
+- Templating / saving a solved pattern as a starting point.
+- Splitting work into a separate workflow when the current one
+  is getting too large.
+
+## Worked example
+
+User: "Search the web for current weather in Tokyo and tell me."
+
+```
+1. agentBuilder({operation: "inspect_canvas"})
+   -> "1 nodes, no tool(s) wired to you, no skills."
+   You see no web-search tool exists. Plan: add one.
+
+2. agentBuilder({operation: "add_tool", node_type: "braveSearch"})
+   -> "Added 'braveSearch' as a tool. Available on your next turn."
+
+3. Reply to the user:
+   "I've added a Brave Search tool to my toolset. Send me the same
+    request on your next message and I'll search for the Tokyo
+    weather."
+```
+
+DO NOT try to call `brave_search` in the same turn -- it's not in
+your tool list yet. Just tell the user it's ready for next turn.
+
+## What NOT to do
+
+- **Don't skip `inspect_canvas`**. Always run it first; it's
+  read-only and cheap.
+- **Don't add a tool you already have**. The inspect summary tells
+  you what's wired.
+- **Don't loop on freshly-added tools**. They're not callable until
+  next invocation.
+- **Don't add `agentBuilder` to yourself via `add_tool`** (rejected
+  -- avoids recursion; `agentBuilder` is excluded from the allowed
+  tool types).
+- **Don't spawn another team-lead** as a subagent (rejected --
+  team-leads delegate to specialists, not to other team-leads).
+- **Don't call `create_workflow`** unless the user explicitly asks
+  to start a fresh workflow.

package/server/skills/payments_agent/stripe-skill/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: stripe-skill
+description: Process payments, manage customers, issue refunds, and handle subscriptions via the Stripe CLI. Pass any Stripe command (customers, charges, payment_intents, refunds, invoices, products, prices, subscriptions) and the tool runs it for you and returns parsed JSON.
+allowed-tools: "stripe_action"
+metadata:
+  author: machina
+  version: "1.0"
+  category: payments
+
+---
+
+# Stripe Skill
+
+Pass-through over the official [Stripe CLI](https://stripe.com/docs/cli).
+The tool runs `stripe <command> --api-key <stored-key>` for you and
+returns parsed JSON. Every Stripe resource the CLI supports works
+without code changes — products and prices created tomorrow work the
+same way.
+
+## Tool: stripe_action
+
+Single field: `command` — a string identical to what you would type
+after `stripe ` on the terminal.
+
+### Schema
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| command | string | Yes | Stripe CLI command (e.g. `"customers create --email a@b.com"`). Quote arguments that contain spaces. |
+
+### Response
+
+```json
+{
+  "command": "customers create --email a@b.com",
+  "success": true,
+  "result": {
+    "id": "cus_NkXz123",
+    "email": "a@b.com",
+    "object": "customer",
+    "created": 1730000000,
+    ...
+  },
+  "stdout": "<raw CLI stdout>"
+}
+```
+
+On CLI failure the tool raises an error with Stripe's own message
+(e.g. `"No such customer: cus_invalid"`).
+
+## Common commands
+
+### Customers
+
+| Command | Purpose |
+|---|---|
+| `customers create --email <addr>` | Create a customer. Optional: `--name`, `--description`, `--phone`, `--metadata key=val`. |
+| `customers retrieve <cus_id>` | Fetch a customer by id. |
+| `customers list --limit 10` | List recent customers. Optional: `--email <addr>` filter. |
+| `customers update <cus_id> --email <new>` | Update fields on a customer. |
+| `customers delete <cus_id>` | Permanently delete a customer. |
+
+Search:
+
+| Command | Purpose |
+|---|---|
+| `customers search --query "email:'a@b.com'"` | Server-side search across customers. Stripe Search query syntax. |
+
+### PaymentIntents (recommended for charges)
+
+| Command | Purpose |
+|---|---|
+| `payment_intents create --amount 2000 --currency usd` | Create a PaymentIntent for $20.00. Amount is in the smallest currency unit (cents for USD). |
+| `payment_intents create --amount 2000 --currency usd --customer cus_123` | Create attached to a saved customer. |
+| `payment_intents create --amount 2000 --currency usd --confirm --payment-method pm_card_visa` | Create + confirm in one shot (most common test path). |
+| `payment_intents retrieve pi_123` | Fetch by id. |
+| `payment_intents list --limit 20` | List recent intents. |
+| `payment_intents cancel pi_123` | Cancel an unconfirmed or processing intent. |
+
+### Charges (legacy direct-charge path)
+
+| Command | Purpose |
+|---|---|
+| `charges retrieve ch_123` | Fetch a charge by id. |
+| `charges list --limit 10` | List recent charges. |
+| `charges list --customer cus_123` | List charges for a specific customer. |
+
+For new integrations prefer **PaymentIntents** over direct
+`charges create` — Stripe deprecated raw card-token charge creation.
+
+### Refunds
+
+| Command | Purpose |
+|---|---|
+| `refunds create --payment-intent pi_123` | Refund a PaymentIntent in full. |
+| `refunds create --payment-intent pi_123 --amount 500` | Partial refund (in smallest currency unit). |
+| `refunds create --charge ch_123` | Refund by charge id (older flow). |
+| `refunds retrieve re_123` | Fetch a refund by id. |
+| `refunds list --limit 10` | List recent refunds. |
+
+### Invoices & Subscriptions
+
+| Command | Purpose |
+|---|---|
+| `invoices create --customer cus_123` | Draft an invoice. |
+| `invoices finalize_invoice in_123` | Finalize a draft (locks for sending/charging). |
+| `invoices pay in_123` | Charge the customer for a finalized invoice. |
+| `invoices list --customer cus_123` | List invoices for a customer. |
+| `subscriptions create --customer cus_123 --items='[{"price":"price_xxx"}]'` | Create a subscription. |
+| `subscriptions retrieve sub_123` | Fetch a subscription. |
+| `subscriptions cancel sub_123` | Cancel immediately. |
+| `subscriptions update sub_123 --cancel-at-period-end true` | Cancel at end of current billing period. |
+
+### Products & Prices
+
+| Command | Purpose |
+|---|---|
+| `products create --name "Pro Plan"` | Create a product. |
+| `prices create --product prod_123 --unit-amount 2000 --currency usd --recurring='{"interval":"month"}'` | Create a recurring price tied to a product. |
+| `prices list --product prod_123` | List prices for a product. |
+
+### Trigger (synthetic test events)
+
+| Command | Purpose |
+|---|---|
+| `trigger payment_intent.succeeded` | Fire a synthetic PaymentIntent succeeded event. |
+| `trigger charge.refunded` | Fire a synthetic refund event. |
+| `trigger customer.subscription.created` | Fire a synthetic subscription event. |
+
+`stripe trigger` is invaluable for testing webhook flows — it sends
+the event to Stripe, which sends it back through the same `stripe
+listen` daemon and into your `stripeReceive` trigger node.
+
+## Common workflows
+
+### Create a customer and charge them
+
+```json
+{ "command": "customers create --email rosy@sparrow.com --name 'Rosy Sparrow'" }
+```
+returns `cus_…`. Then:
+```json
+{ "command": "payment_intents create --amount 2000 --currency usd --customer cus_xxx --payment-method pm_card_visa --confirm" }
+```
+
+### Refund the most recent payment for a customer
+
+```json
+{ "command": "payment_intents list --customer cus_123 --limit 1" }
+```
+read `data[0].id`, then:
+```json
+{ "command": "refunds create --payment-intent pi_xxx" }
+```
+
+### Set up a recurring subscription
+
+```json
+{ "command": "products create --name 'Pro Plan'" }     -> prod_xxx
+{ "command": "prices create --product prod_xxx --unit-amount 2000 --currency usd --recurring='{\"interval\":\"month\"}'" }   -> price_xxx
+{ "command": "subscriptions create --customer cus_xxx --items='[{\"price\":\"price_xxx\"}]'" }
+```
+
+## Quoting and escaping
+
+The `command` string is parsed with `shlex.split` before being handed
+to `stripe`. Use single quotes for arguments that contain spaces:
+
+| You want to send | Type this in `command` |
+|---|---|
+| `--name=Acme Inc` | `customers create --name 'Acme Inc'` |
+| metadata with spaces | `customers update cus_x --metadata 'plan=Acme Pro'` |
+| a JSON array as a flag value | `subscriptions create --items='[{"price":"price_xxx"}]'` |
+
+JSON inside `--items` / `--recurring` etc. should be a single quoted
+JSON string with no internal spaces — the CLI parses it on the
+server side.
+
+## Idempotency
+
+For any create/charge that you don't want to duplicate on retry, add
+an idempotency key:
+
+```
+customers create --email a@b.com -H "Idempotency-Key: order_42_user_7"
+```
+
+The CLI accepts custom headers via `-H`. Stripe deduplicates by the
+key for 24 hours.
+
+## Test mode vs live mode
+
+The stored API key (set in the Credentials Modal) determines mode:
+
+| Key prefix | Mode | Effect |
+|---|---|---|
+| `sk_test_…` | Test | Fake money, fake events, no real charges. Always use this for development. |
+| `sk_live_…` | Live | Real money. Real customers. Use only after thorough testing. |
+| `rk_test_…` / `rk_live_…` | Restricted | Scoped permissions; recommended for production agents that don't need full account access. |
+
+The CLI reports `livemode: true/false` on every response object so
+you can verify which environment a result is from.
+
+## Errors
+
+Stripe returns structured errors that surface in the tool's error
+field. Common ones:
+
+| Error code | Meaning | Recovery |
+|---|---|---|
+| `resource_missing` | The id you passed doesn't exist | Verify the id; list to find the right one |
+| `card_declined` | Card payment failed | Use a different `--payment-method`; in test mode try `pm_card_visa` |
+| `invalid_request_error` | Wrong / missing argument | Check `stripe <resource> create --help` |
+| `authentication_required` | 3DS challenge needed | Use a setup_intent or off-session payment_method |
+| `rate_limit_error` | Too many requests | Pause and retry; Stripe rate limit is 100/sec in live, 25/sec in test |
+
+The CLI's stderr always contains the Stripe request id (`req_…`) —
+include it when reporting issues.
+
+## Webhooks (`stripeReceive` trigger)
+
+When the Stripe daemon is connected (Credentials Modal → Stripe →
+Connect), every event Stripe sends is forwarded to MachinaOs and
+delivered to any active `stripeReceive` trigger nodes after
+HMAC-SHA256 signature verification (`Stripe-Signature` header).
+
+To test event delivery without making real payments, use the
+`trigger` command above. Events fire through the same path as real
+ones.
+
+Filters on the trigger node (`event_type_filter`):
+
+| Filter | Matches |
+|---|---|
+| `all` | every event |
+| `charge.succeeded` | exact match |
+| `charge.*` | every charge.* event (succeeded, refunded, failed, …) |
+| `payment_intent.*` | every PaymentIntent event |
+
+The trigger output mirrors Stripe's event shape: `event_id`,
+`event_type`, `created`, `livemode`, `api_version`, `request_id`,
+`account`, `data`.
+
+## Authentication — `stripe login` (browser OAuth)
+
+Authentication is delegated entirely to the Stripe CLI. There is no
+API key to paste into MachinaOs. The Credentials Modal's **Login
+with Stripe** button drives the CLI's two-step machine-friendly
+login:
+
+1. **Browser-side**: the modal opens
+   `https://dashboard.stripe.com/stripecli/auth/...` in a new tab and
+   shows a verification code. The user signs in to Stripe and
+   confirms the code.
+2. **CLI-side**: the CLI polls Stripe until the user authorises,
+   then writes credentials (one restricted key per mode, valid for
+   90 days) to `~/.config/stripe/config.toml` (or
+   `$XDG_CONFIG_HOME/stripe/config.toml`).
+3. **MachinaOs-side**: when login completes, the listen daemon
+   starts automatically and captures the webhook signing secret.
+
+After login, every `stripe …` command run via this tool reads its
+credentials from the CLI's config file — no `--api-key` flag in any
+command you'd type.
+
+**Logout** (Credentials Modal → Disconnect) stops the listen daemon
+and runs `stripe logout --all` to clear the config file.
+
+## Best practices
+
+1. **Restricted keys are auto-issued.** When you `stripe login`, the
+   CLI generates restricted keys with CLI-appropriate scopes (one
+   per test/live mode) — you don't pick scopes manually.
+2. **Default to test mode** for development. The CLI distinguishes
+   modes; `livemode: true/false` is on every response.
+3. **Add idempotency keys to all create operations.** Especially for
+   charges and refunds — accidental retry without a key duplicates
+   the charge.
+4. **Quote string arguments with spaces** (`--name 'Acme Inc'`).
+5. **Use PaymentIntents, not raw charges** for new integrations.
+6. **Surface Stripe error messages verbatim to the user.** They are
+   precise and actionable; don't paraphrase them.
+7. **Don't include `--api-key` in your `command` string.** The CLI
+   already has stored credentials; an inline `--api-key` overrides
+   them and risks key leakage in process listings and logs.
+
+## Setup checklist
+
+1. **Stripe CLI binary** — auto-downloaded on first **Login with
+   Stripe** click if not already on PATH. Resolution order:
+   - System install (`brew install stripe/stripe-cli/stripe`,
+     `scoop install stripe`, `apt install stripe`, or a direct
+     binary from <https://stripe.com/docs/stripe-cli#install>).
+   - MachinaOs workspace cache at
+     `{workspace_base}/_stripe/bin/stripe[.exe]` (populated
+     automatically from GitHub releases — pinned to a known-good
+     CLI version).
+2. Credentials Modal → Stripe → **Login with Stripe** → a browser
+   tab opens to the Stripe Dashboard with a pairing code. Authorise.
+   The modal flips to "Connected" when the CLI's `login --complete`
+   subprocess returns and the listen daemon spins up
+   (`webhook_secret_captured: true`).
+3. The `Stripe` action node is connected to your agent's
+   `input-tools` handle.
+4. (For webhook flows) A `stripeReceive` trigger node is wired into
+   your workflow with the event-type filter you care about.