@desplega.ai/agent-swarm 1.89.0 → 1.91.0

package/README.md

@@ -129,6 +129,8 @@ Check [our templates](https://templates.agent-swarm.dev) for a quick start.
 - **Harness & LLM agnostic** — run with Claude Code, OpenAI Codex, pi-mono, Devin, Claude Managed Agents, raw LLMs, or opencode. [Harness config →](https://docs.agent-swarm.dev/docs/guides/harness-configuration) · [Add a new provider →](https://docs.agent-swarm.dev/docs/guides/harness-providers)
 - **Follow-up continuity across all harnesses** — child tasks inherit a bounded prior-task context preamble built from the task chain, so continuity survives restarts and works the same across every provider. [Task lifecycle →](https://docs.agent-swarm.dev/docs/concepts/task-lifecycle)
 - **Skills & MCP servers** — reusable procedural knowledge and per-agent MCP servers with scope cascade. [MCP tools →](https://docs.agent-swarm.dev/docs/reference/mcp-tools)
+- **External tool-router access** — the `x` command and `swarm_x` MCP tool let humans and agents execute approved third-party routes such as Composio without baking bespoke MCP servers first. [CLI →](https://docs.agent-swarm.dev/docs/reference/cli) · [Composio →](https://docs.agent-swarm.dev/docs/integrations/composio)
+- **Config-driven metrics dashboards** — define read-only SQL widgets, version them, and render them in the dashboard without shipping custom frontend code. [Metrics API →](https://docs.agent-swarm.dev/docs/api-reference/stats)
 - **DB-backed pages** — agents publish HTML or JSON pages (reports, dashboards, action specs) via the `create_page` MCP tool with public / authed / password modes, version history, view counters, diff helpers, and PDF export. [MCP tools → Pages](https://docs.agent-swarm.dev/docs/reference/mcp-tools#pages-tools)
 - **KV store** — Redis-like namespaced key/value store with auto-scoped context (Slack thread / PR / Linear issue / page). [MCP tools → KV](https://docs.agent-swarm.dev/docs/reference/mcp-tools#kv-tools)
 - **Real-time dashboard** — monitor agents, tasks, and inter-agent chat. [app.agent-swarm.dev →](https://app.agent-swarm.dev)
@@ -197,6 +199,7 @@ Missing one? Ask the swarm to build it.
 | **GitLab** | Same model as GitHub — webhooks on issues/MRs, `glab` preinstalled in workers | [Guide](https://docs.agent-swarm.dev/docs/guides/gitlab-integration) |
 | **AgentMail** | Give each agent an inbox; emails become tasks or lead messages | [Guide](https://docs.agent-swarm.dev/docs/guides/agentmail-integration) |
 | **Kapso (WhatsApp)** | Native inbound WhatsApp webhook routing; agents reply over WhatsApp with MCP tools or the `kapso-whatsapp` skill | [Guide](https://docs.agent-swarm.dev/docs/integrations/kapso) |
+| **Composio** | Route approved third-party app operations through `agent-swarm x composio ...` or the `swarm_x` MCP tool | [Guide](https://docs.agent-swarm.dev/docs/integrations/composio) |
 | **Linear** | Bidirectional ticket sync via OAuth + webhooks | [Guide](https://docs.agent-swarm.dev/docs/guides/linear-integration) |
 | **Jira Cloud** | OAuth 3LO ticket sync — assignee/comment events create tasks; lifecycle posts comments back | [Guide](https://docs.agent-swarm.dev/docs/guides/jira-integration) |
 | **Sentry** | Workers can triage Sentry issues with the `/investigate-sentry-issue` command | [Guide](https://docs.agent-swarm.dev/docs/guides/sentry-integration) |
@@ -226,6 +229,7 @@ bunx @desplega.ai/agent-swarm <command>
 | `worker`  | Run a worker agent |
 | `lead`    | Run a lead agent |
 | `e2b`     | Build E2B templates and launch/manage grouped API + lead + worker swarms |
+| `x`       | Execute approved external routes such as Composio |
 | `docs`    | Open documentation (`--open` to launch in browser) |
 
 ## Deployment

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.89.0",
+    "version": "1.91.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -4105,6 +4105,24 @@
                     "minimum": 1,
                     "maximum": 20,
                     "default": 5
+                  },
+                  "scope": {
+                    "type": "string",
+                    "enum": [
+                      "agent",
+                      "swarm",
+                      "all"
+                    ],
+                    "default": "all"
+                  },
+                  "source": {
+                    "type": "string",
+                    "enum": [
+                      "manual",
+                      "file_index",
+                      "session_summary",
+                      "task_completion"
+                    ]
                   }
                 },
                 "required": [
@@ -8152,6 +8170,10 @@
                       "workspace-rw"
                     ],
                     "default": "none"
+                  },
+                  "idempotencyKey": {
+                    "type": "string",
+                    "maxLength": 200
                   }
                 }
               }
@@ -8321,6 +8343,57 @@
         }
       }
     },
+    "/api/mcp-bridge": {
+      "post": {
+        "summary": "Generic MCP tool proxy for the scripts SDK bridge",
+        "tags": [
+          "Scripts"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "tool": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200
+                  },
+                  "args": {
+                    "type": "object",
+                    "additionalProperties": {},
+                    "default": {}
+                  }
+                },
+                "required": [
+                  "tool"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Tool result"
+          },
+          "400": {
+            "description": "Invalid tool name or args"
+          },
+          "403": {
+            "description": "Tool not in SDK allowlist"
+          },
+          "404": {
+            "description": "Tool not found"
+          }
+        }
+      }
+    },
     "/api/mcp-oauth/{mcpServerId}/metadata": {
       "get": {
         "summary": "Probe OAuth metadata (PRMD + AS) for an MCP server",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.89.0",
+  "version": "1.91.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -60,15 +60,15 @@
     "dev": "bun --hot src/stdio.ts",
     "dev:http": "portless api.swarm bun --hot src/http.ts",
     "start": "bun src/stdio.ts",
-    "start:http": "bun src/http.ts",
-    "start:portless": "portless api.swarm bun src/http.ts",
+    "start:http": "bun --expose-gc src/http.ts",
+    "start:portless": "portless api.swarm bun --expose-gc src/http.ts",
     "inspector": "bunx @modelcontextprotocol/inspector --transport stdio bun src/stdio.ts",
     "inspector:http": "bunx @modelcontextprotocol/inspector --transport http https://api.swarm.localhost:1355/mcp",
     "lint": "biome check src",
     "lint:fix": "biome check --write src",
     "format": "biome format --write src",
-    "build:binary": "bun build ./src/cli.tsx --compile --target=bun-linux-x64 --outfile ./dist/agent-swarm",
-    "build:binary:arm64": "bun build ./src/cli.tsx --compile --target=bun-linux-arm64 --outfile ./dist/agent-swarm",
+    "build:binary": "bun build ./src/cli.tsx --compile --compile-exec-argv='--expose-gc' --target=bun-linux-x64 --outfile ./dist/agent-swarm",
+    "build:binary:arm64": "bun build ./src/cli.tsx --compile --compile-exec-argv='--expose-gc' --target=bun-linux-arm64 --outfile ./dist/agent-swarm",
     "docker:build:worker": "docker build -f Dockerfile.worker -t agent-swarm-worker:latest .",
     "docker:run:worker": "docker run --rm -it --env-file .env.docker -p 3202:3000 -v ./logs:/logs -v ./work/shared:/workspace/shared -v ./work/worker-1:/workspace/personal agent-swarm-worker:latest",
     "docker:run:lead": "docker run --rm -it --env-file .env.docker-lead -e AGENT_ROLE=lead -p 3201:3000 -v ./logs:/logs -v ./work/shared:/workspace/shared -v ./work/lead:/workspace/personal agent-swarm-worker:latest",
@@ -116,7 +116,7 @@
     "@earendil-works/pi-ai": "^0.78.0",
     "@earendil-works/pi-coding-agent": "^0.78.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@openai/codex-sdk": "^0.135.0",
+    "@openai/codex-sdk": "^0.136.0",
     "@opencode-ai/sdk": "^1.15.13",
     "@openfort/openfort-node": "^0.9.1",
     "@opentelemetry/api": "^1.9.1",

package/plugin/skills/composio/SKILL.md

@@ -1,98 +1,173 @@
 ---
 name: composio
-description: Use Composio from Agent Swarm via the `agent-swarm x composio` CLI route or the `swarm_x` MCP tool. Trigger when a task needs connected third-party app tools such as Gmail, GitHub, Slack, Notion, or HubSpot through Composio Tool Router sessions, Connect Links, or connected accounts.
+description: Use Composio from Agent Swarm via the `agent-swarm x composio` CLI route or the `swarm_x` MCP tool. Trigger when a task needs connected third-party app tools such as Gmail, GitHub, Slack, Notion, or HubSpot through Composio Tool Router sessions, Connect Links, or connected accounts. This is the HUB skill — for Google apps see the sibling skills `composio-gmail`, `composio-google-calendar`, `composio-google-docs`.
 ---
 
 # Composio
 
-Use this skill when a task needs Composio-managed third-party app access.
-The current supported surface is the Agent Swarm `x` route:
+Hub skill for Composio-managed third-party app access from the swarm.
+The supported surface is the Agent Swarm `x` route:
 
-- CLI: `agent-swarm x composio <method> <path> [options]`
+- CLI: `agent-swarm x composio <METHOD> <path> [--body '<json>']`
 - MCP: `swarm_x` with `target: "composio"`
 
+`COMPOSIO_API_KEY` is deployment-scoped and injected by the CLI/API process — you
+never pass or see it. All paths are **relative** Composio REST paths.
+
+> **Per-app playbooks (verified slugs + argument shapes + gotchas):**
+> [[composio-gmail]] · [[composio-google-calendar]] · [[composio-google-docs]].
+> Read the sibling skill for the app you're touching — it lists the verified tool
+> slugs so you don't have to `/search` blind.
+
 ## Core Model
 
-- `COMPOSIO_API_KEY` is deployment-scoped and injected by the CLI/API process.
-- `user_id` is the app user whose connected accounts should be used.
-- Connected accounts persist under that `user_id` across sessions.
-- Tool Router sessions are task/conversation runtime contexts. Store and reuse
-  the `session_id` for follow-up turns; create a new session if the user,
-  toolkit set, auth config, or pinned connected account changes.
-- Sessions do not expire, but Connect Links and incomplete connection attempts
-  expire quickly. If a connection is missing or expired, initiate a new link.
-
-## Workflow
-
-1. Create or reuse a Tool Router session for the target user and toolkit set.
-2. Search before executing. Use `/search` to get the current tool slug, schema,
-   plan, pitfalls, and connection status.
-3. If Composio reports no active connection, execute
-   `COMPOSIO_MANAGE_CONNECTIONS` for the exact toolkit names it returned.
-4. Share the returned Connect Link with the user and pause until they complete
-   auth.
-5. Retry the app tool only after the toolkit shows an active connected account.
-6. Prefer metadata-first reads (`include_payload:false`, `verbose:false`) unless
-   the user explicitly needs bodies, attachments, or full records.
-7. Paginate when Composio returns `nextPageToken`, cursors, or continuation
-   fields.
-
-## CLI Examples
-
-Create a Gmail-scoped session:
+- **`user_id`** is the app user whose connected accounts are used. We use the
+  person's **email** as `user_id` (e.g. `t@desplega.ai`). There is **no explicit
+  "create user" call** — a user is created implicitly the first time you reference
+  its `user_id` (e.g. when you create a Connect Link). Don't look for a
+  `POST /users` endpoint; it doesn't exist in this flow.
+- **Auth config** (`ac_…`) = a project-level OAuth app config (one per toolkit,
+  set up in the Composio dashboard). A project can have several.
+- **Connected account** (`ca_…`) = a specific user's authorized connection to a
+  toolkit. Persists across sessions under that `user_id`.
+- **Connect Link** = the short-lived URL the user clicks to authorize OAuth.
+- **Tool Router session** = a task/conversation runtime context that auto-resolves
+  the right connected account for a toolkit set. Reuse its `session_id`; create a
+  new one if the user, toolkit set, auth config, or pinned account changes.
+
+## Two ways to call a tool — and when to use each
+
+1. **Tool Router session** (`/tool_router/session…`) — best for multi-turn agent
+   work over a toolkit set. Auto-resolves connections, supports in-session
+   `/search`. **But** it can fail with `ToolRouterV2_NoActiveConnection` (code
+   4302) when stale/duplicate accounts shadow the good one (see Gotchas).
+2. **Direct execute** (`POST /tools/execute/<TOOL_SLUG>`) — best for one-off reads,
+   verification, or when the session reports no active connection. Pin the account
+   explicitly with `connected_account_id`. **This is the reliable path** when a
+   user has exactly one good connection per toolkit.
 
 ```bash
-agent-swarm x composio POST /tool_router/session \
-  --body '{"user_id":"swarm-user-id","toolkits":{"enable":["gmail"]},"workbench":{"enable":false}}'
+agent-swarm x composio POST /tools/execute/GMAIL_FETCH_EMAILS \
+  --body '{"user_id":"t@desplega.ai","connected_account_id":"ca_xlWpkPocZSGr","arguments":{"max_results":3,"include_payload":false,"verbose":false}}'
 ```
 
-Search for the right Gmail tool:
+## Recipe A — Register a user + send Connect Links (one per toolkit)
+
+1. **List the project's auth configs** to get the `ac_…` ids:
+   ```bash
+   agent-swarm x composio GET "/auth_configs" \
+     | jq -r '.items[] | "\(.toolkit.slug)\t\(.id)\t\(.name)"'
+   ```
+2. **Create one Connect Link per auth config** (flat payload — the user is created
+   implicitly here):
+   ```bash
+   agent-swarm x composio POST /connected_accounts/link \
+     --body '{"auth_config_id":"ac_isRh2iU0Z0lM","user_id":"t@desplega.ai"}'
+   # → returns { redirect_url / connect_url: "https://connect.composio.dev/link/lk_…" }
+   ```
+   - **Use `/connected_accounts/link`, NOT `POST /connected_accounts`.** The older
+     path now returns 400 for Composio-managed OAuth configs.
+   - **There is no single bundled URL** for multiple toolkits — Composio issues
+     **one link per toolkit**. Send all of them, labelled per app.
+3. **Links expire ~10 minutes** after creation (link-start token TTL).
+   **Regenerate fresh links immediately before posting** to the user, and tell
+   them the expiry. Offer to regenerate on request.
+4. The user clicks each link and authorizes. Connections then show as `ACTIVE`.
+
+## Recipe B — Verify connections / check status
 
 ```bash
-agent-swarm x composio POST /tool_router/session/$SESSION_ID/search \
-  --body '{"queries":[{"use_case":"Check recent emails in Gmail and return metadata only."}]}'
+agent-swarm x composio GET "/connected_accounts?user_id=t@desplega.ai" \
+  | jq -r '.items[] | "\(.toolkit.slug)\t\(.id)\t\(.status)"'
+```
+Look for `status: ACTIVE`. Anything `INITIALIZING`/`FAILED`/`EXPIRED` is not
+usable. Pin the `ca_…` of the ACTIVE account when calling tools directly.
+
+## Recipe C — Link a Composio connection to a swarm user identity
+
+"Add the composio connection to my user as identity" → `manage-user` with
+`action: update` and the `identities` array.
+
+> **CRITICAL: `identities` is declarative (the desired *full* set).** You MUST
+> pass every existing externalId PLUS the new one, or the omitted ones get
+> removed. First read the current identities (`resolve-user` / get the user),
+> then write the full list back.
+
+```jsonc
+// manage-user action:update
+{
+  "userId": "4dacc65cdab044a6805b2aa0342331b7",
+  "identities": [
+    { "kind": "github",   "externalId": "tarasyarema" },
+    { "kind": "slack",    "externalId": "U08NR6QD6CS" },
+    { "kind": "linear",   "externalId": "…" },
+    { "kind": "kapso",    "externalId": "…" },
+    { "kind": "composio", "externalId": "t@desplega.ai" }   // ← the new one
+  ]
+}
 ```
+Confirm with `resolve-user(kind:composio, externalId:"t@desplega.ai")`.
 
-Connect Gmail if needed:
+## Workflow (Tool Router session path)
+
+1. Create or reuse a Tool Router session for the user + toolkit set.
+2. `/search` before executing — get the current slug, schema, plan, pitfalls,
+   and connection status. (The sibling skills list verified slugs so you can
+   often skip the search.)
+3. If Composio reports no active connection, run `COMPOSIO_MANAGE_CONNECTIONS`
+   for the exact toolkit names, share the Connect Link, and pause for auth.
+4. Retry only after the toolkit shows an ACTIVE connected account.
+5. Prefer metadata-first reads (`include_payload:false`, `verbose:false`) unless
+   the user explicitly needs bodies/attachments/full records.
+6. Paginate on `nextPageToken` / cursors.
 
 ```bash
+# Create a Gmail-scoped session
+agent-swarm x composio POST /tool_router/session \
+  --body '{"user_id":"t@desplega.ai","toolkits":{"enable":["gmail"]},"workbench":{"enable":false}}'
+
+# Search for the right tool
+agent-swarm x composio POST /tool_router/session/$SESSION_ID/search \
+  --body '{"queries":[{"use_case":"Check recent emails and return metadata only."}]}'
+
+# Connect a toolkit if needed
 agent-swarm x composio POST /tool_router/session/$SESSION_ID/execute \
   --body '{"tool_slug":"COMPOSIO_MANAGE_CONNECTIONS","arguments":{"toolkits":["gmail"]}}'
 ```
 
-Fetch lightweight email metadata after connection:
+## Discovering tools for any toolkit
 
+The sibling skills cover the Google apps. For any other toolkit, list its tools:
 ```bash
-agent-swarm x composio POST /tool_router/session/$SESSION_ID/execute \
-  --body '{"tool_slug":"GMAIL_FETCH_EMAILS","arguments":{"user_id":"me","max_results":5,"include_payload":false,"verbose":false}}'
+agent-swarm x composio GET "/tools?toolkit_slug=<slug>&limit=100" \
+  | jq -r '.items[] | "\(.slug)\t\(.name)"'
+```
+Inspect a tool's arguments before calling:
+```bash
+agent-swarm x composio GET "/tools?toolkit_slug=<slug>&limit=200" \
+  | jq '.items[] | select(.slug=="<SLUG>") | {required:.input_parameters.required, props:(.input_parameters.properties|keys)}'
 ```
 
-## MCP Example
+## Gotchas
 
-```jsonc
-// Tool call: swarm_x
-{
-  "target": "composio",
-  "method": "POST",
-  "path": "/tool_router/session/$SESSION_ID/execute",
-  "body": {
-    "tool_slug": "GMAIL_FETCH_EMAILS",
-    "arguments": {
-      "user_id": "me",
-      "max_results": 5,
-      "include_payload": false,
-      "verbose": false
-    }
-  }
-}
-```
+- **`ToolRouterV2_NoActiveConnection` (4302) despite an ACTIVE account.** Cause:
+  stale `INITIALIZING` duplicate accounts (leftover from regenerated Connect
+  Links) shadow the good one; the session auto-resolves the wrong account and
+  in-session `/search` returns empty. **Fix:** use direct
+  `POST /tools/execute/<SLUG>` with the ACTIVE `connected_account_id` pinned
+  (Recipe B → the `ca_…`). Long-term fix is deleting the stale duplicates — but
+  **ask the user before deleting any connection.**
+- **Calendar "from a year ago" trap** — `GOOGLECALENDAR_EVENTS_LIST` has **no
+  default `timeMin`**, so it returns old events. Always pass `timeMin` (now,
+  RFC3339), `singleEvents:true`, `orderBy:"startTime"`. See [[composio-google-calendar]].
 
 ## Guardrails
 
-- Never invent tool slugs or argument shapes. Use `/search` and returned schemas.
-- Never pass absolute URLs as Composio paths. Use relative API paths only.
+- Never invent tool slugs or argument shapes. Use the sibling skills, `/search`,
+  or `GET /tools?toolkit_slug=…`.
+- Never pass absolute URLs as Composio paths — relative API paths only.
 - Do not expose `COMPOSIO_API_KEY`; server-side code injects it.
-- Do not fetch email bodies, attachments, or destructive tool actions unless the
+- Do not fetch email bodies/attachments or run destructive/write tools unless the
   task explicitly requires them.
-- If multiple accounts exist for a toolkit, ask which account to use or pin the
-  specific connected account/session account according to the task.
+- If multiple accounts exist for a toolkit, ask which to use or pin the specific
+  connected account per the task. **Ask before deleting any connection.**

package/plugin/skills/composio-gmail/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: composio-gmail
+description: Per-app playbook for driving Gmail through Composio (toolkit slug `gmail`). Verified GMAIL_* tool slugs and argument shapes for reading, searching, sending, drafts, labels, and threads. Use alongside the `composio` hub skill whenever a task reads or sends Gmail for a connected user. Covers the metadata-first reads, the GMAIL_SEND_EMAIL HTML flag, and reply-to-thread.
+---
+
+# Composio · Gmail
+
+Toolkit slug: **`gmail`**. Read the [[composio]] hub first for the call model
+(`agent-swarm x composio …`, user_id, connected accounts, the 4302 gotcha).
+Tool `arguments` go inside the request body; `user_id` defaults to `"me"` (the
+authorized account) — you usually don't need to set it.
+
+```bash
+# Direct execute (reliable path — pin the ACTIVE ca_… from the hub Recipe B)
+agent-swarm x composio POST /tools/execute/<SLUG> \
+  --body '{"user_id":"t@desplega.ai","connected_account_id":"ca_…","arguments":{ … }}'
+```
+
+## Headline tools
+
+| Slug | What | Key args |
+|---|---|---|
+| `GMAIL_FETCH_EMAILS` | List/search emails | `query`, `max_results` (def **1** — set it!), `include_payload` (def true), `verbose` (def true), `ids_only`, `label_ids`, `page_token` |
+| `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID` | Full single message | `message_id`, `include_payload` |
+| `GMAIL_FETCH_MESSAGE_BY_THREAD_ID` | All messages in a thread | `thread_id` |
+| `GMAIL_LIST_THREADS` | List threads | `query`, `max_results`, `page_token` |
+| `GMAIL_SEND_EMAIL` | Send | `recipient_email`, `subject`, `body`, `is_html` (def false), `cc`, `bcc`, `extra_recipients`, `attachment` |
+| `GMAIL_REPLY_TO_THREAD` | Reply in-thread | `thread_id`, `message_body`, `recipient_email` |
+| `GMAIL_CREATE_EMAIL_DRAFT` / `GMAIL_SEND_DRAFT` | Draft then send | `body`, `subject`, `recipient_email` / `draft_id` |
+| `GMAIL_GET_PROFILE` | Whose mailbox is this? | — |
+| `GMAIL_LIST_LABELS` / `GMAIL_CREATE_LABEL` / `GMAIL_ADD_LABEL_TO_EMAIL` | Labels | `message_id`, `label_ids` (use LIST_LABELS for custom IDs) |
+| `GMAIL_GET_CONTACTS` / `GMAIL_SEARCH_PEOPLE` | Contacts | `query` |
+| `GMAIL_GET_ATTACHMENT` | Download attachment | `message_id`, `attachment_id` |
+
+Full set: 63 tools — list with
+`agent-swarm x composio GET "/tools?toolkit_slug=gmail&limit=100" | jq -r '.items[]|"\(.slug)\t\(.name)"'`.
+Avoid the ones marked Deprecated (`GMAIL_LIST_MESSAGES`, `GMAIL_REMOVE_LABEL`).
+
+## Read recipe (metadata-first)
+
+```bash
+agent-swarm x composio POST /tools/execute/GMAIL_FETCH_EMAILS \
+  --body '{"connected_account_id":"ca_…","arguments":{"max_results":5,"include_payload":false,"verbose":false}}'
+```
+- **Always set `max_results`** — the default is `1`.
+- Use Gmail `query` syntax: `"is:unread"`, `"from:foo@bar.com newer_than:7d"`,
+  `"subject:invoice has:attachment"`.
+- Keep `include_payload:false` + `verbose:false` unless the user needs full bodies
+  (token-heavy). Use `ids_only:true` for the cheapest listing.
+
+## Send recipe
+
+```bash
+agent-swarm x composio POST /tools/execute/GMAIL_SEND_EMAIL \
+  --body '{"connected_account_id":"ca_…","arguments":{
+    "recipient_email":"someone@example.com",
+    "subject":"Hello",
+    "body":"<p>Hi there</p>",
+    "is_html":true,
+    "cc":["cc@example.com"]
+  }}'
+```
+- Set `is_html:true` when `body` contains HTML, otherwise it sends as literal text.
+- `recipient_email` is the primary; add more via `extra_recipients` / `cc` / `bcc`.
+- **Sending is a write action** — only do it when the task explicitly asks.
+
+## Reply in a thread
+
+```bash
+agent-swarm x composio POST /tools/execute/GMAIL_REPLY_TO_THREAD \
+  --body '{"connected_account_id":"ca_…","arguments":{
+    "thread_id":"<thread_id>","recipient_email":"someone@example.com","message_body":"thanks!"
+  }}'
+```
+
+## Gotchas
+
+- Default `max_results` is `1` — forgetting it makes "list my emails" return a
+  single message.
+- Bodies/attachments are token-heavy and may contain secrets — default to
+  metadata; the secret-scrubber doesn't run on Composio tool output.
+- If you get `ToolRouterV2_NoActiveConnection`, switch to direct execute with the
+  pinned `connected_account_id` (hub Gotchas).

package/plugin/skills/composio-google-calendar/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: composio-google-calendar
+description: Per-app playbook for driving Google Calendar through Composio (toolkit slug `googlecalendar`). Verified GOOGLECALENDAR_* tool slugs and argument shapes for listing, finding, creating, and updating events plus free/busy. Use alongside the `composio` hub skill. CRITICAL — covers the "events from a year ago" trap: GOOGLECALENDAR_EVENTS_LIST has no default timeMin, so you MUST pass timeMin/orderBy/singleEvents to get upcoming events.
+---
+
+# Composio · Google Calendar
+
+Toolkit slug: **`googlecalendar`**. Read the [[composio]] hub first for the call
+model. `calendarId` defaults to `"primary"`. Times are **RFC3339**
+(`2026-06-02T15:00:00Z` or with offset).
+
+```bash
+agent-swarm x composio POST /tools/execute/<SLUG> \
+  --body '{"user_id":"t@desplega.ai","connected_account_id":"ca_…","arguments":{ … }}'
+```
+
+## Headline tools
+
+| Slug | What | Key args |
+|---|---|---|
+| `GOOGLECALENDAR_EVENTS_LIST` | List events on a calendar | `calendarId` (def `primary`), **`timeMin`**, `timeMax`, `singleEvents`, `orderBy`, `q`, `maxResults`, `timeZone`, `pageToken` |
+| `GOOGLECALENDAR_EVENTS_LIST_ALL_CALENDARS` | List across all calendars | `timeMin`, `timeMax`, `singleEvents`, `orderBy` |
+| `GOOGLECALENDAR_FIND_EVENT` | Search for an event | `query`, `timeMin`, `timeMax` |
+| `GOOGLECALENDAR_EVENTS_GET` | One event by id | `calendar_id`, `event_id` |
+| `GOOGLECALENDAR_CREATE_EVENT` | Create event | **`start_datetime`** (required), `end_datetime` / `event_duration_minutes` (def 30), `summary`, `description`, `location`, `attendees`, `timezone`, `calendar_id`, `send_updates`, `create_meeting_room` (def true) |
+| `GOOGLECALENDAR_QUICK_ADD` | NL event ("lunch tmrw 1pm") | `calendar_id`, `text` |
+| `GOOGLECALENDAR_UPDATE_EVENT` / `GOOGLECALENDAR_PATCH_EVENT` | Edit event | `calendar_id`, `event_id`, fields |
+| `GOOGLECALENDAR_DELETE_EVENT` | Delete | `calendar_id`, `event_id` |
+| `GOOGLECALENDAR_FIND_FREE_SLOTS` | Free slots | `items` (def `["primary"]`), `time_min`, `time_max`, `timezone` |
+| `GOOGLECALENDAR_LIST_CALENDARS` | List the user's calendars | — |
+| `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` | Server "now" (use for timeMin) | `timezone` |
+
+Full set: 48 tools — `agent-swarm x composio GET "/tools?toolkit_slug=googlecalendar&limit=100" | jq -r '.items[]|"\(.slug)\t\(.name)"'`.
+
+## ⚠️ The "events from a year ago" trap
+
+`GOOGLECALENDAR_EVENTS_LIST` has **no default `timeMin`**. Calling it with no time
+window returns old/arbitrary events (this is exactly how "what's on my calendar?"
+came back with stuff from a year ago). To get **upcoming** events you MUST set the
+window and ordering explicitly:
+
+```bash
+NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+agent-swarm x composio POST /tools/execute/GOOGLECALENDAR_EVENTS_LIST \
+  --body "{\"connected_account_id\":\"ca_…\",\"arguments\":{
+    \"calendarId\":\"primary\",
+    \"timeMin\":\"$NOW\",
+    \"singleEvents\":true,
+    \"orderBy\":\"startTime\",
+    \"maxResults\":10
+  }}"
+```
+- `timeMin` = now (or the start of the window you care about).
+- `singleEvents:true` expands recurring events into individual instances — required
+  for `orderBy:"startTime"` to be valid.
+- Add `timeMax` to bound the window (e.g. next 7 days).
+- For "today/this week" prefer computing `timeMin`/`timeMax` locally, or call
+  `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` first to anchor to the server's clock.
+
+## Create an event
+
+```bash
+agent-swarm x composio POST /tools/execute/GOOGLECALENDAR_CREATE_EVENT \
+  --body '{"connected_account_id":"ca_…","arguments":{
+    "summary":"Norrsken <> Desplega",
+    "start_datetime":"2026-06-05T15:00:00+02:00",
+    "event_duration_minutes":30,
+    "timezone":"Europe/Madrid",
+    "attendees":["someone@example.com"],
+    "send_updates":"all"
+  }}'
+```
+- Either `end_datetime` OR `event_duration_minutes` (default 30).
+- `create_meeting_room` defaults true (adds Google Meet) — set false to skip.
+- Create/update/delete are **write actions** — only on explicit request.
+
+## Gotchas
+
+- The year-ago trap above is the #1 issue. `timeMin` is not optional in practice.
+- `orderBy:"startTime"` requires `singleEvents:true` or the API errors.
+- Output uses the event's own timezone; pass `timeZone` to normalize display.

package/plugin/skills/composio-google-docs/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: composio-google-docs
+description: Per-app playbook for driving Google Docs through Composio (toolkit slug `googledocs`). Verified GOOGLEDOCS_* tool slugs and argument shapes for searching, reading plaintext, creating (incl. from markdown), and editing documents. Use alongside the `composio` hub skill whenever a task reads or writes Google Docs for a connected user.
+---
+
+# Composio · Google Docs
+
+Toolkit slug: **`googledocs`**. Read the [[composio]] hub first for the call model.
+A document is identified by its `document_id` (the id in the Docs URL).
+
+```bash
+agent-swarm x composio POST /tools/execute/<SLUG> \
+  --body '{"user_id":"t@desplega.ai","connected_account_id":"ca_…","arguments":{ … }}'
+```
+
+## Headline tools
+
+| Slug | What | Key args |
+|---|---|---|
+| `GOOGLEDOCS_SEARCH_DOCUMENTS` | Find docs (Drive search) | `query`, `max_results` (def 10), `order_by` (def `modifiedTime desc`), `modified_after`, `created_after`, `starred_only`, `shared_with_me`, `response_detail` (def `minimal`) |
+| `GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT` | Read doc as text | **`document_id`**, `include_tables` (def true), `include_headers`, `include_footers`, `include_footnotes`, `include_tabs_content` |
+| `GOOGLEDOCS_GET_DOCUMENT_BY_ID` | Full structured doc JSON | `document_id` |
+| `GOOGLEDOCS_CREATE_DOCUMENT` | Create blank/with text | `title`, `text` |
+| `GOOGLEDOCS_CREATE_DOCUMENT_MARKDOWN` | Create from markdown | **`title`**, `markdown_text`, `image_assets` |
+| `GOOGLEDOCS_UPDATE_DOCUMENT_MARKDOWN` | Replace body with markdown | `document_id`, `markdown_text` |
+| `GOOGLEDOCS_INSERT_TEXT_ACTION` | Insert text at index | `document_id`, `text`, `index` |
+| `GOOGLEDOCS_REPLACE_ALL_TEXT` | Find & replace | `document_id`, `find`, `replace` |
+| `GOOGLEDOCS_COPY_DOCUMENT` | Duplicate a doc | `document_id`, `title` |
+| `GOOGLEDOCS_EXPORT_DOCUMENT_AS_PDF` | Export to PDF | `document_id` |
+
+Full set: 35 tools — `agent-swarm x composio GET "/tools?toolkit_slug=googledocs&limit=100" | jq -r '.items[]|"\(.slug)\t\(.name)"'`.
+Prefer the `*_MARKDOWN` create/update tools for authoring; the granular
+`INSERT_*`/`DELETE_*`/table tools are for surgical structural edits.
+
+## Search recipe
+
+```bash
+agent-swarm x composio POST /tools/execute/GOOGLEDOCS_SEARCH_DOCUMENTS \
+  --body '{"connected_account_id":"ca_…","arguments":{"query":"workshop","max_results":5}}'
+# → results under .data.files[]  (id, name, modifiedTime …)
+```
+- Results are Drive file entries at **`.data.files[]`** — grab `.id` to read.
+- `order_by` defaults to `modifiedTime desc` (most recent first).
+- Use `modified_after` / `shared_with_me` to narrow.
+
+## Read recipe
+
+```bash
+agent-swarm x composio POST /tools/execute/GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT \
+  --body '{"connected_account_id":"ca_…","arguments":{"document_id":"<id>","include_tables":true}}'
+```
+Use `GET_DOCUMENT_PLAINTEXT` for reading content; only reach for
+`GET_DOCUMENT_BY_ID` when you need the structured JSON (styles, indices) for an
+edit.
+
+## Create-from-markdown recipe
+
+```bash
+agent-swarm x composio POST /tools/execute/GOOGLEDOCS_CREATE_DOCUMENT_MARKDOWN \
+  --body '{"connected_account_id":"ca_…","arguments":{
+    "title":"Weekly updates","markdown_text":"# Heading\n\n- point one\n- point two"
+  }}'
+```
+
+## Gotchas
+
+- Search returns Drive metadata, not document content — do a second
+  `GET_DOCUMENT_PLAINTEXT` call with the `.id` to read.
+- Doc bodies can be long/token-heavy and may contain secrets — read only what you
+  need (`include_headers/footers/footnotes` default off for a reason).
+- Create/update/replace are **write actions** — only on explicit request.