cli-jaw 0.1.0

package/skills_ref/whatsapp/references/graph-contract.md

@@ -0,0 +1,145 @@
+# Workflow Graph Contract (Workflows / Definition)
+
+This document is the source of truth for editing Kapso workflow graphs over the Platform API.
+
+## Endpoints and envelopes
+
+- Fetch graph (definition): `GET /platform/v1/workflows/:id/definition`
+  - Returns a workflow record that includes `definition` (nodes + edges).
+- Fetch metadata: `GET /platform/v1/workflows/:id`
+  - Returns workflow metadata (including `lock_version`) but does NOT include `definition`.
+- Update graph/settings: `PATCH /platform/v1/workflows/:id`
+  - Send `workflow: { ... }` (what the scripts use). `flow: { ... }` is accepted as an alias.
+  - To update the graph, send `workflow: { definition: <definition> }`.
+
+## Two graph shapes: returned vs editable
+
+### Shape returned by get-graph (ReactFlow-style)
+
+`GET /workflows/:id/definition` returns a ReactFlow-style definition that includes extra/computed fields:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "start",
+      "type": "flow-node",
+      "position": { "x": 120, "y": 120 },
+      "data": { "node_type": "start", "config": {}, "display_name": "Start" }
+    }
+  ],
+  "edges": [
+    {
+      "id": "uuid",
+      "source": "start",
+      "target": "send_text_1710000000000",
+      "label": "next",
+      "type": "default",
+      "flow_condition_id": null
+    }
+  ]
+}
+```
+
+### Minimal editable shape accepted by the API
+
+For `PATCH /workflows/:id`, the minimal shape you should edit and send is:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "start",
+      "position": { "x": 120, "y": 120 },
+      "data": { "node_type": "start", "config": {} }
+    },
+    {
+      "id": "send_text_1710000000000",
+      "position": { "x": 120, "y": 320 },
+      "data": {
+        "node_type": "send_text",
+        "config": { "message": "Hello!", "delay_seconds": 0 }
+      }
+    }
+  ],
+  "edges": [
+    { "source": "start", "target": "send_text_1710000000000", "label": "next" }
+  ]
+}
+```
+
+The API ignores/strips extra fields like `node.type`, `data.display_name`, `edge.id`, and `edge.type`. You can keep them unchanged when roundtripping, but do not rely on editing them.
+
+## Nodes
+
+Required:
+- `node.id` (string)
+- `node.position.x`, `node.position.y` (numbers)
+- `node.data.node_type` (string)
+- `node.data.config` (object; per node_type)
+
+Rules:
+- Exactly one start node with `id = "start"` and `data.node_type = "start"`.
+- Never change existing node IDs.
+- For new nodes: use `{node_type}_{timestamp_ms}` for the `id`.
+
+Footgun (important):
+- If `data.node_type` is missing, the backend defaults it to `"start"`.
+- If you create a node with an unknown `data.node_type`, the backend will create it as a start-like step.
+- Always validate before updating: `node scripts/validate-graph.js --definition-file <path>` and treat warnings as blockers.
+
+## Edges
+
+Required:
+- `edge.source` (existing node id)
+- `edge.target` (existing node id)
+- `edge.label` (string)
+
+Rules:
+- Non-decide nodes: 0 or 1 outgoing edge; if present, its `label` must be `"next"`.
+- Decide nodes: one outgoing edge per condition; each edge `label` must match `config.conditions[].label`.
+
+Optional:
+- `edge.flow_condition_id` (only meaningful for decide edges). If present, it must refer to a condition on that decide node.
+
+## Decide node conditions (ids)
+
+For `decide` nodes, `config.conditions[]` controls valid outgoing edge labels.
+
+- When creating NEW conditions, do not include an `id` field (the backend generates it).
+- When editing an EXISTING decide node fetched from the API, you may see `conditions[].id` and `edges[].flow_condition_id` in the returned graph. Keep them unchanged unless you have a specific reason to remove/rebuild the decide node.
+
+## Computed vs editable fields
+
+Do edit:
+- `node.position`
+- `node.data.node_type`
+- `node.data.config`
+- `edge.source`, `edge.target`, `edge.label`
+
+Do NOT treat as editable (computed/ignored/unstable):
+- `node.data.display_name`
+- `edge.id`, `edge.type`
+- any `*_name` fields (model names, function names, etc.)
+
+## Terminal nodes and agent nodes
+
+- Terminal nodes (leaf nodes) are allowed. A node with no outgoing edge ends the workflow after that step completes.
+- Agent nodes can be terminal or can continue via a `"next"` edge, depending on what you want:
+  - Terminal agent: the agent handles the conversation and finishes via its tools (ex: complete_task or handoff_to_human).
+  - Continuing agent: add a `"next"` edge if you want deterministic post-agent steps (ex: send_text summary).
+
+## lock_version conflicts (exact retry pattern)
+
+The Platform API does not currently enforce `lock_version` for definition updates, so the scripts do a precheck.
+
+Use this pattern:
+1. Fetch graph and lock_version: `node scripts/get-graph.js <workflow_id>`
+2. Apply change with lock precheck:
+   - Small surgical edit: `node scripts/edit-graph.js <workflow_id> --expected-lock-version <n> ...`
+   - Full update: `node scripts/update-graph.js <workflow_id> --expected-lock-version <n> --definition-file <path>`
+     - `update-graph.js` can extract `definition` from wrapper JSON, but prefer sending just the `definition` object.
+3. If you get a conflict error:
+   - Re-fetch the latest graph to get the new lock_version.
+   - Re-apply your change on top of the latest definition.
+   - Retry with the new expected lock version.

