Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.1 KB
Raw Blame
/**
 * The GBrain Helper's iMessage routes, read over 127.0.0.1 only: `GET /v1/imessage/threads` (recent chats) and
 * `GET /v1/imessage/thread` (one chat's messages after a cursor). The token travels as a bearer header, never in a
 * query string. Failures map to the helper's own codes: nothing listening (`apple_helper_not_running`), a token the
 * helper refuses (`apple_helper_unauthorized`), Full Disk Access off (`apple_full_disk_access_pending`) and a Messages
 * database macOS changed (`apple_schema_mismatch`); each stops the whole run. Any other refusal is an item error.
 */
import { OperationError } from '../ops/contract.ts';
import { ConnectorHttpError, ConnectorResponseTooLargeError, type ConnectorFetch } from '../connectors/client.ts';
import type { IMessageMessage, IMessageThread } from '../imessage/types.ts';

/** Chats listed per run, most recent first (the helper's own maximum). */
export const IMESSAGE_THREADS_LIMIT = 200;
const MESSAGES_PAGE = 500;
/** Cursor pages one chat may walk in a run before the run stops partial. */
const MAX_PAGES = 200;
const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
const REQUEST_TIMEOUT_MS = 30_000;

/** A helper response missing a field it must carry: the chat is held, never published partially. */
export class IMessageShapeDriftError extends Error {
  readonly code = 'connector_shape_drift';
  constructor(what: string) {
    super(`imessage: the helper response is missing ${what}; the helper and gbrain may be out of step`);
    this.name = 'IMessageShapeDriftError';
  }
}

const DOCS = 'docs/guides/apple-setup.md';

export function helperNotRunning(sourceId: string, port: number | null, detail: string): OperationError {
  return new OperationError('apple_helper_not_running',
    port === null ? `iMessage source ${sourceId} has no helper port configured (${detail}). Nothing was imported.`
      : `Nothing answered on 127.0.0.1:${port} for iMessage source ${sourceId} (${detail}). The helper is stopped or the Mac is asleep. Nothing was imported.`,
    `Start GBrain Helper on this Mac and check that gbrain config get apple.helper.port names its port, then run: gbrain sync --source ${sourceId}`,
    `${DOCS}#apple_helper_not_running`);
}

function helperUnauthorized(sourceId: string): OperationError {
  return new OperationError('apple_helper_unauthorized', `GBrain Helper refused the token for iMessage source ${sourceId}. Nothing was imported.`,
    `Save the helper's current token for gbrain (the 0600 file ~/.gbrain/connectors/imessage.json, or the source's token variable), then run: gbrain sync --source ${sourceId}`,
    `${DOCS}#apple_helper_unauthorized`);
}

function fullDiskAccessPending(sourceId: string): OperationError {
  return new OperationError('apple_full_disk_access_pending', `GBrain Helper cannot read Messages for iMessage source ${sourceId}: Full Disk Access is off. Nothing was imported.`,
    `Ask the user to open System Settings > Privacy & Security > Full Disk Access and switch on GBrain Helper, then run: gbrain sync --source ${sourceId}`,
    `${DOCS}#apple_full_disk_access_pending`);
}

function schemaMismatch(sourceId: string): OperationError {
  return new OperationError('apple_schema_mismatch', `GBrain Helper does not recognise the Messages database for iMessage source ${sourceId}; macOS may have changed it. Nothing was imported.`,
    `Update GBrain and the GBrain Helper to their newest versions, then run: gbrain sync --source ${sourceId}`,
    `${DOCS}#apple_schema_mismatch`);
}

const str = (value: unknown): string | null => (typeof value === 'string' && value.length > 0 ? value : null);

export interface IMessageHelperOpts {
  sourceId: string;
  port: number;
  token: string;
  fetchImpl?: ConnectorFetch;
}

export interface IMessageHelper {
  threads(signal?: AbortSignal): Promise<IMessageThread[]>;
  /** Every message of one chat at or after `sinceIso`, oldest first. */
  messages(threadId: string, sinceIso: string, signal?: AbortSignal): Promise<IMessageMessage[]>;
}

