@downcity/agent 1.1.438 → 1.1.446

package/src/session/messages/SessionMutationFactory.ts

@@ -0,0 +1,58 @@
+/**
+ * canonical Part 到 `part` Mutation 的唯一构造入口。
+ *
+ * Part 的 `type` 与载荷必须同源，`SessionPartMutation` 又是按 Part 类型展开的联合，
+ * 所以这里按 `type` 显式分派，让编译器验证配对关系，而不是用断言关闭检查。
+ * Message 与 delta Mutation 只有单一调用点，留在各自生产方内联构造。
+ */
+
+import type {
+  SessionAgentMessagePart,
+  SessionPartMutation,
+} from "@downcity/type";
+
+/** 构造 `part` 创建或完整快照 Mutation。 */
+export function create_session_part_mutation(input: {
+  /** 当前 Mutation 的稳定唯一标识。 */
+  mutation_id: string;
+  /** 当前 Mutation 所属 Session 标识。 */
+  session_id: string;
+  /** 当前 Part 所属 Message 标识。 */
+  message_id: string;
+  /** 当前 Part 所属 Turn 标识。 */
+  turn_id?: string;
+  /** 应用当前 Mutation 后的 Message revision。 */
+  revision: number;
+  /** 当前 Mutation 创建时间戳（ms）。 */
+  created_at: number;
+  /** 被创建或更新的完整 Part 快照。 */
+  part: SessionAgentMessagePart;
+}): SessionPartMutation {
+  const base = {
+    mutation_id: input.mutation_id,
+    variant: "part" as const,
+    message_id: input.message_id,
+    ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+    revision: input.revision,
+    session_id: input.session_id,
+    created_at: input.created_at,
+    part_id: input.part.part_id,
+  };
+  const part = input.part;
+  switch (part.type) {
+    case "text":
+      return { ...base, type: "text", part };
+    case "reasoning":
+      return { ...base, type: "reasoning", part };
+    case "tool":
+      return { ...base, type: "tool", part };
+    case "file":
+      return { ...base, type: "file", part };
+    case "data":
+      return { ...base, type: "data", part };
+    case "action":
+      return { ...base, type: "action", part };
+    case "error":
+      return { ...base, type: "error", part };
+  }
+}

package/src/session/messages/SessionUserMessage.ts

@@ -1,38 +1,32 @@
 /**
  * Session User Message 与公开输入 Part 的 canonical 转换规则。
  *
- * 本模块只进行确定性数据归一化，不持有 Message、Store 或 Session 状态。
+ * 本模块只做内容归一化：把调用方提供的内容转成确定、可持久化的形状，
+ * 不分配 `part_id` 与 `sequence`——identity 属于拥有该消息的一方。
  */
 
 import type {
   SessionAgentContent,
   SessionUserContent,
+  SessionUserPartContent,
 } from "@downcity/type";
-import type { SessionUserMessagePart } from "@downcity/type";
 import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
 import {
   normalize_session_context_content,
   normalize_session_context_tag,
 } from "@/session/messages/SessionUserContext.js";
 
