@moxxy/plugin-channel-imessage 0.29.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+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/dist/bluebubbles-client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The BlueBubbles transport seam (the "sidecar" equivalent for iMessage).
+ *
+ * BlueBubbles is a native macOS app running a localhost Koa + socket.io server
+ * (default port 1234). We hit it directly over `http://127.0.0.1:1234`:
+ *  - inbound: a socket.io client subscribed to `new-message` (built-in
+ *    reconnection; no webhook lifecycle),
+ *  - outbound: `POST /api/v1/message/text` with `method: 'apple-script'`.
+ *
+ * Auth is a single password passed as a QUERY PARAM on every call (BlueBubbles
+ * never reads it from a header). There is no HMAC on the socket feed — pure
+ * localhost trust — so the consumer must stay bound to loopback.
+ *
+ * The channel drives this behind {@link BlueBubblesClientLike} so tests inject a
+ * fake and no socket.io / network is touched. `socket.io-client` is imported
+ * lazily inside {@link BlueBubblesClient.connect} so module load (and
+ * `isAvailable`) stays light.
+ */
+export interface BlueBubblesClientLike {
+    /** Best-effort reachability + auth probe; throws a friendly error on failure. */
+    ping(): Promise<void>;
+    /** Open the socket.io connection and begin emitting inbound messages. */
+    connect(): Promise<void>;
+    /** Subscribe to raw `new-message` payloads. Returns an unsubscribe fn. */
+    onMessage(listener: (raw: unknown) => void): () => void;
+    /**
+     * Send a text message. `tempGuid` correlates the send with its echoed
+     * `new-message`; the returned `guid` (when the server reports it) is the
+     * permanent id. Both feed the anti-echo set.
+     */
+    sendText(chatGuid: string, message: string): Promise<{
+        guid: string | null;
+        tempGuid: string;
+    }>;
+    /** Tear down the socket. */
+    close(): void;
+}
+export interface BlueBubblesClientLogger {
+    debug?(msg: string, meta?: Record<string, unknown>): void;
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+/** Minimal slice of a socket.io client the channel uses (keeps typing loose). */
+export interface SocketLike {
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    close(): void;
+}
+export interface BlueBubblesClientOptions {
+    readonly serverUrl: string;
+    readonly password: string;
+    readonly logger?: BlueBubblesClientLogger;
+    /** Test seam: injectable fetch (defaults to global fetch). */
+    readonly fetchImpl?: typeof fetch;
+    /** Test seam: injectable socket factory (defaults to lazy socket.io-client). */
+    readonly socketFactory?: (opts: {
+        url: string;
+        password: string;
+    }) => Promise<SocketLike>;
+}
+/** A fresh per-send temp guid (correlates our send with its echoed message). */
+export declare function makeTempGuid(): string;
+export declare class BlueBubblesClient implements BlueBubblesClientLike {
+    private readonly opts;
+    private readonly base;
+    private socket;
+    private readonly messageListeners;
+    constructor(opts: BlueBubblesClientOptions);
+    ping(): Promise<void>;
+    connect(): Promise<void>;
+    onMessage(listener: (raw: unknown) => void): () => void;
+    sendText(chatGuid: string, message: string): Promise<{
+        guid: string | null;
+        tempGuid: string;
+    }>;
+    close(): void;
+    /** Build an absolute API URL with the password query param appended. */
+    private apiUrl;
+}
+//# sourceMappingURL=bluebubbles-client.d.ts.map

package/dist/bluebubbles-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluebubbles-client.d.ts","sourceRoot":"","sources":["../src/bluebubbles-client.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,yEAAyE;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,0EAA0E;IAC1E,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChG,4BAA4B;IAC5B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAChE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IAC1C,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3F;AAED,gFAAgF;AAChF,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,qBAAa,iBAAkB,YAAW,qBAAqB;IAC7D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA2B;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;gBAE1D,IAAI,EAAE,wBAAwB;IAMpC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB9B,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;IAKjD,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAgBrD,KAAK,IAAI,IAAI;IAab,wEAAwE;IACxE,OAAO,CAAC,MAAM;CAKf"}

package/dist/bluebubbles-client.js

@@ -0,0 +1,113 @@
+import { randomUUID } from 'node:crypto';
+/** A fresh per-send temp guid (correlates our send with its echoed message). */
+export function makeTempGuid() {
+    return `temp-${randomUUID()}`;
+}
+export class BlueBubblesClient {
+    opts;
+    base;
+    socket = null;
+    messageListeners = new Set();
+    constructor(opts) {
+        this.opts = opts;
+        // Normalize the base URL once (strip a trailing slash) so path joins are clean.
+        this.base = opts.serverUrl.trim().replace(/\/+$/, '');
+    }
+    async ping() {
+        const doFetch = this.opts.fetchImpl ?? fetch;
+        let res;
+        try {
+            res = await doFetch(this.apiUrl('/api/v1/ping'));
+        }
+        catch (err) {
+            throw new Error(`Cannot reach the BlueBubbles server at ${this.base}. Is it running on this Mac? ` +
+                `(${err instanceof Error ? err.message : String(err)})`);
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new Error('The BlueBubbles server rejected the password. Check the password in the BlueBubbles app matches the one stored for moxxy.');
+        }
+        // Any other HTTP response means something is listening — reachable enough.
+    }
+    async connect() {
+        const factory = this.opts.socketFactory ?? ((o) => defaultSocketFactory(o));
+        const socket = await factory({ url: this.base, password: this.opts.password });
+        this.socket = socket;
+        socket.on('new-message', (...args) => {
+            const payload = args.length > 0 ? args[0] : undefined;
+            for (const listener of this.messageListeners) {
+                try {
+                    listener(payload);
+                }
+                catch (err) {
+                    this.opts.logger?.warn?.('imessage: message listener threw', { err: String(err) });
+                }
+            }
+        });
+        socket.on('disconnect', (...args) => {
+            this.opts.logger?.debug?.('imessage: socket disconnected (auto-reconnecting)', {
+                reason: String(args.length > 0 ? args[0] : ''),
+            });
+        });
+    }
+    onMessage(listener) {
+        this.messageListeners.add(listener);
+        return () => this.messageListeners.delete(listener);
+    }
+    async sendText(chatGuid, message) {
+        const doFetch = this.opts.fetchImpl ?? fetch;
+        const tempGuid = makeTempGuid();
+        const res = await doFetch(this.apiUrl('/api/v1/message/text'), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ chatGuid, tempGuid, message, method: 'apple-script' }),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new Error(`BlueBubbles send failed (HTTP ${res.status})${detail ? `: ${detail}` : ''}`);
+        }
+        const guid = await extractGuid(res);
+        return { guid, tempGuid };
+    }
+    close() {
+        this.messageListeners.clear();
+        const socket = this.socket;
+        this.socket = null;
+        if (socket) {
+            try {
+                socket.close();
+            }
+            catch (err) {
+                this.opts.logger?.warn?.('imessage: socket close threw', { err: String(err) });
+            }
+        }
+    }
+    /** Build an absolute API URL with the password query param appended. */
+    apiUrl(path) {
+        const url = new URL(this.base + path);
+        url.searchParams.set('password', this.opts.password);
+        return url.toString();
+    }
+}
+/** Read the sent message's permanent guid from the send response, if present. */
+async function extractGuid(res) {
+    const body = await res.json().catch(() => null);
+    if (!body || typeof body !== 'object')
+        return null;
+    const data = body.data;
+    if (!data || typeof data !== 'object')
+        return null;
+    const guid = data.guid;
+    return typeof guid === 'string' && guid.length > 0 ? guid : null;
+}
+/** Lazily import socket.io-client and open a connection to the BlueBubbles feed. */
+async function defaultSocketFactory(opts) {
+    const { io } = await import('socket.io-client');
+    const socket = io(opts.url, {
+        query: { password: opts.password },
+        transports: ['websocket'],
+        // BlueBubbles' socket.io has built-in reconnection; keep it on.
+        reconnection: true,
+    });
+    return socket;
+}
+//# sourceMappingURL=bluebubbles-client.js.map

