Add plugin logs search support

.claude-plugin/marketplace.json

@@ -2,15 +2,15 @@
   "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
   "name": "kapso",
   "version": "0.1.0",
-  "description": "Kapso plugins for Claude Code, including WhatsApp automation, integration, and observability skills.",
+  "description": "Kapso plugins for Claude Code, including WhatsApp automation, integration, log search, and observability skills.",
   "owner": {
     "name": "Kapso",
     "url": "https://kapso.ai"
   },
   "plugins": [
     {
       "name": "kapso",
-      "description": "Build, integrate, and observe Kapso WhatsApp agents.",
+      "description": "Build, integrate, search logs, and observe Kapso WhatsApp agents.",
       "version": "0.1.0",
       "author": {
         "name": "Kapso",

.cursor-plugin/marketplace.json

@@ -5,13 +5,13 @@
     "email": "dev@kap.so"
   },
   "metadata": {
-    "description": "Kapso agent plugins for building, integrating, and observing WhatsApp agents."
+    "description": "Kapso agent plugins for building, integrating, searching logs, and observing WhatsApp agents."
   },
   "plugins": [
     {
       "name": "kapso",
       "source": "plugins/kapso",
-      "description": "Build, integrate, and observe Kapso WhatsApp agents."
+      "description": "Build, integrate, search logs, and observe Kapso WhatsApp agents."
     }
   ]
 }

README.md

@@ -8,7 +8,7 @@ Missing an agent harness? Open an issue in this repository.
 
 - `integrate-whatsapp`: connect WhatsApp to products, onboard customers, configure webhooks, send messages, manage templates, and work with WhatsApp Flows.
 - `automate-whatsapp`: build workflows, triggers, functions, agents, app integrations, and database-backed automations.
-- `observe-whatsapp`: inspect delivery, webhook retries, API errors, number health, templates, and operational incidents.
+- `observe-whatsapp`: search unified project logs, inspect delivery, webhook retries, API errors, workflow events, number health, templates, and operational incidents.
 - Kapso MCP server configs for remote authenticated access to Kapso.
 - Safety guidance, examples, and validation scripts for release checks.
 
@@ -71,7 +71,7 @@ codex plugin install kapso@kapso
 codex mcp login kapso
 ```
 
-Direct API fallback scripts use:
+Direct API fallback scripts, including unified log search, use:
 
 ```bash
 export KAPSO_API_BASE_URL="https://api.kapso.ai"

plugins/kapso/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "kapso",
-  "description": "Build, integrate, and observe Kapso WhatsApp agents with Claude Code.",
+  "description": "Build, integrate, search logs, and observe Kapso WhatsApp agents with Claude Code.",
   "version": "0.1.0",
   "author": {
     "name": "Kapso",

plugins/kapso/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kapso",
   "version": "0.1.0",
-  "description": "Build, integrate, and observe Kapso WhatsApp agents with Codex.",
+  "description": "Build, integrate, search logs, and observe Kapso WhatsApp agents with Codex.",
   "author": {
     "name": "Kapso",
     "email": "dev@kap.so",
@@ -21,8 +21,8 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Kapso",
-    "shortDescription": "Build, integrate, and observe Kapso WhatsApp agents from Codex.",
-    "longDescription": "Kapso is the WhatsApp API for developers. This plugin helps Codex onboard customers to WhatsApp, send and receive messages, manage templates and flows, build workflow automations, deploy functions, and debug production delivery or webhook issues with focused Kapso context.",
+    "shortDescription": "Build, integrate, search logs, and observe Kapso WhatsApp agents from Codex.",
+    "longDescription": "Kapso is the WhatsApp API for developers. This plugin helps Codex onboard customers to WhatsApp, send and receive messages, manage templates and flows, build workflow automations, deploy functions, and debug production delivery, workflow, API, or webhook issues with unified log search and focused Kapso context.",
     "developerName": "Kapso",
     "category": "Developer Tools",
     "capabilities": [
@@ -32,7 +32,7 @@
     ],
     "defaultPrompt": [
       "Set up WhatsApp onboarding",
-      "Check WhatsApp health",
+      "Search project logs",
       "Build a WhatsApp support agent"
     ],
     "websiteURL": "https://kapso.ai",

plugins/kapso/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "kapso",
   "displayName": "Kapso",
   "version": "0.1.0",
-  "description": "Build, integrate, and observe Kapso WhatsApp agents with Cursor.",
+  "description": "Build, integrate, search logs, and observe Kapso WhatsApp agents with Cursor.",
   "author": {
     "name": "Kapso",
     "email": "dev@kap.so"

plugins/kapso/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- Added unified project log search guidance and fallback scripts.
+
 ## 0.1.0
 
 - Added skills for integrating WhatsApp, automating WhatsApp workflows, and observing WhatsApp delivery or webhook issues.

plugins/kapso/README.md

@@ -8,7 +8,7 @@ Kapso is the WhatsApp API for developers. This plugin helps agents build, integr
 
 - Connect WhatsApp to products with setup links, connection detection, webhooks, sends, templates, media, and WhatsApp Flows.
 - Build Kapso workflows with WhatsApp triggers, AI steps, functions, app integrations, data tables, and execution controls.
-- Observe production issues by inspecting message delivery, webhook retries, API logs, template health, number health, and error patterns.
+- Observe production issues with unified project log search across API calls, Meta events, workflow events, webhook deliveries, message delivery, template health, number health, and error patterns.
 - Use bundled examples and references so agents can act with product-specific context instead of generic WhatsApp guidance.
 - Keep risky operations behind explicit user approval for sends, deploys, deletes, webhook changes, template creation, setup links, and workflow mutations.
 
@@ -32,7 +32,7 @@ codex plugin install kapso@kapso
 - Skills:
   - `integrate-whatsapp`: connect WhatsApp to products, onboard customers, configure webhooks, send messages, manage templates, and work with WhatsApp Flows.
   - `automate-whatsapp`: build workflows, triggers, functions, agents, app integrations, and database-backed automations.
-  - `observe-whatsapp`: inspect delivery, webhook retries, API errors, number health, templates, and operational incidents.
+  - `observe-whatsapp`: search unified project logs, inspect delivery, webhook retries, API errors, workflow events, number health, templates, and operational incidents.
 - Rule:
   - `kapso-safety`: classifies read-only, local write, and high-risk write operations, and requires explicit approval before high-risk writes.
 - MCP:
@@ -121,7 +121,7 @@ User prompt: "Why did this WhatsApp message fail, and did the webhook retry?"
 Expected behavior:
 
 - The agent uses the `observe-whatsapp` skill.
-- It gathers message details, delivery history, API errors, webhook deliveries, and number health.
+- It starts with unified log search, then gathers message details, delivery history, API errors, webhook deliveries, and number health as needed.
 - It returns a concise diagnosis with next actions and escalation paths.
 
 ## Safety

plugins/kapso/skills/observe-whatsapp/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: observe-whatsapp
-description: "Observe and troubleshoot WhatsApp in Kapso: debug message delivery, inspect webhook deliveries/retries, triage API errors, and run health checks. Use when investigating production issues, message failures, or webhook delivery problems."
+description: "Observe and troubleshoot WhatsApp in Kapso: search operational logs, debug message delivery, inspect webhook deliveries/retries, triage API errors, and run health checks. Use when investigating production issues, message failures, API calls, workflow execution issues, or webhook delivery problems."
 ---
 
 # Observe WhatsApp
 
 ## When to use
 
-Use this skill for operational diagnostics: message delivery investigation, webhook delivery debugging, error triage, and WhatsApp health checks.
+Use this skill for operational diagnostics: unified project log search, message delivery investigation, webhook delivery debugging, error triage, workflow execution investigation, and WhatsApp health checks.
 
 ## Setup
 
@@ -38,14 +38,31 @@ Fallback path:
 ### Triage errors
 
 Preferred path:
-1. Confirm project and number state: `kapso status`
-2. Run number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
-3. Inspect related templates when relevant: `kapso whatsapp templates list --phone-number "<display-number>" --output json`
+1. Search cross-source logs first when you have a request ID, `wamid.*`, endpoint, webhook ID, workflow execution ID, phone number, or recent time window:
+   `kapso logs search --query "<identifier-or-text>" --period 24h --limit 20 --output json`
+2. Narrow by source when known:
+   `kapso logs search --source external_api_log --query "/messages" --problems-only --output json`
+3. Confirm project and number state: `kapso status`
+4. Run number health: `kapso whatsapp numbers health --phone-number "<display-number>" --output human`
+5. Inspect related templates when relevant: `kapso whatsapp templates list --phone-number "<display-number>" --output json`
+
+MCP path:
+- If the Kapso MCP server is connected, use `search_logs` for cross-resource diagnostics before older narrow tools.
+- Good starting inputs: `query`, `period`, `source`, `problems_only`, `limit`, and `filters` as `{key, value}` entries.
+- Sources: `external_api_log`, `whatsapp_webhook_event`, `flow_event`, `webhook_delivery`.
 
 Fallback path:
-1. Message errors: `node scripts/errors.js`
-2. API logs: `node scripts/api-logs.js`
-3. Webhook deliveries: `node scripts/webhook-deliveries.js`
+1. Unified log search: `node scripts/log-search.js --query "<identifier-or-text>" --period 24h --limit 20`
+2. Discover log-search filters and sources: `node scripts/log-search-catalog.js`
+3. Message errors: `node scripts/errors.js`
+4. API logs: `node scripts/api-logs.js`
+5. Webhook deliveries: `node scripts/webhook-deliveries.js`
+
+Use direct API filters when you know the indexed field:
+```bash
+node scripts/log-search.js --source api --problems-only true --filter response_status=500 --filter endpoint_contains=/messages
+node scripts/log-search.js --source workflows --filter flow_execution_id=exec_123 --limit 20
+```
 
 ### Run health checks
 
@@ -71,6 +88,8 @@ Fallback path:
 
 | Script | Purpose |
 |--------|---------|
+| `log-search.js` | Search unified log events across API, Meta, workflows, and webhook deliveries |
+| `log-search-catalog.js` | List log-search sources, filters, and detail fields |
 | `errors.js` | List message errors |
 | `api-logs.js` | List external API logs |
 | `webhook-deliveries.js` | List webhook delivery attempts |
@@ -95,20 +114,22 @@ npm i
 
 Examples:
 ```bash
-node scripts/openapi-explore.mjs --spec platform search "webhook deliveries"
-node scripts/openapi-explore.mjs --spec platform op listWebhookDeliveries
-node scripts/openapi-explore.mjs --spec platform schema WebhookDelivery
+node scripts/openapi-explore.mjs --spec platform search "log search"
+node scripts/openapi-explore.mjs --spec platform op searchLogs
+node scripts/openapi-explore.mjs --spec platform op getLogSearchCatalog
 ```
 
 ## Notes
 
 - For webhook setup (create/update/delete, signature verification, event types), use `integrate-whatsapp`.
 - Prefer resolving a display phone number to the canonical `phone_number_id` before deep debugging.
-- Keep the scripts as the fallback path when the CLI is unavailable or when you need API-log or webhook-delivery inspection.
+- Prefer unified log search before older narrow tools when the user gives a request ID, WhatsApp `wamid.*`, endpoint, webhook ID, workflow execution ID, phone ID, conversation, or recent incident window.
+- Keep the scripts as the fallback path when the CLI or MCP is unavailable.
 
 ## References
 
 - [references/message-debugging-reference.md](references/message-debugging-reference.md) - Message debugging guide
+- [references/log-search-reference.md](references/log-search-reference.md) - Unified log search guide
 - [references/triage-reference.md](references/triage-reference.md) - Error triage guide
 - [references/health-reference.md](references/health-reference.md) - Health check guide
 
@@ -122,8 +143,8 @@ node scripts/openapi-explore.mjs --spec platform schema WebhookDelivery
 [observe-whatsapp file map]|root: .
 |.:{package.json,SKILL.md}
 |assets:{health-example.json,message-debugging-example.json,triage-example.json}
-|references:{health-reference.md,message-debugging-reference.md,triage-reference.md}
-|scripts:{api-logs.js,errors.js,lookup-conversation.js,message-details.js,messages.js,openapi-explore.mjs,overview.js,webhook-deliveries.js,whatsapp-health.js}
+|references:{health-reference.md,log-search-reference.md,message-debugging-reference.md,triage-reference.md}
+|scripts:{api-logs.js,errors.js,log-search-catalog.js,log-search.js,lookup-conversation.js,message-details.js,messages.js,openapi-explore.mjs,overview.js,webhook-deliveries.js,whatsapp-health.js}
 |scripts/lib/messages:{args.js,kapso-api.js}
 |scripts/lib/status:{args.js,kapso-api.js}
 |scripts/lib/triage:{args.js,kapso-api.js}

plugins/kapso/skills/observe-whatsapp/references/log-search-reference.md

@@ -0,0 +1,80 @@
+# Unified Log Search
+
+Use unified log search before narrow list endpoints when the user gives an identifier or incident window. It searches project-scoped API calls, Meta webhook events, workflow events, and outbound webhook deliveries.
+
+## Surfaces
+
+- CLI: `kapso logs search`
+- MCP: `search_logs`
+- Direct API fallback: `node scripts/log-search.js`
+- Catalog fallback: `node scripts/log-search-catalog.js`
+
+## Sources
+
+- `external_api_log`: customer or backend calls into the Kapso Platform API
+- `whatsapp_webhook_event`: raw Meta webhook event projections
+- `flow_event`: workflow execution and step events
+- `webhook_delivery`: Kapso webhook attempts to customer endpoints
+
+Aliases in the fallback script:
+- `api` -> `external_api_log`
+- `meta` -> `whatsapp_webhook_event`
+- `workflows` -> `flow_event`
+- `webhooks` -> `webhook_delivery`
+
+## Good Starting Searches
+
+Request or trace ID:
+```bash
+kapso logs search --query "req_123" --period 24h --limit 20 --output json
+```
+
+WhatsApp message ID:
+```bash
+kapso logs search --query "wamid.ABC123" --period 7d --output json
+```
+
+Failed API sends:
+```bash
+kapso logs search --source external_api_log --query "/messages" --problems-only --filter response_status=500 --output json
+```
+
+Workflow execution:
+```bash
+kapso logs search --source flow_event --filter flow_execution_id=exec_123 --limit 20 --output json
+```
+
+Direct API fallback:
+```bash
+node scripts/log-search.js --query "wamid.ABC123" --period 24h --limit 10
+node scripts/log-search.js --source webhooks --problems-only true --filter webhook_id=wh_123
+```
+
+## Filters
+
+Use `node scripts/log-search-catalog.js` to discover available filter keys. Common useful filters include:
+
+- `request_id`
+- `response_status`
+- `endpoint_contains`
+- `whatsapp_message_id`
+- `phone_number_id`
+- `flow_execution_id`
+- `event_type`
+- `webhook_id`
+- `status`
+- `has_status_error`
+
+Use filters only when you know the indexed field. Start with `query` when the identifier could appear in multiple sources.
+
+## Context Windows
+
+For event context around a timestamp, use the direct API fallback:
+```bash
+node scripts/log-search.js --period context --around "2026-07-07T12:00:00Z" --highlight-resource-id msg_123 --limit 30
+```
+
+Use `pagination.next_cursor` from a previous response with:
+```bash
+node scripts/log-search.js --cursor "<next_cursor>" --limit 50
+```

plugins/kapso/skills/observe-whatsapp/references/triage-reference.md

@@ -14,12 +14,14 @@
 
 ## Webhook delivery failures
 
-1. Review recent delivery attempts.
-2. Check response status codes and error messages.
-3. Verify webhook URL availability and signature verification logic.
+1. Start with unified log search for the webhook ID, URL text, event name, or recent problem events.
+2. Review recent delivery attempts.
+3. Check response status codes and error messages.
+4. Verify webhook URL availability and signature verification logic.
 
 ## API errors
 
-1. Review external API call logs.
-2. Filter by status code or endpoint.
-3. Identify auth errors, rate limits, or upstream failures.
+1. Start with unified log search for the request ID, endpoint, phone ID, `wamid.*`, or response status.
+2. Review external API call logs when you need the older narrow list view.
+3. Filter by status code or endpoint.
+4. Identify auth errors, rate limits, or upstream failures.

plugins/kapso/skills/observe-whatsapp/scripts/log-search-catalog.js

@@ -0,0 +1,36 @@
+const { kapsoConfigFromEnv, kapsoRequest } = require('./lib/triage/kapso-api');
+
+function err(message, details) {
+  return { ok: false, error: { message, details } };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          usage: 'node scripts/log-search-catalog.js',
+          env: ['KAPSO_API_BASE_URL', 'KAPSO_API_KEY']
+        },
+        null,
+        2
+      )
+    );
+    return 0;
+  }
+
+  try {
+    const config = kapsoConfigFromEnv();
+    const data = await kapsoRequest(config, '/platform/v1/log_search/catalog');
+    console.log(JSON.stringify({ ok: true, data }, null, 2));
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(JSON.stringify(err('Command failed', { message }), null, 2));
+    return 1;
+  }
+}
+
+main().then((code) => process.exit(code));