@baique/pi-web-sky 0.1.55 → 0.1.57

package/lib/rpc-manager.ts

@@ -13,10 +13,26 @@ import {
   preferUserBashExtension,
 } from "./project-command-env";
 import { createTodoExtension } from "./todo-extension";
-import { cacheSessionPath, invalidateSessionListCache } from "./session-reader";
+import { createSubagentExtension, preferPiWebSubagentExtension } from "./subagent-extension";
+import { listSubagentProfiles, readSubagentRun, readSubagentSessionResources, SUBAGENT_CONTROL_TOOL_NAMES } from "./subagents";
+import { createSubagentController } from "./subagent-runtime";
+import { isBuiltInSubagentsEnabled } from "./subagent-settings";
+import { resolveShellTools } from "./powershell-settings";
+import { CHAT_ONLY_RESOURCE_LOADER_OPTIONS } from "./chat-only";
+import { cacheSessionPath, invalidateSessionListCache, resolveSessionPath } from "./session-reader";
+import { indexSessionFileNow } from "./session-index-scanner";
+import { createSessionActivityTracker, type AgentLikeMessage } from "./session-activity";
+import { FIRST_MESSAGE_PREVIEW_LENGTH } from "./session-scanner";
 import { projectIdentityKey } from "./project-identity";
 import { resolveProject } from "./worktree";
-import { ensureSessionMetaRow } from "./task-store";
+import {
+  ensureSessionMetaRow,
+  fillFirstMessageIfEmpty,
+  recordSessionOutcome,
+  setSessionTitle,
+  taskForSession,
+  touchSessionActivity,
+} from "./task-store";
 import { reconcileForkBoard } from "./board-reconcile";
 import { getProjectTrustStatus, projectTrustReloadOptions } from "./project-trust";
 import { persistExplicitStartupPreferences } from "./startup-preferences";
@@ -27,6 +43,7 @@ import type {
   ExtensionUiRequest,
   ExtensionUiResponse,
   ExtensionWidgetItem,
+  SessionEntry,
   SessionInfo,
   SessionMessageEntry,
 } from "./types";
@@ -97,6 +114,11 @@ type ExtensionBindingOptions = {
   forceEmptySystemPrompt?: boolean;
 };
 
