@0xmaxma/claude-gateway 1.8.9 → 1.8.11

package/dist/agent/runner.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRunner = exports.CHANNEL_COALESCE_WINDOW_MS = exports.DEFAULT_MODELS = exports.MAX_IMAGE_SIZE_BYTES = void 0;
+exports.AgentRunner = exports.CHANNEL_COALESCE_WINDOW_MS = exports.WHATSAPP_CLOUD_WINDOW_NOTE = exports.DEFAULT_MODELS = exports.MAX_IMAGE_SIZE_BYTES = void 0;
 exports.toRelMediaFiles = toRelMediaFiles;
 const crypto_1 = require("crypto");
 const events_1 = require("events");
@@ -51,6 +51,9 @@ const receiver_1 = require("../telegram/receiver");
 const receiver_2 = require("../discord/receiver");
 const line_reply_manager_1 = require("./line-reply-manager");
 const slack_client_1 = require("../api/slack-client");
+const whatsapp_cloud_client_1 = require("../api/whatsapp-cloud-client");
+const manager_1 = require("../whatsapp/manager");
+const whatsapp_accounts_1 = require("../config/whatsapp-accounts");
 const markdown_1 = require("../telegram/markdown");
 const skills_1 = require("../skills");
 const builtin_commands_1 = require("./builtin-commands");
@@ -125,6 +128,15 @@ const PROTECTED_WORKSPACE_FILES = [
     'AGENTS.md', 'SOUL.md', 'MEMORY.md', 'CLAUDE.md',
     'IDENTITY.md', 'USER.md', 'HEARTBEAT.md',
 ];
