@moxxy/plugin-channel-signal 0.27.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/channel/chunker.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 declare const SIGNAL_CHUNK_SOFT_LIMIT = 1500;
+/**
+ * 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 declare const SIGNAL_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 splitForSignal(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;;;;;;;;;;;;;;GAcG;AAEH,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAE7C,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,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,WAAgB,GAAG,MAAM,EAAE,CAc/E;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,133 @@
+/**
+ * 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;
+/**
+ * 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 ?? 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, limits = {}) {
+    const hard = limits.hardLimit ?? SIGNAL_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 splitForSignal(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,33 @@
+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 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>;
+}
+/**
+ * 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 declare function runSignalTurn(deps: RunSignalTurnDeps, opts: RunSignalTurnOptions): 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,iBAAiB;IAChC,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,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,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;AAKD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAsDf"}

package/dist/channel/turn-runner.js

@@ -0,0 +1,70 @@
+import { PlainTurnRenderer, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
+import { ChunkedSender } from './chunker.js';
+/** 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, opts) {
+    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) => {
+        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();
+    }
+}
+//# 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;AAyB/D,mFAAmF;AACnF,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAuB,EACvB,IAA0B;IAE1B,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACnD,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,qBAAqB,EAAE,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACnG,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,mEAAmE;IACnE,qEAAqE;IACrE,6BAA6B;IAC7B,MAAM,MAAM,GAAG,CAAC,IAAa,EAAQ,EAAE;QACrC,IAAI,CAAC,UAAU;YAAE,OAAO;QACxB,KAAK,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,CAAC;IACd,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACxE,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;IAEtB,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,qBAAqB,EAAE;YACpC,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,aAAa,CAAC,WAAW,CAAC,CAAC;QAC3B,MAAM,CAAC,IAAI,CAAC,CAAC;QACb,WAAW,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/channel/voice.d.ts

@@ -0,0 +1,37 @@
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { 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 declare const MAX_AUDIO_BYTES: number;
+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 declare function pickAudioAttachment(attachments: ReadonlyArray<SignalAttachment> | undefined): SignalAttachment | 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 declare function transcribeVoiceAttachment(deps: VoiceDeps, attachment: SignalAttachment): Promise<string | null>;
+//# sourceMappingURL=voice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../../src/channel/voice.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE;;;;;;GAMG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAmB,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,wDAAwD;AACxD,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAAC,GAAG,SAAS,GACvD,gBAAgB,GAAG,IAAI,CAGzB;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkExB"}

package/dist/channel/voice.js

@@ -0,0 +1,88 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { attachmentIdSchema } 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;
+/** The first audio attachment in a message, or null. */
+export function pickAudioAttachment(attachments) {
+    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, attachment) {
+    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) => fs.readFile(p));
+    let bytes;
+    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;
+    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;
+}
+//# sourceMappingURL=voice.js.map

package/dist/channel/voice.js.map

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

package/dist/channel.d.ts

