@moxxy/plugin-channel-signal 0.27.0

package/src/channel/chunker.ts

@@ -0,0 +1,147 @@
+/**
+ * Buffered chunked sends — Signal's streaming strategy.
+ *
+ * WHY NOT FramePump edits: signal-cli's `send` does support editing a previous
+ * message (`editTimestamp`), but every Signal edit is a full end-to-end
+ * re-delivery of the whole message body to every device in the conversation.
+ * Driving it at a streaming cadence (an edit per ~1s for a long turn) floods
+ * the recipient's devices with dozens of E2E deliveries per reply, official
+ * clients keep a bounded edit history per message, and burst sends are exactly
+ * what Signal's server-side spam heuristics rate-limit (challenge/backoff).
+ * 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. Liveness comes from the typing
+ * indicator (`sendTyping`), not message churn.
+ */
+
+/** Buffered text below this length is held for the final flush. */
+export const SIGNAL_CHUNK_SOFT_LIMIT = 1_500;
+/**
+ * Never send a single message longer than this. Signal itself allows long
+ * bodies, but clients render extremely long messages poorly and signal-cli
+ * sends the whole body per message; 2000 mirrors common client truncation.
+ */
+export const SIGNAL_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 ?? SIGNAL_CHUNK_SOFT_LIMIT;
+  const hard = limits.hardLimit ?? SIGNAL_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 Signal 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 splitForSignal(text: string, limits: ChunkLimits = {}): string[] {
+  const hard = limits.hardLimit ?? SIGNAL_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 splitForSignal(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,97 @@
+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 RunSignalTurnDeps {
+  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>;
+  /** Start/refresh the typing indicator (best-effort; errors swallowed). */
+  readonly sendTyping?: (stop: boolean) => Promise<void>;
+  readonly chunkLimits?: ChunkLimits;
+  readonly logger?: TurnRunnerLogger;
+}
+
+export interface RunSignalTurnOptions {
+  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>;
+}
+
+/** Signal shows a typing indicator for ~15s per sendTyping; refresh under that. */
+const TYPING_REFRESH_MS = 10_000;
+
+/**
+ * Drive a single Signal 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 Signal gets chunked sends
+ * instead of FramePump edits), keep a typing indicator alive for liveness, run
+ * the turn, flush the final remainder, and unwind in `finally`.
+ */
+export async function runSignalTurn(
+  deps: RunSignalTurnDeps,
+  opts: RunSignalTurnOptions,
+): Promise<void> {
+  const { session, send, sendTyping, 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?.('signal: send failed', { err: err instanceof Error ? err.message : String(err) });
+      }
+    },
+    ...(deps.chunkLimits ? { limits: deps.chunkLimits } : {}),
+  });
+
+  // Liveness: refresh the typing indicator while the turn runs (each
+  // sendTyping shows for ~15s). Best-effort — a failure only loses the
+  // indicator, never the turn.
+  const typing = (stop: boolean): void => {
+    if (!sendTyping) return;
+    void sendTyping(stop).catch(() => undefined);
+  };
+  typing(false);
+  const typingTimer = setInterval(() => typing(false), TYPING_REFRESH_MS);
+  typingTimer.unref?.();
+
+  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?.('signal: 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 {
+    clearInterval(typingTimer);
+    typing(true);
+    unsubscribe();
+  }
+}