package/dist/bluebubbles-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluebubbles-client.js","sourceRoot":"","sources":["../src/bluebubbles-client.ts"],"names":[],"mappings":"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"}

package/dist/channel/chunker.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Buffered chunked sends — iMessage's streaming strategy.
+ *
+ * WHY NOT FramePump edits: editing a sent iMessage requires the BlueBubbles
+ * Private API (a Helper bundle injected into Messages, which needs SIP disabled)
+ * — out of scope for v1's stock apple-script server. With apple-script every
+ * message is immutable once sent, so instead of "send once then edit" we buffer
+ * the streamed text and send coherent chunks: nothing goes out until a
+ * paragraph-aligned chunk is ready, and the remainder goes out once, at turn
+ * end. (Copied from the Signal channel's chunker, which faces the same
+ * immutable-message constraint.)
+ */
+/** Buffered text below this length is held for the final flush. */
+export declare const IMESSAGE_CHUNK_SOFT_LIMIT = 1500;
+/**
+ * Never send a single message longer than this. iMessage itself allows long
+ * bodies, but clients render extremely long messages poorly; 2000 mirrors the
+ * Signal channel's cap for parity.
+ */
+export declare const IMESSAGE_CHUNK_HARD_LIMIT = 2000;
+export interface ChunkLimits {
+    readonly softLimit?: number;
+    readonly hardLimit?: number;
+}
+/**
+ * If `text` has grown past the soft limit, split off one send-ready chunk at
+ * the best boundary (paragraph → line → word) at or below the hard limit.
+ * Returns null while the text should keep buffering.
+ */
+export declare function takeChunk(text: string, limits?: ChunkLimits): {
+    chunk: string;
+    rest: string;
+} | null;
+/** Split a final remainder into hard-limit-sized pieces at the best boundaries. */
+export declare function splitForImessage(text: string, limits?: ChunkLimits): string[];
+export interface ChunkedSenderOptions {
+    /** Deliver one message. Errors should be handled by the caller-supplied fn
+     *  (log + swallow) — a failed chunk must never abort the turn. */
+    readonly send: (text: string) => Promise<void>;
+    readonly limits?: ChunkLimits;
+}
+/**
+ * Drives {@link takeChunk} over a GROWING renderer snapshot: `offer()` on every
+ * change (sends any ready chunk), `finalize()` at turn end (sends the
+ * remainder, or `emptyText` when the whole turn produced nothing). Sends are
+ * serialized on an internal queue so chunks can never interleave out of order.
+ */
+export declare class ChunkedSender {
+    private readonly opts;
+    /** The exact snapshot prefix already delivered (chunk boundaries included). */
+    private sentPrefix;
+    private sentAnything;
+    private queue;
+    constructor(opts: ChunkedSenderOptions);
+    /** Called with the current full snapshot whenever it changes. */
+    offer(snapshot: string): void;
+    /**
+     * Turn end: deliver whatever the final snapshot still owes. When the final
+     * text no longer extends what we already sent (a divergent final frame —
+     * rare), send the full final text so the user always receives the
+     * authoritative reply, accepting the duplication.
+     */
+    finalize(snapshot: string, emptyText?: string): Promise<void>;
+    private deliver;
+}
+//# sourceMappingURL=chunker.d.ts.map