export function imessageHelper(opts: IMessageHelperOpts): IMessageHelper {
  const fetchImpl = opts.fetchImpl ?? (fetch as unknown as ConnectorFetch);
  const base = `http://127.0.0.1:${opts.port}`;
  async function get(path: string, params: Record<string, string>, signal?: AbortSignal): Promise<Record<string, unknown>> {
    const url = `${base}${path}?${new URLSearchParams(params).toString()}`;
    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
    let res: Response;
    try {
      res = await fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${opts.token}`, accept: 'application/json' },
        redirect: 'manual', signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
    } catch (error) {
      if (signal?.aborted) throw error;
      throw helperNotRunning(opts.sourceId, opts.port, error instanceof Error ? error.message : String(error));
    }
    const text = await readBounded(res, path);
    let body: Record<string, unknown> = {};
    try { body = text ? JSON.parse(text) as Record<string, unknown> : {}; } catch { body = {}; }
    if (res.ok) return body;
    const code = str(body.code) ?? str((body.type as string | undefined)?.split('/').pop());
    if (res.status === 401 || code === 'unauthorized' || code === 'insufficient_scope') throw helperUnauthorized(opts.sourceId);
    if (code === 'source_disabled') throw helperNotRunning(opts.sourceId, opts.port, 'the helper has its iMessage source turned off');
    if (code === 'no_access') throw fullDiskAccessPending(opts.sourceId);
    if (code === 'schema_mismatch') throw schemaMismatch(opts.sourceId);
    throw new ConnectorHttpError(`imessage: the helper answered ${res.status}${code ? ` (${code})` : ''} for ${path}`, res.status);
  }
  return {
    async threads(signal) {
      const body = await get('/v1/imessage/threads', { limit: String(IMESSAGE_THREADS_LIMIT) }, signal);
      if (!Array.isArray(body.data)) throw new IMessageShapeDriftError('threads.data');
      return body.data.map((raw: Record<string, unknown>) => {
        const threadId = str(raw?.thread_id);
        if (!threadId) throw new IMessageShapeDriftError('threads.data[].thread_id');
        const lastMessageAt = raw.last_message_at ?? null;
        if (lastMessageAt !== null && !(typeof lastMessageAt === 'string' && Number.isFinite(Date.parse(lastMessageAt)))) {
          throw new IMessageShapeDriftError('threads.data[].last_message_at');
        }
        return { threadId, displayName: str(raw.display_name), participants: Array.isArray(raw.participants) ? raw.participants.filter((p): p is string => typeof p === 'string') : [],
          isGroup: raw.is_group === true, lastMessageAt };
      });
    },
    async messages(threadId, sinceIso, signal) {
      const out: IMessageMessage[] = [];
      let cursor: string | null = null;
      for (let page = 0; page < MAX_PAGES; page++) {
        const body = await get('/v1/imessage/thread', { thread_id: threadId, limit: String(MESSAGES_PAGE),
          ...(cursor ? { since_rowid: cursor } : { since_iso: sinceIso }) }, signal);
        const data = body.data as Record<string, unknown> | undefined;
        if (!data || !Array.isArray(data.messages)) throw new IMessageShapeDriftError('thread.data.messages');
        for (const raw of data.messages as Record<string, unknown>[]) out.push(parseMessage(raw));
        const meta = (body.meta ?? {}) as Record<string, unknown>;
        const more = data.has_more ?? meta.has_more;
        const next = data.next_since_rowid ?? meta.next_since_rowid;
        if (more !== true) return out.filter(m => m.timestamp >= sinceIso).sort((a, b) => a.timestamp.localeCompare(b.timestamp) || a.rowid - b.rowid);
        if (typeof next !== 'number' && typeof next !== 'string') throw new IMessageShapeDriftError('thread.next_since_rowid');
        cursor = String(next);
      }
      throw new ConnectorHttpError(`imessage: one chat returned more than ${MAX_PAGES} pages`, 500);
    },
  };
}

function parseMessage(raw: Record<string, unknown>): IMessageMessage {
  const id = str(raw?.id);
  const timestamp = str(raw?.timestamp);
  const rowid = Number(raw?.rowid);
  if (!id || !timestamp || !Number.isFinite(Date.parse(timestamp)) || !Number.isSafeInteger(rowid)) throw new IMessageShapeDriftError('thread.data.messages[] id, rowid or timestamp');
  const status = raw.text_status === 'empty' || raw.text_status === 'undecodable' ? raw.text_status : 'ok';
  return { id, rowid, timestamp: new Date(timestamp).toISOString(), isFromMe: raw.is_from_me === true, text: typeof raw.text === 'string' ? raw.text : null,
    textStatus: status, from: str(raw.from), hasAttachments: raw.has_attachments === true, editedAt: str(raw.edited_at), retracted: raw.retracted === true };
}

async function readBounded(res: Response, path: string): Promise<string> {
  if (!res.body) return res.text();
  const reader = res.body.getReader();
  const chunks: Uint8Array[] = [];
  let size = 0;
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    size += value.byteLength;
    if (size > MAX_RESPONSE_BYTES) {
      await reader.cancel().catch(() => {});
      throw new ConnectorResponseTooLargeError(path, MAX_RESPONSE_BYTES);
    }
    chunks.push(value);
  }
  return new TextDecoder().decode(Buffer.concat(chunks));
}