agent-messenger 2.27.2 → 2.29.0

package/skills/agent-imessage/references/authentication.md

@@ -0,0 +1,66 @@
+# Authentication
+
+iMessage authentication is unlike the other platforms: there are **no tokens, cookies, or login flow**. `agent-imessage` drives the local [imsg](https://github.com/openclaw/imsg) tool, which relies on **macOS permissions** (Full Disk Access + Automation) granted to the process that launches it. "Authentication" here means: imsg is installed, Messages.app is signed into your Apple ID, and the permissions are granted.
+
+## What gets stored
+
+The credential manager stores an **account record with no secrets** in `~/.config/agent-messenger/imessage-credentials.json` (mode `0600`):
+
+```jsonc
+{
+  "current": "default",
+  "accounts": {
+    "default": {
+      "account_id": "default",
+      "provider": "imsg",          // backend-agnostic discriminator
+      "binary_path": "/opt/homebrew/bin/imsg",  // optional; defaults to "imsg" on PATH
+      "region": "US",               // optional; default region for local-format phone numbers
+      "created_at": "…",
+      "updated_at": "…"
+    }
+  }
+}
+```
+
+There is no password/token field — access is governed entirely by macOS TCC permissions.
+
+## Configuring an account
+
+Guided:
+```bash
+agent-imessage setup            # verifies imsg + permissions (honors --bin/--region), then saves
+```
+
+Scriptable:
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --current
+agent-imessage auth status      # via: agent-imessage doctor
+agent-imessage auth list
+agent-imessage auth use <account-id>
+agent-imessage auth remove <account-id>
+agent-imessage auth logout      # clears all stored accounts
+```
+
+## Credential resolution order
+
+When a command runs, the active configuration is resolved as:
+
+1. `--account <id>` (explicit account selection), then
+2. `AGENT_IMESSAGE_BIN` / `AGENT_IMESSAGE_REGION` environment variables (runtime override — **never persisted to disk**), then
+3. the stored **current** account, then
+4. defaults (`imsg` on PATH, no region).
+
+If nothing resolves, commands exit with `{ "code": "not_authenticated" }` and point to `agent-imessage setup`.
+
+## Permissions (the real "auth")
+
+imsg needs two macOS permissions, granted to the **parent process** (the terminal / agent runtime that launches `agent-messenger`), not to `imsg` in isolation:
+
+- **Full Disk Access** — to read `~/Library/Messages/chat.db`. Missing → `{ "code": "full_disk_access" }`.
+- **Automation → Messages** — to send. Missing → `{ "code": "automation_denied" }`.
+
+These are user-consent TCC grants and **cannot be scripted**. See [permissions](permissions.md) for the exact steps and the parent-process caveat. Run `agent-imessage doctor` to check status.
+
+## Multi-account
+
+Each account is an imsg configuration (binary path + default region). Messages.app has no from-selector, so **send is single-account per Mac**; multiple accounts are only meaningful if you run distinct imsg setups.

package/skills/agent-imessage/references/permissions.md

@@ -0,0 +1,31 @@
+# macOS Permissions for imsg
+
+`agent-imessage` drives [imsg](https://github.com/openclaw/imsg), which needs two macOS permissions. These are TCC (Transparency, Consent, and Control) grants that **cannot be scripted** — a human must approve them once in System Settings.
+
+## Full Disk Access (required for everything)
+
+imsg reads the Messages database at `~/Library/Messages/chat.db`, which macOS protects behind Full Disk Access.
+
+- **Grant to:** the app/terminal/agent-runtime that launches `agent-messenger` — **the parent process**, not `imsg` alone.
+- **Where:** System Settings → Privacy & Security → Full Disk Access → enable your terminal/app → restart it.
+- **Symptom when missing:** `agent-imessage doctor` reports `full_disk_access: denied`; commands return `{ "code": "full_disk_access" }`.
+
+## Automation → Messages (required to send)
+
+Sending uses AppleScript automation of Messages.app.
+
+- **Grant to:** same parent process.
+- **Where:** System Settings → Privacy & Security → Automation → (your app) → enable **Messages**. macOS prompts automatically on the first send attempt.
+- **Symptom when missing:** sends fail with `{ "code": "automation_denied" }`.
+
+## Contacts (optional)
+
+Used only to resolve sender names. Nothing breaks without it; `from_name` is simply absent.
+
+## Why these can't be automated
+
+TCC grants are deliberately user-consent-only. `tccutil` can reset permissions but cannot grant them, and the TCC database is protected by SIP. There is no supported way to grant Full Disk Access or Automation programmatically on an unmanaged Mac — plan for a one-time manual approval (a quick Screen Sharing/VNC session works for a headless Mac).
+
+## SIP and the advanced bridge
+
+Core features (send/read/watch/standard tapbacks) need **no SIP changes**. Only the advanced bridge (`imsg launch`: typing, edit/unsend, group management, targeted/custom reactions) requires **disabling SIP**, which is a separate, deliberate step and out of scope for the core `agent-imessage` features.

package/skills/agent-imessage/references/setup.md

@@ -0,0 +1,49 @@
+# imsg Setup (Operator Guide)
+
+iMessage has no public API. `agent-imessage` runs **on a Mac** and uses [imsg](https://github.com/openclaw/imsg) — a native Swift CLI — to read the local Messages database and send through Messages.app. The agent must run on the same Mac (imsg is local-only; there is no network/server).
+
+## Requirements
+
+- **macOS 14+** (Sonoma or newer). imsg supports macOS 26/Tahoe with caveats (group sends via AppleScript can fail; imsg reports the failure honestly rather than lying).
+- **Messages.app signed in** to your Apple ID. A **dedicated Apple ID** is recommended to avoid mixing automated traffic with your personal account.
+- **imsg installed**: `brew install steipete/tap/imsg`.
+- **Full Disk Access** and **Automation → Messages** permissions (see below).
+
+## One-time setup
+
+1. **Install imsg**
+   ```bash
+   brew install steipete/tap/imsg
+   imsg --version
+   ```
+2. **Sign Messages.app into iMessage** with your (dedicated) Apple ID.
+3. **Grant Full Disk Access** — System Settings → Privacy & Security → Full Disk Access → add the app/terminal that will launch `agent-messenger`. This is required to read `~/Library/Messages/chat.db`.
+4. **Grant Automation → Messages** — triggered on first send; approve the prompt (System Settings → Privacy & Security → Automation → Messages).
+5. **Verify and save an account**
+   ```bash
+   agent-imessage setup      # guided: checks imsg + permissions, saves account
+   agent-imessage doctor     # re-check anytime
+   ```
+
+### The parent-process permission caveat (important)
+
+macOS grants Full Disk Access and Automation to the **process that launches imsg** — i.e. the terminal, IDE, or agent runtime that runs `agent-imessage`, not `imsg` in isolation. If `doctor` reports `full_disk_access: denied`, grant Full Disk Access to **that launching app** and restart it.
+
+## Feature tiers
+
+- **Core (no SIP):** list/search chats, read history, send text, watch new messages, standard tapbacks (to the most recent incoming message). This is all that `agent-imessage` v1 uses.
+- **Bridge (advanced):** typing indicators, read receipts, edit/unsend, group create/rename/members, and reacting to a *specific* message or with custom emoji. These require `imsg launch` (which injects into IMCore) and **disabling SIP**. Not used by v1; documented for completeness.
+
+## Multi-account
+
+Each `agent-imessage` account is an imsg configuration (binary path + default region). Messages.app has no from-selector, so **send is single-account** per Mac. Configure additional accounts only if you run multiple imsg binaries/setups:
+```bash
+agent-imessage auth set --bin /opt/homebrew/bin/imsg --region US --account home --current
+agent-imessage auth use home
+```
+
+## Reliability notes
+
+- The Mac must stay awake and logged in for live `watch` to keep receiving.
+- imsg's watcher uses filesystem events + polling and re-arms across Messages database (WAL) rotation, so it keeps up on busy/iCloud-synced databases.
+- Pin macOS updates if stability matters — major updates can change AppleScript/IMCore behavior.

package/skills/agent-instagram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-instagram
 description: Interact with Instagram DMs - send messages, read conversations, manage accounts
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-instagram:*)
 metadata:
   openclaw:
@@ -27,7 +27,7 @@ Use one of these entrypoints:
 - **Thread ID** = Instagram's identifier for a DM conversation. Numeric string returned by `chat list`.
 - **Browser cookie extraction** = recommended auth method. Extracts cookies from Chromium browsers (Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium) where you're logged into instagram.com. Zero-config.
 - **Username/password auth** = fallback method. Authenticates using Instagram credentials. Supports two-factor authentication via SMS or authenticator app.
-- **HTTP-based** = each command makes HTTP requests and returns. No persistent connection or background process.
+- **HTTP-based** = each CLI command makes HTTP requests and returns. No persistent connection or background process. The SDK additionally offers real-time listeners (`InstagramHybridListener`, `InstagramRealtimeListener`) for streaming DMs — see [SDK: Real-Time Events](#sdk-real-time-events) below.
 - **Multi-account** = multiple Instagram accounts can be stored. Use `auth list` and `auth use` to switch between them.
 - **DM-only** = this CLI focuses on Instagram Direct Messages. It does not manage posts, stories, or followers.
 
@@ -440,3 +440,73 @@ Instagram invalidates sessions based on device fingerprinting and activity patte
 1. Avoid frequent re-authentication
 2. Space out API calls
 3. Don't switch between multiple IP addresses rapidly
+
+## SDK: Real-Time Events
+
+`InstagramHybridListener` connects over Instagram's MQTToT transport (a persistent TLS connection to `edge-mqtt.facebook.com`) and falls back to polling automatically if the connection fails. It retries realtime with capped exponential backoff. This is the recommended listener for most use cases.
+
+`InstagramRealtimeListener` is the pure-realtime option with no polling fallback — use it when you want direct MQTToT and prefer to handle reconnection yourself.
+
+Both use the unofficial private API, the same risk surface as the existing polling listener.
+
+### Setup
+
+```typescript
+import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramHybridListener(client, {
+  pollInterval: 5000,         // fallback poll interval in ms
+  realtimeRetryBaseMs: 2000,  // backoff base for realtime reconnect
+  realtimeRetryMaxMs: 60000,  // backoff cap
+})
+```
+
+Or for pure realtime:
+
+```typescript
+import { InstagramClient, InstagramRealtimeListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramRealtimeListener(client)
+```
+
+### Listening for Events
+
+```typescript
+listener.on('connected', ({ userId, transport }) => {
+  // transport is 'realtime' or 'polling' (hybrid only)
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
+listener.on('message', (msg) => {
+  // msg.id, msg.thread_id, msg.from, msg.timestamp
+  // msg.is_outgoing, msg.type, msg.text, msg.media_url
+  if (msg.is_outgoing) return
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text}`)
+})
+
+listener.on('error', (err) => {
+  console.error(err.message)
+})
+
+listener.on('disconnected', () => {
+  // hybrid listener retries realtime automatically
+})
+```
+
+### Lifecycle
+
+```typescript
+await listener.start()  // connects via MQTToT (or starts polling fallback)
+listener.stop()         // clean shutdown
+```
+
+### Event Types
+
+| Event          | Payload (Hybrid)                                          | Payload (Realtime / Polling) | Description                    |
+| -------------- | --------------------------------------------------------- | ---------------------------- | ------------------------------ |
+| `message`      | `InstagramMessageSummary`                                 | `InstagramMessageSummary`    | New DM received                |
+| `connected`    | `{ userId: string; transport: 'realtime' \| 'polling' }` | `{ userId: string }`         | Listener active                |
+| `disconnected` | —                                                         | —                            | Connection closed              |
+| `error`        | `Error`                                                   | `Error`                      | Connection or API error        |

package/skills/agent-instagram/references/authentication.md

@@ -196,10 +196,21 @@ Session data (cookies and tokens) is stored per account:
 ~/.config/agent-messenger/instagram/<account-id>/
 ```
 
+A device profile (randomized Android device identifiers) is generated once and
+shared across all accounts on this machine, so repeat logins present a
+consistent device fingerprint:
+
+```
+~/.config/agent-messenger/instagram/device.json
+```
+
 ### Security
 
 - Credentials file permissions: `0600` (owner read/write only)
 - Session cookies are stored in plaintext on disk
+- `device.json` holds no secrets — only synthetic device identifiers — but is
+  shared across accounts, so all accounts on this machine share one device
+  fingerprint
 - Keep these files secure. They grant full access to your Instagram account
 - Never commit to version control
 

package/skills/agent-instagram/references/common-patterns.md

@@ -323,6 +323,39 @@ agent-instagram message send-to alice "Hello!"
 agent-instagram message send 12345678901 "Hello!"
 ```
 
+## Pattern 11: Real-Time DM Monitor (SDK)
+
+**Use case**: Receive new DMs as they arrive, without polling
+
+The SDK's `InstagramHybridListener` is the right tool for continuous DM monitoring. It connects over Instagram's MQTToT transport and falls back to polling automatically — no manual loop or `sleep` needed.
+
+```typescript
+import { InstagramClient, InstagramHybridListener } from 'agent-messenger/instagram'
+
+const client = await new InstagramClient().login()
+const listener = new InstagramHybridListener(client)
+
+listener.on('connected', ({ userId, transport }) => {
+  console.log(`Listening as ${userId} via ${transport}`)
+})
+
+listener.on('message', (msg) => {
+  if (msg.is_outgoing) return
+  console.log(`[${msg.thread_id}] ${msg.from}: ${msg.text ?? `[${msg.type}]`}`)
+})
+
+listener.on('error', (err) => {
+  console.error('Listener error:', err.message)
+})
+
+await listener.start()
+// Runs until listener.stop() is called
+```
+
+**When to use**: Any time you need to react to incoming DMs in real time — notifications, bots, monitoring dashboards. Prefer this over a polling shell loop.
+
+**Contrast with shell polling**: The `monitor-chat.sh` template uses `sleep` + `message list` in a loop. That works for simple scripts but makes one HTTP request per interval and can't react faster than the interval. The SDK listener holds a persistent connection and delivers messages as they arrive.
+
 ## Anti-Patterns
 
 ### Don't Poll Too Frequently
@@ -341,6 +374,8 @@ while true; do
 done
 ```
 
+For real-time monitoring, the SDK's `InstagramHybridListener` is a better alternative — it holds a persistent connection and avoids repeated HTTP requests entirely. See [Pattern 11](#pattern-11-real-time-dm-monitor-sdk) above.
+
 ### Don't Spam Threads
 
 ```bash
@@ -360,3 +395,4 @@ agent-instagram message send "$THREAD" "$MESSAGE"
 ## See Also
 
 - [Authentication Guide](authentication.md) - Setting up credentials
+- For real-time events, use the `InstagramHybridListener` SDK (see SKILL.md → SDK: Real-Time Events)

package/skills/agent-instagram/templates/monitor-chat.sh

@@ -12,6 +12,11 @@
 # Example:
 #   ./monitor-chat.sh 340282366841710300949128138443434234567
 #   ./monitor-chat.sh 340282366841710300949128138443434234567 10
+#
+# NOTE: For real-time monitoring, prefer the SDK's InstagramHybridListener over
+# this poll-based approach. It connects over Instagram's MQTToT transport and
+# delivers messages as they arrive, with automatic fallback to polling if needed.
+# See SKILL.md -> SDK: Real-Time Events for setup and usage.
 
 set -euo pipefail
 

package/skills/agent-kakaotalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-kakaotalk
 description: Interact with KakaoTalk - send messages, read chats, manage conversations
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-kakaotalk:*)
 metadata:
   openclaw:

package/skills/agent-line/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-line
 description: Interact with LINE - send messages, read chats, manage conversations
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-line:*)
 metadata:
   openclaw:

package/skills/agent-slack/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slack
 description: Interact with Slack workspaces - send messages, read channels, manage reactions
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-slack:*)
 metadata:
   openclaw:

package/skills/agent-slackbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slackbot
 description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-slackbot:*)
 metadata:
   openclaw:

package/skills/agent-teams/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-teams
 description: Interact with Microsoft Teams - send messages, read channels, manage reactions
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-teams:*)
 metadata:
   openclaw:
@@ -33,11 +33,30 @@ agent-teams channel list <team-id>
 
 ## Authentication
 
-Credentials are extracted automatically from the Teams desktop app (or Chromium browser as fallback) on first use. No manual setup required — just run any command and authentication happens silently in the background.
+Two co-equal ways to sign in — pick whichever fits:
 
-Teams tokens expire in 60-90 minutes. The CLI automatically re-extracts a fresh token when the current one expires, so you don't need to manage token lifecycle manually.
+1. **`agent-teams auth login`** (work/school **or** personal Microsoft accounts) — device-code sign-in. Open the printed URL, enter the code, and approve in your browser. No desktop app or browser extraction needed. It prompts for your Microsoft email (or pass `--email <email>`) and auto-detects work vs personal, then starts the matching flow; pass `--account-type work|personal` to force it and skip detection. Only `auth login` stores the AAD refresh token required by `message search`.
+2. **`agent-teams auth extract`** — zero-config extraction from the Teams desktop app, falling back to a Chromium browser. Best when you're already signed into Teams locally. Yields a Skype token only — sufficient for messaging, but **not** for `message search` (see below).
 
-**IMPORTANT**: Always use `agent-teams auth extract` to obtain tokens. The CLI extracts from the desktop app first, falling back to Chromium browsers if the app isn't installed.
+Credentials are also extracted automatically on first use of any command if none are stored, so `auth extract` can happen silently in the background.
+
+Teams tokens are short-lived (60-90 minutes for extraction, a few hours for device-code). **Device-code accounts (`auth login`) refresh silently** — the CLI re-mints an expired token from the stored refresh token with no re-login needed. Extraction accounts re-extract automatically as long as you're still signed into the Teams desktop app or a supported browser; if that fails, re-run `auth extract` (or switch to `auth login`).
+
+### Non-interactive `auth login` (agents / CI)
+
+When there's no TTY, `auth login` splits into two calls:
+
+```bash
+# 1. Start — returns verification_uri, user_code, and device_code as JSON.
+#    Pass --email to auto-detect the account type (no prompt without a TTY),
+#    or --account-type work|personal to force it.
+agent-teams auth login --email <email>
+
+# 2. After the user approves in a browser, finish with the device_code
+agent-teams auth login --device-code <device_code>
+```
+
+`--client-id <id>` overrides the AAD client ID on either call (or set `AGENT_TEAMS_CLIENT_ID`). `--account-type <work|personal>` selects the account (default `work`); it is preserved across the two-call flow, so pass it to both calls when signing in to a personal account non-interactively.
 
 ### Multi-Team Support
 
