@downcity/agent 1.1.237 → 1.1.258

package/src/session/storage/Persistence.ts

@@ -1,137 +0,0 @@
-/**
- * SDK Session 持久化辅助。
- *
- * 关键点（中文）
- * - 集中处理 session meta 更新时间、模型展示标签与 assistant 消息落盘。
- * - `Session` 只负责调用这些能力，不直接拼装 meta 结构。
- */
-
-import { extractTextFromUiMessage } from "@/executor/messages/UIMessageTransformer.js";
-import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
-import type {
-  SessionRecordV1,
-  SessionMessageRecordV1,
-} from "@/executor/types/SessionRecords.js";
-import { persistAssistantResult } from "@/executor/messages/AssistantResultPersistence.js";
-import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
-import {
-  readSessionMetadata,
-  writeSessionMetadata,
-} from "@/session/storage/Metadata.js";
-
-/**
- * SDK Session 元数据写入参数。
- */
-export interface TouchSessionMetadataParams {
-  /**
-   * 当前项目根目录。
-   */
-  projectRoot: string;
-  /**
-   * 当前 agent 稳定标识。
-   */
-  agentId: string;
-  /**
-   * 当前 sessionId。
-   */
-  sessionId: string;
-  /**
-   * 当前 session 内存配置快照。
-   */
-  sessionConfig: AgentSessionConfigSnapshot;
-  /** 当前 canonical Message 总数。 */
-  message_count?: number;
-  /** 当前 Message 日志文件字节数。 */
-  history_bytes?: number;
-  /** 最近一条用户可见 Message 的文本摘要。 */
-  preview_text?: string;
-}
-
-/**
- * Assistant 结果落盘参数。
- */
-export interface PersistSdkAssistantResultParams
-  extends TouchSessionMetadataParams {
-  /**
-   * 追加 assistant 消息的底层执行编排器。
-   */
-  executor: {
-    append_assistant_message(params: {
-      /**
-       * 已构造好的完整消息。
-       */
-      message?: SessionRecordV1 | null;
-      /**
-       * 兜底文本内容。
-       */
-      fallbackText?: string;
-    }): Promise<void>;
-  };
-  /**
-   * 本轮执行得到的 assistant 消息。
-   *
-   * 关键点（中文）
-   * - stop/abort 且没有 assistant 内容时允许为空。
-   * - 为空时仅刷新 metadata，不写入伪造 assistant 正文。
-   */
-  assistantMessage?: SessionMessageRecordV1 | null;
-}
-
-/**
- * 刷新 SDK session 元数据。
- */
-export async function touchSessionMetadata(
-  params: TouchSessionMetadataParams,
-): Promise<void> {
-  const current = await readSessionMetadata({
-    projectRoot: params.projectRoot,
-    agentId: params.agentId,
-    sessionId: params.sessionId,
-  });
-  const next: SessionHistoryMetaV1 = {
-    ...current,
-    agentId: params.agentId,
-    createdAt:
-      typeof current.createdAt === "number" ? current.createdAt : Date.now(),
-    updatedAt: Date.now(),
-    ...(params.sessionConfig.modelLabel
-      ? {
-          modelLabel: params.sessionConfig.modelLabel,
-        }
-      : {}),
-    ...(params.sessionConfig.modelId
-      ? {
-          modelId: params.sessionConfig.modelId,
-        }
-      : {}),
-    ...(typeof params.message_count === "number"
-      ? { messageCount: params.message_count }
-      : {}),
-    ...(typeof params.history_bytes === "number"
-      ? { historyBytes: params.history_bytes }
-      : {}),
-    ...(params.preview_text ? { previewText: params.preview_text } : {}),
-  };
-  await writeSessionMetadata({
-    projectRoot: params.projectRoot,
-    agentId: params.agentId,
-    sessionId: params.sessionId,
-    meta: next,
-  });
-}
-
-/**
- * 持久化 assistant 结果并同步刷新 session meta。
- */
-export async function persistSdkAssistantResult(
-  params: PersistSdkAssistantResultParams,
-): Promise<void> {
-  await persistAssistantResult({
-    writer: params.executor,
-    assistantMessage: params.assistantMessage,
-    fallbackText: params.assistantMessage
-      ? extractTextFromUiMessage(params.assistantMessage)
-      : undefined,
-  });
-  await touchSessionMetadata(params);
-}

