@downcity/agent 1.1.79 → 1.1.81

package/src/session/services/SessionViewService.ts

@@ -0,0 +1,301 @@
+/**
+ * SessionViewService：本地 Session 查询与派生视图服务。
+ *
+ * 关键点（中文）
+ * - 统一管理 info/history/system/fork 这类读取型能力。
+ * - 该服务只负责拼装查询结果，不负责编排 prompt turn。
+ * - 需要写入持久化状态的地方仍委托给 SessionStateService。
+ */
+
+import { nanoid } from "nanoid";
+import {
+  buildSessionHistoryPage,
+  buildSessionInfo,
+  ensureSessionTitle,
+  readSessionMetadata,
+} from "@/session/index.js";
+import { buildSessionSystemBlocks } from "@/session/SessionSystemBuilder.js";
+import type { JsonlSessionHistoryStore } from "@/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
+import type {
+  AgentSessionForkInput,
+  AgentSessionHistoryInput,
+  AgentSessionHistoryPage,
+  AgentSessionInfo,
+  AgentSessionSystemBlock,
+  AgentSessionSystemSnapshot,
+} from "@/types/agent/AgentTypes.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import { SessionStateService } from "@/session/services/SessionStateService.js";
+import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+
+type SessionViewServiceOptions<TSession> = {
+  /**
+   * 当前 agent 稳定标识。
+   */
+  agent_id: string;
+
+  /**
+   * 当前项目根目录。
+   */
+  project_root: string;
+
+  /**
+   * 当前 session 标识。
+   */
+  session_id: string;
+
+  /**
+   * 当前 session 历史事实源。
+   */
+  history_store: JsonlSessionHistoryStore;
+
+  /**
+   * 当前 session 状态服务。
+   */
+  state_service: SessionStateService;
+
+  /**
+   * 判断当前 session 是否正在执行。
+   */
+  is_executing: () => boolean;
+
+  /**
+   * 读取 instruction system blocks。
+   */
+  get_instruction_system_blocks: () => AgentSessionSystemBlock[];
+
+  /**
+   * 读取受托管 plugin system blocks。
+   */
+  get_managed_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取显式注册 plugin system blocks。
+   */
+  get_plugin_system_blocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 可选自定义 system composer。
+   *
+   * 关键点（中文）
+   * - 仅当调用方覆盖了 system composer 时传入。
+   * - 默认 SDK system snapshot 仍保留 block 级来源信息。
+   */
+  custom_system_composer?: SessionSystemComposer;
+
+  /**
+   * 创建一个新的本地 Session 实例。
+   */
+  create_fork_session: (session_id: string) => Promise<{
+    session: TSession;
+    history_store: JsonlSessionHistoryStore;
+    state_service: SessionStateService;
+  }>;
+};
+
+/**
+ * 本地 Session 查询与派生视图服务。
+ */
+export class SessionViewService<TSession> {
+  private readonly agent_id: string;
+  private readonly project_root: string;
+  private readonly session_id: string;
+  private readonly history_store: JsonlSessionHistoryStore;
+  private readonly state_service: SessionStateService;
+  private readonly is_executing: SessionViewServiceOptions<TSession>["is_executing"];
+  private readonly get_instruction_system_blocks: SessionViewServiceOptions<TSession>["get_instruction_system_blocks"];
+  private readonly get_managed_plugin_system_blocks: SessionViewServiceOptions<TSession>["get_managed_plugin_system_blocks"];
+  private readonly get_plugin_system_blocks: SessionViewServiceOptions<TSession>["get_plugin_system_blocks"];
+  private readonly custom_system_composer?: SessionSystemComposer;
+  private readonly create_fork_session: SessionViewServiceOptions<TSession>["create_fork_session"];
+
+  constructor(options: SessionViewServiceOptions<TSession>) {
+    this.agent_id = options.agent_id;
+    this.project_root = options.project_root;
+    this.session_id = options.session_id;
+    this.history_store = options.history_store;
+    this.state_service = options.state_service;
+    this.is_executing = options.is_executing;
+    this.get_instruction_system_blocks = options.get_instruction_system_blocks;
+    this.get_managed_plugin_system_blocks =
+      options.get_managed_plugin_system_blocks;
+    this.get_plugin_system_blocks = options.get_plugin_system_blocks;
+    this.custom_system_composer = options.custom_system_composer;
+    this.create_fork_session = options.create_fork_session;
+  }
+
+  /**
+   * 读取当前 session 详情。
+   */
+  async get_info(): Promise<AgentSessionInfo> {
+    const [metadata, messages] = await Promise.all([
+      readSessionMetadata({
+        projectRoot: this.project_root,
+        agentId: this.agent_id,
+        sessionId: this.session_id,
+      }),
+      this.history_store.list(),
+    ]);
+    const metadata_with_title = metadata.title
+      ? metadata
+      : await ensureSessionTitle({
+          projectRoot: this.project_root,
+          agentId: this.agent_id,
+          sessionId: this.session_id,
+          messages,
+        });
+    return buildSessionInfo({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      sessionId: this.session_id,
+      metadata: metadata_with_title,
+      messages,
+      executing: this.is_executing(),
+    });
+  }
+
+  /**
+   * 读取当前 session 历史分页。
+   */
+  async history(
+    input?: AgentSessionHistoryInput,
+  ): Promise<AgentSessionHistoryPage> {
+    const [session, messages] = await Promise.all([
+      this.get_info(),
+      this.history_store.list(),
+    ]);
+    return buildSessionHistoryPage({
+      session,
+      messages,
+      input,
+    });
+  }
+
+  /**
+   * 读取当前 session 生效的 system 快照。
+   */
+  async system(): Promise<AgentSessionSystemSnapshot> {
+    const blocks = this.custom_system_composer
+      ? await this.resolve_custom_system_blocks(this.custom_system_composer)
+      : await buildSessionSystemBlocks({
+          agentId: this.agent_id,
+          projectRoot: this.project_root,
+          sessionId: this.session_id,
+          createdAt: this.state_service.get_created_at(),
+          timezone: this.state_service.get_timezone(),
+          getInstructionSystemBlocks: this.get_instruction_system_blocks,
+          getManagedPluginSystemBlocks: this.get_managed_plugin_system_blocks,
+          getPluginSystemBlocks: this.get_plugin_system_blocks,
+        });
+    return {
+      sessionId: this.session_id,
+      session: {
+        agentId: this.agent_id,
+        sessionId: this.session_id,
+        projectRoot: this.project_root,
+        createdAt: new Date(this.state_service.get_created_at()).toISOString(),
+        timezone: this.state_service.get_timezone(),
+      },
+      blocks,
+    };
+  }
+
+  private async resolve_custom_system_blocks(
+    composer: SessionSystemComposer,
+  ): Promise<AgentSessionSystemBlock[]> {
+    const run_context: SessionRunContext = {
+      sessionId: this.session_id,
+      injectedUserMessages: [],
+      deferredPersistedUserMessages: [],
+      pendingAssistantFileParts: [],
+    };
+    const messages = await composer.resolve(run_context);
+    const blocks: AgentSessionSystemBlock[] = [];
+    messages.forEach((message, index) => {
+      const content = this.stringify_system_content(
+        (message as { content?: unknown }).content,
+      );
+      if (!content) return;
+      blocks.push({
+        source: "session",
+        name: `${composer.name || "custom_system"}:${index + 1}`,
+        content,
+      });
+    });
+    return blocks;
+  }
+
+  /**
+   * 从当前 session 创建一个分叉会话。
+   */
+  async fork(input?: AgentSessionForkInput | string): Promise<TSession> {
+    const message_id =
+      typeof input === "string"
+        ? String(input || "").trim() || undefined
+        : String(input?.messageId || "").trim() || undefined;
+    const messages = await this.history_store.list();
+    const fork_messages =
+      !message_id
+        ? messages
+        : this.resolve_fork_messages(messages, message_id);
+
+    const forked_bundle = await this.create_fork_session(
+      `fork-${Date.now()}-${nanoid(8)}`,
+    );
+    const forked = forked_bundle.session;
+    const session_config = this.state_service.get_config();
+    if (session_config.model) {
+      await (
+        forked as unknown as {
+          set(input: { model: unknown }): Promise<void>;
+        }
+      ).set({
+        model: session_config.model,
+      });
+    }
+    await this.append_fork_messages(forked_bundle, fork_messages);
+    return forked;
+  }
+
+  private resolve_fork_messages(
+    messages: SessionMessageV1[],
+    message_id: string,
+  ): SessionMessageV1[] {
+    const target_index = messages.findIndex(
+      (message) => String(message.id || "").trim() === message_id,
+    );
+    if (target_index < 0) {
+      throw new Error(
+        `Cannot fork session "${this.session_id}": messageId "${message_id}" not found.`,
+      );
+    }
+    return messages.slice(0, target_index + 1);
+  }
+
+  private async append_fork_messages(
+    forked_bundle: {
+      history_store: JsonlSessionHistoryStore;
+      state_service: SessionStateService;
+    },
+    messages: SessionMessageV1[],
+  ): Promise<void> {
+    for (const message of messages) {
+      await forked_bundle.history_store.append(message);
+    }
+    await forked_bundle.state_service.ensure_title_from_history({
+      generate: true,
+    });
+    await forked_bundle.state_service.touch_metadata();
+  }
+
+  private stringify_system_content(content: unknown): string {
+    if (typeof content === "string") return content.trim();
+    if (content === null || content === undefined) return "";
+    try {
+      return JSON.stringify(content);
+    } catch {
+      return String(content || "").trim();
+    }
+  }
+}

