cli-wechat-bridge 1.1.7 → 1.2.0

package/dist/bridge/wechat-forwarding.js

@@ -1,2 +1,8 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 /** @deprecated Import from ../channels/wechat/wechat-forwarding.ts instead. */
 export * from "../channels/wechat/wechat-forwarding.js";

package/dist/bridge/wechat-outbound-queue.js

@@ -1,2 +1,8 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 /** @deprecated Import from ../channels/wechat/wechat-outbound-queue.ts instead. */
 export * from "../channels/wechat/wechat-outbound-queue.js";

package/dist/channels/wechat/bridge-final-reply.js

@@ -1,4 +1,4 @@
-import { formatFinalReplyMessage, parseWechatFinalReply, sanitizeWechatFinalReplyText, splitWechatTextIntoChunks, } from "../../bridge/bridge-utils.js";
+import { formatFinalReplyMessage, parseWechatFinalReply, sanitizeWechatFinalReplyText, } from "../../bridge/bridge-utils.js";
 export const OPENCODE_EMPTY_VISIBLE_REPLY_MESSAGE = "OpenCode 没有产生可发送到微信的可见回复。请查看本地终端输出，或重试这条消息。";
 export async function forwardWechatFinalReply(params) {
     const { adapter, rawText, sender, onEmptyVisibleReply } = params;
@@ -6,28 +6,19 @@ export async function forwardWechatFinalReply(params) {
     const sanitizedText = sanitizeWechatFinalReplyText(adapter, parsed.visibleText);
     const visibleText = formatFinalReplyMessage(adapter, sanitizedText).trim();
     if (visibleText) {
-        // Send long replies in bounded chunks: a single oversized sendmessage call
-        // can be rejected by the WeChat API, silently losing the whole reply.
-        const chunks = splitWechatTextIntoChunks(visibleText);
-        for (let index = 0; index < chunks.length; index += 1) {
-            const sent = await sender.sendText(chunks[index]);
-            if (sent === false) {
-                // The send channel is failing (e.g. an expired context token).
-                // Report what was dropped instead of ending mid-reply silently;
-                // this notice itself is best effort and may also fail.
-                const remainingChunks = chunks.length - index - 1;
-                if (remainingChunks > 0 || parsed.attachments.length > 0) {
-                    const parts = [];
-                    if (remainingChunks > 0) {
-                        parts.push(`${remainingChunks} reply chunk(s)`);
-                    }
-                    if (parsed.attachments.length > 0) {
-                        parts.push(`${parsed.attachments.length} attachment(s)`);
-                    }
-                    await sender.sendText(`[bridge] Reply delivery was interrupted; ${parts.join(" and ")} could not be sent. Send a new message to retry.`);
-                }
-                return;
+        // Send the reply as a single message, matching the official WeChat bot
+        // client: it posts the full text in one sendmessage call without
+        // chunking. A failed send surfaces through the sender's own retry and
+        // pending-queue handling instead of being split up.
+        const sent = await sender.sendText(visibleText);
+        if (sent === false) {
+            // The send channel is failing (e.g. an expired context token).
+            // Report what was dropped instead of ending silently; this notice
+            // itself is best effort and may also fail.
+            if (parsed.attachments.length > 0) {
+                await sender.sendText(`[bridge] Reply delivery was interrupted; ${parsed.attachments.length} attachment(s) could not be sent. Send a new message to retry.`);
             }
+            return;
         }
     }
     else if (adapter === "opencode" && parsed.visibleText.trim()) {

package/dist/channels/wechat/index.js

@@ -1,3 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 export * from "./bridge-final-reply.js";
 export * from "./channel-message.js";
 export * from "./wechat-channel-port.js";

package/dist/channels/wechat/wechat-driver.js

@@ -0,0 +1,191 @@
+import { WECHAT_SEND_MAX_ATTEMPTS, computeWechatSendRetryDelayMs, formatWechatContextTokenStaleLogEntry, formatWechatSendFailureLogEntry, formatWechatSendRetryLogEntry, isRetryableWechatSendError, isWechatContextUnavailableError, } from "../../channels/wechat/wechat-forwarding.js";
+import { describeWechatTransportError, isWechatContextTokenStaleError, } from "../../wechat/wechat-transport.js";
+import { formatDuration } from "../../core/text-utils.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Per-recipient typing tickets with a random-refresh TTL and retry backoff. */
+class TypingTicketCache {
+    fetchTicket;
+    log;
+    ttlMs;
+    initialRetryMs;
+    maxRetryMs;
+    cache = new Map();
+    constructor(fetchTicket, log, ttlMs = 24 * 60 * 60 * 1000, initialRetryMs = 2_000, maxRetryMs = 60 * 60 * 1000) {
+        this.fetchTicket = fetchTicket;
+        this.log = log;
+        this.ttlMs = ttlMs;
+        this.initialRetryMs = initialRetryMs;
+        this.maxRetryMs = maxRetryMs;
+    }
+    async getFor(recipientId) {
+        const now = Date.now();
+        const entry = this.cache.get(recipientId);
+        if (entry && now < entry.nextFetchAt) {
+            return entry.ticket;
+        }
+        let ticket;
+        try {
+            ticket = await this.fetchTicket(recipientId);
+        }
+        catch {
+            ticket = "";
+        }
+        if (ticket) {
+            this.cache.set(recipientId, {
+                ticket,
+                nextFetchAt: now + Math.random() * this.ttlMs,
+                retryDelayMs: this.initialRetryMs,
+            });
+            this.log(`wechat_typing_ticket_${entry ? "refreshed" : "cached"}: recipient=${recipientId}`);
+        }
+        else {
+            const retryDelayMs = Math.min((entry?.retryDelayMs ?? this.initialRetryMs / 2) * 2, this.maxRetryMs);
+            this.cache.set(recipientId, {
+                ticket: entry?.ticket ?? "",
+                nextFetchAt: now + retryDelayMs,
+                retryDelayMs,
+            });
+            this.log(`wechat_typing_ticket_fetch_failed: recipient=${recipientId} retry_in=${formatDuration(retryDelayMs)}`);
+        }
+        return this.cache.get(recipientId)?.ticket ?? "";
+    }
+    /** Cached ticket without triggering a fetch (for cancel sends). */
+    peekCached(recipientId) {
+        return this.cache.get(recipientId)?.ticket ?? "";
+    }
+}
+const WECHAT_CONTEXT_STALE_HINT = "WeChat conversation context is stale or unavailable. Ask the WeChat owner to send any message first, then local terminal replies can sync back to WeChat.";
+/** ChannelDriver over the WeChat iLink long-poll transport. */
+export class WechatChannelDriver {
+    id = "wechat";
+    displayName = "WeChat";
+    operatorDescription = "the configured WeChat owner";
+    capabilities = {
+        streamingReplies: false,
+        outboundAttachments: false,
+        multiConversation: false,
+        pushInbound: false,
+    };
+    transport;
+    logError;
+    buildInboundPromptImpl;
+    typingKeepaliveMs;
+    typingTickets;
+    typingTimers = new Map();
+    constructor(options) {
+        this.transport = options.transport;
+        this.logError = options.logError;
+        this.buildInboundPromptImpl = options.buildInboundPrompt;
+        this.typingKeepaliveMs = options.typingKeepaliveMs ?? 5_000;
+        this.typingTickets = new TypingTicketCache((recipientId) => this.transport.fetchTypingTicket(recipientId), (message) => this.logError(`[typing] ${message}`));
+    }
+    defaultConversation() {
+        return null;
+    }
+    directConversation(senderId) {
+        return {
+            channelId: "wechat",
+            conversationId: senderId,
+            recipientId: senderId,
+        };
+    }
+    async sendText(params) {
+        const { target, text, context, log } = params;
+        const senderId = target.recipientId;
+        const startedAtMs = Date.now();
+        log(`wechat_send_started: context=${context} recipient=${senderId} chars=${Array.from(text).length}`);
+        for (let attempt = 1; attempt <= WECHAT_SEND_MAX_ATTEMPTS; attempt += 1) {
+            try {
+                await this.transport.sendText(senderId, text);
+                log(`wechat_send_completed: context=${context} recipient=${senderId} attempt=${attempt} elapsed_ms=${Date.now() - startedAtMs}`);
+                return { status: "sent" };
+            }
+            catch (err) {
+                if (err instanceof Error && err.name === "AbortError") {
+                    log(`wechat_send_timeout: context=${context} recipient=${senderId} attempt=${attempt} elapsed_ms=${Date.now() - startedAtMs}`);
+                }
+                if (isWechatContextUnavailableError(err)) {
+                    if (isWechatContextTokenStaleError(err)) {
+                        this.transport.clearCachedContextToken(senderId);
+                    }
+                    this.logError(`Failed to send WeChat ${context}: ${WECHAT_CONTEXT_STALE_HINT}`);
+                    log(isWechatContextTokenStaleError(err)
+                        ? formatWechatContextTokenStaleLogEntry({
+                            context,
+                            recipientId: senderId,
+                            error: err,
+                        })
+                        : formatWechatSendFailureLogEntry({
+                            context,
+                            recipientId: senderId,
+                            error: err,
+                        }));
+                    return {
+                        status: "target_stale",
+                        error: err,
+                        target,
+                    };
+                }
+                if (attempt < WECHAT_SEND_MAX_ATTEMPTS && isRetryableWechatSendError(err)) {
+                    const delayMs = computeWechatSendRetryDelayMs(attempt);
+                    this.logError(`Failed to send WeChat ${context} (attempt ${attempt}). Retrying in ${formatDuration(delayMs)}. ${describeWechatTransportError(err)}`);
+                    log(formatWechatSendRetryLogEntry({
+                        context,
+                        recipientId: senderId,
+                        attempt,
+                        delayMs,
+                        error: err,
+                    }));
+                    await delay(delayMs);
+                    continue;
+                }
+                this.logError(`Failed to send WeChat ${context}: ${describeWechatTransportError(err)}`);
+                log(formatWechatSendFailureLogEntry({
+                    context,
+                    recipientId: senderId,
+                    error: err,
+                }));
+                return { status: "failed", error: err, target };
+            }
+        }
+        return { status: "failed", error: new Error("unreachable"), target };
+    }
+    buildInboundPrompt(text, attachments) {
+        return this.buildInboundPromptImpl(text, attachments);
+    }
+    async beginTyping(recipientId) {
+        if (this.typingTimers.has(recipientId)) {
+            return;
+        }
+        const ticket = await this.typingTickets.getFor(recipientId);
+        if (!ticket) {
+            return;
+        }
+        const sent = await this.transport.sendTyping(recipientId, ticket, 1);
+        if (!sent) {
+            return;
+        }
+        const timer = setInterval(() => {
+            void this.transport.sendTyping(recipientId, ticket, 1);
+        }, this.typingKeepaliveMs);
+        timer.unref?.();
+        this.typingTimers.set(recipientId, timer);
+    }
+    async endTyping(recipientId) {
+        const timer = this.typingTimers.get(recipientId);
+        if (timer) {
+            clearInterval(timer);
+            this.typingTimers.delete(recipientId);
+        }
+        const ticket = this.typingTickets.peekCached(recipientId);
+        if (!ticket) {
+            return;
+        }
+        await this.transport.sendTyping(recipientId, ticket, 2);
+    }
+    async endAllTyping() {
+        for (const recipientId of [...this.typingTimers.keys()]) {
+            await this.endTyping(recipientId);
+        }
+    }
+}

package/dist/channels/wechat/wechat-forwarding.js

@@ -1,5 +1,23 @@
 import { truncatePreview } from "../../bridge/bridge-utils.js";
 import { classifyWechatTransportError, describeWechatTransportError, isWechatContextTokenStaleError, } from "../../wechat/wechat-transport.js";
+export const WECHAT_SEND_CONTEXTS = [
+    "final_reply",
+    "message",
+    "notice",
+    "approval_required",
+    "user_input_required",
+    "mirrored_user_input",
+    "session_switched",
+    "thread_switched",
+    "task_failed",
+    "fatal_error",
+    "inbound_error",
+    "thinking",
+];
+export function isWechatSendContext(value) {
+    return typeof value === "string" &&
+        WECHAT_SEND_CONTEXTS.includes(value);
+}
 export const WECHAT_SEND_MAX_ATTEMPTS = 3;
 export const CODEX_LOCAL_THREAD_NOTICE_SUPPRESS_MS = 500;
 const WECHAT_SEND_RETRY_BASE_MS = 750;

package/dist/channels/wechat/wechat-outbound-queue.js

@@ -1,8 +1,33 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { getWorkspaceChannelPaths } from "../../wechat/channel-config.js";
 import { writeJsonFileAtomic } from "../../utils/atomic-file.js";
+/** Contexts worth redelivering after the channel recovers. */
+const PENDING_WORTHY_CONTEXTS = new Set([
+    "final_reply",
+    "approval_required",
+    "user_input_required",
+    "task_failed",
+    "fatal_error",
+]);
+/** Drop queued messages older than this — stale replies are noise, not value. */
+const PENDING_MAX_AGE_MS = 30 * 60 * 1000;
+/** Cap the backlog so one recovery never floods the chat. */
+const PENDING_MAX_MESSAGES = 10;
+function isExpired(message, now = Date.now()) {
+    const queuedAtMs = Date.parse(message.queuedAt);
+    if (!Number.isFinite(queuedAtMs)) {
+        return true;
+    }
+    return now - queuedAtMs > PENDING_MAX_AGE_MS;
+}
 export function getPendingWechatMessagesFile(cwd) {
     return getPendingChannelMessagesFile(cwd, "wechat");
 }
@@ -41,6 +66,7 @@ export class PendingWechatMessageStore {
         this.messages = readPendingMessages(filePath);
     }
     list() {
+        this.compact();
         return this.messages.map((message) => ({
             ...message,
             target: message.target ? { ...message.target } : undefined,
@@ -52,6 +78,9 @@ export class PendingWechatMessageStore {
         if (!normalizedRecipientId || !normalizedText) {
             return null;
         }
+        if (!PENDING_WORTHY_CONTEXTS.has(context)) {
+            return null;
+        }
         const message = {
             id: crypto.randomUUID(),
             recipientId: normalizedRecipientId,
@@ -61,9 +90,19 @@ export class PendingWechatMessageStore {
             target: target ? { ...target } : undefined,
         };
         this.messages.push(message);
+        this.compact();
         this.persist();
         return { ...message };
     }
+    /** Drop expired entries and trim the backlog to the cap (oldest first). */
+    compact() {
+        const now = Date.now();
+        const fresh = this.messages.filter((message) => !isExpired(message, now));
+        while (fresh.length > PENDING_MAX_MESSAGES) {
+            fresh.shift();
+        }
+        this.messages = fresh;
+    }
     remove(id) {
         const next = this.messages.filter((message) => message.id !== id);
         if (next.length === this.messages.length) {

package/dist/channels/wecom/bridge-final-reply.js

@@ -1,3 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import path from "node:path";
 import { formatFinalReplyMessage, parseWechatFinalReply, sanitizeWechatFinalReplyText, } from "../../bridge/bridge-utils.js";
 export async function forwardWecomFinalReply(params) {

package/dist/channels/wecom/setup-cli.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import { runWecomSetup } from "./setup.js";
 runWecomSetup().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));

package/dist/channels/wecom/setup.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env bun
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import crypto from "node:crypto";
 import readline from "node:readline";
 import { Writable } from "node:stream";

package/dist/channels/wecom/wecom-config.js

@@ -1,3 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import fs from "node:fs";
 import path from "node:path";
 import { CHANNEL_DATA_DIR, ensureChannelDataDir, } from "../../wechat/channel-config.js";

package/dist/channels/wecom/wecom-driver.js

@@ -0,0 +1,106 @@
+import { buildWecomInboundPrompt, formatWecomVisibleText, } from "./wecom-message.js";
+import { truncatePreview } from "../../core/text-utils.js";
+export function toWecomOutputKind(context) {
+    const known = new Set([
+        "status",
+        "notice",
+        "thinking",
+        "final_reply",
+        "approval_required",
+        "user_input_required",
+        "mirrored_input",
+        "task_failed",
+        "fatal_error",
+    ]);
+    return known.has(context)
+        ? context
+        : context === "mirrored_user_input"
+            ? "mirrored_input"
+            : "notice";
+}
+/** ChannelDriver over the official WeCom smart-bot WebSocket transport. */
+export class WecomChannelDriver {
+    id = "wecom";
+    displayName = "WeCom";
+    operatorDescription = "the paired WeCom operator";
+    capabilities = {
+        streamingReplies: true,
+        outboundAttachments: true,
+        multiConversation: true,
+        pushInbound: true,
+    };
+    transport;
+    accountId;
+    operatorId;
+    logError;
+    constructor(options) {
+        this.transport = options.transport;
+        this.accountId = options.accountId;
+        this.operatorId = options.operatorId;
+        this.logError = options.logError;
+    }
+    defaultConversation() {
+        return this.directConversation(this.operatorId);
+    }
+    directConversation(senderId) {
+        return {
+            channelId: "wecom",
+            accountId: this.accountId,
+            conversationId: senderId,
+            recipientId: senderId,
+            metadata: { chatType: "direct" },
+        };
+    }
+    start(handlers) {
+        this.transport.setHandlers({
+            onMessage: async (message) => {
+                await handlers.onInboundMessage(message);
+            },
+            onUnauthorized: handlers.onUnauthorizedSender
+                ? async (senderId, chatType) => {
+                    await handlers.onUnauthorizedSender(senderId, chatType);
+                }
+                : undefined,
+            onFatal: handlers.onChannelFatal
+                ? async (error) => {
+                    await handlers.onChannelFatal(error);
+                }
+                : undefined,
+            onConnected: handlers.onChannelConnected
+                ? async () => {
+                    await handlers.onChannelConnected();
+                }
+                : undefined,
+        });
+        this.transport.start();
+    }
+    waitUntilReady() {
+        return this.transport.waitUntilConnected();
+    }
+    async sendText(params) {
+        const { target, text, context, log } = params;
+        const startedAtMs = Date.now();
+        log(`wecom_send_started: context=${context} recipient=${target.recipientId} chars=${Array.from(text).length}`);
+        try {
+            await this.transport.sendText(target, formatWecomVisibleText(text), toWecomOutputKind(context));
+            log(`wecom_send_completed: context=${context} recipient=${target.recipientId} elapsed_ms=${Date.now() - startedAtMs}`);
+            return { status: "sent" };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`wecom_send_failed: context=${context} recipient=${target.recipientId} error=${truncatePreview(message, 400)}`);
+            this.logError(`Failed to send WeCom ${context}: ${message}`);
+            return {
+                status: "target_stale",
+                error,
+                target,
+            };
+        }
+    }
+    buildInboundPrompt(text, attachments) {
+        return buildWecomInboundPrompt(text, attachments);
+    }
+    formatVisibleText(text) {
+        return formatWecomVisibleText(text);
+    }
+}

package/dist/channels/wecom/wecom-media.js

@@ -1,3 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import fs from "node:fs";
 import path from "node:path";
 import { decryptFile } from "@wecom/aibot-node-sdk";

package/dist/channels/wecom/wecom-transport.js

@@ -1,3 +1,9 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import fs from "node:fs";
 import path from "node:path";
 import { generateReqId, WSAuthFailureError, WSClient, WSReconnectExhaustedError, } from "@wecom/aibot-node-sdk";

package/dist/commands/check-update.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env bun
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import { checkForUpdate, getCurrentVersion, } from "../utils/version-checker.js";
 async function main() {
     const currentVersion = await getCurrentVersion();

package/dist/companion/codex-remote-client.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 UNLINEARITY <unlinearity@gmail.com>
+// Source: https://github.com/UNLINEARITY/CLI-WeChat-Bridge
+// This file is part of CLI-WeChat-Bridge. Modifications and derivative works
+// must be released under AGPL-3.0-or-later with full source code; see
+// LICENSE.txt. Network services built on it must offer source to users.
 import crypto from "node:crypto";
 import { spawn } from "node:child_process";
 import net from "node:net";
 import path from "node:path";
 import { assertNoReservedExtraCliArgs, buildCliEnvironment, buildCodexCliArgs, resolveSpawnTarget, } from "../bridge/bridge-adapters.shared.js";
 import { killProcessTreeSync } from "../bridge/bridge-process-reaper.js";
-import { CODEX_VISIBLE_CONTROL_HOST, parseCodexVisibleSwitchRequest, sendCodexVisibleSwitchResponse, } from "./codex-visible-client-link.js";
+import { CODEX_VISIBLE_CONTROL_HOST, parseCodexVisibleControlRequest, sendCodexVisibleShutdownResponse, sendCodexVisibleSwitchResponse, } from "./codex-visible-client-link.js";
 import { clearLocalCompanionOccupancy, readLocalCompanionEndpoint, updateCodexVisibleControl, updateLocalCompanionOccupancy, } from "./local-companion-link.js";
 import { migrateLegacyChannelFiles } from "../wechat/channel-config.js";
 import { CODEX_REMOTE_AUTH_TOKEN_ENV } from "../runtime/runtime-types.js";
@@ -302,11 +308,20 @@ export class CodexVisibleClientSupervisor {
                     socket.destroy();
                     return;
                 }
-                const request = parseCodexVisibleSwitchRequest(parsed);
+                const request = parseCodexVisibleControlRequest(parsed);
                 if (!request || request.token !== this.controlToken) {
                     socket.destroy();
                     return;
                 }
+                if (request.type === "shutdown") {
+                    sendCodexVisibleShutdownResponse(socket, {
+                        type: "shutdown_result",
+                        id: request.id,
+                        ok: true,
+                    });
+                    void this.shutdownFromControl();
+                    return;
+                }
                 void this.switchThread(request.threadId).then(() => {
                     sendCodexVisibleSwitchResponse(socket, {
                         type: "switch_thread_result",
@@ -340,6 +355,17 @@ export class CodexVisibleClientSupervisor {
         this.controlServer = server;
         this.controlPort = address.port;
     }
+    async shutdownFromControl() {
+        await this.switchChain.catch(() => undefined);
+        if (this.runSettled) {
+            return;
+        }
+        const child = this.child;
+        if (child) {
+            await this.stopChild(child);
+        }
+        this.finishRun(undefined, 0);
+    }
     async closeControlServer() {
         const server = this.controlServer;
         this.controlServer = null;