openclaw-imessage-photon 0.1.2 → 0.1.3

package/README.md

@@ -16,6 +16,10 @@ agent processes).
   dispatch straight into the embedded agent runtime.
 - **No Mac required** — Photon Spectrum Cloud relays iMessage.
 - **Text, images, voice, polls, effects, contacts** — both directions.
+- **Rich link previews & Mini App cards** — send a URL as an iMessage link
+  card (`url`), a sheet-style Mini App card (`appUrl`, opens inside the
+  Spectrum App — no Safari jump), or a live in-transcript card (`appUrl` +
+  `appLive`).
 - **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,
@@ -85,6 +89,21 @@ iMessage provider, and copy the Project ID / Secret.
 | `enableTyping` | `false` | Typing indicator while processing |
 | `enableReadReceipts` | `false` | Mark inbound as read |
 
+### Rich links & Mini App cards
+
+Plain `send` accepts three URL flavors:
+
+| send param | iMessage rendering |
+|---|---|
+| `url` / `link` | Rich link preview card (tap opens in Safari) |
+| `appUrl` | Mini App card: compact title card; tap opens the full page in the Spectrum iMessage App — no Safari jump |
+| `appUrl` + `appLive: true` | Live card: interactive page rendered inline in the transcript (swipe/click, no tap-to-open) |
+
+App cards use Photon's **Spectrum App** host (Apple-approved iMessage
+launcher) — no business plan needed for `app()` cards; recipients install the
+Spectrum App once. Custom `customizedMiniApp()` (bring-your-own extension) is
+business-plan only.
+
 ### Voice transcription
 
 Configure any OpenClaw media-audio STT provider, e.g. Deepgram:
@@ -116,7 +135,7 @@ core media pipeline; the agent then sees the transcript.
 | Typing indicators | ✅ (`enableTyping`) | ✅ |
 | Read receipts | ✅ (`enableReadReceipts`) | ✅ |
 | Stickers / text animations | ❌ | ✅ (needs `@photon-ai/advanced-imessage`) |
-| Mini-app / status cards | ❌ (business-account only) | ✅ |
+| Mini-app / status cards | ✅ `appUrl`/`appLive` via send (Spectrum App host); custom `customizedMiniApp()` business-only | ✅ (needs `@photon-ai/advanced-imessage`) |
 | photonDoctor diagnostic tool | ❌ (use `openclaw channels status`) | ✅ |
 | Onboarding | manual credentials / env | device-code auto-provisioning |
 | License | **MIT** | UNLICENSED |
@@ -158,8 +177,10 @@ and `cp -r dist/*` there, or re-run `plugins install --force`.
       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)
+- [ ] **Plugin config schema**: declare plugin-owned `channels.imessage-photon.*`
+      keys via `configSchema` (blocked-ish today: openclaw's validator rejects
+      unknown keys, which is why extra switches like edit/unsend can't be added
+      without it)
 - [ ] Multi-account / remote iMessage line refinement
 
 ## License

package/README.zh-CN.md

@@ -9,6 +9,7 @@
 - **原生渠道插件** —— 运行于 OpenClaw gateway 进程内；消息直接进入内嵌 agent 运行时。
 - **无需 Mac** —— Photon Spectrum Cloud 中继 iMessage。
 - **文本、图片、语音、投票、特效、名片** —— 双向。
+- **富链接预览 & Mini App 卡片** —— 用 `url` 发链接卡片；用 `appUrl` 发 sheet 式 Mini App 卡片（在 Spectrum App 内打开，不跳 Safari）；用 `appUrl` + `appLive` 发 live 卡片（对话内直接交互）。
 - **语音转写** —— 通过普通 OpenClaw 配置接入任意 `tools.media.audio` 转录 provider（Deepgram、ElevenLabs、Groq……）。
 - **对用户友好的默认行为** —— DM 白名单、👀 已读反应、tapback、自动重连、已读回执、输入中指示。
 - **引导式配置向导** —— `openclaw onboard` 引导完成 Photon 项目配置（凭据通过 `SPECTRUM_PROJECT_ID` / `SPECTRUM_PROJECT_SECRET` 环境变量，或从控制台粘贴）。
@@ -74,6 +75,18 @@ openclaw gateway restart
 | `enableTyping` | `false` | 处理中显示输入中指示 |
 | `enableReadReceipts` | `false` | 入站消息标记已读 |
 
