@downcity/agent 1.1.430 → 1.1.438

package/src/session/browse/SessionMessageTimeline.ts

@@ -11,7 +11,7 @@ import type {
   AgentSessionTimelineEvent,
 } from "@/types/agent/SessionTypes.js";
 import type {
-  SessionAssistantToolPart,
+  SessionAgentToolPart,
   SessionMessage,
 } from "@downcity/type";
 
@@ -53,7 +53,7 @@ function create_timeline_event(input: {
 /** 将单个 Tool Part 展开为调用与可选结果事件。 */
 function project_tool_part(
   message: SessionMessage,
-  part: SessionAssistantToolPart,
+  part: SessionAgentToolPart,
   start_index: number,
 ): AgentSessionTimelineEvent[] {
   const events = [create_timeline_event({
@@ -84,52 +84,77 @@ function project_tool_part(
 export function to_session_message_timeline_events(
   message: SessionMessage,
 ): AgentSessionTimelineEvent[] {
-  if (message.type === "action") {
-    return [{
-      id: `${message.message_id}:0`,
-      role: "action",
-      ts: message.updated_at,
-      text: message.description
-        ? `${message.title}\n${message.description}`
-        : message.title,
-      action_title: message.title,
-      ...(message.description ? { action_description: message.description } : {}),
-      action_state: message.status,
-    }];
-  }
-  if (message.type === "error") {
-    return [create_timeline_event({
-      message,
-      role: "assistant",
-      text: message.message,
-      index: 0,
-    })];
-  }
-  if (message.type === "user") {
-    const text = message.parts
-      .filter((part) => part.type === "text")
-      .map((part) => part.text.trim())
-      .filter(Boolean)
-      .join("\n");
+  if (message.role === "user") {
+    const text_parts: string[] = [];
+    for (const part of message.parts) {
+      switch (part.type) {
+        case "text":
+          if (part.text.trim()) text_parts.push(part.text.trim());
+          break;
+        case "context":
+        case "file":
+        case "data":
+          break;
+        default:
+          assert_never(part);
+      }
+    }
+    const text = text_parts.join("\n");
     return [create_timeline_event({ message, role: "user", text, index: 0 })];
   }
 
   const events: AgentSessionTimelineEvent[] = [];
   for (const part of [...message.parts].sort((left, right) => left.sequence - right.sequence)) {
-    if (part.type === "text") {
-      const text = part.text.trim();
-      if (text) {
+    switch (part.type) {
+      case "text": {
+        const text = part.text.trim();
+        if (text) {
+          events.push(create_timeline_event({
+            message,
+            role: "agent",
+            text,
+            index: events.length,
+          }));
+        }
+        break;
+      }
+      case "action":
+        events.push({
+          id: `${message.message_id}:${events.length}`,
+          role: "action",
+          ts: message.updated_at,
+          text: part.description
+            ? `${part.title}\n${part.description}`
+            : part.title,
+          action_title: part.title,
+          ...(part.description ? { action_description: part.description } : {}),
+          action_state: part.state,
+        });
+        break;
+      case "error":
         events.push(create_timeline_event({
           message,
-          role: "assistant",
-          text,
+          role: "agent",
+          text: part.message,
           index: events.length,
         }));
-      }
-      continue;
+        break;
+      case "tool":
+        events.push(...project_tool_part(message, part, events.length));
+        break;
+      case "reasoning":
+      case "interaction":
+      case "file":
+      case "data":
+        break;
+      default:
+        assert_never(part);
     }
-    if (part.type !== "tool") continue;
-    events.push(...project_tool_part(message, part, events.length));
   }
   return events;
 }
+
+/** canonical Part 联合类型新增成员时强制时间线显式处理。 */
+function assert_never(value: never): never {
+  throw new Error(`Unsupported timeline Session Part: ${String((value as { type?: unknown }).type)}`);
+}

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

@@ -0,0 +1,307 @@
+/**
+ * 基于稳定 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

@@ -0,0 +1,36 @@
+/**
+ * 全量历史上下文策略。
+ *
+ * 该策略没有派生状态，适用于短会话、测试或拥有足够上下文窗口的模型。
+ */
+
+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/composer/policies/SessionSummaryPrompts.ts

@@ -0,0 +1,42 @@
+/** Session 累计摘要策略使用的稳定提示词。 */
+
+/** 上下文摘要 system prompt。 */
+export const SESSION_SUMMARY_SYSTEM_PROMPT = [
+  "You are a context summarization assistant.",
+  "Read the conversation and produce only a structured checkpoint summary.",
+  "Do not continue the conversation or answer its questions.",
+].join("\n");
+
+/** 构建第一次累计摘要的 prompt。 */
+export function build_initial_session_summary_prompt(input: {
+  /** 本次需要压缩的 canonical 对话文本。 */
+  conversation_text: string;
+}): string {
+  return [
+    input.conversation_text.trim(),
+    "",
+    "Create a concise checkpoint another model can use to continue the work.",
+    "Preserve exact requests, constraints, decisions, completed work, pending work, file paths, function names, and errors.",
+    "Use these headings: Goal, Constraints, Progress, Key Decisions, Next Steps, Critical Context.",
+  ].join("\n");
+}
+
+/** 构建基于旧摘要的增量累计摘要 prompt。 */
+export function build_updated_session_summary_prompt(input: {
+  /** 上一次已经持久化的累计摘要。 */
+  previous_summary: string;
+  /** 本次新增的 canonical 对话文本。 */
+  conversation_text: string;
+}): string {
+  return [
+    "<previous-summary>",
+    input.previous_summary.trim(),
+    "</previous-summary>",
+    "",
+    input.conversation_text.trim(),
+    "",
+    "Update the checkpoint with the new conversation.",
+    "Preserve still-relevant facts and exact requests, constraints, decisions, file paths, function names, and errors.",
+    "Use these headings: Goal, Constraints, Progress, Key Decisions, Next Steps, Critical Context.",
+  ].join("\n");
+}

package/src/session/execution/SessionAssistantOutputAdapter.ts

@@ -7,11 +7,11 @@
 
 import type { ModelStreamEvent } from "@downcity/type";
 import {
-  SessionAssistantMessageWriter,
+  SessionAgentMessageWriter,
   SessionMessages,
 } from "@/session/SessionMessages.js";
-import type { SessionAssistantResultPart } from "@downcity/type";
-import type { SessionAssistantMessagePart } from "@downcity/type";
+import type { SessionAgentContent } from "@downcity/type";
+import type { SessionAgentMessagePart } from "@downcity/type";
 import type { SessionAssistantOutput } from "@/types/executor/SessionAssistantOutput.js";
 import type {
   SessionToolExecutionResult,
@@ -22,8 +22,8 @@ import type {
 export class SessionAssistantOutputAdapter implements SessionAssistantOutput {
   private readonly turn_id: string;
   private readonly messages: SessionMessages;
-  private writer: SessionAssistantMessageWriter | null = null;
-  private writer_task: Promise<SessionAssistantMessageWriter> | null = null;
+  private writer: SessionAgentMessageWriter | null = null;
+  private writer_task: Promise<SessionAgentMessageWriter> | null = null;
   private step_pending = false;
 
   constructor(options: {
@@ -65,7 +65,7 @@ export class SessionAssistantOutputAdapter implements SessionAssistantOutput {
   }
 
   /** 使用模型聚合出的 canonical Parts 校验当前 Step。 */
-  async finish_step(parts: SessionAssistantMessagePart[]): Promise<void> {
+  async finish_step(parts: SessionAgentMessagePart[]): Promise<void> {
     await (await this.ensure_writer()).finish_step(parts);
   }
 
@@ -86,9 +86,23 @@ export class SessionAssistantOutputAdapter implements SessionAssistantOutput {
   }
 
   /** 追加 Action 产生的封闭 Assistant 内容。 */
-  async append_result_parts(parts: readonly SessionAssistantResultPart[]): Promise<void> {
-    if (parts.length === 0) return;
-    await (await this.ensure_writer()).append_result_parts(parts);
+  async append_result_parts(parts: readonly SessionAgentContent[]): Promise<SessionAgentMessagePart[]> {
+    if (parts.length === 0) return [];
+    return await (await this.ensure_writer()).append_result_parts(parts);
+  }
+
+  /** 在 Turn 收口产物之前追加用户可见的 canonical Error Part。 */
+  async append_error(input: {
+    /** 错误影响范围。 */
+    scope: "session" | "turn";
+    /** 稳定错误码。 */
+    code: string;
+    /** 用户可见错误信息。 */
+    message: string;
+    /** 当前错误是否允许重试恢复。 */
+    recoverable: boolean;
+  }): Promise<void> {
+    await (await this.ensure_writer()).append_error(input);
   }
 
   /** 按 Turn 结果收口最后一个 canonical Message。 */
@@ -110,10 +124,10 @@ export class SessionAssistantOutputAdapter implements SessionAssistantOutput {
   }
 
   /** 惰性打开当前连续 Assistant 回复的唯一 Writer。 */
-  private async ensure_writer(): Promise<SessionAssistantMessageWriter> {
+  private async ensure_writer(): Promise<SessionAgentMessageWriter> {
     if (this.writer) return this.writer;
     if (this.writer_task) return await this.writer_task;
-    this.writer_task = this.messages.open_assistant_message({
+    this.writer_task = this.messages.open_agent_message({
       turn_id: this.turn_id,
     });
     try {

package/src/session/messages/{SessionActionMessageWriter.ts → SessionAgentActionPartWriter.ts}

@@ -1,16 +1,16 @@
 /**
- * 单个 canonical Action Message 的生命周期写入器。
+ * 单个 canonical Action Part 的生命周期写入器。
  *
  * Writer 只保存目标 Message 身份与发布策略，实际状态仍由 SessionMessages
  * 持久化和接受，避免形成第二份 Action 状态。
  */
 
 import type { SessionMessages } from "@/session/SessionMessages.js";
-import type { CompleteSessionActionMessageInput } from "@/types/session/SessionMessages.js";
+import type { CompleteSessionAgentActionPartInput } from "@/types/session/SessionMessages.js";
 
-/** 单个 Action Message 的生命周期 writer。 */
-export class SessionActionMessageWriter {
-  /** 当前 Action Message 的稳定标识。 */
+/** 单个 Action Part 的生命周期 writer。 */
+export class SessionAgentActionPartWriter {
+  /** 当前 Action Part 所属 Agent Message 的稳定标识。 */
   readonly message_id: string;
   private readonly messages: SessionMessages;
   private readonly publish_mutation: boolean;
@@ -27,9 +27,9 @@ export class SessionActionMessageWriter {
   }
 
   /** 把 Action 更新为 completed。 */
-  async complete(input?: CompleteSessionActionMessageInput): Promise<void> {
+  async complete(input?: CompleteSessionAgentActionPartInput): Promise<void> {
     if (this.closed) return;
-    await this.messages.update_action_message(
+    await this.messages.update_action_part(
       this.message_id,
       "completed",
       input,
@@ -41,7 +41,7 @@ export class SessionActionMessageWriter {
   /** 把 Action 更新为 failed。 */
   async fail(error: unknown): Promise<void> {
     if (this.closed) return;
-    await this.messages.update_action_message(
+    await this.messages.update_action_part(
       this.message_id,
       "failed",
       {