/add-imessage

name: add-imessage
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

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. Choose a backend

Pick the backend first — it decides which package gets installed and which walkthrough runs below (the other backend's steps are skipped):

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:

[ "$(uname)" = Darwin ]

2. Copy the adapter

Fetch the `channels` branch and copy the unified iMessage adapter and its tests into `src/channels/`:

src/channels/imessage.ts
src/channels/imessage.test.ts
src/channels/imessage-registration.test.ts

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:

import './imessage.js';

4. Install the chosen backend's package

Pinned to an exact version — the supply-chain policy rejects ranges and `latest`. Install only the chosen backend's package.

**Local** — the Chat SDK iMessage adapter:

chat-adapter-imessage@0.1.1

**Hosted** — Photon's Spectrum SDK:

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:

pnpm run build

pnpm exec vitest run src/channels/imessage-registration.test.ts

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.

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:

pnpm exec vitest run src/channels/imessage.test.ts

Local backend: Full Disk Access (macOS)

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:

open "$(dirname "$(which node)")" 2>/dev/null || true

Then tell the user:

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.

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):

bash setup/channels/imessage-configure.sh local

Hosted backend: device login (via photon.codes)

The provisioning flow needs the phone number you send iMessages from — it registers that number with your project so the hosted line recognises you:

The phone number you iMessage from, in E.164 f