cli-jaw 0.1.6 → 0.1.8

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

@@ -1,145 +0,0 @@
-# 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

@@ -1,430 +0,0 @@
-# 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

@@ -1,20 +0,0 @@
-# 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

@@ -1,22 +0,0 @@
-# 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