package/src/channel/voice.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { MAX_AUDIO_BYTES, pickAudioAttachment, transcribeVoiceAttachment } from './voice.js';
+
+function fakeSession(transcriber: { transcribe: (bytes: Uint8Array, o: { mimeType: string }) => Promise<{ text: string }> } | null): Session {
+  return {
+    transcribers: { tryGetActive: () => transcriber },
+  } as unknown as Session;
+}
+
+function replies(): { sent: string[]; reply: (t: string) => Promise<void> } {
+  const sent: string[] = [];
+  return {
+    sent,
+    reply: async (t) => {
+      sent.push(t);
+    },
+  };
+}
+
+describe('pickAudioAttachment', () => {
+  it('picks the first audio/* attachment', () => {
+    expect(
+      pickAudioAttachment([
+        { id: 'a', contentType: 'image/png' },
+        { id: 'b', contentType: 'audio/aac' },
+        { id: 'c', contentType: 'audio/ogg' },
+      ])?.id,
+    ).toBe('b');
+  });
+
+  it('returns null when nothing is audio', () => {
+    expect(pickAudioAttachment([{ id: 'a', contentType: 'image/png' }])).toBeNull();
+    expect(pickAudioAttachment(undefined)).toBeNull();
+  });
+});
+
+describe('transcribeVoiceAttachment', () => {
+  it('replies with install guidance when no transcriber is configured', async () => {
+    const r = replies();
+    const out = await transcribeVoiceAttachment(
+      { session: fakeSession(null), attachmentsDir: '/tmp', reply: r.reply },
+      { id: 'abc', contentType: 'audio/aac', size: 10 },
+    );
+    expect(out).toBeNull();
+    expect(r.sent[0]).toMatch(/plugin-stt-whisper/);
+  });
+
+  it('rejects oversized audio from the declared size before reading', async () => {
+    const r = replies();
+    const readFile = vi.fn();
+    const out = await transcribeVoiceAttachment(
+      {
+        session: fakeSession({ transcribe: async () => ({ text: 'x' }) }),
+        attachmentsDir: '/tmp',
+        reply: r.reply,
+        readFile,
+      },
+      { id: 'abc', contentType: 'audio/aac', size: MAX_AUDIO_BYTES + 1 },
+    );
+    expect(out).toBeNull();
+    expect(readFile).not.toHaveBeenCalled();
+    expect(r.sent[0]).toMatch(/too large/);
+  });
+
+  it('rejects a body that lies about its declared size', async () => {
+    const r = replies();
+    const out = await transcribeVoiceAttachment(
+      {
+        session: fakeSession({ transcribe: async () => ({ text: 'x' }) }),
+        attachmentsDir: '/tmp',
+        reply: r.reply,
+        readFile: async () => new Uint8Array(MAX_AUDIO_BYTES + 1),
+      },
+      { id: 'abc', contentType: 'audio/aac', size: 10 },
+    );
+    expect(out).toBeNull();
+    expect(r.sent[0]).toMatch(/too large/);
+  });
+
+  it('drops attachments whose id could escape the attachments dir', async () => {
+    const r = replies();
+    const readFile = vi.fn();
+    const out = await transcribeVoiceAttachment(
+      {
+        session: fakeSession({ transcribe: async () => ({ text: 'x' }) }),
+        attachmentsDir: '/tmp',
+        reply: r.reply,
+        readFile,
+      },
+      { id: '../../etc/passwd' as never, contentType: 'audio/aac' },
+    );
+    expect(out).toBeNull();
+    expect(readFile).not.toHaveBeenCalled();
+    expect(r.sent).toEqual([]); // silent drop — nothing to say to a forged envelope
+  });
+
+  it('replies with the transcription error instead of throwing', async () => {
+    const r = replies();
+    const out = await transcribeVoiceAttachment(
+      {
+        session: fakeSession({
+          transcribe: async () => {
+            throw new Error('whisper 500');
+          },
+        }),
+        attachmentsDir: '/tmp',
+        reply: r.reply,
+        readFile: async () => new Uint8Array(4),
+      },
+      { id: 'abc', contentType: 'audio/aac' },
+    );
+    expect(out).toBeNull();
+    expect(r.sent[0]).toMatch(/whisper 500/);
+  });
+
+  it('transcribes, echoes "heard:", and returns the transcript', async () => {
+    const r = replies();
+    const transcribe = vi.fn(async () => ({ text: '  turn on the lights  ' }));
+    const out = await transcribeVoiceAttachment(
+      {
+        session: fakeSession({ transcribe }),
+        attachmentsDir: '/data/attachments',
+        reply: r.reply,
+        readFile: async (p) => {
+          expect(p).toBe('/data/attachments/12345.opus');
+          return new Uint8Array([1, 2, 3]);
+        },
+      },
+      { id: '12345.opus', contentType: 'audio/ogg', size: 3 },
+    );
+    expect(out).toBe('turn on the lights');
+    expect(transcribe).toHaveBeenCalledWith(expect.any(Uint8Array), { mimeType: 'audio/ogg' });
+    expect(r.sent[0]).toBe('heard: turn on the lights');
+  });
+});

package/src/channel/voice.ts

