@0xmaxma/claude-gateway 1.8.13 → 2.0.0

package/dist/agent/runner.js

@@ -35,6 +35,14 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 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 channel_input_media_1 = require("../orchestration/channel-input-media");
+const chunks_1 = require("../telegram/chunks");
+const file_delivery_1 = require("../orchestration/file-delivery");
+const voice_reply_policy_1 = require("../orchestration/voice-reply-policy");
+const gateway_config_1 = require("../orchestration/gateway-config");
+const delivery_1 = require("../orchestration/delivery");
+const control_delivery_1 = require("../orchestration/control-delivery");
+const stop_controls_1 = require("../orchestration/stop-controls");
 const crypto_1 = require("crypto");
 const events_1 = require("events");
 const fs = __importStar(require("fs"));
@@ -54,6 +62,10 @@ 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 manager_2 = require("../wechat/manager");
+const ilink_client_1 = require("../wechat/ilink-client");
+const wechat_access_1 = require("../api/wechat-access");
+const pending_senders_1 = require("../api/pending-senders");
 const markdown_1 = require("../telegram/markdown");
 const skills_1 = require("../skills");
 const builtin_commands_1 = require("./builtin-commands");
@@ -71,6 +83,7 @@ const screen_1 = require("../shell/screen");
 const db_1 = require("../history/db");
 const media_store_1 = require("../history/media-store");
 const cleanup_1 = require("../history/cleanup");
+const types_1 = require("../history/types");
 const knowledge_1 = require("./knowledge");
 const resolve_1 = require("../connectors/resolve");
 const DEFAULT_IDLE_TIMEOUT_MINUTES = 30;
