@downcity/agent 1.1.208 → 1.1.210

package/src/plugin/types/PluginApi.ts

@@ -7,70 +7,13 @@
  */
 
 import type { JsonValue } from "@/types/common/Json.js";
+import type {
+  PluginAvailability,
+  PluginView,
+} from "@/types/plugin/PluginRuntime.js";
 
-/**
- * Plugin 概览视图。
- */
-export interface PluginView {
-  /**
-   * Plugin 稳定名称。
-   */
-  name: string;
-  /**
-   * Plugin 展示标题。
-   */
-  title: string;
-  /**
-   * Plugin 面向人类的用途说明。
-   */
-  description: string;
-  /**
-   * 已声明的 Action 名称列表。
-   */
-  actions: string[];
-  /**
-   * 已声明的 pipeline 点名称列表。
-   */
-  pipelines: string[];
-  /**
-   * 已声明的 guard 点名称列表。
-   */
-  guards: string[];
-  /**
-   * 已声明的 effect 点名称列表。
-   */
-  effects: string[];
-  /**
-   * 已声明的 resolve 点名称列表。
-   */
-  resolves: string[];
-  /**
-   * 是否声明了 system 注入。
-   */
-  hasSystem: boolean;
-  /**
-   * 是否声明了 availability 检查。
-   */
-  hasAvailability: boolean;
-}
-
-/**
- * Plugin 可用性响应视图。
- */
-export interface PluginAvailabilityView {
-  /**
-   * Plugin 是否启用。
-   */
-  enabled: boolean;
-  /**
-   * Plugin 当前是否可用。
-   */
-  available: boolean;
-  /**
-   * 不可用原因列表。
-   */
-  reasons: string[];
-}
+export type { PluginView } from "@/types/plugin/PluginRuntime.js";
+export type PluginAvailabilityView = PluginAvailability;
 
 /**
  * plugin catalog 响应。
@@ -141,21 +84,3 @@ export interface PluginActionResponse {
    */
   error?: string;
 }
-
-/**
- * plugin CLI 通用选项。
- */
-export interface PluginCliBaseOptions {
- /**
-  * agent 项目路径（默认当前目录）。
-  */
-  path?: string;
-  /**
-   * 是否输出 JSON。
-   */
-  json?: boolean;
-  /**
-   * agent id（从 managed agent registry 解析到项目路径）。
-   */
-  agent?: string;
-}

package/src/rpc/Client.ts

