@downcity/agent 1.1.430 → 1.1.438

package/src/executor/composer/system/default/variables/VariableReplacer.ts

@@ -1,154 +0,0 @@
-/**
- * VariableReplacer：prompt 变量替换模块。
- *
- * 关键点（中文）
- * - 专职负责模板变量构建与文本替换。
- * - 与 message 组装解耦，便于独立复用与测试。
- */
-
-import { resolve_prompt_geo_context } from "@executor/composer/system/default/variables/GeoContext.js";
-import type { PromptVariables } from "@executor/composer/system/default/variables/PromptTypes.js";
-import { render_template_variables } from "@/utils/Template.js";
-import {
-  format_date_in_timezone,
-  format_date_time_in_timezone,
-  format_year_in_timezone,
-  resolve_runtime_timezone,
-} from "@/utils/Time.js";
-
-/**
- * Prompt 变量替换模式。
- *
- * 关键点（中文）
- * - `full`：完整替换（包含时间/地点等上下文动态变量）。
- * - `stable`：仅保留稳定替换；但 `current_year` 属于低频年度变量，仍保留真实值。
- */
-export type PromptVariableMode = "full" | "stable";
-
-async function buildPromptVariables(options?: {
-  /**
-   * 项目路径（用于 `project_path/project_root`）。
-   */
-  projectPath?: string;
-
-  /**
-   * 会话 ID（用于 `session_id`）。
-   */
-  session_id?: string;
-
-  /**
-   * 变量替换模式（默认 full）。
-   */
-  mode?: PromptVariableMode;
-}): Promise<PromptVariables> {
-  const mode = options?.mode === "stable" ? "stable" : "full";
-  const projectPath = String(options?.projectPath || "").trim() || process.cwd();
-  const safeLocalTimezone = resolve_runtime_timezone();
-  const now = new Date();
-  if (mode === "stable") {
-    return {
-      currentDate: "[See runtime clock tail message]",
-      currentTime: "[See runtime clock tail message]",
-      currentYear: format_year_in_timezone(now, safeLocalTimezone),
-      timezone: safeLocalTimezone,
-      location: "[See runtime clock tail message]",
-      projectPath,
-      project_root: projectPath,
-      session_id: "[Runtime session id]",
-    };
-  }
-
-  const geo = await resolve_prompt_geo_context();
-  const session_id = String(options?.session_id || "").trim() || "unknown";
-  return {
-    // 关键点（中文）：时间字段只使用本机 runtime 时区，避免代理/IP 地理推断改变 cron 与相对时间口径。
-    currentDate: format_date_in_timezone(now, safeLocalTimezone),
-    currentTime: format_date_time_in_timezone(now, safeLocalTimezone),
-    currentYear: format_year_in_timezone(now, safeLocalTimezone),
-    timezone: safeLocalTimezone,
-    location: geo.location,
-    projectPath,
-    project_root: projectPath,
-    session_id,
-  };
-}
-
-/**
- * 替换 prompt 模板变量。
- *
- * 当前支持（中文）
- * - `{{current_time}}`
- * - `{{current_date}}`
- * - `{{current_year}}`
- * - `{{timezone}}`
- * - `{{location}}`
- * - `{{project_path}}`
- * - `{{project_root}}`
- * - `{{session_id}}`
- */
-export async function replace_variables_in_prompts(
-  prompt: string,
-  options?: {
-    /**
-     * 项目路径（用于 `project_path/project_root`）。
-     */
-    projectPath?: string;
-
-    /**
-     * 会话 ID（用于 `session_id`）。
-     */
-    session_id?: string;
-
-    /**
-     * 变量替换模式（默认 full）。
-     */
-    mode?: PromptVariableMode;
-  },
-): Promise<string> {
-  if (!prompt) return prompt;
-  const variables = await buildPromptVariables(options);
-  return render_template_variables(prompt, {
-    current_date: variables.currentDate,
-    current_time: variables.currentTime,
-    current_year: variables.currentYear,
-    timezone: variables.timezone,
-    location: variables.location,
-    project_path: variables.projectPath,
-    project_root: variables.project_root,
-    session_id: variables.session_id,
-  });
-}
-
-/**
- * 构建每轮运行末尾的 runtime clock system prompt。
- *
- * 关键点（中文）
- * - system/static prompt 使用 stable 模式，不能直接承载每轮变化的时间。
- * - 这里在 messages 尾部补齐 `current_date/current_time/timezone`，让 chat、task、prompt 的时间语义统一。
- * - 只使用本机 runtime 时区，避免每轮为了地理位置进行网络请求。
- */
-export function build_runtime_clock_system_prompt(options?: {
-  /**
-   * 项目路径（用于 `project_root`）。
-   */
-  projectPath?: string;
-
-  /**
-   * 会话 ID（用于 `session_id`）。
-   */
-  session_id?: string;
-}): string {
-  const timezone = resolve_runtime_timezone();
-  const projectPath = String(options?.projectPath || "").trim() || process.cwd();
-  const session_id = String(options?.session_id || "").trim() || "unknown";
-  const now = new Date();
-  return [
-    "# Runtime Clock Context",
-    "The following fields are the authoritative time context for this run. Prefer them when resolving relative time expressions such as today, tomorrow, or a specific hour:",
-    `- current_date: ${format_date_in_timezone(now, timezone)}`,
-    `- current_time: ${format_date_time_in_timezone(now, timezone)}`,
-    `- timezone: ${timezone}`,
-    `- session_id: ${session_id}`,
-    `- project_root: ${projectPath}`,
-  ].join("\n");
-}

