@foxden-app/foxclaw 0.13.1 → 0.13.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.13.2 - 2026-10-06
+
+### 中文
+
+- Telegram 后端列表新增“添加后端”，首次支持接入 DSH。本机 CLI、源码路径及官方安装包均可从面板操作，也可发送 `/backend add dsh`。
+- DSH 启动检查通过后保存配置并直接接入本机所有统一 Bot，保留当前任务和会话；明确选择后才切换。安装与配置操作统一归属服务，覆盖跨 Bot 并发、失败、过期按钮及关闭时取消。
+
+### English
+
+- Added Telegram backend setup, initially supporting DSH through a local CLI, source path or official package. Open “Add backend” or send `/backend add dsh`.
+- Verify startup before saving configuration and registering DSH on every unified bot without restarting or switching sessions. One service owns provisioning, including cross-bot concurrency, failures, expired actions and shutdown cancellation.
+
 ## 0.13.1 - 2026-10-06
 
 ### 中文

package/dist/bridge/unified_bridge.d.ts

@@ -1,4 +1,5 @@
 import type { ChannelPort } from '../core/channel_port.js';
+import { BackendSetupManager } from '../service/backend_setup.js';
 import type { AppConfig } from '../config.js';
 import type { Logger } from '../logger.js';
 import type { BridgeStore } from '../store/database.js';