+type AgentSessionWrapperOptions = {
+  exactSystemPrompt?: () => string;
+  chatOnly?: boolean;
+};
+
 const IDLE_RESET_EVENT_TYPES = new Set([
   "agent_end",
   "agent_settled",
@@ -104,6 +126,28 @@ const IDLE_RESET_EVENT_TYPES = new Set([
   "compaction_end",
 ]);
 
+const DEFAULT_SESSION_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * Resolves the PI_WEB_IDLE_TIMEOUT_MS environment variable into a session idle
+ * timeout in milliseconds. An unset/blank value returns the 10-minute default,
+ * `0` disables idle shutdown, and positive values up to Node's timer limit
+ * (2147483647 ms) are used as-is. Invalid or out-of-range values fall back to
+ * the default with a console warning.
+ */
+export function resolveSessionIdleTimeoutMs(
+  rawValue: string | undefined = process.env.PI_WEB_IDLE_TIMEOUT_MS,
+): number {
+  if (rawValue !== undefined && rawValue.trim() !== "") {
+    const parsed = Number(rawValue);
+    if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 2_147_483_647) return parsed;
+    console.warn(`[pi-web] invalid PI_WEB_IDLE_TIMEOUT_MS "${rawValue}", falling back to 10 minutes`);
+  }
+  return DEFAULT_SESSION_IDLE_TIMEOUT_MS;
+}
+
+const SESSION_IDLE_TIMEOUT_MS = resolveSessionIdleTimeoutMs();
+
 export interface RpcSessionStartOptions {
   toolNames?: string[];
   initialModel?: { provider: string; modelId: string };
@@ -180,8 +224,17 @@ export class AgentSessionWrapper {
   private _alive = true;
   /** 最近一次 agent_start 的时间（看板“运行时长”用）；0 = 未知 */
   private lastAgentStart = 0;
-
-  constructor(public readonly inner: AgentSessionLike) {}
+  /** 会话活跃事件 → 落库（last_reply / modified）；按 wrapper 实例持有防并发串台 */
+  private readonly activityTracker = createSessionActivityTracker();
+  private readonly exactSystemPrompt?: () => string;
+  private readonly chatOnly: boolean;
+
+  constructor(public readonly inner: AgentSessionLike, options: AgentSessionWrapperOptions = {}) {
+    this.exactSystemPrompt = options.exactSystemPrompt;
+    this.chatOnly = options.chatOnly ?? false;
+    this.installExactSystemPromptContinuation();
+    this.applyExactSystemPrompt();
+  }
 
   /** 是否有等待用户响应的扩展 UI 请求（waiting_input 判定用） */
   hasPendingUiRequest(): boolean {
@@ -217,6 +270,10 @@ export class AgentSessionWrapper {
     return this._alive;
   }
 
+  isChatOnly(): boolean {
+    return this.chatOnly;
+  }
+
   isRunning(): boolean {
     return this._alive && (this.pendingPromptCount > 0 || this.inner.isStreaming || this.inner.isCompacting || this.inner.isBashRunning);
   }
@@ -230,11 +287,42 @@ export class AgentSessionWrapper {
         invalidateSessionListCache();
       }
       if (IDLE_RESET_EVENT_TYPES.has(event.type)) this.resetIdleTimer();
+      // 会话活跃落库（last_reply / modified）。包在 try/catch 里：库是旁路索引，
+      // 写失败必须可见（console.error），但绝不能打断上面几件事与事件分发。
+      try {
+        this.persistSessionActivity(event);
+      } catch (error) {
+        console.error(
+          `[pi-web] 会话活跃写库失败（${event.type}）:`,
+          error instanceof Error ? error.message : String(error),
+        );
+      }
       this.emit(event);
     });
     this.resetIdleTimer();
   }
 
+  /**
+   * 事件 → session_meta 写入（只 UPDATE；行由创建/扫描链路建立）：
+   *   · agent_start   → modified 前移（运行中会话浮顶）
+   *   · message_end   → 本轮最后一条 assistant 文本（缓存，不落库）
+   *   · agent_settled → last_reply + modified（一轮循环真正结束；用户取消走同一路径）
+   * 用 agent_settled 而非 agent_end：后者一轮里可能多次（重试/compaction/queue 续跑）。
+   */
+  private persistSessionActivity(event: AgentEvent): void {
+    const effect = this.activityTracker.handle(event as { type: string; message?: AgentLikeMessage });
+    if (!effect) return;
+    const sessionId = this.inner.sessionId;
+    if (!sessionId) return;
+    if (effect.kind === "touch") {
+      touchSessionActivity(sessionId);
+      return;
+    }
+    recordSessionOutcome(sessionId, effect);
+    // 首条用户消息此刻已在内存 entries 里（不读文件，读取路径零扫盘）。
+    fillFirstMessageIfEmpty(sessionId, firstUserMessageOf(this.inner.sessionManager.getEntries()));
+  }
+
   setForceEmptySystemPrompt(force: boolean): void {
     this.forceEmptySystemPrompt = force;
     this.applyForcedEmptySystemPrompt();
@@ -250,10 +338,31 @@ export class AgentSessionWrapper {
     await this.waitForExtensionsBound();
   }
 
+  private applyExactSystemPrompt(): void {
+    if (!this.exactSystemPrompt || !this.inner.agent.state) return;
+    this.inner.agent.state.systemPrompt = this.exactSystemPrompt();
+  }
+
+  private installExactSystemPromptContinuation(): void {
+    if (!this.exactSystemPrompt) return;
+    const previous = this.inner.agent.prepareNextTurnWithContext;
+    this.inner.agent.prepareNextTurnWithContext = async (turn, signal) => {
+      const prepared = await previous?.(turn, signal);
+      return {
+        ...prepared,
+        context: {
+          ...(prepared?.context ?? turn.context),
+          systemPrompt: this.exactSystemPrompt!(),
+        },
+      };
+    };
+  }
+
   private ensureExtensionsBound(options: ExtensionBindingOptions = {}): Promise<void> {
     if (options.forceEmptySystemPrompt) this.forceEmptySystemPrompt = true;
     if (this.extensionsBound) {
       this.applyForcedEmptySystemPrompt();
+      this.applyExactSystemPrompt();
       return Promise.resolve();
     }
     if (this.extensionBindingPromise) return this.extensionBindingPromise;
@@ -293,6 +402,7 @@ export class AgentSessionWrapper {
       }
       this.extensionsBound = true;
       this.applyForcedEmptySystemPrompt();
+      this.applyExactSystemPrompt();
       console.log(`[pi-web] session_start dispatched to extensions for session ${this.inner.sessionId}`);
     })().catch((err) => {
       this.extensionBindingError = err;
@@ -361,6 +471,8 @@ export class AgentSessionWrapper {
   }
 
   private resetIdleTimer(): void {
+    // A resolved timeout of 0 disables idle shutdown entirely.
+    if (SESSION_IDLE_TIMEOUT_MS === 0) return;
     if (this.idleTimer) clearTimeout(this.idleTimer);
     this.idleTimer = setTimeout(() => {
       if (this.isRunning()) {
@@ -370,7 +482,7 @@ export class AgentSessionWrapper {
       void this.shutdown().catch((error) => {
         console.error("[pi-web] failed to shut down idle session:", error instanceof Error ? error.message : error);
       });
-    }, 10 * 60 * 1000);
+    }, SESSION_IDLE_TIMEOUT_MS);
   }
 
   onEvent(listener: EventListener): () => void {
@@ -531,6 +643,42 @@ export class AgentSessionWrapper {
         return { id: model.id, provider: model.provider };
       }
 
+      case "fork_branch": {
+        if (this.isRunning()) {
+          throw new Error("Cannot fork while the session is running");
+        }
+        const entryId = command.entryId as string;
+        const sessionManager = this.inner.sessionManager;
+        const currentSessionFile = this.inner.sessionFile;
+        if (!sessionManager.isPersisted()) return { cancelled: true };
+        if (!currentSessionFile) throw new Error("Persisted session is missing a session file");
+        if (!sessionManager.getEntry(entryId)) throw new Error("Invalid entry ID for forking");
+
+        const sessionDir = sessionManager.getSessionDir();
+        const sourceManager = SessionManager.open(currentSessionFile, sessionDir);
+        const forkedPath = sourceManager.createBranchedSession(entryId);
+        if (!forkedPath) throw new Error("Failed to create forked session");
+        // SDK 惰性落盘契约：fork 点之前无 assistant 消息时不写文件（flushed=false），
+        // 只返回路径字符串。不强制落盘则后续 open 不存在文件会 newSession 生成新 id，
+        // 索引/列表/看板全部读不到——必须和 fork case 一样手动写盘。
+        if (!existsSync(forkedPath)) {
+          const content = [sourceManager.getHeader(), ...sourceManager.getEntries()]
+            .map((entry) => JSON.stringify(entry))
+            .join("\n") + "\n";
+          writeFileSync(forkedPath, content, { encoding: "utf8", flag: "wx" });
+          (sourceManager as unknown as { flushed: boolean }).flushed = true;
+        }
+
+        const newSessionId = SessionManager.open(forkedPath, sessionDir).getSessionId();
+        cacheSessionPath(newSessionId, forkedPath);
+        invalidateSessionListCache();
+        // 立即进 session_meta 索引（否则要等 30s 后台扫描才出现在会话列表）；
+        // 归属继承：引用分支与源会话同任务（否则只会在聊天区当孤儿根出现）。
+        const sourceSessionId = sessionManager.getSessionId();
+        await indexSessionFileNow(forkedPath, sourceSessionId, taskForSession(sourceSessionId));
+        return { cancelled: false, newSessionId };
+      }
+
       case "fork": {
         if (this.inner.isBashRunning) {
           throw new Error("Cannot fork while a shell command is running");
@@ -590,6 +738,7 @@ export class AgentSessionWrapper {
         // resolveProject 的 await 不能发生在 registry 还挂着已 fork wrapper 的窗口里；
         // 建行只用局部变量（cwd/newSessionFile/sourceSessionId），不依赖 wrapper。
         const cwd = sessionManager.getCwd();
+        const sourceTaskId = taskForSession(sourceSessionId); // 归属继承：fork 子会话与父同任务
         await this.shutdown();
         try {
           const project = await resolveProject(cwd ?? "");
@@ -598,13 +747,28 @@ export class AgentSessionWrapper {
             cwd: cwd ?? "",
             projectKey: projectIdentityKey(project?.projectRoot ?? cwd ?? ""),
             parentId: sourceSessionId,
+            taskId: sourceTaskId, // 建行即带归属，否则子会话先以临时会话落在聊天区（V1）
           });
+        } catch (error) {
+          // 不阻塞 fork（文件已经在了，pi 侧已成功），但必须可见：静默失败会让子会话
+          // 以「无归属临时会话」出现在聊天区（也是本次要修的 V1 病灶）；扫描器的归属
+          // 收敛是第二道网，不能当成唯一防线。
+          console.error(
+            `[pi-web] fork 建行失败 session=${newSessionId}:`,
+            error instanceof Error ? error.message : String(error),
+          );
+        }
+        try {
           // fork 卡即时入板：源会话归属任务 → 精准 reconcile 该任务看板。
           // await 保证卡先落 yjs 再返回（前端响应到达时卡已存在，无并发写窗口）；
-          // 失败不阻塞 fork，10s 定时兜底。
+          // 失败不阻塞 fork，10s 定时兜底。单独一个 try：与建行失败分开报错，避免
+          // 入板失败被误报成「建行失败」。
           await reconcileForkBoard(sourceSessionId);
-        } catch {
-          // 建行失败不阻塞 fork：扫描器下一轮兜底补行。
+        } catch (error) {
+          console.error(
+            `[pi-web] fork 入板失败 source=${sourceSessionId}:`,
+            error instanceof Error ? error.message : String(error),
+          );
         }
         return { cancelled: false, newSessionId };
       }
@@ -644,6 +808,15 @@ export class AgentSessionWrapper {
         const name = (command.name as string | undefined)?.trim();
         if (!name) throw new Error("Session name cannot be empty");
         this.inner.setSessionName(name);
+        // 列表索引同步：pi 侧改名成功即写 session_meta.title（前端侧栏/看板卡
+        // 改名走这条 RPC，不落库则刷新后退回旧标题）。失败处理与路由层同源但
+        // 语义有别：这里只记日志、不抛——RPC 已经改了文件名，抛错对调用方没有
+        // 可恢复动作，还会断掉命令响应/事件流。
+        try {
+          await setSessionTitle(this.inner.sessionId, name);
+        } catch (error) {
+          console.error("[pi-web] 会话标题写库失败:", error);
+        }
         invalidateSessionListCache();
         return null;
       }
@@ -685,9 +858,10 @@ export class AgentSessionWrapper {
       case "get_tools": {
         const all: ToolInfo[] = this.inner.getAllTools();
         const active = new Set<string>(this.inner.getActiveToolNames());
+        // 对齐上游：展开整个 ToolInfo（含 parameters / promptGuidelines），
+        // 之前只挑 name/description/active 会把参数 schema 丢掉 → 面板参数全是“无”。
         return all.map((t) => ({
-          name: t.name,
-          description: t.description,
+          ...t,
           active: active.has(t.name),
         }));
       }
@@ -723,6 +897,9 @@ export class AgentSessionWrapper {
 
       case "set_tools": {
         const toolNames = command.toolNames as string[];
+        if (readSubagentSessionResources(this.inner.sessionManager.getEntries() as unknown as SessionEntry[])) {
+          throw new Error("Subagent tool selection is fixed by its profile");
+        }
         this.setForceEmptySystemPrompt(toolNames.length === 0);
         this.inner.setActiveToolsByName(withExtensionTools(this.inner, toolNames));
         this.applyForcedEmptySystemPrompt();
@@ -1468,8 +1645,13 @@ async function persistNewSessionFile(manager: SessionManager, sessionId: string)
       // 与扫描器同源归一化（Windows 大小写折叠等），防新建会话 project_key 与列表查询键不一致
       projectKey: projectIdentityKey(project?.projectRoot ?? cwd ?? ""),
     });
-  } catch {
-    // 建行失败不阻塞开会话：扫描器下一轮兜底补行。
+  } catch (error) {
+    // 建行失败不阻塞开会话（文件已落盘，运行时列表由 runtime union 覆盖），但必须可见：
+    // 静默会让该会话最多 30s 不在列表/任务区（扫描器会补行，但不能当成唯一防线）。
+    console.error(
+      `[pi-web] 新会话建行失败 session=${sessionId}:`,
+      error instanceof Error ? error.message : String(error),
+    );
   }
 }
 
@@ -1487,6 +1669,19 @@ function runtimeMessageText(entry: SessionMessageEntry): string {
     .join(" ");
 }
 
+/**
+ * 内存 entries 里首条用户消息的简述（截断与扫描器同一上限）。
+ * 会话活跃事件落库时用它回填 first_message——读取路径不再读文件。
+ */
+function firstUserMessageOf(entries: unknown[]): string {
+  for (const entry of entries as SessionMessageEntry[]) {
+    if (entry?.type !== "message" || entry.message?.role !== "user") continue;
+    const text = runtimeMessageText(entry).trim();
+    if (text) return text.slice(0, FIRST_MESSAGE_PREVIEW_LENGTH);
+  }
+  return "";
+}
+
 function runtimeMessageActivityMs(entry: SessionMessageEntry): number | undefined {
   if (entry.message.role !== "user" && entry.message.role !== "assistant") return undefined;
   if (typeof entry.message.timestamp === "number") return entry.message.timestamp;
@@ -1518,6 +1713,8 @@ export function getRpcSessionInfos(): SessionInfo[] {
     // loads commands. Do not leak it into history before a prompt is accepted.
     if (!persisted && (!session.isRunning() || !firstUserMessage)) continue;
 
+    const subagent = readSubagentRun(entries as unknown as SessionEntry[], header?.id ?? session.sessionId, sessionFile ?? "");
+
     const created = header?.timestamp
       ?? entries[0]?.timestamp
       ?? new Date().toISOString();
@@ -1537,6 +1734,16 @@ export function getRpcSessionInfos(): SessionInfo[] {
       modified: new Date(lastActivityMs).toISOString(),
       messageCount: messages.length,
       firstMessage: firstUserMessage ? runtimeMessageText(firstUserMessage) || "(no messages)" : "(no messages)",
+      ...(subagent ? {
+        parentSessionId: subagent.parentSessionId,
+        relation: {
+          kind: "subagent" as const,
+          parentSessionId: subagent.parentSessionId,
+          profile: subagent.profile,
+          description: subagent.description,
+          status: session.isRunning() ? "running" as const : subagent.status,
+        },
+      } : {}),
       transient: !persisted,
     });
   }
@@ -1646,14 +1853,25 @@ export async function startRpcSession(
   const sessionCwd = sessionManager.getCwd();
   const finishStartingSession = trackStartingSession(sessionCwd);
   const starting = (async () => {
+    // subagent 会话（含恢复）按 profile 的资源/工具加载选项重建；普通会话不命中。
+    const subagentResources = sessionFile
+      ? readSubagentSessionResources(sessionManager.getEntries() as unknown as SessionEntry[])
+      : null;
+    const subagentLoadsResources = Boolean(subagentResources?.loadExtensions || subagentResources?.loadSkills);
+    // chatOnly 仅当“显式空工具列表”时为真：subagent 会话按 profile 的 tools 判定，
+    // 普通会话按调用方传入的 toolNames（undefined = 默认全量，[] = 全关）。
+    const chatOnly = subagentResources
+      ? subagentResources.tools.length === 0 && !subagentLoadsResources
+      : toolNames?.length === 0;
+
     // Some extensions access the SDK's global theme even outside the terminal UI.
-    initTheme();
+    if (!chatOnly) initTheme();
     const agentDir = getAgentDir();
 
     // Determine which tools to pass based on requested toolNames.
     // Since v0.68.0, session creation expects string[] tool names instead of Tool[] instances.
-    let toolsOption: string[] | undefined;
-    if (toolNames !== undefined) {
+    let toolsOption: string[] | undefined = subagentResources?.tools;
+    if (!subagentResources && toolNames !== undefined) {
       // toolNames === [] -> "all off" (an empty allow-list disables every tool).
       // Otherwise DO NOT pass a builtin-only allow-list: passing CODING_TOOL_NAMES
       // set allowedToolNames to coding builtins only, which filtered every
@@ -1674,18 +1892,37 @@ export async function startRpcSession(
       cwd: sessionCwd,
       agentDir,
       settingsManager,
-      resourceLoaderOptions: {
-        extensionFactories: [
-          createProjectCommandBashExtension({
-            cwd: sessionCwd,
-            settings: settingsManager,
-          }),
-          // 内建会话 TODO（工具 + pi-todo.state 快照），装 pi-web-sky 即自带，
-          // 无需用户安装任何 pi 包。工具重名时用户扩展优先（见 pi-todo 文档）。
-          createTodoExtension(),
-        ],
-        extensionsOverride: preferUserBashExtension,
-      },
+      resourceLoaderOptions: subagentResources
+        ? {
+            noExtensions: !subagentResources.loadExtensions,
+            noSkills: !subagentResources.loadSkills,
+            noPromptTemplates: true,
+            noThemes: true,
+            noContextFiles: true,
+            systemPrompt: " ",
+            appendSystemPrompt: subagentResources.appendSystemPrompt,
+          }
+        : chatOnly
+          ? CHAT_ONLY_RESOURCE_LOADER_OPTIONS
+          : {
+              extensionFactories: [
+                createProjectCommandBashExtension({
+                  cwd: sessionCwd,
+                  settings: settingsManager,
+                }),
+                // 内建会话 TODO（工具 + pi-todo.state 快照），装 pi-web-sky 即自带，
+                // 无需用户安装任何 pi 包。工具重名时用户扩展优先（见 pi-todo 文档）。
+                createTodoExtension(),
+                // 内置 subagent（Agent/steer_subagent/get_subagent_result 工具），
+                // 开关见 agents 设置（isBuiltInSubagentsEnabled）。
+                createSubagentExtension(
+                  SUBAGENT_CONTROLLER.extensionRuntime,
+                  () => listSubagentProfiles(sessionCwd),
+                  isBuiltInSubagentsEnabled,
+                ),
+              ],
+              extensionsOverride: (base) => preferUserBashExtension(preferPiWebSubagentExtension(base)),
+            },
       ...(trustReloadOptions ? { resourceLoaderReloadOptions: trustReloadOptions } : {}),
     });
     const scope = await resolveVisibleModels(
@@ -1751,7 +1988,7 @@ export async function startRpcSession(
 
     wrapper.onDestroy(() => registry.delete(realSessionId));
     registry.set(realSessionId, wrapper);
-    wrapper.beginExtensionBinding({ forceEmptySystemPrompt: toolNames?.length === 0 });
+    if (!chatOnly) wrapper.beginExtensionBinding({ forceEmptySystemPrompt: toolNames?.length === 0 });
 
     return { session: wrapper, realSessionId };
   })().finally(() => {
@@ -1762,3 +1999,39 @@ export async function startRpcSession(
   locks.set(sessionId, starting);
   return starting;
 }
+
+const SUBAGENT_CONTROLLER = createSubagentController({
+  getSession: (sessionId) => getRegistry().get(sessionId),
+  registerSession: (inner, options) => {
+    const wrapper = new AgentSessionWrapper(inner, {
+      ...(options?.exactSystemPrompt !== undefined
+        ? { exactSystemPrompt: () => options.exactSystemPrompt! }
+        : {}),
+      chatOnly: options?.chatOnly,
+    });
+    const realSessionId = inner.sessionId as string;
+    const realSessionFile = inner.sessionFile as string | undefined;
+    if (realSessionFile) cacheSessionPath(realSessionId, realSessionFile);
+    wrapper.onDestroy(() => getRegistry().delete(realSessionId));
+    getRegistry().set(realSessionId, wrapper);
+    wrapper.start();
+    if (!wrapper.isChatOnly()) wrapper.beginExtensionBinding();
+  },
+  reopenSession: async (sessionId, sessionFile) =>
+    (await startRpcSession(sessionId, sessionFile, undefined)).session,
+  resolveSessionPath,
+  invalidateSessionList: invalidateSessionListCache,
+  isBuiltInSubagentsEnabled,
+});
+
+export function getSubagentRun(sessionId: string) {
+  return SUBAGENT_CONTROLLER.get(sessionId);
+}
+
+export function steerSubagent(sessionId: string, message: string) {
+  return SUBAGENT_CONTROLLER.steer(sessionId, message);
+}
+
+export function abortSubagent(sessionId: string) {
+  return SUBAGENT_CONTROLLER.abort(sessionId);
+}

package/lib/session-activity.test.mjs

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, {
+  interopDefault: true,
+  moduleCache: false,
+  alias: { "@": process.cwd() },
+});
+const { createSessionActivityTracker, lastAssistantText } = await jiti.import("./session-activity.ts");
+
+const assistant = (text, ts, stopReason = "stop") => ({
+  role: "assistant",
+  timestamp: ts,
+  stopReason,
+  content: [{ type: "text", text }],
+});
+
+/** 依次喂事件，返回所有非 null 效果（真实调用方的用法：一轮事件流按序处理）。 */
+function run(events) {
+  const tracker = createSessionActivityTracker();
+  const effects = [];
+  for (const event of events) {
+    const effect = tracker.handle(event);
+    if (effect) effects.push(effect);
+  }
+  return effects;
+}
+
+test("agent_start → touch（只刷活跃时间，浮动到列表顶部）", () => {
+  assert.deepEqual(run([{ type: "agent_start" }]), [{ kind: "touch" }]);
+});
+
+test("单条 message_end 不落 outcome（不是循环最后一条）", () => {
+  assert.deepEqual(run([{ type: "message_end", message: assistant("中间回复", 1000) }]), []);
+});
+
+test("agent_settled → outcome（带最后一条 assistant 文本与时间戳）", () => {
+  const effects = run([
+    { type: "message_end", message: assistant("第一条", 1000) },
+    { type: "message_end", message: { role: "user", content: "再问" } },
+    { type: "message_end", message: assistant("最后一条回复", 2000) },
+    { type: "agent_settled" },
+  ]);
+  assert.deepEqual(effects, [{ kind: "outcome", lastReply: "最后一条回复", at: 2000 }]);
+});
+
+test("用户取消（stopReason=aborted）同样落 outcome", () => {
+  const effects = run([
+    { type: "message_end", message: assistant("被打断的半截回复", 3000, "aborted") },
+    { type: "agent_settled" },
+  ]);
+  assert.deepEqual(effects, [{ kind: "outcome", lastReply: "被打断的半截回复", at: 3000 }]);
+});
+
+test("本轮没采到任何文本 → 只 touch（空文本不清库）", () => {
+  // 刚发出就被取消 / 整轮只有工具调用：agent_settled 不得产出 lastReply:""，
+  // 否则调用方会把已存的最后一条回复清空。
+  assert.deepEqual(run([{ type: "agent_start" }, { type: "agent_settled" }]), [
+    { kind: "touch" },
+    { kind: "touch" },
+  ]);
+  assert.deepEqual(
+    run([
+      { type: "message_end", message: { role: "assistant", timestamp: 1, content: [{ type: "toolCall", name: "bash" }] } },
+      { type: "message_end", message: { role: "assistant", timestamp: 2, content: [{ type: "thinking", thinking: "想一想" }] } },
+      { type: "message_end", message: { role: "assistant", timestamp: 3, content: [{ type: "text", text: "   " }] } },
+      { type: "agent_settled" },
+    ]),
+    [{ kind: "touch" }],
+  );
+});
+
+test("settle 后 pending 归零：第二段 settle（无新消息）只 touch", () => {
+  const tracker = createSessionActivityTracker();
+  tracker.handle({ type: "message_end", message: assistant("回复", 1000) });
+  assert.deepEqual(tracker.handle({ type: "agent_settled" }), {
+    kind: "outcome",
+    lastReply: "回复",
+    at: 1000,
+  });
+  assert.deepEqual(tracker.handle({ type: "agent_settled" }), { kind: "touch" });
+});
+
+test("tracker 按实例持有状态：并发会话不串台", () => {
+  const a = createSessionActivityTracker();
+  const b = createSessionActivityTracker();
+  a.handle({ type: "message_end", message: assistant("A 的回复", 1000) });
+  b.handle({ type: "message_end", message: assistant("B 的回复", 2000) });
+  assert.deepEqual(b.handle({ type: "agent_settled" }), {
+    kind: "outcome",
+    lastReply: "B 的回复",
+    at: 2000,
+  });
+  assert.deepEqual(a.handle({ type: "agent_settled" }), {
+    kind: "outcome",
+    lastReply: "A 的回复",
+    at: 1000,
+  });
+});
+
+test("无关事件（tool_execution_end 等）不产生效果，也不破坏 pending", () => {
+  const effects = run([
+    { type: "message_end", message: assistant("回复", 1000) },
+    { type: "tool_execution_start", toolName: "bash" },
+    { type: "queue_update", steering: [] },
+    { type: "agent_settled" },
+  ]);
+  assert.deepEqual(effects, [{ kind: "outcome", lastReply: "回复", at: 1000 }]);
+});
+
+test("lastAssistantText：只取 text 块，thinking/toolCall 忽略", () => {
+  assert.equal(
+    lastAssistantText({
+      role: "assistant",
+      content: [{ type: "thinking", thinking: "x" }, { type: "text", text: "a" }, { type: "text", text: "b" }],
+    }),
+    "a\nb",
+  );
+  assert.equal(lastAssistantText({ role: "assistant", content: "plain" }), "plain");
+  assert.equal(lastAssistantText({ role: "assistant" }), "");
+  assert.equal(lastAssistantText({ role: "assistant", content: [{ type: "text", text: "  " }] }), "");
+});