package/src/executor/core-engine/CoreEngineMessageState.ts

@@ -1,117 +0,0 @@
-/**
- * CoreEngine 模型消息运行态。
- *
- * 关键点（中文）
- * - CoreEngine 只维护本 Turn 后续模型 Step 需要的标准 ModelMessage。
- * - canonical SessionMessage 的持久化由 SessionMessages 独立拥有。
- */
-
-import type { ModelMessage } from "@downcity/type";
-import { session_messages_to_model_messages } from "@executor/messages/SessionModelMessages.js";
-import type { SessionMessage, SessionUserMessage } from "@downcity/type";
-
-/**
- * CoreEngine 单轮执行期间的消息基线。
- */
-export class CoreEngineMessageState {
-  /**
-   * 当前模型侧消息基线。
-   */
-  private current_model_messages: ModelMessage[];
-
-  /**
-   * 当前项目根目录，用于解析历史中的相对路径 file part。
-   */
-  private readonly project_root?: string;
-
-  private constructor(params: {
-    /**
-     * 当前模型侧消息基线。
-     */
-    model_messages: ModelMessage[];
-    /**
-     * 当前项目根目录。
-     */
-    project_root?: string;
-  }) {
-    this.current_model_messages = params.model_messages;
-    this.project_root = params.project_root;
-  }
-
-  /**
-   * 基于初始模型消息创建运行态。
-   */
-  static async create(params: {
-    /**
-     * 初始标准模型消息。
-     */
-    messages: ModelMessage[];
-    /**
-     * 当前项目根目录。
-     */
-    project_root?: string;
-  }): Promise<CoreEngineMessageState> {
-    return new CoreEngineMessageState({
-      model_messages: Array.isArray(params.messages) ? [...params.messages] : [],
-      project_root: params.project_root,
-    });
-  }
-
-  /**
-   * 读取当前模型消息。
-   */
-  get model_messages(): ModelMessage[] {
-    return this.current_model_messages;
-  }
-
-  /**
-   * 把 Step 间新增的 canonical User Message 并入模型基线。
-   */
-  async append_merged_user_messages(
-    messages: SessionUserMessage[],
-  ): Promise<ModelMessage[]> {
-    if (messages.length === 0) return [];
-    return await this.append_session_messages(messages);
-  }
-
-  /**
-   * 追加内部生成的 user nudge 消息。
-   */
-  async append_user_message(message: SessionUserMessage): Promise<void> {
-    await this.append_session_messages([message]);
-  }
-
-  /**
-   * 追加 SDK 返回的模型 response messages。
-   */
-  append_model_messages(messages: ModelMessage[]): void {
-    if (!Array.isArray(messages) || messages.length === 0) return;
-    this.current_model_messages = [...this.current_model_messages, ...messages];
-  }
-
-  /**
-   * 原子替换当前模型侧消息基线。
-   *
-   * 关键点（中文）：compact 只替换 Provider 后续可见的 ModelMessage，
-   * Session 语义消息与持久化历史仍保持完整，等待 turn 收口后再单独归档。
-   */
-  replace_model_messages(messages: ModelMessage[]): void {
-    this.current_model_messages = Array.isArray(messages) ? [...messages] : [];
-  }
-
-  /** 使用 Composer 重新生成的模型历史原子替换当前基线。 */
-  replace_model_history(messages: ModelMessage[]): void {
-    this.current_model_messages = Array.isArray(messages) ? [...messages] : [];
-  }
-
-  private async append_session_messages(
-    messages: SessionMessage[],
-  ): Promise<ModelMessage[]> {
-    const model_messages = await session_messages_to_model_messages(
-      messages,
-      this.project_root,
-    );
-    this.current_model_messages = [...this.current_model_messages, ...model_messages];
-    return model_messages;
-  }
-}

