@desplega.ai/agent-swarm 1.85.0 → 1.86.0

package/templates/skills/exa-search/content.md

@@ -0,0 +1,106 @@
+# Exa Search
+
+Exa (https://exa.ai) is a neural/semantic search API. It returns web results ranked by embedding similarity rather than keyword match — much better than Google for "find me companies that sound like X" or "what papers explore the shape of Y."
+
+## When to use Exa vs. WebSearch
+
+| Query shape | Use |
+|---|---|
+| "What is the official Bun docs URL?" | WebSearch (concrete lookup) |
+| "Latest CVE for Next.js" | WebSearch (recent, factual) |
+| "Companies building post-hierarchy AI org platforms" | **Exa** (conceptual / discovery) |
+| "Papers on Bayesian memory rating for agents" | **Exa** (topic-shape) |
+| "Blogs that argue knowledge ≠ data in agent systems" | **Exa** (argument-shape) |
+| "Funding rounds for company X in 2026" | WebSearch (named entity + date) |
+
+Rule of thumb: if you're tempted to run 5+ WebSearch calls rephrasing the same idea, use Exa instead — one neural query usually surfaces the cluster.
+
+## Step 1 — Get the API key
+
+```bash
+# Via MCP tool (preferred — handles secret resolution)
+mcp__agent-swarm__get-config(key="EXA_API_KEY", includeSecrets=true)
+```
+
+The value comes back at `configs[0].value`. Export to env or pass inline.
+
+## Step 2 — Call the search endpoint
+
+Endpoint: `POST https://api.exa.ai/search` — full reference at https://exa.ai/docs/reference/search
+
+```bash
+curl -X POST 'https://api.exa.ai/search' \
+  -H "x-api-key: $EXA_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": "companies building agent coordination layers for enterprises",
+    "type": "neural",
+    "numResults": 10,
+    "useAutoprompt": true
+  }'
+```
+
+Key request fields:
+- `query` (required): the natural-language description, NOT keywords
+- `type`: `"neural"` (semantic, default for discovery) or `"keyword"` (legacy) or `"auto"` (let Exa choose)
+- `numResults`: 1–25, default 10
+- `useAutoprompt`: true → Exa rewrites your query for better embedding match (recommended for short/colloquial queries)
+- `includeDomains` / `excludeDomains`: arrays for filtering
+- `startPublishedDate` / `endPublishedDate`: ISO dates for time-bounding
+- `category`: e.g. `"company"`, `"research paper"`, `"news"`, `"github"`, `"tweet"`, `"pdf"` — narrows the result type
+
+Response shape (trimmed):
+```json
+{
+  "results": [
+    { "title": "...", "url": "...", "publishedDate": "...", "author": "...", "score": 0.42, "id": "..." }
+  ],
+  "autopromptString": "the rewritten query Exa actually used"
+}
+```
+
+## Step 3 — (Optional) Get full content
+
+The `/search` endpoint returns metadata only. To pull article bodies:
+
+```bash
+curl -X POST 'https://api.exa.ai/contents' \
+  -H "x-api-key: $EXA_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "ids": ["result-id-from-search"],
+    "text": true
+  }'
+```
+
+Or use the one-shot `/search` variant with `"contents": { "text": true }` baked into the search request to get content in a single round-trip.
+
+## Step 4 — Pair with WebFetch for verification
+
+Exa surfaces candidates fast but its content snippets can be stale or truncated. For any claim you'll cite (funding amount, headcount, product description), follow up with WebFetch on the canonical company URL. Treat Exa as a discovery layer, WebFetch as the source of truth.
+
+## Discipline — no fabrication
+
+If a query returns no relevant results, **say "not surfaced"** in your output rather than inventing plausible-sounding companies/papers/links. The most common Exa failure mode is over-promising a comprehensive landscape when the embedding space had thin coverage of your topic. Marking gaps explicitly is what makes the research trustworthy.
+
+## Real-world example queries (from 2026-05-04 swarm competitive analysis)
+
+These are the exact queries the Researcher used to map the agent-coordination landscape:
+
+- `"multi-agent platform for enterprises"`
+- `"AI org operating system post-hierarchy intelligence"`
+- `"AI employee platform digital workers"`
+- `"derived knowledge layer for AI agents"`
+- `"agent coordination layer routes work specialist"`
+- `"humans at the edge AI org structure"`
+- `"agent capability gap registry knowledge graph"`
+
+Each surfaced 8–12 results; combined with WebFetch on company sites and WebSearch for funding numbers, the Researcher mapped 5 staked competitive slots + 1 open quadrant in ~30 min. See `agent-fs --org 648a5f3c-35c8-4f11-8673-b89de52cd6bd cat thoughts/d454d1a5-4df9-49bd-8a89-e58d6a657dc3/research/2026-05-04-swarm-competitive-analysis.md` for the full output.
+
+## Quick gotchas
+
+- The header is `x-api-key`, **not** `Authorization: Bearer`.
+- Free-tier rate limits are tight — batch your queries, don't fire dozens.
+- Neural search is non-deterministic across calls; same query can shuffle top-5 results.
+- `useAutoprompt: true` is almost always right; only disable if you've already hand-tuned the query.
+

package/templates/skills/jira-interaction/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "jira-interaction",
+  "displayName": "Jira Interaction",
+  "slug": "jira-interaction",
+  "title": "Jira Interaction",
+  "description": "Generic Jira update discipline for issue comments, transitions, and triage.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["JIRA_PROJECT_KEY"],
+  "runAllSeedersCandidate": false,
+  "tags": ["jira", "tracker", "project-management"]
+}

