@downcity/agent 1.1.438 → 1.1.445

package/src/session/composer/policies/AdaptivePartContextPolicy.ts

@@ -1,307 +0,0 @@
-/**
- * 基于稳定 Part 游标的自适应上下文策略。
- *
- * Message 仍是 canonical 持久化聚合，Part 是上下文取舍与摘要边界。策略只写自己的
- * checkpoint 派生表，不修改 Message；单个 Agent Message 很大时也可以在
- * Message 内部形成摘要边界。
- */
-
-import type {
-  SessionAgentMessagePart,
-  SessionMessage,
-  SessionUserMessagePart,
-} from "@downcity/type";
-import { generate_id } from "@/utils/Id.js";
-import { build_text_model_messages, generate_model } from "@executor/model/ModelGenerate.js";
-import { session_messages_to_model_messages } from "@/executor/messages/SessionModelMessages.js";
-import type { SessionContextPolicy } from "@/types/session/SessionContextPolicy.js";
-import type {
-  AdaptivePartCheckpointRow,
-  StablePartCandidate,
-} from "@/types/session/AdaptivePartContextPolicy.js";
-import {
-  build_initial_session_summary_prompt,
-  build_updated_session_summary_prompt,
-  SESSION_SUMMARY_SYSTEM_PROMPT,
-} from "@/session/composer/policies/SessionSummaryPrompts.js";
-
-const POLICY_VERSION = 1;
-const SUMMARY_MAX_OUTPUT_TOKENS = 4_000;
-const CHECKPOINT_TABLE = "composer_adaptive_part_checkpoints";
-
-/** 默认 Part 级上下文策略。 */
-export class AdaptivePartContextPolicy implements SessionContextPolicy {
-  readonly name = "adaptive_part";
-
-  /** 创建当前策略独享的 checkpoint 表。 */
-  async initialize(input: Parameters<SessionContextPolicy["initialize"]>[0]): Promise<void> {
-    await input.storage.transaction((transaction) => {
-      transaction.execute(`
-        CREATE TABLE IF NOT EXISTS ${CHECKPOINT_TABLE} (
-          checkpoint_id TEXT PRIMARY KEY,
-          through_message_id TEXT NOT NULL REFERENCES messages(message_id) ON DELETE CASCADE,
-          through_message_sequence INTEGER NOT NULL,
-          through_part_sequence INTEGER NOT NULL,
-          summary TEXT NOT NULL,
-          policy_version INTEGER NOT NULL,
-          created_at INTEGER NOT NULL,
-          UNIQUE(through_message_sequence, through_part_sequence, policy_version)
-        )
-      `);
-    });
-  }
-
-  /** 返回显式摘要 system block 与 Part 边界后的 canonical 历史。 */
-  async resolve(input: Parameters<SessionContextPolicy["resolve"]>[0]) {
-    const checkpoint = await this.read_latest_checkpoint(input.storage);
-    const canonical = await input.storage.list_messages();
-    const tail = checkpoint
-      ? slice_messages_after_checkpoint(canonical, checkpoint)
-      : canonical;
-    return {
-      messages: await session_messages_to_model_messages(tail, input.project_root),
-      ...(checkpoint?.summary.trim()
-        ? {
-            system_blocks: [{
-              source: "session" as const,
-              name: "context-summary",
-              content: `<session-context-summary>\n${checkpoint.summary}\n</session-context-summary>`,
-            }],
-          }
-        : {}),
-      diagnostics: {
-        policy_name: this.name,
-        ...(canonical.at(-1)?.sequence !== undefined
-          ? { through_sequence: canonical.at(-1)?.sequence }
-          : {}),
-        ...(checkpoint
-          ? { through_part_sequence: checkpoint.through_part_sequence }
-          : {}),
-        derived: Boolean(checkpoint),
-        ...(checkpoint ? { derivation_id: checkpoint.checkpoint_id } : {}),
-      },
-    };
-  }
-
-  /** 上下文压力出现时，按体积选择较旧稳定 Part 并合并进累计摘要。 */
-  async recover(input: Parameters<SessionContextPolicy["recover"]>[0]): Promise<boolean> {
-    if (!input.model) return false;
-    const previous = await this.read_latest_checkpoint(input.storage);
-    const canonical = await input.storage.list_messages();
-    const candidates = collect_stable_parts(canonical, previous);
-    const compact_parts = select_compact_parts(candidates);
-    const boundary = compact_parts.at(-1);
-    if (!boundary) return false;
-    const conversation_text = compact_parts
-      .map(candidate_to_summary_text)
-      .filter(Boolean)
-      .join("\n");
-    if (!conversation_text) return false;
-    const prompt = previous?.summary.trim()
-      ? build_updated_session_summary_prompt({
-          previous_summary: previous.summary,
-          conversation_text,
-        })
-      : build_initial_session_summary_prompt({ conversation_text });
-    const result = await generate_model(input.model, {
-      messages: build_text_model_messages(SESSION_SUMMARY_SYSTEM_PROMPT, prompt),
-      max_output_tokens: SUMMARY_MAX_OUTPUT_TOKENS,
-    }, {
-      request_kind: "history_compaction",
-      on_failure: input.on_model_request_failure,
-    });
-    const summary = String(result.text || "").trim();
-    if (!summary) throw new Error("Context summary model returned an empty result");
-    const checkpoint_id = `checkpoint:${generate_id()}`;
-    try {
-      await input.storage.transaction((transaction) => {
-        transaction.execute(`
-          INSERT INTO ${CHECKPOINT_TABLE} (
-            checkpoint_id, through_message_id, through_message_sequence,
-            through_part_sequence, summary, policy_version, created_at
-          ) VALUES (?, ?, ?, ?, ?, ?, ?)
-        `, [
-          checkpoint_id,
-          boundary.message.message_id,
-          boundary.message.sequence,
-          boundary.part.sequence,
-          summary,
-          POLICY_VERSION,
-          Date.now(),
-        ]);
-      });
-      return true;
-    } catch (error) {
-      const latest = await this.read_latest_checkpoint(input.storage);
-      if (latest && compare_position(latest, boundary) >= 0) return true;
-      throw error;
-    }
-  }
-
-  /** 读取当前版本位置最靠后的累计 checkpoint。 */
-  private async read_latest_checkpoint(
-    storage: Parameters<SessionContextPolicy["resolve"]>[0]["storage"],
-  ): Promise<AdaptivePartCheckpointRow | null> {
-    return await storage.transaction((transaction) =>
-      transaction.get<AdaptivePartCheckpointRow>(`
-        SELECT checkpoint_id, through_message_id, through_message_sequence,
-               through_part_sequence, summary, policy_version, created_at
-        FROM ${CHECKPOINT_TABLE}
-        WHERE policy_version = ?
-        ORDER BY through_message_sequence DESC, through_part_sequence DESC
-        LIMIT 1
-      `, [POLICY_VERSION])
-    );
-  }
-}
-
-/** 收集 checkpoint 后适合进入摘要的稳定 Part。 */
-function collect_stable_parts(
-  messages: readonly SessionMessage[],
-  checkpoint: AdaptivePartCheckpointRow | null,
-): StablePartCandidate[] {
-  return messages.flatMap((message) => message.parts.flatMap((part) => {
-    if (checkpoint && compare_part_position(message.sequence, part.sequence, checkpoint) <= 0) {
-      return [];
-    }
-    if (!is_stable_summary_part(message, part)) return [];
-    return [{ message, part }];
-  }));
-}
-
-/** 判断 Part 是否稳定且值得占据累计摘要。 */
-function is_stable_summary_part(
-  message: SessionMessage,
-  part: SessionUserMessagePart | SessionAgentMessagePart,
-): boolean {
-  switch (part.type) {
-    case "reasoning":
-    case "action":
-    case "interaction":
-      return false;
-    case "tool":
-      return part.state === "completed" || part.state === "failed";
-    case "text":
-      if (message.role === "user") return true;
-      return "state" in part && part.state === "done" && message.state === "done";
-    case "context":
-    case "file":
-    case "data":
-    case "error":
-      return true;
-    default:
-      return assert_never(part);
-  }
-}
-
-/** 把单个 Part 收窄为摘要模型需要的稳定事实。 */
-function candidate_to_summary_text(candidate: StablePartCandidate): string {
-  return JSON.stringify({
-    role: candidate.message.role,
-    message_id: candidate.message.message_id,
-    part: summary_part(candidate.part),
-  });
-}
-
-/** 删除瞬时字段并保留 Tool 调用/结果原子。 */
-function summary_part(
-  part: SessionUserMessagePart | SessionAgentMessagePart,
-): Record<string, unknown> {
-  switch (part.type) {
-    case "text":
-      return { type: "text", text: part.text };
-    case "context":
-      return { type: "context", tag: part.tag, context: part.context };
-    case "file":
-      return { type: "file", media_type: part.media_type, url: part.url, filename: part.filename };
-    case "data":
-      return { type: "data", data_type: part.data_type, data: part.data };
-    case "tool":
-      return {
-        type: "tool",
-        tool_name: part.tool_name,
-        input: part.input,
-        output: part.output,
-        error: part.error,
-      };
-    case "error":
-      return { type: "error", code: part.code, message: part.message };
-    case "reasoning":
-    case "action":
-    case "interaction":
-      return { type: part.type };
-    default:
-      return assert_never(part);
-  }
-}
-
-/**
- * 选择足以释放约一半原始上下文体积的最旧 Part。
- *
- * 关键点（中文）：Part 数量不能代表上下文压力。一个巨大 Tool/Text Part
- * 可以独自占满窗口，因此使用送入摘要模型的序列化字符体积作为轻量估算，
- * 并保证只有一个可用 Part 时仍能推进 checkpoint。
- */
-function select_compact_parts(
-  candidates: readonly StablePartCandidate[],
-): StablePartCandidate[] {
-  if (candidates.length === 0) return [];
-  const sizes = candidates.map((candidate) =>
-    Math.max(candidate_to_summary_text(candidate).length, 1)
-  );
-  const target_size = Math.ceil(
-    sizes.reduce((total, size) => total + size, 0) / 2,
-  );
-  let selected_size = 0;
-  let selected_count = 0;
-  while (selected_count < candidates.length && selected_size < target_size) {
-    selected_size += sizes[selected_count] ?? 0;
-    selected_count += 1;
-  }
-  return candidates.slice(0, Math.max(selected_count, 1));
-}
-
-/** 删除 checkpoint 以前的 Part；边界可以位于单个 Message 内部。 */
-function slice_messages_after_checkpoint(
-  messages: readonly SessionMessage[],
-  checkpoint: AdaptivePartCheckpointRow,
-): SessionMessage[] {
-  return messages.flatMap((message): SessionMessage[] => {
-    if (message.sequence < checkpoint.through_message_sequence) return [];
-    if (message.sequence > checkpoint.through_message_sequence) return [message];
-    const parts = message.parts.filter(
-      (part) => part.sequence > checkpoint.through_part_sequence,
-    );
-    if (parts.length === 0) return [];
-    return [{ ...message, parts } as SessionMessage];
-  });
-}
-
-/** 比较 canonical Part 与 checkpoint 的全局线性位置。 */
-function compare_part_position(
-  message_sequence: number,
-  part_sequence: number,
-  checkpoint: AdaptivePartCheckpointRow,
-): number {
-  if (message_sequence !== checkpoint.through_message_sequence) {
-    return message_sequence - checkpoint.through_message_sequence;
-  }
-  return part_sequence - checkpoint.through_part_sequence;
-}
-
-/** 比较 checkpoint 与候选边界。 */
-function compare_position(
-  checkpoint: AdaptivePartCheckpointRow,
-  candidate: StablePartCandidate,
-): number {
-  return -compare_part_position(
-    candidate.message.sequence,
-    candidate.part.sequence,
-    checkpoint,
-  );
-}
-
-/** canonical Part 联合类型新增成员时强制摘要策略显式选择语义。 */
-function assert_never(value: never): never {
-  throw new Error(`Unsupported summary Session Part: ${String((value as { type?: unknown }).type)}`);
-}