package/src/types/agent/AgentRuntimeAssembly.ts

@@ -1,74 +0,0 @@
-/**
- * AgentRuntimeAssembly 类型定义。
- *
- * 关键点（中文）
- * - 这里统一描述由本地 agent 装配、再挂入 AgentRuntime 的能力。
- * - plugin runtime / session / plugin 作者 API 只能消费这些稳定能力，不应直接依赖具体宿主实现。
- * - 当前先收敛路径与 plugin 配置持久化两类高频能力。
- */
-
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-
-/**
- * Agent 路径能力集合。
- */
-export interface AgentPathRuntime {
-  /**
-   * 当前项目根目录。
-   */
-  projectRoot: string;
-  /**
-   * 当前 agent 的稳定标识。
-   */
-  agentId: string;
-  /**
-   * `.downcity` 根目录路径。
-   */
-  getDowncityDirPath(): string;
-  /**
-   * `.downcity/.cache` 目录路径。
-   */
-  getCacheDirPath(): string;
-  /**
-   * `.downcity/channel` 目录路径。
-   */
-  getDowncityChannelDirPath(): string;
-  /**
-   * `.downcity/channel/meta.json` 文件路径。
-   */
-  getDowncityChannelMetaPath(): string;
-  /**
-   * `.downcity/chat/<sessionId>/history.jsonl` 文件路径。
-   */
-  getDowncityChatHistoryPath(sessionId: string): string;
-  /**
-   * `.downcity/memory/MEMORY.md` 文件路径。
-   */
-  getDowncityMemoryLongTermPath(): string;
-  /**
-   * `.downcity/memory/daily` 目录路径。
-   */
-  getDowncityMemoryDailyDirPath(): string;
-  /**
-   * `.downcity/memory/daily/<date>.md` 文件路径。
-   */
-  getDowncityMemoryDailyPath(date: string): string;
-  /**
-   * `.downcity/agents/<agentId>/sessions` 根目录路径。
-   */
-  getDowncitySessionRootDirPath(): string;
-  /**
-   * `.downcity/agents/<agentId>/sessions/<sessionId>` 目录路径。
-   */
-  getDowncitySessionDirPath(sessionId: string): string;
-}
-
-/**
- * Plugin 配置持久化能力集合。
- */
-export interface AgentPluginConfigRuntime {
-  /**
-   * 将当前 `plugins` 配置块写回宿主配置存储。
-   */
-  persistProjectPlugins(plugins: DowncityConfig["plugins"] | undefined): Promise<string>;
-}

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