@@ -19,21 +19,22 @@ import type {
   AgentSessionRecordsInput,
   AgentSessionRecordsPage,
   AgentSessionInfo,
-  AgentSessionStopResult,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
 import type { JsonValue } from "@/types/common/Json.js";
 import type { JsonObject } from "@/types/common/Json.js";
+import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type {
   PluginActionResult,
-  PluginAvailability,
-  PluginCommandResult,
-  PluginStateControlAction,
-  PluginStateControlResult,
-  PluginStateSnapshot,
-  PluginView,
-} from "@/plugin/types/Plugin.js";
+} from "@/types/plugin/PluginAction.js";
+import type { PluginCommandResult } from "@/types/plugin/PluginCommand.js";
+import type { PluginAvailability, PluginView } from "@/types/plugin/PluginRuntime.js";
+import type {
+  PluginControlAction,
+  PluginControlResult,
+  PluginSnapshot,
+} from "@/types/plugin/PluginState.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
@@ -66,6 +67,8 @@ type PendingRequest = {
 type RpcSubscription = {
   on_ready: () => void;
   on_event: (event: AgentSessionEvent) => void;
+  /** 底层 RPC 连接结束后的通知。 */
+  on_close: (error?: unknown) => void;
 };
 
 /**
@@ -249,6 +252,7 @@ export class RpcClient {
     session_id: string;
     on_ready: () => void;
     on_event: (event: AgentSessionEvent) => void;
+    on_close: (error?: unknown) => void;
   }): Promise<RpcSessionSubscription> {
     const data = await this.request<{ subscriptionId: string }>({
       method: "sdk.sessions.subscribe",
@@ -263,6 +267,7 @@ export class RpcClient {
     this.subscriptions.set(subscription_id, {
       on_ready: params.on_ready,
       on_event: params.on_event,
+      on_close: params.on_close,
     });
     params.on_ready();
     return {
@@ -343,8 +348,8 @@ export class RpcClient {
   /**
    * 列出 Agent runtime 内 plugin 状态。
    */
-  async list_internal_plugin_states(): Promise<PluginStateSnapshot[]> {
-    const data = await this.request<{ plugins: PluginStateSnapshot[] }>({
+  async list_internal_plugin_states(): Promise<PluginSnapshot[]> {
+    const data = await this.request<{ plugins: PluginSnapshot[] }>({
       method: "internal.plugins.list",
     });
     return Array.isArray(data.plugins) ? data.plugins : [];
@@ -355,9 +360,9 @@ export class RpcClient {
    */
   async control_internal_plugin(params: {
     plugin_name: string;
-    action: PluginStateControlAction;
-  }): Promise<PluginStateControlResult> {
-    return await this.request<PluginStateControlResult>({
+    action: PluginControlAction;
+  }): Promise<PluginControlResult> {
+    return await this.request<PluginControlResult>({
       method: "internal.plugins.control",
       params: {
         pluginName: params.plugin_name,
@@ -374,8 +379,8 @@ export class RpcClient {
     command: string;
     payload?: JsonValue;
     schedule?: JsonValue;
-  }): Promise<PluginCommandResult & { plugin?: PluginStateSnapshot }> {
-    return await this.request<PluginCommandResult & { plugin?: PluginStateSnapshot }>({
+  }): Promise<PluginCommandResult & { plugin?: PluginSnapshot }> {
+    return await this.request<PluginCommandResult & { plugin?: PluginSnapshot }>({
       method: "internal.plugins.command",
       params: {
         pluginName: params.plugin_name,
@@ -650,6 +655,7 @@ export class RpcClient {
         type: "error",
         message,
       });
+      subscription.on_close(new Error(message));
     }
     this.subscriptions.clear();
   }

package/src/session/Session.ts

@@ -12,7 +12,6 @@ import type { Tool } from "ai";
 import { JsonlSessionHistoryComposer } from "@executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
 import { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
 import type {
-  AgentSession,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
   AgentSessionRecordsInput,
@@ -21,14 +20,15 @@ import type {
   AgentSessionSetInput,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
+import type { AgentSession } from "@/types/agent/SessionActor.js";
 import {
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
   getSdkAgentSessionInflightPath,
-  resolveSystemTimezone,
-  createRuntimeSessionPort,
-} from "@/session/index.js";
+} from "@/session/storage/Paths.js";
+import { resolveSystemTimezone } from "@/session/storage/Metadata.js";
+import { createRuntimeSessionPort } from "@/session/storage/RuntimeSessionPort.js";
 import { SessionSystemBuilder } from "@/session/SessionSystemBuilder.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type {
@@ -256,13 +256,6 @@ export class Session implements AgentSession {
     return this.turnService.is_prompt_runtime_active() || this.executor.isExecuting();
   }
 
-  /**
-   * 清理当前 session 的执行器缓存。
-   */
-  clearExecutor(): void {
-    this.executor.clearExecutor();
-  }
-
   /**
    * 从当前 session 创建一个分叉会话。
    */
@@ -284,12 +277,6 @@ export class Session implements AgentSession {
       publishEvent: (event) => {
         this.eventHub.publish(event);
       },
-      clearExecutor: () => {
-        this.executor.clearExecutor();
-      },
-      afterSessionUpdatedAsync: async () => {
-        await this.executor.afterSessionUpdatedAsync();
-      },
       append_user_message: async (message_params) => {
         await this.stateService.append_user_message(message_params);
       },
@@ -301,9 +288,6 @@ export class Session implements AgentSession {
       ensureReadyForExecution: async () => {
         await this.ensureReadyForExecution();
       },
-      touchMetadata: async () => {
-        await this.stateService.touch_metadata();
-      },
     });
     return this.runtimePort;
   }

package/src/session/SessionSystemBuilder.ts

@@ -12,7 +12,7 @@ import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type {
   AgentSessionSystemBlock,
   AgentSessionSystemSessionInfo,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**

package/src/session/browse/Browse.ts

@@ -9,6 +9,7 @@
  */
 
 import fs from "fs-extra";
+import path from "node:path";
 import {
   getToolName,
   isTextUIPart,
@@ -24,7 +25,7 @@ import type {
   AgentSessionSummary,
   AgentSessionSummaryPage,
   AgentSessionTimelineEvent,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
 import type {
   SessionActionRecordV1,
   SessionRecordV1,
@@ -36,7 +37,7 @@ import {
   is_session_message_record,
 } from "@/executor/types/SessionRecords.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
-import { pickLastSuccessfulChatSendText } from "@/executor/messages/UserVisibleText.js";
+import { resolve_session_message_preview } from "@/session/preview/SessionMessagePreview.js";
 import { getSdkAgentSessionMessagesPath } from "@/session/storage/Paths.js";
 import { getSdkAgentSessionMetaPath } from "@/session/storage/Paths.js";
 import { getSdkAgentSessionsRootDirPath } from "@/session/storage/Paths.js";
@@ -80,8 +81,10 @@ type SessionBrowseBaseInput = {
 
   /**
    * 当前 session 已读取到的完整消息。
+   *
+   * 说明（中文）：列表查询已有 metadata 摘要时可省略，详情查询仍传完整记录。
    */
-  messages: SessionRecordV1[];
+  messages?: SessionRecordV1[];
 
   /**
    * 当前 session 是否正在执行。
@@ -163,52 +166,6 @@ function stringifyForDisplay(input: unknown, maxChars = 2400): string {
   }
 }
 
-function extractMessageText(parts: unknown): string {
-  if (!Array.isArray(parts)) return "";
-  const texts: string[] = [];
-  for (const part of parts) {
-    if (!part || typeof part !== "object") continue;
-    const textPart = part as { type?: unknown; text?: unknown };
-    if (textPart.type !== "text" || typeof textPart.text !== "string") continue;
-    const text = textPart.text.trim();
-    if (!text) continue;
-    texts.push(text);
-  }
-  return texts.join("\n").trim();
-}
-
-function extractAssistantToolSummary(message: SessionMessageRecordV1): string {
-  if (!Array.isArray(message.parts)) return "";
-  const toolNames = new Set<string>();
-  for (const part of message.parts as AnyUiPart[]) {
-    if (!part || typeof part !== "object") continue;
-    if (!isToolUIPart(part)) continue;
-    const toolName = String(getToolName(part) || "").trim();
-    if (toolName) toolNames.add(toolName);
-  }
-  if (toolNames.size === 0) return "";
-  return `[tool] ${Array.from(toolNames).join(", ")}`;
-}
-
-/**
- * 解析单条 session 消息的用户可见预览文本。
- */
-export function resolveSessionMessagePreview(message: SessionRecordV1): string {
-  if (is_session_action_record(message)) {
-    return message.description
-      ? `${message.title}\n${message.description}`
-      : message.title;
-  }
-  if (!is_session_message_record(message)) return "";
-  const plainText = extractMessageText(message.parts);
-  if (plainText) return plainText;
-  if (message.role !== "assistant") return "";
-
-  const userVisible = pickLastSuccessfulChatSendText(message).trim();
-  if (userVisible) return userVisible;
-  return extractAssistantToolSummary(message);
-}
-
 function resolveToolName(part: ToolPartCompatShape, aiToolName?: string): string {
   const fromAi = String(aiToolName || "").trim();
   if (fromAi) return fromAi;
@@ -263,7 +220,7 @@ function toActionTimelineEvent(
     id: `${String(message.id || "")}:0`,
     role: "action",
     ...(typeof metadata?.ts === "number" ? { ts: metadata.ts } : {}),
-    text: resolveSessionMessagePreview(message),
+    text: resolve_session_message_preview(message),
     actionTitle: message.title,
     ...(message.description ? { actionDescription: message.description } : {}),
     actionState: message.state,
@@ -286,7 +243,7 @@ export function toSessionTimelineEvents(
       toTimelineEvent({
         message,
         role: message.role === "user" ? "user" : "assistant",
-        text: resolveSessionMessagePreview(message),
+        text: resolve_session_message_preview(message),
         sequence: 0,
       }),
     ];
@@ -352,7 +309,7 @@ export function toSessionTimelineEvents(
       toTimelineEvent({
         message,
         role: "assistant",
-        text: resolveSessionMessagePreview(message),
+        text: resolve_session_message_preview(message),
         sequence: 0,
       }),
     );
@@ -467,12 +424,16 @@ function filterUserVisibleHistoryMessages(
 export function buildSessionInfo(
   input: SessionBrowseBaseInput,
 ): AgentSessionInfo {
-  const previewText = input.messages.length > 0
+  const messages = input.messages;
+  const previewText = messages && messages.length > 0
     ? truncateText(
-        resolveSessionMessagePreview(input.messages[input.messages.length - 1]),
+        resolve_session_message_preview(messages[messages.length - 1]),
         180,
       )
-    : undefined;
+    : input.metadata.previewText;
+  const message_count = messages
+    ? messages.length
+    : input.metadata.messageCount || 0;
   const title =
     typeof input.metadata.title === "string" && input.metadata.title.trim()
       ? input.metadata.title.trim()
@@ -482,7 +443,7 @@ export function buildSessionInfo(
     sessionId: input.sessionId,
     ...(title ? { title } : {}),
     ...(previewText ? { previewText } : {}),
-    messageCount: input.messages.length,
+    messageCount: message_count,
     ...(typeof input.metadata.createdAt === "number"
       ? { createdAt: input.metadata.createdAt }
       : {}),
@@ -499,6 +460,56 @@ export function buildSessionInfo(
   };
 }
 
+/**
+ * 读取列表所需的轻量 session 摘要。
+ *
+ * 关键点（中文）
+ * - 新记录直接使用 metadata 摘要，不扫描 messages.jsonl。
+ * - 旧记录或执行中记录回退读取一次完整历史，并把摘要补写回 metadata。
+ */
+async function resolve_session_summary_metadata(input: {
+  /** 当前 session metadata。 */
+  metadata: SessionHistoryMetaV1;
+  /** 当前消息 JSONL 路径。 */
+  messagesPath: string;
+  /** 当前 metadata 路径。 */
+  metaPath: string;
+  /** 是否强制刷新摘要。 */
+  refresh: boolean;
+}): Promise<SessionHistoryMetaV1> {
+  const history_bytes = await fs.stat(input.messagesPath)
+    .then((file_stat) => file_stat.size)
+    .catch(() => 0);
+  const inflight_path = `${input.messagesPath.slice(0, -"messages.jsonl".length)}inflight.json`;
+  const has_inflight = await fs.pathExists(inflight_path);
+  if (
+    !input.refresh &&
+    !has_inflight &&
+    typeof input.metadata.messageCount === "number" &&
+    input.metadata.historyBytes === history_bytes
+  ) {
+    return input.metadata;
+  }
+  const messages = await loadSessionMessagesFromPath(input.messagesPath);
+  const last_message = messages[messages.length - 1];
+  const preview_text = last_message
+    ? truncateText(resolve_session_message_preview(last_message), 180)
+    : "";
+  const { previewText: _previous_preview, ...metadata_without_preview } = input.metadata;
+  void _previous_preview;
+  const next_metadata: SessionHistoryMetaV1 = {
+    ...metadata_without_preview,
+    messageCount: messages.length,
+    historyBytes: history_bytes,
+    ...(preview_text ? { previewText: preview_text } : {}),
+  };
+  const temp_path = `${input.metaPath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.ensureDir(path.dirname(input.metaPath));
+  await fs.writeJson(temp_path, next_metadata, { spaces: 2 });
+  await fs.move(temp_path, input.metaPath, { overwrite: true });
+  return next_metadata;
+}
+
 /**
  * 基于完整消息列表构建 session records 分页结果。
  */
@@ -584,28 +595,32 @@ export async function listAgentSessionSummaryPage(params: {
     if (!entry.isDirectory()) continue;
     const sessionId = decodeMaybe(entry.name);
     if (!sessionId) continue;
-    const metadata = await readSessionMetadataFromPath({
-      filePath: getSdkAgentSessionMetaPath(
-        params.projectRoot,
-        params.agentId,
-        sessionId,
-      ),
+    const meta_path = getSdkAgentSessionMetaPath(
+      params.projectRoot,
+      params.agentId,
+      sessionId,
+    );
+    const messages_path = getSdkAgentSessionMessagesPath(
+      params.projectRoot,
+      params.agentId,
+      sessionId,
+    );
+    const persisted_metadata = await readSessionMetadataFromPath({
+      filePath: meta_path,
       sessionId,
       agentId: params.agentId,
     });
-    const messages = await loadSessionMessagesFromPath(
-      getSdkAgentSessionMessagesPath(
-        params.projectRoot,
-        params.agentId,
-        sessionId,
-      ),
-    );
+    const metadata = await resolve_session_summary_metadata({
+      metadata: persisted_metadata,
+      messagesPath: messages_path,
+      metaPath: meta_path,
+      refresh: params.executingSessionIds?.has(sessionId) === true,
+    });
     const info = buildSessionInfo({
       projectRoot: params.projectRoot,
       agentId: params.agentId,
       sessionId,
       metadata,
-      messages,
       executing: params.executingSessionIds?.has(sessionId),
     });
     const summary: AgentSessionSummary = {
@@ -679,29 +694,33 @@ export async function listArchivedAgentSessionSummaryPage(params: {
     if (!entry.isDirectory()) continue;
     const sessionId = decodeMaybe(entry.name);
     if (!sessionId) continue;
-    const metadata = await readSessionMetadataFromPath({
-      filePath: getSdkAgentArchivedSessionMetaPath(
-        params.projectRoot,
-        params.agentId,
-        sessionId,
-      ),
+    const meta_path = getSdkAgentArchivedSessionMetaPath(
+      params.projectRoot,
+      params.agentId,
+      sessionId,
+    );
+    const messages_path = getSdkAgentArchivedSessionMessagesPath(
+      params.projectRoot,
+      params.agentId,
+      sessionId,
+    );
+    const persisted_metadata = await readSessionMetadataFromPath({
+      filePath: meta_path,
       sessionId,
       agentId: params.agentId,
     });
-    const messages = await loadSessionMessagesFromPath(
-      getSdkAgentArchivedSessionMessagesPath(
-        params.projectRoot,
-        params.agentId,
-        sessionId,
-      ),
-    );
+    const metadata = await resolve_session_summary_metadata({
+      metadata: persisted_metadata,
+      messagesPath: messages_path,
+      metaPath: meta_path,
+      refresh: false,
+    });
     // 关键点（中文）：归档 session 不再生成新 title，仅读取归档目录内已有 meta。
     const info = buildSessionInfo({
       projectRoot: params.projectRoot,
       agentId: params.agentId,
       sessionId,
       metadata,
-      messages,
       executing: false,
     });
     const summary: AgentSessionSummary = {

package/src/session/preview/SessionMessagePreview.ts

@@ -0,0 +1,75 @@
+/**
+ * Session 消息预览投影。
+ *
+ * 关键点（中文）
+ * - 只负责从单条持久化 record 提取用户可见文本。
+ * - history store 与浏览层共用该投影，避免摘要写入和读取采用不同规则。
+ */
+
+import {
+  getToolName,
+  isToolUIPart,
+  type UIMessagePart,
+} from "ai";
+import { pickLastSuccessfulChatSendText } from "@/executor/messages/UserVisibleText.js";
+import type {
+  SessionMessageRecordV1,
+  SessionRecordV1,
+} from "@/executor/types/SessionRecords.js";
+import {
+  is_session_action_record,
+  is_session_message_record,
+} from "@/executor/types/SessionRecords.js";
+
+type SessionPreviewPart = UIMessagePart<
+  Record<string, never>,
+  Record<string, never>
+>;
+
+function extract_message_text(parts: unknown): string {
+  if (!Array.isArray(parts)) return "";
+  const texts: string[] = [];
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const text_part = part as { type?: unknown; text?: unknown };
+    if (text_part.type !== "text" || typeof text_part.text !== "string") continue;
+    const text = text_part.text.trim();
+    if (text) texts.push(text);
+  }
+  return texts.join("\n").trim();
+}
+
+function extract_assistant_tool_summary(
+  message: SessionMessageRecordV1,
+): string {
+  if (!Array.isArray(message.parts)) return "";
+  const tool_names = new Set<string>();
+  for (const part of message.parts as SessionPreviewPart[]) {
+    if (!part || typeof part !== "object" || !isToolUIPart(part)) continue;
+    const tool_name = String(getToolName(part) || "").trim();
+    if (tool_name) tool_names.add(tool_name);
+  }
+  return tool_names.size > 0
+    ? `[tool] ${Array.from(tool_names).join(", ")}`
+    : "";
+}
+
+/**
+ * 解析单条 session record 的用户可见预览文本。
+ */
+export function resolve_session_message_preview(
+  message: SessionRecordV1,
+): string {
+  if (is_session_action_record(message)) {
+    return message.description
+      ? `${message.title}\n${message.description}`
+      : message.title;
+  }
+  if (!is_session_message_record(message)) return "";
+  const plain_text = extract_message_text(message.parts);
+  if (plain_text) return plain_text;
+  if (message.role !== "assistant") return "";
+
+  const user_visible = pickLastSuccessfulChatSendText(message).trim();
+  return user_visible || extract_assistant_tool_summary(message);
+}

package/src/session/services/SessionStateService.ts

@@ -15,9 +15,9 @@ import {
   patchSessionModelLabel,
   readSessionMetadata,
   resolveSystemTimezone,
-  touchSessionMetadata,
   writeSessionMetadata,
-} from "@/session/index.js";
+} from "@/session/storage/Metadata.js";
+import { touchSessionMetadata } from "@/session/storage/Persistence.js";
 import { ensureSessionTitle } from "@/session/SessionTitle.js";
 import { persistSdkAssistantResult } from "@/session/storage/Persistence.js";
 import { hydrateUserPromptFileParts } from "@executor/messages/SessionAttachmentMapper.js";
@@ -26,7 +26,7 @@ import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/Js
 import type {
   AgentSessionConfigSnapshot,
   AgentSessionSetInput,
-} from "@/types/agent/AgentTypes.js";
+} from "@/types/agent/SessionTypes.js";
 import type {
   AgentSessionEvent,
 } from "@/types/sdk/AgentSessionEvent.js";
@@ -259,7 +259,6 @@ export class SessionStateService {
       if (input.model) {
         this.state.sessionConfig.model = normalizeAgentModel(input.model);
         this.state.sessionConfig.modelLabel = next_model_label;
-        this.executor.clearExecutor();
       }
       await patchSessionModelLabel({
         projectRoot: this.project_root,