package/skills_ref/whatsapp/references/node-types.md

@@ -0,0 +1,430 @@
+# Workflow Node Types
+
+## Supported node_type values
+
+These are the `data.node_type` values supported by the Platform API and validated by `scripts/validate-graph.js`:
+
+- `start`
+- `send_text`
+- `send_template`
+- `send_interactive`
+- `wait_for_response`
+- `set_variable`
+- `decide`
+- `call`
+- `webhook`
+- `pipedream`
+- `function`
+- `agent`
+- `handoff`
+
+Messaging nodes are `send_text`, `send_template`, and `send_interactive`.
+
+Node structure:
+
+```json
+{
+  "id": "send_text_1710000000000",
+  "type": "flow-node",
+  "position": { "x": 300, "y": 100 },
+  "data": {
+    "node_type": "send_text",
+    "config": {},
+    "display_name": "Send Text"
+  }
+}
+```
+
+Notes:
+- `display_name` is computed by the backend and is not reliably editable.
+- New node IDs should use `{node_type}_{timestamp_ms}`.
+- Nodes connect from bottom to top; organize the graph vertically (top-down) rather than left-to-right.
+
+## start
+
+```json
+{ "node_type": "start", "config": {} }
+```
+
+Exactly one start node per workflow, id must be `start`.
+
+## send_text
+
+```json
+{ "node_type": "send_text", "config": { "message": "Hello {{vars.name}}!", "delay_seconds": 0 } }
+```
+
+Optional: `whatsapp_config_id`, `to_phone_number`.
+
+## send_template
+
+```json
+{
+  "node_type": "send_template",
+  "config": {
+    "template_id": "uuid",
+    "parameters": { "1": "{{vars.name}}" }
+  }
+}
+```
+
+Optional: `whatsapp_config_id`, `to_phone_number`.
+Use the `integrate-whatsapp` skill to find template IDs and parameter formats.
+
+## send_interactive (buttons)
+
+```json
+{
+  "node_type": "send_interactive",
+  "config": {
+    "interactive_type": "button",
+    "body_text": "Choose an option:",
+    "buttons": [
+      { "id": "yes", "title": "Yes" },
+      { "id": "no", "title": "No" }
+    ]
+  }
+}
+```
+
+Max 3 buttons; id + title required (title max 20 chars).
+
+## send_interactive (list)
+
+```json
+{
+  "node_type": "send_interactive",
+  "config": {
+    "interactive_type": "list",
+    "body_text": "Select:",
+    "list_button_text": "View options",
+    "list_sections": [
+      { "title": "Section", "rows": [{ "id": "opt1", "title": "Option 1" }] }
+    ]
+  }
+}
+```
+
+## send_interactive (cta_url)
+
+```json
+{
+  "node_type": "send_interactive",
+  "config": {
+    "interactive_type": "cta_url",
+    "body_text": "Visit our site",
+    "cta_display_text": "Open",
+    "cta_url": "https://example.com"
+  }
+}
+```
+
+## send_interactive (flow)
+
+```json
+{
+  "node_type": "send_interactive",
+  "config": {
+    "interactive_type": "flow",
+    "body_text": "Open calendar",
+    "flow_id": "<META_FLOW_ID>",
+    "flow_cta": "Open",
+    "flow_action": "navigate",
+    "flow_action_payload": { "screen": "FIRST_SCREEN" }
+  }
+}
+```
+
+Notes:
+- `flow_id` is the Meta Flow ID (string).
+- `flow_action_payload.screen` must be a valid first screen.
+
+## wait_for_response
+
+```json
+{ "node_type": "wait_for_response", "config": { "save_response_to": "user_reply" } }
+```
+
+Saves the next message into `vars.user_reply`.
+
+## set_variable
+
+```json
+{
+  "node_type": "set_variable",
+  "config": {
+    "variable_name": "customer_name",
+    "variable_value": "{{vars.user_reply}}",
+    "value_type": "string"
+  }
+}
+```
+
+Notes:
+- Use `value_type: "string"` unless you have a specific reason to store a different type.
+
+## decide (AI routing)
+
+```json
+{
+  "node_type": "decide",
+  "config": {
+    "decision_type": "ai",
+    "provider_model_id": "uuid",
+    "conditions": [
+      { "label": "interested", "description": "User shows interest" },
+      { "label": "not_interested", "description": "User declines" }
+    ]
+  }
+}
+```
+
+## decide (function routing)
+
+```json
+{
+  "node_type": "decide",
+  "config": {
+    "decision_type": "function",
+    "function_id": "uuid",
+    "conditions": [
+      { "label": "yes", "description": "Approved" },
+      { "label": "no", "description": "Rejected" }
+    ]
+  }
+}
+```
+
+Rules:
+- Outgoing edge labels must match `conditions[].label`.
+- When creating new conditions, do not include an `id` field.
+
+## call (subworkflow)
+
+```json
+{ "node_type": "call", "config": { "workflow_id": "uuid", "save_error_to": "subflow_error" } }
+```
+
+## webhook
+
+```json
+{
+  "node_type": "webhook",
+  "config": {
+    "url": "https://api.example.com/endpoint",
+    "method": "POST",
+    "headers": { "Authorization": "Bearer {{vars.token}}" },
+    "body_template": { "phone": "{{context.phone_number}}" },
+    "save_response_to": "api_result"
+  }
+}
+```
+
+`headers` and `body_template` must be valid JSON objects.
+
+## pipedream (apps)
+
+```json
+{
+  "node_type": "pipedream",
+  "config": {
+    "action_id": "slack-send_message_to_channel",
+    "app_slug": "slack",
+    "account_id": "apn_example",
+    "configured_props": {
+      "channel": "#general",
+      "text": "Hello {{vars.user_name}}!"
+    },
+    "dynamic_props_id": "dp_optional",
+    "save_response_to": "app_result"
+  }
+}
+```
+
+Notes:
+- Use `references/app-integrations.md` for how to find `action_id`, `account_id`, and build `configured_props`.
+- `configured_props` may include `{{vars.*}}`, `{{system.*}}`, `{{context.*}}` runtime variables.
+
+## function
+
+```json
+{ "node_type": "function", "config": { "function_id": "uuid", "save_response_to": "fn_result" } }
+```
+
+Use `automate-whatsapp` function scripts to find function IDs and update code.
+
+## agent
+
+```json
+{
+  "node_type": "agent",
+  "config": {
+    "system_prompt": "You are a helpful assistant...",
+    "provider_model_id": "uuid",
+    "max_iterations": 10,
+    "temperature": 0.7
+  }
+}
+```
+
+Notes:
+- `provider_model_id` is required. Use `scripts/list-provider-models.js` to find it.
+- Agent tool arrays live inside `data.config` (not at the `data` root).
+
+Default tools (toggle on/off only):
+- complete_task (required)
+- handoff_to_human (required)
+- send_notification_to_user
+- send_media
+- get_execution_metadata
+- get_whatsapp_context
+- get_current_datetime
+- save_variable
+- get_variable
+- ask_about_file
+
+Custom tools:
+- `flow_agent_app_integration_tools[]` (app integrations)
+- `flow_agent_webhooks[]` (webhook tools)
+- `flow_agent_mcp_servers[]` (MCP tools)
+
+### Agent tools: exact placement and structure
+
+All tool arrays go under `data.config` of the agent node:
+
+```json
+{
+  "id": "agent_1730000000000",
+  "type": "flow-node",
+  "position": { "x": 120, "y": 320 },
+  "data": {
+    "node_type": "agent",
+    "config": {
+      "system_prompt": "You can schedule appointments and use calendar tools.",
+      "provider_model_id": "uuid",
+      "max_iterations": 10,
+      "temperature": 0.7,
+      "flow_agent_app_integration_tools": [],
+      "flow_agent_webhooks": [],
+      "flow_agent_mcp_servers": []
+    }
+  }
+}
+```
+
+Example asset: `assets/agent-app-integration-example.json`
+
+#### App integration tools (preferred for agent nodes)
+
+Use pre-configured integrations and attach them as tools:
+
+```json
+{
+  "flow_agent_app_integration_tools": [
+    {
+      "name": "check_calendar",
+      "description": "Check availability in Google Calendar",
+      "app_integration_id": "integration_uuid"
+    }
+  ]
+}
+```
+
+Rules:
+- `app_integration_id` is the integration UUID from `scripts/list-integrations.js`.
+- Do not include headers or URLs here; the integration handles auth.
+- Inputs are defined by the integration's `variable_definitions` (or `{{placeholders}}`).
+
+Tool input payload (runtime):
+```json
+{
+  "input": {
+    "calendar_id": "primary",
+    "time_min": "2025-01-01T10:00:00Z",
+    "time_max": "2025-01-01T12:00:00Z"
+  }
+}
+```
+
+#### Webhook tools (custom HTTP tools)
+
+Use when the agent needs to call arbitrary HTTP endpoints:
+
+```json
+{
+  "flow_agent_webhooks": [
+    {
+      "name": "lookup_customer",
+      "description": "Fetch customer data from internal API",
+      "url": "https://api.example.com/customers/lookup",
+      "http_method": "POST",
+      "headers": {
+        "Authorization": "Bearer {{vars.api_token}}",
+        "Content-Type": "application/json"
+      },
+      "body": {
+        "phone_number": "{{context.phone_number}}"
+      },
+      "body_schema": {
+        "type": "object",
+        "properties": {
+          "phone_number": { "type": "string" }
+        },
+        "required": ["phone_number"]
+      },
+      "jmespath_query": null
+    }
+  ]
+}
+```
+
+Rules:
+- `body_schema` must be valid JSON Schema.
+- `headers` and `body` must be JSON objects (not strings).
+- Tool inputs are defined by `body_schema` and are sent as the webhook JSON body.
+
+#### MCP server tools
+
+Use to attach MCP servers the agent can call:
+
+```json
+{
+  "flow_agent_mcp_servers": [
+    {
+      "name": "files",
+      "description": "Local file access",
+      "url": "https://mcp.example.com",
+      "headers": {
+        "Authorization": "Bearer {{vars.mcp_token}}"
+      }
+    }
+  ]
+}
+```
+
+Rules:
+- `url` is required.
+- `headers` must be a JSON object.
+- MCP tool inputs are defined by the MCP server's tool schemas (not configured here).
+
+## handoff
+
+```json
+{ "node_type": "handoff", "config": {} }
+```
+
+Ends execution and flags for human takeover.
+
+## AI Fields (dynamic content)
+
+Set a field to `{"$ai":{}}` and add `ai_field_config`:
+
+```json
+{
+  "message": { "$ai": {} },
+  "provider_model_id": "uuid",
+  "ai_field_config": {
+    "message": { "mode": "prompt", "prompt": "Write a greeting for {{vars.name}}" }
+  }
+}
+```