package/src/session/composer/policies/FullHistoryContextPolicy.ts

@@ -1,36 +0,0 @@
-/**
- * 全量历史上下文策略。
- *
- * 该策略没有派生状态，适用于短会话、测试或拥有足够上下文窗口的模型。
- */
-
-import { session_messages_to_model_messages } from "@/executor/messages/SessionModelMessages.js";
-import type { SessionContextPolicy } from "@/types/session/SessionContextPolicy.js";
-
-/** 直接把全部 canonical Message 转换为模型历史。 */
-export class FullHistoryContextPolicy implements SessionContextPolicy {
-  readonly name = "full_history";
-
-  /** 全量历史策略不需要创建派生表。 */
-  async initialize(): Promise<void> {}
-
-  /** 按 canonical 顺序返回完整模型历史。 */
-  async resolve(input: Parameters<SessionContextPolicy["resolve"]>[0]) {
-    const messages = await input.storage.list_messages();
-    return {
-      messages: await session_messages_to_model_messages(messages, input.project_root),
-      diagnostics: {
-        policy_name: this.name,
-        ...(messages.at(-1)?.sequence !== undefined
-          ? { through_sequence: messages.at(-1)?.sequence }
-          : {}),
-        derived: false,
-      },
-    };
-  }
-
-  /** 没有派生状态，因此无法通过恢复改变上下文。 */
-  async recover(): Promise<boolean> {
-    return false;
-  }
-}

