caddie-mcp 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# B3OS MCP Server
+
+MCP server that connects Claude to [B3OS](https://b3os.org), a workflow automation platform for blockchain operations. Build, run, and debug automated workflows through natural conversation.
+
+**37 tools** | **562+ actions** | Works with Claude Code, Claude Desktop, and co-work sessions
+
+## Quick Start
+
+### 1. Get an API key
+
+Create one at [b3os.org/organizations/settings?tab=api-keys](https://b3os.org/organizations/settings?tab=api-keys) (starts with `b3sk_`).
+
+### 2. Install
+
+```bash
+npm install -g caddie-mcp
+```
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+cd packages/b3os-mcp
+pnpm install && pnpm run build
+```
+</details>
+
+### 3. Connect to Claude
+
+**Interactive setup (recommended):**
+
+```bash
+b3os-mcp-setup
+```
+
+This validates your API key and configures Claude Code (`~/.claude/mcp.json`), project-level `.mcp.json` (if gitignored), and Claude Desktop automatically.
+
+#### Reducing permission prompts
+
+At the end of setup, you'll be asked whether to pre-approve ~26 read-only b3os-mcp tools (list/get/lookup/debug — no create/update/delete/run). This writes `mcp__b3os-mcp__*` entries to `~/.claude/settings.json` under `permissions.allow`, letting Caddie iterate without constant approval prompts.
+
+Write tools (`create_workflow`, `run_action`, `query_database`, etc.) always require approval per call.
+
+**To revert:** delete the `mcp__b3os-mcp__*` entries from `permissions.allow` in `~/.claude/settings.json`.
+
+<details>
+<summary>Manual setup</summary>
+
+**Claude Code** -- add to `.mcp.json` in your project root (or `~/.claude/mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "b3os": {
+      "type": "stdio",
+      "command": "b3os-mcp",
+      "args": [],
+      "env": {
+        "B3OS_API_KEY": "b3sk_your_key_here",
+        "B3OS_SERVER_URL": "https://api.b3os.org"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** -- edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "b3os": {
+      "command": "b3os-mcp",
+      "env": { "B3OS_API_KEY": "b3sk_your_key_here" }
+    }
+  }
+}
+```
+
+> **nvm/fnm users:** If `b3os-mcp` isn't resolved, replace `"command": "b3os-mcp"` with the absolute node path. Run `which node` to find it. The interactive setup handles this automatically.
+
+</details>
+
+### 4. Restart Claude
+
+Restart your Claude Code session or Claude Desktop app.
+
+## What You Can Do
+
+**Build workflows** -- Claude delegates to Caddie, the B3OS AI agent with deep domain knowledge:
+```
+"Build a workflow that monitors ETH price every 5 min and alerts on Slack if it drops below $2000"
+```
+
+**Debug failed runs** -- Caddie analyzes execution state and suggests fixes:
+```
+"Why did my last workflow run fail?"
+```
+
+**Query on-chain data** -- named lookup tools, no workflow needed:
+```
+"What's the current price of ETH and BTC?"
+"What tokens does 0xd8dA...6045 hold on Base?"
+"Show me prediction markets about Bitcoin on Polymarket"
+```
+
+**Execute actions** -- run any of the 562+ actions directly:
+```
+"Debug tx 0xabc... on Base"
+"Get DeFi positions for vitalik.eth"
+```
+
+## Tools
+
+| Group | Tools | Description |
+|-------|-------|-------------|
+| **Caddie** | `build_workflow`, `debug_run` | AI-powered workflow building and run debugging |
+| **Lookups** | `token_lookup`, `price_lookup`, `balance_lookup`, `defi_lookup`, `debug_transaction`, `polymarket_lookup` | Named tools for common data queries |
+| **Catalog** | `search_actions`, `list_actions`, `get_action`, `list_triggers`, `get_trigger` | Browse 562+ actions and triggers |
+| **Execution** | `query_action`, `run_action`, `run_workflow`, `run_ephemeral` | Execute actions and workflows |
+| **Workflows** | `create_workflow`, `get_workflow`, `list_workflows`, `update_workflow`, `delete_workflow`, `publish_workflow`, `pause_workflow`, `resume_workflow`, `validate_workflow` | Full workflow lifecycle |
+| **Runs** | `list_runs`, `get_run`, `cancel_run` | Inspect and manage workflow runs |
+| **Org** | `whoami`, `list_wallets`, `list_connectors`, `list_slack_channels`, `list_telegram_chats` | Organization context and connected services |
+| **Database** | `query_database`, `list_tables`, `get_table_schema` | Query org's Cloudflare D1 database |
+
+All tools are prefixed with `b3os_` (e.g. `b3os_build_workflow`).
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `B3OS_API_KEY` | Yes | -- | API key from B3OS dashboard |
+| `B3OS_SERVER_URL` | No | `https://api.b3os.org` | Override for local dev (`http://localhost:8080`) |
+
+## Development
+
+```bash
+pnpm run build     # compile TypeScript
+pnpm test          # run tests
+
+# Dev mode (no build step) -- in .mcp.json use:
+#   "command": "pnpm", "args": ["exec", "tsx", "src/index.ts"]
+```
+
+## Architecture
+
+```
+Claude (Code / Desktop / co-work)
+  |-- REST tools ----> B3OS API (workflows, runs, catalog, lookups, database)
+  |-- SSE stream ----> Caddie AI agent (build_workflow, debug_run)
+  +-- Resources -----> Embedded guide (no API call)
+```

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+export declare function getApiKey(): string;
+export declare function getServerUrl(): string;
+export declare class ApiError extends Error {
+    status: number;
+    statusText: string;
+    body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+interface RequestOptions {
+    method?: string;
+    body?: unknown;
+    params?: Record<string, string>;
+    noAuth?: boolean;
+    timeout?: number;
+}
+export declare function request<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+/** Max bytes for a tool response text before truncation. */
+export declare const MAX_RESPONSE_BYTES = 50000;
+/** Truncate a tool response string if it exceeds the byte limit. */
+export declare function truncateResponse(text: string, maxBytes?: number): string;
+/**
+ * Parse a JSON string parameter from MCP clients that serialize objects as strings.
+ * Returns the value as-is if it's not a string. Throws a descriptive error on invalid JSON.
+ */
+export declare function parseJsonParam(value: unknown, paramName: string): unknown;
+export {};

package/dist/client.js

@@ -0,0 +1,134 @@
+export function getApiKey() {
+    const key = process.env.B3OS_API_KEY;
+    if (!key) {
+        throw new Error("B3OS_API_KEY is required. Set it in your MCP server config or run: pnpm setup");
+    }
+    return key;
+}
+export function getServerUrl() {
+    const url = (process.env.B3OS_SERVER_URL || "https://api.b3os.org").replace(/\/+$/, "");
+    if (!/^https:\/\//i.test(url) && process.env.NODE_ENV !== "development") {
+        throw new Error("B3OS_SERVER_URL must use HTTPS");
+    }
+    return url;
+}
+function friendlyHint(status) {
+    switch (status) {
+        case 401:
+            return "Your API key may be invalid or expired. Regenerate it at https://b3os.org/organizations/settings?tab=api-keys";
+        case 403:
+            return "Insufficient permissions. Check that your API key has read-write scope.";
+        case 404:
+            return "Resource not found. Verify the ID is correct.";
+        case 409:
+            return "Conflict — another update may have occurred. Retry with the latest version.";
+        case 429:
+            return "Rate limited. Wait a moment and try again.";
+        default:
+            return "";
+    }
+}
+const MAX_ERROR_BODY_LENGTH = 500;
+function sanitizeBody(body) {
+    if (!body)
+        return "";
+    // Detect HTML error pages (502/503 Cloudflare, nginx) and replace with
+    // a clean message. Uses a single regex to match <!DOCTYPE or <html at
+    // the start, avoiding false-positives on XML/SOAP responses.
+    if (/^\s*<(!DOCTYPE|html)/i.test(body)) {
+        return "(HTML error page — server may be temporarily unavailable)";
+    }
+    // Truncate long error bodies to avoid leaking internal details
+    if (body.length > MAX_ERROR_BODY_LENGTH) {
+        return body.slice(0, MAX_ERROR_BODY_LENGTH) + "…(truncated)";
+    }
+    return body;
+}
+export class ApiError extends Error {
+    status;
+    statusText;
+    body;
+    constructor(status, statusText, body) {
+        const hint = friendlyHint(status);
+        const cleanBody = sanitizeBody(body);
+        super(`API error ${status}: ${statusText}${hint ? `\nHint: ${hint}` : ""}${cleanBody ? `\n${cleanBody}` : ""}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+function buildUrl(path, params) {
+    const url = new URL(`${getServerUrl()}${path}`);
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            if (value)
+                url.searchParams.set(key, value);
+        }
+    }
+    return url.toString();
+}
+function buildHeaders(noAuth) {
+    const headers = { "Content-Type": "application/json" };
+    if (!noAuth) {
+        headers["Authorization"] = `Bearer ${getApiKey()}`;
+    }
+    return headers;
+}
+export async function request(path, options = {}) {
+    const url = buildUrl(path, options.params);
+    const controller = new AbortController();
+    const timeoutMs = options.timeout ?? 30_000;
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: options.method || "GET",
+            headers: buildHeaders(options.noAuth),
+            body: options.body ? JSON.stringify(options.body) : undefined,
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new ApiError(response.status, response.statusText, body);
+        }
+        const text = await response.text();
+        if (!text)
+            return undefined;
+        const parsed = JSON.parse(text);
+        return parsed.data;
+    }
+    catch (err) {
+        if (err instanceof ApiError)
+            throw err;
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error(`Request timed out after ${timeoutMs / 1000} seconds`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Max bytes for a tool response text before truncation. */
+export const MAX_RESPONSE_BYTES = 50_000;
+/** Truncate a tool response string if it exceeds the byte limit. */
+export function truncateResponse(text, maxBytes = MAX_RESPONSE_BYTES) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= maxBytes)
+        return text;
+    return buf.subarray(0, maxBytes).toString("utf8") + `\n…(truncated, ${buf.length} bytes total)`;
+}
+/**
+ * Parse a JSON string parameter from MCP clients that serialize objects as strings.
+ * Returns the value as-is if it's not a string. Throws a descriptive error on invalid JSON.
+ */
+export function parseJsonParam(value, paramName) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch (e) {
+        throw new Error(`Invalid JSON string for parameter '${paramName}': ${e.message}`);
+    }
+}

package/dist/guide.d.ts

@@ -0,0 +1,2 @@
+export declare const GUIDE_URI = "b3os://guide";
+export declare const GUIDE_CONTENT = "# B3OS Platform Guide\n\nB3OS is a workflow automation platform for blockchain operations. Users create\nautomated workflows triggered by blockchain events, schedules, webhooks, or\nmanual execution. Workflows combine 560+ actions across DeFi, social, data,\nand on-chain operations.\n\n---\n\n## Workflow Definition Anatomy\n\nA workflow definition is a JSON object with a single `nodes` map. Each key is a\nnode ID, and the value describes that node's type, configuration, and connections.\n\n```json\n{\n  \"nodes\": {\n    \"root\": {\n      \"type\": \"cronjob\",\n      \"payload\": { \"rrule\": \"DTSTART:20260101T090000Z\\nRRULE:FREQ=MINUTELY;INTERVAL=5\" },\n      \"children\": [\"fetch_price\"]\n    },\n    \"fetch_price\": {\n      \"type\": \"coingecko-get-token-price\",\n      \"payload\": { \"coinId\": \"ethereum\" },\n      \"children\": [\"check_drop\"]\n    },\n    \"check_drop\": {\n      \"type\": \"if\",\n      \"payload\": {\n        \"condition\": { \"$and\": [{ \"{{fetch_price.result.price}}\": { \"$lte\": 2000 } }] }\n      },\n      \"children\": [\"send_alert\", \"do_nothing\"]\n    },\n    \"send_alert\": {\n      \"type\": \"slack-send-message\",\n      \"branch\": \"then\",\n      \"payload\": {\n        \"conversation\": \"{{ask.slack_channel}}\",\n        \"text\": \"ETH dropped to ${{fetch_price.result.price}}\"\n      },\n      \"connector\": { \"type\": \"slack\" },\n      \"children\": []\n    },\n    \"do_nothing\": {\n      \"type\": \"log\",\n      \"branch\": \"else\",\n      \"payload\": { \"message\": \"Price OK: {{fetch_price.result.price}}\" },\n      \"children\": []\n    }\n  }\n}\n```\n\n### Key Structural Rules\n\n- **`root` is always the trigger node.** The workflow engine starts execution from `root`.\n- **`children`** is an ordered array of node IDs that execute after the parent completes.\n- **`branch`** is required on children of `if` nodes (`\"then\"` or `\"else\"`) and `wait` nodes (`\"resumed\"` or `\"timed_out\"`).\n- **`payload`** contains the node's configuration. Supports `{{}}` template expressions.\n- **`connector`** references an OAuth credential: `{ \"type\": \"slack\" }` or `{ \"type\": \"slack\", \"id\": \"conn_abc\" }`. Only needed for actions that interact with external services.\n- **`loopBody`** (on `for-each` nodes) is an array of node IDs that run per iteration \u2014 these go in `loopBody`, not `children`.\n- **`description`** and **`titleOverride`** are optional display labels.\n\n---\n\n## Expression Syntax Reference\n\nTemplate expressions use `{{ }}` syntax and are resolved at runtime.\n\n| Pattern | Example | Resolves To |\n|---------|---------|-------------|\n| Node result | `{{fetch_data.result.items}}` | Output field from an upstream node |\n| Nested path | `{{fetch_data.result.data.price}}` | Nested field access |\n| Node payload | `{{root.payload.chainId}}` | Config value from another node |\n| Trigger input | `{{root.result.body.userId}}` | Webhook body data |\n| User input (ASK) | `{{ask.wallet_address}}` | Creates a UI widget for user input at setup time |\n| Props | `{{$props.chainId}}` | Workflow properties, inlined at creation time |\n| Block inputs | `{{$inputs.coinId}}` | Inputs passed into a reusable block |\n| Loop item | `{{$item.name}}` | Current for-each iteration item |\n| Loop index | `{{$index}}` | Current for-each iteration index (0-based) |\n| Parent loop | `{{$parent_item}}` | Parent for-each item (nested loops) |\n| Ancestor loop | `{{$for.outer_loop.item}}` | Named ancestor for-each (3+ nesting) |\n| Workflow ID | `{{$workflowId}}` | Current workflow's ID |\n| Fallback | `{{node.result.count \\|\\| 0}}` | Use 0 if the variable is nil |\n\n**Important:** Expressions can only reference ancestor nodes \u2014 nodes that have already\nexecuted before the current node in the DAG. You cannot reference sibling or descendant nodes.\n\n---\n\n## Node Types Quick Reference\n\n### Triggers (always the `root` node)\n\n**Core triggers:**\n\n| Type | Description | Key Payload Fields |\n|------|-------------|-------------------|\n| `cronjob` | Schedule-based | `rrule` (two-line DTSTART+RRULE string) |\n| `manual` | User clicks \"Run\" or webhook POST | (none \u2014 also serves as webhook endpoint) |\n| `erc20-receive` | ERC-20 token received | `chainId`, `tokenAddress`, `walletAddress` |\n| `erc20-send` | ERC-20 token sent | `chainId`, `tokenAddress`, `walletAddress` |\n| `eth-receive` | Native ETH received | `chainId`, `walletAddress`, `minAmount` (wei) |\n| `eth-send` | Native ETH sent | `chainId`, `walletAddress` |\n| `evm-log` | Smart contract event | `chainId`, `contractAddress`, `eventName`, `abi` |\n| `token-price-cexes` | Real-time price monitor | `asset`, `condition`, `threshold` |\n| `solana-transaction` | Solana tx event | `address`, `network` |\n\n**Polymarket triggers:**\n\n| Type | Description |\n|------|-------------|\n| `polymarket-user-bet` | A specific user places a bet |\n| `polymarket-market-trade` | Any trade on a market (CLOB WebSocket) |\n| `polymarket-new-market` | New market created |\n| `polymarket-market-close` | Market resolves |\n\n**Social/messaging triggers:**\n\n| Type | Description |\n|------|-------------|\n| `telegram-channel` | New Telegram message |\n| `slack-mentions` | Slack mention detection |\n| `slack-new-message-in-channels` | New message in Slack channel |\n| `farcaster-new-cast` | New Farcaster cast |\n| `x-new-tweet` | New tweet (requires username or keywords filter) |\n| `gmail-new-email-received` | Gmail inbox (OAuth) |\n| `email-new-email-received` | Disposable inbox |\n\n**Other triggers:**\n\n| Type | Description |\n|------|-------------|\n| `exchange-listing` | New trading pair on CEX (Binance, Coinbase, etc.) |\n| `stripe-payment-receive` | Stripe payment received |\n| `shopify-order-created` | Shopify order created |\n| `coinbase-payment-received` | Coinbase Commerce payment |\n\nUse `b3os_list_triggers` to see all available trigger types and their payload schemas.\n\n### Logic Nodes (built-in, no connector needed)\n\n| Type | Description | Key Fields |\n|------|-------------|------------|\n| `if` | Conditional branch | `payload.condition` (object with `$and`/`$or`). Children use `branch: \"then\"/\"else\"` |\n| `for-each` | Loop over array | `payload.array` (expression). Loop nodes go in `loopBody`, not `children` |\n| `filter` | Filter array | `payload.array`, `payload.condition` |\n| `pluck` | Extract fields | `payload.array`, `payload.fields` |\n| `delay` | Wait for duration | `payload.delayMs` (milliseconds) |\n| `log` | Log a message | `payload.message` (supports templates) |\n| `code-transform` | Run JavaScript | `payload.code` (must be `function transform(input) {...}`), `payload.input`, `payload.outputType` |\n| `regex` | Regex extraction | `payload.input`, `payload.pattern` |\n| `wait` | Pause until event | `payload.triggerType`, `payload.triggerConfig`, `payload.timeoutMs`. Children use `branch: \"resumed\"/\"timed_out\"` |\n| `send-webhook` | HTTP POST | `payload.url`, `payload.headers`, `payload.body` |\n\n### Dynamic Actions (560+ from catalog)\n\nUse `b3os_search_actions` to find actions by keyword, then `b3os_get_action` to get\nthe full payload and result schemas. Common examples:\n\n- **Token ops:** `send-erc20-token`, `send-native-token`, `approve-erc20`\n- **Swaps:** `0x-swap`, `cow-swap-gasless`, `relay-swap`, `swapkit-swap`\n- **DeFi:** `morpho-deposit`, `morpho-withdraw`, `v3-add-liquidity`\n- **Data:** `coingecko-get-token-price`, `coinglass-get-funding-rate`\n- **Messaging:** `slack-send-message`, `slack-send-block-kit-message`, `discord-send-message`, `telegram-send-message`\n- **Polymarket:** `polymarket-place-bet`, `polymarket-redeem`\n\n---\n\n## Connector Rules\n\nActions that interact with external services require a `connector` field:\n\n```json\n\"connector\": { \"type\": \"slack\" }\n```\n\nOr with a specific connector ID:\n\n```json\n\"connector\": { \"type\": \"slack\", \"id\": \"conn_abc123\" }\n```\n\n**Connector types:** `slack`, `discord`, `telegram`, `gmail`, `google_sheets`, `wallet` (HSM wallet), `db` (database).\n\n**Logic nodes NEVER need connectors:** `if`, `for-each`, `filter`, `pluck`, `delay`, `log`, `code-transform`, `regex`, `wait`, `send-webhook`.\n\nConnectors must be pre-configured in the B3OS UI before workflows can use them.\nIf the connector ID is unknown at build time, use `{{ask.connector_id}}` or leave\nonly the `type` field \u2014 the user will select the connector in the B3OS UI.\n\n---\n\n## If Condition Format\n\nThe `if` node uses a JSON condition object. The top-level key MUST be `$and` or `$or`:\n\n```json\n{\n  \"condition\": {\n    \"$and\": [\n      { \"{{fetch_price.result.price}}\": { \"$lte\": 2000 } },\n      { \"{{fetch_price.result.volume}}\": { \"$gte\": 1000000 } }\n    ]\n  }\n}\n```\n\n**Operators:** `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$contains`, `$notContains`,\n`$startsWith`, `$endsWith`, `$exists`, `$notExists`, `$in`, `$notIn`.\n\n---\n\n## Common Workflow Patterns\n\n**Pattern A \u2014 Monitor + Alert:** `cronjob \u2192 fetch data \u2192 if condition \u2192 send notification`\nMost common pattern. Schedule a check, fetch external data, conditionally alert.\n\n**Pattern B \u2014 Webhook + Transform:** `webhook \u2192 code-transform \u2192 send-webhook / action`\nReceive external data, transform it, take action. Used for API integrations.\n\n**Pattern C \u2014 Trigger + Loop + Action:** `trigger \u2192 fetch list \u2192 for-each \u2192 action per item`\nBatch processing. Trigger fetches a list, loops over items, processes each.\n\n**Pattern D \u2014 Approval Flow:** `trigger \u2192 slack-send-block-kit-message \u2192 wait \u2192 if approve/reject \u2192 action`\nHuman-in-the-loop. Post approval buttons, wait for click, branch on decision.\n\n---\n\n## Numeric Conventions\n\n**On-chain amounts are strings in raw units (wei/atomic):**\n- 1 ETH = `\"1000000000000000000\"` (18 decimals)\n- 1 USDC = `\"1000000\"` (6 decimals)\n- 1 WBTC = `\"100000000\"` (8 decimals)\n\nNEVER pass human-readable decimals to send/swap/approve actions. Always convert\nto the token's raw unit string. Look up token decimals \u2014 never hardcode them.\n\n**Prices and display values are numbers:** `2000.50`, `0.65`, `1500000`\nThese are used in conditions and display, not on-chain transactions.\n\n---\n\n## ASK Widget Patterns\n\n`{{ask.fieldName}}` creates a user-input widget in the B3OS UI. Use it for values\nthe user should provide at setup time:\n\n```json\n\"walletAddress\": \"{{ask.wallet_address}}\",\n\"conversation\": \"{{ask.slack_channel}}\",\n\"threshold\": \"{{ask.price_threshold}}\"\n```\n\n**Rich widget types** are available for common fields. Use the matching field name\npattern and the B3OS UI will render the appropriate widget:\n- `wallet_address` \u2192 Wallet selector\n- `token_address` / `token_addresses` \u2192 Token contract picker (with chain)\n- `chain_id` / `chain_ids` \u2192 Network selector\n- `connector_id` \u2192 Connector account picker\n- `slack_channel` \u2192 Slack channel picker\n- `telegram_chat` \u2192 Telegram chat picker\n- `token_amount` \u2192 Token amount with decimals\n- `recipient_address` \u2192 Recipient wallet address\n- `contract_address` \u2192 Smart contract address\n- `network` / `networks` \u2192 Network selector (alternative)\n- `boolean`, `number`, `select`, `multiselect`, `textarea`, `date`, `color` \u2192 Basic types\n\n---\n\n## How to Use B3OS Tools\n\n### Building a Workflow\nUse `b3os_build_workflow` to delegate to Caddie, the B3OS AI agent. Caddie has\ndeep domain knowledge, address verification, and 30+ specialized tools.\n\n1. Gather prerequisites: `b3os_list_connectors`, `b3os_list_wallets` \u2192 present options\n2. Describe the workflow in natural language to `b3os_build_workflow`\n3. Review the returned definition with the user\n4. Save: `b3os_create_workflow` (new) or `b3os_update_workflow` (existing)\n5. Confirm with user \u2192 deploy: `b3os_publish_workflow`\n\nTo modify an existing workflow, pass its `workflowId` to `b3os_build_workflow`.\n\n### Debugging a Failure\nUse `b3os_debug_run` to delegate diagnosis to Caddie:\n\n1. `b3os_list_runs` (status: \"failure\") \u2192 find failed runs\n2. `b3os_debug_run` (runId) \u2192 Caddie diagnoses + suggests fixes\n3. Apply fix: `b3os_update_workflow` \u2192 `b3os_publish_workflow`\n\nFor manual inspection: `b3os_get_run` with nodeIds to see per-node input, result, and error.\n\n### Data Queries (no workflow needed)\nUse named lookup tools for common queries:\n- Token info: `b3os_token_lookup` (network + address, or coinId)\n- Prices: `b3os_price_lookup` (coinIds)\n- Balances: `b3os_balance_lookup` (address, chainIds, limit)\n- DeFi positions: `b3os_defi_lookup` (address, chainId)\n- Tx debugging: `b3os_debug_transaction` (txHash, chainId)\n- Polymarket: `b3os_polymarket_lookup` (query, slug, or marketUrl)\n- Any other action: `b3os_query_action` (generic fallback \u2014 use `b3os_search_actions` to find action types first)\n\n### One-Shot Execution (no save)\n- `b3os_run_action` for single-action execution\n- `b3os_run_ephemeral` for multi-step definitions (max 20 nodes, 60s timeout)\n\n---\n\n## Key Gotchas\n\n**Workflow lifecycle:**\n- **Workflows start in \"draft\" status** \u2014 must call `b3os_publish_workflow` to make them live\n- **Connectors must be set up in B3OS UI first** \u2014 Slack, Discord, Google Sheets, etc.\n- **On-chain actions require a funded org wallet** with sufficient balance and gas\n\n**Scheduling:**\n- **Cronjob rrule must be two-line format:** `\"DTSTART:YYYYMMDDTHHmmSSZ\\nRRULE:FREQ=...\"`. A bare RRULE without DTSTART will break scheduling. Encode desired time in DTSTART, NOT in BYHOUR/BYMINUTE.\n- **DTSTART must use current UTC timestamp** \u2014 a future DTSTART means the cron won't fire until then.\n\n**Conditions and expressions:**\n- **If condition format:** top-level key MUST be `$and` or `$or` \u2014 a bare comparison won't work.\n- **Regex matches** are a map with string keys: use `{{node.result.matches.1}}` (dot notation), never `{{node.result.matches[1]}}`.\n- **code-transform output** is at `{{nodeId.result.output}}`, not `{{nodeId.result}}`. The function must be named `transform(input)`.\n\n**Integrations:**\n- **Slack Block Kit `blocks` must be a JSON string**, not an object. Stringify the JSON array before setting the field.\n- **Slack action results** are nested under `data.ret`: use `{{node.result.data.ret.ts}}`, NOT `{{node.result.data.ts}}`.\n- **Google Sheets worksheetId** must be an integer, never a sheet name string.\n- **Gmail vs email triggers:** `gmail-new-email-*` polls a real Gmail inbox via OAuth. `email-new-email-*` creates a disposable inbox. If the user wants to watch their inbox, use `gmail-*`.\n- **x-new-tweet requires at least one filter** \u2014 empty payload is invalid. Must include username or keywords.\n\n**On-chain:**\n- **approve-erc20 is for smart contracts only** (DEX routers, DeFi protocols). For sending tokens to a wallet, use `send-erc20-token` directly \u2014 no approval step needed.\n- **Use `amountFormatted` in notifications**, `amount` for raw precision in on-chain calls.\n\n**Wait nodes:**\n- **Wait node timeout:** default 5 min is too short for human approval. Set `timeoutMs` to at least 86400000 (24h). Always include a `timed_out` branch child.\n- **Wait node uses `waitPayloadSchema`**, NOT the trigger's `payloadSchema`. For slack-new-interaction-event, valid fields are actionId, messageTs, userIds.\n\n**Database:**\n- **db-query results are always wrapped in a `rows` array** \u2014 access as `{{node.result.rows.0.field}}`, NEVER `{{node.result.field}}`.\n- **Use COALESCE for first-run safety:** `SELECT COALESCE((SELECT spent FROM budgets WHERE id = ?), 0)` \u2014 prevents row[0] IndexOutOfBounds.\n\n**Polymarket:**\n- **polymarket-redeem: add an if guard** checking `{{redeem.result.redeemedAmount}}` > 0 before downstream actions \u2014 redeemedAmount is ZERO for losing outcomes.\n- **Minimum bet amounts:** $1 for market orders (FAK/FOK), $5 for limit orders (GTC).\n";