package/src/session/SessionCommand.ts

@@ -1,42 +0,0 @@
-/**
- * Session 有序输入队列中的可执行 Command。
- *
- * Command 对象封装一次需要遵守 Session FIFO 与检查点顺序的行为。Queue 只保存
- * 对象和维护顺序，不识别 Prompt、配置、Compact 等业务种类。
- */
-
-import type {
-  SessionCommandCompletion,
-  SessionCommandOptions,
-} from "@/types/session/SessionCommand.js";
-
-/** 一次等待在 Session 检查点执行的 Command。 */
-export class SessionCommand {
-  private readonly execute_command: SessionCommandOptions["execute"];
-  private readonly cancel_command?: SessionCommandOptions["cancel"];
-  private readonly completion_info?: SessionCommandOptions["completion"];
-
-  /** @param options 当前 Command 的执行与可选取消行为。 */
-  constructor(options: SessionCommandOptions) {
-    this.execute_command = options.execute;
-    this.cancel_command = options.cancel;
-    this.completion_info = options.completion;
-  }
-
-  /** 执行当前 Command，并返回成功后需要持久化的完成信息。 */
-  async execute(): Promise<SessionCommandCompletion | undefined> {
-    await this.execute_command();
-    return this.completion_info;
-  }
-
-  /**
-   * 在 Session stop 时尝试取消当前 Command。
-   *
-   * @returns true 表示 Command 已取消并应从 Queue 移除；false 表示继续保留。
-   */
-  cancel(): boolean {
-    if (!this.cancel_command) return false;
-    this.cancel_command();
-    return true;
-  }
-}

package/src/session/messages/SessionAssistantMessageState.ts