@@ -0,0 +1,154 @@
+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 LinkProcessHandle, type SpawnFn } from './sidecar.js';
+export interface SignalChannelLogger {
+    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;
+}
+/** Where a reply goes: the owner's Note-to-Self thread, or a direct recipient. */
+export type SendTarget = {
+    readonly noteToSelf: true;
+} | {
+    readonly recipient: string;
+};
+/** The RPC slice the channel drives (SignalRpcClient satisfies it; tests fake it). */
+export interface SignalRpcLike {
+    request(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    onNotification(method: string, listener: (params: unknown) => void): () => void;
+    onClose(listener: (reason: string) => void): () => void;
+    close(): void;
+}
+/** The sidecar slice the channel manages (SignalSidecar satisfies it). */
+export interface SignalSidecarLike {
+    start(): Promise<SignalRpcLike>;
+    stop(): Promise<void>;
+    onExit(listener: (code: number | null) => void): () => void;
+}
+export interface SignalStartOpts extends ChannelStartOptsBase {
+    readonly session: Session;
+    /**
+     * If true (and the account isn't linked yet), open a linking window on
+     * startup: spawn `signal-cli link`, publish the `sgnl://linkdevice…` URI as
+     * this channel's connect value (rendered as a QR by the pair flow / desktop
+     * Channels panel), and boot the daemon once the phone completes the link.
+     */
+    readonly pair?: boolean;
+    /**
+     * Running on a dedicated runner under a GUI control surface (the desktop
+     * Channels panel). Equivalent to `pair` for the unlinked case, so the desktop
+     * links with the identical mechanism instead of getting a throw.
+     */
+    readonly dedicated?: boolean;
+    /** Override the autonomous tool allow-list at start. */
+    readonly allowedTools?: ReadonlyArray<string>;
+}
+export interface SignalChannelOptions {
+    readonly vault: VaultStore;
+    /** Account override (E.164); beats env + vault. */
+    readonly account?: string;
+    /** signal-cli binary path/name override. Default: resolve from PATH. */
+    readonly binary?: string;
+    /** Tools the model may call autonomously. `['*']` allows every registered tool. */
+    readonly allowedTools?: ReadonlyArray<string>;
+    /** Extra allowed senders (E.164/uuid), merged with the vault allow-list. */
+    readonly allowedSenders?: ReadonlyArray<string>;
+    readonly logger?: SignalChannelLogger;
+    readonly sidecarFactory?: (opts: {
+        account: string;
+        binary: string;
+    }) => SignalSidecarLike;
+    readonly linkFactory?: (opts: {
+        deviceName: string;
+        binary: string;
+    }) => LinkProcessHandle;
+    readonly listAccountsFn?: (opts: {
+        binary: string;
+    }) => Promise<string[]>;
+    readonly findBinaryFn?: () => string | null;
+    readonly attachmentsDir?: string;
+    readonly spawnFn?: SpawnFn;
+}
+export declare class SignalChannel implements Channel<SignalStartOpts> {
+    readonly name = "signal";
+    /**
+     * 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 account;
+    private allowedSenders;
+    private sidecar;
+    private rpc;
+    private link;
+    private handle;
+    private runningSettled;
+    private resolveRunning;
+    private rejectRunning;
+    private stopping;
+    private readonly turns;
+    private lastTarget;
+    private logUnsub;
+    /**
+     * Timestamps of messages WE sent through the daemon (signal-cli's `send`
+     * result). A linked device sees the account's sends come back as
+     * `syncMessage.sentMessage` envelopes — including its own — so any sync'd
+     * sent-message whose timestamp is in this set is an echo of ourselves and
+     * must be dropped (loop protection).
+     */
+    private readonly sentTimestamps;
+    private linkUri;
+    private linked;
+    private readonly connectListeners;
+    private readonly linkedListeners;
+    private lastDropWarnAt;
+    constructor(opts: SignalChannelOptions);
+    /** The `sgnl://linkdevice…` URI while a linking window is open; null otherwise. */
+    get requestUrl(): string | null;
+    /** Whether the account is linked (the "connect the other side" step). */
+    get connected(): boolean;
+    /** Fires when linking completes (the pair flow prints success off this). */
+    onLinked(listener: (account: string) => void): () => void;
+    start(startOpts: SignalStartOpts): Promise<ChannelHandle>;
+    private openLinkWindow;
+    private bootDaemon;
+    /** Every inbound notification funnels through here — zod-validate FIRST. */
+    private handleReceive;
+    /** A message from ANOTHER account — gate on the sender allow-list. */
+    private handleDataMessage;
+    /**
+     * A sync'd copy of a message the ACCOUNT OWNER sent from another device.
+     * Two jobs: (1) drop echoes of OUR OWN sends (linked devices receive the
+     * account's sends back — loop protection), (2) accept the owner's
+     * Note-to-Self prompts, which are allowed by default after linking.
+     */
+    private handleSyncSent;
+    /** Voice → transcript, busy gate, then one coordinated turn. */
+    private processMessage;
+    /** Send one message and record its timestamp for the sync-echo drop. */
+    private sendText;
+    private sendTyping;
+    /**
+     * 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;
+    /**
+     * Run a handler detached from the socket read loop (an envelope handler that
+     * awaited a whole turn would park notification delivery for its duration).
+     * Errors are logged here — nothing upstream awaits this promise.
+     */
+    private dispatchInBackground;
+    private warnDrop;
+    private notifyConnectChange;
+    private settleRunning;
+    private fatal;
+}
+//# sourceMappingURL=channel.d.ts.map