+### 富链接 & Mini App 卡片
+
+`send` 支持三种 URL 形态：
+
+| send 参数 | iMessage 渲染 |
+|---|---|
+| `url` / `link` | 富链接预览卡片（点击打开 Safari） |
+| `appUrl` | Mini App 卡片：紧凑标题卡片；点击在 Spectrum App 内打开完整页面——不跳 Safari |
+| `appUrl` + `appLive: true` | Live 卡片：页面内嵌在对话中直接交互（滑动/点击，无需点开） |
+
+App 卡片使用 Photon 的 **Spectrum App** 宿主（Apple 已批准的 iMessage 启动器）——`app()` 卡片**无需 business 套餐**；接收方装一次 Spectrum App 即可。自定义 `customizedMiniApp()`（自带扩展）才需要 business。
+
 ### 语音转写
 
 配置任一 OpenClaw 媒体音频转录 provider，例如 Deepgram：
@@ -103,7 +116,7 @@ openclaw gateway restart
 | 输入中指示 | ✅（`enableTyping`） | ✅ |
 | 已读回执 | ✅（`enableReadReceipts`） | ✅ |
 | 贴纸 / 文字动画 | ❌ | ✅（需 `@photon-ai/advanced-imessage`） |
-| mini-app / 状态卡片 | ❌（仅 business 账号） | ✅ |
+| mini-app / 状态卡片 | ✅ `appUrl`/`appLive`（通过 send，Spectrum App 宿主）；自定义 `customizedMiniApp()` 仅 business | ✅（需 `@photon-ai/advanced-imessage`） |
 | photonDoctor 诊断工具 | ❌（用 `openclaw channels status`） | ✅ |
 | 引导配置 | 手动凭据 / 环境变量 | 设备码自动开通 |
 | 许可证 | **MIT** | UNLICENSED |
@@ -133,7 +146,7 @@ systemctl --user restart openclaw-gateway
 - [ ] **测试文件**：config 解析 / inbound 分类 / 去重逻辑（防回归）
 - [ ] **设备码 onboarding**：调用 Photon 公开 API（app.photon.codes）自动登录 + 自动开通项目，免手动复制凭据
 - [ ] **群组 @ 门控**：`requireMention` 配置（群聊中只有被 @ 才回复）
-- [ ] **edit/unsend 通知 agent**：`enableEditUnsend` 开关（收到用户的编辑/撤回事件并回应）
+- [ ] **插件 config schema**：通过 `configSchema` 声明插件自有 `channels.imessage-photon.*` 配置键（当前 openclaw 校验器拒绝未知键，这正是 edit/unsend 等附加开关无法加入的原因）
 - [ ] multi-account / 远程 iMessage 线路支持细化
 
 ## 许可证

package/dist/src/actions.js

@@ -1,7 +1,8 @@
 import { readFile } from "node:fs/promises";
+import { Type } from "typebox";
 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 { text as textContent, markdown as markdownContent, richlink as richlinkContent, app as appContent, 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";
@@ -199,6 +200,27 @@ export function createMessageActions() {
                 mediaSourceParams: {
                     sendAttachment: ["media", "mediaUrl", "filePath", "path", "file"],
                 },
+                // Expose rich-link and App-card capabilities on the shared send action.
+                schema: [
+                    {
+                        properties: {
+                            url: Type.String({
+                                description: "HTTPS URL to send as a rich link-preview message (iMessage renders it as a link card). Mutually exclusive with text/markdown/appUrl.",
+                            }),
+                            link: Type.String({
+                                description: "Alias for url: HTTPS URL to send as a rich link-preview message.",
+                            }),
+                            appUrl: Type.String({
+                                description: "HTTPS URL to send as a native iMessage App card (Spectrum App host). Recipient opens it in the Spectrum iMessage App without leaving Messages; degrades to a link preview on unsupported platforms. Mutually exclusive with text/markdown/url.",
+                            }),
+                            appLive: Type.Optional(Type.Boolean({
+                                description: "When sending an App card (appUrl set), request live in-transcript rendering (MSMessageLiveLayout). Requires the recipient to have the Spectrum App extension installed.",
+                            })),
+                        },
+                        actions: ["send"],
+                        visibility: "current-channel",
+                    },
+                ],
             };
         },
         supportsAction: ({ action }) => SUPPORTED.has(action),
