@steerable/agent-shell 0.6.20 → 0.6.22

package/dist/local-backend/router.js

@@ -1,8 +1,9 @@
 import { randomUUID } from 'crypto';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import os from 'node:os';
-import { getAppRootDir } from '../runtime.js';
+import { getAppRootDir, shellOpenPath } from '../runtime.js';
 import { llmService, getSidecarSupervisor, whenSidecarSupervisor } from '../llm/index.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { buildWorldState, getActiveCoreLoopStreamId, streamCoreLoopTurn, } from './coreloop-stream.js';
@@ -10,7 +11,7 @@ import { driveWithAutoContinue, resolveAutoContinueMax, } from './auto-continue-
 import { builtinSubagentParam } from './subagent-profiles.js';
 import { appendTimelineDelta, syncTimelineTools, } from './turn-timeline.js';
 import { turnDurationMs } from './turn-duration.js';
-import { localStore, DEFAULT_SYSTEM_PROMPT, telemetryEnabled } from '../storage/index.js';
+import { DEFAULT_SYSTEM_PROMPT, telemetryEnabled } from '../storage/index.js';
 import { isSkillPinned, isToolAllowed, mergeAgentCapabilities, normalizeToolPolicy, resolveSkillExcludes, } from './agent-capability.js';
 import { getBrand } from '../brand.js';
 import { recordInsightEvent, recordInsightTurn, recordInsightProfile } from '../insights/record.js';
@@ -21,11 +22,12 @@ import { allowEgressForBaseUrl, getActiveEgressBroker, getEgressPosture } from '
 import { buildExecSandbox, parseExecPolicy } from '../sidecar/exec-sandbox.js';
 import { SidecarSupervisor } from '../sidecar/index.js';
 import { diagnoseLlmConnection } from './llm-diagnose.js';
-import { buildSystemPrompt, buildForcedSkillMessage, conditionsFromTools, } from './prompt-builder.js';
+import { brandSkillVars, buildSystemPrompt, buildForcedSkillMessage, conditionsFromTools, } from './prompt-builder.js';
 import { parseUserMessageTriggers } from './message-triggers.js';
 import { findSkill, loadSkills, classifySkillOrigin, listSkillRoots } from './skill-loader.js';
 import { installSkillFromDirectory } from './skill-install.js';
 import { generateChatTitle } from './ai-title.js';
+import { fallbackSuggestedReplies, generateSuggestedReplies, } from './ai-suggestions.js';
 import { detectDeferredExecution } from './deferred-detector.js';
 import { formatHistoryForSummary, truncateMiddle, } from './context-compactor.js';
 import { planRegenerateTruncate, resolveRegenerateContext, resolveRegenerateForkOrdinal, } from './regenerate-helper.js';
@@ -37,6 +39,9 @@ import { loadProjectRuleFiles } from '../project-rules.js';
 import { registerLiveStream, getLiveStream, removeLiveStream } from './live-stream.js';
 import { beginPackTurnObservers, collectPackExecWritableRoots, collectPackForcedSkillVars, collectPackWorldState, } from './pack-turn-hooks.js';
 import { matchPackBackendRoute } from './pack-backend-routes.js';