@@ -221,6 +234,229 @@ class AgentRunner extends events_1.EventEmitter {
     channelFor(chatId) {
         return this.channelSourceMap.get(chatId) ?? 'telegram';
     }
+    requiresDurableChannelIngress(source) {
+        return Boolean((this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes(source)) ||
+            this.orchestration?.ownsChannelIngress(source));
+    }
+    orchestrationForApi(sessionId) {
+        return Boolean((this.orchestration?.ownsSession(sessionId) && !this.orchestration.canReturnToLegacy()) ||
+            (this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes('api')));
+    }
+    async sendLinkedOrchestrationChannel(...[binding, text, _id, file]) {
+        const channel = String(binding.channel), chat = String(binding.chat_id);
+        if (channel === 'wechat' && file)
+            return { state: 'failed', code: 'CHANNEL_ATTACHMENTS_UNSUPPORTED' };
+        let path;
+        if (file) {
+            try {
+                path = (0, file_delivery_1.resolveChannelFile)(this.agentConfig, file).path;
+            }
+            catch {
+                return { state: 'failed', code: 'ATTACHMENT_UNAVAILABLE' };
+            }
+        }
+        try {
+            if (channel === 'whatsapp') {
+                // Persist the receiving number in the binding; an in-memory last-chat map
+                // can change while a worker is running or disappear after a restart.
+                const thread = String(binding.thread_key ?? '');
+                const account = thread.startsWith('whatsapp-account:') ? thread.slice('whatsapp-account:'.length) : undefined;
+                await this.sendWhatsAppMessage(chat, file?.caption || text, path, account, { asDocument: !!file && file.kind !== 'image' });
+            }
+            else if (channel === 'wechat')
+                await this.sendWeChatMessage(chat, text);
+            else
+                return { state: 'failed', code: 'DELIVERY_NOT_CONFIGURED' };
+            return { state: 'delivered' };
+        }
+        catch {
+            return { state: 'unknown', code: 'PROVIDER_RECEIPT_UNKNOWN' };
+        }
+    }
+    async sendOrchestrationControl(channel, chatId, menu, meta) {
+        if (!['whatsapp', 'whatsapp_cloud', 'wechat'].includes(channel))
+            return (0, control_delivery_1.sendControlMenu)(this.agentConfig, channel, chatId, menu, meta);
+        const text = [menu.text, ...menu.buttons.map(button => `${button.label}: /orch ${button.data.replace(/^orch:/, '')}`)].join('\n');
+        const send = (0, delivery_1.channelSender)(() => this.agentConfig, fetch, () => false, (...args) => this.sendLinkedOrchestrationChannel(...args));
+        for (const part of (0, chunks_1.chunkText)(text, 1900)) {
+            const result = await send({ channel, chat_id: chatId, thread_key: channel === 'whatsapp' && meta.account_id ? `whatsapp-account:${meta.account_id}` : '' }, part, (0, crypto_1.randomUUID)());
+            if (result.state !== 'delivered')
+                throw new Error(result.code);
+        }
+    }
+    async getOrchestration() {
+        if (this.orchestration)
+            return this.orchestration;
+        if (!this.orchestrationStarting) {
+            this.orchestrationStarting = Promise.resolve().then(() => __importStar(require('../orchestration/runtime'))).then(({ AgentOrchestrationRuntime }) => AgentOrchestrationRuntime.open(this.agentConfig, this.gatewayConfig, this.agentDir, this.sessionStore, this.historyDb, {
+                sendLinkedChannel: (...args) => this.sendLinkedOrchestrationChannel(...args),
+                skills: () => this.skillRegistry,
+                refreshSkills: async () => {
+                    try {
+                        const { discoverCliSkills } = await Promise.resolve().then(() => __importStar(require('../orchestration/cli-skills')));
+                        this.skillRegistry.cliSkills = await discoverCliSkills(this.agentConfig, undefined, this.gatewayConfig);
+                        delete this.skillRegistry.cliDiscoveryError;
+                    }
+                    catch {
+                        this.skillRegistry.cliSkills = [];
+                        this.skillRegistry.cliDiscoveryError = 'CLI_SKILL_DISCOVERY_UNAVAILABLE';
+                    }
+                },
+                onManagedTurn: (sessionId, text, metrics, skills) => {
+                    const key = `orchestration:${sessionId}`;
+                    this.skillLearning?.onTurnStart(key, sessionId, text, skills, metrics.startedAt);
+                    for (const id of metrics.toolIds)
+                        this.skillLearning?.onToolUse(key, id);
+                    this.skillLearning?.onTokenUsage(key, metrics.inputTokens, metrics.totalTokens);
+                    this.skillLearning?.onTurnEnd(key, sessionId);
+                },
+                createAgentSession: async (sessionId, profile, model, scope) => {
+                    const key = scope && scope.source !== 'api' ? scope.chatId : sessionId;
+                    const old = this.sessions.get(key);
+                    if (old) {
+                        if (!old.isIdle(0))
+                            throw Object.assign(new Error('Agent session is busy'), { code: 'CONFLICT' });
+                        await old.stop();
+                        this.sessions.delete(key);
+                    }
+                    if (this.sessions.size >= this.maxConcurrent)
+                        throw new Error('Session pool full');
+                    if (this.agentConfig.type !== 'app-agent')
+                        (0, knowledge_1.spawnArchiveReindex)(this.agentConfig.workspace, this.agentConfig.knowledge, this.gatewayConfig.gateway.knowledge);
+                    const agentSession = new process_1.SessionProcess(sessionId, scope?.source ?? 'api', this.agentConfig, this.gatewayConfig, this.sessionStore, scope?.chatId, profile);
+                    agentSession.historyLimit = (0, process_1.resolveMaxHistoryMessages)(this.agentConfig.history?.maxHistoryMessages, this.gatewayConfig.gateway.history?.maxHistoryMessages);
+                    if (model)
+                        agentSession.modelOverride = model;
+                    this.sessions.set(key, agentSession);
+                    return agentSession;
+                },
+                releaseAgentSession: async (sessionId, agentSession) => {
+                    await agentSession.stop();
+                    for (const [key, value] of this.sessions)
+                        if (value === agentSession)
+                            this.sessions.delete(key);
+                },
+            })).then(orchestration => { this.orchestration = orchestration; return orchestration; }).catch(error => { this.orchestrationStarting = undefined; throw error; });
+        }
+        return this.orchestrationStarting;
+    }
+    async orchestrationActivity(sessionId, principalId, after) {
+        return (await this.getOrchestration()).activity(sessionId, principalId, after);
+    }
+    async subscribeResponseText(sessionId, principalId, receive) {
+        return (await this.getOrchestration()).subscribeText(sessionId, principalId, receive);
+    }
+    async voiceReplay(sessionId, principalId, responseId) {
+        return (await this.getOrchestration()).voiceAudio(sessionId, principalId, responseId);
+    }
+    saveVoiceReplay(sessionId, principalId, responseId, audio) {
+        this.orchestration?.saveVoiceAudio(sessionId, principalId, responseId, audio);
+    }
+    async authorizeVoiceSession(sessionId, principalId) {
+        (await this.getOrchestration()).authorizeSession(sessionId, principalId);
+    }
+    async subscribeVoiceResults(sessionId, principalId, receive, gender) {
+        return (await this.getOrchestration()).subscribeVoiceResults(sessionId, principalId, receive, gender);
+    }
+    recordVoicePlayback(responseId, principalId, progress, state) {
+        this.orchestration?.recordPlayback(responseId, principalId, progress, state);
+    }
+    async submitVoiceUtterance(sessionId, chatId, principalId, text, utteranceId, allowTools, model) {
+        if (!this.agentConfig.orchestration?.enabled || !this.agentConfig.voice?.enabled)
+            throw new Error('Voice is disabled');
+        if (!(await this.apiSessionExists(chatId, sessionId)))
+            throw new Error('Session not found');
+        const orchestration = await this.getOrchestration();
+        const accepted = orchestration.submitInput({ scope: { agentId: this.agentConfig.id, agentSessionId: sessionId, source: 'api', accountId: principalId,
+                chatId, threadKey: '', principalId }, text, model, modality: 'live_voice', ingressKey: `utterance:${utteranceId}` }, { execute: allowTools, writeMemory: false });
+        // The browser refreshes history on utterance.accepted, before inference finishes.
+        await orchestration.flushHistory();
+        return { ...accepted, responseId: () => orchestration.responseIdForInput(accepted.inputId) };
+    }
+    async listApiTasks(sessionId, principalId, page = 0, pageSize = 10, includeFinished = false) {
+        if (!this.agentConfig.orchestration?.enabled)
+            throw new Error('ORCHESTRATION_DISABLED');
+        const runtime = await this.getOrchestration();
+        runtime.authorizeSession(sessionId, principalId);
+        return runtime.taskControls.list(sessionId, principalId, page, pageSize, includeFinished);
+    }
+    async showApiTask(sessionId, principalId, taskId) {
+        if (!this.agentConfig.orchestration?.enabled)
+            throw new Error('ORCHESTRATION_DISABLED');
+        const runtime = await this.getOrchestration();
+        const detail = runtime.taskControls.detail(sessionId, principalId, taskId);
+        const task = runtime.store.task(taskId);
+        // Full retained result, with worker-only skill context removed by status().
+        return { ...runtime.tasks.status(task.conversationId, principalId, taskId)[0], ...detail };
+    }
+    async cancelApiTask(sessionId, principalId, taskId) {
+        if (!this.agentConfig.orchestration?.enabled)
+            throw new Error('ORCHESTRATION_DISABLED');
+        const runtime = await this.getOrchestration();
+        const task = runtime.taskControls.cancel(sessionId, principalId, taskId);
+        return task;
+    }
+    stopVoiceResponse(sessionId) { this.orchestration?.stopResponse(sessionId); }
+    async sendOrchestratedApi(sessionId, chatId, message, opts, onText, onTool) {
+        const semantic = this.agentConfig.orchestration?.conversation?.semanticIntake === true;
+        if (!semantic && this.pendingApiSessions.has(sessionId))
+            throw Object.assign(new Error('Session already has a pending request'), { code: 'CONFLICT' });
+        if (!opts.principalId)
+            throw new Error('Authenticated principal required for conversation orchestration');
+        const deadline = Date.now() + opts.timeoutMs;
+        if (!semantic)
+            this.pendingApiSessions.add(sessionId); // reserve before the first await
+        try {
+            const orchestration = await this.getOrchestration();
+            await this.sessionStore.ensureApiSession(this.agentConfig.id, chatId, sessionId);
+            this.apiChatIds.set(sessionId, chatId);
+            const media = opts.mediaFiles?.length ? await promoteUiUploads(this.agentsBaseDir, this.agentConfig.id, sessionId, opts.mediaFiles, this.logger) : [];
+            const index = await this.sessionStore.loadIndex(this.agentConfig.id, chatId, 'api');
+            const saved = index?.sessions.find(session => session.id === sessionId)?.imageConfig;
+            const selected = { ...(saved ? AgentRunner.durableImageConfig(saved) : {}), ...opts.imageParams };
+            const imageParams = AgentRunner.remapImageParamsRefs(Object.keys(selected).length ? selected : undefined, opts.mediaFiles, media);
+            const videoParams = AgentRunner.remapVideoParamsRefs(opts.videoParams, opts.mediaFiles, media);
+            if (videoParams)
+                await this.sessionStore.updateSessionMeta(this.agentConfig.id, chatId, sessionId, { videoConfig: videoParams }, 'api');
+            const imageConfig = opts.imageParams && imageParams ? AgentRunner.durableImageConfig(imageParams) : undefined;
+            if (imageConfig)
+                await this.sessionStore.updateSessionMeta(this.agentConfig.id, chatId, sessionId, { imageConfig }, 'api');
+            const requestId = opts.requestId ?? (0, crypto_1.randomUUID)();
+            const scopedInput = { scope: { agentId: this.agentConfig.id, agentSessionId: sessionId, source: 'api', accountId: opts.principalId,
+                    chatId, threadKey: '', principalId: opts.principalId }, text: message || '[Attachment inspection requested]', attachmentIds: media,
+                requestId, storeUserMessage: !opts.skipUserMessage,
+                metadata: imageParams || videoParams ? { promptContext: (imageParams ? AgentRunner.buildImageParamsNote(imageParams) : '') + (videoParams ? AgentRunner.buildVideoParamsNote(videoParams) : ''), imageRefs: imageParams?.image_refs } : undefined };
+            let text;
+            if (semantic) {
+                const accepted = orchestration.submitInput({ ...scopedInput, model: opts.model }, { execute: opts.allowTools ?? false, writeMemory: false }, onTool);
+                const lengths = new Map();
+                const unsubscribe = orchestration.subscribeText(sessionId, opts.principalId, event => {
+                    if (!orchestration.responseBelongsToInput(accepted.inputId, event.responseId) || !event.text)
+                        return;
+                    const before = lengths.get(event.responseId) ?? 0;
+                    if (event.text.length > before)
+                        onText?.(event.text.slice(before));
+                    lengths.set(event.responseId, event.text.length);
+                });
+                try {
+                    text = await accepted.response;
+                }
+                finally {
+                    unsubscribe();
+                }
+            }
+            else
+                text = await orchestration.send(scopedInput, { execute: opts.allowTools ?? false, writeMemory: false }, { timeoutMs: opts.timeoutMs, model: opts.model, onText, onTool });
+            if (opts.waitForTasks)
+                text = await orchestration.waitForTaskReport(sessionId, opts.principalId, requestId, text, deadline);
+            this.addApiAttachments(sessionId, orchestration.responseFiles(sessionId, requestId).map(ref => media_store_1.MediaStore.resolvePath(this.agentsBaseDir, this.agentConfig.id, ref)));
+            return { text, attachments: this.popApiAttachments(sessionId) };
+        }
+        finally {
+            if (!semantic)
+                this.pendingApiSessions.delete(sessionId);
+        }
+    }
     constructor(agentConfig, gatewayConfig, logger) {
         super();
         this.stopping = false;
@@ -241,6 +477,7 @@ class AgentRunner extends events_1.EventEmitter {
         this.slackThreadTs = new Map();
         this.receiver = null;
         this.discordReceiver = null;
+        this.discordCommandConfig = '';
         // LINE slow-LLM postback button manager (null when LINE disabled or threshold=0).
         this.lineReply = null;
         // Slack has no reply-token TTL to work around (see the plan's "no reply-manager
@@ -271,6 +508,12 @@ class AgentRunner extends events_1.EventEmitter {
         // 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();
+        // WeChat: unlike every credential-input channel above, constructed
+        // unconditionally (there's no config field to gate on — the link flow is
+        // QR device-pairing, not a typed-in token, same reasoning WhatsApp/Baileys
+        // uses). Does nothing until startWeChatLinking() is called or a
+        // previously-linked session is resumed at start().
+        this.wechat = null;
         this.idleCleanerTimer = null;
         // Tracks session IDs with an in-flight API request (prevents concurrent turns)
         this.pendingApiSessions = new Set();
@@ -346,6 +589,7 @@ class AgentRunner extends events_1.EventEmitter {
         this.apiChatIds = new Map();
         // Skill registry for detecting /skill-name commands in user messages
         this.skillRegistry = { skills: new Map() };
+        this.skillNotificationOrigins = new Map();
         // Cancel function for the daily history cleanup timer
         this.cancelCleanup = null;
         /**
@@ -388,7 +632,8 @@ class AgentRunner extends events_1.EventEmitter {
                 }
             });
         };
-        this.agentConfig = agentConfig;
+        this.telegramCommandConfig = '';
+        this.agentConfig = (0, gateway_config_1.applyGatewayOrchestration)(agentConfig, gatewayConfig);
         this.gatewayConfig = gatewayConfig;
         this.logger = logger ?? (0, logger_1.createLogger)(agentConfig.id, gatewayConfig.gateway.logDir);
         // Resolve agentsBaseDir: workspace is at <agentsBaseDir>/<agentId>/workspace
@@ -417,6 +662,25 @@ class AgentRunner extends events_1.EventEmitter {
         return this.skillRegistry;
     }
     /** Wire the skill-learning manager (planning-62). Optional; unset = feature off. */
+    async notifySkillLearning(sessionId, text) {
+        if (this.orchestration?.ownsSession(sessionId)) {
+            const conversation = this.orchestration.store.get('SELECT source,chat_id FROM conversations WHERE agent_session_id=?', sessionId);
+            const source = conversation?.source;
+            const index = source && source !== 'api' ? await this.sessionStore.loadIndex(this.agentConfig.id, String(conversation.chat_id), source) : undefined;
+            await this.orchestration.notifySession(sessionId, text, source === 'api' || index?.activeSessionId === sessionId);
+            return;
+        }
+        const origin = this.skillNotificationOrigins.get(sessionId);
+        if (!origin)
+            return; // Diary only when the original destination is unavailable.
+        this.historyDb.insertMessage({ chatId: `${origin.source}-${origin.chatId}`, sessionId, source: origin.source, role: 'assistant', content: text, ts: Date.now() });
+        const index = await this.sessionStore.loadIndex(this.agentConfig.id, origin.chatId, origin.source);
+        if (index?.activeSessionId !== sessionId)
+            return;
+        const result = await (0, delivery_1.channelSender)(() => this.agentConfig)({ channel: origin.source, chat_id: origin.chatId, thread_key: origin.thread }, text, (0, crypto_1.randomUUID)());
+        if (result.state !== 'delivered')
+            this.logger.warn('Skill notification delivery failed', { sessionId, code: result.code });
+    }
     setSkillLearning(manager) {
         this.skillLearning = manager;
     }
@@ -442,7 +706,7 @@ class AgentRunner extends events_1.EventEmitter {
             req.on('data', (chunk) => {
                 raw += chunk;
             });
-            req.on('end', () => {
+            req.on('end', async () => {
                 if (url.pathname === '/command') {
                     this.handleCommandRequest(raw, res);
                     return;
@@ -460,26 +724,79 @@ class AgentRunner extends events_1.EventEmitter {
                 // receiver (Bun) can try to reuse the stale socket → "socket connection
                 // was closed unexpectedly". Closing per-request avoids the race entirely.
                 res.setHeader('Connection', 'close');
-                res.writeHead(200);
-                res.end('ok');
                 try {
                     const params = JSON.parse(raw);
                     const meta = params.meta ?? {};
                     const chatId = meta['chat_id'] ?? '';
                     const content = params.content ?? '';
-                    // Set channel early so all handlers (including session commands) have it
-                    const channelSource = (meta['source'] === 'discord'
-                        ? 'discord'
-                        : meta['source'] === 'line'
-                            ? 'line'
-                            : meta['source'] === 'slack'
-                                ? 'slack'
-                                : meta['source'] === 'whatsapp'
-                                    ? 'whatsapp'
-                                    : meta['source'] === 'whatsapp_cloud'
-                                        ? 'whatsapp_cloud'
-                                        : 'telegram');
+                    // Set channel early so all handlers (including session commands) have it.
+                    // Derived from the canonical CHAT_CHANNELS list (see history/types.ts's
+                    // doc comment) — a hand-copied ternary here is exactly what silently
+                    // turned every WeChat (and, historically, Slack) message into
+                    // 'telegram' before, since a new channel added elsewhere is easy to
+                    // forget adding to a chain of `=== 'x' ? 'x' : ...` checks.
+                    const channelSource = ((0, types_1.isChatChannel)(meta['source']) ? meta['source'] : 'telegram');
                     this.channelSourceMap.set(chatId, channelSource);
+                    const channelOrchestration = this.orchestration?.ownsChannel(channelSource, chatId) || (this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes(channelSource));
+                    if (channelSource !== 'telegram' && this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes(channelSource) && /^\/sessions?(?:\s|$)/.test(content.trim())) {
+                        const index = await this.sessionStore.listSessions(this.agentConfig.id, chatId, channelSource);
+                        const current = index.sessions.find(session => session.id === index.activeSessionId);
+                        const text = content.trim() === '/sessions'
+                            ? `Sessions\n${index.sessions.slice(0, 15).map(session => `${session.id === index.activeSessionId ? '✅ ' : ''}${session.name}\n${session.id}`).join('\n\n')}`
+                            : `Current session: ${current?.name ?? '(unnamed)'}\n${index.activeSessionId}\nMode: Orchestration\nModel: ${this.agentConfig.claude.model}\nMessages: ${current?.messageCount ?? 0}\n\nCommands: /session /sessions /voice /voices /tasks /stop`;
+                        await this.sendOrchestrationControl(channelSource, chatId, { text, buttons: [] }, meta);
+                        res.writeHead(200);
+                        res.end('ok');
+                        return;
+                    }
+                    if (channelSource !== 'telegram' && (/^\/(voice|voices|tasks|stop|orch)(?:\s|$)/.test(content.trim()) || (this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes(channelSource) && content.trim() === '/help'))) {
+                        const enabled = !!(this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes(channelSource));
+                        if (enabled) {
+                            const sessionId = await this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, channelSource);
+                            const runtime = await this.getOrchestration();
+                            const scope = { channel: channelSource, chatId, thread: meta.thread_ts ?? meta.message_thread_id ?? '', sessionId, principalId: `${channelSource}:${meta.user_id ?? meta.user ?? chatId}` };
+                            let menu;
+                            try {
+                                menu = await runtime.channelControls.handle(scope, content.trim());
+                            }
+                            catch {
+                                menu = { text: 'Control unavailable or expired. Please open the command again.', buttons: [] };
+                            }
+                            await this.sendOrchestrationControl(channelSource, chatId, menu, meta);
+                            res.writeHead(200);
+                            res.end('ok');
+                            return;
+                        }
+                        // Keep the legacy /stop path, but never turn disabled controls into model prompts.
+                        if (!/^\/stop(?:\s|$)/.test(content.trim())) {
+                            await this.sendOrchestrationControl(channelSource, chatId, { text: 'These controls require orchestration mode.', buttons: [] }, meta);
+                            res.writeHead(200);
+                            res.end('ok');
+                            return;
+                        }
+                    }
+                    if (channelOrchestration && !(0, builtin_commands_1.isBuiltinCommand)(content.trim(), channelSource)) {
+                        const sessionId = await this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, channelSource);
+                        const orchestration = await this.getOrchestration();
+                        const { media, quoted, details } = await (0, channel_input_media_1.channelInputMedia)(this.agentConfig, this.agentsBaseDir, channelSource, chatId, meta, AgentRunner.discardEphemeralStaging);
+                        const senderId = meta.user_id ?? meta.user ?? chatId;
+                        const accepted = orchestration.submitInput({ scope: { agentId: this.agentConfig.id, agentSessionId: sessionId, source: channelSource,
+                                accountId: this.agentConfig.id, chatId, threadKey: channelSource === 'whatsapp' && meta.account_id ? `whatsapp-account:${meta.account_id}` : meta.thread_ts ?? meta.message_thread_id ?? '', principalId: `${channelSource}:${senderId}` },
+                            text: content || '[Attachment inspection requested]', attachmentIds: media, trustedChannelMember: true,
+                            modality: ['voice', 'audio'].includes(meta.media_type ?? meta.attachment_kind) ? 'voice_note' : 'text',
+                            ingressKey: meta.message_id, metadata: { senderId, senderName: meta.sender_name, platformMessageId: meta.message_id, platformMessageIds: meta.message_ids_json ? JSON.parse(meta.message_ids_json) : undefined, mediaGroupId: meta.media_group_id,
+                                attachmentName: meta.attachment_name, mediaType: meta.media_type ?? meta.attachment_kind, repliedText: meta.replied_text, repliedMessageId: meta.replied_message_id, repliedSender: meta.replied_user, repliedAttachmentIds: quoted, attachmentDetails: details, attachmentError: meta.attachment_error } }, { execute: this.agentConfig.allow_tools !== false, writeMemory: this.agentConfig.allow_tools !== false });
+                        // The durable receipt precedes receiver acknowledgment and inference.
+                        res.writeHead(200);
+                        res.end('ok');
+                        void accepted.response.catch(error => {
+                            // The durable decision/outbox owns failure delivery and activity, including autonomous turns.
+                            this.logger.error('Conversation channel turn failed', { chatId, code: error.code ?? 'ORCHESTRATION_ERROR', ...(error.timeout ? { timeout: error.timeout } : {}) });
+                        });
+                        return;
+                    }
+                    res.writeHead(200);
+                    res.end('ok');
                     // Slack: remember the current message's thread context so the
                     // auto-forward fallback (writeAutoForward) can stay in-thread. A
                     // top-level message clears it so a later fallback isn't misrouted
@@ -548,6 +865,10 @@ class AgentRunner extends events_1.EventEmitter {
                     return;
                 }
                 catch (err) {
+                    if (!res.headersSent) {
+                        res.writeHead(503);
+                        res.end('Channel input was not accepted');
+                    }
                     this.logger.warn('Failed to parse channel callback body', {
                         error: err.message,
                     });
@@ -591,6 +912,10 @@ class AgentRunner extends events_1.EventEmitter {
             return;
         }
         const session = this.sessions.get(chatId);
+        if (session?.runtimeProfile || this.requiresDurableChannelIngress('telegram')) {
+            respond({ ok: false, error: 'Recovery is owned by orchestration; legacy turn replay is disabled.' });
+            return;
+        }
         const autoRecover = this.gatewayConfig.gateway.selfHealing?.autoRecover === true;
         const req = {
             incidentId: body.incidentId ?? '',
@@ -758,6 +1083,119 @@ class AgentRunner extends events_1.EventEmitter {
             return;
         }
         const command = body.command;
+        if (command === 'telegram_voices') {
+            const chatId = body.chat_id ?? '', payload = body.payload ?? {};
+            if (!/^\d+$/.test(chatId) || payload.user_id !== chatId) {
+                respond({ success: false }, 400);
+                return;
+            }
+            if (!this.agentConfig.orchestration?.enabled || !this.agentConfig.orchestration.channels?.includes('telegram')) {
+                respond({ success: false, error: 'Voice controls unavailable.' });
+                return;
+            }
+            try {
+                const voices = (await this.getOrchestration()).telegramVoices;
+                if (payload.action === 'dismiss' && typeof payload.menu_id === 'string') {
+                    voices.dismiss(chatId, payload.menu_id);
+                    respond({ success: true });
+                }
+                else if (payload.action === 'choose' && typeof payload.menu_id === 'string' && typeof payload.index === 'number')
+                    respond({ success: true, ...await voices.choose(chatId, payload.menu_id, payload.index) });
+                else
+                    respond({ success: true, ...await voices.menu(chatId, typeof payload.page === 'number' ? payload.page : 0, typeof payload.menu_id === 'string' ? payload.menu_id : undefined, typeof payload.gender === 'string' ? payload.gender : undefined) });
+            }
+            catch {
+                respond({ success: false, error: 'Voice list unavailable or provider changed. Use /voices to refresh.' });
+            }
+            return;
+        }
+        if (command === 'telegram_tasks') {
+            const chatId = body.chat_id ?? '', payload = body.payload ?? {}, principalId = `telegram:${payload.user_id ?? ''}`;
+            if (!/^\d+$/.test(chatId) || payload.user_id !== chatId) {
+                respond({ success: false }, 400);
+                return;
+            }
+            if (!this.agentConfig.orchestration?.enabled || !this.agentConfig.orchestration.channels?.includes('telegram')) {
+                respond({ success: false, error: 'Task controls require orchestration mode.' });
+                return;
+            }
+            try {
+                const runtime = await this.getOrchestration();
+                const sessionId = await this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, 'telegram');
+                if (payload.session_id !== undefined && payload.session_id !== sessionId) {
+                    respond({ success: false, error: 'TASK_SESSION_CHANGED' });
+                    return;
+                }
+                if (payload.action === 'detail' || payload.action === 'cancel') {
+                    if (typeof payload.task_id !== 'string')
+                        throw Error('INVALID_TASK');
+                    const task = payload.action === 'cancel' ? runtime.taskControls.cancel(sessionId, principalId, payload.task_id) : runtime.taskControls.detail(sessionId, principalId, payload.task_id);
+                    respond({ success: true, sessionId, task });
+                }
+                else
+                    respond({ success: true, sessionId, ...runtime.taskControls.list(sessionId, principalId, typeof payload.page === 'number' ? payload.page : 0) });
+            }
+            catch {
+                respond({ success: false, error: 'Task unavailable. Use /tasks to refresh.' });
+            }
+            return;
+        }
+        if (command === 'task_stop') {
+            const chatId = body.chat_id ?? '', principalId = `telegram:${body.payload?.user_id ?? ''}`;
+            if (!/^\d+$/.test(chatId) || body.payload?.user_id !== chatId) {
+                respond({ success: false, error: 'invalid_request' }, 400);
+                return;
+            }
+            try {
+                if (!(this.agentConfig.orchestration?.enabled && this.agentConfig.orchestration.channels?.includes('telegram'))) {
+                    if (body.payload?.menu_id) {
+                        respond({ success: false, error: 'Orchestration is disabled.' });
+                        return;
+                    }
+                    await this.handleCommandStop(chatId);
+                    respond({ success: true, legacy: true });
+                    return;
+                }
+                const runtime = await this.getOrchestration();
+                const sessionId = await this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, 'telegram');
+                if (typeof body.payload?.menu_id === 'string' && typeof body.payload?.index === 'number') {
+                    respond({ success: true, ...runtime.stopControls.choose(sessionId, principalId, body.payload.menu_id, body.payload.index) });
+                }
+                else {
+                    const menu = runtime.stopControls.open(sessionId, principalId);
+                    respond({ success: true, ...menu, text: (0, stop_controls_1.stopMenuText)(menu, true) });
+                }
+            }
+            catch {
+                respond({ success: false, error: 'Selection unavailable. Use /stop to refresh the task list.' });
+            }
+            return;
+        }
+        if (command === 'telegram_voice') {
+            const chatId = body.chat_id ?? '';
+            const value = body.payload?.enabled;
+            const mode = body.payload?.mode;
+            if (!/^\d+$/.test(chatId) || (value !== undefined && typeof value !== 'boolean') || (mode !== undefined && !voice_reply_policy_1.VOICE_REPLY_MODES.includes(mode))) {
+                respond({ success: false, error: 'invalid_request' }, 400);
+                return;
+            }
+            if (!this.agentConfig.orchestration?.enabled || !this.agentConfig.orchestration.channels?.includes('telegram') || !this.agentConfig.voice?.enabled || this.agentConfig.voice?.notes?.replyWithVoice === false) {
+                respond({ success: false, error: 'voice_not_configured' });
+                return;
+            }
+            try {
+                const runtime = await this.getOrchestration();
+                if (mode !== undefined)
+                    runtime.store.setTelegramVoiceMode(chatId, mode);
+                else if (typeof value === 'boolean')
+                    runtime.store.setTelegramVoice(chatId, value);
+                respond({ success: true, enabled: runtime.store.telegramVoice(chatId), mode: runtime.store.telegramVoiceMode(chatId) });
+            }
+            catch {
+                respond({ success: false, error: 'voice_settings_unavailable' }, 500);
+            }
+            return;
+        }
         if (command === 'get_model') {
             respond({ model: this.agentConfig.claude.model });
             return;
@@ -790,6 +1228,10 @@ class AgentRunner extends events_1.EventEmitter {
         // its initData. The browser-facing routes live on the gateway; here we only
         // mint the pairing and hand back the phone-openable link.
         if (command === 'cli_pair') {
+            if (this.gatewayConfig.gateway.headless !== false || this.agentConfig.type === 'app-agent' || this.agentConfig.orchestration?.enabled) {
+                respond({ success: false, error: 'interactive_mode_required' });
+                return;
+            }
             const payload = body.payload ?? {};
             const channel = payload['channel'];
             const userId = typeof payload['user_id'] === 'string' ? payload['user_id'] : '';
@@ -1074,7 +1516,21 @@ 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)' : meta['document_path'] ? '(document)' : meta['sticker_path'] ? '(sticker)' : '');
+                // `image_path` is used for ANY attachment, not just photos (see
+                // handleWeChatInboundMessage's doc comment) — a non-image
+                // extension (e.g. WeChat's PDF/file support) must not show as
+                // "(photo)" in the transcript.
+                const isImagePath = /\.(jpe?g|png|gif|webp|heic|bmp)$/i.test(meta['image_path'] ?? '');
+                const attachmentPlaceholder = meta['attachment_file_id']
+                    ? '(photo)'
+                    : meta['image_path']
+                        ? (isImagePath ? '(photo)' : '(file)')
+                        : meta['document_path']
+                            ? '(document)'
+                            : meta['sticker_path']
+                                ? '(sticker)'
+                                : '';
+                const userContent = content || attachmentPlaceholder;
                 const userTs = Date.now();
                 await this.sessionStore.appendTelegramMessage(this.agentConfig.id, chatId, sessionId, {
                     role: 'user',
@@ -1220,6 +1676,8 @@ class AgentRunner extends events_1.EventEmitter {
             session.setProcessing(true);
             const turnText = blocks.join('\n');
             // Skill-learning: mark the start of a user turn (cheap, best-effort).
+            const originMeta = entries[0]?.meta ?? {};
+            this.skillNotificationOrigins.set(sessionId, { source: channelSource, chatId, thread: originMeta.thread_ts ?? originMeta.message_thread_id ?? '' });
             this.skillLearning?.onTurnStart(chatId, sessionId, entries[0]?.content ?? '', invokedSkills);
             session.sendMessage(turnText);
             // Remember this turn for the C1 guarded resend (Phase 3b): reset the
@@ -1717,6 +2175,9 @@ class AgentRunner extends events_1.EventEmitter {
             let lastAssistantTextThisTurn = '';
             let typingDoneTimer = null;
             const TYPING_DONE_DELAY_MS = 3000;
+            // Same hand-copied-ternary gap CHAT_CHANNELS' doc comment warns about —
+            // 'wechat' was missing here too (confirmed live 2026-09-11), so this
+            // turn-completion tracking never recognized a wechat_reply tool call.
             const replyToolName = source === 'discord'
                 ? 'mcp__gateway__discord_reply'
                 : source === 'line'
@@ -1727,7 +2188,9 @@ class AgentRunner extends events_1.EventEmitter {
                             ? 'mcp__gateway__whatsapp_reply'
                             : source === 'whatsapp_cloud'
                                 ? 'mcp__gateway__whatsapp_cloud_reply'
-                                : 'mcp__gateway__telegram_reply';
+                                : source === 'wechat'
+                                    ? 'mcp__gateway__wechat_reply'
+                                    : 'mcp__gateway__telegram_reply';
             proc.on('output', (line) => {
                 try {
                     const obj = JSON.parse(line);
@@ -2090,7 +2553,7 @@ class AgentRunner extends events_1.EventEmitter {
                     // event. Start the typing-done timer here so the indicator stays alive
                     // through multi-turn tool-call sequences and only stops when all work is done.
                     if (obj['type'] === 'session_idle' && proc.backend === 'pty-shell') {
-                        // A parent can become idle immediately after dispatching background
+                        // An agent can become idle immediately after dispatching background
                         // Agent/Workflow work. Keep the Telegram typing signal and processing
                         // sentinel alive until the task notification starts its follow-up turn.
                         const waitingForBackgroundWork = proc.retainBackgroundWorkingState();
@@ -2146,7 +2609,7 @@ class AgentRunner extends events_1.EventEmitter {
                 }, this.channelFor(mapKey)).catch(() => { });
             }
             proc.on('backgroundWorkExpired', () => {
-                // The child task never notified its parent within the bounded grace
+                // The child task never notified its agent within the bounded grace
                 // window; release the Telegram typing signal instead of leaving it live.
                 this.writeTypingDone(mapKey);
             });
@@ -2211,6 +2674,9 @@ class AgentRunner extends events_1.EventEmitter {
         });
         return proc;
     }
+    apiTaskStopReply(sessionId, principalId, text) {
+        return this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes('api') ? this.orchestration?.stopControls.replyCommand(sessionId, principalId, text) : undefined;
+    }
     static isApiBuiltinCommand(content) {
         return (0, builtin_commands_1.isBuiltinCommand)(content, 'api');
     }
@@ -2410,6 +2876,13 @@ class AgentRunner extends events_1.EventEmitter {
      * "No turn in progress." that fired whenever interrupt() no-op'd mid-spawn.
      */
     async handleCommandStop(chatId) {
+        if (this.orchestration && this.agentConfig.orchestration?.enabled) {
+            const sessionId = await this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, this.channelFor(chatId));
+            if (this.orchestration.stopResponse(sessionId)) {
+                this.writeAutoForward(chatId, 'Response stopped. Tasks remain active.');
+                return;
+            }
+        }
         // Cancel queued + buffered work first so nothing flushes in behind the interrupt.
         const buffered = this.channelCoalesce.get(chatId);
         if (buffered?.timer)
@@ -2791,7 +3264,9 @@ class AgentRunner extends events_1.EventEmitter {
         const { immediate, deferred } = await this.restartOrDefer({
             skipBusy: false,
             deferIdle: true,
-            filter: (proc) => proc.connectorConfigChanged(connectorId, target),
+            // Managed turns use a fresh subprocess/config on their next decision or task.
+            // Never send them through legacy restart/replay while effects may be in flight.
+            filter: (proc) => !proc.runtimeProfile && proc.connectorConfigChanged(connectorId, target),
         });
         return { restarted: immediate + deferred > 0 };
     }
@@ -2935,6 +3410,21 @@ class AgentRunner extends events_1.EventEmitter {
             }
             return;
         }
+        // WeChat has no .forward consumer either — same gap that used to silently
+        // drop every command reply / no-tool-call fallback for Slack (confirmed
+        // live 2026-09-11: the agent's plain-text reply showed up in the web
+        // session view but never reached the user's phone, because it landed in
+        // a chatId.forward file nothing reads for this channel). Deliver via the
+        // manager directly, mirroring Slack's branch above.
+        if (this.channelFor(chatId) === 'wechat') {
+            void this.wechat?.sendMessage(chatId, text).catch((err) => {
+                this.logger.warn('WeChat 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 {
@@ -3003,7 +3493,7 @@ class AgentRunner extends events_1.EventEmitter {
     startIdleCleaner() {
         this.idleCleanerTimer = setInterval(async () => {
             for (const [id, proc] of this.sessions) {
-                // A parent that just dispatched Agent/Workflow/Monitor work is CLI-idle
+                // An agent that just dispatched Agent/Workflow/Monitor work is CLI-idle
                 // but that dispatch may still need this session to receive its
                 // eventual task notification.
                 if (proc.hasLikelyOutstandingBackgroundWork())
@@ -3018,16 +3508,20 @@ class AgentRunner extends events_1.EventEmitter {
         }, 5 * 60 * 1000);
     }
     async start() {
+        if (this.agentConfig.orchestration?.enabled || fs.existsSync(path.join(this.agentDir, 'orchestration.db')))
+            await this.getOrchestration();
         this.stopping = false;
         await this.sweepStaleSessionDirs();
         await this.startCallbackServer();
         if (this.agentConfig.telegram?.botToken) {
-            this.receiver = new receiver_1.TelegramReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir);
+            this.receiver = new receiver_1.TelegramReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir, this.gatewayConfig.gateway.headless !== false);
             this.receiver.start();
+            this.telegramCommandConfig = this.telegramCommandsKey();
         }
         if (this.agentConfig.discord?.botToken) {
-            this.discordReceiver = new receiver_2.DiscordReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir);
+            this.discordReceiver = new receiver_2.DiscordReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir, this.gatewayConfig.gateway.headless !== false);
             this.discordReceiver.start();
+            this.discordCommandConfig = this.telegramCommandsKey();
         }
         // LINE slow-LLM postback button: gateway-side token lifecycle + cache.
         // Enabled for any LINE agent unless its threshold is 0 (then the MCP
@@ -3043,6 +3537,8 @@ class AgentRunner extends events_1.EventEmitter {
         // no-ops here and stays 'unlinked' until the user starts a QR/pairing
         // flow via the API.
         this.syncWhatsAppAccounts();
+        this.ensureWeChatManager();
+        await this.wechat?.resumeIfLinked();
         this.startIdleCleaner();
         this._startCleanupScheduler();
         this.logger.info('AgentRunner started', { agentId: this.agentConfig.id });
@@ -3086,8 +3582,34 @@ class AgentRunner extends events_1.EventEmitter {
             }
         }
     }
+    telegramCommandsKey() {
+        return JSON.stringify([this.gatewayConfig.gateway.headless !== false, this.agentConfig.type,
+            Boolean(this.agentConfig.orchestration?.enabled), this.agentConfig.orchestration?.channels ?? ['api']]);
+    }
+    /** Reload only the receiver when command visibility changes; Agent/Worker work continues. */
+    refreshTelegramCommands() {
+        const discord = this.discordReceiver, discordKey = this.telegramCommandsKey();
+        if (discord && discordKey !== this.discordCommandConfig) {
+            this.discordCommandConfig = discordKey;
+            void discord.stop().then(() => { if (this.discordReceiver !== discord || this.stopping)
+                return; this.discordReceiver = null; this.startDiscordReceiver(); });
+        }
+        const previous = this.receiver, key = this.telegramCommandsKey();
+        if (!previous || key === this.telegramCommandConfig)
+            return;
+        this.telegramCommandConfig = key;
+        void previous.stop().then(() => {
+            if (this.receiver !== previous || this.stopping)
+                return;
+            this.receiver = null;
+            this.startTelegramReceiver();
+        });
+    }
     updateAgentConfig(newConfig) {
+        newConfig = (0, gateway_config_1.applyGatewayOrchestration)(newConfig, this.gatewayConfig);
+        this.orchestration?.updateAgentConfig(newConfig);
         this.agentConfig = newConfig;
+        this.refreshTelegramCommands();
         // Restart LineReplyManager if the LINE config changed so the live instance
         // picks up a new access token, threshold, or labels without a full restart.
         this.stopLineReply();
@@ -3104,6 +3626,10 @@ class AgentRunner extends events_1.EventEmitter {
         // (access-control fields) into every already-running manager, and
         // add/remove managers only if the set of configured accounts changed.
         this.syncWhatsAppAccounts();
+        // WeChat has no credential to react to (QR-linked, not config-driven) —
+        // just hand the manager the fresh config so its access-control reads
+        // (dmPolicy/dmAllowlist/pairing) see the latest values.
+        this.wechat?.updateAgentConfig(newConfig);
     }
     /**
      * Reconcile `this.whatsappAccounts` with `agentConfig.whatsapp.accounts`.
@@ -3220,6 +3746,152 @@ class AgentRunner extends events_1.EventEmitter {
     opts) {
         await this.whatsAppManagerFor(jid, accountId).sendMessage(jid, text, imagePath, opts);
     }
+    /** Lazily construct this agent's WeChatManager — safe to call repeatedly. */
+    ensureWeChatManager() {
+        if (!this.wechat) {
+            // WECHAT_ILINK_FAKE is local-testing-only (see ilink-client.ts's
+            // createFakeILinkClient doc comment) — never set in a real deployment.
+            // The real client needs no account/credential of its own (confirmed
+            // against Tencent's own protocol doc — see ilink-client.ts's module
+            // comment), this flag exists purely to skip a real QR scan while
+            // iterating on the UI.
+            const client = (0, ilink_client_1.isWeChatILinkFakeEnabled)()
+                ? (0, ilink_client_1.createFakeILinkClient)()
+                : (0, ilink_client_1.createILinkClient)(process.env.ILINK_BASE_URL ?? '', this.agentConfig.wechat?.botAgent);
+            this.wechat = new manager_2.WeChatManager(this.agentConfig, this.gatewayConfig.gateway.logDir, client, (update) => this.handleWeChatInboundMessage(update));
+        }
+        return this.wechat;
+    }
+    getWeChatStatus() {
+        return this.ensureWeChatManager().getStatus();
+    }
+    async startWeChatLinking() {
+        await this.ensureWeChatManager().startLinking();
+    }
+    async unlinkWeChat() {
+        await this.ensureWeChatManager().unlink();
+    }
+    async sendWeChatMessage(toId, text) {
+        await this.ensureWeChatManager().sendMessage(toId, text);
+    }
+    /**
+     * Gate + forward one inbound WeChat message. Mirrors the LINE webhook
+     * router's own gate-then-forward-to-/channel shape exactly (see
+     * src/api/line-webhook-router.ts's `recordDeniedSender` call and its
+     * "forward to the agent's existing /channel intake" comment) — WeChat has
+     * no webhook of its own, so this is the equivalent point for a message
+     * arriving off WeChatManager's long-poll loop instead of an Express route.
+     */
+    handleWeChatInboundMessage(update) {
+        const cfg = this.agentConfig.wechat;
+        const allowed = (0, wechat_access_1.isWeChatConversationAllowed)(cfg, { fromId: update.fromId });
+        if (!allowed) {
+            const pairingOn = cfg?.pairing !== false; // absent ⇒ on, mirrors line.pairing/slack.pairing
+            const existing = (0, pending_senders_1.getPendingSender)('wechat', this.agentConfig.id, update.fromId);
+            const code = pairingOn ? (existing?.code ?? (0, pending_senders_1.generatePairingCode)()) : undefined;
+            const isNew = (0, pending_senders_1.recordDeniedSender)('wechat', this.agentConfig.id, update.fromId, update.displayName, Date.now(), code);
+            if (isNew && pairingOn && code) {
+                this.wechat
+                    ?.sendMessage(update.fromId, `This account isn't approved to message this agent yet. Give the admin this code: ${code}`)
+                    .catch((err) => this.logger.warn('WeChat pairing-code reply failed', { error: err.message }));
+            }
+            return;
+        }
+        // Self-heal a stale pending-knock record for a sender who's now allowed.
+        // Approving a sender already clears their pending entry (router.ts's
+        // wechat_dm_allowlist PATCH handler), but confirmed live 2026-09-11: a
+        // sender can still show as both allowed AND pending in the UI, most
+        // likely a race between that approval and a message processed in the
+        // same window. Clearing it here too means any such staleness can't
+        // outlive this sender's very next allowed message.
+        (0, pending_senders_1.clearPendingSender)('wechat', this.agentConfig.id, update.fromId);
+        const meta = {
+            source: 'wechat',
+            chat_id: update.fromId,
+            user_id: update.fromId,
+            user: update.displayName || update.fromId,
+            message_id: update.id,
+            ts: new Date(update.timestamp ?? Date.now()).toISOString(),
+        };
+        void (async () => {
+            // Stage an inbound image or file to a temp path the same way LINE's
+            // webhook router does (src/api/line-webhook-router.ts's
+            // downloadLineImage/drainToFile pattern) — AgentRunner.injectTurn
+            // already knows how to take meta.image_path from here (the field name
+            // is historical; the mechanism itself is content-agnostic — it just
+            // copies whatever's at that path into MediaStore), rewrite the path
+            // for the agent's sandbox, and clean up the ephemeral original. No
+            // format sniffing for images: always staged as .jpg, matching
+            // Hermes-agent's own assumption for this same protocol. Files keep
+            // their real name/extension (sniffing isn't needed — it's given).
+            // update.id (Tencent's message_id) arrives as a JSON number at runtime
+            // despite ILinkUpdate declaring it a string (confirmed live
+            // 2026-09-11: `.replace is not a function` on a real image message) —
+            // String() it before sanitizing.
+            const safeId = String(update.id).replace(/[^a-zA-Z0-9_-]/g, '_');
+            if (update.image) {
+                try {
+                    const bytes = await (0, ilink_client_1.downloadWeixinImage)(update.image, { maxBytes: media_store_1.MediaStore.maxUploadBytes });
+                    const tempPath = path.join(os.tmpdir(), `wechat-img-${safeId}-${Date.now()}.jpg`);
+                    await fsPromises.writeFile(tempPath, bytes);
+                    meta.image_path = tempPath;
+                    meta.media_ephemeral = '1';
+                }
+                catch (err) {
+                    this.logger.warn('WeChat image download failed, forwarding text only', {
+                        error: err.message,
+                    });
+                }
+            }
+            else if (update.file) {
+                try {
+                    const bytes = await (0, ilink_client_1.downloadWeixinImage)(update.file, { maxBytes: media_store_1.MediaStore.maxUploadBytes });
+                    // Preserve the sender's real filename/extension (unlike images,
+                    // which are always staged as .jpg) — the agent's Read tool needs a
+                    // correct extension to make sense of a PDF/docx/etc.
+                    const safeName = update.file.fileName.replace(/[^a-zA-Z0-9_.-]/g, '_') || 'file';
+                    const tempPath = path.join(os.tmpdir(), `wechat-file-${safeId}-${Date.now()}-${safeName}`);
+                    await fsPromises.writeFile(tempPath, bytes);
+                    meta.image_path = tempPath;
+                    meta.media_ephemeral = '1';
+                }
+                catch (err) {
+                    this.logger.warn('WeChat file download failed, forwarding text only', {
+                        error: err.message,
+                    });
+                }
+            }
+            if (update.reply) {
+                if (update.reply.messageId)
+                    meta.replied_message_id = update.reply.messageId;
+                if (update.reply.text)
+                    meta.replied_text = update.reply.text;
+                const ref = update.reply.image ?? update.reply.file;
+                if (ref)
+                    try {
+                        const bytes = await (0, ilink_client_1.downloadWeixinImage)(ref, { maxBytes: media_store_1.MediaStore.maxUploadBytes });
+                        const name = update.reply.file?.fileName.replace(/[^a-zA-Z0-9_.-]/g, '_') ?? 'image.jpg';
+                        const dest = path.join(os.tmpdir(), `wechat-reply-${safeId}-${Date.now()}-${name}`);
+                        await fsPromises.writeFile(dest, bytes, { mode: 0o600 });
+                        meta.replied_image_path = dest;
+                        meta.media_ephemeral = '1';
+                    }
+                    catch {
+                        meta.attachment_error = 'The quoted attachment could not be downloaded. Do not claim to have read it.';
+                    }
+            }
+            try {
+                await fetch(`http://127.0.0.1:${this.callbackPort}/channel`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ content: update.text ?? '', meta }),
+                });
+            }
+            catch (err) {
+                this.logger.error('WeChat: failed to forward to callback', { error: err.message });
+            }
+        })();
+    }
     startSlackOutbound() {
         if (!this.agentConfig.slack?.botToken || !this.agentConfig.slack?.signingSecret)
             return;
@@ -3285,8 +3957,9 @@ class AgentRunner extends events_1.EventEmitter {
             return;
         if (!this.agentConfig.telegram?.botToken)
             return;
-        this.receiver = new receiver_1.TelegramReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir);
+        this.receiver = new receiver_1.TelegramReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir, this.gatewayConfig.gateway.headless !== false);
         this.receiver.start();
+        this.telegramCommandConfig = this.telegramCommandsKey();
         this.logger.info('TelegramReceiver hot-started', { agentId: this.agentConfig.id });
     }
     stopTelegramReceiver() {
@@ -3304,8 +3977,9 @@ class AgentRunner extends events_1.EventEmitter {
             return;
         if (!this.agentConfig.discord?.botToken)
             return;
-        this.discordReceiver = new receiver_2.DiscordReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir);
+        this.discordReceiver = new receiver_2.DiscordReceiver(this.agentConfig, this.callbackPort, this.gatewayConfig.gateway.logDir, this.gatewayConfig.gateway.headless !== false);
         this.discordReceiver.start();
+        this.discordCommandConfig = this.telegramCommandsKey();
         this.logger.info('DiscordReceiver hot-started', { agentId: this.agentConfig.id });
     }
     stopDiscordReceiver() {
@@ -3320,6 +3994,12 @@ class AgentRunner extends events_1.EventEmitter {
     }
     async stop() {
         this.stopping = true;
+        if (this.orchestrationStarting) {
+            const orchestration = await this.orchestrationStarting.catch(() => undefined);
+            await orchestration?.close();
+            this.orchestration = undefined;
+            this.orchestrationStarting = undefined;
+        }
         if (this.idleCleanerTimer !== null) {
             clearInterval(this.idleCleanerTimer);
             this.idleCleanerTimer = null;
@@ -3402,6 +4082,17 @@ class AgentRunner extends events_1.EventEmitter {
     isRunning() {
         return this.receiver?.isRunning() ?? false;
     }
+    getOrchestrationSummary() {
+        if (!this.agentConfig.orchestration?.enabled && !this.orchestration)
+            return undefined;
+        const summary = this.orchestration?.dashboardSummary() ?? { enabled: true, backend: 'headless', workspaceMode: this.agentConfig.type === 'app-agent' ? 'container' : this.agentConfig.orchestration?.tasks?.workspaceMode ?? 'host', activeAgentSessions: [], tasks: [], sessions: [] };
+        const processes = [...this.sessions.values()].filter(p => p.runtimeProfile?.role === 'agent' && p.isRunning());
+        return { ...summary, sessions: summary.sessions.map(s => {
+                const p = processes.find(p => p.sessionId === s.sessionId);
+                return { ...s, model: p?.model ?? s.model, tokens: p?.totalTokens ?? 0, spawnedAt: p?.spawnedAt ?? 0,
+                    uptimeSec: p ? Math.floor((Date.now() - p.spawnedAt) / 1000) : 0 };
+            }), agentProcesses: processes.map(p => ({ sessionId: p.sessionId, hostProcessId: p.processId, container: this.agentConfig.container })) };
+    }
     getSessionsSummary() {
         const now = Date.now();
         // A single logical session can appear multiple times in the ring buffer: a
@@ -3439,6 +4130,8 @@ class AgentRunner extends events_1.EventEmitter {
      * - Appends user message and assistant reply to SessionStore for history persistence.
      */
     async sendApiMessage(sessionId, chatId, message, opts) {
+        if (this.orchestrationForApi(sessionId))
+            return this.sendOrchestratedApi(sessionId, chatId, message, opts);
         if (this.pendingApiSessions.has(sessionId)) {
             const err = Object.assign(new Error(`Session ${sessionId} already has a pending request`), { code: 'CONFLICT' });
             throw err;
@@ -3721,6 +4414,18 @@ class AgentRunner extends events_1.EventEmitter {
      * expires (#421).
      */
     async sendApiMessageStream(sessionId, chatId, message, callbacks, opts) {
+        if (this.orchestrationForApi(sessionId)) {
+            if (this.pendingApiSessions.has(sessionId))
+                throw Object.assign(new Error('Session already has a pending request'), { code: 'CONFLICT' });
+            const turn = this.turnStreams.start((0, turn_stream_1.turnStreamKey)('api', sessionId), opts.requestId ?? (0, crypto_1.randomUUID)());
+            const sink = (0, turn_stream_1.callbackSink)(callbacks);
+            turn.attach(sink, 0);
+            void this.sendOrchestratedApi(sessionId, chatId, message, { ...opts, requestId: turn.requestId }, text => turn.emit({ type: 'text_delta', text }), event => { if (event.type === 'tool_use')
+                turn.emit({ ...event, type: 'tool_use' }); })
+                .then(result => this.turnStreams.complete(turn, (0, turn_stream_1.resultEvent)(result.text, result.attachments)))
+                .catch(error => this.turnStreams.complete(turn, (0, turn_stream_1.errorEvent)(error), error));
+            return () => turn.detach(sink);
+        }
         if (this.pendingApiSessions.has(sessionId)) {
             const err = Object.assign(new Error(`Session ${sessionId} already has a pending request`), { code: 'CONFLICT' });
             throw err;
@@ -4192,6 +4897,8 @@ class AgentRunner extends events_1.EventEmitter {
         if (!AgentRunner.isApiBuiltinCommand(cmd)) {
             throw new Error(`Unknown command: ${cmd}`);
         }
+        if (cmd === '/stop' && this.agentConfig.orchestration?.enabled && opts?.principalId)
+            this.orchestration?.authorizeSession(sessionId, opts.principalId);
         // Register session in the api-{chatId} index on first use (same as sendApiMessageStream)
         await this.sessionStore.ensureApiSession(agentId, storeChatId, sessionId).catch((err) => {
             this.logger.warn('Failed to register API session in index for command', { agentId, chatId, sessionId, error: err.message });
@@ -4214,7 +4921,7 @@ class AgentRunner extends events_1.EventEmitter {
         // Persist the full user command before executing so it appears in history.
         // Skip for /clear — clearSession() below wipes the table anyway; only the response survives.
         if (cmd !== '/clear') {
-            persist('user', command);
+            persist('user', opts?.displayCommand ?? command);
         }
         let result;
         let responseText;
@@ -4229,17 +4936,41 @@ class AgentRunner extends events_1.EventEmitter {
                     : `Current model: ${model}`;
             }
             else if (cmd === '/stop') {
-                const session = this.sessions.get(sessionId);
-                const stopped = session ? session.interrupt() : false;
-                result = { stopped };
-                responseText = stopped
-                    ? 'Session was interrupted before I could respond.'
-                    : 'No active session to stop.';
-                // A turn was actually cut off — always leave a visible note in history so the
-                // web Stop button (skipPersist:true, to suppress the "/stop" command echo) and
-                // a typed /stop command show the same outcome instead of the button leaving a
-                // silently-dangling user turn.
-                forcePersist = stopped;
+                if (this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes('api') && this.orchestration && opts?.principalId) {
+                    const selection = /^\/stop\s+([a-f0-9-]{36})\s+(\d+)$/.exec(command.trim());
+                    if (selection) {
+                        try {
+                            const selected = this.orchestration.stopControls.choose(sessionId, opts.principalId, selection[1], Number(selection[2]));
+                            result = { ...selected };
+                            responseText = selected.text;
+                        }
+                        catch {
+                            result = { error: 'STOP_SELECTION_UNAVAILABLE' };
+                            responseText = 'Selection unavailable. Use /stop to refresh the task list.';
+                        }
+                    }
+                    else {
+                        const menu = this.orchestration.stopControls.open(sessionId, opts.principalId);
+                        responseText = (0, stop_controls_1.stopMenuText)(menu);
+                        result = { ...menu, responseText };
+                    }
+                    forcePersist = true;
+                }
+                else {
+                    const session = this.sessions.get(sessionId);
+                    const stopped = this.agentConfig.orchestration?.enabled && this.orchestration?.isBusy(sessionId)
+                        ? this.orchestration.stopResponse(sessionId)
+                        : session ? session.interrupt() : false;
+                    result = { stopped };
+                    responseText = stopped
+                        ? 'Session was interrupted before I could respond.'
+                        : 'No active session to stop.';
+                    // A turn was actually cut off — always leave a visible note in history so the
+                    // web Stop button (skipPersist:true, to suppress the "/stop" command echo) and
+                    // a typed /stop command show the same outcome instead of the button leaving a
+                    // silently-dangling user turn.
+                    forcePersist = stopped;
+                }
             }
             else if (cmd === '/restart') {
                 this.restartProcess(sessionId).catch(() => { });
@@ -4519,6 +5250,100 @@ class AgentRunner extends events_1.EventEmitter {
         const mediaPaths = this.historyDb.clearSession(`api-${chatId}`, sessionId);
         media_store_1.MediaStore.deleteMediaFiles(this.agentsBaseDir, this.agentConfig.id, mediaPaths);
     }
+    /** The route has already authorized this API principal for the Agent. Preserve
+     * the original channel binding, but never impersonate its human sender. */
+    async sendOrchestratedChannel(rawChatId, channel, sessionId, message, senderName, callbacks, opts) {
+        if (!opts.principalId)
+            throw new Error('Authenticated principal required for conversation orchestration');
+        const runtime = await this.getOrchestration();
+        const rows = runtime.store.all('SELECT * FROM conversations WHERE agent_session_id=?', sessionId);
+        if (rows.length > 1 || rows.some(row => row.source !== channel || row.chat_id !== rawChatId))
+            throw new Error('Ambiguous or mismatched channel session');
+        if (!rows.length) {
+            const index = await this.sessionStore.loadIndex(this.agentConfig.id, rawChatId, channel);
+            if (!index?.sessions.some(session => session.id === sessionId))
+                throw new Error('Session not found');
+        }
+        const requestId = opts.requestId ?? (0, crypto_1.randomUUID)();
+        const accepted = runtime.submitInput({ scope: { agentId: this.agentConfig.id, agentSessionId: sessionId,
+                source: channel, accountId: String(rows[0]?.account_id ?? this.agentConfig.id), chatId: rawChatId,
+                threadKey: String(rows[0]?.thread_key ?? ''), principalId: opts.principalId },
+            text: message, requestId, trustedChannelMember: true, metadata: { senderName, senderId: opts.principalId } }, { execute: opts.allowTools ?? false, writeMemory: false });
+        const turn = this.turnStreams.start((0, turn_stream_1.turnStreamKey)(channel, sessionId), requestId);
+        const sink = (0, turn_stream_1.callbackSink)(callbacks);
+        turn.attach(sink, 0);
+        const displayed = new Map();
+        const unsubscribe = runtime.subscribeText(sessionId, opts.principalId, event => {
+            if (!runtime.responseBelongsToInput(accepted.inputId, event.responseId))
+                return;
+            const previous = displayed.get(event.responseId) ?? '';
+            if (event.text.startsWith(previous)) {
+                const delta = event.text.slice(previous.length);
+                displayed.set(event.responseId, event.text);
+                if (delta)
+                    turn.emit({ type: 'text_delta', text: delta });
+            }
+        });
+        const input = runtime.store.get('SELECT conversation_id FROM conversation_inputs WHERE id=?', accepted.inputId);
+        const conversation = runtime.store.assertMember(String(input.conversation_id), opts.principalId);
+        let cursor = { streamId: String(conversation.stream_id), seq: Number(conversation.last_event_seq) };
+        const events = runtime.events.subscribe(String(conversation.id), opts.principalId, cursor);
+        let closed = false;
+        let timer;
+        const close = () => { closed = true; clearTimeout(timer); unsubscribe(); events.close(); };
+        const forward = (page) => {
+            if (page.snapshotRequired)
+                throw new Error('Tool activity history expired; reload session activity');
+            for (const event of page.events) {
+                if (event.seq <= cursor.seq)
+                    continue;
+                const payload = event.payload;
+                if (event.type === 'tool.activity' && payload.type === 'tool_use')
+                    turn.emit({ ...payload, type: 'tool_use' });
+                cursor = { streamId: page.cursor.streamId, seq: event.seq };
+            }
+        };
+        const drain = () => {
+            while (true) {
+                const page = runtime.events.read(String(conversation.id), opts.principalId, cursor);
+                forward(page);
+                if (!page.snapshotRequired && !page.events.length)
+                    break;
+            }
+        };
+        const fail = (error) => {
+            if (closed)
+                return;
+            try {
+                drain();
+            }
+            catch { /* Preserve the original stream/provider failure. */ }
+            this.turnStreams.completeAndRelease(turn, (0, turn_stream_1.errorEvent)(error), error);
+            close();
+        };
+        void (async () => {
+            for await (const page of events.pages) {
+                if (closed)
+                    break;
+                forward(page);
+            }
+        })().catch(fail);
+        timer = setTimeout(() => fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT_SOFT' })), opts.timeoutMs);
+        void accepted.response.then(text => {
+            if (closed)
+                return;
+            try {
+                // Drain before terminal success, even when completion precedes the next poll.
+                drain();
+                this.turnStreams.completeAndRelease(turn, (0, turn_stream_1.resultEvent)(text, []));
+                close();
+            }
+            catch (error) {
+                fail(error instanceof Error ? error : new Error('Tool activity stream failed'));
+            }
+        }, fail);
+        return () => { turn.detach(sink); }; // Durable work and original channel delivery survive disconnect.
+    }
     /**
      * Send a message into an existing channel session (cross-channel continuation from UI).
      * The session process receives full history context from the session JSON (Layer 1).
@@ -4528,6 +5353,10 @@ class AgentRunner extends events_1.EventEmitter {
      * parser — and writing here as well produced a second row per turn. See done().
      */
     async sendMessageToSession(rawChatId, channel, sessionId, message, senderName, callbacks, opts) {
+        const managed = (this.agentConfig.orchestration?.enabled && (this.agentConfig.orchestration.channels ?? ['api']).includes(channel)) ||
+            (this.orchestration?.ownsSession(sessionId) && !this.orchestration.canReturnToLegacy());
+        if (managed)
+            return this.sendOrchestratedChannel(rawChatId, channel, sessionId, message, senderName, callbacks, opts);
         // Ensure the session process uses the correct channel source
         this.channelSourceMap.set(rawChatId, channel);
         // Channel sessions use agent-level model (not per-session)