+/**
+ * One-line reminder injected into every `whatsapp_cloud` turn's <channel>
+ * block (see buildChannelXml) — the 24h customer-service window is a
+ * WhatsApp-Business-only rule the agent cannot infer from the turn itself.
+ *
+ * Must stay free of `--` so it remains a well-formed XML comment.
+ */
+exports.WHATSAPP_CLOUD_WINDOW_NOTE = '[WhatsApp Business: free-form replies only work within 24h of the user\'s last message. ' +
+    'Outside that window, whatsapp_cloud_reply requires template_name + template_language (see templatesEnabled).]';
 const MAX_API_IMAGES = 5;
 /** Extra time an api turn may keep running AFTER its soft timeout already
  *  answered the caller (#75). The soft timeout only abandons the WAIT — the
@@ -236,6 +248,29 @@ class AgentRunner extends events_1.EventEmitter {
         // it exists only so writeAutoForward's fallback/command-reply path (below) has
         // somewhere to actually deliver Slack messages instead of silently dropping them.
         this.slackOutbound = null;
+        // WhatsApp Cloud mirrors Slack exactly: webhook-based, real credentials, no
+        // reply-token TTL to work around — a plain client so writeAutoForward's
+        // fallback/command-reply path has somewhere to deliver messages instead of
+        // silently dropping them (see the Slack comment just above).
+        this.whatsAppCloudOutbound = null;
+        // One live Baileys socket per linked WhatsApp account, keyed by account id
+        // (Phase 1 of the WhatsApp feature-parity plan — this used to be a single
+        // `whatsapp: WhatsAppManager | null`). Populated in start() (needs
+        // this.callbackPort, only resolved once startCallbackServer() runs — same
+        // reason DiscordReceiver/TelegramReceiver are built there too) and then
+        // DIFFED, never rebuilt wholesale, by syncWhatsAppAccounts(): unlike
+        // SlackClient/DiscordReceiver there is no credential to re-read on a config
+        // change, since the credential IS the on-disk session (see
+        // WhatsAppAccountConfig's doc comment), so tearing a linked socket down on
+        // an unrelated config edit would be pure downtime. Each manager decides for
+        // itself whether there's anything to do on start (resumeIfLinked() no-ops
+        // if that account was never linked).
+        this.whatsappAccounts = new Map();
+        // chatId → the account id its last inbound message arrived on. Mirrors
+        // slackThreadTs above: it lets writeAutoForward (and a whatsapp_reply call
+        // that omits account_id) answer on the SAME number the user wrote to
+        // instead of guessing 'default' and replying from the wrong line.
+        this.whatsappAccountForChat = new Map();
         this.idleCleanerTimer = null;
         // Tracks session IDs with an in-flight API request (prevents concurrent turns)
         this.pendingApiSessions = new Set();
@@ -439,7 +474,11 @@ class AgentRunner extends events_1.EventEmitter {
                             ? 'line'
                             : meta['source'] === 'slack'
                                 ? 'slack'
-                                : 'telegram');
+                                : meta['source'] === 'whatsapp'
+                                    ? 'whatsapp'
+                                    : meta['source'] === 'whatsapp_cloud'
+                                        ? 'whatsapp_cloud'
+                                        : 'telegram');
                     this.channelSourceMap.set(chatId, channelSource);
                     // Slack: remember the current message's thread context so the
                     // auto-forward fallback (writeAutoForward) can stay in-thread. A
@@ -452,6 +491,14 @@ class AgentRunner extends events_1.EventEmitter {
                         else
                             this.slackThreadTs.delete(chatId);
                     }
+                    // WhatsApp: remember which linked number this chat last came in on,
+                    // so a reply that doesn't name an account_id (the auto-forward
+                    // fallback, or a whatsapp_reply call that omitted it) still goes out
+                    // on the number the user actually wrote to. Same shape as the Slack
+                    // thread-context stash just above.
+                    if (channelSource === 'whatsapp' && meta['account_id']) {
+                        this.whatsappAccountForChat.set(chatId, meta['account_id']);
+                    }
                     // LINE slow-LLM postback: stash this turn's reply token + arm the
                     // button timer before the token expires. In groups/rooms the shared
                     // button is disabled (armButton:false) — the token is still stashed so
@@ -1027,7 +1074,7 @@ class AgentRunner extends events_1.EventEmitter {
             for (const entry of entries) {
                 const meta = entry.meta ?? {};
                 const content = entry.content ?? '';
-                const userContent = content || (meta['attachment_file_id'] || meta['image_path'] ? '(photo)' : '');
+                const userContent = content || (meta['attachment_file_id'] || meta['image_path'] ? '(photo)' : meta['document_path'] ? '(document)' : meta['sticker_path'] ? '(sticker)' : '');
                 const userTs = Date.now();
                 await this.sessionStore.appendTelegramMessage(this.agentConfig.id, chatId, sessionId, {
                     role: 'user',
@@ -1058,6 +1105,33 @@ class AgentRunner extends events_1.EventEmitter {
                         // Non-fatal — leave the original path so host agents still read it
                     }
                 }
+                // WhatsApp Cloud documents (PDF today — see MediaStore.isAllowedMime):
+                // same MediaStore copy + path-rewrite as image_path above, parallel
+                // key so an inbound document doesn't collide with an inbound image
+                // in the same turn.
+                if (meta['document_path']) {
+                    try {
+                        const rel = media_store_1.MediaStore.copyToMedia(this.agentsBaseDir, this.agentConfig.id, `${channelSource}-${chatId}`, meta['document_path']);
+                        mediaFiles.push(rel);
+                        meta['document_path'] = media_store_1.MediaStore.resolvePath(this.agentsBaseDir, this.agentConfig.id, rel);
+                    }
+                    catch {
+                        // Non-fatal — leave the original path so host agents still read it
+                    }
+                }
+                // WhatsApp stickers (both channels — image/webp): same MediaStore
+                // copy + path-rewrite as image_path above, on its own key so an
+                // inbound sticker never masquerades as a photo.
+                if (meta['sticker_path']) {
+                    try {
+                        const rel = media_store_1.MediaStore.copyToMedia(this.agentsBaseDir, this.agentConfig.id, `${channelSource}-${chatId}`, meta['sticker_path']);
+                        mediaFiles.push(rel);
+                        meta['sticker_path'] = media_store_1.MediaStore.resolvePath(this.agentsBaseDir, this.agentConfig.id, rel);
+                    }
+                    catch {
+                        // Non-fatal — leave the original path so host agents still read it
+                    }
+                }
                 this.historyDb.insertMessage({
                     chatId: `${channelSource}-${chatId}`,
                     sessionId,
@@ -1068,6 +1142,14 @@ class AgentRunner extends events_1.EventEmitter {
                     senderId: meta['user_id'] ?? meta['chat_id'] ?? undefined,
                     platformMessageId: meta['message_id'] ?? undefined,
                     mediaFiles: mediaFiles.length > 0 ? mediaFiles : undefined,
+                    // Reply context (WhatsApp Phase 2) — the same meta keys buildChannelXml
+                    // renders into <replied> for the agent, persisted so the web dashboard
+                    // can show "in reply to X" instead of losing it after the turn.
+                    // whatsapp_cloud only ever sets replied_message_id (its webhook reports
+                    // the quoted id and nothing else), so the other two stay undefined there.
+                    repliedToMessageId: meta['replied_message_id'] ?? undefined,
+                    repliedToText: meta['replied_text'] ?? undefined,
+                    repliedToUser: meta['replied_user'] ?? undefined,
                     ts: userTs,
                 });
             }
@@ -1219,6 +1301,54 @@ class AgentRunner extends events_1.EventEmitter {
             `Do NOT open or Read the referenced files first — the image model receives the actual files; ` +
             `reading them wastes minutes and can push the request past its timeout. Go straight to generate_image.\n`);
     }
+    /**
+     * Render composer-selected video options as a directive the agent reads and
+     * forwards to the generate_video MCP tool. Mirrors buildImageParamsNote. Returns
+     * '' when no usable options are present. Without this the agent gets no composer
+     * context for video and invents duration/aspect (a phantom 10s cap, an 8+8 scene
+     * split, or a landscape clip when 9:16 was picked).
+     */
+    static buildVideoParamsNote(p) {
+        const attrs = [
+            p.model ? `model="${AgentRunner.escapeXmlAttr(p.model)}"` : '',
+            p.resolution ? `resolution="${AgentRunner.escapeXmlAttr(p.resolution)}"` : '',
+            p.aspect_ratio ? `aspect_ratio="${AgentRunner.escapeXmlAttr(p.aspect_ratio)}"` : '',
+            typeof p.duration === 'number' ? `duration="${p.duration}"` : '',
+            p.image_ref ? `image_ref="${AgentRunner.escapeXmlAttr(p.image_ref)}"` : '',
+        ].filter(Boolean);
+        if (!attrs.length)
+            return '';
+        // The generate_video schema lets the agent pick model/duration itself; when the
+        // composer selection isn't made authoritative the agent falls back to
+        // action="list" and self-selects, or invents a duration cap and splits the clip
+        // into multiple scenes. Nail every field down.
+        const modelNote = p.model
+            ? `The user explicitly SELECTED model="${AgentRunner.escapeXmlAttr(p.model)}" in the composer. ` +
+                `Call generate_video with that exact model — do NOT call action="list" to second-guess an ` +
+                `explicit selection or substitute a different model.\n`
+            : '';
+        const durationNote = typeof p.duration === 'number'
+            ? `duration=${p.duration} is a valid length for the selected model — pass it verbatim as the "duration" ` +
+                `argument. Do NOT invent a maximum, do NOT clamp it to a smaller value, and do NOT split the request ` +
+                `into multiple shorter scenes/clips. Generate exactly ONE clip of this duration.\n`
+            : '';
+        const aspectNote = p.aspect_ratio
+            ? `Pass aspect_ratio="${AgentRunner.escapeXmlAttr(p.aspect_ratio)}" verbatim — do NOT change the orientation.\n`
+            : '';
+        const refNote = p.image_ref
+            ? `The user selected a source image for image-to-video. Pass image_ref="${AgentRunner.escapeXmlAttr(p.image_ref)}" ` +
+                `as the "image" argument of generate_video (the source frame's own aspect then wins). ` +
+                `Do NOT call list_refs to second-guess it, and do NOT open or Read the file first.\n`
+            : '';
+        return (`<video-params ${attrs.join(' ')} />\n` +
+            `The user selected the video-generation options above in the composer. When the request involves ` +
+            `creating a video, call the generate_video tool (action="generate") using these exact values, then ` +
+            `deliver the returned video with your reply tool.\n` +
+            modelNote +
+            durationNote +
+            aspectNote +
+            refNote);
+    }
     /**
      * The durable slice of the composer image options — everything except
      * `image_refs`, which is a per-turn explicit selection (#73) and must never be
@@ -1238,16 +1368,26 @@ class AgentRunner extends events_1.EventEmitter {
      * session path; refs that were never staged (catalog refs, artifact:<id>)
      * pass through untouched. (#74)
      */