package/src/session/control/SessionInteractions.ts

@@ -1,311 +0,0 @@
-/**
- * Session 用户异步交互运行时。
- *
- * 本模块只拥有 pending waiter、超时与恢复执行；Interaction 的权威状态由
- * SessionMessages 持久化。任何终态都必须先提交 canonical Message，再兑现等待 Promise。
- */
-
-import type { SessionMessages } from "@/session/SessionMessages.js";
-import type {
-  RespondSessionInteractionInput,
-  SessionInteractionHandle,
-  SessionInteractionLifecycle,
-  SessionInteractionPort,
-  SessionInteractionRequest,
-  SessionInteractionResponse,
-  SessionInteractionResult,
-  SessionPendingInteraction,
-} from "@downcity/type";
-import type { SessionPendingInteractionRuntime } from "@/types/session/SessionInteractions.js";
-
-/** 单个 Session 的异步用户交互入口。 */
-export class SessionInteractions implements SessionInteractionPort, SessionInteractionLifecycle {
-  private readonly session_id: string;
-  private readonly messages: SessionMessages;
-  private readonly pending_by_id = new Map<
-    string,
-    SessionPendingInteractionRuntime
-  >();
-
-  constructor(options: {
-    /** 当前 Interaction 运行时所属 Session 标识。 */
-    session_id: string;
-    /** 当前 Session 的 canonical Message 入口。 */
-    messages: SessionMessages;
-  }) {
-    this.session_id = String(options.session_id || "").trim();
-    this.messages = options.messages;
-    if (!this.session_id) {
-      throw new Error("SessionInteractions requires a non-empty session_id");
-    }
-  }
-
-  /** 创建并持久化一次 Interaction，返回等待终态结果的句柄。 */
-  async request(
-    request: SessionInteractionRequest,
-  ): Promise<SessionInteractionHandle> {
-    this.validate_request(request);
-    if (this.pending_by_id.has(request.interaction_id)) {
-      throw new Error(`Session Interaction is already pending: ${request.interaction_id}`);
-    }
-
-    let resolve_result!: (result: SessionInteractionResult) => void;
-    const result = new Promise<SessionInteractionResult>((resolve) => {
-      resolve_result = resolve;
-    });
-    const pending: SessionPendingInteractionRuntime = {
-      request: structuredClone(request),
-      resolve: resolve_result,
-    };
-    this.pending_by_id.set(request.interaction_id, pending);
-
-    try {
-      await this.messages.request_interaction(request);
-    } catch (error) {
-      this.pending_by_id.delete(request.interaction_id);
-      throw error;
-    }
-
-    if (request.expires_at !== undefined) {
-      const delay_ms = Math.max(0, request.expires_at - Date.now());
-      const timer = setTimeout(() => {
-        void this.expire(request.interaction_id);
-      }, delay_ms);
-      if (typeof timer.unref === "function") timer.unref();
-      pending.timer = timer;
-    }
-
-    return {
-      interaction_id: request.interaction_id,
-      result,
-    };
-  }
-
-  /** 返回当前 Session 全部 pending Interaction 请求快照。 */
-  list(): SessionPendingInteraction[] {
-    return this.messages.list_pending_interactions().map((interaction) => ({
-      request: structuredClone(interaction.request),
-    }));
-  }
-
-  /** 保存用户响应，并在提交成功后恢复原执行。 */
-  async respond(
-    input: RespondSessionInteractionInput,
-  ): Promise<SessionInteractionResult> {
-    const pending = this.require_pending(input.interaction_id);
-    this.validate_response(pending.request, input.response);
-    await this.messages.resolve_interaction(
-      input.interaction_id,
-      input.response,
-    );
-    const result: SessionInteractionResult = input.response.outcome === "denied"
-      ? {
-        status: "denied",
-        interaction_id: input.interaction_id,
-        reason: extract_interaction_reason(input.response.payload),
-      }
-      : {
-        status: "resolved",
-        interaction_id: input.interaction_id,
-        response: structuredClone(input.response),
-      };
-    this.finish_pending(input.interaction_id, result);
-    return result;
-  }
-
-  /** 取消当前 Session 的全部 pending Interaction。 */
-  async cancel_all(
-    reason: "turn_stopped" | "session_disposed" | "runtime_interrupted",
-  ): Promise<void> {
-    let first_error: unknown;
-    for (const interaction_id of [...this.pending_by_id.keys()]) {
-      const result: SessionInteractionResult = {
-        status: "cancelled",
-        interaction_id,
-        reason,
-      };
-      try {
-        await this.messages.close_interaction(interaction_id, {
-          status: "cancelled",
-          reason,
-        });
-        this.finish_pending(interaction_id, result);
-      } catch (error) {
-        first_error ??= error;
-      }
-    }
-    if (first_error) throw first_error;
-  }
-
-  /** 处理单个 Interaction 自动过期。 */
-  private async expire(interaction_id: string): Promise<void> {
-    if (!this.pending_by_id.has(interaction_id)) return;
-    const result: SessionInteractionResult = {
-      status: "expired",
-      interaction_id,
-    };
-    try {
-      await this.messages.close_interaction(interaction_id, {
-        status: "expired",
-      });
-    } catch {
-      return;
-    }
-    this.finish_pending(interaction_id, result);
-  }
-
-  /** 校验执行面提交的 Interaction 请求。 */
-  private validate_request(request: SessionInteractionRequest): void {
-    if (!String(request.interaction_id || "").trim()) {
-      throw new Error("Session Interaction requires interaction_id");
-    }
-    if (!String(request.turn_id || "").trim()) {
-      throw new Error("Session Interaction requires turn_id");
-    }
-    if (
-      request.expires_at !== undefined &&
-      (!Number.isFinite(request.expires_at) || request.expires_at < request.created_at)
-    ) {
-      throw new Error("Session Interaction expires_at must not precede created_at");
-    }
-    if (!String(request.type || "").trim()) {
-      throw new Error("Session Interaction requires a non-empty type");
-    }
-    if (!request.source || typeof request.source !== "object") {
-      throw new Error("Session Interaction requires a source");
-    }
-    if (request.type === "question") {
-      const payload = request.payload as { questions?: unknown };
-      const questions = payload?.questions;
-      if (!Array.isArray(questions) || questions.length === 0) {
-        throw new Error("Question Interaction requires at least one question");
-      }
-      const question_ids = new Set<string>();
-      for (const question of questions as Array<Record<string, unknown>>) {
-        if (!String(question.question_id || "").trim()) {
-          throw new Error("Interaction question requires question_id");
-        }
-        if (question_ids.has(String(question.question_id))) {
-          throw new Error("Duplicate Interaction question_id");
-        }
-        question_ids.add(String(question.question_id));
-        if (!String(question.prompt || "").trim()) {
-          throw new Error(
-            `Interaction question requires prompt: ${question.question_id}`,
-          );
-        }
-        if (
-          question.response_type !== "text" &&
-          (!Array.isArray(question.options) || question.options.length === 0)
-        ) {
-          throw new Error(
-            `Select Interaction question requires options: ${question.question_id}`,
-          );
-        }
-        if (question.options) {
-          const option_values = new Set<string>();
-          for (const option of question.options as Array<Record<string, unknown>>) {
-            if (!String(option.value || "").trim()) {
-              throw new Error(
-                `Interaction option requires value: ${question.question_id}`,
-              );
-            }
-            const option_value = String(option.value);
-            if (option_values.has(option_value)) {
-              throw new Error("Duplicate Interaction option value");
-            }
-            option_values.add(option_value);
-          }
-        }
-      }
-    }
-  }
-
-  /** 校验响应 type、问题集合与回答值。 */
-  private validate_response(
-    request: SessionInteractionRequest,
-    response: SessionInteractionResponse,
-  ): void {
-    if (request.type !== response.type) {
-      throw new Error("Session Interaction response type mismatch");
-    }
-    if (response.outcome !== "resolved" && response.outcome !== "denied") {
-      throw new Error("Session Interaction response requires a valid outcome");
-    }
-    if (request.type !== "question") return;
-    const request_payload = request.payload as { questions?: unknown };
-    const response_payload = response.payload as { answers?: unknown };
-    const questions = Array.isArray(request_payload.questions)
-      ? request_payload.questions as Array<Record<string, unknown>>
-      : [];
-    const response_answers = Array.isArray(response_payload?.answers)
-      ? response_payload.answers as Array<Record<string, unknown>>
-      : [];
-    const answers = new Map<string, string | string[]>();
-    for (const answer of response_answers) {
-      const question_id = String(answer.question_id || "");
-      if (answers.has(question_id)) {
-        throw new Error("Duplicate Session Interaction answer");
-      }
-      answers.set(question_id, answer.value as string | string[]);
-    }
-    if (answers.size !== questions.length) {
-      throw new Error("Session Interaction answer count mismatch");
-    }
-    for (const question of questions) {
-      const question_id = String(question.question_id || "");
-      const value = answers.get(question_id);
-      if (value === undefined) {
-        throw new Error("Session Interaction answer is missing");
-      }
-      if (question.response_type === "multi_select") {
-        if (!Array.isArray(value)) {
-          throw new Error("Session Interaction answer must be an array");
-        }
-      } else if (typeof value !== "string") {
-        throw new Error("Session Interaction answer must be a string");
-      }
-      if (question.response_type !== "text") {
-        const allowed = new Set(
-          (Array.isArray(question.options) ? question.options : []).map(
-            (option) => (option as { value: string }).value,
-          ),
-        );
-        const selected = Array.isArray(value) ? value : [value];
-        if (selected.some((item) => !allowed.has(item))) {
-          throw new Error("Session Interaction answer contains an invalid option");
-        }
-      }
-    }
-  }
-
-  /** 读取当前 pending Interaction 运行态。 */
-  private require_pending(
-    interaction_id: string,
-  ): SessionPendingInteractionRuntime {
-    const pending = this.pending_by_id.get(interaction_id);
-    if (pending) return pending;
-    throw new Error(`Pending Session Interaction not found: ${interaction_id}`);
-  }
-
-  /** 清理运行态并兑现执行方等待 Promise。 */
-  private finish_pending(
-    interaction_id: string,
-    result: SessionInteractionResult,
-  ): void {
-    const pending = this.pending_by_id.get(interaction_id);
-    if (!pending) return;
-    if (pending.timer) clearTimeout(pending.timer);
-    this.pending_by_id.delete(interaction_id);
-    pending.resolve(result);
-  }
-}
-
-/** 从通用响应 payload 中读取可选的人类可读拒绝原因。 */
-function extract_interaction_reason(payload: unknown): string | undefined {
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    return undefined;
-  }
-  const reason = (payload as { reason?: unknown }).reason;
-  return typeof reason === "string" ? reason : undefined;
-}