@foxden-app/foxclaw 0.11.1 → 0.13.0

package/dist/telegram/media.js

@@ -1,180 +1 @@
-import path from 'node:path';
-export const TELEGRAM_INBOX_DIR = '.telegram-inbox';
-export const TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES = 20 * 1024 * 1024;
-const FALLBACK_EXTENSION_BY_KIND = {
-    photo: '.jpg',
-    document: '',
-    audio: '.mp3',
-    voice: '.ogg',
-    video: '.mp4',
-    animation: '.mp4',
-    sticker: '.webp',
-    videoNote: '.mp4',
-};
-const MIME_EXTENSION_MAP = {
-    'application/gzip': '.gz',
-    'application/json': '.json',
-    'application/pdf': '.pdf',
-    'application/zip': '.zip',
-    'audio/mpeg': '.mp3',
-    'audio/mp4': '.m4a',
-    'audio/ogg': '.ogg',
-    'audio/wav': '.wav',
-    'image/gif': '.gif',
-    'image/jpeg': '.jpg',
-    'image/png': '.png',
-    'image/webp': '.webp',
-    'text/csv': '.csv',
-    'text/html': '.html',
-    'text/markdown': '.md',
-    'text/plain': '.txt',
-    'video/mp4': '.mp4',
-    'video/quicktime': '.mov',
-};
-export function isNativeImageAttachment(attachment) {
-    if (attachment.kind === 'photo') {
-        return true;
-    }
-    if (attachment.kind === 'sticker') {
-        return !attachment.isAnimated && !attachment.isVideo;
-    }
-    if (attachment.kind !== 'document') {
-        return false;
-    }
-    const lowerMime = attachment.mimeType?.toLowerCase() ?? '';
-    if (lowerMime === 'image/jpeg' || lowerMime === 'image/png' || lowerMime === 'image/webp' || lowerMime === 'image/gif') {
-        return true;
-    }
-    const extension = extensionFromName(attachment.fileName);
-    return extension === '.jpg' || extension === '.jpeg' || extension === '.png' || extension === '.webp' || extension === '.gif';
-}
-export function planAttachmentStoragePath(cwd, threadId, attachment, remoteFilePath, now = new Date()) {
-    const dateSegment = now.toISOString().slice(0, 10);
-    const threadSegment = sanitizePathSegment(threadId);
-    const timestamp = now.toISOString().slice(0, 19).replace(/[-:]/g, '').replace('T', '-');
-    const resolvedFileName = resolveAttachmentFileName(attachment, remoteFilePath);
-    const uniquePrefix = `${timestamp}-${sanitizePathSegment(attachment.fileUniqueId).slice(0, 16)}`;
-    const joinedName = truncateFileName(`${uniquePrefix}-${resolvedFileName}`, 160);
-    const relativePath = path.join(TELEGRAM_INBOX_DIR, dateSegment, threadSegment, joinedName);
-    return {
-        fileName: resolvedFileName,
-        localPath: path.resolve(cwd, relativePath),
-        relativePath,
-    };
-}
-export function buildAttachmentPrompt(userText, attachments) {
-    const normalizedText = userText.trim();
-    const lines = [];
-    if (normalizedText) {
-        lines.push(normalizedText, '');
-    }
-    else {
-        lines.push('User sent Telegram attachments without a caption.', '');
-    }
-    lines.push('Telegram attachments:');
-    attachments.forEach((attachment, index) => {
-        lines.push(`${index + 1}. ${describeAttachment(attachment)}`);
-        lines.push(`   filename: ${attachment.fileName}`);
-        lines.push(`   path: ${attachment.localPath}`);
-        if (attachment.mimeType)
-            lines.push(`   mime: ${attachment.mimeType}`);
-        if (attachment.fileSize !== null)
-            lines.push(`   size_bytes: ${attachment.fileSize}`);
-        if (attachment.width !== null && attachment.height !== null) {
-            lines.push(`   dimensions: ${attachment.width}x${attachment.height}`);
-        }
-        if (attachment.durationSeconds !== null) {
-            lines.push(`   duration_seconds: ${attachment.durationSeconds}`);
-        }
-        if (attachment.nativeImage) {
-            lines.push('   attached_as: localImage');
-        }
-    });
-    lines.push('', 'Use the local file paths above when you inspect these attachments.');
-    return lines.join('\n');
-}
-export function summarizeTelegramInput(text, attachments) {
-    const lines = [];
-    const normalizedText = text.trim();
-    if (normalizedText) {
-        lines.push(normalizedText);
-    }
-    if (attachments.length > 0) {
-        lines.push(`[attachments: ${attachments.map((attachment) => `${attachment.kind}:${attachment.fileName ?? attachment.fileUniqueId}`).join(', ')}]`);
-    }
-    return truncateSummary(lines.join(' '), 500);
-}
-function resolveAttachmentFileName(attachment, remoteFilePath) {
-    const providedName = attachment.fileName ? path.basename(attachment.fileName) : '';
-    const remoteName = remoteFilePath ? path.basename(remoteFilePath) : '';
-    const baseCandidate = providedName || remoteName || `${attachment.kind}-${attachment.fileUniqueId}`;
-    const sanitizedBase = sanitizeFileName(baseCandidate);
-    const extension = extensionFromName(sanitizedBase)
-        || extensionFromName(remoteName)
-        || extensionFromMimeType(attachment.mimeType)
-        || fallbackExtensionByKind(attachment.kind);
-    if (!extension) {
-        return sanitizedBase;
-    }
-    const withoutExtension = sanitizedBase.slice(0, sanitizedBase.length - extensionFromName(sanitizedBase).length) || `${attachment.kind}-${attachment.fileUniqueId}`;
-    return truncateFileName(`${withoutExtension}${extension}`, 120);
-}
-function describeAttachment(attachment) {
-    switch (attachment.kind) {
-        case 'photo':
-            return 'photo';
-        case 'document':
-            return 'document';
-        case 'audio':
-            return 'audio file';
-        case 'voice':
-            return 'voice message';
-        case 'video':
-            return 'video';
-        case 'animation':
-            return 'animation';
-        case 'sticker':
-            return attachment.isAnimated || attachment.isVideo ? 'animated sticker' : 'sticker';
-        case 'videoNote':
-            return 'video note';
-    }
-}
-function sanitizeFileName(fileName) {
-    const trimmed = fileName.trim().replace(/[\\/]+/g, '-');
-    const sanitized = trimmed
-        .replace(/[^\w.\-()+@]+/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^\.+/, '')
-        .replace(/^-+/, '')
-        .replace(/[.-]+$/, '');
-    return sanitized || 'attachment';
-}
-function sanitizePathSegment(value) {
-    return value.replace(/[^\w.-]+/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '') || 'thread';
-}
-function extensionFromMimeType(mimeType) {
-    if (!mimeType)
-        return '';
-    return MIME_EXTENSION_MAP[mimeType.toLowerCase()] ?? '';
-}
-function extensionFromName(fileName) {
-    if (!fileName)
-        return '';
-    const extension = path.extname(fileName).toLowerCase();
-    return extension === '.' ? '' : extension;
-}
-function truncateFileName(fileName, maxLength) {
-    if (fileName.length <= maxLength)
-        return fileName;
-    const extension = extensionFromName(fileName);
-    const base = extension ? fileName.slice(0, -extension.length) : fileName;
-    return `${base.slice(0, Math.max(1, maxLength - extension.length))}${extension}`;
-}
-function truncateSummary(text, maxLength) {
-    if (text.length <= maxLength)
-        return text;
-    return `${text.slice(0, maxLength - 3)}...`;
-}
-function fallbackExtensionByKind(kind) {
-    return FALLBACK_EXTENSION_BY_KIND[kind] ?? '';
-}
+export { ATTACHMENT_INBOX_DIR as TELEGRAM_INBOX_DIR, DEFAULT_REMOTE_DOWNLOAD_LIMIT_BYTES as TELEGRAM_BOT_API_DOWNLOAD_LIMIT_BYTES, isNativeImageAttachment, planAttachmentStoragePath, buildAttachmentPrompt, summarizeInput as summarizeTelegramInput } from '../core/attachment_files.js';