package/dist/channel/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../src/channel/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAC/C;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,OAAQ,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,WAAgB,GACvB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBxC;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,WAAgB,GAAG,MAAM,EAAE,CAcjF;AAED,MAAM,WAAW,oBAAoB;IACnC;sEACkE;IAClE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,+EAA+E;IAC/E,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAoC;gBAErC,IAAI,EAAE,oBAAoB;IAItC,iEAAiE;IACjE,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAiB7B;;;;;OAKG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAkBrD,OAAO;CAMtB"}

package/dist/channel/chunker.js

@@ -0,0 +1,130 @@
+/**
+ * Buffered chunked sends — iMessage's streaming strategy.
+ *
+ * WHY NOT FramePump edits: editing a sent iMessage requires the BlueBubbles
+ * Private API (a Helper bundle injected into Messages, which needs SIP disabled)
+ * — out of scope for v1's stock apple-script server. With apple-script every
+ * message is immutable once sent, so instead of "send once then edit" we buffer
+ * the streamed text and send coherent chunks: nothing goes out until a
+ * paragraph-aligned chunk is ready, and the remainder goes out once, at turn
+ * end. (Copied from the Signal channel's chunker, which faces the same
+ * immutable-message constraint.)
+ */
+/** Buffered text below this length is held for the final flush. */
+export const IMESSAGE_CHUNK_SOFT_LIMIT = 1_500;
+/**
+ * Never send a single message longer than this. iMessage itself allows long
+ * bodies, but clients render extremely long messages poorly; 2000 mirrors the
+ * Signal channel's cap for parity.
+ */
+export const IMESSAGE_CHUNK_HARD_LIMIT = 2_000;
+/**
+ * If `text` has grown past the soft limit, split off one send-ready chunk at
+ * the best boundary (paragraph → line → word) at or below the hard limit.
+ * Returns null while the text should keep buffering.
+ */
+export function takeChunk(text, limits = {}) {
+    const soft = limits.softLimit ?? IMESSAGE_CHUNK_SOFT_LIMIT;
+    const hard = limits.hardLimit ?? IMESSAGE_CHUNK_HARD_LIMIT;
+    if (text.length <= soft)
+        return null;
+    const window = text.slice(0, Math.min(text.length, hard));
+    // Prefer a paragraph break; a chunk that ends mid-sentence reads badly as a
+    // standalone message. Require the boundary to keep a meaningful chunk (≥ half
+    // the soft limit) so a leading blank line can't produce confetti.
+    const minCut = Math.floor(soft / 2);
+    for (const boundary of ['\n\n', '\n', ' ']) {
+        const at = window.lastIndexOf(boundary);
+        if (at >= minCut) {
+            return { chunk: window.slice(0, at).trimEnd(), rest: text.slice(at + boundary.length) };
+        }
+    }
+    if (text.length <= hard)
+        return null; // no boundary yet — wait for more text
+    return { chunk: window, rest: text.slice(window.length) }; // pathological: hard cut
+}
+/** Split a final remainder into hard-limit-sized pieces at the best boundaries. */
+export function splitForImessage(text, limits = {}) {
+    const hard = limits.hardLimit ?? IMESSAGE_CHUNK_HARD_LIMIT;
+    const parts = [];
+    let rest = text;
+    while (rest.length > hard) {
+        // Reuse takeChunk with soft==hard-ish so it only splits when forced.
+        const taken = takeChunk(rest, { softLimit: Math.floor(hard / 2), hardLimit: hard });
+        if (!taken)
+            break;
+        if (taken.chunk)
+            parts.push(taken.chunk);
+        rest = taken.rest;
+    }
+    const tail = rest.trim();
+    if (tail)
+        parts.push(tail);
+    return parts;
+}
+/**
+ * Drives {@link takeChunk} over a GROWING renderer snapshot: `offer()` on every
+ * change (sends any ready chunk), `finalize()` at turn end (sends the
+ * remainder, or `emptyText` when the whole turn produced nothing). Sends are
+ * serialized on an internal queue so chunks can never interleave out of order.
+ */
+export class ChunkedSender {
+    opts;
+    /** The exact snapshot prefix already delivered (chunk boundaries included). */
+    sentPrefix = '';
+    sentAnything = false;
+    queue = Promise.resolve();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Called with the current full snapshot whenever it changes. */
+    offer(snapshot) {
+        this.queue = this.queue.then(async () => {
+            // Streamed text only ever grows; if the snapshot diverged from what we
+            // already delivered (the final assistant_message rewrote history) hold
+            // everything for finalize(), which handles divergence explicitly.
+            if (!snapshot.startsWith(this.sentPrefix))
+                return;
+            let consumed = this.sentPrefix.length;
+            let taken = takeChunk(snapshot.slice(consumed), this.opts.limits);
+            while (taken) {
+                await this.deliver(taken.chunk);
+                consumed = snapshot.length - taken.rest.length;
+                this.sentPrefix = snapshot.slice(0, consumed);
+                taken = takeChunk(taken.rest, this.opts.limits);
+            }
+        });
+    }
+    /**
+     * Turn end: deliver whatever the final snapshot still owes. When the final
+     * text no longer extends what we already sent (a divergent final frame —
+     * rare), send the full final text so the user always receives the
+     * authoritative reply, accepting the duplication.
+     */
+    async finalize(snapshot, emptyText) {
+        this.queue = this.queue.then(async () => {
+            const finalText = snapshot.trim();
+            if (!finalText) {
+                if (!this.sentAnything && emptyText)
+                    await this.deliver(emptyText);
+                return;
+            }
+            const remainder = snapshot.startsWith(this.sentPrefix)
+                ? snapshot.slice(this.sentPrefix.length)
+                : snapshot; // diverged: resend the authoritative text in full
+            for (const part of splitForImessage(remainder, this.opts.limits)) {
+                await this.deliver(part);
+            }
+            this.sentPrefix = snapshot;
+        });
+        await this.queue;
+    }
+    async deliver(text) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        this.sentAnything = true;
+        await this.opts.send(trimmed);
+    }
+}
+//# sourceMappingURL=chunker.js.map