package/skills_ref/whatsapp/references/triggers.md

@@ -0,0 +1,20 @@
+# Workflow Triggers
+
+Triggers are separate from the workflow graph. Do not store triggers in `workflow_graph`.
+
+Trigger types:
+- `inbound_message`: fires on WhatsApp message (requires `phone_number_id`).
+- `api_call`: fires via Platform API.
+- `whatsapp_event`: fires on WhatsApp events (requires `event`, optional `phone_number_id`).
+
+Use these scripts:
+- `scripts/list-triggers.js <workflow-id>`
+- `scripts/create-trigger.js <workflow-id> --trigger-type <inbound_message|api_call|whatsapp_event> ...`
+- `scripts/update-trigger.js --trigger-id <id> --active true|false`
+- `scripts/delete-trigger.js --trigger-id <id>`
+- `scripts/list-whatsapp-phone-numbers.js` (to find `phone_number_id`)
+
+Notes:
+- For inbound message triggers, use `phone_number_id` (Meta ID).
+- For whatsapp_event triggers, use `event` like `whatsapp.message.delivered`.
+- For API triggers, no extra fields are required.

package/skills_ref/whatsapp/references/workflow-overview.md

@@ -0,0 +1,22 @@
+# Workflow Overview
+
+## Key behaviors
+
+- Workflows are automation graphs; an execution moves node-to-node until it waits or ends.
+- Trigger inbound_message: if a non-observer execution is running or waiting for that conversation, the message routes to it. If in handoff, workflow processing is skipped. Otherwise, a new execution starts.
+- Trigger api_call: starts an execution from the API; context channel is api.
+- Trigger whatsapp_event: starts an observer execution for each matching event; observer executions are read-only by default (allow_outbound: false).
+
+## Execution states
+
+- running: processing steps.
+- waiting: paused waiting for user input (wait_for_response or agent nodes).
+- handoff: halted for human takeover; automation does not process inbound messages.
+- ended: terminal success.
+- failed: terminal error; error_details recorded.
+
+Valid transitions:
+- running -> waiting | ended | failed | handoff
+- waiting -> running | ended | failed | handoff
+- handoff -> running | ended | failed
+- ended/failed have no transitions