@desplega.ai/agent-swarm 1.88.0 → 1.90.0

package/README.md

@@ -9,6 +9,9 @@
   <sub>Built by <a href="https://desplega.sh">desplega.sh</a> — by builders, for builders.</sub>
 </p>
 
+> [!TIP]
+> **This repo evolves every single day.** [Watch now →](https://github.com/desplega-ai/agent-swarm/subscription)
+
 <p align="center">
   <video src="https://github.com/user-attachments/assets/e220712e-c54d-4f46-b059-bac04639d229" controls muted playsinline width="720"></video>
 </p>
@@ -126,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)
@@ -194,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) |
@@ -223,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.88.0",
+    "version": "1.90.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": [
@@ -277,6 +277,46 @@
         }
       }
     },
+    "/api/active-sessions/recover-orphaned-tasks": {
+      "post": {
+        "summary": "Recover orphaned in-progress tasks for an agent",
+        "tags": [
+          "Active Sessions"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "agentId": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "minAgeSeconds": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0
+                  }
+                },
+                "required": [
+                  "agentId"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Recovery result"
+          }
+        }
+      }
+    },
     "/api/agents": {
       "post": {
         "summary": "Register or re-register an agent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.88.0",
+  "version": "1.90.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -45,6 +45,7 @@
     "tsc:check": "bun tsc --noEmit",
     "check:db-boundary": "bash scripts/check-db-boundary.sh",
     "check:api-key-boundary": "bash scripts/check-api-key-boundary.sh",
+    "check:audit-columns": "bash scripts/check-audit-columns.sh",
     "prepare-release": "bun scripts/prepare-release.ts",
     "sync-chart-version": "bun scripts/sync-chart-version.ts",
     "check-chart-version": "bun scripts/sync-chart-version.ts --check-if-package-version-changed",
@@ -115,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

@@ -0,0 +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. This is the HUB skill — for Google apps see the sibling skills `composio-gmail`, `composio-google-calendar`, `composio-google-docs`.
+---
+
+# Composio
+
+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> [--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
+
+- **`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 /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}}'
+```
+
+## 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 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")`.
+
+## 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"]}}'
+```
+
+## Discovering tools for any toolkit
+
+The sibling skills cover the Google apps. For any other toolkit, list its tools:
+```bash
+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)}'
+```
+
+## Gotchas
+
+- **`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 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 run destructive/write tools unless the
+  task explicitly requires them.
+- 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.