@@ -0,0 +1,118 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { attachmentIdSchema, type SignalAttachment } from '../schema.js';
+
+/**
+ * Voice-note handling for the Signal channel. signal-cli writes received
+ * attachments to `<dataDir>/attachments/<id>` (it does NOT inline them in the
+ * receive notification), so the flow is: pick the first audio attachment,
+ * size-cap it, read the file, transcribe via the session's active Transcriber,
+ * and hand the transcript back for a normal text turn.
+ */
+
+/**
+ * Hard cap on an audio file we will buffer into memory before transcribing —
+ * matches the Telegram channel's ceiling so an authorized-but-compromised
+ * sender can't make the runner buffer an arbitrarily large blob.
+ */
+export const MAX_AUDIO_BYTES = 20 * 1024 * 1024;
+
+export interface VoiceLogger {
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface VoiceDeps {
+  readonly session: Session;
+  /** signal-cli's attachments dir (injectable for tests). */
+  readonly attachmentsDir: string;
+  /** Reply to the sender (guidance / error strings). */
+  readonly reply: (text: string) => Promise<void>;
+  /** Injectable file reader (tests). Defaults to fs.readFile. */
+  readonly readFile?: (filePath: string) => Promise<Uint8Array>;
+  readonly logger?: VoiceLogger;
+}
+
+/** The first audio attachment in a message, or null. */
+export function pickAudioAttachment(
+  attachments: ReadonlyArray<SignalAttachment> | undefined,
+): SignalAttachment | null {
+  if (!attachments) return null;
+  return attachments.find((a) => (a.contentType ?? '').toLowerCase().startsWith('audio/')) ?? null;
+}
+
+/**
+ * Transcribe a received audio attachment. Returns the transcript, or null when
+ * the message was fully handled with a reply (no transcriber configured,
+ * oversized, unreadable, transcription failed).
+ */
+export async function transcribeVoiceAttachment(
+  deps: VoiceDeps,
+  attachment: SignalAttachment,
+): Promise<string | null> {
+  const transcriber = deps.session.transcribers.tryGetActive();
+  if (!transcriber) {
+    await deps.reply(
+      'Heard a voice note, but no speech-to-text backend is configured. Install @moxxy/plugin-stt-whisper ' +
+        'and run `moxxy login openai` (or set OPENAI_API_KEY) to enable voice input.',
+    );
+    return null;
+  }
+
+  // Reject oversized audio up-front from the declared size, before any read.
+  if (typeof attachment.size === 'number' && attachment.size > MAX_AUDIO_BYTES) {
+    await deps.reply(
+      `That audio is too large (${Math.round(attachment.size / (1024 * 1024))}MB). The limit is ${MAX_AUDIO_BYTES / (1024 * 1024)}MB.`,
+    );
+    return null;
+  }
+
+  // The id becomes a filename under signal-cli's attachments dir; re-validate
+  // its charset here (defense in depth on top of the zod schema) so a crafted
+  // id can never traverse out of the directory.
+  const id = attachmentIdSchema.safeParse(attachment.id);
+  if (!id.success) {
+    deps.logger?.warn?.('signal: dropping voice note with invalid attachment id');
+    return null;
+  }
+  const filePath = path.join(deps.attachmentsDir, id.data);
+
+  const read = deps.readFile ?? ((p: string) => fs.readFile(p));
+  let bytes: Uint8Array;
+  try {
+    bytes = await read(filePath);
+  } catch (err) {
+    deps.logger?.warn?.('signal: could not read voice attachment', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await deps.reply('Could not read that voice note from the signal-cli attachment store.');
+    return null;
+  }
+  if (bytes.byteLength > MAX_AUDIO_BYTES) {
+    await deps.reply('That audio is too large to transcribe.');
+    return null;
+  }
+
+  let transcript: string;
+  try {
+    const result = await transcriber.transcribe(bytes, {
+      mimeType: attachment.contentType ?? 'audio/aac',
+    });
+    transcript = result.text.trim();
+  } catch (err) {
+    deps.logger?.warn?.('signal: transcription failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await deps.reply(`Transcription failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+  if (!transcript) {
+    await deps.reply('Could not transcribe the voice note (got empty text).');
+    return null;
+  }
+
+  // Echo what we heard so the user can spot misrecognitions before the agent
+  // acts on it (same UX as the Telegram voice path).
+  await deps.reply(`heard: ${transcript}`);
+  return transcript;
+}