@@ -145,6 +164,10 @@ If a memorized ID returns an error (channel not found, team not found), remove i
 ### Auth Commands
 
 ```bash
+# Sign in via device code (personal Microsoft accounts).
+agent-teams auth login
+agent-teams auth login --device-code <code>   # finish a non-interactive login
+
 # Extract token from Teams desktop app or browser (usually automatic)
 agent-teams auth extract
 agent-teams auth extract --debug
@@ -191,8 +214,14 @@ agent-teams message get <team-id> <channel-id> <message-id>
 
 # Delete a message
 agent-teams message delete <team-id> <channel-id> <message-id> --force
+
+# Search messages across Teams (requires `auth login` — see Authentication)
+agent-teams message search <query>
+agent-teams message search "deploy" --limit 10 --from 0
 ```
 
+`message search` requires an `auth login` account: it queries Microsoft's Substrate search API with an AAD token that `auth extract` (cookie-based) cannot provide. Cookie-only accounts get a clear error telling you to run `auth login`. `--limit` is a positive integer (default 20); `--from` is a non-negative offset for pagination (default 0).
+
 ### Channel Commands
 
 ```bash
@@ -279,8 +308,15 @@ agent-teams file list <team-id> <channel-id>
 
 # Get file info
 agent-teams file info <team-id> <channel-id> <file-id>
+
+# Download a file (to a path or directory; defaults to the current dir)
+agent-teams file download <team-id> <channel-id> <file-id>
+agent-teams file download <team-id> <channel-id> <file-id> ./report.pdf
+agent-teams file download <team-id> <channel-id> <file-id> ./downloads/ --pretty
 ```
 
