connect-apps

Files (5)

• SKILL.md
• connect-precheck.py · hooks/
• manifest.json
• precheck_apps.json
• connectors.py · scripts/

SKILL.md (first lines)

# Connect apps

The owner's apps (Google Calendar, Gmail, Google Meet, Google Drive, Slack, Linear, Notion, GitHub,
and a thousand more) are reached through the `sutando-station` MCP server. A connection made
mid-session works at once; nothing here ever needs a restart.

When an app isn't connected, the flow looks like this in the owner's chat:

1. You: "Your Google Calendar isn't connected yet, so I can't peek at your schedule. Want to hook it up?"
2. A card: the app's icon and name with a **Connect** button.
3. You: "Once that's done I'll be able to check what's coming up for you." The task ends here.
4. After sign-in you continue by yourself: "Your Google Calendar is connected and ready to go. Here's your Friday: ..."

In a room with other people, lines 1 to 3 are not messages: they are a **private card** under the
owner's message, inside their "Only visible to you" activity card, which no other member receives.
The room sees nothing about connecting, only your reply once the request is done (step 3b).

Every request gets exactly one answer: the steps below check for a wait before answering.

**Calendar, contacts and reminders: the connector first, the native Mac apps never on your own.**
Order: (1) the Station connector (`composio_find {"apps": ["google calendar"]}` → `composio_exec`,
toolkit `googlecalendar`); (2) if it is not connected, the owner's own tools when they are in your
tool list (`mcp__claude_ai_Google_Calendar__*`); (3) otherwise the Connect card below, or ask the
owner. Never fall back to the macOS Calendar, Reminders or Contacts app by yourself — it raises a
permission prompt on the owner's screen (the `native-pim-guard` hook denies the command). Only when
the owner asked for the local app: `skills/macos-tools` scripts with `--owner-asked`. Once the owner
denied that permission, never re-prompt.

## Tools

- `mcp__sutando-station__composio_find` `{query?, apps?: [names], toolkit?, limit?}` returns JSON
  `{"apps":[{toolkit, name, icon_url, connected, auth_mode, coming_soon}], "actions":[{toolkit, action, description, inputSchema}], "next_step"?}`.
  `apps` matches app names ("google calendar", "linear"); actions are listed for connected apps and
  for an exact `toolkit` slug.
- `mcp__sutando-station__composio_exec` `{toolkit, action, arguments}` runs one action. An error
  whose message contains `connect_required` means the app is not connected.
- `mcp__sutando-station__station_find` / `station_call` reach the owner's cloud tools, including one
  activated a minute ago. See "Paid cloud tools" below.
- The helper script, next to this file:

```bash
C="<this skill's directory>/scripts/connectors.py"
python3 "$C" find "google calendar"            # exact catalog app: {"match": {...} | null, "suggestions": [...]}
python3 "$C" status googlecalendar --room '<room id>'   # connected? plus the room's pending and resumed waits
python3 "$C" status                            # every connection: id, toolkit, name, status, accountLabel
python3 "$C" card googlecalendar --room '<room id>' --reply-to '<source_message_id>' \
  --task '<task id>' --owner-from-task --request-file - <<'SUTANDO_REQUEST'
<the owner request, verbatim>
SUTANDO_REQUEST
# the owner's DM: checks the catalog and the connections, arms the wait, prints "message" to post
python3 "$C" card youtube --room '<shared room id>' --reply-to '<source_message_id>' \
  --task '<task id>' --owner-from-task --private \
  --line "YouTube isn't connected yet, so I can't do that. Connect it here and I'll carry on." \
  --line "Once that's done I'll pull up your latest videos." --request-file - <<'SUTANDO_REQUEST'
<the owner request, verbatim>
SUTANDO_REQUEST
# a room with other people: writes the private card under the owner's message; nothing to post
python3 "$C" card linear --room '<room id>' --reply-to '<source_message_id>' \
  --task '<task id>' --owner-from-task --switch --request-file - <<'SUTANDO_REQUEST'
<the owner request, verbatim>
SUTANDO_REQUEST
# a Switch account card (add --private in a room with other people)
python3 "$C" note '<wait id>' "YouTube is connected. On it." [--status connected]   # a private-card line
python3 "$C" claim '<room id>'                 # before answering in a room that may have a wait
python3 "$C" verify-account '<wait id>'        # a resume: is the wait's AG2 Cloud account the one in use now?
python3 "$C" set-default gmail work@x.io      # the account the agent uses for gmail unless told otherwise
python3 "$C" rearm                             # restart dead waiters (startup + proactive loop run it)
```

