@xmanrui/dsh-im 4.17.0 → 4.18.0

package/plugin-src/host/channels/shared/startup.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../../../management-rpc.mjs';
 import { resolveRpcAuthority } from '../../rpc-authority.mjs';
 import { publicChannelInitializing, publicChannelStartupError } from './startup-error.mjs';
 
@@ -5,12 +6,9 @@ import { publicChannelInitializing, publicChannelStartupError } from './startup-
 export async function installProductionChannel(ctx, config, {
   channel, rpcChannel, createProduction, createHandler,
 }) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
   let startupError = publicChannelInitializing(channel);
   let handler = async () => ({ ok: false, error: startupError });
-  const disposeRpc = ctx.connection.rpc.handle(rpcChannel, (endpoint, payload, signal) => {
+  const disposeRpc = registerManagementRpc(ctx, rpcChannel, (endpoint, payload, signal) => {
     if (signal?.aborted) {
       return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.', details: {} } };
     }

package/plugin-src/host/channels/slack/rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../../../management-rpc.mjs';
 import { SET_CONTEXT_ENHANCEMENT_ENDPOINT, validContextEnhancementPayload } from '../shared/context-enhancement-rpc.mjs';
 import { SET_ACCESS_POLICY_ENDPOINT, validAccessPolicyPayload } from '../shared/access-policy-rpc.mjs';
 import { resolveRpcAuthority } from '../../rpc-authority.mjs';
@@ -200,10 +201,7 @@ export function createSlackRpcHandler(controller) {
 }
 
 export function installSlackRpc(ctx, controller, authority) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     SLACK_RPC_CHANNEL,
     createSlackRpcHandler(controller),
     { authority: resolveRpcAuthority(authority) },

package/plugin-src/host/channels/telegram/rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../../../management-rpc.mjs';
 import {
   TOKEN_BOT_ENDPOINTS,
   createTokenBotRpcHandler,
@@ -13,10 +14,7 @@ export function createTelegramRpcHandler(controller) {
 }
 
 export function installTelegramRpc(ctx, controller, authority) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     TELEGRAM_RPC_CHANNEL,
     createTelegramRpcHandler(controller),
     { authority: resolveRpcAuthority(authority) },

package/plugin-src/host/channels/wecom/rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../../../management-rpc.mjs';
 import QRCode from 'qrcode';
 import { SET_CONTEXT_ENHANCEMENT_ENDPOINT, validContextEnhancementPayload } from '../shared/context-enhancement-rpc.mjs';
 import { SET_ACCESS_POLICY_ENDPOINT, validAccessPolicyPayload } from '../shared/access-policy-rpc.mjs';
@@ -233,10 +234,7 @@ export function installWecomRpc(ctx, controller, options, authority) {
 
 /** Mount the existing Connection transport before the production controller is ready. */
 export function installWecomRpcHandler(ctx, handler, authority) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     WECOM_RPC_CHANNEL,
     handler,
     { authority: resolveRpcAuthority(authority) },

package/plugin-src/host/channels/wecom-app/rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../../../management-rpc.mjs';
 import { SET_CONTEXT_ENHANCEMENT_ENDPOINT, validContextEnhancementPayload } from '../shared/context-enhancement-rpc.mjs';
 import { SET_ACCESS_POLICY_ENDPOINT, validAccessPolicyPayload } from '../shared/access-policy-rpc.mjs';
 import { resolveRpcAuthority } from '../../rpc-authority.mjs';
@@ -214,10 +215,7 @@ export function createWecomAppRpcHandler(controller) {
 }
 
 export function installWecomAppRpc(ctx, controller, options, authority) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     WECOM_APP_RPC_CHANNEL,
     createWecomAppRpcHandler(controller, options),
     { authority: resolveRpcAuthority(authority) },

package/plugin-src/host/channels/weixin/rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../../../management-rpc.mjs';
 import QRCode from 'qrcode';
 import { SET_CONTEXT_ENHANCEMENT_ENDPOINT, validContextEnhancementPayload } from '../shared/context-enhancement-rpc.mjs';
 import { SET_ACCESS_POLICY_ENDPOINT, validAccessPolicyPayload } from '../shared/access-policy-rpc.mjs';
@@ -260,10 +261,7 @@ export function createWeixinRpcHandler(controller, { encodeQr = qrDataUrl } = {}
 }
 
 export function installWeixinRpc(ctx, controller, options, authority) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     WEIXIN_RPC_CHANNEL,
     createWeixinRpcHandler(controller, options),
     { authority: resolveRpcAuthority(authority) },

package/plugin-src/host/channels/whatsapp/rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../../../management-rpc.mjs';
 import QRCode from 'qrcode';
 
 import { publicConnectionTestResult } from '../../../../src/channels/shared/connection-test.mjs';
@@ -218,10 +219,7 @@ export function createWhatsappRpcHandler(controller, { encodeQr = qrDataUrl } =
 }
 
 export function installWhatsappRpc(ctx, controller, options, authority) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     WHATSAPP_RPC_CHANNEL,
     createWhatsappRpcHandler(controller, options),
     { authority: resolveRpcAuthority(authority) },

package/plugin-src/host/delivery-adapter.mjs

@@ -15,6 +15,7 @@ const CHANNELS = new Set([
   'telegram',
   'discord',
   'whatsapp',
+  'imessage',
 ]);
 
 export function supportsDeliveryChannel(channel) {
@@ -122,6 +123,9 @@ function normalizeRoute(channel, kind, route) {
       }
       return normalized;
     }
+    case 'imessage':
+      oneOf(kind, ['user']);
+      return routeWithStrings(route, ['chatGuid']);
     default:
       throw new TypeError(`Unsupported delivery channel: ${channel}`);
   }

package/plugin-src/host/delivery-rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../management-rpc.mjs';
 import { resolveRpcAuthority } from './rpc-authority.mjs';
 
 export const DELIVERY_RPC_CHANNEL = '/dsh-im-delivery';
@@ -159,10 +160,7 @@ export function createDeliveryRpcHandler(service) {
 }
 
 export function installDeliveryRpc(ctx, service, { authority } = {}) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     DELIVERY_RPC_CHANNEL,
     createDeliveryRpcHandler(service),
     { authority: resolveRpcAuthority(authority) },

package/plugin-src/host/inbound-ttl-rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../management-rpc.mjs';
 import { normalizeInboundTtlHours } from '../../src/channels/shared/inbound-ttl.mjs';
 import { getInboundTtlRuntime } from './inbound-ttl-runtime.mjs';
 
@@ -69,13 +70,10 @@ export function createInboundTtlRpcHandler({ store, service, logger = null } = {
 }
 
 export function installInboundTtlRpc(ctx, options = {}) {
-  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
-    throw new TypeError('DSH Host Connection RPC is required');
-  }
   const runtime = options.runtime ?? getInboundTtlRuntime(ctx, options.config);
   const logger = typeof ctx?.logger === 'function'
     ? ctx.logger('dsh-im:inbound-ttl') : (ctx?.logger ?? null);
-  return ctx.connection.rpc.handle(
+  return registerManagementRpc(ctx,
     INBOUND_TTL_RPC_CHANNEL,
     createInboundTtlRpcHandler({ ...runtime, logger }),
     { authority: 'loopback' },

package/plugin-src/host/index.mjs

@@ -9,6 +9,7 @@ import { apply as applyWecom } from './channels/wecom/index.mjs';
 import { apply as applyWecomApp } from './channels/wecom-app/index.mjs';
 import { apply as applyWeixin } from './channels/weixin/index.mjs';
 import { apply as applyWhatsapp } from './channels/whatsapp/index.mjs';
+import { apply as applyIMessage } from './channels/imessage/index.mjs';
 import { installOutboundArtifactTool } from '../../src/channels/shared/semantic/artifact.mjs';
 import { setImHostLanguage } from '../../src/channels/shared/i18n.mjs';
 import { installDeliveryRpc } from './delivery-rpc.mjs';
@@ -53,6 +54,7 @@ export function createImHostPlugin(internals = {}) {
   const startDiscord = internals.applyDiscord ?? applyDiscord;
   const startOffice = internals.applyOffice ?? applyOffice;
   const startWhatsapp = internals.applyWhatsapp ?? applyWhatsapp;
+  const startIMessage = internals.applyIMessage ?? applyIMessage;
   const channels = [
     ['feishu', startFeishu],
     ['weixin', startWeixin],
@@ -64,6 +66,7 @@ export function createImHostPlugin(internals = {}) {
     ['telegram', startTelegram],
     ['discord', startDiscord],
     ['whatsapp', startWhatsapp],
+    ['imessage', startIMessage],
     ['office', startOffice],
   ];
   return Object.freeze({
@@ -130,7 +133,7 @@ export function createImHostPlugin(internals = {}) {
     const logger = typeof ctx?.logger === 'function'
       ? ctx.logger(name)
       : (ctx?.logger ?? console);
-    if (ctx?.connection?.rpc) {
+    if (ctx?.connection?.fetch) {
       try {
         startUpdate(ctx);
       } catch (error) {

package/plugin-src/host/modern-harness-api.mjs

@@ -5,7 +5,7 @@ import { hasActiveHarnessInteractionOwner } from '../../src/channels/shared/harn
 const modernApis = new WeakMap();
 
 function failureOf(error) {
-  const failure = error?.failure;
+  const failure = error?.failure ?? (error?.isDSHRemoteError === true ? error : undefined);
   if (failure && typeof failure === 'object'
     && typeof failure.code === 'string'
     && typeof failure.message === 'string') {

package/plugin-src/host/update-rpc.mjs

@@ -1,3 +1,4 @@
+import { registerManagementRpc } from '../management-rpc.mjs';
 import { createUpdateRuntime } from './update-runtime.mjs';
 import { createUpdateService } from './update-service.mjs';
 
@@ -42,7 +43,7 @@ export function createUpdateRpcHandler(service) {
 export function installUpdateRpc(ctx, options = {}) {
   const runtime = options.runtime ?? createUpdateRuntime({ ctx, moduleUrl: import.meta.url });
   const service = options.service ?? createUpdateService({ runtime });
-  const dispose = ctx.connection.rpc.handle(UPDATE_RPC_CHANNEL, createUpdateRpcHandler(service), {
+  const dispose = registerManagementRpc(ctx, UPDATE_RPC_CHANNEL, createUpdateRpcHandler(service), {
     authority: 'loopback',
   });
   ctx.effect(() => () => service.close(), 'dsh-im: close update installer');

package/plugin-src/management-rpc.mjs

@@ -0,0 +1,77 @@
+import { resolveRpcAuthority } from './host/rpc-authority.mjs';
+
+function rpcEndpoint(channel) {
+  if (!/^\/[A-Za-z0-9._~-]+$/.test(channel)) throw new TypeError('Invalid IM RPC channel');
+  return `dsh-im${channel}`;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isLoopbackAuthority(authority) {
+  if (!authority) return false;
+  try {
+    const url = new URL(`http://${authority}`);
+    if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) return false;
+    const hostname = url.hostname.replace(/\.$/, '');
+    return hostname === 'localhost' || hostname === '[::1]'
+      || /^127\.\d+\.\d+\.\d+$/.test(hostname);
+  } catch { return false; }
+}
+
+function isLoopbackRequest(request) {
+  if (!isLoopbackAuthority(request.headers.get('host'))) return false;
+  const origin = request.headers.get('origin');
+  if (origin === null) return true;
+  try {
+    const url = new URL(origin);
+    return ['http:', 'https:'].includes(url.protocol) && isLoopbackAuthority(url.host);
+  } catch { return false; }
+}
+
+function reply(rpcId, result) {
+  // Older endpoint handlers omit details; Connection's client requires the field.
+  const value = result.ok === false
+    ? { ...result, error: { ...result.error, details: result.error.details ?? {} } } : result;
+  return Response.json({ type: 'server-response', rpcId, result: value });
+}
+
+/** Register an IM channel through the public /api carrier shared by supported DSH releases. */
+export function registerManagementRpc(ctx, channel, handler, { authority } = {}) {
+  const policy = resolveRpcAuthority(authority);
+  const endpoint = rpcEndpoint(channel);
+  if (typeof ctx?.connection?.fetch?.register !== 'function') {
+    throw new TypeError('DSH Host Connection Fetch registry is required');
+  }
+  return ctx.connection.fetch.register({
+    path: `/api/${endpoint}`,
+    methods: ['POST'],
+    requestBody: 'buffered',
+    async fetch(request) {
+      // DSH applies browser authentication and Host/Origin trust before this handler.
+      if (policy === 'loopback' && !isLoopbackRequest(request)) return new Response('forbidden', { status: 403 });
+      if (request.method !== 'POST') return new Response('method not allowed', { status: 405 });
+      if (request.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase() !== 'application/json') {
+        return new Response('content type must be application/json', { status: 415 });
+      }
+      let message;
+      try { message = await request.json(); }
+      catch { return new Response('body is not JSON', { status: 400 }); }
+      const rpcId = typeof message?.rpcId === 'string' ? message.rpcId : 'invalid-request';
+      const call = message?.payload;
+      if (!isRecord(message) || message.type !== 'client-request' || typeof message.rpcId !== 'string'
+        || message.method !== endpoint || !isRecord(call) || typeof call.method !== 'string'
+        || !Object.hasOwn(call, 'payload')) {
+        return reply(rpcId, { ok: false, error: { code: 'gateway/bad-request', message: 'Invalid IM management request.' } });
+      }
+      try { return reply(rpcId, await handler(call.method, call.payload, request.signal)); }
+      catch { return new Response('IM management handler failed', { status: 500 }); }
+    },
+  });
+}
+
+/** Keep channel UI callers unchanged while using DSH's native correlation and response validation. */
+export function callManagementRpc(connection, channel, method, payload, signal) {
+  return connection.rpc.call('/api', rpcEndpoint(channel), { method, payload }, signal);
+}

package/src/channels/imessage/config-store.mjs

@@ -0,0 +1,24 @@
+import {
+  deriveTokenBotIdentity,
+  maskPlatformId,
+  TokenBotConfigStore,
+} from '../shared/token-config-store.mjs';
+
+const IDENTITY_OPTIONS = Object.freeze({
+  botPrefix: 'imessage',
+  tokenRefPrefix: 'DSH_IMESSAGE_PASSWORD',
+});
+
+export function deriveIMessageBotIdentity(platformId) {
+  return deriveTokenBotIdentity(platformId, IDENTITY_OPTIONS);
+}
+
+export function maskIMessageBotId(platformId) {
+  return maskPlatformId(platformId, 'iMessage 网关');
+}
+
+export class IMessageConfigStore extends TokenBotConfigStore {
+  constructor(path) {
+    super(path, { channel: 'iMessage', ...IDENTITY_OPTIONS });
+  }
+}

package/src/channels/imessage/controller.mjs

@@ -0,0 +1,37 @@
+import { TokenBotController } from '../shared/token-bot-controller.mjs';
+import { MacOSMessagesApi } from './imessage-api.mjs';
+import {
+  deriveIMessageBotIdentity,
+  maskIMessageBotId,
+} from './config-store.mjs';
+import { IMESSAGE_DESCRIPTOR } from './imessage-bridge.mjs';
+
+const NATIVE_CREDENTIAL = 'macos-messages-native';
+
+export async function inspectIMessageCredential(value, { api = new MacOSMessagesApi() } = {}) {
+  if (value !== NATIVE_CREDENTIAL) throw new TypeError('Invalid native iMessage credential');
+  const permissions = await api.getPermissions();
+  return { platformId: 'macos-messages', name: 'Mac Messages', permissions };
+}
+
+export class IMessageController extends TokenBotController {
+  constructor(options) {
+    super({
+      ...options,
+      descriptor: IMESSAGE_DESCRIPTOR,
+      inspectToken: options.inspectToken ?? inspectIMessageCredential,
+      deriveIdentity: deriveIMessageBotIdentity,
+      maskPlatformId: maskIMessageBotId,
+    });
+  }
+
+  async bindNative() {
+    return super.bindCredentials({ token: NATIVE_CREDENTIAL });
+  }
+
+  async permissions() {
+    return new MacOSMessagesApi().getPermissions();
+  }
+}
+
+export { NATIVE_CREDENTIAL };

package/src/channels/imessage/harness-client.mjs

@@ -0,0 +1,7 @@
+import { HarnessClient } from '../shared/harness-client.mjs';
+
+export class IMessageHarnessClient extends HarnessClient {
+  constructor(options) {
+    super({ ...options, rpcIdPrefix: 'imessage', logPrefix: 'dsh-imessage' });
+  }
+}

package/src/channels/imessage/imessage-api.mjs

@@ -0,0 +1,194 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const DEFAULT_DB_PATH = `${process.env.HOME ?? ''}/Library/Messages/chat.db`;
+const DEFAULT_TIMEOUT_MS = 15_000;
+// Self-chat has no separate bot sender. Keep the reply marker in Messages itself
+// so echoes are still recognizable after a Host restart or iCloud resync.
+export const IMESSAGE_BOT_REPLY_PREFIX = '🤖 DSH\n';
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function normalizeChatGuid(value) {
+  const chatGuid = cleanString(value?.chatGuid ?? value);
+  if (!chatGuid || chatGuid.length > 512 || /[\r\n]/.test(chatGuid)) {
+    throw new TypeError('iMessage chatGuid is required');
+  }
+  return chatGuid;
+}
+
+function normalizeAddress(value) {
+  const address = cleanString(value);
+  if (!address || address.length > 512 || /[\r\n]/.test(address)) {
+    throw new TypeError('iMessage address is required');
+  }
+  return address;
+}
+
+function permissionError(kind, message, cause) {
+  const error = new Error(message, { cause });
+  error.code = kind;
+  return error;
+}
+
+function sqlString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function decodeRows(stdout) {
+  const text = String(stdout ?? '').trim();
+  if (!text) return [];
+  try {
+    const rows = JSON.parse(text);
+    return Array.isArray(rows) ? rows : [];
+  } catch (error) {
+    throw new Error('macOS Messages returned invalid database output', { cause: error });
+  }
+}
+
+function appleScriptString(value) {
+  return JSON.stringify(String(value));
+}
+
+export function normalizeIMessageTarget(value) {
+  return normalizeChatGuid(value);
+}
+
+export function normalizeIMessage(value, { botId } = {}) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.serviceName !== undefined && value.serviceName !== 'iMessage') return null;
+  const guid = cleanString(value.guid ?? value.id);
+  const chatGuid = cleanString(value.chatGuid ?? value.chat_guid);
+  const text = cleanString(value.text);
+  const sender = cleanString(value.sender ?? value.handle_id);
+  if (!guid || !chatGuid || !text || !sender) return null;
+  if (text.startsWith(IMESSAGE_BOT_REPLY_PREFIX)) return null;
+  if (value.isFromMe === 1 || value.isFromMe === true) return null;
+  if (botId && sender === botId) return null;
+  return Object.freeze({
+    messageId: guid,
+    providerMessageId: guid,
+    conversationId: chatGuid,
+    kind: 'direct',
+    senderId: sender,
+    senderName: sender,
+    content: text,
+    addressed: true,
+    replyTarget: { chatGuid, address: sender, serviceName: 'iMessage' },
+    connectionTestTarget: { chatGuid, address: sender, serviceName: 'iMessage' },
+    ...(value.receivedAt ? { receivedAt: value.receivedAt } : {}),
+  });
+}
+
+export class MacOSMessagesApi {
+  #dbPath;
+  #execFile;
+  #execFileOptions;
+  #osascript;
+
+  constructor({ dbPath = DEFAULT_DB_PATH, execFileImpl = execFileAsync, osascriptImpl } = {}) {
+    this.#dbPath = dbPath;
+    this.#execFile = execFileImpl;
+    this.#execFileOptions = { timeout: DEFAULT_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 };
+    this.#osascript = osascriptImpl ?? ((script) => this.#execFile('/usr/bin/osascript', ['-e', script], this.#execFileOptions));
+    if (typeof this.#execFile !== 'function' || typeof this.#osascript !== 'function') {
+      throw new TypeError('MacOSMessagesApi requires command runners');
+    }
+  }
+
+  async getPermissions() {
+    const result = { platform: process.platform, database: 'unknown', automation: 'unknown' };
+    if (process.platform !== 'darwin') {
+      return { ...result, database: 'unsupported', automation: 'unsupported' };
+    }
+    try {
+      await this.#execFile('/usr/bin/sqlite3', ['-json', this.#dbPath, 'SELECT 1 AS ok LIMIT 1;'], this.#execFileOptions);
+      result.database = 'granted';
+    } catch (error) {
+      result.database = /authorization denied|not authorized|unable to open database/i.test(String(error?.stderr ?? error))
+        ? 'required' : 'error';
+    }
+    try {
+      await this.#osascript('tell application "Messages" to get name');
+      result.automation = 'granted';
+    } catch (error) {
+      result.automation = /not authorized|(-1743)|assistive/i.test(String(error?.stderr ?? error))
+        ? 'required' : 'error';
+    }
+    return result;
+  }
+
+  async listMessages({ after = 0, limit = 50, chatGuid } = {}) {
+    const cursor = Number.isSafeInteger(after) && after >= 0 ? after : 0;
+    const boundedLimit = Math.max(1, Math.min(100, Number(limit) || 50));
+    const chatFilter = chatGuid ? ` AND c.guid = ${sqlString(normalizeChatGuid(chatGuid))}` : '';
+    // Messages delivers self-chat back as an incoming copy. Read that copy once,
+    // keeping all outgoing rows excluded, and filter bot replies by their marker.
+    const query = `SELECT m.ROWID AS rowid, m.guid AS guid, m.text AS text,
+      h.id AS sender, c.guid AS chatGuid, c.service_name AS serviceName,
+      m.is_from_me AS isFromMe,
+      datetime((m.date / 1000000000) + 978307200, 'unixepoch') AS receivedAt
+      FROM message m
+      JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+      JOIN chat c ON c.ROWID = cmj.chat_id
+      LEFT JOIN handle h ON h.ROWID = m.handle_id
+      WHERE m.ROWID > ${cursor} AND m.is_from_me = 0
+        AND m.text IS NOT NULL AND m.text != ''
+        AND c.service_name = 'iMessage'${chatFilter}
+      ORDER BY m.ROWID ASC LIMIT ${boundedLimit};`;
+    try {
+      const { stdout } = await this.#execFile('/usr/bin/sqlite3', ['-json', this.#dbPath, query], this.#execFileOptions);
+      return decodeRows(stdout);
+    } catch (error) {
+      if (/authorization denied|not authorized|unable to open database/i.test(String(error?.stderr ?? error))) {
+        throw permissionError('messages-database-permission-required', '请在系统设置中授予 DeepSeek Harness 完全磁盘访问权限。', error);
+      }
+      throw error;
+    }
+  }
+
+  async getLatestMessageRowId() {
+    if (process.platform !== 'darwin') return 0;
+    const query = `SELECT COALESCE(MAX(m.ROWID), 0) AS rowid
+      FROM message m
+      JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+      JOIN chat c ON c.ROWID = cmj.chat_id
+      WHERE c.service_name = 'iMessage';`;
+    const { stdout } = await this.#execFile(
+      '/usr/bin/sqlite3', ['-json', this.#dbPath, query], this.#execFileOptions,
+    );
+    const rows = decodeRows(stdout);
+    const rowid = Number(rows[0]?.rowid ?? 0);
+    return Number.isSafeInteger(rowid) && rowid >= 0 ? rowid : 0;
+  }
+
+  async sendText({ chatGuid, address, text } = {}) {
+    const target = normalizeChatGuid(chatGuid);
+    const recipient = address ? normalizeAddress(address) : target.split(';').at(-1) || target;
+    const content = cleanString(text);
+    if (!content) throw new TypeError('iMessage text is required');
+    const reply = content.startsWith(IMESSAGE_BOT_REPLY_PREFIX)
+      ? content : `${IMESSAGE_BOT_REPLY_PREFIX}${content}`;
+    const script = `tell application "Messages"
+      set serviceList to every service whose service type = iMessage
+      if (count of serviceList) is 0 then error "No iMessage service is available"
+      set targetService to item 1 of serviceList
+      set targetBuddy to buddy ${appleScriptString(recipient)} of targetService
+      send ${appleScriptString(reply)} to targetBuddy
+    end tell`;
+    try {
+      await this.#osascript(script);
+      return { sent: true };
+    } catch (error) {
+      if (/not authorized|(-1743)|assistive/i.test(String(error?.stderr ?? error))) {
+        throw permissionError('messages-automation-permission-required', '请在系统设置中允许 DeepSeek Harness 自动化控制 Messages。', error);
+      }
+      throw error;
+    }
+  }
+}
+
+export { DEFAULT_DB_PATH };

package/src/channels/imessage/imessage-bridge.mjs

@@ -0,0 +1,16 @@
+import { TextHarnessBridge, createTextBridgeStatus } from '../shared/text-harness-bridge.mjs';
+
+export const IMESSAGE_DESCRIPTOR = Object.freeze({
+  key: 'imessage',
+  label: 'iMessage',
+  connectionLabel: ' macOS Messages 连接',
+  reactions: Object.freeze({ processing: '👀', success: '✅', error: '❌' }),
+});
+
+export class IMessageHarnessBridge extends TextHarnessBridge {
+  constructor(options) {
+    super({ ...options, descriptor: IMESSAGE_DESCRIPTOR });
+  }
+}
+
+export { createTextBridgeStatus as createIMessageBridgeStatus };