+`file download` output: `{ "id", "name", "size", "content_type", "path" }` where `path` is where the file was written. Inline/image attachments download with the extracted Skype token and work for any signed-in account; SharePoint/OneDrive documents download via Microsoft Graph and require an `auth login` account (cookie-only `auth extract` accounts get a clear error telling you to run `auth login`).
+
 ### Snapshot Command
 
 Get team overview for AI agents (brief by default):
@@ -427,13 +463,30 @@ await client.addReaction(teams[0].id, channels[0].id, msg.id, 'like')
 await client.uploadFile(teams[0].id, channels[0].id, './report.pdf')
 ```
 
+### Real-time Events
+
+Stream Teams chat messages in real time over the internal trouter WebSocket — as a user, no bot and no public endpoint. Requires the Teams desktop app to be logged in.
+
+```typescript
+import { TeamsClient, TeamsListener } from 'agent-messenger/teams'
+
+const client = await new TeamsClient().login()
+const listener = new TeamsListener(client)
+
+listener.on('message', (message) => {
+  console.log(`New message in ${message.chatId}: ${message.content}`)
+})
+
+await listener.start()
+```
+
 ### Full API Reference
 
 See the [Teams SDK documentation](https://agent-messenger.dev/docs/sdk/teams) for complete method signatures, types, schemas, and examples.
 
 ## Limitations
 
-- No real-time events / WebSocket connection
+- Real-time events are SDK-only (`TeamsListener`); the CLI has no `watch` command
 - No voice/video channel support
 - No team management (create/delete channels, roles)
 - Personal accounts: chats only (no teams/channels); use the `chat` commands
@@ -441,7 +494,7 @@ See the [Teams SDK documentation](https://agent-messenger.dev/docs/sdk/teams) fo
 - No webhook support
 - Plain text messages only (no adaptive cards in v1)
 - User tokens only (no app tokens)
-- **Token expires in 60-90 minutes** - auto-refreshed, but requires Teams desktop app or browser to be logged in
+- **Tokens are short-lived** - device-code (`auth login`) accounts refresh silently from the stored refresh token; extraction accounts auto-refresh but need the Teams desktop app or browser to still be logged in
 
 ## Troubleshooting
 

package/skills/agent-teams/references/authentication.md

@@ -95,10 +95,21 @@ The tool searches within:
 
 ### What Gets Extracted
 
-- **skypetoken_asm**: Authentication token for Teams API
+- **skypetoken_asm**: Authentication token for Teams API (sent as the `X-Skypetoken` header)
 - **teams**: All teams you're a member of
 - **token_extracted_at**: Timestamp for expiry tracking
 
+### Real-time Auth (`authtoken` / id_token)
+
+The real-time `TeamsListener` (SDK) additionally needs an OAuth Bearer token to
+authenticate its trouter WebSocket connection. This is **not** persisted with
+your credentials — the client extracts it on demand from the Teams `authtoken`
+cookie (a JWE, stored URL-encoded with a `Bearer=` prefix), decrypted with the
+same keychain machinery as `skypetoken_asm`. The listener re-extracts it on
+every (re)connection, so it always uses the current cookie value. Because it is
+read live from the desktop app's cookie store, the Teams desktop app must be
+logged in for real-time streaming to work.
+
 ## Multi-Team Management
 
 ### List Teams
@@ -181,6 +192,25 @@ Credentials are stored in:
 - Keep this file secure - it grants access to your Teams account
 - **Tokens auto-expire in 60-90 minutes** - provides some security
 
+## AAD Tokens (required for `message search`)
+
+Most commands use only the Skype token above. **`message search` is different**: it queries Microsoft's Substrate search API, which requires an AAD Bearer token for the `substrate.office.com` audience — a token the Skype cookie cannot produce.
+
+- **Only `auth login` (device-code) can mint it.** That flow stores an `aad_refresh_token` (and `aad_client_id`) alongside the Skype token. `auth extract` (cookie extraction) yields a Skype token only and therefore **cannot** run `message search` — the CLI returns an actionable error telling you to run `auth login`.
+- **Work and personal accounts** are both supported by `auth login`. It detects the account type from your Microsoft email (prompted interactively, or via `--email <email>`) and starts the matching flow; `--account-type work|personal` forces it and skips detection. If a personal account still reaches the work flow, the CLI stops with an actionable hint to rerun with `--account-type personal`.
+- At search time, the CLI silently exchanges the stored refresh token for a short-lived Substrate access token (per-scope AAD grant), caches it in memory only (never written to disk), and rotates the refresh token. The same mechanism can mint a Graph token for other AAD-gated features.
+
+Credentials for an `auth login` account therefore include additional fields:
+
+```json
+{
+  "account_type": "work",
+  "auth_method": "device-code",
+  "aad_refresh_token": "0.AXoA...redacted...",
+  "aad_client_id": "5e3ce6c0-2b1f-4285-8d4b-75ee78787346"
+}
+```
+
 ## Authentication Status
 
 Check if you're authenticated:

package/skills/agent-telegram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegram
 description: Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-telegram:*)
 ---
 

package/skills/agent-telegrambot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegrambot
 description: Interact with Telegram using bot tokens - send messages, read chats, manage reactions
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-telegrambot:*)
 metadata:
   openclaw:

package/skills/agent-webex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webex
 description: Interact with Cisco Webex - send messages, read spaces, manage memberships
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-webex:*)
 metadata:
   openclaw:

package/skills/agent-webexbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webexbot
 description: Interact with Cisco Webex using bot tokens - send messages, reply in threads, upload and download files, look up people, read spaces, manage memberships, stream real-time events
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-webexbot:*)
 metadata:
   openclaw:

package/skills/agent-wechatbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-wechatbot
 description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-wechatbot:*)
 metadata:
   openclaw:

package/skills/agent-whatsapp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsapp
 description: Interact with WhatsApp - send messages, read chats, manage conversations
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-whatsapp:*)
 metadata:
   openclaw:

package/skills/agent-whatsappbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsappbot
 description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
-version: 2.27.2
+version: 2.29.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:

package/src/cli.ts

@@ -68,6 +68,10 @@ program.command('channeltalk', 'Interact with Channel Talk', {
   executableFile: join(__dirname, 'platforms', 'channeltalk', `cli${ext}`),
 })
 
+program.command('imessage', 'Interact with iMessage via imsg (local, on-Mac)', {
+  executableFile: join(__dirname, 'platforms', 'imessage', `cli${ext}`),
+})
+
 program.command('channeltalkbot', 'Interact with Channel Talk using API credentials', {
   executableFile: join(__dirname, 'platforms', 'channeltalkbot', `cli${ext}`),
 })