@steerable/agent-shell-web 0.6.20 → 0.6.21

package/src/components/chat/path-mentions.ts

@@ -0,0 +1,148 @@
+/**
+ * 正文里提到的文件路径：识别 + 存在性解析缓存。
+ *
+ * 助手回答里的路径通常写在行内代码里（`` `./报告.docx` ``）。这里先用
+ * 廉价的形状判断挑出候选，再交给后端 stat 证伪——路径是模型写出来的自然
+ * 语言片段，形状判断必然有误报，只有后端确认存在的才会变成可点击。
+ *
+ * 缓存是模块级的：流式渲染期间同一个代码节点会重渲染很多次，没有缓存和
+ * 请求合并会把 resolve-paths 打成风暴。同一 (chatId, 字面量) 只解析一次，
+ * 同一批渲染里的多个候选合并成一次请求。
+ */
+
+import { resolveLocalPaths, type ResolvedLocalPath } from '@/lib/local-api';
+
+/** 协议前缀（http:// 等）不是本地路径。 */
+const URL_LIKE = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** `1.2.3` / `v0.6.20` 这类版本号会被「带扩展名的裸文件名」规则误收。 */
+const VERSION_LIKE = /^v?\d+(\.\d+)+$/;
+/** Windows 绝对路径：`C:\x` / `C:/x`。 */
+const WINDOWS_ABSOLUTE = /^[A-Za-z]:[\\/]/;
+/** 不含分隔符但带扩展名的裸文件名：`报告.docx`。 */
+const BARE_FILE_NAME = /^[^\\/<>:"|?*]+\.[A-Za-z0-9]{1,10}$/;
+
+/** 单条候选的长度上限（与后端一致）。 */
+const MAX_CANDIDATE_LENGTH = 512;
+
+/**
+ * 形状上像不像本地文件/目录路径。只做廉价判断，存在性由后端把关。
+ * 含空白的一律否决——行内代码里带空格的多是命令（`npm install`），
+ * 带空格的真实路径在正文里极少，误伤远小于把命令渲染成可点击。
+ */
+export function looksLikeFilePath(text: string): boolean {
+  const candidate = text.trim();
+  if (!candidate || candidate.length > MAX_CANDIDATE_LENGTH) return false;
+  if (/\s/.test(candidate)) return false;
+  if (URL_LIKE.test(candidate)) return false;
+  if (VERSION_LIKE.test(candidate)) return false;
+  if (candidate.startsWith('~/') || WINDOWS_ABSOLUTE.test(candidate)) return true;
+  if (candidate.includes('/')) return true;
+  return BARE_FILE_NAME.test(candidate);
+}
+
+/** null = 后端确认过但不存在（不可点击）；undefined = 还没解析。 */
+type CacheEntry = ResolvedLocalPath | null;
+
+const cache = new Map<string, CacheEntry>();
+const waiters = new Map<string, Set<(entry: CacheEntry) => void>>();
+const queued = new Map<string, Set<string>>();
+let flushHandle: ReturnType<typeof setTimeout> | null = null;
+
+function cacheKey(candidate: string, chatId: string): string {
+  return `${chatId}\u0000${candidate}`;
+}
+
+/** 已解析过就直接返回结果，否则返回 undefined（调用方需要订阅）。 */
+export function peekResolvedPath(
+  candidate: string,
+  chatId?: string | null,
+): CacheEntry | undefined {
+  return cache.get(cacheKey(candidate.trim(), chatId ?? ''));
+}
+
+/**
+ * 订阅一个候选的解析结果。已有缓存时同步回调；否则入队，同一批渲染的候选
+ * 合并成一次请求。返回取消订阅函数（组件卸载后不再回调）。
+ */
+export function subscribeResolvedPath(
+  candidate: string,
+  chatId: string | null | undefined,
+  onResolve: (entry: CacheEntry) => void,
+): () => void {
+  const trimmed = candidate.trim();
+  const scope = chatId ?? '';
+  const key = cacheKey(trimmed, scope);
+  const cached = cache.get(key);
+  if (cached !== undefined) {
+    onResolve(cached);
+    return () => {};
+  }
+
+  let listeners = waiters.get(key);
+  if (!listeners) {
+    listeners = new Set();
+    waiters.set(key, listeners);
+  }
+  listeners.add(onResolve);
+
+  let scoped = queued.get(scope);
+  if (!scoped) {
+    scoped = new Set();
+    queued.set(scope, scoped);
+  }
+  scoped.add(trimmed);
+  scheduleFlush();
+
+  return () => {
+    listeners?.delete(onResolve);
+  };
+}
+
+function scheduleFlush(): void {
+  if (flushHandle !== null) return;
+  flushHandle = setTimeout(() => {
+    flushHandle = null;
+    void flushQueued();
+  }, 0);
+}
+
+async function flushQueued(): Promise<void> {
+  const batches = [...queued.entries()];
+  queued.clear();
+  for (const [scope, candidates] of batches) {
+    const list = [...candidates];
+    if (list.length === 0) continue;
+    let resolved: ResolvedLocalPath[] = [];
+    try {
+      const response = await resolveLocalPaths(list, scope || null);
+      resolved = response.resolved ?? [];
+    } catch {
+      // 解析失败（后端不可达等）当作「不存在」落缓存：正文照旧渲染成
+      // 普通行内代码，不给用户一个点不开的假affordance。
+      resolved = [];
+    }
+    const byCandidate = new Map(resolved.map((item) => [item.candidate, item]));
+    for (const candidate of list) {
+      settle(cacheKey(candidate, scope), byCandidate.get(candidate) ?? null);
+    }
+  }
+}
+
+function settle(key: string, entry: CacheEntry): void {
+  cache.set(key, entry);
+  const listeners = waiters.get(key);
+  waiters.delete(key);
+  if (!listeners) return;
+  for (const listener of listeners) listener(entry);
+}
+
+/** 测试用：清空模块级缓存与待解析队列。 */
+export function resetPathMentionCache(): void {
+  cache.clear();
+  waiters.clear();
+  queued.clear();
+  if (flushHandle !== null) {
+    clearTimeout(flushHandle);
+    flushHandle = null;
+  }
+}

package/src/components/chat/suggested-replies-model.ts

@@ -0,0 +1,40 @@
+/**
+ * 从助手消息 metadata 读出持久化的追问建议（刷新后仍能画在最后一条回复下）。
+ */
+import type { ChatMessage } from '@steerable/agent-protocol';
+
+export interface SuggestedRepliesState {
+  messageId: string;
+  suggestions: string[];
+}
+
+function readSuggestedReplies(metadata: unknown): string[] | null {
+  if (typeof metadata !== 'string' || !metadata) return null;
+  try {
+    const parsed = JSON.parse(metadata) as { suggestedReplies?: unknown };
+    if (
+      Array.isArray(parsed.suggestedReplies) &&
+      parsed.suggestedReplies.length > 0 &&
+      parsed.suggestedReplies.every((item) => typeof item === 'string' && item.trim())
+    ) {
+      return parsed.suggestedReplies.map((item) => item.trim()).slice(0, 3);
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/** 从新→旧找最近一条带 suggestedReplies 的助手消息。 */
+export function extractLatestSuggestedReplies(
+  messages: Array<ChatMessage & { messageMetadata?: string | null }> | undefined,
+): SuggestedRepliesState | null {
+  if (!messages || messages.length === 0) return null;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    if (message.role !== 'assistant') continue;
+    const suggestions = readSuggestedReplies(message.messageMetadata);
+    if (suggestions) return { messageId: message.id, suggestions };
+  }
+  return null;
+}

package/src/components/chat/turn-files.ts

@@ -0,0 +1,50 @@
+/**
+ * 回合产物文件列表（「本轮写了哪些文件」）的前端模型。
+ *
+ * 数据源：local-backend 在回合收尾时扫描可写根 + 写工具参数并集（见
+ * `src/local-backend/turn-files.ts`），经 `turn_files` SSE 事件下发，并
+ * 持久化进助手消息的 messageMetadata（键 `turnFiles`）供刷新后水合。
+ */
+
+export interface TurnFile {
+  /** 绝对路径 —— 点击打开直接传给后端。 */
+  path: string;
+  /** created = 本轮新建；modified = 已有文件被改动。 */
+  kind: 'created' | 'modified';
+  /** 字节数（展示用，可缺省）。 */
+  size?: number;
+}
+
+/** 解析 SSE 事件 / 持久化元数据里的文件列表；形状不符返回 null（与 parseTurnBlocks 同约定）。 */
+export function parseTurnFiles(raw: unknown): TurnFile[] | null {
+  if (!Array.isArray(raw) || raw.length === 0) return null;
+  const files: TurnFile[] = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') return null;
+    const rec = item as Record<string, unknown>;
+    if (typeof rec.path !== 'string' || !rec.path) return null;
+    if (rec.kind !== 'created' && rec.kind !== 'modified') return null;
+    files.push({
+      path: rec.path,
+      kind: rec.kind,
+      ...(typeof rec.size === 'number' ? { size: rec.size } : {}),
+    });
+  }
+  return files;
+}
+
+/** 文件名的展示分段：basename 加粗、目录部分弱化。 */
+export function splitTurnFilePath(filePath: string): { dir: string; name: string } {
+  const normalized = filePath.replace(/[/\\]+$/, '');
+  const idx = Math.max(normalized.lastIndexOf('/'), normalized.lastIndexOf('\\'));
+  if (idx < 0) return { dir: '', name: normalized };
+  return { dir: normalized.slice(0, idx + 1), name: normalized.slice(idx + 1) };
+}
+
+/** 紧凑的字节数展示（不足 1 KB 显示 B）。 */
+export function formatFileSize(size: number | undefined): string | null {
+  if (size == null || !Number.isFinite(size) || size < 0) return null;
+  if (size < 1024) return `${size} B`;
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`;
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/layouts/AgentLayout.tsx

@@ -4,8 +4,8 @@ import { LuPanelLeftOpen } from 'react-icons/lu';
 import { AgentSidebar } from '@/components/AgentSidebar';
 import { TerminalPanel } from '@/components/TerminalPanel';
 import { TaskProcessPanel, type InspectedTask } from '@/components/chat/TaskProcessPanel';
-import { ApprovalModalHost } from '@/components/chat/ApprovalModal';
-import { AskUserModalHost } from '@/components/chat/AskUserModalHost';
+import { AskUserPromptProvider } from '@/components/chat/AskUserPromptProvider';
+import { ApprovalPromptProvider } from '@/components/chat/ApprovalPromptProvider';
 import { InsightsConsentBanner } from '@/components/settings/InsightsSettingsPanel';
 import { trackBehavior } from '@/lib/insights';
 import { getElectronBridge, isElectron } from '@/lib/electron-bridge';
@@ -32,9 +32,8 @@ import {
  *     view stays mounted while the user switches chats. Toggled from the
  *     sidebar 终端 button or Cmd+T (`menu:open-terminal`, subscribed in
  *     AgentSidebar). Open state + width persist to localStorage.
- *   - Auto-reveal: when the agent runs a shell command through the
- *     visible PTY, main broadcasts `terminal:reveal` and this layout
- *     opens the panel (idempotent) so the user watches the agent type.
+ *     Agent shell commands still run in the shared PTY; the panel is not
+ *     auto-opened when that happens.
  *   - Closing the panel only unmounts the xterm VIEW; the PTY session is
  *     a main-process singleton and keeps running. Reopening replays the
  *     output buffer via `terminal:ensure`.
@@ -89,7 +88,7 @@ export type AgentOutletContext = UseChatsAndAgentsResult & {
   inspectTask: (task: InspectedTask) => void;
 };
 
-export function AgentLayout() {
+function AgentLayoutContent() {
   const data = useChatsAndAgents();
   const { chatId } = useParams<{ chatId?: string }>();
 
@@ -370,20 +369,6 @@ export function AgentLayout() {
     persistRightPanel('terminal');
   }, [persistRightPanel]);
 
-  // Codex 式 auto-reveal：agent 的命令进入可见 PTY 时，main 广播
-  // `terminal:reveal`，这里自动展开终端面板。幂等——已打开时是 no-op；
-  // 用户手动关掉后，下一条命令会再次拉开（符合"看 agent 打字"的意图）。
-  useEffect(() => {
-    const bridge = getElectronBridge();
-    if (!bridge?.terminal?.onReveal) return;
-    return bridge.terminal.onReveal(() => {
-      setInspectedTask(null);
-      rightPanelRef.current = 'terminal';
-      setRightPanelState('terminal');
-      persistRightPanel('terminal');
-    });
-  }, [persistRightPanel]);
-
   // 包槽位的自动展开（如文档包：后端在本轮产出新设计稿时广播包事件）。
   // 互斥规则：仅当栏位空闲（null）时 reveal 才生效；
   // 已打开任一面板时，自动展开请求被忽略。订阅逻辑由包自己实现。
@@ -563,12 +548,16 @@ export function AgentLayout() {
           )}
         </div>
       </div>
-      {/* W4-1 审批弹窗挂在 layout 层而非 chat 视图：审批请求属于正在跑的
-          回合，回合不因用户切走页面而暂停——挂在 AgentChatView 下时，用户
-          导航到首页/别的对话会让模态永不渲染，请求只能等超时 fail-closed。 */}
-      {isElectron() && <ApprovalModalHost />}
-      {/* W8 提问卡片同理：挂在 layout 层，页面切换不丢待答问题。 */}
-      {isElectron() && <AskUserModalHost />}
     </div>
   );
 }
+
+export function AgentLayout() {
+  return (
+    <ApprovalPromptProvider>
+      <AskUserPromptProvider>
+        <AgentLayoutContent />
+      </AskUserPromptProvider>
+    </ApprovalPromptProvider>
+  );
+}

package/src/lib/browser-dev-electron-mock.ts

@@ -39,6 +39,10 @@ interface BrowserMockState {
   fixtureMeta: Pick<BrowserDevFixture, 'exportedAt' | 'source'> | null;
 }
 
+const suggestedReplyListeners = new Set<
+  (payload: { chatId: string; messageId: string; suggestions: string[] }) => void
+>();
+
 const USER_ID = 'browser-preview-user';
 const now = new Date();
 
@@ -576,6 +580,7 @@ async function startStream(
           { type: 'text', content: reply },
         ],
         durationMs: 1_200,
+        suggestedReplies: ['继续完善这份结果', '换一种呈现方式', '告诉我下一步怎么做'],
       }),
     });
     assistantMessage.createdAt = new Date().toISOString();
@@ -588,6 +593,10 @@ async function startStream(
     pushSse(onEvent, '[DONE]');
     onEvent({ type: 'end', status: 200 });
     state.activeStreams.delete(streamId);
+    const suggestions = ['继续完善这份结果', '换一种呈现方式', '告诉我下一步怎么做'];
+    for (const listener of suggestedReplyListeners) {
+      listener({ chatId, messageId: assistantMessage.id, suggestions });
+    }
   }, 440 + chunks.length * 80);
 
   return streamId;
@@ -629,6 +638,12 @@ export function installBrowserDevElectronMock() {
     onMenuOpenTerminal: () => undefined,
     offMenuOpenTerminal: () => undefined,
     onChatTitleUpdated: () => () => undefined,
+    onSuggestedReplies: (callback) => {
+      suggestedReplyListeners.add(callback);
+      return () => {
+        suggestedReplyListeners.delete(callback);
+      };
+    },
   } satisfies ElectronBridge;
 
   console.info(

package/src/lib/electron-bridge.ts

@@ -153,6 +153,17 @@ export interface ElectronBridge {
   onChatTitleUpdated?: (
     callback: (payload: { chatId: string; title: string }) => void,
   ) => () => void;
+  /**
+   * 回合追问建议就绪。Backend 在助手回复完成后推 `{chatId, messageId, suggestions}`
+   * （先启发式、后 LLM 替换）。返回解除订阅函数。
+   */
+  onSuggestedReplies?: (
+    callback: (payload: {
+      chatId: string;
+      messageId: string;
+      suggestions: string[];
+    }) => void,
+  ) => () => void;
   /**
    * 会话补建通知。Backend 在「向一个本地不存在的 chatId 首次发送」时按 URL
    * 里的 id 现场补建会话（见 router.handleStream），随后广播 `chat-created`
@@ -202,6 +213,7 @@ export interface ElectronBridge {
       kind: ApprovalDecisionKind;
       reason?: string;
     }) => Promise<void>;
+    pending: () => Promise<ApprovalPromptRequest[]>;
   };
   /**
    * W8 结构化提问：sidecar ask_user 工具的请示经主进程/BS 服务器广播到
@@ -214,6 +226,7 @@ export interface ElectronBridge {
       requestId: string;
       answers: Record<string, string | string[]>;
     }) => Promise<void>;
+    pending: () => Promise<AskUserPromptRequest[]>;
   };
   terminal?: {
     /** Ensures a session exists (reuses last one if alive). */
@@ -230,13 +243,6 @@ export interface ElectronBridge {
         signal: string | null;
       }) => void,
     ) => () => void;
-    /**
-     * agent 命令进入可见 PTY 时由 main 广播（`terminal:reveal`）——渲染端
-     * 据此自动展开内嵌终端面板（Codex 式 auto-reveal）。已打开时是 no-op。
-     */
-    onReveal: (
-      callback: (payload: { sessionId: string }) => void,
-    ) => () => void;
   };
   // 场景包的 invoke 命名空间（如包 preload 贡献的 `<pack>` / `<pack>Mock`）
   // 不进本接口——包用自己的结构化收窄访问器（见各包 web/bridge.ts），

package/src/lib/http-bridge.ts

@@ -241,6 +241,12 @@ export function createHttpBridge(): ElectronBridge {
     onChatTitleUpdated: (callback) =>
       subscribeChannel<{ chatId: string; title: string }>('chat-title-updated', callback),
 
+    onSuggestedReplies: (callback) =>
+      subscribeChannel<{ chatId: string; messageId: string; suggestions: string[] }>(
+        'suggested-replies',
+        callback,
+      ),
+
     onChatCreated: (callback) =>
       subscribeChannel<{ chatId: string; agentId?: string | null }>('chat-created', callback),
 
@@ -268,6 +274,7 @@ export function createHttpBridge(): ElectronBridge {
       decide: async (decision) => {
         await http('POST', '/host/approval/decide', decision);
       },
+      pending: () => http<ApprovalPromptRequest[]>('GET', '/host/approval/pending'),
     },
 
     askUser: {
@@ -276,6 +283,7 @@ export function createHttpBridge(): ElectronBridge {
       answer: async (reply) => {
         await http('POST', '/host/ask-user/answer', reply);
       },
+      pending: () => http<AskUserPromptRequest[]>('GET', '/host/ask-user/pending'),
     },
 
     terminal: {
@@ -289,8 +297,6 @@ export function createHttpBridge(): ElectronBridge {
           'terminal:exit',
           callback,
         ),
-      onReveal: (callback) =>
-        subscribeChannel<{ sessionId: string }>('terminal:reveal', callback),
     },
 
   };

package/src/lib/local-api.ts

@@ -332,6 +332,37 @@ export async function cancelChatTurn(chatId: string) {
   });
 }
 
+/**
+ * 用系统默认应用打开本地绝对路径（回合产物列表的点击行为）。
+ * 成功时后端返回 `{ success: true }`；打开失败返回 `{ success: false, error }`。
+ */
+export async function openLocalPath(targetPath: string) {
+  return bridge().localBackend.request<{ success: boolean; error?: string }>({
+    method: 'POST',
+    path: '/api/v2/local/open-path',
+    body: { path: targetPath },
+  });
+}
+
+/** 后端确认存在的路径：`candidate` 是正文里的原字面量，`path` 是落地绝对路径。 */
+export interface ResolvedLocalPath {
+  candidate: string;
+  path: string;
+  isDirectory: boolean;
+}
+
+/**
+ * 批量确认正文里提到的路径是否真实存在（用于决定行内代码要不要变成可点击）。
+ * 相对路径由后端按对话绑定的项目根解析，无项目时按 home；不存在的候选不回。
+ */
+export async function resolveLocalPaths(candidates: string[], chatId?: string | null) {
+  return bridge().localBackend.request<{ resolved: ResolvedLocalPath[] }>({
+    method: 'POST',
+    path: '/api/v2/local/resolve-paths',
+    body: { candidates, ...(chatId ? { chatId } : {}) },
+  });
+}
+
 /* ---------------- Projects（项目模式） ---------------- */
 
 export interface LocalProject {