@@ -1,392 +0,0 @@
-/**
- * canonical Assistant Message 的串行状态转换器。
- *
- * 关键点（中文）
- * - 只拥有每条 Assistant Message 的临时写事务链，不拥有 Message 事实源。
- * - 所有草稿、Part、Interaction 与终态都先持久化，再交回 SessionMessages 接受。
- * - 同一 Assistant Message 的 revision 严格串行，不同 Message 可以并行推进。
- */
-
-import { generate_id } from "@/utils/Id.js";
-import { SessionMessageInteractionWriter } from "@/session/messages/SessionMessageInteractionWriter.js";
-import type {
-  SessionAssistantInteractionPart,
-  SessionAssistantMessage,
-  SessionAssistantMessagePart,
-  SessionAssistantToolPart,
-  SessionMessage,
-} from "@downcity/type";
-import type {
-  SessionInteractionCloseInput,
-  SessionInteractionRequest,
-  SessionInteractionResponse,
-} from "@downcity/type";
-import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
-import type { SessionMutation } from "@downcity/type";
-import type { SessionAssistantMessageStateOptions } from "@/types/session/SessionAssistantMessageState.js";
-
-/** 管理 Assistant 草稿、Part 与 Interaction 的原子状态转换。 */
-export class SessionAssistantMessageState {
-  private readonly session_id: string;
-  private readonly options: SessionAssistantMessageStateOptions;
-  /** 按 Assistant Message 隔离的完整写事务链。 */
-  private readonly write_chains = new Map<string, Promise<void>>();
-  /** Assistant Message 内 Interaction Part 的原子状态写入器。 */
-  private readonly interaction_writer: SessionMessageInteractionWriter;
-
-  constructor(options: SessionAssistantMessageStateOptions) {
-    this.session_id = options.session_id;
-    this.options = options;
-    this.interaction_writer = new SessionMessageInteractionWriter({
-      list_messages: options.list_messages,
-      find_streaming_tool: (tool_call_id) => this.find_streaming_tool(tool_call_id),
-      enqueue_assistant_write: (message_id, operation) =>
-        this.enqueue_write(message_id, operation),
-      commit_assistant_snapshot: (current, parts) =>
-        this.commit_snapshot(current, parts),
-    });
-  }
-
-  /** 写入 Assistant 原始文本 delta。 */
-  async append_delta(
-    message_id: string,
-    part_id: string,
-    type: "text" | "reasoning",
-    delta: string,
-  ): Promise<void> {
-    if (!delta) return;
-    await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      const part = current.parts.find((item) => item.part_id === part_id);
-      if (!part || (part.type !== "text" && part.type !== "reasoning")) {
-        throw new Error(`Delta target Part does not exist: ${part_id}`);
-      }
-      if (part.type !== type) {
-        throw new Error(`Delta type changed for Part: ${part_id}`);
-      }
-      const created_at = Date.now();
-      const message: SessionAssistantMessage = {
-        ...current,
-        revision: current.revision + 1,
-        updated_at: created_at,
-        parts: current.parts.map((item) =>
-          item.part_id === part_id &&
-              (item.type === "text" || item.type === "reasoning")
-            ? { ...item, text: item.text + delta }
-            : item,
-        ),
-      };
-      await this.options.store.write_assistant_message(message);
-      this.options.accept_mutation({
-        mutation_id: generate_id(),
-        variant: "delta",
-        type,
-        message_id,
-        revision: message.revision,
-        session_id: this.session_id,
-        turn_id: message.turn_id,
-        created_at,
-        part_id,
-        delta,
-      }, message);
-    });
-  }
-
-  /** 写入 Assistant Tool 输入原始 delta。 */
-  async append_tool_input_delta(
-    message_id: string,
-    part_id: string,
-    tool_call_id: string,
-    delta: string,
-  ): Promise<void> {
-    if (!delta) return;
-    await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      const part = current.parts.find((item) => item.part_id === part_id);
-      if (!part || part.type !== "tool") {
-        throw new Error(`Tool input Delta target Part does not exist: ${part_id}`);
-      }
-      if (part.tool_call_id !== tool_call_id) {
-        throw new Error(`Tool input Delta tool_call_id changed for Part: ${part_id}`);
-      }
-      if (part.state !== "input-streaming") {
-        throw new Error(`Tool input Delta cannot update ${part.state} Part: ${part_id}`);
-      }
-      const created_at = Date.now();
-      const message: SessionAssistantMessage = {
-        ...current,
-        revision: current.revision + 1,
-        updated_at: created_at,
-        parts: current.parts.map((item) =>
-          item.part_id === part_id && item.type === "tool"
-            ? { ...item, input_text: `${item.input_text || ""}${delta}` }
-            : item,
-        ),
-      };
-      await this.options.store.write_assistant_message(message);
-      this.options.accept_mutation({
-        mutation_id: generate_id(),
-        variant: "delta",
-        type: "tool_input",
-        message_id,
-        revision: message.revision,
-        session_id: this.session_id,
-        turn_id: message.turn_id,
-        created_at,
-        part_id,
-        tool_call_id,
-        delta,
-      }, message);
-    });
-  }
-
-  /** 提交一个完整 canonical Assistant Part。 */
-  async update_part(
-    message_id: string,
-    part: SessionAssistantMessagePart,
-  ): Promise<void> {
-    await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      const existing = current.parts.find((item) => item.part_id === part.part_id);
-      if (existing && existing.sequence !== part.sequence) {
-        throw new Error(`Assistant Part sequence changed: ${part.part_id}`);
-      }
-      const created_at = Date.now();
-      const next_part = structuredClone(part);
-      const message: SessionAssistantMessage = {
-        ...current,
-        revision: current.revision + 1,
-        updated_at: created_at,
-        parts: (existing
-          ? current.parts.map((item) =>
-              item.part_id === part.part_id ? next_part : item)
-          : [...current.parts, next_part]
-        ).sort((left, right) => left.sequence - right.sequence),
-      };
-      await this.options.store.write_assistant_message(message);
-      this.options.accept_mutation({
-        mutation_id: generate_id(),
-        variant: "part",
-        type: next_part.type,
-        message_id,
-        revision: message.revision,
-        session_id: this.session_id,
-        turn_id: message.turn_id,
-        created_at,
-        part_id: next_part.part_id,
-        part: next_part,
-      } as SessionMutation, message);
-    });
-  }
-
-  /** 原子提交当前 Assistant step 的 metadata 快照。 */
-  async commit_step(
-    message_id: string,
-    parts: SessionAssistantMessagePart[],
-  ): Promise<void> {
-    await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      if (
-        parts.length !== current.parts.length ||
-        parts.some((part, index) =>
-          part.part_id !== current.parts[index]?.part_id ||
-          part.sequence !== current.parts[index]?.sequence
-        )
-      ) {
-        throw new Error(
-          `Assistant step changed canonical Part identity: ${message_id}`,
-        );
-      }
-      const message: SessionAssistantMessage = {
-        ...current,
-        revision: current.revision + 1,
-        updated_at: Date.now(),
-        parts: structuredClone(parts),
-      };
-      await this.options.store.write_assistant_message(message);
-      this.options.accept_message(message);
-    });
-  }
-
-  /** 收口 Assistant Message，并把草稿提交到 Active。 */
-  async complete(
-    message_id: string,
-    status: "completed" | "stopped" | "failed",
-    error?: string,
-  ): Promise<void> {
-    await this.enqueue_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      const created_at = Date.now();
-      const interrupted_interactions = status === "stopped"
-        ? current.parts.filter(
-            (part): part is SessionAssistantInteractionPart =>
-              part.type === "interaction" && part.status === "pending",
-          )
-        : [];
-      const interrupted_tool_ids = new Set(
-        interrupted_interactions.flatMap((part) =>
-          part.request.source.tool_call_id
-            ? [part.request.source.tool_call_id]
-            : [],
-        ),
-      );
-      const message: SessionAssistantMessage = {
-        ...current,
-        revision: current.revision + 1,
-        status,
-        updated_at: created_at,
-        parts: current.parts.map((part) => {
-          if (part.type === "text" || part.type === "reasoning") {
-            return { ...part, state: "done" as const };
-          }
-          if (part.type === "interaction" && part.status === "pending") {
-            return {
-              ...part,
-              status: "cancelled" as const,
-              cancel_reason: "runtime_interrupted" as const,
-              resolved_at: created_at,
-            };
-          }
-          if (
-            part.type === "tool" &&
-            part.state !== "completed" &&
-            part.state !== "failed"
-          ) {
-            return {
-              ...part,
-              state: "failed" as const,
-              error:
-                status === "stopped" &&
-                  part.state === "waiting-user" &&
-                  interrupted_tool_ids.has(part.tool_call_id)
-                  ? "Interaction cancelled"
-                  : error || "Tool did not complete before Assistant Message closed",
-            };
-          }
-          return part;
-        }),
-      };
-      await this.options.store.finalize_assistant_message(message);
-      this.options.accept_message(message);
-    });
-  }
-
-  /** 读取当前流式 Assistant 中的指定 Tool Part。 */
-  find_streaming_tool(
-    tool_call_id: string,
-  ): SessionStreamingToolLocation | undefined {
-    for (const message of this.options.list_messages()) {
-      if (message.type !== "assistant" || message.status !== "streaming") continue;
-      const part = message.parts.find(
-        (item): item is SessionAssistantToolPart =>
-          item.type === "tool" && item.tool_call_id === tool_call_id,
-      );
-      if (part) return { message_id: message.message_id, part };
-    }
-    return undefined;
-  }
-
-  /** 返回当前 Session 中全部等待用户响应的 canonical Interaction。 */
-  list_pending_interactions(): SessionAssistantInteractionPart[] {
-    return this.interaction_writer.list_pending();
-  }
-
-  /** 原子创建 Interaction，并把关联 Tool 转为 waiting-user。 */
-  async request_interaction(
-    request: SessionInteractionRequest,
-  ): Promise<SessionAssistantInteractionPart> {
-    return await this.interaction_writer.request(request);
-  }
-
-  /** 原子保存用户响应，并按 Interaction 结果恢复或终止关联 Tool。 */
-  async resolve_interaction(
-    interaction_id: string,
-    response: SessionInteractionResponse,
-  ): Promise<SessionAssistantInteractionPart> {
-    return await this.interaction_writer.resolve(interaction_id, response);
-  }
-
-  /** 原子结束未响应 Interaction，并把关联 Tool 标记为失败。 */
-  async close_interaction(
-    interaction_id: string,
-    input: SessionInteractionCloseInput,
-  ): Promise<SessionAssistantInteractionPart> {
-    return await this.interaction_writer.close(interaction_id, input);
-  }
-
-  /** 串行执行同一 Assistant Message 的完整写事务。 */
-  private async enqueue_write<T>(
-    message_id: string,
-    operation: () => Promise<T>,
-  ): Promise<T> {
-    const previous = this.write_chains.get(message_id) || Promise.resolve();
-    const result = previous.then(operation, operation);
-    const chain = result.then(() => undefined, () => undefined);
-    this.write_chains.set(message_id, chain);
-    try {
-      return await result;
-    } finally {
-      if (this.write_chains.get(message_id) === chain) {
-        this.write_chains.delete(message_id);
-      }
-    }
-  }
-
-  /** 原子提交包含多个 Part 状态变化的 Assistant 完整快照。 */
-  private async commit_snapshot(
-    current: SessionAssistantMessage,
-    parts: SessionAssistantMessagePart[],
-  ): Promise<void> {
-    const created_at = Date.now();
-    const message: SessionAssistantMessage = {
-      ...current,
-      revision: current.revision + 1,
-      updated_at: created_at,
-      parts: structuredClone(parts).sort(
-        (left, right) => left.sequence - right.sequence,
-      ),
-    };
-    await this.options.store.write_assistant_message(message);
-    const current_by_id = new Map(
-      current.parts.map((part) => [part.part_id, part]),
-    );
-    const changed_parts = message.parts.filter((part) => {
-      const previous = current_by_id.get(part.part_id);
-      return !previous || JSON.stringify(previous) !== JSON.stringify(part);
-    });
-    if (changed_parts.length === 0) {
-      this.options.accept_message(message);
-      return;
-    }
-    for (const part of changed_parts) {
-      this.options.accept_mutation({
-        mutation_id: generate_id(),
-        variant: "part",
-        type: part.type,
-        message_id: message.message_id,
-        revision: message.revision,
-        session_id: this.session_id,
-        turn_id: message.turn_id,
-        created_at,
-        part_id: part.part_id,
-        part: structuredClone(part),
-      } as SessionMutation, message);
-    }
-  }
-
-  /** 读取指定的流式 Assistant Message，否则抛出稳定领域错误。 */
-  private require_streaming_assistant(
-    message_id: string,
-  ): SessionAssistantMessage {
-    const message = [...this.options.list_messages()].find(
-      (item) => item.message_id === message_id,
-    );
-    if (!message || message.type !== "assistant") {
-      throw new Error(`Session assistant Message not found: ${message_id}`);
-    }
-    if (message.status !== "streaming") {
-      throw new Error(`Assistant Message is already closed: ${message_id}`);
-    }
-    return message;
-  }
-}