@downcity/agent 1.1.200 → 1.1.203

package/src/session/services/SessionViewService.ts

@@ -2,14 +2,14 @@
  * SessionViewService：本地 Session 查询与派生视图服务。
  *
  * 关键点（中文）
- * - 统一管理 info/history/system/fork 这类读取型能力。
+ * - 统一管理 info/records/system/fork 这类读取型能力。
  * - 该服务只负责拼装查询结果，不负责编排 prompt turn。
  * - 需要写入持久化状态的地方仍委托给 SessionStateService。
  */
 
 import { nanoid } from "nanoid";
 import {
-  buildSessionHistoryPage,
+  buildSessionRecordsPage,
   buildSessionInfo,
   getSdkAgentSessionArchiveFilePath,
   ensureSessionTitle,
@@ -21,14 +21,14 @@ import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/Js
 import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
 import type {
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSession,
   AgentSessionSystemBlock,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/AgentTypes.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 import { SessionStateService } from "@/session/services/SessionStateService.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
@@ -138,7 +138,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
         agentId: this.agent_id,
         sessionId: this.session_id,
       }),
-      this.history_store.list(),
+      this.history_store.list_records(),
     ]);
     return await this.build_info({
       metadata,
@@ -155,7 +155,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
     /**
      * 当前 session 消息列表。
      */
-    messages: SessionMessageV1[];
+    messages: SessionRecordV1[];
   }): Promise<AgentSessionInfo> {
     const metadata_with_title = input.metadata.title
       ? input.metadata
@@ -176,11 +176,11 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
   }
 
   /**
-   * 读取当前 session 历史分页。
+   * 读取当前 session records 分页。
    */