package/dist/channel/chunker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.js","sourceRoot":"","sources":["../../src/channel/chunker.ts"],"names":[],"mappings":"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"}

package/dist/channel/turn-runner.d.ts

@@ -0,0 +1,32 @@
+import type { newTurnId } from '@moxxy/core';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { type ChunkLimits } from './chunker.js';
+export interface TurnRunnerLogger {
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+export interface RunImessageTurnDeps {
+    readonly session: Session;
+    /** Deliver one outbound message to the turn's reply target. Must swallow its
+     *  own transport errors (log + resolve) — a failed send never aborts the turn. */
+    readonly send: (text: string) => Promise<void>;
+    readonly chunkLimits?: ChunkLimits;
+    readonly logger?: TurnRunnerLogger;
+}
+export interface RunImessageTurnOptions {
+    readonly text: string;
+    readonly model?: string;
+    readonly controller: AbortController;
+    /** Pre-minted turn id; the channel records it as an own-turn id (invariant #8). */
+    readonly turnId: ReturnType<typeof newTurnId>;
+}
+/**
+ * Drive a single iMessage turn end-to-end: subscribe to THIS turn's events
+ * (filtered by turnId — `session.log` fans out to every listener, AGENTS.md
+ * invariant #8), stream the rendered snapshot through the buffered
+ * {@link ChunkedSender} (see chunker.ts for why iMessage gets chunked sends
+ * instead of FramePump edits — apple-script messages are immutable), run the
+ * turn, flush the final remainder, and unwind in `finally`. No typing indicator:
+ * that needs the BlueBubbles Private API, which v1 deliberately omits.
+ */
+export declare function runImessageTurn(deps: RunImessageTurnDeps, opts: RunImessageTurnOptions): Promise<void>;
+//# sourceMappingURL=turn-runner.d.ts.map

package/dist/channel/turn-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-runner.d.ts","sourceRoot":"","sources":["../../src/channel/turn-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;sFACkF;IAClF,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA2Cf"}

package/dist/channel/turn-runner.js

@@ -0,0 +1,58 @@
+import { PlainTurnRenderer, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
+import { ChunkedSender } from './chunker.js';
+/**
+ * Drive a single iMessage turn end-to-end: subscribe to THIS turn's events
+ * (filtered by turnId — `session.log` fans out to every listener, AGENTS.md
+ * invariant #8), stream the rendered snapshot through the buffered
+ * {@link ChunkedSender} (see chunker.ts for why iMessage gets chunked sends
+ * instead of FramePump edits — apple-script messages are immutable), run the
+ * turn, flush the final remainder, and unwind in `finally`. No typing indicator:
+ * that needs the BlueBubbles Private API, which v1 deliberately omits.
+ */
+export async function runImessageTurn(deps, opts) {
+    const { session, send, logger } = deps;
+    const { text, model, controller, turnId } = opts;
+    const renderer = new PlainTurnRenderer();
+    const sender = new ChunkedSender({
+        send: async (t) => {
+            try {
+                await send(t);
+            }
+            catch (err) {
+                logger?.warn?.('imessage: send failed', {
+                    err: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+        ...(deps.chunkLimits ? { limits: deps.chunkLimits } : {}),
+    });
+    const unsubscribe = subscribeTurn(session, turnId, (event) => {
+        if (renderer.accept(event))
+            sender.offer(renderer.snapshot());
+    });
+    try {
+        await driveTurn(session, {
+            turnId,
+            prompt: text,
+            ...(model ? { model } : {}),
+            signal: controller.signal,
+        });
+        await sender.finalize(renderer.snapshot(), '(no output)');
+    }
+    catch (err) {
+        logger?.warn?.('imessage: turn failed', {
+            err: err instanceof Error ? err.message : String(err),
+        });
+        // Surface the failure to the sender rather than going silent.
+        try {
+            await send(`Turn failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    finally {
+        unsubscribe();
+    }
+}
+//# sourceMappingURL=turn-runner.js.map

package/dist/channel/turn-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-runner.js","sourceRoot":"","sources":["../../src/channel/turn-runner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAoB,MAAM,cAAc,CAAC;AAuB/D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAyB,EACzB,IAA4B;IAE5B,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACvC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAEjD,MAAM,QAAQ,GAAG,IAAI,iBAAiB,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC;QAC/B,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;YAChB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,EAAE,IAAI,EAAE,CAAC,uBAAuB,EAAE;oBACtC,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBACtD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1D,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;QAC3D,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,OAAO,EAAE;YACvB,MAAM;YACN,MAAM,EAAE,IAAI;YACZ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3B,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,aAAa,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,EAAE,IAAI,EAAE,CAAC,uBAAuB,EAAE;YACtC,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACtD,CAAC,CAAC;QACH,8DAA8D;QAC9D,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,gBAAgB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjF,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,WAAW,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/channel.d.ts

@@ -0,0 +1,87 @@
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { Channel, ChannelHandle, ChannelStartOptsBase, PermissionResolver } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { type BlueBubblesClientLike, type BlueBubblesClientOptions } from './bluebubbles-client.js';
+export interface ImessageChannelLogger {
+    debug?(msg: string, meta?: Record<string, unknown>): void;
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+    error?(msg: string, meta?: Record<string, unknown>): void;
+}
+export interface ImessageStartOpts extends ChannelStartOptsBase {
+    readonly session: Session;
+    /** Override the autonomous tool allow-list at start. */
+    readonly allowedTools?: ReadonlyArray<string>;
+}
+export interface ImessageChannelOptions {
+    readonly vault: VaultStore;
+    /** Server URL override; beats env + vault. */
+    readonly serverUrl?: string;
+    /** Server password override; beats env + vault. */
+    readonly password?: string;
+    /** Tools the model may call autonomously. `['*']` allows every registered tool. */
+    readonly allowedTools?: ReadonlyArray<string>;
+    /** Extra allow-listed handles, merged with the vault allow-list. */
+    readonly allowedHandles?: ReadonlyArray<string>;
+    /** Extra owner handles (self-chat identities), merged with the vault list. */
+    readonly ownerHandles?: ReadonlyArray<string>;
+    readonly logger?: ImessageChannelLogger;
+    /** Test seam: build the BlueBubbles transport (production uses the real one). */
+    readonly clientFactory?: (opts: BlueBubblesClientOptions) => BlueBubblesClientLike;
+}
+export declare class ImessageChannel implements Channel<ImessageStartOpts> {
+    readonly name = "imessage";
+    /**
+     * Installed on the session by the CLI dispatcher. Replaced in `start()` once
+     * the live tool registry is available for `['*']` expansion; until then it
+     * denies everything (safe default before start).
+     */
+    permissionResolver: PermissionResolver;
+    private readonly opts;
+    private session;
+    private model;
+    private client;
+    private readonly allowedHandles;
+    private readonly ownerHandles;
+    private readonly turns;
+    private lastChatGuid;
+    private logUnsub;
+    /**
+     * guid + tempGuid of messages WE sent. BlueBubbles emits `new-message` for
+     * the account's own sends too (our replies come back `isFromMe`), so any
+     * inbound whose id is in this set is an echo of ourselves and must be dropped
+     * (loop protection).
+     */
+    private readonly sentIds;
+    private handle;
+    private runningSettled;
+    private resolveRunning;
+    private stopping;
+    private lastDropWarnAt;
+    constructor(opts: ImessageChannelOptions);
+    start(startOpts: ImessageStartOpts): Promise<ChannelHandle>;
+    /** Every inbound `new-message` funnels through the one gate. */
+    private handleInbound;
+    /** Busy gate, then one coordinated turn. */
+    private processMessage;
+    /** Send one message and record its ids for the echo drop. */
+    private sendText;
+    private recordSent;
+    /**
+     * Post the assistant's prose for a turn this channel did not initiate.
+     * Skipped for our own turnIds (robust to async ordering / replay, invariant
+     * #8) and while a turn of ours is streaming via the chunked sender.
+     */
+    private mirrorForeignTurn;
+    private makeClient;
+    private rebuildHandleSet;
+    /**
+     * Run a handler detached from the socket read loop (an inbound handler that
+     * awaited a whole turn would park delivery for its duration). Errors are
+     * logged here — nothing upstream awaits this promise.
+     */
+    private dispatchInBackground;
+    private warnDrop;
+    private settleRunning;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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"}