@downcity/agent 1.1.74 → 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/session/storage/Paths.ts

@@ -114,3 +114,22 @@ export function getSdkAgentSessionArchiveDirPath(
     "archive",
   );
 }
+
+/**
+ * 单个 session 的 inflight assistant 路径。
+ *
+ * 关键点（中文）
+ * - 运行中的 assistant 只保留一份增量快照。
+ * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
+ * - 完成后再把最终 assistant 合并进 `messages.jsonl`，并清理该文件。
+ */
+export function getSdkAgentSessionInflightPath(
+  projectRoot: string,
+  agentId: string,
+  sessionId: string,
+): string {
+  return path.join(
+    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
+    "inflight.json",
+  );
+}

package/src/types/agent/AgentOptions.ts

@@ -0,0 +1,172 @@
+/**
+ * Agent 本地实例配置与生命周期类型。
+ *
+ * 关键点（中文）
+ * - 只描述本地 Agent 的构造、启动、停止与 RPC 绑定。
+ * - RemoteAgent 与 Session 数据结构拆到独立类型文件。
+ */
+
+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 构造参数。
+ */
+export interface AgentOptions {
+  /**
+   * 当前 agent 的稳定标识。
+   *
+   * 关键点（中文）
+   * - 用于 `.downcity/agents/<agentId>/...` 目录分区。
+   * - 应保持稳定、可 URL 编码、尽量不要依赖展示名称。
+   */
+  id: string;
+
+  /** 当前 agent 绑定的项目根目录。 */
+  path: string;
+
+  /**
+   * 当前 agent 默认可用的工具集合。
+   *
+   * 关键点（中文）
+   * - tools 归属于 agent 级，而不是 session 级。
+   * - session 运行时会直接复用这份工具集合。
+   */
+  tools?: Record<string, Tool>;
+
+  /**
+   * 调用方显式传入的静态基础指令。
+   *
+   * 关键点（中文）
+   * - `instruction` 是稳定、缓存友好的 system 前缀，不做动态变量替换。
+   * - SDK 不主动读取 `PROFILE.md` / `SOUL.md`；这类项目文件应由 city 或调用方读取后传入。
+   * - 未传入时，SDK 会使用包内最小 core instruction 作为 fallback。
+   */
+  instruction?: string | string[];
+
+  /**
+   * 当前 agent 为新建 session 提供的默认模型实例。
+   *
+   * 关键点（中文）
+   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的模型实例。
+   * - 支持 AI SDK `LanguageModel`，也支持 City City 返回的 `CityModel`。
+   * - 该模型会作为 session 首次执行前的默认注入值。
+   */
+  model?: AgentModel;
+
+  /**
+   * 当前 agent 显式持有的插件实例集合。
+   *
+   * 关键点（中文）
+   * - 这里接收已经实例化好的 `BasePlugin` 对象，而不是 plugin class。
+   * - `Agent` 会在构造阶段按名称注册这些实例，并自动绑定到当前 runtime。
+   * - 同名 plugin 会直接报错，避免 action / hook / resolve 行为被静默覆盖。
+   * - SDK 不再自动注入任何 built-in plugin；需要的能力都应由宿主显式传入。
+   */
+  plugins?: BasePlugin[];
+
+  /**
+   * 当前 agent 使用的本地 Session 类。
+   *
+   * 关键点（中文）
+   * - Agent 只负责用这个类创建/恢复 session，不感知具体 Composer 策略。
+   * - 如果需要自定义 Composer，请在自定义 Session 类内部传给 `super({ composers })`。
+   * - 该能力仅适用于本地 `Agent`。
+   */
+  Session?: AgentSessionConstructor;
+
+  /**
+   * 当前 agent 的显式环境变量覆盖项。
+   *
+   * 关键点（中文）
+   * - 这里表示宿主显式注入给 agent 的基础 env。
+   * - `Agent` 会在这份基础 env 之上继续叠加项目 `.env`。
+   * - 覆盖后的最终 env 会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
+   */
+  env?: Record<string, string>;
+}
+
+/**
+ * Agent 启动参数。
+ */
+export interface AgentStartOptions {
+  /**
+   * 是否启动本机 RPC 服务。
+   *
+   * 关键点（中文）
+   * - `false` 表示不启动。
+   * - 传对象时会按给定 host/port 启动。
+   * - 省略时默认不启动，避免 SDK 本地嵌入场景误开端口。
+   */
+  rpc?: false | AgentRpcStartOptions;
+
+  /**
+   * 是否启动当前 agent 的 plugins。
+   *
+   * 关键点（中文）
+   * - 默认 `true`。
+   * - `false` 适合只需要 session 能力、不希望启动后台能力的嵌入场景。
+   */
+  plugins?: boolean;
+}
+
+/**
+ * Agent 停止结果快照。
+ */
+export interface AgentStopResult {
+  /** 本次是否实际停止了本机 RPC 服务。 */
+  rpcStopped: boolean;
+  /** 本次是否实际停止了 plugins。 */
+  pluginsStopped: boolean;
+}
+
+/**
+ * Agent 启动后的状态快照。
+ */
+export interface AgentStartResult {
+  /** 当前 agent 是否已启动本机 RPC 服务。 */
+  rpc?: AgentRpcBinding;
+  /** 当前 agent 是否已启动 plugins。 */
+  pluginsStarted: boolean;
+}
+
+/**
+ * Agent RPC 启动参数。
+ */
+export interface AgentRpcStartOptions {
+  /** RPC 监听主机。 */
+  host?: string;
+  /** RPC 监听端口。 */
+  port?: number;
+}
+
+/**
+ * Agent RPC 绑定信息。
+ */
+export interface AgentRpcBinding {
+  /** 远程访问地址。 */
+  url: string;
+  /** 当前 host。 */
+  host: string;
+  /** 当前 port。 */
+  port: number;
+  /** RPC server 句柄。 */
+  server: RpcServerInstance;
+}

package/src/types/{runtime/host/AgentHost.ts → agent/AgentRuntimeAssembly.ts}

@@ -1,8 +1,8 @@
 /**
- * Agent 宿主能力类型定义。
+ * AgentRuntimeAssembly 类型定义。
  *
  * 关键点（中文）
- * - 这里统一描述由 agent runtime 装配、再挂入 AgentRuntime 的宿主能力。
+ * - 这里统一描述由本地 agent 装配、再挂入 AgentRuntime 的能力。
  * - plugin runtime / session / plugin 作者 API 只能消费这些稳定能力，不应直接依赖具体宿主实现。
  * - 当前先收敛路径与 plugin 配置持久化两类高频能力。
  */