tide-commander 1.91.0 → 1.93.0

package/dist/src/packages/server/integrations/slack/slack-polling-client.js

@@ -75,11 +75,17 @@ export class SlackPollingClient {
     allowlistChannelIds;
     keepAllDms;
     minMsBetweenCalls;
+    useSearch;
     scheduler;
     now;
-    /** Pacer state: serializes outbound API calls through a promise chain. */
-    rateGateChain = Promise.resolve();
-    /** When > now(), all paced calls sleep until that wall-clock ms. Set on 429. */
+    /** Token-bucket rate limiter shared by every paced API call. Concurrent
+     *  workers really run in parallel — only the *rate* (tokens/sec) is capped.
+     *  Replaces the older serial promise-chain gate which silently nullified
+     *  the `concurrency` option (every paced call was forced to run one at a
+     *  time spaced by `minMsBetweenCalls`, so `concurrency: 8` behaved like
+     *  `concurrency: 1`). */
+    bucket = null;
+    /** When > now(), every paced call sleeps until that wall-clock ms. Set on 429. */
     globalPauseUntil = 0;
     running = false;
     timer = null;
@@ -106,53 +112,47 @@ export class SlackPollingClient {
         this.allowlistChannelIds = new Set((opts.allowlistChannelIds ?? []).map((s) => s.trim()).filter(Boolean));
         this.keepAllDms = opts.keepAllDms !== false;
         this.minMsBetweenCalls = Math.max(0, opts.minMsBetweenCalls ?? 0);
+        this.useSearch = opts.useSearch === true;
         this.scheduler = opts.scheduler ?? DEFAULT_SCHEDULER;
         this.now = opts.now ?? Date.now;
+        if (this.minMsBetweenCalls > 0) {
+            // Tier 3 spec: ~50/min sustained with bursts up to ~5/sec. Refill rate
+            // = minMsBetweenCalls (e.g. 1200ms → 50/min). Burst capacity caps the
+            // initial flood from a cycle wake-up without us having to throttle every
+            // single call serially.
+            this.bucket = new TokenBucket({
+                capacity: 5,
+                refillIntervalMs: this.minMsBetweenCalls,
+                now: this.now,
+                globalPauseUntil: () => this.globalPauseUntil,
+                isRunning: () => this.running,
+            });
+        }
     }
     /**
      * Throttle gate for outbound Slack API calls. All calls (history + replies)
-     * go through here so the per-cycle burst is smeared across the cycle. When
-     * `minMsBetweenCalls` is 0 the gate is a no-op — used by tests.
+     * go through here. With `minMsBetweenCalls > 0` we acquire a token from the
+     * shared bucket; multiple workers can hold tokens concurrently up to the
+     * burst capacity, so `concurrency: 8` actually parallelizes (unlike the
+     * older serial promise-chain gate). With `minMsBetweenCalls === 0` we are
+     * in test mode and skip throttling entirely.
      *
-     * Honors `globalPauseUntil` set by 429 handlers so the entire client backs
-     * off when Slack tells us to.
+     * The bucket honors `globalPauseUntil` set by 429 handlers so the entire
+     * client backs off when Slack tells us to.
      */
     async paceCall(fn) {
-        // Stop() was called while we were queued — bail without consuming the
-        // pacing slot or making the API call.
         if (!this.running) {
             throw new Error('SlackPollingClient stopped');
         }
-        if (this.minMsBetweenCalls === 0 && this.globalPauseUntil <= this.now()) {
+        if (!this.bucket) {
+            // Test mode: no throttling at all.
             return fn();
         }
-        const prev = this.rateGateChain;
-        let release;
-        this.rateGateChain = new Promise((r) => { release = r; });
-        await prev;
-        // Re-check after waiting on the gate — stop() could have fired meanwhile.
+        await this.bucket.acquire();
         if (!this.running) {
-            release();
             throw new Error('SlackPollingClient stopped');
         }
-        // Sleep through any global pause first.
-        const pauseRemainingMs = this.globalPauseUntil - this.now();
-        if (pauseRemainingMs > 0) {
-            await new Promise((r) => setTimeout(r, pauseRemainingMs));
-        }
-        try {
-            return await fn();
-        }
-        finally {
-            // Release the gate after the min interval — the next paced call will
-            // unblock then. We don't await this; it's fire-and-forget.
-            if (this.minMsBetweenCalls > 0) {
-                setTimeout(release, this.minMsBetweenCalls);
-            }
-            else {
-                release();
-            }
-        }
+        return fn();
     }
     /** Subscribe to fatal-error notifications (e.g. invalid_auth). */
     setOnFatalError(cb) {
@@ -233,6 +233,25 @@ export class SlackPollingClient {
             return;
         this.cycleCount += 1;
         const cycleStart = this.now();
+        // Search-mode: one `search.messages` call replaces the entire per-channel
+        // history sweep. Covers thread replies for old parents that history would
+        // miss. Done in its own branch so the legacy per-channel path stays
+        // intact for tokens without `search:read` scope.
+        if (this.useSearch) {
+            try {
+                const { dispatched, pages } = await this.pollViaSearch();
+                const elapsed = this.now() - cycleStart;
+                log.log(`cycle=${this.cycleCount} via=search pages=${pages} dispatched=${dispatched} elapsedMs=${elapsed}`);
+            }
+            catch (err) {
+                if (isInvalidAuthError(err)) {
+                    this.handleFatal(`invalid_auth on search.messages (cycle=${this.cycleCount})`);
+                    return;
+                }
+                log.warn(`search-mode cycle failed (cycle=${this.cycleCount}): ${describeErr(err)}`);
+            }
+            return;
+        }
         // Refresh channel list on first cycle and every N cycles after.
         if (this.cycleCount === 1 || this.cycleCount % this.channelListRefreshEveryNCycles === 0) {
             try {
@@ -365,14 +384,15 @@ export class SlackPollingClient {
         if (messages.length === 0)
             return 0;
         // Slack returns newest-first; dispatch in chronological order so trigger
-        // listeners and dedupe see them in real-world order.
-        const ordered = [...messages].sort((a, b) => parseFloat(a.ts) - parseFloat(b.ts));
+        // listeners and dedupe see them in real-world order. BigInt sort avoids
+        // the precision loss `parseFloat` had on Slack's 16-sig-fig timestamps.
+        const ordered = [...messages].sort((a, b) => tsCmp(a.ts, b.ts));
         let dispatched = 0;
         let highestTs = wm?.lastTs ?? '0';
         for (const msg of ordered) {
             // Defense-in-depth: never re-dispatch ts <= watermark even if the
             // server returned an unexpected row.
-            if (wm && parseFloat(msg.ts) <= parseFloat(wm.lastTs))
+            if (wm && tsLte(msg.ts, wm.lastTs))
                 continue;
             const event = {
                 ts: msg.ts,
@@ -390,7 +410,7 @@ export class SlackPollingClient {
             catch (err) {
                 log.error(`dispatch error channel=${channelId} ts=${msg.ts}: ${describeErr(err)}`);
             }
-            if (parseFloat(msg.ts) > parseFloat(highestTs)) {
+            if (tsGt(msg.ts, highestTs)) {
                 highestTs = msg.ts;
             }
             // ─── Cheap thread-reply heuristic ───
@@ -404,7 +424,7 @@ export class SlackPollingClient {
             const parentTs = msg.ts;
             const replyCount = msg.reply_count ?? 0;
             const latestReply = msg.latest_reply;
-            const repliesAreNew = !!latestReply && parseFloat(latestReply) > parseFloat(wm?.lastTs ?? '0');
+            const repliesAreNew = !!latestReply && tsGt(latestReply, wm?.lastTs ?? '0');
             if (replyCount > 0 && repliesAreNew) {
                 const oldestForReplies = wm?.lastTs ?? parentTs;
                 try {
@@ -416,10 +436,10 @@ export class SlackPollingClient {
                     }));
                     const replies = (repliesRes.messages ?? []).filter((r) => !!r && typeof r.ts === 'string' && r.ts !== parentTs);
                     // conversations.replies returns oldest-first, but be defensive.
-                    const orderedReplies = [...replies].sort((a, b) => parseFloat(a.ts) - parseFloat(b.ts));
+                    const orderedReplies = [...replies].sort((a, b) => tsCmp(a.ts, b.ts));
                     for (const reply of orderedReplies) {
                         // Defense: skip ts already at or below the watermark (handles overlap).
-                        if (wm && parseFloat(reply.ts) <= parseFloat(wm.lastTs))
+                        if (wm && tsLte(reply.ts, wm.lastTs))
                             continue;
                         const replyEvent = {
                             ts: reply.ts,
@@ -437,7 +457,7 @@ export class SlackPollingClient {
                         catch (err) {
                             log.error(`dispatch error (reply) channel=${channelId} ts=${reply.ts}: ${describeErr(err)}`);
                         }
-                        if (parseFloat(reply.ts) > parseFloat(highestTs)) {
+                        if (tsGt(reply.ts, highestTs)) {
                             highestTs = reply.ts;
                         }
                     }
@@ -470,6 +490,131 @@ export class SlackPollingClient {
         }
         return dispatched;
     }
+    /**
+     * Search-mode cycle: pull every message (channels + DMs + thread replies)
+     * since "yesterday" with a single `search.messages` call (paginated). Each
+     * match is filtered against the allowlist (and keepAllDms for DMs), checked
+     * against the per-channel watermark, then dispatched. Watermark advances
+     * per channel just like the legacy path so a switch back to per-channel
+     * polling stays correct.
+     *
+     * Why "yesterday" and not the global watermark? Slack search's date
+     * operators are day-precision only (`after:YYYY-MM-DD`). We pick a 1-day
+     * lookback to make sure we always overlap with the last-seen ts. The
+     * per-channel watermark filter drops duplicates so we never re-dispatch.
+     */
+    async pollViaSearch() {
+        if (!this.webClient.search) {
+            log.error('useSearch=true but webClient has no `search.messages` method; bailing.');
+            return { dispatched: 0, pages: 0 };
+        }
+        const searchApi = this.webClient.search;
+        // Slack's date operators want YYYY-MM-DD. Use UTC; mismatched local TZ
+        // would shift the boundary by ≤1 day which is harmless (watermark filter
+        // dedupes anyway).
+        const yesterday = new Date(this.now() - 24 * 60 * 60 * 1000);
+        const y = yesterday.getUTCFullYear();
+        const m = String(yesterday.getUTCMonth() + 1).padStart(2, '0');
+        const d = String(yesterday.getUTCDate()).padStart(2, '0');
+        const query = `after:${y}-${m}-${d}`;
+        let dispatched = 0;
+        let page = 1;
+        const MAX_PAGES = 10; // ~1000 messages per cycle ceiling
+        // Track highest seen ts per channel so we advance watermark at the end.
+        const highestByChannel = new Map();
+        while (page <= MAX_PAGES) {
+            if (!this.running)
+                break;
+            let res;
+            try {
+                res = await this.paceCall(() => searchApi.messages({
+                    query,
+                    count: 100,
+                    page,
+                    sort: 'timestamp',
+                    sort_dir: 'asc',
+                }));
+            }
+            catch (err) {
+                if (isInvalidAuthError(err))
+                    throw err;
+                if (isRateLimitedError(err)) {
+                    const seconds = readRetryAfter(err) ?? 60;
+                    const until = this.now() + seconds * 1000;
+                    if (until > this.globalPauseUntil)
+                        this.globalPauseUntil = until;
+                    log.warn(`429 on search.messages page=${page}, deferred ${seconds}s`);
+                    break;
+                }
+                log.warn(`search.messages page=${page} failed: ${describeErr(err)}`);
+                break;
+            }
+            const matches = res.messages?.matches ?? [];
+            if (matches.length === 0)
+                break;
+            for (const match of matches) {
+                const channelId = match.channel?.id;
+                if (!channelId || !match.ts || typeof match.ts !== 'string')
+                    continue;
+                // Allowlist filter: respect the same rule as the legacy path so the
+                // user's "only these channels + DMs" config still gates everything.
+                if (this.allowlistChannelIds.size > 0) {
+                    const isDm = !!match.channel?.is_im || channelId.startsWith('D');
+                    const allowed = this.allowlistChannelIds.has(channelId) ||
+                        (this.keepAllDms && isDm);
+                    if (!allowed)
+                        continue;
+                }
+                // Watermark filter: drop anything we've already dispatched. Each
+                // channel keeps its own watermark so a switch back to per-channel
+                // polling later picks up exactly where search left off.
+                const wm = this.watermarkStore.get(channelId);
+                if (wm && tsLte(match.ts, wm.lastTs))
+                    continue;
+                const seen = highestByChannel.get(channelId);
+                if (seen && tsLte(match.ts, seen))
+                    continue;
+                const event = {
+                    ts: match.ts,
+                    thread_ts: match.thread_ts,
+                    channel: channelId,
+                    user: match.user,
+                    text: match.text,
+                    subtype: match.subtype,
+                    files: Array.isArray(match.files) ? match.files : undefined,
+                };
+                try {
+                    await this.dispatch(event);
+                    dispatched += 1;
+                }
+                catch (err) {
+                    log.error(`dispatch error (search) channel=${channelId} ts=${match.ts}: ${describeErr(err)}`);
+                }
+                if (!seen || tsGt(match.ts, seen)) {
+                    highestByChannel.set(channelId, match.ts);
+                }
+            }
+            // Pagination control. Slack returns `pagination.page_count` or the
+            // legacy `paging.pages`; bail when we're past the last page or when
+            // matches < count (no more left).
+            const total = res.messages?.pagination?.page_count
+                ?? res.messages?.paging?.pages
+                ?? page;
+            if (matches.length < 100)
+                break;
+            if (page >= total)
+                break;
+            page += 1;
+        }
+        // Persist per-channel watermarks for everything we dispatched this cycle.
+        for (const [channelId, highest] of highestByChannel) {
+            const existing = this.watermarkStore.get(channelId)?.lastTs;
+            if (!existing || tsGt(highest, existing)) {
+                await this.watermarkStore.set(channelId, highest);
+            }
+        }
+        return { dispatched, pages: page };
+    }
     handleFatal(reason) {
         this.fatalError = reason;
         this.running = false;
@@ -520,3 +665,112 @@ async function mapWithConcurrency(items, concurrency, worker) {
 export function asPollingWebClient(client) {
     return client;
 }
+// ─── Slack TS comparison helpers ───
+//
+// Slack timestamps are strings shaped like `XXXXXXXXXX.YYYYYY` — 10-digit
+// seconds + 6-digit microseconds. Using `parseFloat()` on them silently loses
+// precision in the last digits (JS doubles top out around 15–17 sig figs),
+// which can cause two adjacent timestamps to compare equal and a real message
+// to be silently dropped (`msg.ts <= wm.lastTs` accepting it as already-seen
+// and `msg.ts > highestTs` refusing to advance the watermark). We use BigInt
+// instead so the comparison is exact.
+function tsToBigInt(ts) {
+    if (!ts)
+        return 0n;
+    const dot = ts.indexOf('.');
+    const sec = dot === -1 ? ts : ts.slice(0, dot);
+    const micro = dot === -1 ? '' : ts.slice(dot + 1);
+    // Pad / truncate microseconds to exactly 6 digits so concatenation always
+    // produces a consistent-magnitude integer.
+    const microPadded = (micro + '000000').slice(0, 6);
+    try {
+        return BigInt(sec + microPadded);
+    }
+    catch {
+        return 0n;
+    }
+}
+/** True if `a <= b`. */
+function tsLte(a, b) {
+    return tsToBigInt(a) <= tsToBigInt(b);
+}
+/** True if `a > b`. */
+function tsGt(a, b) {
+    return tsToBigInt(a) > tsToBigInt(b);
+}
+/** Compare two ts strings for Array.sort. Returns -1, 0, or 1. */
+function tsCmp(a, b) {
+    const ab = tsToBigInt(a);
+    const bb = tsToBigInt(b);
+    return ab < bb ? -1 : ab > bb ? 1 : 0;
+}
+class TokenBucket {
+    tokens;
+    lastRefillMs;
+    waiters = [];
+    pumpScheduled = false;
+    capacity;
+    refillIntervalMs;
+    nowFn;
+    globalPauseUntilFn;
+    isRunningFn;
+    constructor(opts) {
+        this.capacity = Math.max(1, opts.capacity);
+        this.refillIntervalMs = Math.max(1, opts.refillIntervalMs);
+        this.nowFn = opts.now;
+        this.globalPauseUntilFn = opts.globalPauseUntil;
+        this.isRunningFn = opts.isRunning;
+        this.tokens = this.capacity;
+        this.lastRefillMs = opts.now();
+    }
+    refillNow() {
+        const elapsed = this.nowFn() - this.lastRefillMs;
+        if (elapsed <= 0)
+            return;
+        const gained = elapsed / this.refillIntervalMs;
+        if (gained > 0) {
+            this.tokens = Math.min(this.capacity, this.tokens + gained);
+            this.lastRefillMs = this.nowFn();
+        }
+    }
+    async acquire() {
+        if (!this.isRunningFn())
+            throw new Error('SlackPollingClient stopped');
+        // Wait through any global 429 pause before consuming a token so the
+        // entire workspace honors Retry-After.
+        const pauseRemaining = this.globalPauseUntilFn() - this.nowFn();
+        if (pauseRemaining > 0) {
+            await new Promise((r) => setTimeout(r, pauseRemaining));
+            if (!this.isRunningFn())
+                throw new Error('SlackPollingClient stopped');
+        }
+        this.refillNow();
+        if (this.tokens >= 1 && this.waiters.length === 0) {
+            this.tokens -= 1;
+            return;
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+            this.schedulePump();
+        });
+    }
+    schedulePump() {
+        if (this.pumpScheduled)
+            return;
+        this.pumpScheduled = true;
+        const needed = Math.max(0, 1 - this.tokens);
+        const waitMs = Math.max(10, Math.ceil(needed * this.refillIntervalMs));
+        setTimeout(() => {
+            this.pumpScheduled = false;
+            this.refillNow();
+            while (this.tokens >= 1 && this.waiters.length > 0) {
+                this.tokens -= 1;
+                const resolve = this.waiters.shift();
+                resolve();
+            }
+            if (this.waiters.length > 0) {
+                this.schedulePump();
+            }
+        }, waitMs);
+    }
+}

package/dist/src/packages/server/integrations/slack/slack-skill.js

@@ -230,6 +230,22 @@ Disable the auto-ack by setting \`SLACK_REACT_ON_TRIGGER=false\` (accepts \`fals
 curl -s http://localhost:5174/api/slack/status
 \`\`\`
 
+## Reading Inbound Attachments from a Slack Trigger
+
+When a Slack message that fires your trigger carries file attachments (\`file_share\`, screenshots, PDFs, etc.), Tide Commander downloads the bytes server-side so you don't have to fetch them yourself. The local paths are surfaced in your prompt template under \`{{slack.attachmentsBlock}}\` (and \`{{slack.filePaths}}\` for a flat comma list).
+
+Each downloaded attachment renders as one line in the block:
+
+\`\`\`
+[attachment: /tmp/tide-commander-uploads/triggers/slack/<msgTs>-<fileId>/<filename>  mimetype=image/png  name=screenshot.png  size=124300]
+\`\`\`
+
+Use the **Read** tool directly on that absolute path — do NOT call the Slack file API yourself. Files older than 24 hours are swept automatically.
+
+If a file is too large (>25 MB) or the bot couldn't download it, the line becomes \`[attachment-skipped: too-large …]\` or \`[attachment-skipped: fetch-failed …]\` instead. In that case, surface the limitation to the user rather than silently ignoring the attachment.
+
+Per-message cap: at most 10 files are downloaded; additional files are emitted as \`[attachment-skipped: unsupported …]\`.
+
 ## Notes
 - Channel IDs look like \`C0123456789\`. Use the list channels endpoint to find them.
 - Thread timestamps look like \`1234567890.123456\`.

package/dist/src/packages/server/integrations/slack/slack-trigger-handler.js

@@ -10,6 +10,7 @@
 import * as slackClient from './slack-client.js';
 import { listInstances } from './slack-instance.js';
 import { listInstanceMetas } from './slack-instance-manifest.js';
+import { formatAttachmentLine } from '../../services/attachment-downloader.js';
 const unsubscribers = [];
 /** Env toggle: set SLACK_REACT_ON_TRIGGER=false (or 0/no/off) to disable the auto-:eyes: ack. */
 function reactOnTriggerEnabled() {
@@ -90,10 +91,24 @@ export const slackTriggerHandler = {
         const msg = event.data;
         void trigger;
         const files = msg.files ?? [];
+        const downloaded = msg.attachmentPaths ?? [];
+        const skipped = msg.skippedAttachments ?? [];
         // Resolved channel label: `#name` / `DM con @user` / `Grupo: @a, @b…`.
         // Falls back to the raw id when the resolver couldn't fetch metadata
         // (network blip, missing scope, deleted channel).
         const channelLabel = msg.channelName || msg.channel;
+        // Build the "attachments block" agents can ingest verbatim — one line per
+        // downloaded file with absolute path, plus a line per skipped file with
+        // the reason. Empty string when there are no attachments.
+        const blockLines = [];
+        for (const att of downloaded) {
+            blockLines.push(formatAttachmentLine(att));
+        }
+        for (const sk of skipped) {
+            const sizeMb = typeof sk.size === 'number' ? `${Math.round(sk.size / (1024 * 1024))}MB` : 'unknown';
+            blockLines.push(`[attachment-skipped: ${sk.reason} name=${sk.filename ?? 'unknown'} size=${sizeMb}${sk.detail ? ` detail=${sk.detail}` : ''}]`);
+        }
+        const attachmentsBlock = blockLines.join('\n');
         return {
             'slack.user': msg.userName,
             // fromName/fromId are the boss-canonical names mirroring the Slack
@@ -113,6 +128,10 @@ export const slackTriggerHandler = {
             'slack.fileIds': files.map((f) => f.id).join(','),
             'slack.fileNames': files.map((f) => f.name ?? '').filter(Boolean).join(','),
             'slack.attachmentsList': files.map((f) => f.name ?? '').filter(Boolean).join(','),
+            // New: absolute paths and ready-to-paste attachments block. Additive —
+            // existing user templates that don't reference these vars keep working.
+            'slack.filePaths': downloaded.map((a) => a.path).join(','),
+            'slack.attachmentsBlock': attachmentsBlock,
             'slack.instanceId': msg.instanceId,
             'slack.instanceName': msg.instanceId,
         };

package/dist/src/packages/server/integrations/whatsapp/whatsapp-config.js

@@ -11,6 +11,9 @@ const DEFAULT_CONFIG = {
     baseUrl: 'http://localhost:3007',
     enrichContactName: true,
     showIncomingToasts: true,
+    transcribeAudio: true,
+    whisperModel: 'medium',
+    whisperLanguage: 'Spanish',
     updatedAt: 0,
     version: '1',
 };
@@ -82,6 +85,39 @@ export const whatsappConfigSchema = [
         defaultValue: true,
         group: 'General',
     },
+    {
+        key: 'transcribeAudio',
+        label: 'Transcribe inbound audio (whisper)',
+        type: 'boolean',
+        description: 'Run the local `whisper` CLI on inbound voice notes and audio attachments. Transcription is exposed as {{whatsapp.audioTranscription}} and appended to {{whatsapp.attachmentsBlock}}. Safe no-op if whisper is not installed.',
+        defaultValue: true,
+        group: 'Audio Transcription',
+    },
+    {
+        key: 'whisperModel',
+        label: 'Whisper model',
+        type: 'select',
+        description: 'Whisper model name. Larger models are more accurate but slower on CPU.',
+        defaultValue: 'medium',
+        options: [
+            { label: 'tiny (fastest)', value: 'tiny' },
+            { label: 'base', value: 'base' },
+            { label: 'small', value: 'small' },
+            { label: 'medium (default)', value: 'medium' },
+            { label: 'large', value: 'large' },
+            { label: 'turbo', value: 'turbo' },
+        ],
+        group: 'Audio Transcription',
+    },
+    {
+        key: 'whisperLanguage',
+        label: 'Whisper language',
+        type: 'text',
+        description: 'Hint for whisper (e.g. "Spanish", "English"). Leave blank to let whisper auto-detect — slower but works for mixed inboxes.',
+        defaultValue: 'Spanish',
+        placeholder: 'Spanish',
+        group: 'Audio Transcription',
+    },
     {
         key: 'baseUrl',
         label: 'WhatsApp API Base URL',
@@ -126,6 +162,9 @@ export function getConfigValues(secrets) {
         defaultSessionId: config.defaultSessionId || '',
         enrichContactName: config.enrichContactName !== false,
         showIncomingToasts: config.showIncomingToasts !== false,
+        transcribeAudio: config.transcribeAudio !== false,
+        whisperModel: config.whisperModel || 'medium',
+        whisperLanguage: config.whisperLanguage ?? 'Spanish',
         // Mask secret values for UI display
         whatsappApiKey: secrets.get(WHATSAPP_API_KEY_SECRET) ? '********' : '',
         webhookVerifyToken: config.webhookVerifyToken ? '********' : '',
@@ -151,6 +190,13 @@ export async function setConfigValues(values, secrets) {
         updates.enrichContactName = values.enrichContactName;
     if (typeof values.showIncomingToasts === 'boolean')
         updates.showIncomingToasts = values.showIncomingToasts;
+    if (typeof values.transcribeAudio === 'boolean')
+        updates.transcribeAudio = values.transcribeAudio;
+    if (typeof values.whisperModel === 'string' && values.whisperModel)
+        updates.whisperModel = values.whisperModel;
+    if (typeof values.whisperLanguage === 'string') {
+        updates.whisperLanguage = values.whisperLanguage;
+    }
     if (typeof values.webhookVerifyToken === 'string' &&
         values.webhookVerifyToken &&
         values.webhookVerifyToken !== '********') {

package/dist/src/packages/server/integrations/whatsapp/whatsapp-skill.js

@@ -53,6 +53,18 @@ curl -s -X POST -H "X-Auth-Token: abcd" http://localhost:5174/api/whatsapp/send-
   -d '{"to":"5215532967210","mediaUrl":"https://example.com/cat.png","caption":"meow","type":"image"}'
 \`\`\`
 
+### 4. Read an attachment from an inbound WhatsApp trigger
+
+When your trigger fires from an inbound WhatsApp message that has media, Tide Commander downloads the bytes server-side and surfaces the local path in your prompt template under \`{{whatsapp.attachmentsBlock}}\` (and \`{{whatsapp.attachmentPath}}\` individually). The block looks like:
+
+\`\`\`
+[attachment: /tmp/tide-commander-uploads/triggers/whatsapp/<msgId>/<filename>  mimetype=image/jpeg  name=photo.jpg  size=124300]
+\`\`\`
+
+Use the **Read** tool directly on that path — do NOT try to fetch the original \`mediaUrl\` (it's an encrypted Meta CDN URL that you can't decrypt). Files older than 24 hours are swept automatically.
+
+If the line says \`[attachment-skipped: too-large …]\` or \`[attachment-skipped: fetch-failed …]\` instead, the bytes were not saved and you should respond accordingly (ask the user to re-send, or proceed without the attachment).
+
 ---
 
 ## Send a Text Message (full reference)