@@ -1,387 +0,0 @@
-/**
- * Agent 执行上下文类型定义。
- *
- * 职责说明（中文）
- * - 这里定义 plugin runtime、plugin、prompt system 共用的统一执行上下文。
- * - `AgentContext` 是一个 class，表达"当前一次执行可见的能力面"，不是宿主状态本体。
- * - 同一 agent 实例全程共享同一个 context；plugin、session、executor 都基于它读写状态。
- */
-
-import type { LanguageModel } from "ai";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type {
-  AgentPathRuntime,
-  AgentPluginConfigRuntime,
-} from "@/types/agent/AgentRuntimeAssembly.js";
-import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
-import type { JsonValue } from "@/types/common/Json.js";
-import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
-import type { Plugin } from "@/types/plugin/PluginDefinition.js";
-import type {
-  SessionMetadataV1,
-  SessionRecordV1,
-} from "@/executor/types/SessionRecords.js";
-import type {
-  SessionRunInput,
-  SessionRunResult,
-} from "@/executor/types/SessionRun.js";
-import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
-import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
-import type {
-  SessionMutationSubscriber,
-  SessionMutationUnsubscribe,
-} from "@/types/session/SessionMutation.js";
-import type { SessionApprovalRuntimeEvent } from "@/types/session/SessionApproval.js";
-import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-import { getSessionRunContext } from "@/executor/SessionRunScope.js";
-
-/**
- * 跨 plugin runtime 调用参数。
- */
-export interface InvokePluginParams {
-  /**
-   * 目标 plugin 名称。
-   */
-  plugin: string;
-  /**
-   * 目标 action 名称。
-   */
-  action: string;
-  /**
-   * 调用时附带的结构化 payload。
-   */
-  payload?: JsonValue;
-}
-
-/**
- * 跨 plugin runtime 调用结果。
- */
-export interface InvokePluginResult {
-  /**
-   * 调用是否成功。
-   */
-  success: boolean;
-  /**
-   * 成功时返回的数据载荷。
-   */
-  data?: JsonValue;
-  /**
-   * 失败时的错误信息。
-   */
-  error?: string;
-}
-
-/**
- * 跨 plugin runtime 调用端口。
- */
-export interface InvokePluginPort {
-  /**
-   * 调用指定 plugin action。
-   */
-  invoke(params: InvokePluginParams): Promise<InvokePluginResult>;
-}
-
-/**
- * 单个 Session 执行端口。
- */
-export interface SessionExecutorPort {
-  /**
-   * 执行一次 session run。
-   */
-  run(params: SessionRunInput): Promise<SessionRunResult>;
-
-  /**
-   * 请求取消当前正在执行的 turn。
-   *
-   * 关键点（中文）
-   * - 返回 `true` 表示已发出取消请求。
-   * - 返回 `false` 表示当前没有可取消的执行。
-   */
-  stop(): boolean;
-}
-
-/**
- * 单个 Session 实例端口。
- */
-export interface SessionPort {
-  /**
-   * 当前 session 标识。
-   */
-  readonly sessionId: string;
-  /**
-   * 获取当前 session 的执行端口。
-   */
-  getExecutor(): SessionExecutorPort;
-  /**
-   * 获取当前 session 的持久化端口。
-   */
-  getHistoryStore(): SessionHistoryStore;
-  /**
-   * 向当前 session actor 追加一条新的 prompt。
-   *
-   * 关键点（中文）
-   * - 这是面向 SDK / transport 的统一交互输入入口。
-   * - 返回值只有在当前输入被绑定到某个 turn 后才会兑现。
-   */
-  prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle>;
-  /**
-   * 停止当前 turn，并取消尚未被吸收的排队 prompt。
-   */
-  stop(): Promise<AgentSessionStopResult>;
-  /**
-   * 订阅当前 session 后续产生的 future 事件。
-   *
-   * 关键点（中文）
-   * - 只广播订阅之后产生的事件。
-   * - 当前 Message snapshot 通过公开 SDK `session.messages()` 读取。
-   */
-  subscribe(
-    subscriber: SessionMutationSubscriber,
-  ): SessionMutationUnsubscribe;
-  /**
-   * 发布一条 session runtime 事件。
-   *
-   * 关键点（中文）
-   * - plugin runtime 用它把审批、外部进度等非模型 chunk 事件推送给订阅方。
-   * - 历史消息持久化仍由 append_user_message / append_assistant_message 负责。
-   */
-  publishEvent(event: SessionApprovalRuntimeEvent): Promise<void>;
-  /**
-   * 追加一条 user 消息。
-   */
-  append_user_message(params: {
-    /**
-     * 已构造好的完整消息。
-     */
-    message?: SessionRecordV1 | null;
-    /**
-     * 兜底文本内容。
-     */
-    text?: string;
-    /**
-     * 附加元数据。
-     */
-    extra?: SessionMetadataV1["extra"];
-  }): Promise<void>;
-  /**
-   * 追加一条 assistant 消息。
-   */
-  append_assistant_message(params: {
-    /**
-     * 已构造好的完整消息。
-     */
-    message?: SessionRecordV1 | null;
-    /**
-     * 兜底文本内容。
-     */
-    fallbackText?: string;
-    /**
-     * 附加元数据。
-     */
-    extra?: SessionMetadataV1["extra"];
-  }): Promise<void>;
-  /**
-   * 返回当前 session 是否正在执行。
-   */
-  isExecuting(): boolean;
-}
-
-/**
- * Session 集合入口。
- */
-export interface SessionCollectionPort {
-  /**
-   * 获取指定 sessionId 对应的 Session 实例。
-   */
-  get(sessionId: string): SessionPort;
-  /**
-   * 返回当前所有执行中的 sessionId。
-   */
-  listExecutingSessionIds(): string[];
-  /**
-   * 返回当前执行中的 session 数量。
-   */
-  getExecutingSessionCount(): number;
-  /**
-   * 解析指定 session 当前绑定的模型实例。
-   *
-   * 关键点（中文）
-   * - 模型归属于 session，而不是 agent 全局运行时。
-   * - 这里会触发 session 初始化/宿主配置，适合 task 等后台链路按 session 读取模型。
-   */
-  resolveModel(sessionId: string): Promise<LanguageModel | undefined>;
-}
-
-/**
- * AgentContext 构造参数。
- *
- * 关键点（中文）
- * - 装配方负责把 session / plugins 等上层依赖注入进来。
- * - `env` 必须传入 agent 持有的 mutable 共享对象引用，不要在这里克隆。
- */
-export interface AgentContextOptions {
-  /** 当前命令工作目录。 */
-  cwd: string;
-  /** 当前项目根目录。 */
-  rootPath: string;
-  /** 统一日志器。 */
-  logger: Logger;
-  /** 当前运行时已解析配置。 */
-  config: DowncityConfig;
-  /**
-   * 当前 agent env 共享对象引用。
-   *
-   * 关键点（中文）
-   * - 必须是 Agent 持有的同一个 mutable 引用，不要克隆后再传入。
-   * - Session step 内优先读取队列已经提交的 effective env。
-   */
-  env: Record<string, string>;
-  /** 当前生效的 system 文本集合。 */
-  systems: string[];
-  /** 当前可见的路径能力集合。 */
-  paths: AgentPathRuntime;
-  /** 当前可见的 plugin 配置持久化能力集合。 */
-  pluginConfig: AgentPluginConfigRuntime;
-  /** 当前 agent 持有的插件实例集合。 */
-  pluginInstances: Map<string, Plugin>;
-  /** Session 能力入口。 */
-  session: SessionCollectionPort;
-  /** Plugin 调用入口。 */
-  plugins: AgentPlugins;
-}
-
-/**
- * 统一执行上下文。
- *
- * 关键点（中文）
- * - 字段全部 readonly，构造一次后语义稳定，避免 plugin 误改。
- * - `env` 引用 agent 级共享 mutable 对象，`...ctx.env` / `ctx.env.FOO` 直接可用。
- * - `invoke` 是构造期组装的 plugin 调用端口，对外仍以 `InvokePluginPort` 形态暴露。
- */
-export class AgentContext {
-  /** 当前命令工作目录。 */
-  readonly cwd: string;
-  /** 当前项目根目录。 */
-  readonly rootPath: string;
-  /** 统一日志器。 */
-  readonly logger: Logger;
-  /** 当前运行时已解析配置。 */
-  readonly config: DowncityConfig;
-  /** 当前 Agent configured env 共享对象。 */
-  private readonly configured_env: Record<string, string>;
-  /** 当前 Agent configured system 文本。 */
-  private readonly configured_systems: string[];
-  /** 当前可见的路径能力集合。 */
-  readonly paths: AgentPathRuntime;
-  /** 当前可见的 plugin 配置持久化能力集合。 */
-  readonly pluginConfig: AgentPluginConfigRuntime;
-  /** 当前 agent 持有的插件实例集合。 */
-  readonly pluginInstances: Map<string, Plugin>;
-  /** Session 能力入口。 */
-  readonly session: SessionCollectionPort;
-  /** Plugin 调用入口。 */
-  readonly plugins: AgentPlugins;
-  /** 跨 plugin runtime 调用主入口。 */
-  readonly invoke: InvokePluginPort;
-
-  constructor(options: AgentContextOptions) {
-    this.cwd = options.cwd;
-    this.rootPath = options.rootPath;
-    this.logger = options.logger;
-    this.config = options.config;
-    this.configured_env = options.env;
-    this.configured_systems = options.systems;
-    this.paths = options.paths;
-    this.pluginConfig = options.pluginConfig;
-    this.pluginInstances = options.pluginInstances;
-    this.session = options.session;
-    this.plugins = options.plugins;
-    this.invoke = {
-      invoke: (params) => this.invoke_plugin_action(params),
-    };
-  }
-
-  /**
-   * 读取当前调用链可见的 Agent env。
-   *
-   * 关键点（中文）
-   * - Session step 内优先返回统一输入队列已经提交的 effective env。
-   * - Session 运行外返回 Agent 配置 API 最近一次成功写入的 configured env。
-   */
-  get env(): Record<string, string> {
-    const effective_env = getSessionRunContext()?.agentEnv;
-    return effective_env
-      ? { ...effective_env }
-      : this.configured_env;
-  }
-
-  /**
-   * 读取当前调用链可见的 Agent instruction。
-   */
-  get systems(): string[] {
-    const effective_systems = getSessionRunContext()?.agentSystems;
-    return effective_systems
-      ? [...effective_systems]
-      : this.configured_systems;
-  }
-
-  /**
-   * 读取指定 sessionId 对应的 session 端口。
-   *
-   * 关键点（中文）
-   * - 返回值是统一的 `SessionPort`，而不是裸 `Executor`。
-   * - 这样 HTTP / plugin runtime / chat queue / contact 等入口都能复用同一层会话装配与执行兜底。
-   */
-  getSession(sessionId: string): SessionPort {
-    return this.session.get(sessionId);
-  }
-
-  /**
-   * 返回当前执行中的 sessionId 列表。
-   */
-  listExecutingSessionIds(): string[] {
-    return this.session.listExecutingSessionIds();
-  }
-
-  /**
-   * 返回当前执行中的 session 数量。
-   */
-  getExecutingSessionCount(): number {
-    return this.session.getExecutingSessionCount();
-  }
-
-  /**
-   * 跨 plugin runtime 调用 action 的内部实现。
-   *
-   * 关键点（中文）
-   * - 统一把 `runAction` 的成功/失败结果归一化为 `InvokePluginResult`。
-   * - 这里替代了原 `createAgentContext` 工厂里的胶水匿名函数。
-   */
-  private async invoke_plugin_action(
-    params: InvokePluginParams,
-  ): Promise<InvokePluginResult> {
-    const result = await this.plugins.runAction({
-      plugin: params.plugin,
-      action: params.action,
-      ...(params.payload !== undefined ? { payload: params.payload } : {}),
-    });
-    if (!result.success) {
-      return {
-        success: false,
-        error: result.error || result.message || "plugin action failed",
-      };
-    }
-    return {
-      success: true,
-      ...(result.data !== undefined ? { data: result.data } : {}),
-    };
-  }
-}
-
-/**
- * 允许 optional 字段的结构化配置对象。
- */
-export type StructuredConfig = {
-  [key: string]: JsonValue | undefined;
-};

package/src/types/session/SessionComposerOptions.ts

@@ -1,107 +0,0 @@
-/**
- * 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>;
-}