+import { collectTurnFiles } from './turn-files.js';
+import { resolveMentionedPaths } from './mentioned-paths.js';
+import { getAuthProvider } from '../auth/index.js';
 /**
  * 把 CoreLoop/LLM 的底层错误翻译成适合直接显示在助手消息里的中文提示。
  * 原始错误仍保存在 messageMetadata.completionReason 里，便于排查。
@@ -59,7 +64,7 @@ export function userFacingCoreLoopFailure(reason) {
 /**
  * Parses a pagination-style query param (`?page=`, `?limit=`) into a finite
  * positive integer, falling back to `fallback` for missing/non-numeric input
- * (e.g. `?page=abc`) instead of letting `NaN` leak into `localStore` queries
+ * (e.g. `?page=abc`) instead of letting `NaN` leak into storage queries
  * and the echoed-back `pagination` block of the response.
  */
 function parsePositiveIntParam(raw, fallback) {
@@ -145,19 +150,44 @@ function buildLocalAgent() {
 }
 export class LocalBackendRouter {
     toolRouter;
+    defaultStore;
+    storeContext = new AsyncLocalStorage();
+    resolveStore;
     broadcast;
     /** 4.6a/4.6c：任务面板的路由入口（列表 + 合并/丢弃）。未注入时任务路由 503。 */
     taskService;
-    constructor(toolRouter, options = {}) {
+    constructor(toolRouter, options) {
         this.toolRouter = toolRouter;
+        this.defaultStore = options.store;
+        this.resolveStore = options.resolveStore ?? (() => options.store);
         this.broadcast = options.broadcast ?? null;
         this.taskService = options.taskService ?? null;
     }
-    async handle(request) {
+    get store() {
+        return this.storeContext.getStore() ?? this.defaultStore;
+    }
+    /** Store selected for the active request, or the host default outside one. */
+    get activeStore() {
+        return this.store;
+    }
+    handle(request) {
+        return this.storeContext.run(this.resolveStore(request.principal), () => this.handleScoped(request));
+    }
+    async handleScoped(request) {
         const { method } = request;
         const url = new URL(request.path, 'http://local.backend');
         const pathname = url.pathname;
         if (method === 'GET' && pathname === '/api/v2/auth/me') {
+            const authProvider = getAuthProvider();
+            if (authProvider) {
+                if (!request.principal) {
+                    return { status: 401, data: { detail: 'unauthorized' } };
+                }
+                return {
+                    status: 200,
+                    data: await authProvider.describeSelf(request.principal),
+                };
+            }
             return { status: 200, data: buildLocalApiUser() };
         }
         // Desktop Agent —— 在本地模式下虚拟一个永远在线的 agent，所有 exec 直接走 ToolRouter
@@ -215,7 +245,7 @@ export class LocalBackendRouter {
         if (method === 'GET' && pathname === '/api/v2/chats') {
             const page = parsePositiveIntParam(url.searchParams.get('page'), 1);
             const limit = parsePositiveIntParam(url.searchParams.get('limit'), 50);
-            const { chats, total } = localStore.listChats(page, limit);
+            const { chats, total } = await this.store.listChats(page, limit);
             return {
                 status: 200,
                 data: {
@@ -247,10 +277,10 @@ export class LocalBackendRouter {
         const branchesMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/branches$/);
         if (method === 'GET' && branchesMatch) {
             const chatId = branchesMatch[1];
-            const chat = localStore.getChat(chatId);
+            const chat = await this.store.getChat(chatId);
             if (!chat)
                 return { status: 404, data: { detail: 'chat not found' } };
-            const activeRecordId = localStore.getChatRecordId(chatId) ?? chatId;
+            const activeRecordId = await this.store.getChatRecordId(chatId) ?? chatId;
             const supervisor = getSidecarSupervisor();
             const branches = supervisor ? await supervisor.sessionBranches(activeRecordId) : null;
             return {
@@ -268,10 +298,10 @@ export class LocalBackendRouter {
         const branchTreeMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/branches\/tree$/);
         if (method === 'GET' && branchTreeMatch) {
             const chatId = branchTreeMatch[1];
-            const chat = localStore.getChat(chatId);
+            const chat = await this.store.getChat(chatId);
             if (!chat)
                 return { status: 404, data: { detail: 'chat not found' } };
-            const activeRecordId = localStore.getChatRecordId(chatId) ?? chatId;
+            const activeRecordId = await this.store.getChatRecordId(chatId) ?? chatId;
             const supervisor = getSidecarSupervisor();
             const family = supervisor ? await supervisor.sessionTree(activeRecordId) : null;
             return {
@@ -292,7 +322,7 @@ export class LocalBackendRouter {
         const activateMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/branches\/activate$/);
         if (method === 'POST' && activateMatch) {
             const chatId = activateMatch[1];
-            const chat = localStore.getChat(chatId);
+            const chat = await this.store.getChat(chatId);
             if (!chat)
                 return { status: 404, data: { detail: 'chat not found' } };
             const payload = this.toRecord(request.body);
@@ -304,7 +334,7 @@ export class LocalBackendRouter {
             if (!supervisor) {
                 return { status: 503, data: { detail: 'sidecar unavailable' } };
             }
-            const activeRecordId = localStore.getChatRecordId(chatId) ?? chatId;
+            const activeRecordId = await this.store.getChatRecordId(chatId) ?? chatId;
             const family = await supervisor.sessionTree(activeRecordId);
             const activation = resolveBranchActivation(activeRecordId, family?.tree ?? null, targetRecordId);
             if (!activation.ok) {
@@ -314,8 +344,8 @@ export class LocalBackendRouter {
             if (!projection) {
                 return { status: 404, data: { detail: `record not found: ${targetRecordId}` } };
             }
-            localStore.setChatRecordId(chatId, targetRecordId);
-            localStore.replaceChatMessages(chatId, projection.messages
+            await this.store.setChatRecordId(chatId, targetRecordId);
+            await this.store.replaceChatMessages(chatId, projection.messages
                 .filter((m) => m.role === 'user' || m.role === 'assistant')
                 .map((m) => ({ role: m.role, content: m.content })));
             return {
@@ -339,7 +369,7 @@ export class LocalBackendRouter {
                     };
                 }
             }
-            const created = localStore.createChat('新对话', typeof payload.agentId === 'string' ? payload.agentId : getBrand().defaultAgentId, projectId);
+            const created = await this.store.createChat('新对话', typeof payload.agentId === 'string' ? payload.agentId : getBrand().defaultAgentId, projectId);
             return {
                 status: 200,
                 data: {
@@ -359,7 +389,7 @@ export class LocalBackendRouter {
             const exceptChatId = typeof payload.exceptChatId === 'string' && payload.exceptChatId.trim()
                 ? payload.exceptChatId.trim()
                 : null;
-            const deletedChatIds = localStore.deleteEmptyChats(exceptChatId);
+            const deletedChatIds = await this.store.deleteEmptyChats(exceptChatId);
             return { status: 200, data: { deletedChatIds } };
         }
         // ───── 项目模式：projects CRUD ─────
@@ -419,7 +449,7 @@ export class LocalBackendRouter {
                 if (!ok)
                     return this.notFound('项目不存在');
                 // 会话不删，只解绑——它们变成"无项目对话"。
-                const detached = localStore.clearProjectAssignment(projectId);
+                const detached = await this.store.clearProjectAssignment(projectId);
                 return { status: 200, data: { success: true, detachedChats: detached } };
             }
         }
@@ -455,17 +485,17 @@ export class LocalBackendRouter {
                 return { status: 503, data: { detail: 'task service unavailable' } };
             }
             const chatId = chatTasksMatch[1];
-            const chat = localStore.getChat(chatId);
+            const chat = await this.store.getChat(chatId);
             if (!chat)
                 return { status: 404, data: { detail: 'chat not found' } };
-            return { status: 200, data: { tasks: localStore.listTasks(chatId) } };
+            return { status: 200, data: { tasks: await this.store.listTasks(chatId) } };
         }
         const taskProcessMatch = pathname.match(/^\/api\/v2\/tasks\/([^/]+)\/process$/);
         if (method === 'GET' && taskProcessMatch) {
             if (!this.taskService) {
                 return { status: 503, data: { detail: 'task service unavailable' } };
             }
-            const snapshot = this.taskService.getProcess(taskProcessMatch[1]);
+            const snapshot = await this.taskService.getProcess(taskProcessMatch[1]);
             if (!snapshot)
                 return { status: 404, data: { detail: '任务不存在' } };
             return {
@@ -503,7 +533,7 @@ export class LocalBackendRouter {
         const projectContextMatch = pathname.match(/^\/api\/v2\/chats\/([^/]+)\/project-context$/);
         if (projectContextMatch && method === 'GET') {
             const chatId = projectContextMatch[1];
-            const chat = localStore.getChat(chatId);
+            const chat = await this.store.getChat(chatId);
             if (!chat)
                 return this.notFound('Chat not found');
             const registry = this.toolRouter.projectRegistry;
@@ -528,7 +558,7 @@ export class LocalBackendRouter {
         if (chatMatch) {
             const chatId = chatMatch[1];
             if (method === 'GET') {
-                const chat = localStore.getChat(chatId);
+                const chat = await this.store.getChat(chatId);
                 if (!chat)
                     return this.notFound('Chat not found');
                 return {
@@ -549,13 +579,13 @@ export class LocalBackendRouter {
             }
             if (method === 'DELETE') {
                 if (url.searchParams.get('onlyIfEmpty') === '1') {
-                    const deleted = localStore.deleteChatIfEmpty(chatId);
+                    const deleted = await this.store.deleteChatIfEmpty(chatId);
                     return {
                         status: 200,
                         data: { success: true, deleted, chatId },
                     };
                 }
-                const ok = localStore.deleteChat(chatId);
+                const ok = await this.store.deleteChat(chatId);
                 if (!ok)
                     return this.notFound('Chat not found');
                 return {
@@ -572,7 +602,7 @@ export class LocalBackendRouter {
         if (chatPinMatch && method === 'PUT') {
             const chatId = chatPinMatch[1];
             const payload = this.toRecord(request.body);
-            const updated = localStore.updateChat(chatId, { isPinned: Boolean(payload.isPinned) });
+            const updated = await this.store.updateChat(chatId, { isPinned: Boolean(payload.isPinned) });
             if (!updated)
                 return this.notFound('Chat not found');
             return {
@@ -607,7 +637,7 @@ export class LocalBackendRouter {
                     return this.badRequest('projectId 必须是项目 id 字符串或 null');
                 }
             }
-            const updated = localStore.updateChat(chatId, {
+            const updated = await this.store.updateChat(chatId, {
                 title: typeof payload.title === 'string' ? payload.title : undefined,
                 systemPrompt: typeof payload.systemPrompt === 'string' ? payload.systemPrompt : undefined,
                 pinnedRefs: Array.isArray(payload.pinnedRefs) ? payload.pinnedRefs : undefined,
@@ -635,7 +665,7 @@ export class LocalBackendRouter {
         if (messageListMatch && method === 'GET') {
             const chatId = messageListMatch[1];
             const limit = parsePositiveIntParam(url.searchParams.get('limit'), 200);
-            const records = localStore.listMessages(chatId, limit);
+            const records = await this.store.listMessages(chatId, limit);
             const messages = records.map(item => ({
                 id: item.id,
                 chatId: item.chatId,
@@ -652,7 +682,7 @@ export class LocalBackendRouter {
             // 同一 record 上开出第二个写者）。listMessages 是 DESC，records[0]
             // 即最后一条。
             const interrupted = detectInterruptedTurn({
-                turnActive: localStore.getTurnActive(chatId) !== null,
+                turnActive: await this.store.getTurnActive(chatId) !== null,
                 streamActive: getActiveCoreLoopStreamId(chatId) !== undefined,
                 lastMessageRole: records[0]?.role ?? null,
             });
@@ -708,7 +738,7 @@ export class LocalBackendRouter {
         }
         if (method === 'GET' && pathname === '/api/v2/chat-agents') {
             const includeArchived = url.searchParams.get('include_archived') === 'true';
-            const agents = localStore.listChatAgents(includeArchived);
+            const agents = await this.store.listChatAgents(includeArchived);
             return {
                 status: 200,
                 data: {
@@ -719,7 +749,7 @@ export class LocalBackendRouter {
         }
         if (method === 'POST' && pathname === '/api/v2/chat-agents') {
             const payload = this.toRecord(request.body);
-            const agent = localStore.createChatAgent({
+            const agent = await this.store.createChatAgent({
                 name: String(payload.name || '新助手'),
                 icon: typeof payload.icon === 'string' ? payload.icon : null,
                 color: typeof payload.color === 'string' ? payload.color : null,
@@ -1144,14 +1174,14 @@ export class LocalBackendRouter {
         if (chatAgentMatch) {
             const agentId = chatAgentMatch[1];
             if (method === 'GET') {
-                const agent = localStore.getChatAgent(agentId);
+                const agent = await this.store.getChatAgent(agentId);
                 if (!agent)
                     return this.notFound('Agent not found');
                 return { status: 200, data: agent };
             }
             if (method === 'PATCH') {
                 const payload = this.toRecord(request.body);
-                const agent = localStore.updateChatAgent(agentId, {
+                const agent = await this.store.updateChatAgent(agentId, {
                     name: typeof payload.name === 'string' ? payload.name : undefined,
                     icon: typeof payload.icon === 'string' ? payload.icon : undefined,
                     color: typeof payload.color === 'string' ? payload.color : undefined,
@@ -1170,7 +1200,7 @@ export class LocalBackendRouter {
                 return { status: 200, data: { agent } };
             }
             if (method === 'DELETE') {
-                const ok = localStore.archiveChatAgent(agentId);
+                const ok = await this.store.archiveChatAgent(agentId);
                 if (!ok)
                     return this.notFound('Agent not found');
                 return {
@@ -1373,12 +1403,12 @@ export class LocalBackendRouter {
             if (method === 'GET') {
                 return {
                     status: 200,
-                    data: localStore.getLlmSettings(),
+                    data: await this.store.getLlmSettings(),
                 };
             }
             if (method === 'POST') {
                 const payload = this.toRecord(request.body);
-                const saved = llmService.setSettings({
+                const saved = await llmService.setSettings({
                     provider: sanitizeLlmProvider(payload.provider),
                     vendorId: sanitizeVendorId(payload.vendorId),
                     model: String(payload.model || 'llama3.1:8b'),
@@ -1398,7 +1428,7 @@ export class LocalBackendRouter {
                         : undefined,
                     compat: sanitizeCompatOverrides(payload.compat),
                     presets: sanitizePresetsChoice(payload.presets),
-                });
+                }, this.store);
                 // 立即让新默认超时对后续 local_exec_shell 生效（重启后由 main.ts 启动时恢复）。
                 setDefaultExecTimeoutMs(saved.execTimeoutSeconds ? saved.execTimeoutSeconds * 1000 : null);
                 // 代理白名单是 boot 时按当时的 baseUrl 派生的，换了网关后本会话（含
@@ -1418,12 +1448,12 @@ export class LocalBackendRouter {
             if (method === 'GET') {
                 return {
                     status: 200,
-                    data: localStore.getTelemetrySettings(),
+                    data: await this.store.getTelemetrySettings(),
                 };
             }
             if (method === 'POST') {
                 const payload = this.toRecord(request.body);
-                const saved = localStore.setTelemetrySettings({
+                const saved = await this.store.setTelemetrySettings({
                     endpoint: typeof payload.endpoint === 'string' ? payload.endpoint : undefined,
                     privacyMode: payload.privacyMode === 'full' ? 'full' : 'metadata',
                     serviceName: typeof payload.serviceName === 'string' ? payload.serviceName : undefined,
@@ -1438,12 +1468,12 @@ export class LocalBackendRouter {
             if (method === 'GET') {
                 return {
                     status: 200,
-                    data: localStore.getWebSearchSettings(),
+                    data: await this.store.getWebSearchSettings(),
                 };
             }
             if (method === 'POST') {
                 const payload = this.toRecord(request.body);
-                const saved = localStore.setWebSearchSettings({
+                const saved = await this.store.setWebSearchSettings({
                     provider: payload.provider === 'ddg' ? 'ddg' : 'tavily',
                     apiKey: typeof payload.apiKey === 'string' ? payload.apiKey : undefined,
                 });
@@ -1455,10 +1485,10 @@ export class LocalBackendRouter {
         }
         if (pathname === '/api/v2/local-settings/insights') {
             if (method === 'GET') {
-                const settings = localStore.ensureInsightsSettings();
+                const settings = await this.store.ensureInsightsSettings();
                 return {
                     status: 200,
-                    data: { ...settings, stats: localStore.insightStats() },
+                    data: { ...settings, stats: await this.store.insightStats() },
                 };
             }
             if (method === 'POST') {
@@ -1487,20 +1517,20 @@ export class LocalBackendRouter {
                     patch.apiBase = payload.apiBase;
                 if (Object.keys(profilePatch).length)
                     patch.profile = profilePatch;
-                const saved = localStore.setInsightsSettings(patch);
+                const saved = await this.store.setInsightsSettings(patch);
                 const hasProfileFields = Boolean(saved.profile.displayName ||
                     saved.profile.email ||
                     saved.profile.company ||
                     saved.profile.note);
                 if (hasProfileFields) {
-                    recordInsightProfile(saved.profile);
+                    await recordInsightProfile(this.store, saved.profile);
                 }
-                void flushInsightsOutbox().catch((err) => {
+                void flushInsightsOutbox(this.store).catch((err) => {
                     console.warn('[insights] flush after settings save failed', err);
                 });
                 return {
                     status: 200,
-                    data: { ...saved, stats: localStore.insightStats() },
+                    data: { ...saved, stats: await this.store.insightStats() },
                 };
             }
         }
@@ -1513,19 +1543,19 @@ export class LocalBackendRouter {
             const properties = payload.properties && typeof payload.properties === 'object'
                 ? payload.properties
                 : {};
-            recordInsightEvent(eventName, properties);
+            await recordInsightEvent(this.store, eventName, properties);
             return { status: 200, data: { status: 'ok' } };
         }
         if (method === 'GET' && pathname === '/api/v2/insights/export') {
-            return { status: 200, data: buildInsightsExportPayload() };
+            return { status: 200, data: await buildInsightsExportPayload(this.store) };
         }
         if (method === 'POST' && pathname === '/api/v2/insights/upload-local') {
-            const ok = await uploadInsightsBundle();
+            const ok = await uploadInsightsBundle(this.store);
             return {
                 status: ok ? 200 : 502,
                 data: {
                     ok,
-                    stats: localStore.insightStats(),
+                    stats: await this.store.insightStats(),
                     detail: ok ? 'uploaded' : 'upload_failed_kept_local',
                 },
             };
@@ -1534,7 +1564,7 @@ export class LocalBackendRouter {
             const days = parsePositiveIntParam(url.searchParams.get('days'), 30);
             return {
                 status: 200,
-                data: localStore.getUsageSummary(days),
+                data: await this.store.getUsageSummary(days),
             };
         }
         if (method === 'POST' && pathname.match(/^\/api\/v2\/chats\/[^/]+\/suggest-replies$/)) {
@@ -1620,7 +1650,7 @@ export class LocalBackendRouter {
             if (!chatId) {
                 return { status: 400, data: { detail: 'chatId is required' } };
             }
-            const traces = localStore.listTracesByChat(chatId, limit).map(item => ({
+            const traces = (await this.store.listTracesByChat(chatId, limit)).map(item => ({
                 ...item,
                 payload: this.safeJson(item.payload, {}),
             }));
@@ -1631,7 +1661,7 @@ export class LocalBackendRouter {
         }
         const traceMatch = pathname.match(/^\/api\/v2\/local\/traces\/([^/]+)$/);
         if (traceMatch && method === 'GET') {
-            const trace = localStore.getTrace(traceMatch[1]);
+            const trace = await this.store.getTrace(traceMatch[1]);
             if (!trace)
                 return this.notFound('Trace not found');
             return {
@@ -1642,6 +1672,37 @@ export class LocalBackendRouter {
                 },
             };
         }
+        // 回合产物列表的「点击打开」：用系统默认应用打开本地路径（与 agent 的
+        // local_open_path 工具同一宿主能力，这里给渲染层一个 HTTP 入口，CS/BS
+        // 两种模式都经 localBackend.request 到达）。
+        if (method === 'POST' && pathname === '/api/v2/local/open-path') {
+            const payload = this.toRecord(request.body);
+            const target = typeof payload.path === 'string' ? payload.path.trim() : '';
+            if (!target || !path.isAbsolute(target)) {
+                return { status: 400, data: { detail: 'absolute path is required' } };
+            }
+            const openError = await shellOpenPath(target);
+            if (openError) {
+                return { status: 200, data: { success: false, error: openError } };
+            }
+            return { status: 200, data: { success: true } };
+        }
+        // 正文里提到的路径能否点击打开：渲染层把行内代码里「像路径」的字面量
+        // 批量送来，这里落地成绝对路径并 stat 验证，只有真实存在的才回。相对
+        // 路径按对话绑定的项目根解析，无项目时按 home（同 exec 缺省 cwd 的回落）。
+        if (method === 'POST' && pathname === '/api/v2/local/resolve-paths') {
+            const payload = this.toRecord(request.body);
+            const candidates = Array.isArray(payload.candidates)
+                ? payload.candidates.filter((item) => typeof item === 'string')
+                : [];
+            if (candidates.length === 0) {
+                return { status: 200, data: { resolved: [] } };
+            }
+            const chatId = typeof payload.chatId === 'string' ? payload.chatId : '';
+            const baseDir = (chatId ? (await this.resolveChatProject(chatId))?.folderPath : null) ?? os.homedir();
+            const resolved = await resolveMentionedPaths({ candidates, baseDir });
+            return { status: 200, data: { resolved } };
+        }
         // ─── 场景包路由（1.2：/api/v2/<包前缀>/* 由包经 pack-backend-routes
         // 注册表贡献；在宿主自带路由之后、fallback 之前匹配，包不能遮蔽宿主
         // 路由）。 ───
@@ -1696,10 +1757,14 @@ export class LocalBackendRouter {
      *   `accumulatedContent += parsedData.content` 一行追加渲染。
      * - 同步真实 messageId：`data: {"type":"message_id","messageId":"..."}`
      * - 工具执行结果（无需用户确认）：`data: {"type":"executed_actions","actions":[...]}`
+     * - 回合产物文件列表（仅非空时发，在 message_id 之前）：`data: {"type":"turn_files","files":[...]}`
      * - 错误：保留 `event:error` + `data: {"message":"..."}`（前端会忽略，但日志/未来 UI 用）
      * - 结束：标准 SSE `[DONE]` 串。
      */
-    async handleStream(request, emit, options = {}) {
+    handleStream(request, emit, options = {}) {
+        return this.storeContext.run(this.resolveStore(request.principal), () => this.handleStreamScoped(request, emit, options));
+    }
+    async handleStreamScoped(request, emit, options = {}) {
         const signal = options.signal;
         const url = new URL(request.path, 'http://local.backend');
         const pathname = url.pathname;
@@ -1715,7 +1780,7 @@ export class LocalBackendRouter {
         }
         const chatId = sendMatch ? sendMatch[1] : regenerateMatch[1];
         const payload = this.toRecord(request.body);
-        let chat = localStore.getChat(chatId);
+        let chat = await this.store.getChat(chatId);
         if (!chat) {
             // 会话 URL 即会话身份：外部平台（自动化/eval）把一个 chatId 当成一次
             // 会话任务反复打开运行，本地会话却可能已经被用户清理、被空会话 prune、
@@ -1731,7 +1796,7 @@ export class LocalBackendRouter {
                 const agentId = typeof payload.agentId === 'string' && payload.agentId.trim()
                     ? payload.agentId.trim()
                     : 'local-assistant';
-                chat = localStore.createChatWithId(chatId, '新对话', agentId);
+                chat = await this.store.createChatWithId(chatId, '新对话', agentId);
                 console.warn('[local-backend] stream: chat missing, auto-provisioned', {
                     chatId,
                     agentId,
@@ -1769,7 +1834,7 @@ export class LocalBackendRouter {
             // the *real* request instead of a generic placeholder (matters for
             // deferred-exec detection, mode preamble, etc., which all key off the
             // actual ask).
-            const priorMessages = localStore.listMessages(chatId, 200).reverse();
+            const priorMessages = (await this.store.listMessages(chatId, 200)).reverse();
             const resolution = resolveRegenerateContext(priorMessages, targetMessageId);
             if (!resolution.ok) {
                 emit(this.sse('error', { message: 'regenerate target message not found or not an assistant message' }));
@@ -1788,13 +1853,13 @@ export class LocalBackendRouter {
             const supervisor = getSidecarSupervisor();
             const outcome = supervisor
                 ? await supervisor.forkSession({
-                    recordId: localStore.getChatRecordId(chatId) ?? chatId,
+                    recordId: await this.store.getChatRecordId(chatId) ?? chatId,
                     beforeUserIndex: resolveRegenerateForkOrdinal(priorMessages, targetMessageId),
                     newRecordId: `${chatId}:r${Date.now().toString(36)}`,
                 })
                 : null;
             if (outcome?.ok) {
-                localStore.setChatRecordId(chatId, outcome.fork.recordId);
+                await this.store.setChatRecordId(chatId, outcome.fork.recordId);
                 console.log('[local-backend] regenerate: record forked (old tail preserved)', {
                     chatId,
                     branchRecordId: outcome.fork.recordId,
@@ -1813,7 +1878,7 @@ export class LocalBackendRouter {
                 emit(this.sse('error', { message: plan.message }));
                 return { status: 409 };
             }
-            const deleted = localStore.deleteMessagesFrom(chatId, targetMessageId);
+            const deleted = await this.store.deleteMessagesFrom(chatId, targetMessageId);
             console.log('[local-backend] regenerate: truncated history', {
                 chatId,
                 targetMessageId,
@@ -1825,9 +1890,9 @@ export class LocalBackendRouter {
             // sidecar 回放 durable record 的投影作为循环种子。只在检测确为
             // interrupted 时接受：对一个已正常完结的 turn 续跑只会给完整对话
             // 凭空多接一段回复。
-            const prior = localStore.listMessages(chatId, 200);
+            const prior = await this.store.listMessages(chatId, 200);
             const interrupted = detectInterruptedTurn({
-                turnActive: localStore.getTurnActive(chatId) !== null,
+                turnActive: await this.store.getTurnActive(chatId) !== null,
                 streamActive: getActiveCoreLoopStreamId(chatId) !== undefined,
                 lastMessageRole: prior[0]?.role ?? null,
             });
@@ -1858,8 +1923,8 @@ export class LocalBackendRouter {
         //   3. 历史里目前没有任何 assistant 消息——也就是说，本轮即将产生的是第一条助手回复
         // 这避免在已经聊到一半的对话里突然把标题换掉。listMessages 是 DESC，limit 拉
         // 大一点确保看到完整历史（200 已经覆盖绝大多数本地会话）。
-        const existingAssistant = localStore
-            .listMessages(chatId, 200)
+        const existingAssistant = (await this.store
+            .listMessages(chatId, 200))
             .some((m) => m.role === 'assistant');
         const shouldGenerateTitle = !regenerateMatch &&
             !isResume &&
@@ -1880,7 +1945,7 @@ export class LocalBackendRouter {
         // persisted (and already in the durable record).
         let currentUserMessageId;
         if (!regenerateMatch && !isResume) {
-            const userMessage = localStore.addMessage(chatId, 'user', userMessageText);
+            const userMessage = await this.store.addMessage(chatId, 'user', userMessageText);
             currentUserMessageId = userMessage.id;
             emit(this.sseData({ type: 'user_message', message: userMessage }));
         }
@@ -1889,7 +1954,7 @@ export class LocalBackendRouter {
         const chatMode = payload.mode === 'plan' ? 'plan' : 'agent';
         // 本轮生效的智能体：人设、技能勾选、工具策略同源。必须先解析——工具
         // 策略决定工具列表，工具列表又决定技能的触发条件。
-        const turnAgents = this.resolveTurnAgents(chatId, payload);
+        const turnAgents = await this.resolveTurnAgents(chatId, payload);
         // Wave 2 工具分层：模型可见列表只出 direct 层（内置工具 + tool_search
         // 发现缝）；MCP 动态工具全在 deferred 层，经 tool_search 命中即调。
         // 附带收益：MCP 目录增删不再改动系统提示词里的工具名录，前缀更稳。
@@ -2001,7 +2066,7 @@ export class LocalBackendRouter {
                     });
                     return;
                 }
-                const fresh = localStore.getChat(chatId);
+                const fresh = await this.store.getChat(chatId);
                 if (!fresh) {
                     console.log('[local-backend] title-gen skip', {
                         chatId,
@@ -2017,7 +2082,7 @@ export class LocalBackendRouter {
                     });
                     return;
                 }
-                const updated = localStore.updateChat(chatId, { title: result.title });
+                const updated = await this.store.updateChat(chatId, { title: result.title });
                 if (!updated) {
                     console.warn('[local-backend] title-gen write failed', { chatId });
                     return;
@@ -2046,8 +2111,8 @@ export class LocalBackendRouter {
      * Public: main.ts 的反向通道（reverse-tools.ts）经它给 CoreLoop 路径的
      * 工具调用补上 projectRoot 围栏。
      */
-    resolveChatProject(chatId) {
-        const projectId = localStore.getChat(chatId)?.projectId;
+    async resolveChatProject(chatId) {
+        const projectId = (await this.store.getChat(chatId))?.projectId;
         if (!projectId)
             return null;
         const project = this.toolRouter.projectRegistry?.get(projectId);
@@ -2068,9 +2133,9 @@ export class LocalBackendRouter {
      *
      * @param chatId 当前对话 id。
      * @param payload 前端提交的流请求体。
-     * @returns 本轮的智能体顺序、人设智能体，以及合并后的能力面。
+     * @returns 本轮的智能体顺序、人设智能体、自称，以及合并后的能力面。
      */
-    resolveTurnAgents(chatId, payload) {
+    async resolveTurnAgents(chatId, payload) {
         const mentionedAgentIds = Array.isArray(payload.mentionedAgentIds)
             ? payload.mentionedAgentIds.filter((s) => typeof s === 'string')
             : [];
@@ -2082,19 +2147,20 @@ export class LocalBackendRouter {
         ].filter((id, idx, arr) => arr.indexOf(id) === idx);
         if (orderedAgentIds.length === 0) {
             const fallbackId = (typeof payload.agentId === 'string' && payload.agentId) ||
-                localStore.getChat(chatId)?.agentId ||
+                (await this.store.getChat(chatId))?.agentId ||
                 null;
             if (fallbackId)
                 orderedAgentIds.push(fallbackId);
         }
-        const agents = orderedAgentIds
-            .map((id) => localStore.getChatAgent(id))
+        const agents = (await Promise.all(orderedAgentIds.map((id) => this.store.getChatAgent(id))))
             .filter((agent) => Boolean(agent));
         return {
             orderedAgentIds,
             // 能力面来自全部解析到的智能体，人设前言只用配了 rolePrompt 的那些——
-            // 自建智能体可以只勾技能、不写人设。
+            // 自建智能体可以只勾技能、不写人设。自称始终跟第一个解析到的智能体，
+            // 不要求写了人设——否则没 rolePrompt 的角色会回落成产品品牌。
             personaAgents: agents.filter((agent) => Boolean(agent.rolePrompt)),
+            identityName: agents[0]?.name.trim() || null,
             capability: mergeAgentCapabilities(agents),
         };
     }
@@ -2105,7 +2171,7 @@ export class LocalBackendRouter {
         // 摘要，也不再按 40 条窗口截断——让框架 record 累积完整对话并按需压缩。
         // 上限即存储层 listMessages 的 1000 条硬上限；超出时最旧历史随
         // host_revision 优雅退化。
-        let rawHistory = localStore.listMessages(chatId, HISTORY_SEED_LIMIT).reverse();
+        let rawHistory = (await this.store.listMessages(chatId, HISTORY_SEED_LIMIT)).reverse();
         // 剔除刚刚写入数据库的当前轮用户消息，避免在上下文历史中与我们显式添加的
         // latestUserMessage 发生重复。send 路径按 id 精确剔除——上一条 assistant
         // 回复在流结束后异步落库（createdAt 取落库时刻），快速连续发送时它会排到
@@ -2150,7 +2216,7 @@ export class LocalBackendRouter {
         })))
             .filter(Boolean);
         const settings = llmService.getSettings();
-        const { personaAgents, capability } = turnAgents;
+        const { personaAgents, capability, identityName } = turnAgents;
         let personaPreamble = '';
         if (personaAgents.length === 1) {
             personaPreamble = `【当前角色】${personaAgents[0].name}\n${personaAgents[0].rolePrompt}`;
@@ -2218,6 +2284,7 @@ export class LocalBackendRouter {
                 excludeSkillNames,
                 pinnedSkillNames: capability.pinnedSkills,
                 personaPreamble: effectivePersonaPreamble,
+                identityName,
                 realityCheckSuffix: realityCheck,
                 forcedMcpTool,
                 ignoreConditions: capability.loadAllSkills,
@@ -2246,7 +2313,7 @@ export class LocalBackendRouter {
         // 项目模式：绑定项目的对话在系统提示末尾追加沙箱约定（两条拼装路径
         // 都追加）。硬围栏在 ToolRouter/LocalExecutor，这里让模型事先知道边界，
         // 减少越界尝试。
-        const chatProject = this.resolveChatProject(chatId);
+        const chatProject = await this.resolveChatProject(chatId);
         if (chatProject) {
             systemPrompt +=
                 `\n\n【项目模式】当前对话绑定项目「${chatProject.name}」，根目录：${chatProject.folderPath}\n` +
@@ -2258,7 +2325,7 @@ export class LocalBackendRouter {
             // 仅在用户显式信任该项目后才注入模型上下文——未信任一律不读取、不注入
             // （打开恶意仓库时，一段构造的规则文件不能劫持 agent）。信任状态持久化、
             // 可在设置里撤销；每回合重新读盘，规则保存即生效。
-            const projectId = localStore.getChat(chatId)?.projectId;
+            const projectId = (await this.store.getChat(chatId))?.projectId;
             const registry = this.toolRouter.projectRegistry;
             if (projectId && registry?.isTrusted(projectId)) {
                 const rules = loadProjectRuleFiles(chatProject.folderPath);
@@ -2284,7 +2351,10 @@ export class LocalBackendRouter {
             const forcedSkill = await findSkill(forcedSkillName, { exclude: forcedSkillExcludes });
             if (forcedSkill) {
                 // 场景包的正文占位符变量（如包技能正文里的工作区路径占位符）。
-                finalUserContent = `${buildForcedSkillMessage(forcedSkill, collectPackForcedSkillVars(chatId))}\n\n---\n\n${latestUserMessage}`;
+                finalUserContent = `${buildForcedSkillMessage(forcedSkill, {
+                    ...brandSkillVars({ identityName }),
+                    ...collectPackForcedSkillVars(chatId),
+                })}\n\n---\n\n${latestUserMessage}`;
             }
         }
         // W6-3 多模态：渲染进程把图片附件以 metadata.images（{path,name}）传上来，
@@ -2336,14 +2406,14 @@ export class LocalBackendRouter {
             .slice(0, MAX_REFERENCED_CHATS);
         const out = [];
         for (const refChatId of ids) {
-            const refChat = localStore.getChat(refChatId);
+            const refChat = await this.store.getChat(refChatId);
             if (!refChat) {
                 console.warn('[local-backend] referenced chat not found, skipping', { refChatId });
                 continue;
             }
             const sections = [];
-            const recent = (await Promise.all(localStore
-                .listMessages(refChatId, RECENT_MESSAGES_PER_CHAT)
+            const recent = (await Promise.all((await this.store
+                .listMessages(refChatId, RECENT_MESSAGES_PER_CHAT))
                 .reverse()
                 .map(async (item) => {
                 if (item.role !== 'user' && item.role !== 'assistant')
@@ -2718,7 +2788,7 @@ export class LocalBackendRouter {
         // empty list, so writes confine to system scratch dirs only.
         // `execPolicy: 'full'`（输入框「完整权限」）关闭这一层，让 mkdir
         // Downloads 这类项目外写入不再被 Seatbelt 拦成 Operation not permitted。
-        const chatProject = this.resolveChatProject(chatId);
+        const chatProject = await this.resolveChatProject(chatId);
         const execSandbox = buildExecSandbox([
             // 场景包声明的每会话可写根（如文档包在项目根之外落盘产物的
             // 工作区）。
@@ -2754,19 +2824,27 @@ export class LocalBackendRouter {
         // 下方的清除点，残留的标记就是「上次回复被中断」的签名（与活进程写下的
         // cancelled/failed 终态区分）。标记只覆盖「已交给 sidecar」的阶段：503
         // （sidecar 未运行）在上方已 return，record 里没有这一轮，无可续跑。
-        localStore.setTurnActive(chatId);
+        await this.store.setTurnActive(chatId);
         // 实时快照：executedActions / timeline / children 传引用（原地 mutate），
         // content 由 onText 逐段更新。切走再切回的 renderer 靠 GET /live-stream 读它。
         const live = registerLiveStream(chatId, { executedActions, timeline, children });
         // 场景包的回合观察器（如识别包技能调用并广播产物更新）。
         const packObservers = beginPackTurnObservers({ chatId, broadcast: this.broadcast ?? undefined });
+        // 回合产物文件列表（回合收尾时收集）：扫描根与 exec 沙箱可写根同源
+        // （项目根 + 包工作区），与沙箱是否启用无关——「完整权限」下根列表只是
+        // 不再被强制，产物仍大概率落在这里；根之外的显式写由工具参数并集补。
+        const turnStartedAtMs = Date.now();
+        const turnFileRoots = [
+            ...collectPackExecWritableRoots(chatId),
+            ...(chatProject ? [chatProject.folderPath] : []),
+        ];
         try {
             const coreLoopOptions = {
                 supervisor,
                 chatId,
                 // W5-2: after a regenerate-fork the chat's live record is the
                 // branch; undefined falls back to chatId on the sidecar.
-                recordId: localStore.getChatRecordId(chatId) ?? undefined,
+                recordId: await this.store.getChatRecordId(chatId) ?? undefined,
                 systemPrompt,
                 messages,
                 resume,
@@ -2950,14 +3028,14 @@ export class LocalBackendRouter {
                     : // resume 要求 messages 为空:记录是唯一权威，再喂一份历史会
                         // 静默分叉（sidecar 对此 fail loud）。
                         { ...coreLoopOptions, resume: true, messages: [] }),
-                afterPass: (outcome) => {
+                afterPass: async (outcome) => {
                     if (outcome.traceId)
                         passTraceIds.push(outcome.traceId);
                     // W6-9 用量归因:落一条 chat 用量事件(含成本估算,无单价模型 costUsd=null)。
                     // 每趟各落一条——续跑的花费是真实发生的，不该被合并掉。
                     if (outcome.usage) {
                         try {
-                            localStore.recordUsageEvent({
+                            await this.store.recordUsageEvent({
                                 chatId,
                                 kind: 'chat',
                                 provider: settings.provider,
@@ -3011,8 +3089,22 @@ export class LocalBackendRouter {
                 passTraceIds.push(failureTraceId);
             }
         }
-        const durationMs = turnDurationMs(localStore.getTurnActive(chatId)?.startedAt, Date.now());
-        const assistant = localStore.addMessage(chatId, 'assistant', assistantText, JSON.stringify({
+        const durationMs = turnDurationMs((await this.store.getTurnActive(chatId))?.startedAt, Date.now());
+        // 回合产物文件列表（成功/失败/取消都收集——半截回合写出的文件同样是
+        // 产物）。收集失败只记日志，永远不该拖垮回合收尾。
+        let turnFiles = [];
+        try {
+            turnFiles = await collectTurnFiles({
+                roots: turnFileRoots,
+                sinceMs: turnStartedAtMs,
+                actions: executedActions,
+                projectRoot: chatProject?.folderPath ?? null,
+            });
+        }
+        catch (turnFilesErr) {
+            console.warn('[local-backend] collect turn files failed', turnFilesErr);
+        }
+        const assistant = await this.store.addMessage(chatId, 'assistant', assistantText, JSON.stringify({
             completionStatus,
             completionReason,
             executedActions,
@@ -3022,9 +3114,10 @@ export class LocalBackendRouter {
             traceId: outcomeTraceId,
             ...(durationMs != null ? { durationMs } : {}),
             ...(autoContinuations > 0 ? { autoContinuations } : {}),
+            ...(turnFiles.length > 0 ? { turnFiles } : {}),
         }));
         try {
-            recordInsightTurn({
+            await recordInsightTurn(this.store, {
                 chatId,
                 mode: chatMode,
                 modelId: overrideModel || settings.model,
@@ -3041,7 +3134,7 @@ export class LocalBackendRouter {
         // W7-1: 回复落库后才清标记（顺序不能反——先清后写的话，两者之间崩溃
         // 会丢回复且无任何续跑入口；这个顺序的最坏情况是残留标记被检测器的
         // 「末尾已是 assistant」规则判定为已完结）。
-        localStore.clearTurnActive(chatId);
+        await this.store.clearTurnActive(chatId);
         // 回合落库即结束——移除实时快照，后续 GET /live-stream 返回 active=false。
         removeLiveStream(chatId);
         // Persist the sidecar-recorded traces into harness_traces so the CoreLoop
@@ -3050,7 +3143,7 @@ export class LocalBackendRouter {
         // 一趟一条:自动续跑的每一趟都是一次独立的 sidecar 运行,全部挂到本轮
         // 那条 assistant 消息上(message_id 无唯一约束),否则中间趟的 trace 就
         // 从消息侧不可达了。
-        const telemetry = localStore.getTelemetrySettings();
+        const telemetry = await this.store.getTelemetrySettings();
         for (const [index, traceId] of passTraceIds.entries()) {
             // 只有最后一趟携带本轮终态;之前每一趟都是撞墙截停才有下一趟。
             const passStatus = index === passTraceIds.length - 1 ? completionStatus : 'budget_exhausted';
@@ -3060,7 +3153,7 @@ export class LocalBackendRouter {
                 const durationMs = typeof sidecarTrace.durationMs === 'number'
                     ? sidecarTrace.durationMs
                     : null;
-                localStore.saveTrace({
+                await this.store.saveTrace({
                     id: traceId,
                     chatId,
                     messageId: assistant.id,
@@ -3094,11 +3187,65 @@ export class LocalBackendRouter {
                 });
             }
         }
+        // 产物文件列表赶在 message_id 之前发：前端按 message_id 把本轮队列
+        // 归档到落库消息上，顺序保证产物列表随同一批次归档。
+        if (turnFiles.length > 0) {
+            emit(this.sseData({ type: 'turn_files', files: turnFiles }));
+        }
         emit(this.sseData({ type: 'message_id', messageId: assistant.id }));
         emit('data: [DONE]\n\n');
         this.runTitleGenInBackground(chatId, shouldGenerateTitle, firstUserMessageForTitle);
+        this.runSuggestedRepliesInBackground({
+            chatId,
+            messageId: assistant.id,
+            userText: firstUserMessageForTitle,
+            assistantText,
+            completionStatus,
+        });
         return { status: 200 };
     }
+    /**
+     * 回合结束后生成 3 条下一轮用户输入建议。先同步推启发式兜底（芯片立刻出现），
+     * 再 fire-and-forget 跑 LLM，成功则替换。走 broadcast 而不是 SSE：`[DONE]`
+     * 之后渲染端已经不再监听这条流。
+     */
+    runSuggestedRepliesInBackground(args) {
+        const { chatId, messageId, userText, assistantText, completionStatus } = args;
+        if (completionStatus === 'cancelled' || completionStatus === 'failed')
+            return;
+        if (!assistantText.trim())
+            return;
+        const fallback = fallbackSuggestedReplies(userText, assistantText);
+        this.publishSuggestedReplies(chatId, messageId, fallback);
+        void (async () => {
+            try {
+                const result = await generateSuggestedReplies(userText, assistantText, {
+                    perAttemptTimeoutMs: 60_000,
+                });
+                if (result.usedFallback)
+                    return;
+                const same = result.suggestions.length === fallback.length &&
+                    result.suggestions.every((item, i) => item === fallback[i]);
+                if (same)
+                    return;
+                this.publishSuggestedReplies(chatId, messageId, result.suggestions);
+            }
+            catch (err) {
+                console.warn('[local-backend] suggested-replies failed', { chatId, err });
+            }
+        })();
+    }
+    async publishSuggestedReplies(chatId, messageId, suggestions) {
+        if (suggestions.length === 0)
+            return;
+        try {
+            await this.store.patchMessageMetadata(chatId, messageId, { suggestedReplies: suggestions });
+        }
+        catch (err) {
+            console.warn('[local-backend] suggested-replies persist failed', { chatId, messageId, err });
+        }
+        this.broadcast?.('suggested-replies', { chatId, messageId, suggestions });
+    }
     /**
      * 标准"匿名事件" SSE：不带 event 行，前端 SSEParser 会落到默认 onMessage 分支，
      * 用 parseSSEData 把 data 反序列化为 JSON 后用 type/content 字段路由。