@0xmaxma/claude-gateway 1.8.14 → 2.0.1

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"));
@@ -226,6 +234,237 @@ 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 (!['telegram', '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}` : meta.message_thread_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;
+    }
+    async answerApiTask(sessionId, principalId, taskId, questionId, answer) {
+        if (!this.agentConfig.orchestration?.enabled)
+            throw new Error('ORCHESTRATION_DISABLED');
+        const runtime = await this.getOrchestration();
+        const task = runtime.taskControls.answer(sessionId, principalId, taskId, questionId, answer);
+        await runtime.flushHistory();
+        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;
@@ -246,6 +485,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
@@ -357,6 +597,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;
         /**
@@ -399,7 +640,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
@@ -428,6 +670,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;
     }
@@ -453,7 +714,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;
@@ -471,8 +732,6 @@ 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 ?? {};
@@ -486,6 +745,87 @@ class AgentRunner extends events_1.EventEmitter {
                     // 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 (/^\/task_question(?:\s|$)/.test(content.trim()) || (channelSource !== 'telegram' && /^\/orch\s+q:/.test(content.trim()))) {
+                        let menu = { text: 'Task controls require orchestration mode.', buttons: [] };
+                        if (channelOrchestration) {
+                            const sessionId = await this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, channelSource);
+                            const runtime = await this.getOrchestration();
+                            const scope = { channel: channelSource, chatId, thread: channelSource === 'whatsapp' && meta.account_id ? `whatsapp-account:${meta.account_id}` : meta.thread_ts ?? meta.message_thread_id ?? '', sessionId, principalId: `${channelSource}:${meta.user_id ?? meta.user ?? chatId}` };
+                            try {
+                                menu = runtime.questionControls.handle(scope, content.trim()) ?? { text: 'Invalid task question command.', buttons: [] };
+                            }
+                            catch {
+                                menu = { text: 'Question unavailable or already answered. Use /tasks to refresh.', buttons: [] };
+                            }
+                            await runtime.flushHistory();
+                        }
+                        const responseMeta = { ...meta };
+                        delete responseMeta.control_message_id;
+                        await this.sendOrchestrationControl(channelSource, chatId, menu, responseMeta);
+                        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
@@ -554,6 +894,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,
                     });
@@ -597,6 +941,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 ?? '',
@@ -764,6 +1112,146 @@ 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_question') {
+            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: 'Task controls require orchestration mode.' });
+                return;
+            }
+            if (typeof payload.question_id !== 'string' || !['snooze', 'mute'].includes(String(payload.action))) {
+                respond({ success: false, error: 'Invalid question command.' }, 400);
+                return;
+            }
+            try {
+                const runtime = await this.getOrchestration();
+                const sessionId = await this.sessionStore.getActiveSessionId(this.agentConfig.id, chatId, 'telegram');
+                const menu = runtime.questionControls.handle({ channel: 'telegram', chatId, thread: typeof payload.thread === 'string' ? payload.thread : '', sessionId, principalId: `telegram:${payload.user_id}` }, `/task_question ${payload.question_id} ${payload.action}`);
+                if (!menu)
+                    throw Error('INVALID_QUESTION');
+                respond({ success: true, text: menu.text });
+            }
+            catch {
+                respond({ success: false, error: 'Question unavailable or already answered. Use /tasks 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;
@@ -796,6 +1284,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'] : '';
@@ -1240,6 +1732,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
@@ -2115,7 +2609,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();
@@ -2171,7 +2665,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);
             });
@@ -2236,6 +2730,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');
     }
@@ -2435,6 +2932,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)
@@ -2816,7 +3320,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 };
     }
@@ -3043,7 +3549,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())
@@ -3058,16 +3564,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
@@ -3128,8 +3638,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();
@@ -3381,6 +3917,25 @@ class AgentRunner extends events_1.EventEmitter {
                     });
                 }
             }
+            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',
@@ -3458,8 +4013,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() {
@@ -3477,8 +4033,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() {
@@ -3493,6 +4050,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;
@@ -3575,6 +4138,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
@@ -3612,6 +4186,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;
@@ -3894,6 +4470,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;
@@ -4365,6 +4953,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 });
@@ -4387,7 +4977,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;
@@ -4402,17 +4992,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(() => { });
@@ -4692,6 +5306,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).
@@ -4701,6 +5409,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)