/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. Its `chat.db` reader (`@photon-ai/imessage-kit`) brings its own `better-sqlite3` 12.x, which ships no prebuilt binary, and NanoClaw doesn't run dependency build scripts, so that copy can't open the database. First point the reader at NanoClaw's own prebuilt `better-sqlite3` (`$better-sqlite3` is pnpm's reference to the version NanoClaw pins). The reinstall applies it to an install that already has the adapter, since the step below skips a package that is already present:

pnpm pkg set 'pnpm.overrides[@photon-ai/imessage-kit>better-sqlite3]=$better-sqlite3'
pnpm install --no-frozen-lockfile

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

For the local backend, check that the `chat.db` reader's `better-sqlite3` loads under Node. It fails with `Could not locate the bindings file` when that copy has no binary, meaning step 4's override didn't land: re-run that override step, then this check:

node --input-type=module -e 'import { createRequire } from "node:module"; const kit = createRequire(import.meta.resolve("chat-adapter-imessage")).resolve("@photon-ai/imessage-kit"); const Database = createRequire(kit)("better-sqlite3"); new Database(":memory:").close();'

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. Ha