-/** 把 Downcity Session User parts 归一为 canonical User parts。 */
+/** 把 Downcity Session User 输入归一为尚未分配身份的内容 Part。 */
 export function normalize_session_user_parts(
   parts: SessionUserContent[] | null | undefined,
-): SessionUserMessagePart[] {
+): SessionUserPartContent[] {
   if (!Array.isArray(parts)) return [];
-  return parts.flatMap<SessionUserMessagePart>((part, index) => {
+  return parts.flatMap<SessionUserPartContent>((part) => {
     if (part.type === "text") {
-      return [{
-        part_id: `user-text:${index + 1}`,
-        sequence: index + 1,
-        type: "text",
-        text: part.text,
-      }];
+      return [{ type: "text", text: part.text }];
     }
     if (part.type === "context") {
       return [{
-        part_id: `user-context:${index + 1}`,
-        sequence: index + 1,
         type: "context",
         tag: normalize_session_context_tag(part.tag),
         context: normalize_session_context_content(part.context),
@@ -40,8 +34,6 @@ export function normalize_session_user_parts(
     }
     if (part.type === "file") {
       return [{
-        part_id: `user-file:${index + 1}`,
-        sequence: index + 1,
         type: "file",
         url: part.url,
         media_type: part.media_type,
@@ -49,8 +41,6 @@ export function normalize_session_user_parts(
       }];
     }
     return [{
-      part_id: `user-data:${index + 1}`,
-      sequence: index + 1,
       type: "data",
       data_type: part.data_type,
       data: to_session_json_value(part.data),
@@ -59,21 +49,6 @@ export function normalize_session_user_parts(
   });
 }
 
-/** 校验直接写入的 canonical User Parts，并保留已有 Part identity。 */
-export function normalize_canonical_session_user_parts(
-  parts: readonly SessionUserMessagePart[],
-): SessionUserMessagePart[] {
-  return parts.map((part, index) => {
-    const canonical = { ...structuredClone(part), sequence: index + 1 };
-    if (canonical.type !== "context") return canonical;
-    return {
-      ...canonical,
-      tag: normalize_session_context_tag(canonical.tag),
-      context: normalize_session_context_content(canonical.context),
-    };
-  });
-}
-
 /** 判断 Assistant 结果中是否包含可持久化内容。 */
 export function has_assistant_result_content(
   parts: readonly SessionAgentContent[],

package/src/{executor/core-engine/CoreEngineSignals.ts → session/runner/AssistantParts.ts}

@@ -1,18 +1,13 @@
 /**
- * CoreEngine Tool Loop 的纯信号与诊断模块。
+ * AssistantParts：Assistant 产出的读取与诊断工具。
  *
- * 所有消息判断都直接读取 canonical `SessionAgentMessagePart`，不依赖 UI 投影。
+ * 关键点（中文）：所有判断都直接读取 canonical `SessionAgentMessagePart`，
+ * 不依赖 UI 投影，也不修改任何 Part。
  */
 
 import type { JsonObject } from "@downcity/type";
 import type { SessionAgentMessagePart } from "@downcity/type";
 
-/** 单次 Tool Loop 允许的最大 Step 数。 */
-export const MAX_TOOL_LOOP_STEPS = 64;
-
-/** 不完整响应自动恢复的最大次数。 */
-export const MAX_INCOMPLETE_RESPONSE_RECOVERIES = 1;
-
 /** 调试日志中的文本预览最大长度。 */
 const DEBUG_TEXT_PREVIEW_MAX_CHARS = 180;
 
@@ -106,19 +101,6 @@ export function extract_assistant_text(
     .trim();
 }
 
-/** 构造不完整响应恢复提示。 */
-export function build_incomplete_response_recovery_nudge(
-  recovery_index: number,
-): string {
-  const round = Math.max(1, recovery_index);
-  return [
-    `系统恢复提醒（第 ${round} 次）：上一轮响应在流式阶段异常中断。`,
-    "不要复述已完成内容。",
-    "请从中断处继续；如果需要工具，请重新发起完整工具调用。",
-    "只有在答案完整结束、任务真正完成、或明确受阻时才停止。",
-  ].join("\n");
-}
-
 /** 检测模型报告未知完成原因或存在未完成 Tool Part 的情况。 */
 export function detect_incomplete_response(input: {
   /** 当前 Step 结果。 */

package/src/{executor/core-engine/CoreEngineContextCompaction.ts → session/runner/ContextPressure.ts}

@@ -1,15 +1,15 @@
 /**
- * CoreEngine Downcity 模型上下文压缩模块。
+ * ContextPressure：上下文压力阈值判断。
  *
- * 本模块只判断真实 Provider usage 是否达到恢复阈值；具体选择、摘要和持久化全部
- * 归属于 SessionComposer 的 Context Policy。
+ * 本模块只判断真实 Provider usage 是否接近上下文窗口上限；具体选择、摘要和持久化
+ * 全部归属于 SessionComposer 的上下文推进实现。
  */
 
 /** usage 达到模型上下文窗口 95% 时安排下一 step 压缩。 */
-export const MODEL_CONTEXT_COMPACTION_TRIGGER_RATIO = 0.95;
+export const CONTEXT_PRESSURE_RATIO = 0.95;
 
 /** 读取 Provider usage 中的实际总 token。 */
-export function resolve_model_usage_tokens(usage: unknown): number | null {
+export function resolve_usage_tokens(usage: unknown): number | null {
   if (!usage || typeof usage !== "object") return null;
   const record = usage as Record<string, unknown>;
   const total_tokens = read_non_negative_number(record.total_tokens ?? record.totalTokens);
@@ -21,21 +21,21 @@ export function resolve_model_usage_tokens(usage: unknown): number | null {
 }
 
 /** 计算真实 usage 占当前模型上下文窗口的比例。 */
-export function resolve_model_usage_ratio(
+export function resolve_usage_ratio(
   usage: unknown,
   context_window: number | undefined,
 ): number | null {
   if (!Number.isSafeInteger(context_window) || Number(context_window) <= 0) return null;
-  const used_tokens = resolve_model_usage_tokens(usage);
+  const used_tokens = resolve_usage_tokens(usage);
   return used_tokens === null ? null : used_tokens / Number(context_window);
 }
 
-/** 判断一次真实 usage 是否要求下一 step 继续压缩。 */
-export function should_compact_after_usage(
+/** 判断一次真实 usage 是否已接近上下文窗口上限。 */
+export function is_context_pressured(
   usage_ratio: number | null,
 ): boolean {
   if (usage_ratio === null || !Number.isFinite(usage_ratio)) return false;
-  return usage_ratio >= MODEL_CONTEXT_COMPACTION_TRIGGER_RATIO;
+  return usage_ratio >= CONTEXT_PRESSURE_RATIO;
 }
 
 /** 读取非负数字。 */

package/src/{executor/services/ExecutorRecoveryPolicy.ts → session/runner/ContextRetry.ts}

@@ -1,9 +1,9 @@
 /**
- * ExecutorRecoveryPolicy：执行恢复与重试策略。
+ * ContextRetry：推进上下文后重试整轮 Turn 的策略。
  *
  * 关键点（中文）
- * - 统一封装“压缩后重试”和“普通失败兜底”逻辑。
- * - Executor 提供单次 Turn 行为，本模块只决定是否恢复并重试。
+ * - 统一封装「推进上下文后重试」和「普通失败兜底」逻辑。
+ * - 执行器提供单次 Turn 行为，本模块只决定是否恢复并重试。
  * - 不改变外部行为，只把异常分流规则集中到一个地方。
  */
 
@@ -11,16 +11,16 @@ import type { Logger } from "@/utils/logger/Logger.js";
 import type { SessionTurnExecutionResult } from "@/types/session/SessionExecution.js";
 
 /**
- * 可压缩错误的最大重试次数。
+ * 上下文推进后的最大重试次数。
  */
-const MAX_COMPACTION_RETRY_ATTEMPTS = 3;
+const MAX_CONTEXT_ADVANCE_ATTEMPTS = 3;
 
-interface ExecutorRecoveryPolicyOptions {
+interface ContextRetryOptions {
   /** 当前 Session 稳定标识。 */
   session_id: string;
 
   /** 请求 Composer 尝试推进上下文派生状态。 */
-  recover_context: (error: unknown) => Promise<boolean>;
+  advance_context: (error: unknown) => Promise<boolean>;
 
   /**
    * 当前 session 统一日志器。
@@ -28,24 +28,24 @@ interface ExecutorRecoveryPolicyOptions {
   logger: Logger;
 }
 
-interface ExecutorRecoveryInput {
-  /** 按当前恢复次数执行完整 Turn。 */
-  execute_turn: (retry_count: number) => Promise<SessionTurnExecutionResult>;
+interface ContextRetryInput {
+  /** 按当前上下文推进次数执行完整 Turn。 */
+  execute_turn: (advance_count: number) => Promise<SessionTurnExecutionResult>;
 }
 
 /**
  * 执行恢复与重试策略服务。
  */
-export class ExecutorRecoveryPolicy {
-  private readonly recover_context: ExecutorRecoveryPolicyOptions["recover_context"];
+export class ContextRetry {
+  private readonly advance_context: ContextRetryOptions["advance_context"];
   private readonly logger: Logger;
 
-  constructor(options: ExecutorRecoveryPolicyOptions) {
+  constructor(options: ContextRetryOptions) {
     const session_id = String(options.session_id || "").trim();
-    this.recover_context = options.recover_context;
+    this.advance_context = options.advance_context;
     this.logger = options.logger;
     if (!session_id) {
-      throw new Error("ExecutorRecoveryPolicy requires a non-empty session_id");
+      throw new Error("ContextRetry requires a non-empty session_id");
     }
   }
 
@@ -53,25 +53,25 @@ export class ExecutorRecoveryPolicy {
    * 执行一次带恢复策略的 Session Turn。
    */
   async execute_with_retry(
-    input: ExecutorRecoveryInput,
+    input: ContextRetryInput,
   ): Promise<SessionTurnExecutionResult> {
-    let retry_count = 0;
+    let advance_count = 0;
     while (true) {
       try {
-        return await input.execute_turn(retry_count);
+        return await input.execute_turn(advance_count);
       } catch (error) {
-        if (retry_count < MAX_COMPACTION_RETRY_ATTEMPTS) {
-          const recovered = await this.recover_context(error);
-          if (recovered) {
-            await this.logger.log("info", "[agent] compacting", {
-              retryCount: retry_count,
+        if (advance_count < MAX_CONTEXT_ADVANCE_ATTEMPTS) {
+          const advanced = await this.advance_context(error);
+          if (advanced) {
+            await this.logger.log("info", "[agent] context.advance", {
+              advanceCount: advance_count,
               error: String(error),
             });
-            retry_count += 1;
+            advance_count += 1;
             continue;
           }
         }
-        if (retry_count > 0) {
+        if (advance_count > 0) {
           return this.build_failure_result({
             error_text:
               "Context length exceeded and retries failed. Please resend your question.",

package/src/{executor/core-engine/CoreEngineError.ts → session/runner/ModelFailure.ts}

@@ -1,9 +1,9 @@
 /**
- * CoreEngine 执行错误归一化工具。
+ * ModelFailure：模型调用错误归一化。
  *
  * 关键点（中文）
  * - 模型流的最终错误可能只是兜底包装，底层 Provider 错误应优先保留。
- * - Executor 内部 CoreEngine 流程只需要消费这里输出的日志字段与最终错误文本。
+ * - 执行器只需要消费这里输出的日志字段与最终错误文本。
  */
 
 import type { JsonObject } from "@downcity/type";
@@ -28,7 +28,7 @@ export function summarize_stream_error(error: unknown): JsonObject {
 /**
  * 提取实际应返回给上层的错误文本。
  */
-export function resolve_effective_core_engine_error(params: {
+export function resolve_model_error(params: {
   /**
    * 外层捕获到的执行错误。
    */