package/dist/telegram/task_preview.d.ts

@@ -0,0 +1,13 @@
+import type { TelegramGateway } from './gateway.js';
+/** Owns live drafts and fallback cards; draft ids are never persistent message ids. */
+export declare class TelegramTaskPreviews {
+    private readonly gateway;
+    private readonly previews;
+    private readonly draftIds;
+    constructor(gateway: TelegramGateway);
+    private keyboard;
+    private sendCard;
+    begin(scopeId: string, taskId: string, text: string, reuseMessageId?: number): Promise<number>;
+    update(scopeId: string, taskId: string, messageId: number, html: string): Promise<number>;
+    end(scopeId: string, taskId: string): Promise<void>;
+}

package/dist/telegram/task_preview.js

@@ -0,0 +1,92 @@
+import { randomInt } from 'node:crypto';
+import { parseTelegramTargetFromBridgeScope } from '../core/bridge_scope.js';
+import { telegramRichHtml } from './rich.js';
+import { renderTelegramMarkdownRichHtml } from './rich_markdown.js';
+/** Owns live drafts and fallback cards; draft ids are never persistent message ids. */
+export class TelegramTaskPreviews {
+    gateway;
+    previews = new Map();
+    draftIds = new Set();
+    constructor(gateway) {
+        this.gateway = gateway;
+    }
+    keyboard(taskId) { return [[{ text: '🛑 停止 / Stop', callback_data: `engine:stop:${taskId}` }]]; }
+    async sendCard(scopeId, taskId, html) {
+        const target = parseTelegramTargetFromBridgeScope(scopeId);
+        try {
+            return await this.gateway.sendRichMessage(target.chatId, telegramRichHtml(html), this.keyboard(taskId), target.topicId);
+        }
+        catch {
+            return this.gateway.sendHtmlMessage(target.chatId, html.replace(/<\/?p>/g, ''), this.keyboard(taskId), target.topicId);
+        }
+    }
+    async begin(scopeId, taskId, text, reuseMessageId = 0) {
+        const target = parseTelegramTargetFromBridgeScope(scopeId);
+        const html = renderTelegramMarkdownRichHtml(text);
+        const preview = { scopeId, draftId: null, messageId: reuseMessageId };
+        this.previews.set(taskId, preview);
+        if (reuseMessageId > 0) {
+            await this.gateway.editRichMessage(target.chatId, reuseMessageId, telegramRichHtml(html), this.keyboard(taskId));
+            return reuseMessageId;
+        }
+        if (/^[1-9]\d*$/.test(target.chatId)) {
+            let draftId = randomInt(1, 2 ** 31);
+            while (this.draftIds.has(draftId))
+                draftId = randomInt(1, 2 ** 31);
+            this.draftIds.add(draftId);
+            preview.draftId = draftId;
+            this.gateway.registerGeneration(draftId, scopeId, taskId, target.chatId, target.topicId);
+            try {
+                await this.gateway.sendRichMessageDraft(target.chatId, draftId, telegramRichHtml(html), target.topicId, true);
+                return 0;
+            }
+            catch {
+                this.gateway.releaseGeneration(draftId);
+                this.draftIds.delete(draftId);
+                preview.draftId = null;
+            }
+        }
+        preview.messageId = await this.sendCard(scopeId, taskId, html);
+        return preview.messageId;
+    }
+    async update(scopeId, taskId, messageId, html) {
+        const preview = this.previews.get(taskId);
+        if (!preview || preview.scopeId !== scopeId)
+            return messageId;
+        const target = parseTelegramTargetFromBridgeScope(scopeId);
+        if (preview.draftId !== null) {
+            try {
+                await this.gateway.sendRichMessageDraft(target.chatId, preview.draftId, telegramRichHtml(html), target.topicId, true);
+                return 0;
+            }
+            catch {
+                const draftId = preview.draftId;
+                this.gateway.releaseGeneration(draftId);
+                this.draftIds.delete(draftId);
+                preview.draftId = null;
+                await this.gateway.sendMessageDraft(target.chatId, draftId, '', target.topicId).catch(() => { });
+                preview.messageId = await this.sendCard(scopeId, taskId, html);
+                return preview.messageId;
+            }
+        }
+        try {
+            await this.gateway.editRichMessage(target.chatId, preview.messageId, telegramRichHtml(html), this.keyboard(taskId));
+        }
+        catch {
+            await this.gateway.editHtmlMessage(target.chatId, preview.messageId, html, this.keyboard(taskId));
+        }
+        return preview.messageId;
+    }
+    async end(scopeId, taskId) {
+        const preview = this.previews.get(taskId);
+        if (!preview || preview.scopeId !== scopeId)
+            return;
+        this.previews.delete(taskId);
+        if (preview.draftId !== null) {
+            this.gateway.releaseGeneration(preview.draftId);
+            this.draftIds.delete(preview.draftId);
+            const target = parseTelegramTargetFromBridgeScope(scopeId);
+            await this.gateway.sendMessageDraft(target.chatId, preview.draftId, '', target.topicId).catch(() => { });
+        }
+    }
+}