@@ -216,17 +238,23 @@ export function createMessageActions() {
                     case "send": {
                         const text = readString(params, "text", "message", "content");
                         const url = readString(params, "url", "link");
-                        const md = readString(params, "markdown", "md");
+                        const appUrl = readString(params, "appUrl", "app_url", "cardUrl");
+                        if (appUrl) {
+                            const live = params.appLive === true || params.appLive === "true" || params.live === true || params.live === "true";
+                            await space.send(appContent(appUrl, live ? { live: true } : undefined));
+                            return actionOk({ to, type: "app", url: appUrl, live });
+                        }
                         if (url) {
                             await space.send(richlinkContent(url));
                             return actionOk({ to, type: "richlink", url });
                         }
+                        const md = readString(params, "markdown", "md");
                         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)");
+                            throw new Error("send requires text/message/content (or url/link, or appUrl)");
                         await space.send(textContent(text));
                         return actionOk({ to, type: "text" });
                     }

package/dist/src/channel.js

@@ -1,5 +1,5 @@
 import { createChatChannelPlugin, } from "openclaw/plugin-sdk/channel-core";
-import { connectSpectrum, resetSpectrum, rememberSpace, rememberMessage } from "./spectrum.js";
+import { connectSpectrum, resetSpectrum, rememberSpace, rememberMessage, resolveOrOpenSpace, sendText } from "./spectrum.js";
 import { handleInbound } from "./inbound.js";
 import { createMessageActions } from "./actions.js";
 function channelSection(cfg) {
@@ -36,6 +36,7 @@ export function resolveAccount(cfg, accountId) {
         enableGroups: Boolean(section?.enableGroups),
         enableTyping: Boolean(section?.enableTyping),
         enableReadReceipts: Boolean(section?.enableReadReceipts),
+        contactNames: section?.contactNames ?? {},
     };
 }
 const setupWizard = {
@@ -160,6 +161,29 @@ export const imessagePhotonPlugin = createChatChannelPlugin({
             reply: true,
         },
         actions: createMessageActions(),
+        agentPrompt: {
+            // Text guidance layered on top of the fixed openclaw message-tool
+            // schema: keep replies as plain text by default, and only use
+            // reply-quoting when the user themselves quoted a message.
+            messageToolHints: ({ cfg }) => {
+                const account = resolveAccount(cfg);
+                const hints = [
+                    "Prefer plain text (text) over markdown (markdown) unless the recipient explicitly asked for rich formatting. Plain text renders best in iMessage.",
+                    "For everyday replies use the plain send action without quotes.",
+                ];
+                if (account.enableMedia) {
+                    hints.push("Images/audio/video/files are sent with sendAttachment (media/buffer/filePath).");
+                }
+                return hints;
+            },
+            inboundFormattingHints: () => ({
+                text_markup: "plain text",
+                rules: [
+                    "When the user's message is a reply-to (quoted) message, reply by quoting that message back using the reply action with its messageId — this keeps the quoted conversation thread visible in iMessage.",
+                    "When the user's message is NOT a reply, reply with a plain send (no quote).",
+                ],
+            }),
+        },
         setupWizard,
         config: {
             listAccountIds: () => ["default"],
@@ -176,6 +200,21 @@ export const imessagePhotonPlugin = createChatChannelPlugin({
                 };
             },
         },
+        // Directory: give iMessage contacts a friendly display name so sessions
+        // show "iMessage <last4>" instead of the raw E.164 number.
+        directory: {
+            listPeers: async ({ cfg }) => {
+                const account = resolveAccount(cfg);
+                const peers = account.allowFrom ?? [];
+                return peers.map((raw) => {
+                    const id = String(raw).trim();
+                    if (!id)
+                        return null;
+                    const tail = id.slice(-4);
+                    return { kind: "user", id, name: `iMessage ${tail}` };
+                }).filter((e) => e !== null);
+            },
+        },
         setup: {
             applyAccountConfig: ({ cfg, input }) => ({
                 ...cfg,
@@ -239,9 +278,21 @@ export const imessagePhotonPlugin = createChatChannelPlugin({
     },
     threading: { topLevelReplyToMode: "reply" },
     outbound: {
-        // Outbound delivery runs inside the gateway via our message actions
-        // (handleAction). Declaring deliveryMode "gateway" makes the shared
-        // message tool treat this channel as send-capable.
-        deliveryMode: "gateway",
+        // Real active-outbound surface: lets the core deliver proactive sends
+        // (cron announcements, heartbeat, control-UI new message) to iMessage via
+        // Spectrum. sendText resolves/creates the 1:1 Space by phone number.
+        deliveryMode: "direct",
+        sendText: async ({ to, text }) => {
+            const space = await resolveOrOpenSpace(to);
+            if (!space)
+                throw new Error(`imessage-photon: no reachable space for ${to}`);
+            await sendText(space, text);
+            return {
+                channel: "imessage-photon",
+                messageId: "",
+                target: { kind: "conversation", id: to },
+                timestamp: Date.now(),
+            };
+        },
     },
 });

package/dist/src/inbound.js

@@ -36,8 +36,7 @@ export async function handleInbound(runtime, cfg, space, message, log) {
         await dispatchPollEvent(runtime, cfg, space, message, account, log);
     }
     else if (message.content.type === "edit" || message.content.type === "unsend") {
-        // Agent-facing edit/unsend handling is opt-in (enableEditUnsend);
-        // until then, these are system events: log only.
+        // edit/unsend from the user are system events: log only (no agent turn).
         log?.(`[imessage-photon] system event type=${message.content.type} from ${space.id}`);
     }
     else {
@@ -49,7 +48,16 @@ export async function handleInbound(runtime, cfg, space, message, log) {
 /** Shared turn dispatch: build session route + context, then run the agent. */
 async function runAgentTurn(runtime, cfg, space, message, account, log, opts) {
     const phone = senderPhone(space, message) ?? space.id;
-    const senderName = message.sender?.name;
+    // Sender display name, separate from the conversation label:
+    // 1. explicit per-number contact name from config (contactNames) — bubbles show
+    //    this instead of a phone-derived label, e.g. "Ethan".
+    // 2. any real name the platform delivers (spectrum currently never sends one).
+    // 3. stable fallback "iMessage <last4 digits>" so the label never fluctuates.
+    const platformName = message.sender?.name;
+    const senderName = account.contactNames[phone] ?? platformName?.trim() ?? `iMessage ${phone.slice(-4)}`;
+    // Conversation title stays a stable, human-meaningful label independent of the
+    // per-message sender display name.
+    const conversationLabel = `iMessage ${phone.slice(-4)}`;
     // Read receipt: mark the conversation read (iMessage marks the whole chat).
     if (account.enableReadReceipts) {
         message.read().catch((err) => log?.(`[imessage-photon] read receipt failed: ${String(err)}`));
@@ -92,6 +100,7 @@ async function runAgentTurn(runtime, cfg, space, message, account, log, opts) {
     });
     await runtime.inbound.run({
         channel: CHANNEL,
+        accountId: "default",
         raw: message,
         adapter: {
             ingest: (raw) => ({
@@ -102,9 +111,17 @@ async function runAgentTurn(runtime, cfg, space, message, account, log, opts) {
                 raw,
             }),
             resolveTurn: async (input) => {
+                // Pass the configured DM scope through so iMessage DMs get their own
+                // session (agent:main:imessage-photon:direct:<phone>) instead of being
+                // merged into the main session (agent:main:main). The default
+                // dmScope in core is "main"; without this, every channel merges.
+                const s = cfg.session;
                 const routeSessionKey = runtime.routing.buildAgentSessionKey({
                     agentId: AGENT_ID,
                     channel: CHANNEL,
+                    mainKey: s?.mainKey ?? "main",
+                    dmScope: s?.dmScope ?? "main",
+                    identityLinks: s?.identityLinks,
                     peer: { kind: "direct", id: phone },
                 });
                 const storePath = runtime.session.resolveStorePath(cfg.session?.store, {
@@ -112,9 +129,10 @@ async function runAgentTurn(runtime, cfg, space, message, account, log, opts) {
                 });
                 const ctxPayload = await runtime.inbound.buildContext({
                     channel: CHANNEL,
+                    accountId: "default",
                     from: phone,
                     sender: { id: phone, name: senderName },
-                    conversation: { kind: "direct", id: space.id },
+                    conversation: { kind: "direct", id: space.id, label: conversationLabel },
                     route: { agentId: AGENT_ID, routeSessionKey },
                     reply: { to: phone, sourceReplyDeliveryMode: "reply" },
                     message: { rawBody: opts.rawText, bodyForAgent: opts.textForAgent },
@@ -128,6 +146,21 @@ async function runAgentTurn(runtime, cfg, space, message, account, log, opts) {
                     storePath,
                     ctxPayload,
                     recordInboundSession: runtime.session.recordInboundSession,
+                    // openclaw ≥ 2026.8.1 requires prepared turns to declare a dispatch
+                    // lifecycle: turnAdoptionLifecycle is undefined for this non-durable
+                    // direct-DM turn; onDispatchSkipped releases what runDispatch would
+                    // have settled (typing indicator + seen-ack) when dispatch is
+                    // skipped (outboundEcho / botLoopProtection / observeOnly).
+                    runDispatchLifecycle: {
+                        turnAdoptionLifecycle: undefined,
+                        onDispatchSkipped: async () => {
+                            await stopTyping();
+                            if (ackHandle) {
+                                const h = ackHandle;
+                                await h.remove().catch((err) => log?.(`[imessage-photon] ack remove failed (skipped): ${String(err)}`));
+                            }
+                        },
+                    },
                     runDispatch: () => runtime.reply.dispatchReplyWithBufferedBlockDispatcher({
                         ctx: ctxPayload,
                         cfg,

package/dist/src/spectrum.js

@@ -39,6 +39,33 @@ export function resolveSpace(target) {
         return undefined;
     return spacesByPhone.get(phone);
 }
+/**
+ * Resolve a Space for an outbound target, falling back to resolving/creating
+ * the 1:1 conversation via the platform when the target was never observed on
+ * the inbound stream (active outbound sends).
+ */
+export async function resolveOrOpenSpace(target) {
+    const cached = resolveSpace(target);
+    if (cached)
+        return cached;
+    const explicitPhone = normalizePhone(target);
+    if (!explicitPhone || !app)
+        return undefined;
+    try {
+        const namespace = app.space;
+        const create = namespace?.["imessage"]
+            ?.create;
+        if (!create)
+            return undefined;
+        const space = await create(explicitPhone);
+        if (space)
+            rememberSpace(space);
+        return space;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Number of known spaces (used in diagnostics). */
 export function knownSpaceCount() {
     return spacesByPhone.size;

package/openclaw.plugin.json

@@ -3,7 +3,9 @@
   "name": "iMessage (Photon)",
   "description": "iMessage channel via Photon Spectrum Cloud — no Mac required. Register at https://photon.codes, create a project, and paste the Project ID and Secret.",
   "icon": "https://cdn.simpleicons.org/imessage",
-  "channels": ["imessage-photon"],
+  "channels": [
+    "imessage-photon"
+  ],
   "channelEnvVars": {
     "imessage-photon": [
       "SPECTRUM_PROJECT_ID",
@@ -22,20 +24,38 @@
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
         "properties": {
-          "enabled": { "type": "boolean" },
+          "enabled": {
+            "type": "boolean"
+          },
           "dmPolicy": {
             "type": "string",
-            "enum": ["allowlist", "pairing", "open", "disabled"]
+            "enum": [
+              "allowlist",
+              "pairing",
+              "open",
+              "disabled"
+            ]
           },
           "dmSecurity": {
             "type": "string",
-            "enum": ["allowlist", "pairing", "open", "disabled"]
+            "enum": [
+              "allowlist",
+              "pairing",
+              "open",
+              "disabled"
+            ]
+          },
+          "projectId": {
+            "type": "string"
+          },
+          "projectSecret": {
+            "type": "string"
           },
-          "projectId": { "type": "string" },
-          "projectSecret": { "type": "string" },
           "allowFrom": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Allowed sender phone numbers in E.164 form, e.g. +8613800138000. Empty = allow everyone."
           },
           "ackReaction": {
@@ -45,7 +65,10 @@
           },
           "tapbackNotifications": {
             "type": "string",
-            "enum": ["off", "all"],
+            "enum": [
+              "off",
+              "all"
+            ],
             "default": "all",
             "description": "off = ignore inbound tapbacks; all = forward them to the agent as system events."
           },
@@ -88,15 +111,29 @@
             "type": "boolean",
             "default": false,
             "description": "Mark inbound messages as read (read receipts)."
+          },
+          "contactNames": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Map of E.164 phone numbers to human-readable display names shown as the message sender in conversation bubbles, e.g. {\"+8613800138000\": \"Ethan\"}. Falls back to \"iMessage <last4 digits>\" and then to any name provided by the platform."
           }
         },
         "additionalProperties": false
       },
       "uiHints": {
-        "projectId": { "label": "Photon project ID" },
-        "projectSecret": { "label": "Photon project secret", "sensitive": true },
-        "allowFrom": { "label": "Allowed phone numbers" }
+        "projectId": {
+          "label": "Photon project ID"
+        },
+        "projectSecret": {
+          "label": "Photon project secret",
+          "sensitive": true
+        },
+        "allowFrom": {
+          "label": "Allowed phone numbers"
+        }
       }
     }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-imessage-photon",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "iMessage channel for OpenClaw via Photon Spectrum Cloud (no Mac required).",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,8 @@
     }
   },
   "dependencies": {
-    "spectrum-ts": "^12.8.0"
+    "spectrum-ts": "^12.8.0",
+    "typebox": "1.3.3"
   },
   "devDependencies": {
     "@types/node": "^22",