-  async history(
-    input?: AgentSessionHistoryInput,
-  ): Promise<AgentSessionHistoryPage> {
+  async records(
+    input?: AgentSessionRecordsInput,
+  ): Promise<AgentSessionRecordsPage> {
     const archive_id = String(input?.archive_id || "").trim();
     const [metadata, current_messages] = await Promise.all([
       readSessionMetadata({
@@ -188,7 +188,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
         agentId: this.agent_id,
         sessionId: this.session_id,
       }),
-      this.history_store.list(),
+      this.history_store.list_records(),
     ]);
     const page_messages = archive_id
       ? await loadSessionArchiveMessagesFromPath(
@@ -204,7 +204,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
       metadata,
       messages: current_messages,
     });
-    return buildSessionHistoryPage({
+    return buildSessionRecordsPage({
       session,
       messages: page_messages,
       input,
@@ -273,7 +273,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
       typeof input === "string"
         ? String(input || "").trim() || undefined
         : String(input?.messageId || "").trim() || undefined;
-    const messages = await this.history_store.list();
+    const messages = await this.history_store.list_records();
     const fork_messages =
       !message_id
         ? messages
@@ -282,7 +282,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
 
     await this.state_service.emit_action_event({
       id: action_id,
-      title: "Forking session history",
+      title: "Forking session records",
       description: `Preparing ${String(fork_messages.length)} messages for the new session.`,
       state: "running",
     });
@@ -304,7 +304,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
       await this.append_fork_messages(forked_bundle, fork_messages);
       await this.state_service.emit_action_event({
         id: action_id,
-        title: "Session history forked",
+        title: "Session records forked",
         description: `Created ${String((forked as { id?: unknown }).id || "")} with ${String(fork_messages.length)} messages.`,
         state: "completed",
       });
@@ -312,7 +312,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
     } catch (error) {
       await this.state_service.emit_action_event({
         id: action_id,
-        title: "Session history fork failed",
+        title: "Session records fork failed",
         description: error instanceof Error ? error.message : String(error),
         state: "failed",
       });
@@ -321,9 +321,9 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
   }
 
   private resolve_fork_messages(
-    messages: SessionMessageV1[],
+    messages: SessionRecordV1[],
     message_id: string,
-  ): SessionMessageV1[] {
+  ): SessionRecordV1[] {
     const target_index = messages.findIndex(
       (message) => String(message.id || "").trim() === message_id,
     );
@@ -340,9 +340,9 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
       history_store: JsonlSessionHistoryStore;
       state_service: SessionStateService;
     },
-    messages: SessionMessageV1[],
+    messages: SessionRecordV1[],
   ): Promise<void> {
-    await forked_bundle.history_store.appendMany(messages);
+    await forked_bundle.history_store.write_records(messages);
   }
 
   private stringify_system_content(content: unknown): string {

package/src/session/storage/Persistence.ts

@@ -9,9 +9,9 @@
 import { extractTextFromUiMessage } from "@/executor/messages/UIMessageTransformer.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type {
-  SessionMessageV1,
-  SessionModelMessageV1,
-} from "@/executor/types/SessionMessages.js";
+  SessionRecordV1,
+  SessionMessageRecordV1,
+} from "@/executor/types/SessionRecords.js";
 import { persistAssistantResult } from "@/executor/messages/AssistantResultPersistence.js";
 import type { AgentSessionConfigSnapshot } from "@/types/agent/AgentTypes.js";
 import {
@@ -50,11 +50,11 @@ export interface PersistSdkAssistantResultParams
    * 追加 assistant 消息的底层执行编排器。
    */
   executor: {
-    appendAssistantMessage(params: {
+    append_assistant_message(params: {
       /**
        * 已构造好的完整消息。
        */
-      message?: SessionMessageV1 | null;
+      message?: SessionRecordV1 | null;
       /**
        * 兜底文本内容。
        */
@@ -68,7 +68,7 @@ export interface PersistSdkAssistantResultParams
    * - stop/abort 且没有 assistant 内容时允许为空。
    * - 为空时仅刷新 metadata，不写入伪造 assistant 正文。
    */
-  assistantMessage?: SessionModelMessageV1 | null;
+  assistantMessage?: SessionMessageRecordV1 | null;
 }
 
 /**

package/src/session/storage/RuntimeSessionPort.ts

@@ -58,11 +58,11 @@ export interface CreateRuntimeSessionPortParams {
   /**
    * 追加 user 消息到底层历史。
    */
-  appendUserMessage: SessionPort["appendUserMessage"];
+  append_user_message: SessionPort["append_user_message"];
   /**
    * 追加 assistant 消息到底层历史。
    */
-  appendAssistantMessage: SessionPort["appendAssistantMessage"];
+  append_assistant_message: SessionPort["append_assistant_message"];
   /**
    * 返回当前 session 是否正在执行。
    */
@@ -111,12 +111,12 @@ export function createRuntimeSessionPort(
     afterSessionUpdatedAsync: async () => {
       await params.afterSessionUpdatedAsync();
     },
-    appendUserMessage: async (messageParams) => {
-      await params.appendUserMessage(messageParams);
+    append_user_message: async (messageParams) => {
+      await params.append_user_message(messageParams);
       await params.touchMetadata();
     },
-    appendAssistantMessage: async (messageParams) => {
-      await params.appendAssistantMessage(messageParams);
+    append_assistant_message: async (messageParams) => {
+      await params.append_assistant_message(messageParams);
       await params.touchMetadata();
     },
     isExecuting: () => params.isExecuting(),

package/src/types/agent/AgentTypes.ts

@@ -36,9 +36,9 @@ export type {
   AgentListSessionsInput,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
-  AgentSessionHistoryView,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
+  AgentSessionRecordsView,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSummary,
@@ -53,6 +53,6 @@ export type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 export type {
   AgentSession,
   AgentSessionActor,
-  AgentSessionCollection,
+  AgentSessions,
   RemoteAgentSession,
 } from "@/types/agent/SessionActor.js";

package/src/types/agent/SessionActor.ts

@@ -16,8 +16,8 @@ import type {
   AgentListSessionsInput,
   AgentSessionConfigSnapshot,
   AgentSessionForkInput,
-  AgentSessionHistoryInput,
-  AgentSessionHistoryPage,
+  AgentSessionRecordsInput,
+  AgentSessionRecordsPage,
   AgentSessionInfo,
   AgentSessionSetInput,
   AgentSessionSummaryPage,
@@ -32,23 +32,23 @@ import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
 /**
- * SDK Session 集合绑定。
+ * SDK Session 集合入口。
  */
-export interface AgentSessionCollection {
+export interface AgentSessions<TSession extends AgentSessionActor = AgentSession> {
   /** 新建一个 session。 */
-  create_session(input?: AgentCreateSessionInput): Promise<AgentSession>;
+  create(input?: AgentCreateSessionInput): Promise<TSession>;
 
   /** 获取一个已存在的 session。 */
-  get_session(sessionId: string): Promise<AgentSession>;
+  get(session_id: string): Promise<TSession>;
 
   /** 列出当前 agent 的 session 摘要页。 */
-  list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
+  list(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage>;
 
   /** 归档单个 session。 */
-  archive_session(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult>;
+  archive(input: AgentArchiveSessionInput): Promise<AgentArchiveSessionResult>;
 
   /** 列出已归档的 session 摘要页。 */
-  archive_sessions(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult>;
+  archived(input?: AgentArchiveSessionsInput): Promise<AgentArchiveSessionsResult>;
 
   /** 永久清空已归档 session。 */
   clean_archive(): Promise<AgentCleanArchiveResult>;
@@ -62,7 +62,7 @@ export interface AgentSessionActor {
   readonly id: string;
 
   /** 读取当前 session 详情。 */
-  getInfo(): Promise<AgentSessionInfo>;
+  get_info(): Promise<AgentSessionInfo>;
 
   /** 追加一条新的 prompt。 */
   prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
@@ -73,8 +73,8 @@ export interface AgentSessionActor {
   /** 订阅当前 session 的未来事件。 */
   subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
 
-  /** 读取当前 session 历史分页。 */
-  history(input?: AgentSessionHistoryInput): Promise<AgentSessionHistoryPage>;
+  /** 读取当前 session records 分页。 */
+  records(input?: AgentSessionRecordsInput): Promise<AgentSessionRecordsPage>;
 
   /** 读取当前 session 生效的 system 快照。 */
   system(): Promise<AgentSessionSystemSnapshot>;

package/src/types/agent/SessionTypes.ts

@@ -8,7 +8,7 @@
 
 import type { LanguageModel } from "ai";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 
 /**
  * 新建 session 的输入参数。
@@ -83,9 +83,9 @@ export interface AgentSessionConfigSnapshot {
 }
 
 /**
- * Session 历史视图类型。
+ * Session records视图类型。
  */
-export type AgentSessionHistoryView = "message" | "timeline";
+export type AgentSessionRecordsView = "message" | "timeline";
 
 /**
  * Session 时间线事件。
@@ -286,9 +286,9 @@ export interface AgentSessionSummaryPage {
 }
 
 /**
- * Session 历史读取输入。
+ * Session records 读取输入。
  */
-export interface AgentSessionHistoryInput {
+export interface AgentSessionRecordsInput {
   /** 当前页返回上限。 */
   limit?: number;
   /** 分页游标。 */
@@ -316,25 +316,25 @@ export interface AgentSessionHistoryInput {
    * - `message`：原始 session 消息
    * - `timeline`：适合直接渲染 UI 的平铺事件
    */
-  view?: AgentSessionHistoryView;
+  view?: AgentSessionRecordsView;
 }
 
 /**
- * Session 历史分页结果。
+ * Session records 分页结果。
  */
-export interface AgentSessionHistoryPage {
+export interface AgentSessionRecordsPage {
   /** 当前读取所对应的 session 信息。 */
   session: AgentSessionInfo;
   /** 当前页实际返回视图。 */
-  view: AgentSessionHistoryView;
+  view: AgentSessionRecordsView;
   /**
    * 当前页数据列表。
    *
    * 说明（中文）
-   * - `view=message` 时返回 `SessionMessageV1[]`
+   * - `view=message` 时返回 `SessionRecordV1[]`
    * - `view=timeline` 时返回 `AgentSessionTimelineEvent[]`
    */
-  items: SessionMessageV1[] | AgentSessionTimelineEvent[];
+  items: SessionRecordV1[] | AgentSessionTimelineEvent[];
   /**
    * 过滤前后的总条数。
    *
@@ -360,7 +360,7 @@ export interface AgentSessionHistoryPage {
    *
    * 关键点（中文）
    * - compact summary 不会出现在 `items` 中。
-   * - 若当前层包含 compact summary，则这里暴露其 archive ID，供调用方继续 `session.history({ archive_id })`。
+   * - 若当前层包含 compact summary，则这里暴露其 archive ID，供调用方继续 `session.records({ archive_id })`。
    */
   previous_archive_id?: string;
 }

package/src/types/executor/SessionRunContext.ts

@@ -16,7 +16,7 @@ import type {
   SessionAssistantStepCallback,
   SessionUiMessageChunkCallback,
 } from "@/executor/types/SessionRun.js";
-import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
 import type { FileUIPart } from "ai";
 
 /**
@@ -75,7 +75,7 @@ export interface SessionRunContext {
    * action 发布回调。
    *
    * 关键点（中文）
-   * - 用于把 compaction 等辅助动作转成 session event 与 action message。
+   * - 用于把 compaction 等辅助动作转成 session event 与 action record。
    * - action 不代表 assistant 正文，也不会进入 LLM 输入。
    */
   onActionCallback?: AgentSessionActionCallback;

package/src/types/rpc/RpcProtocol.ts

@@ -15,7 +15,7 @@ import type {
   AgentArchiveSessionResult,
   AgentArchiveSessionsResult,
   AgentCleanArchiveResult,
-  AgentSessionHistoryInput,
+  AgentSessionRecordsInput,
   AgentSessionStopResult,
   AgentSessionSystemSnapshot,
 } from "@/types/agent/AgentTypes.js";
@@ -112,14 +112,14 @@ export type RpcRequest =
   | {
       /** 请求 id，用于匹配响应。 */
       id: string;
-      /** 读取 session history。 */
-      method: "sdk.sessions.history";
-      /** history 查询参数。 */
+      /** 读取 session records。 */
+      method: "sdk.sessions.records";
+      /** records 查询参数。 */
       params: {
         /** 目标 session id。 */
         sessionId: string;
-        /** history 分页与视图参数。 */
-        input?: AgentSessionHistoryInput;
+        /** records 分页与视图参数。 */
+        input?: AgentSessionRecordsInput;
       };
     }
   | {

package/src/types/runtime/agent/AgentContext.ts

@@ -19,8 +19,8 @@ import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type {
   SessionMetadataV1,
-  SessionMessageV1,
-} from "@/executor/types/SessionMessages.js";
+  SessionRecordV1,
+} from "@/executor/types/SessionRecords.js";
 import type {
   SessionRunInput,
   SessionRunResult,
@@ -133,7 +133,7 @@ export interface SessionPort {
    *
    * 关键点（中文）
    * - 只广播订阅之后产生的事件。
-   * - 历史消息仍通过 `getHistoryStore()` / SDK `history()` 读取。
+   * - session records 仍通过 `getHistoryStore()` / SDK `records()` 读取。
    */
   subscribe(subscriber: AgentSessionSubscriber): AgentSessionUnsubscribe;
   /**
@@ -141,7 +141,7 @@ export interface SessionPort {
    *
    * 关键点（中文）
    * - plugin runtime 用它把审批、外部进度等非模型 chunk 事件推送给订阅方。
-   * - 历史消息持久化仍由 appendUserMessage / appendAssistantMessage 负责。
+   * - 历史消息持久化仍由 append_user_message / append_assistant_message 负责。
    */
   publishEvent(event: AgentSessionEvent): void;
   /**
@@ -155,11 +155,11 @@ export interface SessionPort {
   /**
    * 追加一条 user 消息。
    */
-  appendUserMessage(params: {
+  append_user_message(params: {
     /**
      * 已构造好的完整消息。
      */
-    message?: SessionMessageV1 | null;
+    message?: SessionRecordV1 | null;
     /**
      * 兜底文本内容。
      */
@@ -172,11 +172,11 @@ export interface SessionPort {
   /**
    * 追加一条 assistant 消息。
    */
-  appendAssistantMessage(params: {
+  append_assistant_message(params: {
     /**
      * 已构造好的完整消息。
      */
-    message?: SessionMessageV1 | null;
+    message?: SessionRecordV1 | null;
     /**
      * 兜底文本内容。
      */

package/src/types/sdk/AgentSessionAction.ts

@@ -1,75 +1,31 @@
 /**
- * Agent Session action 类型定义。
+ * Agent Session action 公开类型。
  *
  * 关键点（中文）
- * - action 描述 session 内部正在发生的辅助动作，不代表 assistant 正文。
- * - action 同时用于 `session.subscribe()` 实时事件与 JSONL history item。
- * - action 只服务前端状态展示与历史回放，不进入 LLM 输入。
+ * - action 是 session records 中的 `type: "action"` 记录。
+ * - 同一份结构同时用于 JSONL 持久化与 `session.subscribe()` 实时事件。
+ * - action 不进入 LLM 输入；组装模型消息前必须过滤。
  */
 
+import type {
+  SessionActionRecordV1,
+  SessionActionStateV1,
+} from "@/executor/types/SessionRecords.js";
+
 /**
  * Session action 当前状态。
  */
-export type AgentSessionActionState = "running" | "completed" | "failed";
+export type AgentSessionActionState = SessionActionStateV1;
 
 /**
  * Session action 记录。
  */
-export interface AgentSessionActionRecord {
-  /**
-   * 同一个 action 生命周期内稳定复用的 ID。
-   *
-   * 说明（中文）
-   * - 这是 history item envelope 字段，用于把同一个动作更新为一条记录。
-   * - 前端展示语义只依赖 `type/title/description/state`。
-   */
-  id: string;
-
-  /**
-   * 当前 action 标题。
-   */
-  title: string;
-
-  /**
-   * 当前 action 描述。
-   */
-  description?: string;
-
-  /**
-   * 当前 action 状态。
-   */
-  state: AgentSessionActionState;
-
-  /**
-   * 当前 action 关联的 turn 标识。
-   */
-  turnId?: string;
-
-  /**
-   * 是否建议前端展示。
-   *
-   * 说明（中文）
-   * - 默认视为 `true`。
-   * - 调试或审计类辅助事件可显式写入 `false`。
-   */
-  visible?: boolean;
-}
+export type AgentSessionActionRecord = SessionActionRecordV1;
 
 /**
  * Session action 订阅事件。
  */
-export interface AgentSessionActionEvent
-  extends Omit<AgentSessionActionRecord, "visible"> {
-  /**
-   * 当前事件类型。
-   */
-  type: "action";
-
-  /**
-   * 当前 session 唯一标识。
-   */
-  sessionId: string;
-}
+export type AgentSessionActionEvent = SessionActionRecordV1;
 
 /**
  * Session action 发布回调。

package/src/types/sdk/AgentSessionTurn.ts

@@ -7,7 +7,7 @@
  * - 增量过程继续通过 `session.subscribe()` 观察；turn handle 只负责等待最终完成结果。
  */
 
-import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
 
 /**
  * 单个 Session turn 的最终结果。
@@ -35,7 +35,7 @@ export interface AgentSessionTurnResult {
    * - `turn.finished` 返回的结果以这条消息作为最终事实源。
    * - transport / runtime service 若需要读取最终结构化输出，应优先消费这里。
    */
-  assistantMessage?: SessionModelMessageV1;
+  assistantMessage?: SessionMessageRecordV1;
 
   /**
    * 当前 turn 失败时的错误文本。