-    static remapImageParamsRefs(p, stagedPaths, promotedPaths) {
-        if (!p || !stagedPaths?.length || !promotedPaths?.length)
-            return p;
+    // Build the staging→promoted path map: promoteUiUploads moves a turn's
+    // ui-upload files into per-session storage, so any ref built from a staging
+    // path must follow the file to its new location (#74). Empty map = nothing
+    // moved (or no uploads), so callers leave their refs untouched.
+    static buildRefRemap(stagedPaths, promotedPaths) {
         const map = new Map();
+        if (!stagedPaths?.length || !promotedPaths?.length)
+            return map;
         for (let i = 0; i < Math.min(stagedPaths.length, promotedPaths.length); i++) {
             const from = stagedPaths[i];
             const to = promotedPaths[i];
             if (from !== to)
                 map.set(from, to);
         }
+        return map;
+    }
+    static remapImageParamsRefs(p, stagedPaths, promotedPaths) {
+        if (!p)
+            return p;
+        const map = AgentRunner.buildRefRemap(stagedPaths, promotedPaths);
         if (!map.size)
             return p;
         const remap = (r) => map.get(r) ?? r;
@@ -1257,10 +1397,26 @@ class AgentRunner extends events_1.EventEmitter {
             ...(p.image_refs?.length ? { image_refs: p.image_refs.map(remap) } : {}),
         };
     }
+    // Video analogue of remapImageParamsRefs. The composer's image-to-video
+    // source frame (VideoParams.image_ref) is built from a staging path; without
+    // this remap the raw ref dangles after promoteUiUploads moves the file, and
+    // generate_video fails share_ref_not_found. artifact:/catalog refs aren't in
+    // the map, so they pass through untouched.
+    static remapVideoParamsRefs(p, stagedPaths, promotedPaths) {
+        if (!p?.image_ref)
+            return p;
+        const to = AgentRunner.buildRefRemap(stagedPaths, promotedPaths).get(p.image_ref);
+        return to ? { ...p, image_ref: to } : p;
+    }
     static buildChannelXml(params) {
         const meta = params.meta ?? {};
         const optionalAttrs = [
             'image_path',
+            'document_path', // WhatsApp Cloud: inbound PDF document (see MediaStore.isAllowedMime)
+            'sticker_path', // WhatsApp (both channels): inbound sticker — kept distinct from image_path so the agent can tell a sticker from a photo
+            'location_lat', // WhatsApp (both channels): inbound location pin
+            'location_lng',
+            'vcard', // WhatsApp: inbound contact card — raw vCard on Baileys, synthesized from Meta's structured payload on Cloud
             'attachment_file_id',
             'attachment_kind',
             'attachment_mime',
@@ -1268,6 +1424,8 @@ class AgentRunner extends events_1.EventEmitter {
             'user_id', // LINE: the userId the session passes back to line_reply
             'reply_token', // LINE: single-use reply token (push is preferred; surfaced for completeness)
             'thread_ts', // Slack: set when the inbound message is inside a thread — pass back as thread_id to slack_reply to reply in-thread
+            'account_id', // WhatsApp: which linked number this arrived on — pass back to whatsapp_reply to answer on the same one
+            'interactive_id', // WhatsApp Cloud: the id of the tapped button / picked list row (content already carries its title)
             // NOTE: message_id is NOT listed here — the base <channel> template below
             // already unconditionally emits it; adding it here would duplicate the
             // attribute in the XML whenever meta.message_id is set (any channel).
@@ -1280,6 +1438,10 @@ class AgentRunner extends events_1.EventEmitter {
         if (meta['replied_message_id']) {
             const repliedAttrs = [
                 'replied_image_path',
+                'replied_attachment_file_id',
+                'replied_attachment_kind',
+                'replied_attachment_mime',
+                'replied_attachment_name',
             ]
                 .filter(k => meta[k])
                 .map(k => ` ${k}="${meta[k].replace(/"/g, '&quot;')}"`)
@@ -1291,9 +1453,18 @@ class AgentRunner extends events_1.EventEmitter {
                     `</replied>`;
         }
         const source = meta['source'] ?? 'telegram';
+        // Per-turn channel note (Phase 3). WhatsApp Business enforces a 24h
+        // customer-service window that no other channel here has, and the agent
+        // cannot discover it from the turn itself — it only shows up as an opaque
+        // Meta error at send time. Emitted as an XML COMMENT so it can never be
+        // mistaken for part of the user's message, and kept to ONE short line
+        // because it repeats on every single whatsapp_cloud turn. (A frozen,
+        // system-prompt-level injection would be new infra for one warning; the
+        // per-turn wrapper is the existing seam.)
+        const channelNote = source === 'whatsapp_cloud' ? `<!-- ${exports.WHATSAPP_CLOUD_WINDOW_NOTE} -->` : '';
         return (`<channel source="${source}" chat_id="${meta['chat_id'] ?? ''}" ` +
             `message_id="${meta['message_id'] ?? ''}" user="${AgentRunner.escapeXmlAttr(meta['user'] ?? '')}" ` +
-            `ts="${meta['ts'] ?? new Date().toISOString()}"${optionalAttrs}>${repliedBlock}${params.content ?? ''}</channel>`);
+            `ts="${meta['ts'] ?? new Date().toISOString()}"${optionalAttrs}>${channelNote}${repliedBlock}${params.content ?? ''}</channel>`);
     }
     /**
      * Await a SessionProcess's in-flight crash-triggered auto-restart
@@ -1552,7 +1723,11 @@ class AgentRunner extends events_1.EventEmitter {
                     ? 'mcp__gateway__line_reply'
                     : source === 'slack'
                         ? 'mcp__gateway__slack_reply'
-                        : 'mcp__gateway__telegram_reply';
+                        : source === 'whatsapp'
+                            ? 'mcp__gateway__whatsapp_reply'
+                            : source === 'whatsapp_cloud'
+                                ? 'mcp__gateway__whatsapp_cloud_reply'
+                                : 'mcp__gateway__telegram_reply';
             proc.on('output', (line) => {
                 try {
                     const obj = JSON.parse(line);
@@ -1865,10 +2040,15 @@ class AgentRunner extends events_1.EventEmitter {
                                 }
                                 else if (channelSrcForResult !== 'discord' &&
                                     channelSrcForResult !== 'slack' &&
+                                    channelSrcForResult !== 'whatsapp' &&
+                                    channelSrcForResult !== 'whatsapp_cloud' &&
                                     ((0, markdown_1.hasMarkdown)(channelText) || (0, markdown_1.containsTelegramHtml)(channelText))) {
                                     // Telegram HTML entities — Slack has its own mrkdwn format and
                                     // would display these tags literally, so Slack skips this and
-                                    // falls through to the plain-text branch below.
+                                    // falls through to the plain-text branch below. WhatsApp (and
+                                    // WhatsApp Cloud, same lightweight markup) has
+                                    // its own lightweight markup (*bold*/_italic_/~strike~, not
+                                    // HTML), same reasoning.
                                     this.writeAutoForward(mapKey, (0, markdown_1.toTelegramHtml)(channelText), 'html', replySendFailed);
                                 }
                                 else {
@@ -2725,6 +2905,36 @@ class AgentRunner extends events_1.EventEmitter {
             }
             return;
         }
+        // WhatsApp likewise has no .forward consumer, and — unlike Slack/SMS's
+        // outbound REST clients — cannot open a fresh connection per call either
+        // (see WhatsAppManager's doc comment): reach the live socket this
+        // process already holds directly.
+        if (this.channelFor(chatId) === 'whatsapp') {
+            // No account_id to go on here (this is the fallback path, not a tool
+            // call), so whatsAppManagerFor falls back to the account this chat's
+            // last inbound message arrived on — the number the user wrote to.
+            void this.sendWhatsAppMessage(chatId, text).catch((err) => {
+                this.logger.warn('WhatsApp auto-forward failed', {
+                    chatId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+            return;
+        }
+        // WhatsApp Cloud mirrors Slack exactly (no .forward consumer, a real REST
+        // client that can open a fresh connection per call — unlike Baileys'
+        // `whatsapp` above, there's no live socket to reuse or reason to).
+        if (this.channelFor(chatId) === 'whatsapp_cloud') {
+            if (this.whatsAppCloudOutbound) {
+                void this.whatsAppCloudOutbound.sendText(chatId, text).catch((err) => {
+                    this.logger.warn('WhatsApp Cloud auto-forward failed', {
+                        chatId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            }
+            return;
+        }
         const typingDir = this.getTypingDir(chatId);
         const forwardPath = path.join(typingDir, `${chatId}.forward`);
         try {
@@ -2824,6 +3034,15 @@ class AgentRunner extends events_1.EventEmitter {
         // line_reply tool keeps the plain reply-first → push-fallback path).
         this.startLineReply();
         this.startSlackOutbound();
+        this.startWhatsAppCloudOutbound();
+        // Unconditional (unlike every credential-gated channel above) — each
+        // WhatsAppManager checks disk for a previously-linked session itself;
+        // there's no config field to gate on, and an agent with no `whatsapp`
+        // block still gets the implicit 'default' account (see
+        // resolveWhatsAppAccounts). A brand-new agent that's never linked just
+        // no-ops here and stays 'unlinked' until the user starts a QR/pairing
+        // flow via the API.
+        this.syncWhatsAppAccounts();
         this.startIdleCleaner();
         this._startCleanupScheduler();
         this.logger.info('AgentRunner started', { agentId: this.agentConfig.id });
@@ -2877,6 +3096,129 @@ class AgentRunner extends events_1.EventEmitter {
         // it up, same reasoning as LineReplyManager above.
         this.stopSlackOutbound();
         this.startSlackOutbound();
+        // WhatsApp Cloud credentials may have changed (or been cleared) — rebuild
+        // to pick it up, same reasoning as Slack above.
+        this.stopWhatsAppCloudOutbound();
+        this.startWhatsAppCloudOutbound();
+        // WhatsApp has no credential to rebuild on — push the new config
+        // (access-control fields) into every already-running manager, and
+        // add/remove managers only if the set of configured accounts changed.
+        this.syncWhatsAppAccounts();
+    }
+    /**
+     * Reconcile `this.whatsappAccounts` with `agentConfig.whatsapp.accounts`.
+     *
+     * Diffing (rather than teardown+recreate) is load-bearing here: a manager
+     * holds a live, authenticated Baileys socket that can take tens of seconds
+     * to re-establish, so an edit to account "sales" must not drop account
+     * "default"'s connection. Accounts that survive the diff only get the new
+     * AgentConfig pushed into them — their socket is untouched.
+     *
+     * Removal uses stop() (socket teardown), never unlink(): dropping an
+     * account from config must not silently wipe its on-disk session. The
+     * DELETE .../whatsapp/accounts/:id route unlinks explicitly before it
+     * rewrites config.
+     */
+    syncWhatsAppAccounts() {
+        const snapshot = JSON.stringify(this.agentConfig.whatsapp ?? null);
+        const accounts = (0, whatsapp_accounts_1.resolveWhatsAppAccounts)(this.agentConfig.whatsapp);
+        // Always push the fresh config into live managers — access-control fields
+        // are read live off it on every inbound message.
+        for (const manager of this.whatsappAccounts.values()) {
+            manager.updateAgentConfig(this.agentConfig);
+        }
+        // Nothing about the WhatsApp block moved ⇒ the account SET can't have
+        // changed either, so skip the diff entirely.
+        if (this.whatsappConfigSnapshot === snapshot && this.whatsappAccounts.size > 0)
+            return;
+        this.whatsappConfigSnapshot = snapshot;
+        const wanted = new Set(accounts.map((a) => a.id));
+        for (const [accountId, manager] of [...this.whatsappAccounts]) {
+            if (wanted.has(accountId))
+                continue;
+            manager.stop();
+            this.whatsappAccounts.delete(accountId);
+            this.logger.info('WhatsApp account removed', { agentId: this.agentConfig.id, accountId });
+        }
+        for (const account of accounts) {
+            if (this.whatsappAccounts.has(account.id))
+                continue;
+            const manager = new manager_1.WhatsAppManager(this.agentConfig, account.id, this.callbackPort, this.gatewayConfig.gateway.logDir);
+            this.whatsappAccounts.set(account.id, manager);
+            void manager.resumeIfLinked();
+            this.logger.info('WhatsApp account started', { agentId: this.agentConfig.id, accountId: account.id });
+        }
+    }
+    /** Live managers, in configured order. */
+    whatsAppManagers() {
+        return (0, whatsapp_accounts_1.resolveWhatsAppAccounts)(this.agentConfig.whatsapp)
+            .map((a) => this.whatsappAccounts.get(a.id))
+            .filter((m) => !!m);
+    }
+    /**
+     * Pick the manager a call should use.
+     *
+     * An EXPLICIT accountId must exist — silently falling back would send a
+     * reply from the wrong number, which on WhatsApp is visible to the
+     * recipient and unrecoverable. Without one, prefer the account the chat's
+     * last inbound message arrived on (so a reply leaves on the number the user
+     * actually wrote to), then 'default', then — for an agent whose only
+     * account is named something else — its single account.
+     */
+    whatsAppManagerFor(chatId, accountId) {
+        if (accountId) {
+            const explicit = this.whatsappAccounts.get(accountId);
+            if (!explicit)
+                throw new Error(`Unknown WhatsApp account '${accountId}'`);
+            return explicit;
+        }
+        const remembered = chatId ? this.whatsappAccountForChat.get(chatId) : undefined;
+        const managers = this.whatsAppManagers();
+        const picked = (remembered ? this.whatsappAccounts.get(remembered) : undefined) ??
+            this.whatsappAccounts.get(whatsapp_accounts_1.DEFAULT_WHATSAPP_ACCOUNT_ID) ??
+            managers[0];
+        if (!picked)
+            throw new Error('Agent not started');
+        return picked;
+    }
+    /**
+     * Which account id a send to `chatId` (with an optional explicit
+     * `accountId`) would actually use — the same resolution
+     * `sendWhatsAppMessage` applies internally, exposed read-only so a caller
+     * (the `/whatsapp/send` route) can run access-control/path-confinement
+     * checks against the REAL target account without duplicating or
+     * second-guessing this resolution logic. Throws the same errors
+     * `whatsAppManagerFor` would (unknown account / agent not started).
+     */
+    resolveWhatsAppAccountId(chatId, accountId) {
+        return this.whatsAppManagerFor(chatId, accountId).accountId;
+    }
+    /** Live link status for one account (defaults to 'default'). */
+    getWhatsAppStatus(accountId = whatsapp_accounts_1.DEFAULT_WHATSAPP_ACCOUNT_ID) {
+        return this.whatsappAccounts.get(accountId)?.getStatus();
+    }
+    /** Configured account ids that currently have a live manager. */
+    getWhatsAppAccountIds() {
+        return this.whatsAppManagers().map((m) => m.accountId);
+    }
+    async startWhatsAppLinking(accountId) {
+        await this.whatsAppManagerFor(undefined, accountId).startLinking();
+    }
+    async requestWhatsAppPairingCode(phoneNumber, accountId) {
+        return this.whatsAppManagerFor(undefined, accountId).requestPairingCode(phoneNumber);
+    }
+    async unlinkWhatsApp(accountId) {
+        await this.whatsAppManagerFor(undefined, accountId).unlink();
+    }
+    async sendWhatsAppMessage(jid, text, imagePath, accountId, 
+    /**
+     * Phase 2 extras, all optional so existing callers (auto-forward, older
+     * MCP builds) are unaffected: quote an inbound message, send the image
+     * uncompressed as a document, and clear the ⏳ ack left on the inbound
+     * message once the send lands.
+     */
+    opts) {
+        await this.whatsAppManagerFor(jid, accountId).sendMessage(jid, text, imagePath, opts);
     }
     startSlackOutbound() {
         if (!this.agentConfig.slack?.botToken || !this.agentConfig.slack?.signingSecret)
@@ -2891,6 +3233,21 @@ class AgentRunner extends events_1.EventEmitter {
     stopSlackOutbound() {
         this.slackOutbound = null;
     }
+    startWhatsAppCloudOutbound() {
+        const cfg = this.agentConfig.whatsapp_cloud;
+        if (!cfg?.accessToken || !cfg?.phoneNumberId || !cfg?.appSecret || !cfg?.verifyToken)
+            return;
+        if (this.whatsAppCloudOutbound)
+            return; // already running
+        this.whatsAppCloudOutbound = new whatsapp_cloud_client_1.WhatsAppCloudClient({
+            accessToken: cfg.accessToken,
+            phoneNumberId: cfg.phoneNumberId,
+            logDir: this.gatewayConfig.gateway.logDir,
+        });
+    }
+    stopWhatsAppCloudOutbound() {
+        this.whatsAppCloudOutbound = null;
+    }
     startLineReply() {
         const lineThreshold = this.agentConfig.line?.slowResponseThreshold ?? 45;
         if (!this.agentConfig.line?.channelSecret || !this.agentConfig.line?.channelAccessToken || lineThreshold <= 0)
@@ -2987,6 +3344,16 @@ class AgentRunner extends events_1.EventEmitter {
         // teardown rather than serially — both are bounded, neither depends on the
         // other, and shutdown latency is user-visible.
         const receiversStopped = [this.receiver?.stop(), this.discordReceiver?.stop()];
+        // stop(), not unlink() — gateway shutdown should NOT wipe a linked
+        // session; resumeIfLinked() picks each account back up on next boot.
+        // Synchronous (no socket-close promise to await), unlike the receivers above.
+        for (const manager of this.whatsappAccounts.values())
+            manager.stop();
+        this.whatsappAccounts.clear();
+        this.whatsappAccountForChat.clear();
+        // Force syncWhatsAppAccounts() to rebuild from scratch if this runner is
+        // started again, rather than short-circuiting on a stale snapshot.
+        this.whatsappConfigSnapshot = undefined;
         this.stopLineReply();
         await Promise.all([
             ...receiversStopped,
@@ -3090,6 +3457,8 @@ class AgentRunner extends events_1.EventEmitter {
         // Refs built from staging paths must follow the files to their promoted
         // location — see remapImageParamsRefs (#74).
         const imageParams = AgentRunner.remapImageParamsRefs(opts.imageParams, opts.mediaFiles, finalMediaFiles);
+        // The image-to-video source frame follows the same staging→promoted move.
+        const videoParams = AgentRunner.remapVideoParamsRefs(opts.videoParams, opts.mediaFiles, finalMediaFiles);
         // Resolve media files to absolute paths for file-path based image passing
         // (same pattern as Telegram — Claude Code reads files via Read tool instead of base64 inline)
         const imagePaths = finalMediaFiles?.length ? this.resolveMediaPaths(finalMediaFiles) : [];
@@ -3145,6 +3514,7 @@ class AgentRunner extends events_1.EventEmitter {
         // Build channel XML with image_path attribute (like Telegram) for first image
         const imageAttr = effectiveImagePaths.length ? ` image_path="${AgentRunner.escapeXmlAttr(effectiveImagePaths[0])}"` : '';
         const imageParamsNote = imageParams ? AgentRunner.buildImageParamsNote(imageParams) : '';
+        const videoParamsNote = videoParams ? AgentRunner.buildVideoParamsNote(videoParams) : '';
         // Persist the composer image options to session meta so the web can restore the
         // selection on reload (SessionMeta.imageConfig). Only when the send carries them
         // (the web sends image_params on first-set/change), so this holds the latest.
@@ -3156,10 +3526,17 @@ class AgentRunner extends events_1.EventEmitter {
                 .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { imageConfig: durableImageConfig }, 'api')
                 .catch(() => { });
         }
+        // Persist composer video options the same way (SessionMeta.videoConfig).
+        if (videoParams) {
+            this.sessionStore
+                .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { videoConfig: videoParams }, 'api')
+                .catch(() => { });
+        }
         const channelXml = `<channel source="api" chat_id="${chatId}" session_id="${sessionId}" ts="${new Date().toISOString()}"${imageAttr}>\n` +
             `${message}\n\n` +
             `${systemNote}` +
             `${imageParamsNote}` +
+            `${videoParamsNote}` +
             `</channel>` +
             (skillInvocation ? `\n${(0, skills_1.formatSkillContext)(skillInvocation)}` : '');
         return new Promise((resolve, reject) => {
@@ -3362,6 +3739,8 @@ class AgentRunner extends events_1.EventEmitter {
         // Refs built from staging paths must follow the files to their promoted
         // location — see remapImageParamsRefs (#74).
         const imageParamsStream = AgentRunner.remapImageParamsRefs(opts.imageParams, opts.mediaFiles, finalMediaFilesStream);
+        // The image-to-video source frame follows the same staging→promoted move.
+        const videoParamsStream = AgentRunner.remapVideoParamsRefs(opts.videoParams, opts.mediaFiles, finalMediaFilesStream);
         // Resolve media files to absolute paths for file-path based image passing
         const imagePathsStream = finalMediaFilesStream?.length ? this.resolveMediaPaths(finalMediaFilesStream) : [];
         if (!opts.skipUserMessage) {
@@ -3625,6 +4004,7 @@ class AgentRunner extends events_1.EventEmitter {
         // Build channel XML with image_path attribute (like Telegram) for first image
         const imageAttrStream = effectiveImagePathsStream.length ? ` image_path="${AgentRunner.escapeXmlAttr(effectiveImagePathsStream[0])}"` : '';
         const imageParamsNoteStream = imageParamsStream ? AgentRunner.buildImageParamsNote(imageParamsStream) : '';
+        const videoParamsNoteStream = videoParamsStream ? AgentRunner.buildVideoParamsNote(videoParamsStream) : '';
         // Persist composer image config to session meta (SessionMeta.imageConfig) so the
         // web restores the selection on reload. This is the streaming path the web uses.
         // image_refs are per-turn and deliberately excluded (#73).
@@ -3637,10 +4017,17 @@ class AgentRunner extends events_1.EventEmitter {
                 .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { imageConfig: durableImageConfigStream }, 'api')
                 .catch(() => { });
         }
+        // Persist composer video options the same way (SessionMeta.videoConfig).
+        if (videoParamsStream) {
+            this.sessionStore
+                .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { videoConfig: videoParamsStream }, 'api')
+                .catch(() => { });
+        }
         const channelXml = `<channel source="api" chat_id="${chatId}" session_id="${sessionId}" ts="${new Date().toISOString()}"${imageAttrStream}>\n` +
             `${message}\n\n` +
             systemNote +
             imageParamsNoteStream +
+            videoParamsNoteStream +
             `</channel>` +
             (skillInvocationStream ? `\n${(0, skills_1.formatSkillContext)(skillInvocationStream)}` : '');
         session.setProcessing(true);