@moxxy/plugin-channel-imessage 0.29.0

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@moxxy/plugin-channel-imessage",
+  "version": "0.29.0",
+  "description": "iMessage channel for moxxy via a localhost BlueBubbles server (macOS only). Sends text with the apple-script method and receives via the BlueBubbles socket.io feed, driving the Session from allow-listed handles (your own self-chat by default). Immutable chunked replies; autonomous allow-list permission model.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "channel",
+    "imessage",
+    "bluebubbles",
+    "bot"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-channel-imessage"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "channel"
+    },
+    "requirements": [
+      {
+        "kind": "plugin",
+        "name": "@moxxy/plugin-vault",
+        "hint": "imessage resolves the vault from the service registry for its BlueBubbles server URL + password + handle allow-list; @moxxy/plugin-vault must load first"
+      }
+    ],
+    "setup": {
+      "title": "iMessage (BlueBubbles)",
+      "description": "macOS only. Install the BlueBubbles server (https://bluebubbles.app) on this Mac, sign in to Messages, and set a server password. Then paste the server URL (default http://localhost:1234) and the password below, and run `moxxy channels imessage setup` to add the handles allowed to talk to moxxy.",
+      "fields": [
+        {
+          "key": "serverUrl",
+          "label": "BlueBubbles server URL",
+          "kind": "text",
+          "vaultKey": "imessage_server_url",
+          "required": true,
+          "placeholder": "http://localhost:1234"
+        },
+        {
+          "key": "password",
+          "label": "BlueBubbles server password",
+          "kind": "secret",
+          "vaultKey": "imessage_server_password",
+          "required": true
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "socket.io-client": "^4.8.1",
+    "zod": "^3.24.0",
+    "@moxxy/core": "0.29.0",
+    "@moxxy/plugin-vault": "0.29.0",
+    "@moxxy/channel-kit": "0.29.0",
+    "@moxxy/sdk": "0.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/bluebubbles-client.ts

@@ -0,0 +1,182 @@
+import { randomUUID } from 'node:crypto';
+
+/**
+ * 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 function makeTempGuid(): string {
+  return `temp-${randomUUID()}`;
+}
+
+export class BlueBubblesClient implements BlueBubblesClientLike {
+  private readonly opts: BlueBubblesClientOptions;
+  private readonly base: string;
+  private socket: SocketLike | null = null;
+  private readonly messageListeners = new Set<(raw: unknown) => void>();
+
+  constructor(opts: BlueBubblesClientOptions) {
+    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(): Promise<void> {
+    const doFetch = this.opts.fetchImpl ?? fetch;
+    let res: Response;
+    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(): Promise<void> {
+    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: unknown[]) => {
+      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: unknown[]) => {
+      this.opts.logger?.debug?.('imessage: socket disconnected (auto-reconnecting)', {
+        reason: String(args.length > 0 ? args[0] : ''),
+      });
+    });
+  }
+
+  onMessage(listener: (raw: unknown) => void): () => void {
+    this.messageListeners.add(listener);
+    return () => this.messageListeners.delete(listener);
+  }
+
+  async sendText(
+    chatGuid: string,
+    message: string,
+  ): Promise<{ guid: string | null; tempGuid: string }> {
+    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(): void {
+    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. */
+  private apiUrl(path: string): string {
+    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: Response): Promise<string | null> {
+  const body: unknown = await res.json().catch(() => null);
+  if (!body || typeof body !== 'object') return null;
+  const data = (body as { data?: unknown }).data;
+  if (!data || typeof data !== 'object') return null;
+  const guid = (data as { guid?: unknown }).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: { url: string; password: string }): Promise<SocketLike> {
+  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 as unknown as SocketLike;
+}

package/src/channel/chunker.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ChunkedSender,
+  IMESSAGE_CHUNK_HARD_LIMIT,
+  splitForImessage,
+  takeChunk,
+} from './chunker.js';
+
+describe('takeChunk', () => {
+  it('holds short text for the final flush', () => {
+    expect(takeChunk('hello world')).toBeNull();
+    expect(takeChunk('x'.repeat(1_500))).toBeNull();
+  });
+
+  it('splits at a paragraph boundary once past the soft limit', () => {
+    const text = 'a'.repeat(1_200) + '\n\n' + 'b'.repeat(600);
+    const taken = takeChunk(text);
+    expect(taken).not.toBeNull();
+    expect(taken?.chunk).toBe('a'.repeat(1_200));
+    expect(taken?.rest).toBe('b'.repeat(600));
+  });
+
+  it('falls back to newline, then word boundaries', () => {
+    const nl = 'a'.repeat(1_200) + '\n' + 'b'.repeat(600);
+    expect(takeChunk(nl)?.chunk).toBe('a'.repeat(1_200));
+    const word = 'a'.repeat(1_200) + ' ' + 'b'.repeat(600);
+    expect(takeChunk(word)?.chunk).toBe('a'.repeat(1_200));
+  });
+
+  it('never returns a chunk above the hard limit (hard cut when boundary-less)', () => {
+    const text = 'x'.repeat(IMESSAGE_CHUNK_HARD_LIMIT + 500);
+    const taken = takeChunk(text);
+    expect(taken).not.toBeNull();
+    expect(taken?.chunk.length).toBe(IMESSAGE_CHUNK_HARD_LIMIT);
+    expect(taken?.rest.length).toBe(500);
+  });
+
+  it('waits for more text when boundary-less but under the hard limit', () => {
+    expect(takeChunk('x'.repeat(1_800))).toBeNull();
+  });
+
+  it('ignores boundaries too early to form a meaningful chunk', () => {
+    const text = '\n\n' + 'x'.repeat(1_700);
+    expect(takeChunk(text)).toBeNull();
+  });
+});
+
+describe('splitForImessage', () => {
+  it('returns short text as a single message', () => {
+    expect(splitForImessage('hi')).toEqual(['hi']);
+  });
+
+  it('drops pure whitespace', () => {
+    expect(splitForImessage('   \n ')).toEqual([]);
+  });
+
+  it('splits long text into under-limit pieces', () => {
+    const paragraphs = Array.from({ length: 8 }, (_, i) => `${'p'.repeat(700)}${i}`).join('\n\n');
+    const parts = splitForImessage(paragraphs);
+    expect(parts.length).toBeGreaterThan(1);
+    for (const part of parts) expect(part.length).toBeLessThanOrEqual(IMESSAGE_CHUNK_HARD_LIMIT);
+    expect(parts.join('')).toContain('p'.repeat(700) + '7');
+  });
+});
+
+describe('ChunkedSender', () => {
+  function collector(): { sent: string[]; send: (t: string) => Promise<void> } {
+    const sent: string[] = [];
+    return {
+      sent,
+      send: async (t) => {
+        sent.push(t);
+      },
+    };
+  }
+
+  it('buffers below the soft limit and flushes once on finalize', async () => {
+    const { sent, send } = collector();
+    const sender = new ChunkedSender({ send });
+    sender.offer('Hello');
+    sender.offer('Hello world');
+    await sender.finalize('Hello world, done.');
+    expect(sent).toEqual(['Hello world, done.']);
+  });
+
+  it('streams paragraph chunks as the snapshot grows, then sends only the remainder', async () => {
+    const { sent, send } = collector();
+    const sender = new ChunkedSender({ send, limits: { softLimit: 20, hardLimit: 60 } });
+    sender.offer('first paragraph text\n\nsecond');
+    await sender.finalize('first paragraph text\n\nsecond part is done');
+    expect(sent).toEqual(['first paragraph text', 'second part is done']);
+  });
+
+  it('sends the empty-turn placeholder only when nothing was ever sent', async () => {
+    const { sent, send } = collector();
+    const sender = new ChunkedSender({ send });
+    await sender.finalize('   ', '(no output)');
+    expect(sent).toEqual(['(no output)']);
+  });
+
+  it('does not send the placeholder when chunks already went out', async () => {
+    const { sent, send } = collector();
+    const sender = new ChunkedSender({ send, limits: { softLimit: 5, hardLimit: 30 } });
+    sender.offer('streamed text already sent\n\nx');
+    await sender.finalize('', '(no output)');
+    expect(sent).toEqual(['streamed text already sent']);
+  });
+
+  it('re-sends the authoritative final text when it diverges from the streamed prefix', async () => {
+    const { sent, send } = collector();
+    const sender = new ChunkedSender({ send, limits: { softLimit: 10, hardLimit: 40 } });
+    sender.offer('streamed draft one\n\nmore text here');
+    await sender.finalize('a completely different final answer');
+    expect(sent[0]).toBe('streamed draft one');
+    expect(sent).toContain('a completely different final answer');
+  });
+
+  it('serializes sends in order', async () => {
+    const order: string[] = [];
+    const sender = new ChunkedSender({
+      send: async (t) => {
+        await new Promise((r) => setTimeout(r, 5));
+        order.push(t);
+      },
+      limits: { softLimit: 4, hardLimit: 12 },
+    });
+    sender.offer('one two\n\n');
+    sender.offer('one two\n\nthree four\n\n');
+    await sender.finalize('one two\n\nthree four\n\nfive');
+    expect(order).toEqual(['one two', 'three four', 'five']);
+  });
+});

package/src/channel/chunker.ts

@@ -0,0 +1,144 @@
+/**
+ * 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;
+
+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 function takeChunk(
+  text: string,
+  limits: ChunkLimits = {},
+): { chunk: string; rest: string } | null {
+  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: string, limits: ChunkLimits = {}): string[] {
+  const hard = limits.hardLimit ?? IMESSAGE_CHUNK_HARD_LIMIT;
+  const parts: string[] = [];
+  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;
+}
+
+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 class ChunkedSender {
+  private readonly opts: ChunkedSenderOptions;
+  /** The exact snapshot prefix already delivered (chunk boundaries included). */
+  private sentPrefix = '';
+  private sentAnything = false;
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(opts: ChunkedSenderOptions) {
+    this.opts = opts;
+  }
+
+  /** Called with the current full snapshot whenever it changes. */
+  offer(snapshot: string): void {
+    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: string, emptyText?: string): Promise<void> {
+    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;
+  }
+
+  private async deliver(text: string): Promise<void> {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    this.sentAnything = true;
+    await this.opts.send(trimmed);
+  }
+}

package/src/channel/turn-runner.ts

@@ -0,0 +1,82 @@
+import type { newTurnId } from '@moxxy/core';
+import { PlainTurnRenderer, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { ChunkedSender, 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 async function runImessageTurn(
+  deps: RunImessageTurnDeps,
+  opts: RunImessageTurnOptions,
+): Promise<void> {
+  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();
+  }
+}