package/dist/telegram/task_result.d.ts

@@ -0,0 +1,2 @@
+/** Only the generated fold formatting is accepted; arbitrary model HTML remains escaped. */
+export declare function telegramTaskResult(content: string): import("./rich.js").TelegramInputRichMessage;

package/dist/telegram/task_result.js

@@ -0,0 +1,12 @@
+import { telegramRichHtml, telegramRichMarkdown } from './rich.js';
+import { renderTelegramMarkdownRichHtml } from './rich_markdown.js';
+/** Only the generated fold formatting is accepted; arbitrary model HTML remains escaped. */
+export function telegramTaskResult(content) {
+    const folded = /^(<blockquote expandable>[\s\S]*?<\/blockquote>)(?:\s*|$)/.exec(content);
+    if (!folded)
+        return telegramRichMarkdown(content, { skipEntityDetection: true });
+    const response = content.slice(folded[0].length);
+    const summary = folded[1].replace(/<[^>]*>/g, tag => /^(?:<\/?(?:b|i|code)>|<blockquote expandable>|<\/blockquote>)$/.test(tag)
+        ? tag : tag.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'));
+    return telegramRichHtml(`${response.trim() ? renderTelegramMarkdownRichHtml(response) : ''}\n${summary}`, { skipEntityDetection: true });
+}

package/dist/telegram/text.d.ts

@@ -2,6 +2,6 @@ export declare const TELEGRAM_MESSAGE_LIMIT = 4000;
 export declare const TELEGRAM_STREAM_MESSAGE_LIMIT = 1200;
 export declare const TELEGRAM_DRAFT_LIMIT = 4000;
 export declare function sanitizeTelegramPreview(text: string): string;
-export declare function chunkTelegramMessage(text: string, limit?: number, fallbackText?: string): string[];
+export { chunkMessage as chunkTelegramMessage } from '../core/message_text.js';
 export declare function chunkTelegramStreamMessage(text: string, limit?: number): string[];
 export declare function clipTelegramDraftMessage(text: string, fallbackText?: string): string;

package/dist/telegram/text.js

@@ -8,33 +8,8 @@ export function sanitizeTelegramPreview(text) {
         ? `${text.slice(0, TELEGRAM_MESSAGE_LIMIT - 3)}...`
         : text;
 }
-export function chunkTelegramMessage(text, limit = TELEGRAM_MESSAGE_LIMIT, fallbackText = 'Completed.') {
-    const source = text.trim() ? text : fallbackText;
-    if (!source) {
-        return [];
-    }
-    if (source.length <= limit) {
-        return [source];
-    }
-    const chunks = [];
-    let start = 0;
-    while (start < source.length) {
-        const remaining = source.length - start;
-        if (remaining <= limit) {
-            chunks.push(source.slice(start));
-            break;
-        }
-        const tentativeEnd = start + limit;
-        const window = source.slice(start, tentativeEnd);
-        const splitAt = Math.max(window.lastIndexOf('\n\n'), window.lastIndexOf('\n'));
-        const end = splitAt >= Math.floor(limit / 2)
-            ? start + splitAt + 1
-            : tentativeEnd;
-        chunks.push(source.slice(start, end));
-        start = end;
-    }
-    return chunks.filter(chunk => chunk.length > 0);
-}
+export { chunkMessage as chunkTelegramMessage } from '../core/message_text.js';
+import { chunkMessage as chunkTelegramMessage } from '../core/message_text.js';
 export function chunkTelegramStreamMessage(text, limit = TELEGRAM_STREAM_MESSAGE_LIMIT) {
     return chunkTelegramMessage(text, limit, '');
 }

package/dist/types.d.ts

@@ -17,7 +17,7 @@ export interface ChatSessionSettings {
     /** Bridge scope id (e.g. `telegram:…`). */
     chatId: string;
     model: string | null;
-    reasoningEffort: ReasoningEffortValue | null;
+    reasoningEffort: string | null;
     locale: AppLocale | null;
     accessPreset: AccessPresetValue | null;
     collaborationMode: CollaborationModeValue | null;
@@ -403,7 +403,7 @@ export interface RuntimeStatus {
         activeTurns: number;
         runtimeKind?: 'default' | 'isolated';
         currentAuth?: string | null;
-        defaultBackend?: 'codex' | 'antigravity';
+        defaultBackend?: 'codex' | 'antigravity' | 'dsh';
         codexHome?: string | null;
         antigravityHome?: string | null;
         codexAppServer?: RuntimeStatus['codexAppServer'];

package/docs/dsh.md

@@ -0,0 +1,83 @@
+# DeepSeek Harness backend
+
+FoxClaw launches DSH's shipped `acp` profile and reuses Telegram progress, tool status, final answers, queueing, and interruption. Models and reasoning levels come from the current DSH session. Bindings and settings are stored separately for each bot, chat, and topic.
+
+## Existing bot
+
+Add to FoxClaw's `.env`:
+
+```dotenv
+DSH_ENABLED=true
+DSH_SOURCE_DIR=/absolute/path/to/deepseek-harness
+```
+
+Prepare DSH dependencies and its platform native addon first. Source mode runs `apps/cli/src/bin.ts` with FoxClaw's Node and resolves `tsx` from the DSH repository. For Linux development, run `pnpm install` and `pnpm run build:native-system` inside DSH; follow DSH's installation instructions for other platforms.
+
+For an installed CLI, replace `DSH_SOURCE_DIR` with `DSH_CLI_BIN=/absolute/path/to/dsh`. A `.js`, `.mjs`, or `.cjs` entry point also works. Source mode takes precedence when both are set.
+
+Restart FoxClaw, then send `/backend dsh` and `/setup` to your Codex or Antigravity bot. Switching back restores the previous backend's session and settings. Interrupt an active turn before switching backends.
+
+## Dedicated bot
+
+```dotenv
+CODEX_BOT_TOKENS=
+DSH_BOT_TOKEN=123456:your-independent-bot-token
+DSH_SOURCE_DIR=/absolute/path/to/deepseek-harness
+TG_ALLOWED_USER_ID=123456789
+DEFAULT_CWD=/absolute/path/to/workspace
+```
+
+`DSH_BOT_TOKEN` enables DSH automatically and must differ from other backend tokens. Standalone DSH requires neither Codex nor Antigravity. Run `foxclaw doctor` and start the service normally. DSH currently connects through Telegram; Weixin uses the existing backends.
+
+## Configuration and controls
+
+| Setting | Default / purpose |
+| --- | --- |
+| `DSH_HOME` | Existing DSH home, normally `~/.dsh`; credentials, profiles, and persisted sessions |
+| `DSH_PROFILE` | `acp`; custom profiles must expose ACP, model controls, and `permissionPresets` |
+| `DSH_PATCHES` | JSON array, e.g. `["/absolute/path/to/patch.yml"]`, applied in order |
+| `DSH_STARTUP_TIMEOUT_MS` | `60000`; startup timeout, including first profile initialization |
+| `DEFAULT_SANDBOX_MODE` | Initial access: `read-only`, `workspace-write`, or `danger-full-access` |
+
+Provider credentials remain managed by DSH. Provider environment variables such as `DEEPSEEK_API_KEY` can be placed in FoxClaw's `.env` and are inherited by DSH. Codex/AGY account rotation and auth synchronization are not used by this backend.
+
+| Control | Purpose |
+| --- | --- |
+| `/setup` | Models, reasoning, permissions, queue/interrupt mode, sessions, and plugin configuration |
+| `/models`, `/model <provider/model>` | Native model selection; `/model default` restores the session's initial model |
+| `/effort`, `/effort <level>` | Reasoning choices advertised by the current model; changing models resets reasoning to the new model's default |
+| `/permissions read-only\|default\|full-access` | Read-only, workspace-write, or full-access, also available as buttons |
+| `/threads`, `/open <session ID>` | List and resume persisted DSH sessions |
+| `/new [directory]` | New session with an optional working directory |
+| `/active queue\|steer`, `/queue`, `/steer <message>`, `/interrupt` | Queueing, interruption, and takeover |
+| `/plugins` | Profile dependencies and configured patch paths |
+
+The bundled `foxclaw-permissions` plugin applies native DSH permission presets to root agents; children inherit according to DSH's rules. Native approval requests become Allow once / Reject buttons. Interrupting or stopping cancels pending approvals. Access changes require an idle turn.
+
+## Plugins and limitations
+
+`/plugins` shows explicit profile dependencies and configured patches, rather than a complete inventory of active built-in plugins. Install/remove packages with DSH's own command, using the same `DSH_HOME` and profile, then restart FoxClaw:
+
+```bash
+dsh plugin --profile acp add <package>
+dsh plugin --profile acp remove <package>
+```
+
+In source mode, run `node --import tsx/esm apps/cli/src/bin.ts plugin --profile acp ...` inside the DSH repository. There are currently no chat buttons for installing/removing packages.
+
+Progress follows committed ACP messages and tool events, rather than raw model token streaming. Images are sent natively when advertised by ACP; other attachments are passed as local paths. The current DSH ACP surface does not expose transcript replay, forks, renaming, or Agent/Plan switching, so those Codex-specific controls are omitted.
+
+ACP reports context occupancy rather than per-turn input/output/cache token consumption. The DSH status page explicitly marks those counts as unavailable.
+
+## Development verification
+
+Ordinary tests use a keyless ACP subprocess fixture. To exercise the actual source CLI with DSH's bundled control-surface fixture:
+
+```bash
+FOXCLAW_DSH_TEST_SOURCE_DIR=/absolute/path/to/deepseek-harness \
+DSH_TELEMETRY_DISABLED=1 node --test --import tsx src/dsh/source.integration.test.ts
+```
+
+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.

package/docs/release.md

@@ -16,38 +16,40 @@ Check the worktree and remote state:
 
 ```bash
 git status --short --branch
-npm pkg get name version
-npm view @foxden-app/foxclaw version
+node -p "require('./package.json').name + '@' + require('./package.json').version"
+pnpm view @foxden-app/foxclaw version
 git tag --list 'v*' --sort=-v:refname | head
 ```
 
 Confirm the target version and remote tag do not already exist:
 
 ```bash
-npm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
+pnpm view @foxden-app/foxclaw@0.5.10 version 2>/dev/null || true
 git ls-remote --tags origin refs/tags/v0.5.10
 ```
 
+Use the version pinned in `packageManager` and install with `pnpm install --frozen-lockfile`. npm is used only by the publishing workflow for registry authentication and publication.
+
 Run the same local checks as the publish workflow:
 
 ```bash
-npm run lint
-npm run typecheck
-npm test
-npm pack --dry-run
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm pack --pack-destination /tmp/foxclaw-release
 git diff --check
 ```
 
-`npm pack --dry-run` runs `prepack` and lists the package contents. Confirm `CHANGELOG.md` is included.
+`pnpm pack` runs `prepack` and creates the release archive. Inspect it with `tar -tzf /tmp/foxclaw-release/*.tgz` and confirm `CHANGELOG.md` is included.
 
 ## Prepare The Version
 
-1. Update `package.json` and `package-lock.json`.
+1. Update `package.json` and `pnpm-lock.yaml`.
 2. Add a new top entry to `CHANGELOG.md` with both `### 中文` and `### English` sections.
 3. Commit the release metadata:
 
 ```bash
-git add package.json package-lock.json CHANGELOG.md
+git add package.json pnpm-lock.yaml CHANGELOG.md
 git commit -m "发布 0.5.10：short release summary"
 ```
 
@@ -71,7 +73,7 @@ gh run watch <run-id> --repo foxden-app/foxclaw --exit-status
 After success, verify npm and GitHub Releases:
 
 ```bash
-npm view @foxden-app/foxclaw version
+pnpm view @foxden-app/foxclaw version
 gh release view v0.5.10 --repo foxden-app/foxclaw --json tagName,name,url,publishedAt,isDraft,isPrerelease
 ```
 

package/docs/zh/architecture-review.md

@@ -0,0 +1,106 @@
+# FoxClaw 架构复审与重构
+
+日期：2026-10-06。基线：v0.12.0。
+
+## 判断
+
+保留后端适配器 + 共享调度的方向，但 v0.12.0 还没有形成完整的后端边界。新增 DSH 时必须同时修改 Antigravity 控制器、调度器、启动逻辑及多处面板分支。问题不是目录名称，而是执行身份、会话状态、界面入口和资源清理由不同地方分别决定。
+
+本轮改动任务调度、通道契约、持久任务日志、资源归属，并提取存量控制器的独立功能。Telegram 为主通道；微信保留文字入口，完整迁移等待观察消息方案落定。存量数据库和导入路径继续兼容。
+
+## 当前边界
+
+```mermaid
+flowchart TD
+    Main[main.ts：运行时组装] --> Bridge[bridge/unified_bridge：存量 Codex / AGY 功能接入]
+    Main --> Definition[后端定义：adapter / defaults / commands / createUi]
+    Bridge --> Registry[BackendRegistry：注册与面板生命周期]
+    Definition --> Registry
+    Registry --> UI[BackendUi：模型、权限、历史与审批面板]
+    UI --> Host[BackendUiHost：有限的界面操作]
+    Host --> Orchestrator[Orchestrator：任务调度与交付]
+    Orchestrator --> ScopeOps[ScopeOperations：每会话串行操作]
+    Orchestrator --> SPI[Engine SPI：后端执行、事件、取消]
+    Orchestrator --> Store[BridgeStore：会话、任务日志、持久队列]
+    Orchestrator --> Channel[ChannelPort：消息与交互能力]
+    Main --> Supervisor[RuntimeSupervisor：依赖逆序清理]
+```
+
+- `core/engine_spi.ts` 定义执行契约和后端声明；原生推理档位使用字符串，不受 Codex 枚举限制。
+- `core/backend_registry.ts` 保持后端执行身份稳定，允许发现逻辑刷新展示元数据；注册失败不会残留半个后端，清理统一执行且只执行一次。
+- `core/backend_ui.ts` 定义面板接口与操作端口。后端面板不再依赖整个调度器实现。全局服务命令优先于后端命令；后端回调归属由注册的界面声明。
+- `dsh/backend.ts` 提供一份 DSH 定义，共享 Bot 与独立 Bot 均复用它。统一控制器无需导入或构造 DSH。
+- `bridge/unified_bridge.ts` 是存量后端的组合层，不再挂在 Antigravity 引擎目录下。旧导入路径保留为兼容转发。
+- `core/access.ts` 是权限策略的领域逻辑，Codex 适配器将当前设置传入原生线程和任务请求。
+
+新增后端应在组装处注入定义。调度器不应再增加 `adapter.id === 某后端` 来处理附件、取消、默认推理档位或菜单。
+
+## 状态约束与修复
+
+### 会话操作
+
+启动、插话、中断、新会话、切换后端和队列领取按 scope 串行执行；不同 scope 独立。任务从启动准备到最终回答交付都保留占用状态，避免两个消息在准备阶段同时启动任务。
+
+所有事件回调验证任务对象的所有权，忽略已取消或被替换任务的会话 ID、增量、错误和终态。取消前先屏蔽旧任务回调，并等待适配器返回的取消承诺完成后释放槽位。取消失败保留占用，不能自动启动重叠任务。Codex / OpenCode 的启动阶段取消也会结束等待者并释放监听器；DSH 无法及时取消时关闭其自有进程。
+
+执行中或仍有排队任务时不能切换后端。未启用的已选后端不会静默退回其他执行器，原会话与设置保留，用户可通过 `/backend` 重新选择。新后端的首次使用清除旧后端权限及模型覆盖；返回时恢复该后端保存的配置。
+
+### 通道收件箱与持久队列
+
+Telegram 更新在分类、准备附件和等待会话锁之前写入持久收件箱。通道只在处理完成后推进收取位置；重启先恢复未完成收件，再接收新更新。处理成功后清除原始载荷，保留收件标识用于去重；原生任务日志另行去重，避免收件重放导致重复执行工具。
+
+新队列载荷记录版本、原始 prompt、后端、工作目录和已落盘附件。已有文本数组格式继续可读。
+
+队列状态为 `queued → processing → completed / failed / cancelled`，只有实际执行和交付结束才进入终态。任务日志为 `accepted → queued / running → delivery_pending → completed / failed / cancelled`，另外记录 `awaiting_confirmation`。普通输入、显式排队和插话在等待会话锁之前保存原始输入、附件引用、模型、权限和后端配置；队列写入与任务关联使用同一数据库事务。队列已领取、任务日志仍为 queued 时可确认尚未调用执行器，重启重新排队。上下文不匹配会失败并提示。
+
+附件只在通道入口落盘，原始文本与附件清单交给适配器；适配器决定使用原生图片还是文件提示。JSON 文件不再被调度器统一过滤。OAuth 文件导入仅由 Antigravity 的入站界面处理。
+
+### 重启与交付行为（本地实现，尚未部署）
+
+- 已接受但尚未启动：恢复原始输入与配置，再准备附件。
+- 已保存原生结果：只重试剩余结果交付，不再次执行工具。
+- 已开始但结果未知：保留输入与附件，暂停该会话队列，提供 `/recover continue|retry|cancel` 和按钮。继续会要求模型检查已有工作；重试可能重复操作。该保守恢复策略随 v0.13.0 启用。
+- 最终消息逐块保存交付进度。消息平台成功发送却丢失确认时，恢复可能重复一条回答；不能保证平台交付恰好一次，但不会为了补发结果重跑工具。
+- 启动时按 scope 归属导入旧预览和 processing 队列，不触碰其他 Bot 的记录。
+
+### 通道与资源
+
+`ChannelPort`、入站事件和附件类型独立于 Telegram。Telegram 自行处理寻址、命令菜单与原生消息编号；无按钮通道可把操作转换成有 scope 归属、有效期、单次使用约束的文字选择。不可编辑通道不推送每段增量。
+
+`RuntimeSupervisor` 从分配起登记资源，覆盖部分启动失败，按消费者到依赖逆序关闭，继续清理其他资源并收集错误。数据库最后关闭、进程锁最后释放。关闭信号只执行一次；Telegram 长轮询可取消并等待退出。原生 RPC 监听器由控制面拥有，停止时移除并等待已开始的审批、通知、观察轮询及定时后台操作完成；共享原生客户端由运行时组装层关闭。客户端分配后立即登记，即使后续初始化失败也会清理。
+
+Codex 控制面挂在后端注册界面下，负责账号、原生面板和审批，不再启动另一套任务恢复逻辑，也不会为统一调度器拥有的任务启动第二个渲染器。多 Bot 共享 RPC 时只处理自己拥有的会话。Antigravity 账号面板与会话/观察服务已独立提取，观察轮询在停止时等待结束。
+
+### 展示依据
+
+默认档位、Boost 和逐轮 token 统计由后端定义声明，模型可携带自己的推理档位。Codex 模型列表完全使用服务端返回结果，移除硬编码补入的模型。状态与模型入口使用共享回调，具体面板由已选后端渲染。
+
+## 已拆分与明确保留的边界
+
+- Codex 提取用量缓存服务、配额服务、原生面板服务，以及账号文件、账号展示、交互解析、工具展示等模块。控制器约从 14,000 行降至 10,000 行，仍保留存量会话、观察与鉴权协调，不能称为全部技术债归零。
+- AGY 提取账号面板和会话/观察服务，统一组合层约从 2,500 行降至 1,600 行。DSH 继续通过独立后端定义接入。
+- 微信仍使用存量 Codex 会话核心，已增加文字选择；没有自动获得完整多后端能力。按用户优先级暂不迁移其观察执行路径。
+- 调度器本身仍承担较多任务恢复和交付工作，后续可沿任务日志与交付服务边界提取。通道收件箱已补齐收取到分类之间的恢复缺口；平台消息交付仍不承诺恰好一次。
+- 独立 OpenCode 控制器仍使用存量任务流程，未完整迁移持久任务日志；已有 OpenCode 执行适配器与统一执行契约兼容，但不能据此声称独立 Bot 已达标。
+- `main.ts` 仍组装鉴权同步与各 Bot 状态；资源退出责任已集中，组装代码可继续按运行时工厂提取。
+
+## 四项完成标准的验收范围
+
+| 标准 | Telegram 统一任务路径 | 证据与边界 |
+| --- | --- | --- |
+| 新增后端不改其他后端 | 达到 | 注入后端定义与界面工厂；未知后端的默认档位、面板、回调和执行通过契约测试 |
+| 新增通道不改执行器 | 达到 | 入站事件、附件与消息能力为通用契约；未知通道可使用同一个后端，执行器不导入 Telegram 文件工具 |
+| 任务全程可恢复 | 达到有边界的恢复要求 | 持久收件箱 → 接受与排队 → 原生配置 → 结果与交付游标；原生结果未知时暂停并要求确认，不能承诺任意外部工具恰好执行一次 |
+| 资源有唯一负责人 | 达到已迁移路径要求 | 运行时拥有共享客户端和数据库；控制面拥有监听与后台操作；调度器拥有任务槽位；Telegram 通道拥有草稿和停止关联；部分启动失败和停止竞态已有测试 |
+
+验收范围为 Telegram 的 Codex / Antigravity / DSH 统一任务路径。微信存量执行路径、独立 OpenCode 控制器和外部会话观察展示仍有遗留边界，因此全仓库四项标准尚未全部达成。
+
+Telegram 已实现单条进度卡、停止操作与完成后的折叠执行摘要。私聊优先使用原生临时草稿，不支持时回退持久消息卡；群聊编辑同一持久消息。停止保留排队任务，并保留已生成内容；最终移除旧停止操作。草稿编号不写成持久消息编号，最终交付前等待正在进行的预览编辑。大工具摘要按完整格式行限长，避免拆坏折叠标签。个人临时设置面板和微信观察摘要尚未启用。
+
+官方功能依据和接入状态见 [Telegram 主通道](telegram-experience.md)。
+
+## 验证
+
+回归覆盖每会话并发启动、跨会话独立执行、取消完成屏障、取消失败、旧回调隔离、新会话与启动竞态、终态重复事件、最终回答交付期间排队、附件队列重启恢复、所有后端切换限制、原生权限 RPC、注册清理与禁用后端保护。另保留全量测试，并运行真实 DSH ACP 控制面集成测试。
+
+v0.13.0 发布前全量回归 547 项：545 通过、2 跳过。任务生命周期、长摘要、控制面审批与后台清理专项 40 项全部通过；准备阶段预览释放测试也已纳入全量回归。pnpm lint、typecheck、build 通过；使用编译产物的真实 DSH ACP 控制面集成测试通过（模型切换、权限保存、恢复、取消、桥接插件加载）。Telegram 新停止字段、收取确认顺序、草稿与卡片降级、过期按钮隔离均有模拟接口验证；未向真实 Bot 发送测试消息，手机交互尚需上线验收。上述改动纳入 v0.13.0 正式版。