@@ -27,6 +28,7 @@ export interface UnifiedBridgeRuntimeStatus {
     lastError?: string | null | undefined;
 }
 export interface UnifiedBridgeCoreOptions {
+    backendSetup?: BackendSetupManager | undefined;
     codexApp?: CodexAppClient | undefined;
     codexAdapter?: CodexEngineAdapter | undefined;
     codexCore?: BridgeSessionCore | undefined;
@@ -41,6 +43,9 @@ export interface UnifiedBridgeCoreOptions {
     ownsScope?: (scopeId: string) => boolean;
 }
 export declare class UnifiedBridgeCore {
+    private readonly backendSetup?;
+    private readonly backendSetupUi?;
+    private readonly detachBackendSetup?;
     private readonly conversationUi;
     private readonly accountUi;
     private readonly config;

package/dist/bridge/unified_bridge.js

@@ -1,6 +1,7 @@
 import { AntigravityConversationUi } from '../antigravity/conversation_ui.js';
 import { AntigravityAccountUi } from '../antigravity/account_ui.js';
 import { createCodexBackendUi } from '../codex_app/backend_ui.js';
+import { BackendSetupUi, safeSetupError } from '../service/backend_setup.js';
 import fsPromises from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -40,6 +41,9 @@ function formatAccountExpiry(expiryMs, locale, isActive = false) {
 }
 import { AGY_MODEL_CALLBACK_PREFIX, AGY_AUTH_CALLBACK_PREFIX, AGY_EFFORT_CALLBACK_PREFIX, AGY_OPEN_CALLBACK_PREFIX, AGY_SETUP_CALLBACK_PREFIX, AGY_WATCH_CALLBACK_PREFIX, } from '../antigravity/ui_callbacks.js';
 export class UnifiedBridgeCore {
+    backendSetup;
+    backendSetupUi;
+    detachBackendSetup;
     conversationUi;
     accountUi;
     config;
@@ -74,6 +78,7 @@ export class UnifiedBridgeCore {
         this.codexApp = options?.codexApp;
         this.defaultBackendId = options?.defaultBackendId ?? 'antigravity';
         this.selfUpdater = options?.selfUpdater;
+        this.backendSetup = options?.backendSetup;
         this.codexCore = options?.codexCore;
         if (!this.codexCore && options?.codexApp) {
             try {
@@ -198,11 +203,50 @@ export class UnifiedBridgeCore {
             }),
             backendProvider: () => this.getBackendDescriptors(),
             messaging: this.messaging,
-            serviceUi: { handleCustomCommand: (scopeId, cmd, args, locale, event) => this.handleServiceCommand(scopeId, cmd, args, locale, event) },
+            serviceUi: {
+                handleCustomCommand: (scopeId, cmd, args, locale, event) => this.handleServiceCommand(scopeId, cmd, args, locale, event),
+                renderBackendMenuRows: async (_scopeId, locale) => this.backendSetupUi?.rows(locale) ?? [],
+                handleCustomInbound: (event, locale) => this.backendSetupUi?.inbound(event, locale) ?? false,
+                handleCustomCallback: async (scopeId, data, locale, messageId, event) => {
+                    if (!this.backendSetupUi)
+                        return false;
+                    if (!data.startsWith('backend-setup:'))
+                        return this.backendSetupUi.callback(scopeId, data, locale, messageId);
+                    if (event)
+                        await this.messaging.answerCallback(event.callbackQueryId, '');
+                    try {
+                        await this.backendSetupUi.callback(scopeId, data, locale, messageId);
+                    }
+                    catch (error) {
+                        await this.sendMessage(scopeId, `❌ ${safeSetupError(error)}`);
+                    }
+                    return true;
+                },
+            },
         });
         const panels = { sendMessage: this.sendMessage.bind(this), editMessage: this.editMessage.bind(this), scheduleStalePanelDeletion: this.scheduleStalePanelDeletion.bind(this) };
         this.conversationUi = new AntigravityConversationUi(config, store, logger, this.conversations, panels, this.orchestrator);
         this.accountUi = new AntigravityAccountUi(config, store, logger, this.auth, panels, this.orchestrator);
+        if (this.backendSetup) {
+            this.backendSetupUi = new BackendSetupUi(this.backendSetup, {
+                listBackends: () => this.orchestrator.listBackends(),
+                readPathState: scopeId => this.store.getServiceInteraction(scopeId, 'backend-setup:path'),
+                writePathState: (scopeId, state) => this.store.setServiceInteraction(scopeId, 'backend-setup:path', state),
+                send: async (scopeId, text, keyboard, messageId) => {
+                    if (messageId)
+                        await this.editMessage(scopeId, messageId, text, keyboard);
+                    else
+                        await this.sendMessage(scopeId, text, keyboard);
+                },
+            });
+            this.detachBackendSetup = this.backendSetup.attach(factory => {
+                const backend = factory({ config: this.config, store: this.store, logger: this.logger, messaging: this.messaging });
+                if (this.backendDefinitions.some(existing => existing.id === backend.id))
+                    return;
+                this.orchestrator.registerBackend(backend);
+                this.backendDefinitions.push(backend);
+            });
+        }
     }
     backendDefinitions;
     async getBackendDescriptors() {
@@ -325,6 +369,8 @@ export class UnifiedBridgeCore {
     }
     async stop() {
         this.clearSelfUpdateStatusPoll();
+        this.detachBackendSetup?.();
+        this.backendSetupUi?.stop();
         try {
             await this.orchestrator.stop();
         }
@@ -421,7 +467,7 @@ export class UnifiedBridgeCore {
         };
     }
     isIdleForServiceUpdate() {
-        return this.orchestrator.isIdleForServiceUpdate();
+        return !this.backendSetup?.busy && this.orchestrator.isIdleForServiceUpdate();
     }
     async getCurrentAuthLabel() {
         const codexHome = this.config.codexAuthDir ?? this.config.codexHome ?? path.join(os.homedir(), '.codex');
@@ -703,7 +749,13 @@ export class UnifiedBridgeCore {
         return false;
     }
     async handleServiceCommand(scopeId, cmd, _args, locale, _event) {
+        if (await this.backendSetupUi?.command(scopeId, cmd, _args, locale))
+            return true;
         if (cmd.toLowerCase() === 'update') {
+            if (this.backendSetup?.busy) {
+                await this.sendMessage(scopeId, locale === 'zh' ? '⏳ 正在添加后端，请完成后再升级。' : '⏳ Backend setup is running. Update after it finishes.');
+                return true;
+            }
             if (this.selfUpdater) {
                 const status = await this.selfUpdater.readStatus();
                 if (status?.state === 'pending') {

package/dist/core/backend_ui.d.ts

@@ -16,9 +16,10 @@ export interface EngineCustomUiHook {
     renderModelsMenu?(scopeId: string, locale: AppLocale, messageId?: number): Promise<boolean>;
     renderCustomStatus?(scopeId: string, locale: AppLocale): Promise<string | null>;
     renderCustomSetupRows?(scopeId: string, locale: AppLocale): Promise<ChannelInlineKeyboard>;
+    renderBackendMenuRows?(scopeId: string, locale: AppLocale): Promise<ChannelInlineKeyboard>;
     handleCustomCallback?(scopeId: string, data: string, locale: AppLocale, messageId?: number, event?: ChannelCallbackEvent): Promise<boolean>;
     handleCustomCommand?(scopeId: string, command: string, args: string, locale: AppLocale, event?: ChannelTextEvent): Promise<boolean>;
-    handleCustomInbound?(event: ChannelTextEvent, locale: AppLocale): Promise<boolean>;
+    handleCustomInbound?(event: ChannelTextEvent, locale: AppLocale): boolean | Promise<boolean>;
 }
 export interface BackendUi extends EngineCustomUiHook {
     /** Recognize owned buttons even after the user switches to another backend (e.g. pending approvals). */

package/dist/core/orchestrator.js

@@ -660,6 +660,9 @@ export class UnifiedChannelOrchestrator {
                 event.text.trim() || event.attachments.length ? { kind: 'prompt', text: event.text } : { kind: 'ignore' });
         if (addressing.kind === 'ignore')
             return;
+        const serviceInbound = this.serviceUi?.handleCustomInbound?.(event, locale);
+        if (serviceInbound && await serviceInbound)
+            return;
         if (addressing.kind === 'command') {
             const name = addressing.command.name.toLowerCase();
             const args = addressing.command.args.join(' ').trim();
@@ -766,6 +769,8 @@ export class UnifiedChannelOrchestrator {
         const locale = this.store.getChatSettings(scopeId)?.locale ?? 'zh';
         const data = event.data || '';
         const messageId = event.messageId;
+        if (this.serviceUi?.handleCustomCallback && await this.serviceUi.handleCustomCallback(scopeId, data, locale, messageId, event))
+            return;
         if (data.startsWith('engine:stop:')) {
             const status = await this.stopTask(scopeId, data.slice('engine:stop:'.length));
             await this.messaging.answerCallback(event.callbackQueryId, status ? (locale === 'zh' ? '已停止，排队任务保留' : 'Stopped; queued tasks kept') : (locale === 'zh' ? '此任务已结束' : 'This task has ended'));
@@ -1907,6 +1912,9 @@ export class UnifiedChannelOrchestrator {
                 },
             ]);
         });
+        if (this.serviceUi?.renderBackendMenuRows) {
+            keyboard.push(...await this.serviceUi.renderBackendMenuRows(scopeId, locale));
+        }
         keyboard.push([{ text: '◀️ 返回控制面板', callback_data: 'engine:setup:main' }]);
         const text = lines.join('\n');
         if (editMessageId) {
@@ -1947,7 +1955,7 @@ export class UnifiedChannelOrchestrator {
         if (!targetDesc) {
             await this.sendMessage(scopeId, locale === 'zh'
                 ? `❌ 未找到后端: \`${argsString}\`。可用列表: ${backends.map((b) => `\`${b.id}\``).join(', ')}`
-                : `❌ Backend not found: \`${argsString}\`. Available: ${backends.map((b) => `\`${b.id}\``).join(', ')}`);
+                : `❌ Backend not found: \`${argsString}\`. Available: ${backends.map((b) => `\`${b.id}\``).join(', ')}`, await this.serviceUi?.renderBackendMenuRows?.(scopeId, locale));
             return;
         }
         await this.switchBackend(scopeId, targetId, locale);

package/dist/dsh/client.d.ts

@@ -30,7 +30,7 @@ export declare class DshClient extends EventEmitter {
     constructor(options: DshClientOptions, scopeId: string, logger: Logger);
     setAccess(preset: AccessPresetValue): Promise<void>;
     private writeAccess;
-    start(): Promise<void>;
+    start(signal?: AbortSignal): Promise<void>;
     private launch;
     get connected(): boolean;
     get imageSupported(): boolean;

package/dist/dsh/client.js

@@ -41,13 +41,14 @@ export class DshClient extends EventEmitter {
         await fs.writeFile(temporary, preset === 'full-access' ? 'danger-full-access' : preset === 'read-only' ? 'read-only' : 'workspace-write', { mode: 0o600 });
         await fs.rename(temporary, this.policyPath);
     }
-    start() {
+    start(signal) {
+        signal?.throwIfAborted();
         if (this.connection && !this.connection.signal.aborted)
             return Promise.resolve();
-        this.starting ??= this.launch().finally(() => { this.starting = null; });
+        this.starting ??= this.launch(signal).finally(() => { this.starting = null; });
         return this.starting;
     }
-    async launch() {
+    async launch(signal) {
         if (this.stopping)
             await this.stopping;
         if (this.process)
@@ -75,6 +76,7 @@ export class DshClient extends EventEmitter {
             args.unshift(path.resolve(command));
             command = process.execPath;
         }
+        signal?.throwIfAborted();
         const child = spawn(command, args, { cwd, env: { ...process.env, ...(this.options.home ? { DSH_HOME: this.options.home } : {}) }, stdio: 'pipe', windowsHide: true });
         this.process = child;
         this.stderr = '';
@@ -98,12 +100,17 @@ export class DshClient extends EventEmitter {
             this.emit('disconnected');
         });
         const controller = new AbortController();
+        const abortInitialization = () => connection.close(new Error('DSH startup cancelled'));
+        signal?.addEventListener('abort', abortInitialization, { once: true });
+        if (signal?.aborted)
+            abortInitialization();
         let timer;
         const timeout = new Promise((_resolve, reject) => {
             timer = setTimeout(() => { controller.abort(); reject(new Error('DSH initialization timed out')); }, this.options.startupTimeoutMs);
         });
         try {
-            const initialized = await Promise.race([connection.agent.request('initialize', { protocolVersion: PROTOCOL_VERSION, clientCapabilities: {}, clientInfo: { name: 'foxclaw', version: '1' } }, { cancellationSignal: controller.signal }), timeout]);
+            const cancellationSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
+            const initialized = await Promise.race([connection.agent.request('initialize', { protocolVersion: PROTOCOL_VERSION, clientCapabilities: {}, clientInfo: { name: 'foxclaw', version: '1' } }, { cancellationSignal }), timeout]);
             this.capabilities = { image: initialized.agentCapabilities?.promptCapabilities?.image === true, resume: initialized.agentCapabilities?.sessionCapabilities?.resume != null, list: initialized.agentCapabilities?.sessionCapabilities?.list != null };
         }
         catch (error) {
@@ -112,6 +119,7 @@ export class DshClient extends EventEmitter {
         }
         finally {
             clearTimeout(timer);
+            signal?.removeEventListener('abort', abortInitialization);
         }
     }
     get connected() { return this.connection !== null && !this.connection.signal.aborted; }

package/dist/dsh/setup.d.ts

@@ -0,0 +1,3 @@
+import { type BackendSetupDefinition } from '../service/backend_setup.js';
+import type { Logger } from '../logger.js';
+export declare function createDshSetupDefinition(logger: Logger, env?: NodeJS.ProcessEnv, installDir?: string): BackendSetupDefinition;

package/dist/dsh/setup.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { valid } from 'semver';
+import { APP_HOME, parseDshPatches } from '../config.js';
+import { DshClient } from './client.js';
+import { createDshBackend } from './backend.js';
+import { runBackendCommand } from '../service/backend_setup.js';
+export function createDshSetupDefinition(logger, env = process.env, installDir = path.join(APP_HOME, 'backends', 'dsh')) {
+    const managedCli = path.join(installDir, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
+    const options = (candidate) => {
+        const startupTimeoutMs = Number(env.DSH_STARTUP_TIMEOUT_MS || 60000);
+        if (!Number.isSafeInteger(startupTimeoutMs) || startupTimeoutMs <= 0)
+            throw new Error('DSH_STARTUP_TIMEOUT_MS must be a positive integer');
+        return {
+            cliBin: candidate.updates.DSH_CLI_BIN || 'dsh', sourceDir: candidate.updates.DSH_SOURCE_DIR || null,
+            home: env.DSH_HOME || null, profile: env.DSH_PROFILE || 'acp', patches: parseDshPatches(env.DSH_PATCHES),
+            runtimeDir: path.join(APP_HOME, 'runtime', 'dsh'), startupTimeoutMs,
+        };
+    };
+    const fromPath = async (location) => {
+        if (!path.isAbsolute(location) || /[\r\n\0]/.test(location))
+            throw new Error('请提供本机绝对路径 / An absolute local path is required');
+        const target = await fs.realpath(location);
+        const stat = await fs.stat(target);
+        if (stat.isDirectory()) {
+            await fs.access(path.join(target, 'apps', 'cli', 'src', 'bin.ts'));
+            return { label: 'DSH 源码 / source', location: target,
+                updates: { DSH_ENABLED: 'true', DSH_SOURCE_DIR: target, DSH_CLI_BIN: '' } };
+        }
+        if (!stat.isFile())
+            throw new Error('Not a CLI file or source directory');
+        // Keep stable launchers and node_modules links; pnpm's real target embeds a version.
+        const cli = path.resolve(location);
+        await fs.access(cli, /\.[cm]?js$/.test(cli) ? fs.constants.R_OK : fs.constants.X_OK);
+        return { label: 'DSH CLI', location: cli,
+            updates: { DSH_ENABLED: 'true', DSH_SOURCE_DIR: '', DSH_CLI_BIN: cli } };
+    };
+    return {
+        id: 'dsh', name: 'DeepSeek Harness (DSH)', fromPath,
+        async discover() {
+            const commands = (env.PATH || '').split(path.delimiter).filter(Boolean).map(directory => path.join(directory, process.platform === 'win32' ? 'dsh.cmd' : 'dsh'));
+            const locations = [env.DSH_SOURCE_DIR, env.DSH_CLI_BIN, managedCli, ...commands,
+                env.DEFAULT_CWD ? path.join(path.dirname(env.DEFAULT_CWD), 'deepseek-harness') : null,
+                path.join(os.homedir(), 'git', 'deepseek-harness')].filter((location) => Boolean(location));
+            const found = [];
+            for (const location of locations) {
+                try {
+                    const candidate = await fromPath(location);
+                    if (!found.some(previous => previous.location === candidate.location))
+                        found.push(candidate);
+                }
+                catch { /* Keep unavailable paths out of the selectable list. */ }
+            }
+            return found;
+        },
+        async validate(candidate, signal) {
+            const clientOptions = options(candidate);
+            const runtimeDir = await fs.mkdtemp(path.join(os.tmpdir(), 'foxclaw-dsh-check-'));
+            const client = new DshClient({ ...clientOptions, runtimeDir }, `setup:${randomUUID()}`, logger);
+            try {
+                signal.throwIfAborted();
+                await client.setAccess('read-only');
+                signal.throwIfAborted();
+                await client.start(signal);
+                signal.throwIfAborted();
+            }
+            finally {
+                await client.stop();
+                await fs.rm(runtimeDir, { recursive: true, force: true });
+            }
+        },
+        factory: candidate => host => createDshBackend({ ...host.config, dsh: options(candidate) }, host.store, host.logger, host.messaging),
+        async install(signal) {
+            await fs.mkdir(installDir, { recursive: true, mode: 0o700 });
+            const packageFile = path.join(installDir, 'package.json');
+            try {
+                await fs.access(packageFile);
+            }
+            catch {
+                await fs.writeFile(packageFile, JSON.stringify({ name: 'foxclaw-dsh-runtime', private: true }), { mode: 0o600 });
+            }
+            const npm = path.join(path.dirname(process.execPath), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+            const npmCli = process.platform === 'win32'
+                ? path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js')
+                : await fs.realpath(npm);
+            const installEnv = { ...env, PATH: `${path.dirname(process.execPath)}${path.delimiter}${env.PATH || ''}` };
+            const result = await runBackendCommand(process.execPath, [npmCli, 'view', '@deepseek-ai/dsh@latest', 'version', '--json', '--registry=https://registry.npmjs.org', '--prefer-online'], installDir, installEnv, signal, 30000);
+            const version = JSON.parse(result);
+            if (typeof version !== 'string' || !valid(version))
+                throw new Error('Cannot verify official DSH version');
+            await runBackendCommand(process.execPath, [npmCli, 'exec', '--yes', '--package=pnpm@10', '--', 'pnpm', '--config.minimum-release-age=0',
+                'add', '--ignore-scripts', '--registry=https://registry.npmjs.org', `@deepseek-ai/dsh@${version}`], installDir, installEnv, signal);
+            return fromPath(managedCli);
+        },
+    };
+}

package/dist/main.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { RuntimeSupervisor } from './core/runtime_supervisor.js';
+import { BackendSetupManager } from './service/backend_setup.js';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -606,7 +607,7 @@ function truncateStatusLine(value, maxLength) {
     return normalized.length <= maxLength ? normalized : `${normalized.slice(0, Math.max(0, maxLength - 1))}…`;
 }
 async function runServeCli() {
-    const [{ BridgeMessagingRouter }, { TelegramMessagingPort }, { WeixinChannelAdapter }, { WeixinMessagingPort }, { attachIlinkRuntimeFromBridgeLogger }, { loadWeixinAccount }, { Logger }, { BridgeStore }, { TelegramGateway }, { CodexAppClient }, { BridgeSessionCore }, { TelegramChannelAdapter }, { AuthCandidateMirror }, { CrossNodeAuthSync }, { OpencodeTelegramRuntime }, { DshTelegramRuntime }, { createDshBackend }, { UnifiedBridgeCore }, { AntigravityAppClient }, { AntigravityAuthManager, linkAntigravityAuthTokens },] = await Promise.all([
+    const [{ BridgeMessagingRouter }, { TelegramMessagingPort }, { WeixinChannelAdapter }, { WeixinMessagingPort }, { attachIlinkRuntimeFromBridgeLogger }, { loadWeixinAccount }, { Logger }, { BridgeStore }, { TelegramGateway }, { CodexAppClient }, { BridgeSessionCore }, { TelegramChannelAdapter }, { AuthCandidateMirror }, { CrossNodeAuthSync }, { OpencodeTelegramRuntime }, { DshTelegramRuntime }, { createDshBackend }, { createDshSetupDefinition }, { UnifiedBridgeCore }, { AntigravityAppClient }, { AntigravityAuthManager, linkAntigravityAuthTokens },] = await Promise.all([
         import('./channels/bridge_messaging_router.js'),
         import('./channels/telegram/telegram_messaging_port.js'),
         import('./channels/weixin/weixin_channel_adapter.js'),
@@ -624,6 +625,7 @@ async function runServeCli() {
         import('./opencode/runtime.js'),
         import('./dsh/runtime.js'),
         import('./dsh/backend.js'),
+        import('./dsh/setup.js'),
         import('./bridge/unified_bridge.js'),
         import('./antigravity/client.js'),
         import('./antigravity/auth.js'),
@@ -718,6 +720,8 @@ async function runServeCli() {
             codexCliBin: config.codexCliBin,
             agyCliBin: config.antigravityCliBin,
         });
+        const backendSetup = new BackendSetupManager([createDshSetupDefinition(logger)], config.envPath ?? DEFAULT_ENV_PATH, async () => (await selfUpdater.readStatus())?.state !== 'pending');
+        supervisor.register('backend-setup', { stop: () => backendSetup.stop() });
         sharedAntigravityAuth = new AntigravityAuthManager(config.antigravityAuthDir, logger);
         sharedAntigravityApp = new AntigravityAppClient(config.antigravityCliBin, logger);
         if (config.codexCliBin) {
@@ -1001,6 +1005,7 @@ async function runServeCli() {
                 antigravityApp: seed.antigravityApp,
                 antigravityAuth: seed.antigravityAuth,
                 defaultBackendId: seed.defaultBackend,
+                backendSetup,
                 backends: seed.config.dsh ? [createDshBackend(seed.config, store, logger, telegramMessaging)] : [],
                 selfUpdater,
             });

package/dist/service/backend_setup.d.ts

@@ -0,0 +1,72 @@
+import type { AppConfig } from '../config.js';
+import type { BridgeStore } from '../store/database.js';
+import type { Logger } from '../logger.js';
+import type { AppLocale } from '../types.js';
+import type { ChannelPort, ChannelInlineKeyboard } from '../core/channel_port.js';
+import type { ChannelTextEvent } from '../core/channel_events.js';
+import type { BackendDescriptor } from '../core/engine_spi.js';
+export interface BackendSetupHost {
+    config: AppConfig;
+    store: BridgeStore;
+    logger: Logger;
+    messaging: ChannelPort;
+}
+export type BackendFactory = (host: BackendSetupHost) => BackendDescriptor;
+export interface BackendCandidate {
+    label: string;
+    location: string;
+    updates: Record<string, string>;
+}
+export interface BackendSetupDefinition {
+    id: string;
+    name: string;
+    discover(): Promise<BackendCandidate[]>;
+    fromPath(location: string): Promise<BackendCandidate>;
+    validate(candidate: BackendCandidate, signal: AbortSignal): Promise<void>;
+    factory(candidate: BackendCandidate): BackendFactory;
+    install?(signal: AbortSignal): Promise<BackendCandidate>;
+}
+/** One owner for provisioning jobs and config writes across all bots on this service. */
+export declare class BackendSetupManager {
+    private readonly envPath;
+    private readonly canConfigure;
+    readonly definitions: ReadonlyMap<string, BackendSetupDefinition>;
+    private readonly targets;
+    private active;
+    private stopped;
+    constructor(definitions: BackendSetupDefinition[], envPath: string, canConfigure?: () => Promise<boolean>);
+    get busy(): boolean;
+    attach(target: (factory: BackendFactory) => void): () => void;
+    enable(id: string, candidate?: BackendCandidate): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function writeBackendEnv(envPath: string, updates: Record<string, string>): void;
+/** Fixed executable/argument vectors only; bounded lifetime and process-tree cleanup. */
+export declare function runBackendCommand(command: string, args: string[], cwd: string, env: NodeJS.ProcessEnv, signal: AbortSignal, timeoutMs?: number): Promise<string>;
+interface SetupPanelHost {
+    listBackends(): Promise<BackendDescriptor[]>;
+    send(scopeId: string, text: string, keyboard: ChannelInlineKeyboard, messageId?: number): Promise<void>;
+    readPathState?(scopeId: string): string | null;
+    writePathState?(scopeId: string, state: string | null): void;
+}
+/** Per-bot, per-scope menus. Choices never select an execution backend implicitly. */
+export declare class BackendSetupUi {
+    private readonly manager;
+    private readonly host;
+    private readonly choices;
+    private readonly pendingPaths;
+    constructor(manager: BackendSetupManager, host: SetupPanelHost);
+    private clearScope;
+    private choice;
+    rows(locale: AppLocale): ChannelInlineKeyboard;
+    menu(scopeId: string, locale: AppLocale, messageId?: number): Promise<void>;
+    select(scopeId: string, id: string, locale: AppLocale, messageId?: number): Promise<void>;
+    callback(scopeId: string, data: string, locale: AppLocale, messageId?: number): Promise<boolean>;
+    command(scopeId: string, command: string, args: string, locale: AppLocale): Promise<boolean>;
+    inbound(event: ChannelTextEvent, locale: AppLocale): boolean | Promise<boolean>;
+    private consumePath;
+    private enable;
+    stop(): void;
+}
+export declare function safeSetupError(error: unknown): string;
+export {};

package/dist/service/backend_setup.js

@@ -0,0 +1,319 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+/** One owner for provisioning jobs and config writes across all bots on this service. */
+export class BackendSetupManager {
+    envPath;
+    canConfigure;
+    definitions;
+    targets = new Set();
+    active = null;
+    stopped = false;
+    constructor(definitions, envPath, canConfigure = async () => true) {
+        this.envPath = envPath;
+        this.canConfigure = canConfigure;
+        this.definitions = new Map(definitions.map(definition => [definition.id, definition]));
+    }
+    get busy() { return this.active !== null; }
+    attach(target) {
+        if (this.stopped)
+            throw new Error('Backend setup is stopped');
+        this.targets.add(target);
+        return () => this.targets.delete(target);
+    }
+    async enable(id, candidate) {
+        if (this.stopped)
+            throw new Error('Backend setup is stopped');
+        if (this.active)
+            throw new Error('Another backend is being configured');
+        const definition = this.definitions.get(id);
+        if (!definition)
+            throw new Error('Unknown backend');
+        const controller = new AbortController();
+        // Claim before the first await: two bots cannot start overlapping installations.
+        let finish;
+        const done = new Promise(resolve => { finish = resolve; });
+        this.active = { controller, done };
+        try {
+            if (!await this.canConfigure())
+                throw new Error('A service update is running; try again when it finishes');
+            controller.signal.throwIfAborted();
+            const selected = candidate ?? await definition.install?.(controller.signal);
+            if (!selected)
+                throw new Error('This backend requires a local installation');
+            await definition.validate(selected, controller.signal);
+            controller.signal.throwIfAborted();
+            const factory = definition.factory(selected);
+            writeBackendEnv(this.envPath, selected.updates);
+            for (const target of this.targets)
+                target(factory);
+        }
+        finally {
+            this.active = null;
+            finish();
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        this.active?.controller.abort();
+        await this.active?.done;
+        this.targets.clear();
+    }
+}
+export function writeBackendEnv(envPath, updates) {
+    // Preserve symlink-backed configuration and every unrelated setting/comment.
+    const target = fs.existsSync(envPath) ? fs.realpathSync(envPath) : envPath;
+    let text = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
+    for (const [key, value] of Object.entries(updates)) {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(key) || /[\r\n\0]/.test(value))
+            throw new Error('Invalid backend configuration');
+        const line = `${key}=${JSON.stringify(value)}`;
+        const pattern = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=.*$`, 'gm');
+        if (pattern.test(text))
+            text = text.replace(pattern, () => line);
+        else
+            text = `${text.trimEnd()}\n${line}\n`;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, text, { mode: 0o600 });
+        fs.renameSync(temporary, target);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+/** Fixed executable/argument vectors only; bounded lifetime and process-tree cleanup. */
+export async function runBackendCommand(command, args, cwd, env, signal, timeoutMs = 5 * 60_000) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+            detached: process.platform !== 'win32' });
+        let stdout = '';
+        let stderr = '';
+        let cancelled = false;
+        let escalation;
+        const kill = (force) => {
+            if (!child.pid)
+                return;
+            try {
+                if (process.platform === 'win32') {
+                    spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' }).on('error', () => { });
+                }
+                else
+                    process.kill(-child.pid, force ? 'SIGKILL' : 'SIGTERM');
+            }
+            catch { /* Already exited. */ }
+        };
+        const cancel = () => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            kill(false);
+            escalation = setTimeout(() => kill(true), 3000);
+        };
+        const timeout = setTimeout(cancel, timeoutMs);
+        signal.addEventListener('abort', cancel, { once: true });
+        child.stdout.on('data', (data) => { stdout = (stdout + data.toString()).slice(-8000); });
+        child.stderr.on('data', (data) => { stderr = (stderr + data.toString()).slice(-8000); });
+        const cleanup = () => {
+            clearTimeout(timeout);
+            clearTimeout(escalation);
+            signal.removeEventListener('abort', cancel);
+        };
+        child.once('error', error => { cleanup(); reject(error); });
+        child.once('close', code => {
+            if (cancelled)
+                kill(true);
+            cleanup();
+            if (cancelled)
+                reject(new Error(signal.aborted ? 'Backend setup cancelled' : 'Backend setup timed out'));
+            else if (code !== 0)
+                reject(new Error(`Backend command failed (${code}): ${(stderr || stdout).slice(-2000)}`));
+            else
+                resolve(stdout.trim());
+        });
+    });
+}
+/** Per-bot, per-scope menus. Choices never select an execution backend implicitly. */
+export class BackendSetupUi {
+    manager;
+    host;
+    choices = new Map();
+    pendingPaths = new Map();
+    constructor(manager, host) {
+        this.manager = manager;
+        this.host = host;
+    }
+    clearScope(scopeId) {
+        this.pendingPaths.delete(scopeId);
+        this.host.writePathState?.(scopeId, null);
+        for (const [key, choice] of this.choices)
+            if (choice.scopeId === scopeId)
+                this.choices.delete(key);
+    }
+    choice(scopeId, backendId, candidate) {
+        for (const [key, choice] of this.choices)
+            if (choice.expires < Date.now())
+                this.choices.delete(key);
+        const key = randomUUID();
+        this.choices.set(key, { scopeId, backendId, candidate, expires: Date.now() + 5 * 60_000 });
+        return key;
+    }
+    rows(locale) {
+        return [[{ text: locale === 'zh' ? '➕ 添加后端' : '➕ Add backend', callback_data: 'backend-setup:list' }]];
+    }
+    async menu(scopeId, locale, messageId) {
+        this.clearScope(scopeId);
+        const installed = new Set((await this.host.listBackends()).map(backend => backend.engineType));
+        const definitions = [...this.manager.definitions.values()].filter(definition => !installed.has(definition.id));
+        const keyboard = definitions.map(definition => [{ text: definition.name, callback_data: `backend-setup:select:${definition.id}` }]);
+        keyboard.push([{ text: locale === 'zh' ? '◀️ 返回后端列表' : '◀️ Back to backends', callback_data: 'engine:setup:backend' }]);
+        await this.host.send(scopeId, locale === 'zh'
+            ? `➕ **添加后端**\n\n${definitions.length ? '选择要接入的后端。会保留当前会话，接入后可自行切换。' : '支持从面板接入的后端均已添加。'}`
+            : `➕ **Add backend**\n\n${definitions.length ? 'Choose a backend. Your current session stays selected; switch after setup.' : 'All backends supported by this setup panel are already added.'}`, keyboard, messageId);
+    }
+    async select(scopeId, id, locale, messageId) {
+        const definition = this.manager.definitions.get(id);
+        if (!definition)
+            throw new Error('Unknown backend');
+        this.clearScope(scopeId);
+        const candidates = await definition.discover();
+        const keyboard = candidates.map(candidate => [{
+                text: `${locale === 'zh' ? '接入' : 'Use'} · ${candidate.label}`,
+                callback_data: `backend-setup:use:${this.choice(scopeId, id, candidate)}`,
+            }]);
+        if (definition.install)
+            keyboard.push([{ text: locale === 'zh' ? '下载官方 CLI 并接入' : 'Install official CLI and enable',
+                    callback_data: `backend-setup:install:${this.choice(scopeId, id)}` }]);
+        keyboard.push([{ text: locale === 'zh' ? '指定 CLI / 源码路径' : 'Specify CLI / source path', callback_data: `backend-setup:path:${id}` }]);
+        keyboard.push(...this.rows(locale));
+        const locations = candidates.map(candidate => `• ${candidate.label}: \`${candidate.location}\``).join('\n');
+        await this.host.send(scopeId, `➕ **${definition.name}**\n\n${locations || (locale === 'zh' ? '尚未找到本机安装。' : 'No local installation found.')}\n\n${locale === 'zh' ? '接入前检查启动能力；官方 CLI 安装在 FoxClaw 的独立目录，沿用该后端的本机凭据。无需新增 Bot，也不会自动切换当前会话。' : 'Startup is checked before enabling. Official CLIs use a dedicated FoxClaw directory and existing backend credentials. No extra bot or automatic session switch.'}`, keyboard, messageId);
+    }
+    async callback(scopeId, data, locale, messageId) {
+        if (!data.startsWith('backend-setup:')) {
+            this.clearScope(scopeId);
+            return false;
+        }
+        const [, action, value] = data.split(':');
+        if (action === 'list')
+            await this.menu(scopeId, locale, messageId);
+        else if (action === 'select')
+            await this.select(scopeId, value, locale, messageId);
+        else if (action === 'path') {
+            if (!this.manager.definitions.has(value))
+                throw new Error('Unknown backend');
+            this.clearScope(scopeId);
+            const pending = { backendId: value, expires: Date.now() + 5 * 60_000 };
+            this.pendingPaths.set(scopeId, pending);
+            this.host.writePathState?.(scopeId, JSON.stringify(pending));
+            await this.host.send(scopeId, locale === 'zh' ? '发送本机 CLI 文件或源码目录的绝对路径。\n/backend cancel 取消' : 'Send an absolute local CLI or source path.\n/backend cancel to cancel.', this.rows(locale), messageId);
+        }
+        else if (action === 'use' || action === 'install') {
+            const choice = this.choices.get(value);
+            if (!choice || choice.scopeId !== scopeId || choice.expires < Date.now() || (action === 'use') !== Boolean(choice.candidate)) {
+                await this.host.send(scopeId, locale === 'zh' ? '此操作已过期，请重新选择后端。' : 'This choice expired. Select the backend again.', this.rows(locale));
+                return true;
+            }
+            this.clearScope(scopeId);
+            await this.enable(scopeId, choice.backendId, choice.candidate, locale, messageId);
+        }
+        return true;
+    }
+    async command(scopeId, command, args, locale) {
+        this.clearScope(scopeId);
+        if (!['backend', 'backends', 'engine', 'engines'].includes(command))
+            return false;
+        if (args === 'cancel') {
+            this.pendingPaths.delete(scopeId);
+            await this.menu(scopeId, locale);
+            return true;
+        }
+        const match = /^add(?:\s+([a-z][a-z0-9-]*))?$/.exec(args);
+        if (!match)
+            return false;
+        try {
+            if (match[1])
+                await this.select(scopeId, match[1], locale);
+            else
+                await this.menu(scopeId, locale);
+        }
+        catch (error) {
+            await this.host.send(scopeId, `❌ ${safeSetupError(error)}`, this.rows(locale));
+        }
+        return true;
+    }
+    inbound(event, locale) {
+        let pending = this.pendingPaths.get(event.scopeId);
+        if (!pending) {
+            const saved = this.host.readPathState?.(event.scopeId);
+            if (saved) {
+                try {
+                    const parsed = JSON.parse(saved);
+                    if (typeof parsed.backendId === 'string' && typeof parsed.expires === 'number' && this.manager.definitions.has(parsed.backendId)) {
+                        pending = { backendId: parsed.backendId, expires: parsed.expires };
+                        this.pendingPaths.set(event.scopeId, pending);
+                    }
+                }
+                catch { /* Invalid saved interaction is not used as an executable choice. */ }
+            }
+        }
+        if (!pending)
+            return false;
+        // POSIX paths resemble slash commands. Consume them before command dispatch,
+        // while actual commands such as /new and /backend cancel still work normally.
+        if (/^\/[\w]+(?:@[\w]+)?(?:\s|$)/.test(event.text.trim())) {
+            this.clearScope(event.scopeId);
+            return false;
+        }
+        return this.consumePath(event, pending, locale);
+    }
+    async consumePath(event, pending, locale) {
+        if (pending.expires < Date.now()) {
+            await this.host.send(event.scopeId, locale === 'zh' ? '路径输入已过期，请重新打开添加面板，或发送 /backend cancel 返回聊天。' : 'Path input expired. Reopen setup or send /backend cancel to return to chat.', this.rows(locale));
+            return true;
+        }
+        try {
+            const definition = this.manager.definitions.get(pending.backendId);
+            const candidate = await definition.fromPath(event.text.trim());
+            if (this.pendingPaths.get(event.scopeId) !== pending)
+                return true;
+            const key = this.choice(event.scopeId, pending.backendId, candidate);
+            await this.host.send(event.scopeId, `${definition.name}\n\`${candidate.location}\``, [[{
+                        text: locale === 'zh' ? '检查并接入' : 'Validate and enable', callback_data: `backend-setup:use:${key}`,
+                    }], ...this.rows(locale)]);
+        }
+        catch (error) {
+            await this.host.send(event.scopeId, safeSetupError(error), this.rows(locale));
+        }
+        return true;
+    }
+    async enable(scopeId, id, candidate, locale, messageId) {
+        if ((await this.host.listBackends()).some(backend => backend.engineType === id)) {
+            await this.menu(scopeId, locale, messageId);
+            return;
+        }
+        await this.host.send(scopeId, locale === 'zh' ? '⏳ 正在准备后端并检查启动能力…' : '⏳ Preparing backend and checking startup…', [], messageId);
+        try {
+            await this.manager.enable(id, candidate);
+            await this.host.send(scopeId, locale === 'zh' ? '✅ 后端已接入，配置已保存。当前会话继续使用原后端。' : '✅ Backend enabled and configuration saved. Your current session keeps its backend.', [[{
+                        text: locale === 'zh' ? '切换至新后端' : 'Switch to this backend', callback_data: `engine:backend:${id}`,
+                    }], ...this.rows(locale)], messageId);
+        }
+        catch (error) {
+            await this.host.send(scopeId, `❌ ${safeSetupError(error)}`, this.rows(locale), messageId);
+        }
+    }
+    stop() { this.choices.clear(); this.pendingPaths.clear(); }
+}
+export function safeSetupError(error) {
+    let message = error instanceof Error ? error.message : String(error);
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value && value.length >= 8 && /KEY|TOKEN|SECRET|PASSWORD/.test(key))
+            message = message.split(value).join('[redacted]');
+    }
+    return message.slice(-1800);
+}