`card` is `status` + `await` in one process: the catalog check for each slug, one connections read,
one account read, then the wait (merged with the room's pending waits for the same apps and account,
exactly as `await`). `--owner-from-task` takes the owner from the task file's `user_id`, so you never
call `ag2.whoami` for it. `--line` is optional: the first line is the intro (the text above the card
in the DM, the first line of a private card); without it a plain default is used. `await` (same
arguments, `--owner '<owner mxid>'` required, no catalog or connections check, no message) still
exists for the same wait; `card` is the one to use.

Pass the owner's words only through the quoted heredoc above, never inside a quoted `--request`
argument: their text (an apostrophe, a quote) must never become shell. `--line` and `note` text is
yours, not the owner's: plain sentences, no quotes from their message.

| exit | meaning |
|---|---|
| 0 | done: a match, all apps connected, a wait recorded (or `card` found every app connected), a wait claimed, the account verified |
| 1 | a negative answer: no exact match, an app not connected, nothing claimed, `account_changed`, `account_unknown`, `no_such_wait` |
| 2 | a setup problem to relay, never retry: `not_signed_in`, `wrong_account`, `connectors_disabled`, `unknown_app`, `coming_soon`, `too_many_apps`, `not_owner_task`, `invalid_arguments`, `cloud_error` |

`card` and `await` exit 1 with `"reason": "account_changed"` (plus `cloud_user_id`,
`stamp_cloud_user_id`, `base`) when this agent's AG2 Cloud credential is not the account the desktop
started the core's station for: no wait and no card are made. Post no card; Step 4 says what to
tell the owner and where.

`card` prints everything `await` prints plus `mode` (`dm` or `private`), `apps` (each with
`connected`), `all_connected`, and for `mode: dm` a `message` object (`body`, `extra_content`,
`reply_to`, `operation_id`) to pass verbatim to `room.action.execute` / `room.message.send`. It is
`null` for a private card and when no wait was made. `find`, `status` and `card` read the
connections and the catalog through a 30-second cache; `claim`, `verify-account`, the switch
baseline and the waiter always read the cloud.

`--switch` (step 3c) records which connections of the apps are active right now; the wait is ready
only once each app has an active connection that wasn't, so the old account never answers. A switch
wait and a plain wait are never merged. Every wait summary carries `switch: true|false`.

Every command prints one JSON object. A **resumed** entry (`resumed` from `claim` and `await`,
`resumed_waits` from `status`) is a wait from the last 30 minutes whose request is already handled:
`resume_task` names the task that answers it (`null` when an owner message task claimed and answered
it), and `resume_pending: true` means that task hasn't run yet. Only `claimed_by` `connected` or
`claim` answers the request; with `timeout`, `user_changed` or `unverified` that task posts a note
asking the owner to connect or ask again, so the same request asked again is a fresh one. When a
resume task answers, close your own task with `[no-send]`, never `[deduped: task-connect-...]`: a
resume task's result is itself `[no-send]`, so the gateway would read the dedup as unanswered and
re-ask your task.

## Step 0: who gets a card

A card and a wait only when **all** of these hold for the task:

- `access_tier: owner`, and no `collaborator: true` header;
- `source: ag2space` (a message in AG2 Space; its room is `channel_id` / `source_room_id`).

From sonichi/sutando, MIT.

More from sonichi/sutando