openclaw-imessage-photon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# openclaw-imessage-photon
+
+**English** · [中文](README.zh-CN.md)
+
+iMessage channel plugin for [OpenClaw](https://github.com/contaxy/openclaw) via
+**Photon Spectrum Cloud** — no Mac, no iMessage server, no bridge process.
+
+Run iMessage on your VPS/cloud server: your agent talks to iMessage contacts
+directly through Photon's cloud relay, as a native OpenClaw channel plugin
+(runs inside the gateway process — no per-message CLI spawn, no temporary
+agent processes).
+
+## Highlights
+
+- **Native channel plugin** — runs in the OpenClaw gateway process; messages
+  dispatch straight into the embedded agent runtime.
+- **No Mac required** — Photon Spectrum Cloud relays iMessage.
+- **Text, images, voice, polls, effects, contacts** — both directions.
+- **Voice transcription** — plug any `tools.media.audio` STT provider
+  (Deepgram, ElevenLabs, Groq, ...) via ordinary OpenClaw config.
+- **Green-friendly defaults** — DM allowlist, seen-ack reaction, tapbacks,
+  auto-reconnect, read receipts, typing indicators.
+- **Onboarding wizard** — `openclaw onboard` guides through Photon project
+  setup (credentials via `SPECTRUM_PROJECT_ID` / `SPECTRUM_PROJECT_SECRET`,
+  or paste from the dashboard).
+
+## Installation
+
+Requirements: OpenClaw ≥ 2026.7.1, Node 22+.
+
+**Via npm (recommended)** — either ask an AI agent to run it, or:
+
+```bash
+npx -y openclaw-imessage-photon-cli@latest install
+```
+
+Or install the plugin package directly:
+
+```bash
+openclaw plugins install npm:openclaw-imessage-photon
+```
+
+**From source:**
+git clone https://github.com/ethanjtch/openclaw-imessage-photon
+cd openclaw-imessage-photon
+npm install
+npm run build
+openclaw plugins install ./imessage-photon
+openclaw gateway restart
+```
+
+Then configure the channel (run `openclaw onboard`, pick **iMessage (Photon)**)
+or edit `openclaw.json` directly:
+
+```json5
+{
+  channels: {
+    "imessage-photon": {
+      enabled: true,
+      projectId: "...",       // or env SPECTRUM_PROJECT_ID
+      projectSecret: "...",   // or env SPECTRUM_PROJECT_SECRET
+      allowFrom: ["+8613800138000"], // DM allowlist (E.164). [] = open
+    },
+  },
+}
+```
+
+Register at [photon.codes](https://photon.codes), create a project with the
+iMessage provider, and copy the Project ID / Secret.
+
+## Configuration
+
+| Key | Default | Description |
+|---|---|---|
+| `projectId` / `projectSecret` | env `SPECTRUM_PROJECT_ID` / `SPECTRUM_PROJECT_SECRET` | Photon project credentials |
+| `allowFrom` | `[]` (open) | DM allowlist, E.164 numbers |
+| `ackReaction` | `👀` | Seen/processing reaction on inbound text; removed after reply. `""` disables |
+| `tapbackNotifications` | `all` | `all` forward tapbacks to agent; `off` ignores them |
+| `enableMedia` | `false` | Agent can send/receive media attachments |
+| `enablePoll` | `false` | Agent can create polls |
+| `enableEffects` | `false` | Full-screen effects (confetti, lasers, ...) |
+| `enableContact` | `false` | Agent can share contacts |
+| `enableVoice` | `false` | Agent can send voice (via media + audio content type) |
+| `enableGroups` | `false` | Handle group chats |
+| `enableTyping` | `false` | Typing indicator while processing |
+| `enableReadReceipts` | `false` | Mark inbound as read |
+
+### Voice transcription
+
+Configure any OpenClaw media-audio STT provider, e.g. Deepgram:
+
+```json5
+{
+  tools: { media: { audio: { models: [{ provider: "deepgram", model: "nova-3", language: "zh" }] } } },
+}
+```
+
+Requires the provider's env key (e.g. `DEEPGRAM_API_KEY`) in the gateway
+environment. Inbound voice is saved to the media store and transcribed by the
+core media pipeline; the agent then sees the transcript.
+
+## Capability matrix
+
+| iMessage capability | This plugin | [Mouxy/openclaw-photon](https://github.com/Mouxy/openclaw-photon) |
+|---|---|---|
+| Text / reply / active send | ✅ | ✅ |
+| Media (images/files, both ways) | ✅ (`enableMedia`) | ✅ |
+| Voice send + inbound transcription | ✅ (`enableVoice` + `tools.media.audio`) | ✅ |
+| Polls (create) | ✅ (`enablePoll`) | ✅ |
+| Poll vote events | ⚠️ blocked by upstream spectrum-ts bug | ✅ |
+| Full-screen effects | ✅ (`enableEffects`) | ✅ |
+| Contacts | ✅ (`enableContact`) | ✅ |
+| Group chats | ✅ (`enableGroups`, no mention gating) | ✅ |
+| Tapbacks (inbound) | ✅ | ✅ |
+| Seen-ack reaction | ✅ (👀) | — |
+| Typing indicators | ✅ (`enableTyping`) | ✅ |
+| Read receipts | ✅ (`enableReadReceipts`) | ✅ |
+| Stickers / text animations | ❌ | ✅ (needs `@photon-ai/advanced-imessage`) |
+| Mini-app / status cards | ❌ (business-account only) | ✅ |
+| photonDoctor diagnostic tool | ❌ (use `openclaw channels status`) | ✅ |
+| Onboarding | manual credentials / env | device-code auto-provisioning |
+| License | **MIT** | UNLICENSED |
+
+### Attribution
+
+This project is an **independent implementation** inspired by
+[Mouxy/openclaw-photon](https://github.com/Mouxy/openclaw-photon)'s design and
+its pointer that OpenClaw's shared message tool + channel runtime are the right
+integration surface. No code from that repository is used — its license is
+UNLICENSED, and this project is written from scratch against the OpenClaw
+plugin SDK and `spectrum-ts`. Thank you, Mouxy, for the inspiration.
+
+## Development
+
+```bash
+npm run build              # tsc -> dist/
+npm test                   # (planned) config/inbound/dedupe unit tests
+openclaw plugins install ./imessage-photon --force
+systemctl --user restart openclaw-gateway
+```
+
+Local install lives under `~/.openclaw/extensions/imessage-photon/`; rebuild
+and `cp -r dist/*` there, or re-run `plugins install --force`.
+
+## Known issues
+
+- **Poll vote events**: spectrum-ts's `toCachedPoll` rejects events whose poll
+  title is an empty string, crashing and dropping the event in the library
+  before the plugin can see it (issue draft:
+  `spectrum-ts-poll-bug-issue-draft.md`). Poll *creation* works.
+
+## Roadmap / TODO
+
+- [ ] **Message dedupe**: 48h window + restart protection (avoid duplicate
+      replies after a gateway restart)
+- [ ] **Unit tests**: config parsing / inbound classification / dedupe
+- [ ] **Device-code onboarding**: auto-login + auto-provision the Photon
+      project via Photon's public API (no manual credential copying)
+- [ ] **Group mention gating**: `requireMention` config (only reply in groups
+      when mentioned)
+- [ ] **Edit/unsend notifications**: `enableEditUnsend` switch (agent reacts
+      to inbound edit/unsend events)
+- [ ] Multi-account / remote iMessage line refinement
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,141 @@
+# openclaw-imessage-photon
+
+基于 **Photon Spectrum Cloud** 的 [OpenClaw](https://github.com/contaxy/openclaw) iMessage 渠道插件 —— **无需 Mac、无需 iMessage 服务器、无独立 bridge 进程**。
+
+在你的 VPS/云服务器上直接跑 iMessage：你的 agent 通过 Photon 云中继与 iMessage 联系人对话，以 OpenClaw 原生渠道插件形式运行（在 gateway 进程内 —— 没有每次消息临时起 CLI 进程、没有瞬时 agent 进程）。
+
+## 亮点
+
+- **原生渠道插件** —— 运行于 OpenClaw gateway 进程内；消息直接进入内嵌 agent 运行时。
+- **无需 Mac** —— Photon Spectrum Cloud 中继 iMessage。
+- **文本、图片、语音、投票、特效、名片** —— 双向。
+- **语音转写** —— 通过普通 OpenClaw 配置接入任意 `tools.media.audio` 转录 provider（Deepgram、ElevenLabs、Groq……）。
+- **对用户友好的默认行为** —— DM 白名单、👀 已读反应、tapback、自动重连、已读回执、输入中指示。
+- **引导式配置向导** —— `openclaw onboard` 引导完成 Photon 项目配置（凭据通过 `SPECTRUM_PROJECT_ID` / `SPECTRUM_PROJECT_SECRET` 环境变量，或从控制台粘贴）。
+
+## 安装
+
+要求：OpenClaw ≥ 2026.7.1，Node 22+。
+
+**通过 npm 安装（推荐）** —— 让任意 AI agent 帮你执行，或手动：
+
+```bash
+npx -y openclaw-imessage-photon-cli@latest install
+```
+
+或直接安装插件包：
+
+```bash
+openclaw plugins install npm:openclaw-imessage-photon
+```
+
+**从源码安装：**
+
+```bash
+git clone https://github.com/ethanjtch/openclaw-imessage-photon
+cd openclaw-imessage-photon
+npm install
+npm run build
+openclaw plugins install ./imessage-photon
+openclaw gateway restart
+```
+
+然后配置渠道（运行 `openclaw onboard` 选择 **iMessage (Photon)**），或直接编辑 `openclaw.json`：
+
+```json5
+{
+  channels: {
+    "imessage-photon": {
+      enabled: true,
+      projectId: "...",       // 或环境变量 SPECTRUM_PROJECT_ID
+      projectSecret: "...",   // 或环境变量 SPECTRUM_PROJECT_SECRET
+      allowFrom: ["+8613800138000"], // DM 白名单（E.164）。[] = 所有人
+    },
+  },
+}
+```
+
+在 [photon.codes](https://photon.codes) 注册、创建 iMessage provider 项目，复制 Project ID / Secret 填入。
+
+## 配置项
+
+| 配置项 | 默认值 | 说明 |
+|---|---|---|
+| `projectId` / `projectSecret` | 环境变量 `SPECTRUM_PROJECT_ID` / `SPECTRUM_PROJECT_SECRET` | Photon 项目凭据 |
+| `allowFrom` | `[]`（所有人） | DM 白名单，E.164 号码 |
+| `ackReaction` | `👀` | 收到文本消息时的"已读/处理中"反应；回复后移除。`""` 关闭 |
+| `tapbackNotifications` | `all` | `all` 把 tapback 转发给 agent；`off` 忽略 |
+| `enableMedia` | `false` | agent 收发媒体附件 |
+| `enablePoll` | `false` | agent 发起投票 |
+| `enableEffects` | `false` | 全屏特效（彩带、激光……） |
+| `enableContact` | `false` | agent 分享名片 |
+| `enableVoice` | `false` | agent 发送语音（走媒体 + audio 内容类型） |
+| `enableGroups` | `false` | 处理群聊 |
+| `enableTyping` | `false` | 处理中显示输入中指示 |
+| `enableReadReceipts` | `false` | 入站消息标记已读 |
+
+### 语音转写
+
+配置任一 OpenClaw 媒体音频转录 provider，例如 Deepgram：
+
+```json5
+{
+  tools: { media: { audio: { models: [{ provider: "deepgram", model: "nova-3", language: "zh" }] } } },
+}
+```
+
+需在 gateway 环境中配置对应 provider 的 key（如 `DEEPGRAM_API_KEY`）。入站语音会被保存到媒体库，由核心媒体管线转写，agent 随后能看到转录文本。
+
+## 能力对比矩阵
+
+| iMessage 能力 | 本插件 | [Mouxy/openclaw-photon](https://github.com/Mouxy/openclaw-photon) |
+|---|---|---|
+| 文本 / 引用回复 / 主动发送 | ✅ | ✅ |
+| 媒体（图片/文件，双向） | ✅（`enableMedia`） | ✅ |
+| 语音发送 + 入站转写 | ✅（`enableVoice` + `tools.media.audio`） | ✅ |
+| 投票（发起） | ✅（`enablePoll`） | ✅ |
+| 投票事件通知 | ⚠️ 被上游 spectrum-ts bug 阻断 | ✅ |
+| 全屏特效 | ✅（`enableEffects`） | ✅ |
+| 名片 | ✅（`enableContact`） | ✅ |
+| 群聊 | ✅（`enableGroups`，无 @ 门控） | ✅ |
+| Tapback（收到点赞） | ✅ | ✅ |
+| 👀 已读反应 | ✅（👀） | — |
+| 输入中指示 | ✅（`enableTyping`） | ✅ |
+| 已读回执 | ✅（`enableReadReceipts`） | ✅ |
+| 贴纸 / 文字动画 | ❌ | ✅（需 `@photon-ai/advanced-imessage`） |
+| mini-app / 状态卡片 | ❌（仅 business 账号） | ✅ |
+| photonDoctor 诊断工具 | ❌（用 `openclaw channels status`） | ✅ |
+| 引导配置 | 手动凭据 / 环境变量 | 设备码自动开通 |
+| 许可证 | **MIT** | UNLICENSED |
+
+### 致谢（Attribution）
+
+本项目是**独立实现**，受 [Mouxy/openclaw-photon](https://github.com/Mouxy/openclaw-photon) 的设计及其"OpenClaw 共享 message 工具 + channel runtime 是正确的集成入口"这一洞察启发。**未使用该仓库的任何代码** —— 其许可证为 UNLICENSED；本项目基于 OpenClaw 插件 SDK 与 `spectrum-ts` 从零编写。感谢 Mouxy 提供的灵感。
+
+## 开发
+
+```bash
+npm run build              # tsc -> dist/
+npm test                   # （计划中）config/inbound/dedupe 单元测试
+openclaw plugins install ./imessage-photon --force
+systemctl --user restart openclaw-gateway
+```
+
+本地安装位于 `~/.openclaw/extensions/imessage-photon/`；重新构建后 `cp -r dist/*` 到该目录，或重新执行 `plugins install --force`。
+
+## 已知问题
+
+- **投票事件通知**：spectrum-ts 的 `toCachedPoll` 会拒绝 poll 标题为空字符串的事件，在库内崩溃并丢弃事件，插件无法看到（issue 草稿：`spectrum-ts-poll-bug-issue-draft.md`）。投票**发起**正常。
+
+## 路线图（Roadmap / TODO）
+
+- [ ] **消息去重**：48 小时窗口去重 + 重启后防止重复处理（防重启重复回复）
+- [ ] **测试文件**：config 解析 / inbound 分类 / 去重逻辑（防回归）
+- [ ] **设备码 onboarding**：调用 Photon 公开 API（app.photon.codes）自动登录 + 自动开通项目，免手动复制凭据
+- [ ] **群组 @ 门控**：`requireMention` 配置（群聊中只有被 @ 才回复）
+- [ ] **edit/unsend 通知 agent**：`enableEditUnsend` 开关（收到用户的编辑/撤回事件并回应）
+- [ ] multi-account / 远程 iMessage 线路支持细化
+
+## 许可证
+
+[MIT](LICENSE)

package/dist/index.js

@@ -0,0 +1,8 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { imessagePhotonPlugin } from "./src/channel.js";
+export default defineChannelPluginEntry({
+    id: "imessage-photon",
+    name: "iMessage (Photon)",
+    description: "iMessage channel via Photon Spectrum Cloud — no Mac required.",
+    plugin: imessagePhotonPlugin,
+});

package/dist/setup-entry.js

@@ -0,0 +1,3 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { imessagePhotonPlugin } from "./src/channel.js";
+export default defineSetupPluginEntry(imessagePhotonPlugin);

package/dist/src/actions.js

@@ -0,0 +1,331 @@
+import { readFile } from "node:fs/promises";
+import { jsonResult } from "openclaw/plugin-sdk/agent-runtime";
+import { loadOutboundMediaFromUrl } from "openclaw/plugin-sdk/outbound-media";
+import { text as textContent, markdown as markdownContent, richlink as richlinkContent, attachment as attachmentContent, poll as pollContent, read as readContent, reply as replyContent, voice as voiceContent, contact as contactContent, } from "spectrum-ts";
+import { effect as effectContent } from "@spectrum-ts/imessage";
+import { resolveAccount } from "./channel.js";
+import { resolveSpace, resolveMessage } from "./spectrum.js";
+// Full-screen iMessage effects (spectrum-ts exposes the builder but not the
+// id table, so we keep the canonical ids here).
+const MESSAGE_EFFECTS = {
+    balloons: "com.apple.messages.effect.CKBalloonEffect",
+    celebration: "com.apple.messages.effect.CKHappyBirthdayEffect",
+    confetti: "com.apple.messages.effect.CKConfettiEffect",
+    echo: "com.apple.messages.effect.CKEchoEffect",
+    fireworks: "com.apple.messages.effect.CKFireworksEffect",
+    gentle: "com.apple.MobileSMS.expressivesend.gentle",
+    heart: "com.apple.messages.effect.CKHeartEffect",
+    invisible: "com.apple.MobileSMS.expressivesend.invisibleink",
+    lasers: "com.apple.messages.effect.CKLasersEffect",
+    loud: "com.apple.MobileSMS.expressivesend.loud",
+    slam: "com.apple.MobileSMS.expressivesend.impact",
+    sparkles: "com.apple.messages.effect.CKSparklesEffect",
+    spotlight: "com.apple.messages.effect.CKSpotlightEffect",
+};
+// Base chat actions always available through the shared message tool.
+const BASE_ACTIONS = ["send", "react", "read", "edit", "unsend", "reply"];
+// Feature-gated actions (default off; enable via channels.imessage-photon.*).
+const MEDIA_ACTION = "sendAttachment";
+const POLL_ACTION = "poll";
+const EFFECT_ACTION = "sendWithEffect";
+const CONTACT_ACTION = "sendContact";
+// Note: there is no custom "sendVoice" action. OpenClaw's message-tool layer
+// hard-codes which actions accept a target (MESSAGE_ACTION_TARGET_MODE), and
+// unknown actions are rejected with "Action X does not accept a target".
+// Voice is sent via sendAttachment with contentType audio/* instead.
+const SUPPORTED = new Set([
+    ...BASE_ACTIONS,
+    MEDIA_ACTION,
+    POLL_ACTION,
+    EFFECT_ACTION,
+    CONTACT_ACTION,
+]);
+function readString(params, ...keys) {
+    for (const key of keys) {
+        const v = params[key];
+        if (typeof v === "string" && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+function readStringArray(params, ...keys) {
+    for (const key of keys) {
+        const v = params[key];
+        if (Array.isArray(v))
+            return v.map(String).map((s) => s.trim()).filter(Boolean);
+    }
+    return [];
+}
+function readTarget(params) {
+    return readString(params, "to", "target", "phone", "phoneNumber", "number");
+}
+function readMessageId(params) {
+    return readString(params, "messageId", "message_id", "targetMessageId", "id");
+}
+/** Normalize an effect name to the iMessage effect id, or throw. */
+function resolveEffect(name) {
+    const key = (name ?? "").trim().toLowerCase();
+    if (!key)
+        throw new Error(`sendWithEffect requires effect (one of: ${Object.keys(MESSAGE_EFFECTS).join(", ")})`);
+    const id = MESSAGE_EFFECTS[key];
+    if (!id)
+        throw new Error(`unsupported effect "${key}" (one of: ${Object.keys(MESSAGE_EFFECTS).join(", ")})`);
+    return id;
+}
+/**
+ * Read a media source from the agent's params into a sendable attachment.
+ *
+ * OpenClaw's message-tool layer can deliver media as either:
+ *   - `params.buffer` (base64) — from local files / hosted hydration
+ *   - `params.mediaUrl` / `media` / `filePath` / `path` — URL or sandbox path
+ * We support both. Buffer input REQUIRES an explicit mimeType (no extension
+ * to inspect), so we resolve contentType from params, then fall back to
+ * extension/magic-byte sniffing via guessMimeType.
+ */
+async function readMediaContent(ctx, params) {
+    // Render-friendly metadata
+    const name = readString(params, "filename", "name", "fileName") ?? "attachment";
+    const contentType = readString(params, "contentType", "mimeType");
+    // Our own param names; accept Mouxy-style aliases only for tool compatibility
+    const asVoice = params.asVoiceMessage === true ||
+        params.asVoice === true ||
+        params.as_voice === true;
+    // 1) Hydrated base64 buffer
+    const bufferB64 = typeof params.buffer === "string" ? params.buffer : undefined;
+    if (bufferB64) {
+        const buf = Buffer.from(bufferB64, "base64");
+        const mime = contentType ?? guessMimeType(name, buf);
+        if (!mime) {
+            throw new Error("Unable to resolve MIME type for attachment. Pass contentType/mimeType explicitly.");
+        }
+        const builder = asVoice ? voiceContent : attachmentContent;
+        return builder(buf, { name, mimeType: mime });
+    }
+    // 2) mediaUrl / media / filePath / path (URL or sandbox path)
+    const source = readString(params, "mediaUrl", "media", "media_url") ??
+        readString(params, "filePath", "path", "file", "mediaPath");
+    if (!source)
+        throw new Error("sendAttachment requires buffer, mediaUrl/media, or filePath/path");
+    const loaded = await loadOutboundMediaFromUrl(source, {
+        maxBytes: typeof params.maxBytes === "number" ? params.maxBytes : 20 * 1024 * 1024,
+        mediaAccess: ctx.mediaAccess,
+        mediaLocalRoots: ctx.mediaLocalRoots,
+        mediaReadFile: ctx.mediaReadFile,
+    });
+    const mime = contentType ??
+        loaded.contentType ??
+        guessMimeType(loaded.fileName ?? name, loaded.buffer);
+    if (!mime) {
+        throw new Error("Unable to resolve MIME type for attachment. Pass contentType/mimeType explicitly.");
+    }
+    const builder = asVoice ? voiceContent : attachmentContent;
+    return builder(loaded.buffer, {
+        name: loaded.fileName ?? name,
+        mimeType: mime,
+    });
+}
+/** Best-effort MIME detection from a filename extension (or buffer magic bytes). */
+function guessMimeType(filename, buf) {
+    const ext = (filename ?? "").toLowerCase().split(".").pop() ?? "";
+    const byExt = {
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        heic: "image/heic",
+        heif: "image/heif",
+        svg: "image/svg+xml",
+        mp3: "audio/mpeg",
+        m4a: "audio/mp4",
+        aac: "audio/aac",
+        wav: "audio/wav",
+        ogg: "audio/ogg",
+        mp4: "video/mp4",
+        mov: "video/quicktime",
+        m4v: "video/mp4",
+        pdf: "application/pdf",
+        txt: "text/plain",
+        md: "text/markdown",
+        zip: "application/zip",
+    };
+    if (ext && byExt[ext])
+        return byExt[ext];
+    if (buf && buf.length >= 8) {
+        const hex = buf.subarray(0, 8).toString("hex");
+        if (hex.startsWith("89504e47"))
+            return "image/png";
+        if (hex.startsWith("ffd8ff"))
+            return "image/jpeg";
+        if (hex.startsWith("47494638"))
+            return "image/gif";
+        if (hex.startsWith("52494646") && buf.subarray(8, 12).toString() === "WAVE")
+            return "audio/wav";
+        if (hex.startsWith("494433") || hex.startsWith("fffb") || hex.startsWith("fff3"))
+            return "audio/mpeg";
+        if (hex.startsWith("25504446"))
+            return "application/pdf";
+    }
+    return undefined;
+}
+function actionOk(data) {
+    return jsonResult({ ok: true, ...data });
+}
+function actionError(message) {
+    return jsonResult({ ok: false, error: message });
+}
+/** Build the channel message-action adapter for iMessage via Photon. */
+export function createMessageActions() {
+    return {
+        describeMessageTool: ({ cfg, accountId }) => {
+            let account;
+            try {
+                account = resolveAccount(cfg, accountId);
+            }
+            catch {
+                return null;
+            }
+            const actions = [...BASE_ACTIONS];
+            if (account.enableMedia)
+                actions.push(MEDIA_ACTION);
+            if (account.enablePoll)
+                actions.push(POLL_ACTION);
+            if (account.enableEffects)
+                actions.push(EFFECT_ACTION);
+            if (account.enableContact)
+                actions.push(CONTACT_ACTION);
+            return {
+                actions,
+                mediaSourceParams: {
+                    sendAttachment: ["media", "mediaUrl", "filePath", "path", "file"],
+                },
+            };
+        },
+        supportsAction: ({ action }) => SUPPORTED.has(action),
+        resolveExecutionMode: () => "gateway",
+        handleAction: async (ctx) => {
+            const { action, params } = ctx;
+            const actionName = action;
+            try {
+                const to = readTarget(params);
+                const space = to ? resolveSpace(to) : undefined;
+                if (!space) {
+                    return actionError(`no known iMessage space for target "${to ?? "(none)"}". The user must message the bot first.`);
+                }
+                switch (actionName) {
+                    case "send": {
+                        const text = readString(params, "text", "message", "content");
+                        const url = readString(params, "url", "link");
+                        const md = readString(params, "markdown", "md");
+                        if (url) {
+                            await space.send(richlinkContent(url));
+                            return actionOk({ to, type: "richlink", url });
+                        }
+                        if (md) {
+                            await space.send(markdownContent(md));
+                            return actionOk({ to, type: "markdown" });
+                        }
+                        if (!text)
+                            throw new Error("send requires text/message/content (or url/link, or markdown/md)");
+                        await space.send(textContent(text));
+                        return actionOk({ to, type: "text" });
+                    }
+                    case "sendAttachment": {
+                        const content = await readMediaContent(ctx, params);
+                        await space.send(content);
+                        return actionOk({ to, type: "attachment" });
+                    }
+                    case "poll": {
+                        const question = readString(params, "pollQuestion", "question", "title", "text", "message");
+                        const options = readStringArray(params, "pollOptions", "options", "pollOption", "choices");
+                        if (!question)
+                            throw new Error("poll requires pollQuestion/question/title");
+                        if (options.length < 2)
+                            throw new Error("poll requires at least two options");
+                        await space.send(pollContent(question, ...options));
+                        return actionOk({ to, type: "poll", question, optionCount: options.length });
+                    }
+                    case "sendWithEffect": {
+                        const text = readString(params, "text", "message", "content");
+                        const effectName = readString(params, "effect", "effectId");
+                        if (!text)
+                            throw new Error("sendWithEffect requires text/message/content");
+                        await space.send(effectContent(markdownContent(text), resolveEffect(effectName)));
+                        return actionOk({ to, type: "effect", effect: effectName });
+                    }
+                    case "sendContact": {
+                        const input = readString(params, "name", "contactName") ??
+                            readString(params, "phone", "contactPhone") ??
+                            readString(params, "email", "contactEmail");
+                        if (!input)
+                            throw new Error("sendContact requires name, phone, or email");
+                        const contactValue = readString(params, "name", "contactName") ?? input;
+                        const phone = readString(params, "phone", "contactPhone");
+                        const email = readString(params, "email", "contactEmail");
+                        // contact() accepts a phone/email string or ContactInput; build
+                        // a phone-number contact when possible.
+                        await space.send(contactContent(phone ?? email ?? contactValue));
+                        return actionOk({ to, type: "contact" });
+                    }
+                    case "sendVoice": {
+                        // Kept for backward compatibility: voice is sent through the media
+                        // path (audio/* contentType).
+                        const content = await readMediaContent(ctx, params);
+                        await space.send(content);
+                        return actionOk({ to, type: "voice" });
+                    }
+                    case "react": {
+                        const target = resolveMessage(readMessageId(params));
+                        if (!target)
+                            return actionError("react requires messageId of a recent message");
+                        const emoji = readString(params, "emoji", "reaction");
+                        if (!emoji)
+                            throw new Error("react requires emoji");
+                        await target.react(emoji);
+                        return actionOk({ to, emoji });
+                    }
+                    case "read": {
+                        const target = resolveMessage(readMessageId(params));
+                        if (target)
+                            await target.read();
+                        else
+                            await space.send(readContent(target ?? {}));
+                        return actionOk({ to });
+                    }
+                    case "edit": {
+                        const target = resolveMessage(readMessageId(params));
+                        if (!target)
+                            return actionError("edit requires messageId of a recent message");
+                        const text = readString(params, "text", "message", "content");
+                        if (!text)
+                            throw new Error("edit requires text/message/content");
+                        await target.edit(textContent(text));
+                        return actionOk({ to });
+                    }
+                    case "unsend": {
+                        const target = resolveMessage(readMessageId(params));
+                        if (!target)
+                            return actionError("unsend requires messageId of a recent message");
+                        await target.unsend();
+                        return actionOk({ to });
+                    }
+                    case "reply": {
+                        const target = resolveMessage(readMessageId(params));
+                        const text = readString(params, "text", "message", "content");
+                        if (!target)
+                            return actionError("reply requires messageId of a recent message");
+                        if (!text)
+                            throw new Error("reply requires text/message/content");
+                        await space.send(replyContent(textContent(text), target));
+                        return actionOk({ to });
+                    }
+                    default:
+                        return actionError(`unsupported action: ${actionName}`);
+                }
+            }
+            catch (err) {
+                return actionError(`imessage-photon ${actionName}: ${err.message}`);
+            }
+        },
+    };
+}