add-imessage skill

Add iMessage

NanoClaw talks to iMessage through a single imessage channel with two pluggable backends:

reading this Mac's signed-in iMessage account (chat.db). macOS only; the Node binary needs Full Disk Access.

• Local (this Mac) — the Chat SDK bridge over chat-adapter-imessage,

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.

• Hosted iMessage (via photon.codes) — a native adapter over Photon's

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.

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 format — + followed by country code and number, no spaces or dashes (e.g. +14155551234).

Tell the user what's about to happen:

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 registers your number and prints the iMessage line Photon assigned to it. Send one message from your phone to that line — a number only enters routing after it has texted its line once.
4. Once the opt-in lands, setup finishes on its own and confirms your agent's iMessage number.

Run the device-login flow. It provisions the project, reuses its current secret (regenerating only when the API returns none), registers your number, prints the line to text and waits until that message opts the number in, and surfaces the iMessage number you'll use — writing PHOTONPROJECTID + PHOTONPROJECTSECRET to .env and the assigned number to data/photon-auth.json:

pnpm exec tsx scripts/photon-setup.ts setup --phone {{owner_handle}} --embedded

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.

Then select the hosted backend in .env — the Photon credentials already imply hosted, but the explicit selector avoids ambiguity if local keys linger:

bash setup/channels/imessage-configure.sh hosted

Restart

Restart the service so it loads the iMessage adapter and the backend config you just wrote, and wait for its CLI socket before wiring:

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