add-imessage · diff
git:20260713.26abae5 to git:20260801.905ce15
205 added, 107 removed. Audit A to A.
---
name: add-imessage
- description: Add iMessage channel integration via Chat SDK. Local (macOS) or remote (Photon API) mode.
+ description: Add iMessage to NanoClaw — one channel, two backends. Local (this Mac's chat.db via the Chat SDK bridge; macOS + Full Disk Access) or Hosted iMessage (via photon.codes — native spectrum-ts with a device-login wizard; any OS, no Mac relay). Triggers on "add imessage", "connect imessage", "add photon", "imessage via photon", "native imessage".
---
- # Add iMessage Channel
+ # Add iMessage
- Adds iMessage support via the Chat SDK bridge. Two modes: local (macOS with Full
- Disk Access) or remote (Photon API). NanoClaw doesn't ship channels in trunk —
- this skill copies the iMessage adapter in from the `channels` branch.
+ NanoClaw talks to iMessage through a single **`imessage`** channel with two
+ pluggable backends:
+ - **Local (this Mac)** — the Chat SDK bridge over `chat-adapter-imessage`,
+ reading this Mac's signed-in iMessage account (`chat.db`). macOS only; the
+ Node binary needs Full Disk Access.
+ - **Hosted iMessage (via photon.codes)** — a native adapter over Photon's
+ `spectrum-ts` gRPC stream. The hosted service owns the iMessage line, so
+ there's no Mac relay, webhook, or public URL. Works on any OS, and a
+ device-login flow provisions everything for you.
+
+ Both register the same `imessage` channel type; only one runs per install.
+ NanoClaw doesn't ship channels in trunk — this skill copies the unified
+ `imessage` adapter in from the `channels` branch. Full reference:
+ [docs/imessage.md](docs.md).
+
The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads
the prose and applies them, and a parser can apply them deterministically from
the same document. Every directive is idempotent, so the whole skill is safe to
re-run; anything a parser can't apply falls back to the prose beside it.
## Apply
- ### 1. Copy the adapter
+ ### 1. Choose a backend
- Fetch the `channels` branch and copy the iMessage adapter into `src/channels/`
- (overwrite — the branch is canonical):
+ Pick the backend first — it decides which package gets installed and which
+ walkthrough runs below (the other backend's steps are skipped):
+ ```nc:prompt backend validate:^(local|hosted)$
+ How should iMessage run — `local` (this Mac's signed-in iMessage account; macOS only, needs Full Disk Access) or `hosted` (a managed line via photon.codes; works on any OS)?
+ ```
+
+ The local backend only works on a Mac — it reads this machine's iMessage
+ `chat.db` directly, and there is no such database off macOS. On any other OS,
+ stop here and choose `hosted` instead; otherwise you'd write a local config
+ that can never receive a message:
+
+ ```nc:run effect:check when:backend=local
+ [ "$(uname)" = Darwin ]
+ ```
+
+ ### 2. Copy the adapter
+
+ Fetch the `channels` branch and copy the unified iMessage adapter and its tests
+ into `src/channels/`:
+
```nc:copy from-branch:channels
src/channels/imessage.ts
+ src/channels/imessage.test.ts
src/channels/imessage-registration.test.ts
```
- ### 2. Register the adapter
+ ### 3. Register the adapter
Append the self-registration import to the channel barrel (skipped if the line
is already present). This one line is the skill's only reach-in into core:
```nc:append to:src/channels/index.ts
import './imessage.js';
```
- ### 3. Install the adapter package
+ ### 4. Install the chosen backend's package
- Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:
+ Pinned to an exact version — the supply-chain policy rejects ranges and
+ `latest`. Install only the chosen backend's package.
- ```nc:dep
+ **Local** — the Chat SDK iMessage adapter:
+
+ ```nc:dep when:backend=local
chat-adapter-imessage@0.1.1
```
- ### 4. Build and validate
+ **Hosted** — Photon's Spectrum SDK:
- Build guards the typed `createChatSdkBridge(...)` core call and proves the
- dependency is installed (the adapter's top-level `import` from
- `chat-adapter-imessage` throws if it isn't):
+ ```nc:dep when:backend=hosted
+ spectrum-ts@11.0.0
+ ```
+ > Pin exactly. `spectrum-ts` ships breaking majors (v11 is what the adapter
+ > targets); don't `@latest`. NanoClaw's pnpm gate (`minimumReleaseAge`) requires
+ > a version ≥3 days old — both pins clear it. A fresher pin needs human sign-off
+ > before a `minimumReleaseAgeExclude` entry (CLAUDE.md → Supply Chain Security).
+
+ ### 5. Build and validate
+
+ Build guards the typed `createChatSdkBridge(...)` core call used by the local
+ backend, and the registration test proves the channel is wired:
+
```nc:run effect:build
pnpm run build
```
```nc:run effect:test
pnpm exec vitest run src/channels/imessage-registration.test.ts
```
- `imessage-registration.test.ts` imports the real channel barrel and asserts the
- registry contains `imessage` — it goes red if the import line is deleted or
- drifts, if the barrel fails to evaluate, or if `chat-adapter-imessage` isn't
- installed (the import throws), so it also covers the dependency from step 3.
-
- End-to-end message delivery against a real iMessage account is verified manually
- once the service is running — see Next Steps.
-
- ## Credentials
-
- iMessage runs in one of two modes:
-
- - **Local (macOS)** — the bot runs on this Mac and talks via the signed-in
- iMessage account. Reading `chat.db` needs Full Disk Access granted to the
- Node binary the host runs under.
- - **Remote (Photon API)** — the bot talks to a separate Photon server that owns
- an iMessage account on another Mac. Use this off macOS, or to keep this Mac's
- chat history out of the loop.
+ Both must be clean. `imessage-registration.test.ts` imports the real channel
+ barrel and asserts the registry contains `imessage` — it goes red if the
+ `import './imessage.js';` line is missing or the barrel fails to evaluate. The
+ adapter loads neither backend's SDK at import (hosted `spectrum-ts` only in
+ `setup()`, local `chat-adapter-imessage` only in the factory), so the test
+ needs no package.
- Mode choice and the Full Disk Access / Photon walkthroughs are human and
- interactive. Pick the mode first (local is the macOS default; remote is the only
- option off macOS), then walk only that mode's setup — the other mode's steps are
- skipped:
+ For the hosted backend, also run the full adapter suite — it includes an
+ integration block that exercises the real installed `spectrum-ts` (version,
+ exports, builders) and auto-skips when the package is absent:
- ```nc:prompt mode validate:^(local|remote)$
- How should iMessage run — `local` (this Mac, needs Full Disk Access) or `remote` (a Photon server)?
+ ```nc:run effect:test when:backend=hosted
+ pnpm exec vitest run src/channels/imessage.test.ts
```
- ### Local Mode (macOS)
-
- Requirements: macOS, with Full Disk Access granted to the Node binary. Without
- it the adapter can't read `chat.db` and inbound messages never arrive.
-
- Local mode only works on a Mac — it reads this machine's iMessage `chat.db`
- directly, and there is no such database off macOS. On any other OS, stop here and
- use remote (Photon) mode instead; otherwise you'd write a local config that can
- never receive a message:
-
- ```nc:run effect:check when:mode=local
- [ "$(uname)" = Darwin ]
- ```
+ ## Local backend: Full Disk Access (macOS)
- The Node binary path is buried deep (e.g. `~/.nvm/versions/node/v22.x.x/bin/node`),
- so open its folder in Finder to make the drag-and-drop target obvious. Harmless
- off a desktop (SSH/headless) — it just no-ops:
+ The adapter reads this Mac's `chat.db`, which requires Full Disk Access granted
+ to the Node binary the host runs under. The Node path is buried deep (e.g.
+ `~/.nvm/versions/node/v22.x.x/bin/node`), so open its folder in Finder to make
+ the drag-and-drop target obvious. Harmless off a desktop (SSH/headless) — it
+ just no-ops:
- ```nc:run effect:external when:mode=local
+ ```nc:run effect:external when:backend=local
open "$(dirname "$(which node)")" 2>/dev/null || true
```
Then tell the user:
- ```nc:operator when:mode=local
+ ```nc:operator when:backend=local
Grant Full Disk Access to Node so iMessage can read your chat history:
1. Open System Settings > Privacy & Security > Full Disk Access.
2. Click +, then drag the "node" file from the Finder window that just opened.
3. Toggle it on, then come back here.
```
Stop and wait for the user to confirm Full Disk Access is granted before
continuing.
- ### Remote Mode (Photon API)
-
- Photon is a separate service that owns an iMessage account and exposes it over
- HTTP; NanoClaw talks to it via its API. Tell the user:
+ Now select the local backend in `.env`. The configure script owns this
+ upsert-and-remove (a plain set-if-absent env write can neither replace a stale
+ value nor delete a key, and a lingering hosted selector would shadow the
+ choice):
- ```nc:operator when:mode=remote
- Set up remote iMessage via Photon:
- 1. Create a Photon server: https://photon.codes
- 2. Copy the server URL and API key from your Photon dashboard.
+ ```nc:run effect:external when:backend=local
+ bash setup/channels/imessage-configure.sh local
```
- Then collect the two values:
+ ## Hosted backend: device login (via photon.codes)
- ```nc:prompt server_url when:mode=remote validate:^https?:// flags:i reuse:IMESSAGE_SERVER_URL
- Your Photon server URL — starts with http:// or https:// (e.g. https://photon.example.com).
- ```
- ```nc:prompt api_key secret when:mode=remote reuse:IMESSAGE_API_KEY
- Your Photon API key — from the Photon dashboard.
+ The provisioning flow needs the phone number you send iMessages from — it
+ registers that number with your project so the hosted line recognises you:
+
+ ```nc:prompt owner_handle normalize:trim validate:^\+\d{8,15}$ when:backend=hosted
+ The phone number you iMessage from, in E.164 format — + followed by country code and number, no spaces or dashes (e.g. +14155551234).
```
- ### Configure environment
+ Tell the user what's about to happen:
- The two modes use different `.env` keys. Write only the keys for the chosen
- mode, and strip the opposite mode's keys so a stale value can't confuse the
- adapter's factory. The configure script owns this upsert-and-remove (a plain
- set-if-absent env write can neither replace a stale value nor delete a key):
+ ```nc:operator when:backend=hosted
+ Connect your hosted iMessage line (photon.codes):
+ 1. A login URL and a short code will print below.
+ 2. Open the URL in a browser, approve the device, and enter the code.
+ 3. Setup then asks for one dashboard step: add your number as a user in the Photon dashboard and accept the invite that arrives on your phone. Numbers only receive messages after that invite.
+ 4. Once the opt-in lands, setup finishes on its own and prints your agent's iMessage number.
+ ```
- **Local mode** — writes `IMESSAGE_LOCAL=true` and `IMESSAGE_ENABLED=true`, and
- removes `IMESSAGE_SERVER_URL` / `IMESSAGE_API_KEY` if present:
+ Run the device-login flow. It provisions the project, reuses its current secret
+ (regenerating only when the API returns none), walks you through the dashboard
+ Add-user + invite step (waiting until your number is opted in), and surfaces
+ the iMessage number you'll text — writing
+ `PHOTON_PROJECT_ID` + `PHOTON_PROJECT_SECRET` to `.env` and the assigned number
+ to `data/photon-auth.json`:
- ```nc:run effect:external when:mode=local
- bash setup/channels/imessage-configure.sh local
+ ```nc:run effect:step when:backend=hosted
+ pnpm exec tsx scripts/photon-setup.ts setup --phone {{owner_handle}} --embedded
```
- **Remote mode** — writes `IMESSAGE_LOCAL=false`, `IMESSAGE_SERVER_URL`, and
- `IMESSAGE_API_KEY`, and removes `IMESSAGE_ENABLED` if present:
+ If the login times out, the code expired (~30 min) — re-run the step; a stored
+ token is reused. Check state any time with
+ `pnpm exec tsx scripts/photon-setup.ts status`.
- ```nc:run effect:external when:mode=remote
- bash setup/channels/imessage-configure.sh remote "{{server_url}}" "{{api_key}}"
+ Then select the hosted backend in `.env` — the Photon credentials already imply
+ hosted, but the explicit selector avoids ambiguity if local keys linger:
+
+ ```nc:run effect:external when:backend=hosted
+ bash setup/channels/imessage-configure.sh hosted
```
## Restart
- Restart the service so it loads the iMessage adapter and the credentials you
- just stored, and wait for its CLI socket before wiring:
+ Restart the service so it loads the iMessage adapter and the backend config you
+ just wrote, and wait for its CLI socket before wiring:
```nc:run effect:restart
bash setup/lib/restart.sh
```
+ For the hosted backend, confirm the connection came up:
+ `grep "Photon channel connected" logs/nanoclaw.log | tail -1`.
+
## Resolve your iMessage handle
- The agent greets you in the iMessage conversation tied to the phone number or
- Apple ID email you message from — that handle is both your identity and the
- conversation address. Resolve it so the owner-wiring step can target it.
+ The agent greets you in the iMessage conversation tied to the handle you
+ message from — that handle is both your identity and the conversation address.
+ The hosted flow already collected it above; for the local backend, resolve it
+ now (email works too — whatever iMessage recognises):
- ```nc:prompt owner_handle validate:^(\+\d{8,15}|[^\s@]+@[^\s@]+\.[^\s@]+)$
+ ```nc:prompt owner_handle validate:^(\+\d{8,15}|[^\s@]+@[^\s@]+\.[^\s@]+)$ when:backend=local
The phone number or email you iMessage from — a +E.164 number (e.g. +14155551234) or an email / Apple ID (e.g. you@icloud.com).
```
- iMessage is a native adapter: it sends the raw handle as the conversation
+ **Hosted first contact:** text your agent's iMessage number once (it was
+ printed above; also stored in `data/photon-auth.json`) before expecting any
+ message from it. This first text is required, not just convenient — the hosted
+ line can only message numbers that have already texted it (cold outbound is
+ rejected with `Target not allowed for this project`). Tell the user:
+
+ ```nc:operator when:backend=hosted
+ Send one text — anything — from your phone to your agent's iMessage number (printed above). The hosted line can only reply to numbers that have texted it first, so its welcome message needs yours to arrive first.
+ ```
+
+ iMessage is a native channel: it sends the raw handle as the conversation
address, with no channel prefix — so the messaging-group platform id is that
- handle as-is.
+ handle as-is:
```nc:run capture:platform_id
echo "{{owner_handle}}"
```
`owner_handle` and `platform_id` are what the owner-wiring step needs. The
- welcome iMessage goes out through the adapter once the service is running — in
- local mode that needs Full Disk Access granted (above); in remote mode it goes
- via your Photon server.
+ welcome iMessage goes out through the adapter once the service is running — on
+ the local backend that needs Full Disk Access granted (above); on the hosted
+ backend it goes out via your photon.codes line after your first text.
## Next Steps
- If you're in the middle of `/setup`, return to the setup flow now. Otherwise wire
- this channel with `/init-first-agent` (or `/manage-channels`).
+ If you're in the middle of `/setup`, return to the setup flow now. Otherwise
+ `/init-first-agent` stands up an agent on your iMessage DM, or `/manage-channels`
+ wires it to an existing agent group.
## Channel Info
- - **type**: `imessage`
- - **terminology**: iMessage has "conversations." Each conversation is with a contact identified by phone number or email address. Group chats are also supported.
- - **how-to-find-id**: The platform ID is the contact's phone number (e.g. `+15551234567`) or email address. For group chats, the ID is assigned by iMessage internally.
+ - **type**: `imessage` (one channel; the backend is local or hosted)
+ - **terminology**: iMessage has 1:1 "chats" (DMs) and group chats. Photon
+ (hosted) calls each conversation a "space".
+ - **platform-id-format**: DM = your bare handle (E.164 phone, or email for
+ local) — direct-addressable; the user id is `imessage:<handle>`. Group
+ (hosted) = the opaque Spectrum space id.
+ - **how-to-find-id**: DMs use the counterpart's phone/email. Groups (hosted) are
+ discovered on first message —
+ `pnpm exec tsx scripts/q.ts data/v2.db "SELECT platform_id, name FROM messaging_groups WHERE channel_type='imessage'"`
- **supports-threads**: no
- **typical-use**: Interactive 1:1 chat — personal messaging
- - **default-isolation**: Same agent group if you're the only person messaging the bot across iMessage and other channels. Separate agent group if different contacts should have information isolation.
+ - **default-isolation**: One agent per install. Multiple DMs with the same
+ operator can share an agent group; groups with other people should typically
+ use `isolated` session mode.
+ ### Hosted features
+
+ Markdown (native; `PHOTON_MARKDOWN=false` for plain text), file attachments in
+ and out (inbound staged into the session inbox, capped by
+ `PHOTON_MAX_INLINE_ATTACHMENT_BYTES`, default 20 MB), tapback reactions, read
+ receipts, typing indicators, and `ask_user_question` via `/approve` / `/reject`
+ slash replies. Optional `.env`: `PHOTON_MARKDOWN`, `PHOTON_TELEMETRY`,
+ `PHOTON_MAX_INLINE_ATTACHMENT_BYTES`, `PHOTON_DASHBOARD_HOST`,
+ `PHOTON_SPECTRUM_HOST`. Full table in [docs/imessage.md](docs.md).
+
## Troubleshooting
- **The mode answer is rejected.** It must be exactly `local` or `remote`, lowercase. Local only exists on macOS — it reads this Mac's `chat.db` directly — so on any other OS the platform check stops you and remote (Photon) is the only path.
+ **The backend answer is rejected.** It must be exactly `local` or `hosted`,
+ lowercase. Local only exists on macOS — it reads this Mac's `chat.db` directly —
+ so on any other OS the platform check stops you and hosted is the only path.
- **Local mode: outgoing works but nothing ever arrives.** Full Disk Access wasn't granted to the *actual* Node binary the service runs under — with nvm the path changes per Node version (`~/.nvm/versions/node/v22.x.x/bin/node`), so an old grant silently stops covering a new binary. Re-open System Settings → Privacy & Security → Full Disk Access, add the binary at `$(which node)`, then restart the service.
+ **Local: outgoing works but nothing ever arrives.** Full Disk Access wasn't
+ granted to the *actual* Node binary the service runs under — with nvm the path
+ changes per Node version (`~/.nvm/versions/node/v22.x.x/bin/node`), so an old
+ grant silently stops covering a new binary. Re-open System Settings → Privacy &
+ Security → Full Disk Access, add the binary at `$(which node)`, then restart
+ the service.
- **Remote mode: Photon values rejected or unreachable.** The server URL must start with `http://` or `https://` — copy it and the API key from your Photon dashboard at photon.codes. If the adapter starts but sends fail, curl the server URL from this machine to rule out a network path issue.
+ **`spectrum-ts` not installed** (hosted) — re-run step 4
+ (`pnpm install spectrum-ts@11.0.0`) and restart.
- **Your handle is rejected at the resolve step.** It must be a bare +E.164 number (`+14155551234` — no spaces, dashes, or parentheses) or an email/Apple ID. Use the exact handle you actually send iMessages from — a number-vs-email mismatch means your messages never map to the wired conversation.
+ **Device login times out** (hosted) — the code expires in ~30 min; re-run the
+ login step (a stored token is reused).
- **Adapter installed but silent.** Run `pnpm exec vitest run src/channels/imessage-registration.test.ts` — red means the barrel import or the `chat-adapter-imessage` install drifted, so re-run the Apply steps. If green, restart the service (`bash setup/lib/restart.sh`) so it loads the adapter and the mode config, then check `logs/nanoclaw.error.log`.
+ **`Target not allowed for this project`** (hosted) — intended: the line only
+ messages numbers that have texted it first. Text the agent's number once, then
+ retry (a welcome DM queued before that first text simply fails delivery).
+
+ **Your handle is rejected at the resolve step.** It must be a bare +E.164
+ number (`+14155551234` — no spaces, dashes, or parentheses) or, on the local
+ backend, an email/Apple ID. Use the exact handle you actually send iMessages
+ from — a number-vs-email mismatch means your messages never map to the wired
+ conversation.
+
+ **Adapter installed but silent.** Run
+ `pnpm exec vitest run src/channels/imessage-registration.test.ts` — red means
+ the barrel import or the package install drifted, so re-run the Apply steps.
+ If green, confirm the backend connected (hosted:
+ `grep "Photon channel connected" logs/nanoclaw.log`), restart the service
+ (`bash setup/lib/restart.sh`), then check `logs/nanoclaw.error.log`.
+
+ More in [docs/imessage.md](docs.md).
+
+ ## Upgrading spectrum-ts (hosted)
+
+ `spectrum-ts` is pinned exactly because it ships breaking majors. To upgrade,
+ read the [release notes](https://github.com/photon-hq/spectrum-ts/releases) for
+ every version between the pins, bump the pin, reconcile
+ `src/channels/imessage.ts` against the new typings, then `pnpm run build` and
+ `pnpm exec vitest run src/channels/imessage.test.ts`. See
+ [docs/imessage.md](docs.md).