package/src/types/agent/AgentOptions.ts

@@ -10,6 +10,21 @@ import type { Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
 import type { RpcServerInstance } from "@/rpc/Server.js";
+import type {
+  AgentManagedSession,
+  SessionOptions,
+} from "@/types/session/SessionOptions.js";
+
+/**
+ * Agent 可使用的 Session 类。
+ *
+ * 关键点（中文）
+ * - 传 class，而不是传实例，保证 Agent 可以按 sessionId 创建多个 session。
+ * - 自定义类可继承默认 `Session`，并在构造函数里注入自己的 Composer。
+ */
+export type AgentSessionConstructor = new (
+  options: SessionOptions,
+) => AgentManagedSession;
 
 /**
  * 本地 Agent 构造参数。
@@ -67,6 +82,16 @@ export interface AgentOptions {
    */
   plugins?: BasePlugin[];
 
+  /**
+   * 当前 agent 使用的本地 Session 类。
+   *
+   * 关键点（中文）
+   * - Agent 只负责用这个类创建/恢复 session，不感知具体 Composer 策略。
+   * - 如果需要自定义 Composer，请在自定义 Session 类内部传给 `super({ composers })`。
+   * - 该能力仅适用于本地 `Agent`。
+   */
+  Session?: AgentSessionConstructor;
+
   /**
    * 当前 agent 的显式环境变量覆盖项。
    *

package/src/types/agent/AgentTypes.ts

@@ -8,10 +8,20 @@
  */
 
 export type { AgentModel } from "@/model/CityModelAdapter.js";
+export type {
+  SessionComposerFactoryContext,
+  SessionComposerInput,
+  SessionComposerOptions,
+} from "@/types/session/SessionComposerOptions.js";
+export type {
+  AgentManagedSession,
+  SessionOptions,
+} from "@/types/session/SessionOptions.js";
 export type {
   AgentOptions,
   AgentRpcBinding,
   AgentRpcStartOptions,
+  AgentSessionConstructor,
   AgentStartOptions,
   AgentStartResult,
   AgentStopResult,

package/src/types/agent/SessionTypes.ts

@@ -23,6 +23,7 @@ export interface AgentCreateSessionInput {
    * - 省略时由 SDK 自动生成稳定且不可推导的 sessionId。
    */
   sessionId?: string;
+
 }
 
 /**

package/src/types/executor/SessionRunContext.ts

@@ -0,0 +1,76 @@
+/**
+ * SessionRunContext：单次 session run 的显式运行上下文。
+ *
+ * 关键点（中文）
+ * - 这里承载本轮执行过程中需要在多个组件间透传的运行期数据。
+ * - 业务侧上下文优先通过该对象显式传递，避免分散读取隐式全局状态。
+ * - tool 深层回调等无法直接传参的场景，才通过 run scope 间接读取这个对象。
+ */
+
+import type {
+  SessionAssistantStepCallback,
+  SessionUiMessageChunkCallback,
+} from "@/executor/types/SessionRun.js";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { FileUIPart } from "ai";
+
+/**
+ * 单次 session run 的运行上下文。
+ */
+export interface SessionRunContext {
+  /**
+   * 当前执行所属的 session 标识。
+   */
+  sessionId: string;
+
+  /**
+   * step 边界合并回调。
+   *
+   * 关键点（中文）
+   * - 由 Session actor 在 turn 运行期间注入。
+   * - 用于把运行中追加的 user 消息并入下一 step。
+   */
+  onStepCallback?: () => Promise<SessionUserMessageV1[]>;
+
+  /**
+   * assistant step 完成回调。
+   *
+   * 关键点（中文）
+   * - 用于把中间 step 文本或 reasoning 事件回传给 Session 事件流。
+   */
+  onAssistantStepCallback?: SessionAssistantStepCallback;
+
+  /**
+   * UI stream chunk 回调。
+   *
+   * 关键点（中文）
+   * - 用于把底层模型 UI chunk 旁路输出到订阅流或 transport。
+   */
+  onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
+
+  /**
+   * 本轮运行中待并入下一 step 的 user 消息。
+   *
+   * 关键点（中文）
+   * - 主要由 tool runtime 在当前 turn 内动态注入。
+   * - 这些消息只影响当前执行，不会自动持久化。
+   */
+  injectedUserMessages: SessionUserMessageV1[];
+
+  /**
+   * 本轮运行结束后待写入长期历史的 user 消息。
+   *
+   * 关键点（中文）
+   * - 为保证时间线顺序稳定，这些消息会在 assistant 结果落盘之后统一持久化。
+   */
+  deferredPersistedUserMessages: SessionUserMessageV1[];
+
+  /**
+   * 本轮运行结束前待并入最终 assistant 消息的 file parts。
+   *
+   * 关键点（中文）
+   * - 用于 tool/plugin 在执行期产生图片、文件等最终输出。
+   * - 这些 part 不依赖模型把 tool result 再复述一遍，直接落入 assistant UIMessage。
+   */
+  pendingAssistantFileParts: FileUIPart[];
+}

package/src/types/plugin/ImagePlugin.ts

@@ -0,0 +1,103 @@
+/**
+ * ImagePlugin 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里仅定义 agent 对图片能力的最低层协议，不绑定 city 或任意上游 provider。
+ * - 图片生成结果使用 AI SDK UIMessage，保证 session 落盘格式与现有消息系统一致。
+ * - 字段保持 JSON 可序列化，便于通过 plugin action 与 tool bridge 传递。
+ */
+
+import type { UIMessage } from "ai";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+
+/**
+ * 图片生成文本内容片段。
+ */
+export interface ImagePluginTextContent {
+  /** 内容类型，固定为文本。 */
+  type: "text";
+  /** 生图提示词或上下文文本。 */
+  text: string;
+}
+
+/**
+ * 图片生成参考图片内容片段。
+ */
+export interface ImagePluginFileContent {
+  /** 内容类型，固定为图片。 */
+  type: "image";
+  /** 远程图片 URL。 */
+  url?: string;
+  /** data URL 图片内容。 */
+  data_url?: string;
+  /** 图片 MIME 类型，例如 `image/png`。 */
+  media_type?: string;
+}
+
+/**
+ * 图片生成多模态内容片段。
+ */
+export type ImagePluginContent =
+  | ImagePluginTextContent
+  | ImagePluginFileContent;
+
+/**
+ * 图片生成上下文消息。
+ */
+export interface ImagePluginMessage {
+  /** 消息角色。 */
+  role: "system" | "user" | "assistant";
+  /** 该消息内的文本与图片内容。 */
+  content: ImagePluginContent[];
+}
+
+/**
+ * ImagePlugin 调用输入。
+ */
+export interface ImagePluginInput {
+  /** 图片模型引用。 */
+  model?: string;
+  /** 单句快捷提示词。 */
+  prompt?: string;
+  /** 多轮或多模态图片生成上下文。 */
+  messages?: ImagePluginMessage[];
+  /** 生成图片数量。 */
+  n?: number;
+  /** 生成图片数量，兼容部分上游使用的 count 命名。 */
+  count?: number;
+  /** 图片尺寸，例如 `1024x1024`。 */
+  size?: string;
+  /** 图片宽高比，例如 `1:1`。 */
+  aspect_ratio?: string;
+  /** 图片宽高比，兼容部分上游使用的 ratio 命名。 */
+  ratio?: string;
+  /** 图片质量，例如 `standard`、`hd`、`ultra`、`4k`。 */
+  quality?: string;
+  /** 随机种子。 */
+  seed?: number;
+  /** 业务侧任务 ID，用于异步图片任务幂等、追踪和恢复。 */
+  client_job_id?: string;
+  /** Provider 私有参数，例如 `{ openai: {...}, gemini: {...}, luchi: {...} }`。 */
+  provider_options?: JsonObject;
+  /** 允许外部 image 函数接收其他 JSON 可序列化参数。 */
+  [key: string]: JsonValue | ImagePluginMessage[] | undefined;
+}
+
+/**
+ * ImagePlugin 生成结果。
+ */
+export type ImagePluginResult = UIMessage;
+
+/**
+ * ImagePlugin 构造参数。
+ */
+export interface ImagePluginOptions {
+  /** Plugin 稳定名称，默认 `image`。 */
+  name?: string;
+  /** Plugin 展示标题，默认 `Image`。 */
+  title?: string;
+  /** Plugin 用途说明。 */
+  description?: string;
+  /** 图片生成函数，通常传入 `(input) => city.ai.image(input)`。 */
+  image: (input: ImagePluginInput) => Promise<ImagePluginResult> | ImagePluginResult;
+}

package/src/types/session/SessionComposerOptions.ts

@@ -0,0 +1,107 @@
+/**
+ * Session Composer 配置类型。
+ *
+ * 关键点（中文）
+ * - Composer 是 session 执行阶段的可替换策略对象。
+ * - 调用方可以传入现成实例，也可以传入 factory 为每个 session 创建独立实例。
+ * - factory 适合 history/system 等可能绑定 sessionId、historyStore 或 session 元信息的 composer。
+ */
+
+import type { Tool } from "ai";
+import type { SessionCompactionComposer } from "@/executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionContextComposer } from "@/executor/composer/context/SessionContextComposer.js";
+import type { SessionHistoryComposer } from "@/executor/composer/history/SessionHistoryComposer.js";
+import type { SessionSystemComposer } from "@/executor/composer/system/SessionSystemComposer.js";
+import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+
+/**
+ * 单个 session 创建 Composer 时可读取的稳定上下文。
+ */
+export interface SessionComposerFactoryContext {
+  /**
+   * 当前 agent 的稳定标识。
+   */
+  agentId: string;
+
+  /**
+   * 当前 agent 绑定的项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 session 唯一标识。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 对应的 history 事实源。
+   *
+   * 关键点（中文）
+   * - history composer 和 compaction composer 通常需要基于它读取或压缩历史。
+   * - factory 每次收到的都是当前 session 自己的 store。
+   */
+  historyStore: SessionHistoryStore;
+
+  /**
+   * 当前 agent 默认工具集合读取器。
+   */
+  getTools: () => Record<string, Tool>;
+
+  /**
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   */
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+
+  /**
+   * 读取当前 agent 显式注入的受托管 plugin system blocks。
+   */
+  getManagedPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前 agent 显式注册 plugin 的 system blocks。
+   */
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前 session 首次创建时间（ms）。
+   */
+  getSessionCreatedAt: () => number;
+
+  /**
+   * 读取当前 session 初始化时解析到的系统时区。
+   */
+  getSessionTimezone: () => string;
+}
+
+/**
+ * 可直接传入 composer 实例，也可传入按 session 创建 composer 的 factory。
+ */
+export type SessionComposerInput<TComposer> =
+  | TComposer
+  | ((context: SessionComposerFactoryContext) => TComposer);
+
+/**
+ * Session Composer 覆盖项。
+ */
+export interface SessionComposerOptions {
+  /**
+   * 覆盖本轮 system messages 的 composer。
+   */
+  systemComposer?: SessionComposerInput<SessionSystemComposer>;
+
+  /**
+   * 覆盖本轮 history messages 的 composer。
+   */
+  historyComposer?: SessionComposerInput<SessionHistoryComposer>;
+
+  /**
+   * 覆盖本轮 tools、step hooks、fallback assistant message 等运行上下文 composer。
+   */
+  contextComposer?: SessionComposerInput<SessionContextComposer>;
+
+  /**
+   * 覆盖本轮上下文压缩 composer。
+   */
+  compactionComposer?: SessionComposerInput<SessionCompactionComposer>;
+}

package/src/types/session/SessionLocalState.ts

@@ -0,0 +1,40 @@
+/**
+ * SessionLocalState：本地 Session 运行态快照。
+ *
+ * 关键点（中文）
+ * - 这里承载本地 Session 在内存中的可变运行态。
+ * - state / turn / view 三类 service 通过共享该对象协作，避免彼此复制状态。
+ * - 这里只保存运行态，不承载行为逻辑。
+ */
+
+import type { AgentSessionConfigSnapshot } from "@/types/agent/AgentTypes.js";
+
+/**
+ * 本地 Session 内存状态。
+ */
+export interface SessionLocalState {
+  /**
+   * 当前 session 配置快照。
+   */
+  sessionConfig: AgentSessionConfigSnapshot;
+
+  /**
+   * 当前 session 创建时间（毫秒时间戳）。
+   */
+  createdAt: number;
+
+  /**
+   * 当前 session 参考时区。
+   */
+  timezone: string;
+
+  /**
+   * initialize() 过程中的并发复用 Promise。
+   */
+  initializePromise: Promise<void> | null;
+
+  /**
+   * ensureReadyForExecution() 过程中的并发复用 Promise。
+   */
+  ensureConfiguredPromise: Promise<void> | null;
+}