@downcity/agent 1.1.200 → 1.1.203

package/src/agent/remote/RemoteAgent.ts

@@ -8,7 +8,15 @@
  */
 
 import type {
-  AgentSessionCollection,
+  AgentArchiveSessionInput,
+  AgentArchiveSessionsInput,
+  AgentArchiveSessionResult,
+  AgentArchiveSessionsResult,
+  AgentCleanArchiveResult,
+  AgentCreateSessionInput,
+  AgentListSessionsInput,
+  AgentSessionSummaryPage,
+  AgentSessions,
   RemoteAgentPluginActionInput,
   RemoteAgentPluginActionResult,
   RemoteAgentOptions,
@@ -30,6 +38,8 @@ import { create_remote_agent_transport } from "@/agent/remote/TransportFactory.j
  * RemoteAgent：远程 Agent 客户端。
  */
 export class RemoteAgent {
+  readonly sessions: AgentSessions<RemoteAgentSession>;
+
   private readonly transport: RemoteAgentTransport;
 
   constructor(options: RemoteAgentOptions) {
@@ -38,6 +48,7 @@ export class RemoteAgent {
       throw new Error("RemoteAgent requires a non-empty url");
     }
     this.transport = create_remote_agent_transport(url, options.token);
+    this.sessions = new RemoteAgentSessions(this.transport);
   }
 
   /**
@@ -121,27 +132,51 @@ export class RemoteAgent {
     await this.transport.close?.();
   }
 
-  /**
-   * 返回当前远程 session collection 入口。
-   *
-   * 关键点（中文）
-   * - `RemoteAgentTransport` 只负责协议传输，不直接等价于 `AgentSessionCollection`。
-   * - 这里把 transport 包装为 `AgentSessionCollection`，`create_session` / `get_session` 返回 `RemoteSession` 实例。
-   */
-  session_collection(): AgentSessionCollection {
-    return {
-     create_session: async (input) => {
-       const info = await this.transport.create_session(input);
-        return new RemoteSession(this.transport, info);
-      },
-      get_session: async (session_id) => {
-        const info = await this.transport.get_info(session_id);
-        return new RemoteSession(this.transport, info);
-      },
-      list_sessions: async (input) => await this.transport.list_sessions(input),
-      archive_session: async (input) => await this.transport.archive_session(input),
-      archive_sessions: async (input) => await this.transport.archive_sessions(input),
-      clean_archive: async () => await this.transport.clean_archive(),
-    };
+}
+
+/**
+ * 远程 Agent session 集合入口。
+ *
+ * 关键点（中文）
+ * - `RemoteAgentTransport` 只负责协议传输，不直接暴露为用户 SDK API。
+ * - 这里把远程传输包装成和本地 `agent.sessions` 一致的方法命名。
+ */
+class RemoteAgentSessions implements AgentSessions<RemoteAgentSession> {
+  private readonly transport: RemoteAgentTransport;
+
+  constructor(transport: RemoteAgentTransport) {
+    this.transport = transport;
+  }
+
+  /** 新建一个远程 session。 */
+  async create(input?: AgentCreateSessionInput): Promise<RemoteAgentSession> {
+    const info = await this.transport.create_session(input);
+    return new RemoteSession(this.transport, info);
+  }
+
+  /** 获取一个远程 session。 */
+  async get(session_id: string): Promise<RemoteAgentSession> {
+    const info = await this.transport.get_info(session_id);
+    return new RemoteSession(this.transport, info);
+  }
+
+  /** 列出远程 session 摘要页。 */
+  async list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
+    return await this.transport.list_sessions(input);
+  }
+
+  /** 归档一个远程 session。 */
+  async archive(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult> {
+    return await this.transport.archive_session(input);
+  }
+
+  /** 列出远程已归档 session。 */
+  async archived(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult> {
+    return await this.transport.archive_sessions(input);
+  }
+
+  /** 永久清空远程已归档 session。 */
+  async clean_archive(): Promise<AgentCleanArchiveResult> {
+    return await this.transport.clean_archive();
   }
 }

package/src/agent/remote/RemoteSession.ts

@@ -7,14 +7,14 @@
  */
 
 import type {
-  AgentSession,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSystemSnapshot,
+  RemoteAgentSession,
 } from "@/types/agent/AgentTypes.js";
 import { isAgentSessionPromptInputEmpty } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -53,7 +53,7 @@ type RemoteTurnLifecycle = {
 /**
  * 远程 Session 客户端。
  */
-export class RemoteSession implements AgentSession {
+export class RemoteSession implements RemoteAgentSession {
   readonly id: string;
   readonly agentId: string;
   readonly config: AgentSessionConfigSnapshot;
@@ -87,7 +87,7 @@ export class RemoteSession implements AgentSession {
   /**
    * 读取当前远程 session 详情。
    */
-  async getInfo(): Promise<AgentSessionInfo> {
+  async get_info(): Promise<AgentSessionInfo> {
     return await this.transport.get_info(this.id);
   }
 
@@ -135,8 +135,8 @@ export class RemoteSession implements AgentSession {
   /**
    * 读取远程消息历史。
    */
-  async history(input?: AgentSessionHistoryInput): Promise<AgentSessionHistoryPage> {
-    return await this.transport.history(this.id, input);
+  async records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage> {
+    return await this.transport.records(this.id, input);
   }
 
   /**
@@ -149,7 +149,7 @@ export class RemoteSession implements AgentSession {
   /**
    * 分叉远程 session。
    */
-  async fork(input?: AgentSessionForkInput | string): Promise<AgentSession> {
+  async fork(input?: AgentSessionForkInput | string): Promise<RemoteAgentSession> {
     const info = await this.transport.fork(this.id, input);
     return new RemoteSession(this.transport, info);
   }
@@ -296,6 +296,8 @@ function extract_turn_id(event: AgentSessionEvent): string | null {
     case "assistant-step":
     case "turn-finish":
       return event.turnId;
+    case "action":
+      return event.metadata.turnId || null;
     default:
       return null;
   }

package/src/agent/remote/RemoteTransport.ts

@@ -15,8 +15,8 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -63,10 +63,10 @@ export type RemoteSessionTransport = {
     on_event: (event: AgentSessionEvent) => void;
   }): Promise<TransportSubscription>;
   /** 读取 history。 */
-  history(
+  records(
     session_id: string,
-    input?: AgentSessionHistoryInput,
-  ): Promise<AgentSessionHistoryPage>;
+    input?: AgentSessionRecordsInput,
+  ): Promise<AgentSessionRecordsPage>;
   /** 读取 system snapshot。 */
   system(session_id: string): Promise<AgentSessionSystemSnapshot>;
   /** 分叉 session。 */

package/src/agent/remote/transports/HttpRemoteAgentTransport.ts

@@ -15,8 +15,8 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -184,10 +184,10 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     };
   }
 
-  async history(
+  async records(
     session_id: string,
-    input?: AgentSessionHistoryInput,
-  ): Promise<AgentSessionHistoryPage> {
+    input?: AgentSessionRecordsInput,
+  ): Promise<AgentSessionRecordsPage> {
     const query = new URLSearchParams();
     if (input?.limit !== undefined) query.set("limit", String(input.limit));
     if (input?.cursor) query.set("cursor", input.cursor);
@@ -197,19 +197,19 @@ export class HttpRemoteAgentTransport implements RemoteAgentTransport {
     const payload = await read_http_json<{
       success?: boolean;
       error?: string;
-      history?: AgentSessionHistoryPage;
+      records?: AgentSessionRecordsPage;
     }>(
-      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/history${
+      `${this.base_url}/api/sdk/sessions/${encodeURIComponent(session_id)}/records${
         query.size > 0 ? `?${query.toString()}` : ""
       }`,
       {
         headers: this.headers(),
       },
     );
-    if (!payload.success || !payload.history || !Array.isArray(payload.history.items)) {
-      throw new Error(String(payload.error || "Remote session history failed"));
+    if (!payload.success || !payload.records || !Array.isArray(payload.records.items)) {
+      throw new Error(String(payload.error || "Remote session records failed"));
     }
-    return payload.history;
+    return payload.records;
   }
 
   async system(session_id: string): Promise<AgentSessionSystemSnapshot> {

package/src/agent/remote/transports/RpcRemoteAgentTransport.ts

@@ -15,8 +15,8 @@ import type {
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSummaryPage,
   AgentSessionSystemSnapshot,
@@ -89,11 +89,11 @@ export class RpcRemoteAgentTransport implements RemoteAgentTransport {
     };
   }
 
-  async history(
+  async records(
     session_id: string,
-    input?: AgentSessionHistoryInput,
-  ): Promise<AgentSessionHistoryPage> {
-    return await this.client.get_session_history({
+    input?: AgentSessionRecordsInput,
+  ): Promise<AgentSessionRecordsPage> {
+    return await this.client.get_session_records({
       session_id,
       input,
     });

package/src/executor/Executor.ts

@@ -25,10 +25,13 @@ import { ExecutorRecoveryPolicy } from "@executor/services/ExecutorRecoveryPolic
 import { generateId } from "@/utils/Id.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionActionRecordV1,
+  SessionRecordV1,
+} from "@/executor/types/SessionRecords.js";
+import { to_session_action_record } from "@/executor/types/SessionRecords.js";
 import type { SessionExecutor } from "@/executor/types/SessionExecutor.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
-import type { AgentSessionActionRecord } from "@/types/sdk/AgentSessionAction.js";
 import type {
   SessionExecuteInput,
   SessionRunResult,
@@ -212,23 +215,23 @@ export class Executor implements SessionExecutor {
   /**
    * 追加一条 user 消息。
    */
-  async appendUserMessage(params: {
-    message?: SessionMessageV1 | null;
+  async append_user_message(params: {
+    message?: SessionRecordV1 | null;
     text?: string;
     extra?: JsonObject;
   }): Promise<void> {
-    await this.historyWriter.appendUserMessage(params);
+    await this.historyWriter.append_user_message(params);
   }
 
   /**
    * 追加一条 assistant 消息。
    */
-  async appendAssistantMessage(params: {
-    message?: SessionMessageV1 | null;
+  async append_assistant_message(params: {
+    message?: SessionRecordV1 | null;
     fallbackText?: string;
     extra?: JsonObject;
   }): Promise<void> {
-    await this.historyWriter.appendAssistantMessage(params);
+    await this.historyWriter.append_assistant_message(params);
   }
 
   /**
@@ -372,7 +375,7 @@ export class Executor implements SessionExecutor {
       }
 
       const emit_compaction_action = async (
-        action: AgentSessionActionRecord,
+        action: SessionActionRecordV1,
       ): Promise<void> => {
         if (action.state === "running") {
           compaction_action_id = action.id;
@@ -389,13 +392,18 @@ export class Executor implements SessionExecutor {
       });
     } catch (error) {
       await this.emitAction(run_context, {
+        type: "action",
         id:
           compaction_action_id ||
           `compacting:${this.sessionId}:failed:${Date.now()}:${generateId()}`,
-        title: "Session history compact failed",
+        title: "Session records compact failed",
         description: error instanceof Error ? error.message : String(error),
         state: "failed",
-        visible: false,
+        metadata: {
+          v: 1,
+          ts: Date.now(),
+          sessionId: this.sessionId,
+        },
       });
       // 压缩失败不阻断主流程，继续使用当前历史消息执行。
     }
@@ -514,21 +522,24 @@ export class Executor implements SessionExecutor {
    */
   private async emitAction(
     run_context: SessionRunContext,
-    action: AgentSessionActionRecord,
+    action: SessionActionRecordV1,
   ): Promise<void> {
     if (typeof run_context.onActionCallback !== "function") return;
     const action_id =
       String(action.id || "").trim() ||
       `action:${this.sessionId}:${Date.now()}:${generateId()}`;
-    await run_context.onActionCallback({
-      type: "action",
-      sessionId: run_context.sessionId || this.sessionId,
+    const event = to_session_action_record({
       ...action,
       id: action_id,
-      ...(run_context.turnId && !action.turnId
-        ? { turnId: run_context.turnId }
-        : {}),
-    });
+      metadata: {
+        ...action.metadata,
+        sessionId: run_context.sessionId || this.sessionId,
+        ...(run_context.turnId && !action.metadata.turnId
+          ? { turnId: run_context.turnId }
+          : {}),
+      },
+    }, run_context.sessionId || this.sessionId);
+    await run_context.onActionCallback(event);
   }
 
   /**

package/src/executor/SessionRunScope.ts

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { FileUIPart } from "ai";
-import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
 /**

package/src/executor/composer/compaction/SessionCompactionComposer.ts

@@ -8,7 +8,7 @@
 
 import type { LanguageModel, SystemModelMessage } from "ai";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type { AgentSessionActionRecord } from "@/types/sdk/AgentSessionAction.js";
+import type { SessionActionRecordV1 } from "@/executor/types/SessionRecords.js";
 
 /**
  * compaction Composer 执行输入。
@@ -39,9 +39,9 @@ export type SessionCompactionInput = {
    *
    * 说明（中文）
    * - 默认 compaction Composer 可在真正开始压缩时发布 action。
-   * - 回调由上层 Session 负责转成订阅事件与 action message。
+   * - 回调由上层 Session 负责转成订阅事件与 action record。
    */
-  onAction?: (action: AgentSessionActionRecord) => Promise<void>;
+  onAction?: (action: SessionActionRecordV1) => Promise<void>;
 };
 
 /**

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionExecutor.ts

@@ -18,16 +18,22 @@ import {
 import { generateId } from "@/utils/Id.js";
 import { getLogger } from "@/utils/logger/Logger.js";
 import type {
-  SessionMessageV1,
+  SessionActionRecordV1,
+  SessionRecordV1,
   SessionMetadataV1,
-  SessionModelMessageV1,
-} from "@/executor/types/SessionMessages.js";
+  SessionMessageRecordV1,
+} from "@/executor/types/SessionRecords.js";
 import {
-  isSessionActionMessage,
-  isSessionModelMessage,
-} from "@/executor/types/SessionMessages.js";
+  is_session_message_record,
+} from "@/executor/types/SessionRecords.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
-import type { AgentSessionActionRecord } from "@/types/sdk/AgentSessionAction.js";
+import {
+  append_session_compaction_file_operations,
+  build_initial_session_compaction_prompt,
+  build_update_session_compaction_prompt,
+  SESSION_COMPACTION_SYSTEM_PROMPT,
+} from "@executor/composer/compaction/jsonl/JsonlSessionCompactionPrompts.js";
+import { format_session_compaction_file_operations } from "@executor/composer/compaction/jsonl/JsonlSessionCompactionFileOperations.js";
 
 export type SessionCompactParams = {
   model: LanguageModel;
@@ -36,19 +42,19 @@ export type SessionCompactParams = {
   maxInputTokensApprox: number;
   archiveOnCompact: boolean;
   compactRatio: number;
-  onAction?: (action: AgentSessionActionRecord) => Promise<void>;
+  onAction?: (action: SessionActionRecordV1) => Promise<void>;
 };
 
 type SessionCompactDeps = {
   rootPath: string;
   sessionId: string;
   withWriteLock: <T>(fn: () => Promise<T>) => Promise<T>;
-  loadAll: () => Promise<SessionMessageV1[]>;
+  loadAll: () => Promise<SessionRecordV1[]>;
   createSummaryMessage: (params: {
     text: string;
     archiveId?: string;
     sourceRange?: SessionMetadataV1["sourceRange"];
-  }) => SessionMessageV1;
+  }) => SessionRecordV1;
   getArchiveDirPath: () => string;
   getMessagesFilePath: () => string;
   readMetaUnsafe: () => Promise<SessionHistoryMetaV1>;
@@ -71,12 +77,18 @@ export async function compactSessionMessagesIfNeeded(
   let action_started = false;
 
   const publish_action = async (
-    action: Omit<AgentSessionActionRecord, "id">,
+    action: Omit<SessionActionRecordV1, "type" | "id" | "metadata">,
   ): Promise<void> => {
     if (typeof params.onAction !== "function") return;
     await params.onAction({
+      type: "action",
       id: action_id,
       ...action,
+      metadata: {
+        v: 1,
+        ts: Date.now(),
+        sessionId: deps.sessionId,
+      },
     });
   };
 
@@ -84,10 +96,10 @@ export async function compactSessionMessagesIfNeeded(
   // phase 1：snapshot（短锁）
   // - 仅负责拿一致性快照，不做耗时的模型调用。
   // - 目的是把锁持有时间降到最低。
-  let snapshot: SessionModelMessageV1[] = [];
+  let snapshot: SessionMessageRecordV1[] = [];
   let snapshotTailId = "";
   await deps.withWriteLock(async () => {
-    snapshot = (await deps.loadAll()).filter(isSessionModelMessage);
+    snapshot = (await deps.loadAll()).filter(is_session_message_record);
     snapshotTailId =
       snapshot.length > 0
         ? String(snapshot[snapshot.length - 1].id || "")
@@ -121,16 +133,27 @@ export async function compactSessionMessagesIfNeeded(
 
   action_started = true;
   await publish_action({
-    title: "Compacting session history",
+    title: "Compacting session records",
     state: "running",
   });
 
-  const olderTextAll = extractPlainTextFromMessages(older);
+  const previous_summary = extract_existing_compaction_summary(older[0]);
+  const conversation_messages = previous_summary ? older.slice(1) : older;
+  const olderTextAll = extractPlainTextFromMessages(conversation_messages);
   const maxOlderChars = 24_000;
   const olderText =
     olderTextAll.length > maxOlderChars
       ? "（注意：更早历史过长，已截断保留末尾）\n" + olderTextAll.slice(-maxOlderChars)
       : olderTextAll;
+  const prompt = previous_summary
+    ? build_update_session_compaction_prompt({
+        previous_summary,
+        new_conversation_text: olderText || "(none)",
+      })
+    : build_initial_session_compaction_prompt({
+        conversation_text: olderText || "(none)",
+      });
+  const file_operations_xml = format_session_compaction_file_operations(older);
 
   // phase 1.5：生成摘要（不持锁）
   // - 这一步最耗时，必须在锁外执行，避免阻塞 append。
@@ -141,18 +164,15 @@ export async function compactSessionMessagesIfNeeded(
       system: [
         {
           role: "system",
-          content:
-            "你是对话压缩助手。请把更早的对话历史压缩成“可持续复用”的工作摘要。\n" +
-            "要求：\n" +
-            "- 输出中文\n" +
-            "- 不要复述无关细节，不要输出工具原始日志\n" +
-            "- 必须包含：已确认事实/用户偏好约束/已做决策/未完成事项\n" +
-            "- 使用 Markdown 列表，控制在 300~800 字",
+          content: SESSION_COMPACTION_SYSTEM_PROMPT,
         },
       ],
-      prompt: `请压缩以下更早历史（按 user/assistant 交替记录）：\n\n${olderText}`,
+      prompt,
+    });
+    summary = append_session_compaction_file_operations({
+      summary: String(r.text || "").trim(),
+      file_operations_xml,
     });
-    summary = String(r.text || "").trim();
   } catch (e) {
     await logger.log(
       "warn",
@@ -162,9 +182,12 @@ export async function compactSessionMessagesIfNeeded(
         error: String(e),
       },
     );
-    summary = "（系统自动压缩：摘要生成失败，已丢弃更早历史，仅保留最近对话。）";
+    summary = append_session_compaction_file_operations({
+      summary: "（系统自动压缩：摘要生成失败，已丢弃更早历史，仅保留最近对话。）",
+      file_operations_xml,
+    });
     await publish_action({
-      title: "Compacting session history",
+      title: "Compacting session records",
       description: "Summary generation failed; using a fallback summary.",
       state: "running",
     });
@@ -190,7 +213,7 @@ export async function compactSessionMessagesIfNeeded(
     void snapshotTailId;
 
     const current_model_messages = current.filter(
-      isSessionModelMessage,
+      is_session_message_record,
     );
     const currentCompactCount = resolveCompactCount(
       current_model_messages.length,
@@ -243,7 +266,7 @@ export async function compactSessionMessagesIfNeeded(
 
   if (action_started) {
     await publish_action({
-      title: "Session history compacted",
+      title: "Session records compacted",
       description: `Compacted ${String(older.length)} earlier messages into ${archiveId}.`,
       state: "completed",
     });
@@ -297,7 +320,7 @@ function estimateTokensApproxFromText(text: string): number {
  * - 统一把 user / assistant 内容线性化，作为 compact 摘要输入。
  * - tool 原始结构不会原样输出，避免把噪声日志喂给摘要模型。
  */
-function extractPlainTextFromMessages(messages: SessionModelMessageV1[]): string {
+function extractPlainTextFromMessages(messages: SessionMessageRecordV1[]): string {
   const lines: string[] = [];
   for (const m of messages) {
     if (!m || typeof m !== "object") continue;
@@ -310,3 +333,24 @@ function extractPlainTextFromMessages(messages: SessionModelMessageV1[]): string
   }
   return lines.join("\n");
 }
+
+/**
+ * 从已有 compact summary 消息中提取旧摘要。
+ *
+ * 关键点（中文）
+ * - 旧摘要通常位于 messages.jsonl 第一条，后续 compact 应基于它迭代更新。
+ * - 只识别 compact 生成的 summary，避免误把普通 assistant 文本当作旧摘要。
+ */
+function extract_existing_compaction_summary(
+  message: SessionMessageRecordV1 | undefined,
+): string {
+  if (!message || typeof message !== "object") return "";
+  const metadata = message.metadata;
+  if (metadata?.source !== "compact" || metadata.kind !== "summary") return "";
+  const parts = Array.isArray(message.parts) ? message.parts : [];
+  return parts
+    .filter(isTextUIPart)
+    .map((part) => String(part.text ?? ""))
+    .join("\n")
+    .trim();
+}