package/dist/store/database.d.ts

@@ -161,6 +161,8 @@ export declare class BridgeStore {
     updateGuidedPlanSessionMessage(sessionId: string, messageId: number): void;
     updateGuidedPlanSessionState(sessionId: string, state: GuidedPlanSessionState): void;
     insertAudit(direction: 'inbound' | 'outbound', chatId: string, eventType: string, summary: string): void;
+    getServiceInteraction(scopeId: string, namespace: string): string | null;
+    setServiceInteraction(scopeId: string, namespace: string, payload: string | null): void;
     close(): void;
     private mapApproval;
     private mapPendingUserInput;

package/dist/store/database.js

@@ -14,6 +14,12 @@ export class BridgeStore {
         this.taskJournal = new TaskJournal(this.db);
         this.channelInbox = new ChannelInbox(this.db);
         this.db.exec(`
+      CREATE TABLE IF NOT EXISTS service_interactions (
+        scope_id TEXT NOT NULL,
+        namespace TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        PRIMARY KEY (scope_id, namespace)
+      );
       CREATE TABLE IF NOT EXISTS telegram_offsets (
         bot_key TEXT PRIMARY KEY,
         update_id INTEGER NOT NULL
@@ -893,6 +899,18 @@ export class BridgeStore {
     insertAudit(direction, chatId, eventType, summary) {
         this.db.prepare('INSERT INTO audit_logs (direction, chat_id, event_type, summary, created_at) VALUES (?, ?, ?, ?, ?)').run(direction, chatId, eventType, summary, Date.now());
     }
+    getServiceInteraction(scopeId, namespace) {
+        const row = this.db.prepare('SELECT payload FROM service_interactions WHERE scope_id = ? AND namespace = ?').get(scopeId, namespace);
+        return row ? String(row.payload) : null;
+    }
+    setServiceInteraction(scopeId, namespace, payload) {
+        if (payload === null) {
+            this.db.prepare('DELETE FROM service_interactions WHERE scope_id = ? AND namespace = ?').run(scopeId, namespace);
+        }
+        else {
+            this.db.prepare('INSERT INTO service_interactions (scope_id, namespace, payload) VALUES (?, ?, ?) ON CONFLICT(scope_id, namespace) DO UPDATE SET payload = excluded.payload').run(scopeId, namespace, payload);
+        }
+    }
     close() {
         this.db.close();
     }

package/docs/dsh.md

@@ -4,6 +4,14 @@ FoxClaw launches DSH's shipped `acp` profile and reuses Telegram progress, tool
 
 ## Existing bot
 
+Open Telegram `/setup` → backend list → **Add backend** and select DSH, or send `/backend add dsh`:
+
+- Use a discovered local CLI / source tree, or supply an absolute local path.
+- If none is installed, choose “Install official CLI and enable”. FoxClaw uses pnpm to install official `@deepseek-ai/dsh` under `~/.foxclaw/backends/dsh`, leaving global CLIs unchanged.
+- After checking startup, save configuration and register DSH on all unified Codex / Antigravity bots on this machine without restarting. Existing tasks, sessions and selected backends stay unchanged. Switch explicitly using the completion button.
+
+Model accounts and API keys use DSH's existing local configuration. Failed installation or startup checks do not enable the backend; the panel shows the error and lets you retry or choose another local path. `/backend cancel` or another command exits path input.
+
 Add to FoxClaw's `.env`:
 
 ```dotenv
@@ -80,4 +88,4 @@ DSH_TELEMETRY_DISABLED=1 node --test --import tsx src/dsh/source.integration.tes
 
 This uses temporary DSH home/session directories and verifies model/reasoning selection, native permission logs, resume, tools, and cancellation without paid model calls. It is skipped when the source path is unset.
 
-Run `npm run build` first and add `FOXCLAW_DSH_TEST_BUILT=1` to verify the compiled backend and packaged permission plugin.
+Run `pnpm build` first and add `FOXCLAW_DSH_TEST_BUILT=1` to verify the compiled backend and packaged permission plugin.

package/docs/zh/dsh.md

@@ -4,6 +4,14 @@ FoxClaw 直接启动 DSH 的 `acp` profile，复用 Telegram 的任务进度、
 
 ## 接入现有 Bot
 
+也可以直接在 Telegram 的 `/setup` → 后端列表 → **添加后端** 中选择 DSH，或发送 `/backend add dsh`：
+
+- 接入检测到的本机 CLI / 源码，或发送它的绝对路径。
+- 没有本机安装时，点击“下载官方 CLI 并接入”。FoxClaw 使用 pnpm 在 `~/.foxclaw/backends/dsh` 安装官方 `@deepseek-ai/dsh`，不改动全局 CLI。
+- 启动检查通过后保存配置，并直接接入本机所有统一 Codex / Antigravity Bot，无需重启。当前任务、会话和后端保持原状；点击“切换至新后端”后才切换。
+
+DSH 模型账号和 API Key 沿用其本机配置。安装或启动检查失败时不会启用后端；面板显示原因，可以重新选择本机路径或重试。`/backend cancel` 取消路径输入，其他命令也会退出路径输入。
+
 在 FoxClaw 的 `.env` 中增加：
 
 ```dotenv
@@ -80,4 +88,4 @@ DSH_TELEMETRY_DISABLED=1 node --test --import tsx src/dsh/source.integration.tes
 
 联调使用临时 home 和会话目录，验证模型/推理设置、原生权限日志、恢复、工具事件和取消。未配置源码路径时跳过此项。
 
-先执行 `npm run build`，再追加 `FOXCLAW_DSH_TEST_BUILT=1` 可验证编译后的后端和随包发布的权限插件。
+先执行 `pnpm build`，再追加 `FOXCLAW_DSH_TEST_BUILT=1` 可验证编译后的后端和随包发布的权限插件。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.13.1",
+  "version": "0.13.2",
   "description": "Foxden local execution claw for controlling Codex, OpenCode, Antigravity, and DeepSeek Harness from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",