package/templates/skills/jira-interaction/content.md

@@ -0,0 +1,252 @@
+# Jira Interaction (Read + Outbound Push)
+
+The swarm has Jira OAuth connected but **no inbound sync** (unlike Linear). Every read or write is a direct API call against the Atlassian REST API v3.
+
+## TL;DR — minimum knowledge
+
+1. Pull the access token from `oauth_tokens` (provider = `jira`).
+2. Hit `https://api.atlassian.com/ex/jira/<CLOUD_ID>/rest/api/3/...` — *not* `desplega.atlassian.net` directly. 3LO bearer tokens only work via the `api.atlassian.com` proxy.
+3. Bodies for descriptions/comments must be in **ADF** (Atlassian Document Format), not plain text or markdown.
+
+## Known constants (Desplega tenant)
+
+- Site: `desplega.atlassian.net`
+- Cloud ID: `0054e739-8d39-4f01-8d6a-431619cae8fc`
+- Default project: `KAN` ("Swarm")
+- Scopes on the stored token: `manage:jira-webhook offline_access read:jira-work read:me write:jira-work`
+
+If the cloudId ever changes, rediscover it:
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
+  https://api.atlassian.com/oauth/token/accessible-resources | jq '.'
+```
+
+## Authentication
+
+The OAuth token is in the swarm DB (`oauth_tokens`, provider = `jira`).
+
+```sql
+-- via the db-query MCP tool
+SELECT accessToken, expiresAt, scope FROM oauth_tokens WHERE provider = 'jira';
+```
+
+**Always check `expiresAt` first.** Atlassian access tokens are short-lived (~1h). If expired, do NOT keep retrying — report it. Re-auth path:
+
+```
+https://api.desplega.agent-swarm.dev/api/trackers/jira/authorize
+```
+(User may need to remove the app and re-auth.)
+
+## Calling pattern
+
+Every endpoint below is relative to:
+```
+https://api.atlassian.com/ex/jira/<CLOUD_ID>/rest/api/3
+```
+
+Standard header set:
+```bash
+-H "Authorization: Bearer $TOKEN"
+-H "Accept: application/json"
+-H "Content-Type: application/json"   # only on POST/PUT
+```
+
+## Common operations
+
+### 1. List projects
+
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/project/search" \
+  | jq '.values[] | {key, name, id, projectTypeKey}'
+```
+
+### 2. Get a project (with issue types + lead)
+
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/project/KAN" \
+  | jq '{key, name, lead: .lead.displayName, issueTypes: [.issueTypes[] | {id, name, subtask}]}'
+```
+
+### 3. Search issues with JQL
+
+Use the **`/search/jql`** endpoint (the older `/search` is deprecated for cloud).
+
+```bash
+curl -s -G \
+  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
+  --data-urlencode 'jql=project = KAN AND statusCategory != Done' \
+  --data-urlencode 'fields=summary,status,assignee,priority' \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/search/jql" \
+  | jq '[.issues[] | {key, summary: .fields.summary, status: .fields.status.name, assignee: .fields.assignee.displayName}]'
+```
+
+### 4. Create an issue
+
+Description must be ADF. Minimal valid ADF:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue" \
+  -d '{
+    "fields": {
+      "project": { "key": "KAN" },
+      "summary": "Short title",
+      "issuetype": { "name": "Task" },
+      "description": {
+        "type": "doc",
+        "version": 1,
+        "content": [
+          { "type": "paragraph", "content": [ { "type": "text", "text": "Body goes here." } ] }
+        ]
+      }
+    }
+  }'
+```
+
+Returns `{ id, key, self }` on success (HTTP 201). The `key` (e.g. `KAN-7`) is what humans use; URL is `https://desplega.atlassian.net/browse/<KEY>`.
+
+Available issue types in `KAN` (verify per-project): `Epic, Subtask, Task, Story, Feature, Request, Bug`.
+
+### 5. Transition issue status (e.g. → Done)
+
+Transitions are project- and workflow-specific. Always discover them first:
+
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/<KEY>/transitions" \
+  | jq '.transitions[] | {id, name, to: .to.name}'
+```
+
+For project `KAN` (verified 2026-04-27), the workflow exposes ALL transitions from any state — you do not need to walk through intermediate states:
+
+| Transition ID | Target state |
+|---|---|
+| `11` | To Do |
+| `21` | In Progress |
+| `31` | In Review |
+| `41` | Backlog |
+| `51` | **Done** |
+
+Transition (returns HTTP 204 on success, no body):
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3/transitions" \
+  -d '{"transition":{"id":"51"}}'
+```
+
+### 6. Comment on an issue
+
+ADF body again:
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3/comment" \
+  -d '{
+    "body": {
+      "type": "doc", "version": 1,
+      "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Update from the swarm." } ] } ]
+    }
+  }'
+```
+
+### 7. Assign an issue
+
+Atlassian Cloud uses **accountId**, not username. Find one via:
+
+```bash
+curl -s -G -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
+  --data-urlencode 'query=taras' \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/user/search" \
+  | jq '.[] | {accountId, displayName, emailAddress}'
+```
+
+Assign:
+```bash
+curl -s -X PUT \
+  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3/assignee" \
+  -d '{"accountId":"<ACCOUNT_ID>"}'
+```
+
+To unassign: `{"accountId": null}`.
+
+### 8. Edit fields on an existing issue
+
+```bash
+curl -s -X PUT \
+  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/KAN-3" \
+  -d '{ "fields": { "summary": "New summary", "labels": ["swarm","auto"] } }'
+```
+
+Returns HTTP 204.
+
+## ADF cheat-sheet
+
+ADF = JSON tree. Always wrap content in `{ "type": "doc", "version": 1, "content": [...] }`.
+
+Common nodes:
+- Paragraph: `{ "type": "paragraph", "content": [ { "type": "text", "text": "hi" } ] }`
+- Bold: `{ "type": "text", "text": "x", "marks": [{ "type": "strong" }] }`
+- Code inline: `{ "type": "text", "text": "x", "marks": [{ "type": "code" }] }`
+- Code block: `{ "type": "codeBlock", "attrs": { "language": "bash" }, "content": [ { "type": "text", "text": "echo hi" } ] }`
+- Bullet list: `{ "type": "bulletList", "content": [ { "type": "listItem", "content": [ { "type": "paragraph", "content": [...] } ] } ] }`
+- Link: `{ "type": "text", "text": "click", "marks": [{ "type": "link", "attrs": { "href": "https://..." } }] }`
+
+If you need rich content, build it in a script — don't try to write deep ADF inline in shell.
+
+## Operational rules
+
+- **Token-expiry first.** Always check `expiresAt`. Don't loop on 401s.
+- **Use the proxy.** All authenticated calls go through `api.atlassian.com/ex/jira/<cloudId>/...`. Hitting `desplega.atlassian.net/rest/api/3/...` with a 3LO bearer token will fail.
+- **Discover transitions per issue** before transitioning — different projects/workflows have different IDs.
+- **Use `/search/jql`**, not the legacy `/search` (which is deprecated and may be removed).
+- **ADF is mandatory** for `description`, `comment`, and rich text fields. Plain strings will be rejected.
+- **Account IDs, not usernames** for assignment, mentions, and filters.
+- **Rate limits:** Atlassian rate-limits per app and per user. For bulk transitions/comments, sleep ~200–500 ms between calls.
+- **Don't leak tokens.** Never echo the access token to logs or Slack. Read it into an env var only.
+
+## Error handling
+
+| Status | Likely cause | Action |
+|---|---|---|
+| 401 | Token expired/invalid | Check `expiresAt`. Notify user to re-auth. Don't retry. |
+| 403 | Missing scope, or restricted issue | Check the `scope` column. For `write:jira-work` operations, confirm scope is present. |
+| 404 | Wrong key, wrong cloudId, wrong project | Re-verify with a project list call. |
+| 400 | Body shape wrong (often ADF or required field) | Inspect `errorMessages` / `errors` in the response JSON. |
+| 429 | Rate-limited | Back off, retry after `Retry-After` seconds. |
+
+## Complete worked example: clean a project
+
+```bash
+TOKEN=$(db-query "SELECT accessToken FROM oauth_tokens WHERE provider='jira'")
+CLOUD_ID="0054e739-8d39-4f01-8d6a-431619cae8fc"
+
+# 1. List open issues in KAN
+curl -s -G -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
+  --data-urlencode 'jql=project = KAN AND statusCategory != Done' \
+  --data-urlencode 'fields=summary,status' \
+  "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/search/jql" \
+  | jq -r '.issues[].key' > /tmp/keys.txt
+
+# 2. Transition each to Done (id 51 in KAN)
+for KEY in $(cat /tmp/keys.txt); do
+  curl -s -X POST \
+    -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
+    "https://api.atlassian.com/ex/jira/$CLOUD_ID/rest/api/3/issue/$KEY/transitions" \
+    -d '{"transition":{"id":"51"}}'
+  sleep 0.3
+done
+```
+
+## Notes for swarm sync (future)
+
+- The MCP tracker tools (`tracker-link-task`, `tracker-sync-status`, etc.) are designed for two-way sync mappings. Jira tracker support exists at the schema level but is not currently wired up to inbound webhooks. Until it is, all Jira interaction must go through this skill.
+- If/when inbound Jira webhooks land, this skill should add a "When to transition" section mirroring the Linear one.
+

package/templates/skills/kapso-whatsapp/config.json

@@ -0,0 +1,13 @@
+{
+  "kind": "skill",
+  "name": "kapso-whatsapp",
+  "displayName": "WhatsApp Messaging",
+  "slug": "kapso-whatsapp",
+  "title": "WhatsApp Messaging",
+  "description": "Generic WhatsApp messaging guardrails for approved business messaging providers.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": ["WHATSAPP_PROVIDER_API_KEY", "WHATSAPP_SENDER_ID"],
+  "runAllSeedersCandidate": false,
+  "tags": ["whatsapp", "messaging", "communications"]
+}