@downcity/agent 1.1.438 → 1.1.446

package/src/session/input/composer/AdaptiveContextParts.ts

@@ -0,0 +1,166 @@
+/**
+ * 上下文 checkpoint 的纯算法部分。
+ *
+ * 这里没有任何存储或模型调用：调用方提供 canonical history 快照与 checkpoint，
+ * 本模块只决定哪些 Part 值得进入摘要、边界落在哪里、以及裁剪后剩下什么。
+ *
+ * 关键点（中文）：Part 数量不代表上下文压力。一个巨大的 Tool/Text Part 可以独自占满
+ * 窗口，因此选择使用送入摘要模型的序列化字符体积作为轻量估算。
+ */
+
+import type {
+  SessionAgentMessagePart,
+  SessionMessage,
+  SessionUserMessagePart,
+} from "@downcity/type";
+import type {
+  ContextCheckpointRow,
+  StableContextPart,
+} from "@/types/session/ContextCheckpoint.js";
+
+/** 收集 checkpoint 之后适合进入摘要的稳定 Part。 */
+export function collect_stable_parts(
+  messages: readonly SessionMessage[],
+  checkpoint: ContextCheckpointRow | null,
+): StableContextPart[] {
+  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。
+ *
+ * 关键点（中文）：至少推进一个 Part，保证只有一个可用 Part 时仍能建立边界。
+ */
+export function select_compact_parts(
+  candidates: readonly StableContextPart[],
+): StableContextPart[] {
+  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));
+}
+
+/** 把单个 Part 收窄为摘要模型需要的稳定事实。 */
+export function candidate_to_summary_text(candidate: StableContextPart): string {
+  return JSON.stringify({
+    role: candidate.message.role,
+    message_id: candidate.message.message_id,
+    part: summary_part(candidate.part),
+  });
+}
+
+/** 删除 checkpoint 以前的 Part；边界可以位于单个 Message 内部。 */
+export function slice_messages_after_checkpoint(
+  messages: readonly SessionMessage[],
+  checkpoint: ContextCheckpointRow,
+): 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];
+  });
+}
+
+/** 比较 checkpoint 与候选边界，checkpoint 位于候选之前时返回负数。 */
+export function compare_position(
+  checkpoint: ContextCheckpointRow,
+  candidate: StableContextPart,
+): number {
+  return -compare_part_position(
+    candidate.message.sequence,
+    candidate.part.sequence,
+    checkpoint,
+  );
+}
+
+/** 判断 Part 是否稳定且值得占据累计摘要。 */
+function is_stable_summary_part(
+  message: SessionMessage,
+  part: SessionUserMessagePart | SessionAgentMessagePart,
+): boolean {
+  switch (part.type) {
+    case "reasoning":
+    case "action":
+      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);
+  }
+}
+
+/** 删除瞬时字段并保留 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":
+      return { type: part.type };
+    default:
+      return assert_never(part);
+  }
+}
+
+/** 比较 canonical Part 与 checkpoint 的全局线性位置。 */
+function compare_part_position(
+  message_sequence: number,
+  part_sequence: number,
+  checkpoint: ContextCheckpointRow,
+): number {
+  if (message_sequence !== checkpoint.through_message_sequence) {
+    return message_sequence - checkpoint.through_message_sequence;
+  }
+  return part_sequence - checkpoint.through_part_sequence;
+}
+
+/** canonical Part 联合类型新增成员时强制摘要算法显式选择语义。 */
+function assert_never(value: never): never {
+  throw new Error(`Unsupported summary Session Part: ${String((value as { type?: unknown }).type)}`);
+}

package/src/session/input/composer/ComposerAssembly.ts

@@ -0,0 +1,81 @@
+/**
+ * Composer 共用的组装原语。
+ *
+ * 本模块只做无状态的纯组装：把已冻结的 Step 状态转成 system blocks，并把 Power 动态
+ * 参考内容注入模型消息副本。所有内置 Composer 都复用这里，避免各自复制 system 与
+ * Power 拼接逻辑。
+ */
+
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { SessionHookContextBlock } from "@downcity/type";
+import type { SessionComposeInput } from "@/types/session/SessionComposer.js";
+import type { SessionSystemMessage } from "@downcity/type";
+import type { ModelMessage } from "@downcity/type";
+import { build_session_system_blocks } from "@/session/input/SessionSystem.js";
+
+/** 把当前 Step 生效的 instruction 与 Power blocks 组装成 system blocks。 */
+export async function build_composer_system_blocks(
+  input: SessionComposeInput,
+): Promise<AgentSessionSystemBlock[]> {
+  return await build_session_system_blocks({
+    agent_id: input.session.agent_id,
+    project_root: input.session.project_root,
+    session_id: input.session.session_id,
+    created_at: input.session.created_at,
+    timezone: input.session.timezone,
+    get_instruction_system_blocks: () => [
+      ...(input.state.instruction_system_blocks ?? []),
+    ],
+    get_power_system_blocks: async () => [
+      ...(input.state.power_system_blocks ?? []),
+    ],
+  });
+}
+
+/** 把 system blocks 投影为模型 system messages。 */
+export function to_system_messages(
+  blocks: readonly AgentSessionSystemBlock[],
+): SessionSystemMessage[] {
+  return blocks.map((block) => ({
+    role: "system" as const,
+    content: block.content,
+  }));
+}
+
+/** 把低权限 Power 内容渲染为与用户原文分离的模型参考区。 */
+export function render_power_context_blocks(
+  blocks: readonly SessionHookContextBlock[],
+): string {
+  return blocks.map((block) => [
+    `<extension-context extension="${escape_xml_attribute(block.source_power)}" name="${escape_xml_attribute(block.name)}" trust="reference">`,
+    block.content,
+    "</extension-context>",
+  ].join("\n")).join("\n\n");
+}
+
+/** 只修改模型消息副本，把动态参考信息前置到当前最后一条 User Message。 */
+export function inject_power_context(
+  messages: ModelMessage[],
+  blocks: readonly SessionHookContextBlock[],
+): ModelMessage[] {
+  if (blocks.length === 0) return messages;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!message || message.role !== "user") continue;
+    messages[index] = {
+      ...message,
+      content: [{ type: "text", text: render_power_context_blocks(blocks) }, ...message.content],
+    };
+    break;
+  }
+  return messages;
+}
+
+/** 转义模型上下文标签属性，避免 Power 名称破坏边界。 */
+function escape_xml_attribute(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("\"", "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}

package/src/session/{composer/policies/SessionSummaryPrompts.ts → input/composer/ContextSummaryPrompts.ts}

@@ -1,7 +1,10 @@
-/** Session 累计摘要策略使用的稳定提示词。 */
+/** Session 累计摘要使用的稳定提示词。 */
+
+/** 摘要模型可使用的最大输出 token。 */
+export const CONTEXT_SUMMARY_MAX_OUTPUT_TOKENS = 4_000;
 
 /** 上下文摘要 system prompt。 */
-export const SESSION_SUMMARY_SYSTEM_PROMPT = [
+export const CONTEXT_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.",

package/src/session/input/composer/DefaultSessionComposer.ts

@@ -0,0 +1,147 @@
+/**
+ * 默认 Session Composer。
+ *
+ * 负责组装当前 Step 的 system、messages 与 tools，并在上下文压力出现时把较旧的稳定
+ * Part 折叠进累计摘要 checkpoint。
+ *
+ * 关键点（中文）
+ * - canonical history 由调用方传入，本模块只读取它，从不改写。
+ * - 压缩结果只写自己的 checkpoint 派生表；下一次 compose 才会读到新边界。
+ * - 自定义压缩算法可以继承本类并只覆盖 `advance_context()`。
+ */
+
+import { build_text_model_messages, generate_model } from "@/model/ModelGenerate.js";
+import { session_messages_to_model_messages } from "@/model/messages/SessionModelMessages.js";
+import type {
+  SessionComposer,
+  SessionComposeInput,
+  SessionContextAdvanceInput,
+  SessionContextDiagnostics,
+  SessionStepInput,
+} from "@/types/session/SessionComposer.js";
+import type { ContextCheckpointRow } from "@/types/session/ContextCheckpoint.js";
+import {
+  build_composer_system_blocks,
+  inject_power_context,
+  to_system_messages,
+} from "@/session/input/composer/ComposerAssembly.js";
+import {
+  initialize_checkpoint_schema,
+  insert_checkpoint,
+  read_latest_checkpoint,
+} from "@/session/input/composer/AdaptiveContextCheckpoint.js";
+import {
+  candidate_to_summary_text,
+  collect_stable_parts,
+  compare_position,
+  select_compact_parts,
+  slice_messages_after_checkpoint,
+} from "@/session/input/composer/AdaptiveContextParts.js";
+import {
+  build_initial_session_summary_prompt,
+  build_updated_session_summary_prompt,
+  CONTEXT_SUMMARY_MAX_OUTPUT_TOKENS,
+  CONTEXT_SUMMARY_SYSTEM_PROMPT,
+} from "@/session/input/composer/ContextSummaryPrompts.js";
+
+/** 基于 Part 级 checkpoint 的默认 Composer。 */
+export class DefaultSessionComposer implements SessionComposer {
+  /** Composer 名称，同时作为派生表命名空间。 */
+  readonly name = "adaptive_part";
+
+  /** 创建累计摘要 checkpoint 派生表。 */
+  async initialize(
+    input: Parameters<SessionComposer["initialize"]>[0],
+  ): Promise<void> {
+    await initialize_checkpoint_schema(input.derived, this.name);
+  }
+
+  /** 返回显式摘要 system block 与 checkpoint 边界后的 canonical 历史。 */
+  async compose(input: SessionComposeInput): Promise<SessionStepInput> {
+    const checkpoint = await read_latest_checkpoint(input.derived, this.name);
+    const system_blocks = await build_composer_system_blocks(input);
+    if (checkpoint?.summary.trim()) {
+      system_blocks.push({
+        source: "session",
+        name: "context-summary",
+        content: `<session-context-summary>\n${checkpoint.summary}\n</session-context-summary>`,
+      });
+    }
+    const tail = checkpoint
+      ? slice_messages_after_checkpoint(input.history, checkpoint)
+      : input.history;
+    return {
+      system: to_system_messages(system_blocks),
+      system_blocks,
+      messages: inject_power_context(
+        await session_messages_to_model_messages(tail, input.session.project_root),
+        input.state.power_context_blocks ?? [],
+      ),
+      tools: { ...input.state.tools },
+      context_diagnostics: build_diagnostics(this.name, input.history, checkpoint),
+    };
+  }
+
+  /** 按体积选择较旧稳定 Part，合并进累计摘要并推进 checkpoint。 */
+  async advance_context(input: SessionContextAdvanceInput): Promise<boolean> {
+    if (!input.model) return false;
+    const previous = await read_latest_checkpoint(input.derived, this.name);
+    const compact_parts = select_compact_parts(
+      collect_stable_parts(input.history, previous),
+    );
+    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(CONTEXT_SUMMARY_SYSTEM_PROMPT, prompt),
+      max_output_tokens: CONTEXT_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");
+
+    try {
+      await insert_checkpoint(input.derived, this.name, {
+        through_message_id: boundary.message.message_id,
+        through_message_sequence: boundary.message.sequence,
+        through_part_sequence: boundary.part.sequence,
+        summary,
+      });
+      return true;
+    } catch (error) {
+      // 并发推进：只要有别人把边界推过本次位置，本次推进就已经生效。
+      const latest = await read_latest_checkpoint(input.derived, this.name);
+      if (latest && compare_position(latest, boundary) >= 0) return true;
+      throw error;
+    }
+  }
+}
+
+/** 组装当前上下文的只读诊断。 */
+function build_diagnostics(
+  composer_name: string,
+  history: SessionComposeInput["history"],
+  checkpoint: ContextCheckpointRow | null,
+): SessionContextDiagnostics {
+  const latest_sequence = history.at(-1)?.sequence;
+  return {
+    composer_name,
+    ...(latest_sequence !== undefined ? { through_sequence: latest_sequence } : {}),
+    ...(checkpoint ? { through_part_sequence: checkpoint.through_part_sequence } : {}),
+    derived: Boolean(checkpoint),
+    ...(checkpoint ? { derivation_id: checkpoint.checkpoint_id } : {}),
+  };
+}

package/src/session/input/composer/FullHistorySessionComposer.ts

@@ -0,0 +1,55 @@
+/**
+ * 全量历史 Session Composer。
+ *
+ * 不做任何上下文推进：每次交给模型的都是完整 canonical history，也没有派生表。
+ * 适用于短会话、测试或上下文窗口足够大的模型。
+ */
+
+import { session_messages_to_model_messages } from "@/model/messages/SessionModelMessages.js";
+import type {
+  SessionComposer,
+  SessionComposeInput,
+  SessionStepInput,
+} from "@/types/session/SessionComposer.js";
+import {
+  build_composer_system_blocks,
+  inject_power_context,
+  to_system_messages,
+} from "@/session/input/composer/ComposerAssembly.js";
+
+/** 直接投影全部 canonical history 的 Composer。 */
+export class FullHistorySessionComposer implements SessionComposer {
+  /** Composer 名称；该实现不建立派生表。 */
+  readonly name = "full_history";
+
+  /** 没有派生 schema 需要初始化。 */
+  async initialize(): Promise<void> {}
+
+  /** 返回完整 canonical 历史与当前 Step 的工具集合。 */
+  async compose(input: SessionComposeInput): Promise<SessionStepInput> {
+    const system_blocks = await build_composer_system_blocks(input);
+    const latest_sequence = input.history.at(-1)?.sequence;
+    return {
+      system: to_system_messages(system_blocks),
+      system_blocks,
+      messages: inject_power_context(
+        await session_messages_to_model_messages(
+          input.history,
+          input.session.project_root,
+        ),
+        input.state.power_context_blocks ?? [],
+      ),
+      tools: { ...input.state.tools },
+      context_diagnostics: {
+        composer_name: this.name,
+        ...(latest_sequence !== undefined ? { through_sequence: latest_sequence } : {}),
+        derived: false,
+      },
+    };
+  }
+
+  /** 没有派生状态可以推进。 */
+  async advance_context(): Promise<boolean> {
+    return false;
+  }
+}

package/src/session/loop/README.md

@@ -0,0 +1,28 @@
+# session/loop
+
+轮次编排：一次 `prompt()` 从入队到收口的全过程，以及驱动它所需的配置状态。
+
+## 文件
+
+| 文件 | 随轮次销毁 | 职责 |
+| --- | --- | --- |
+| `SessionLoop.ts` | — | 队列消费与 Turn 生命周期所有者 |
+| `SessionQueue.ts` | — | 进程内 FIFO，只保存 Command 与顺序 |
+| `SessionTurnContext.ts` | 是 | 一个 Turn 的执行上下文：身份、生命周期、Step、输入输出协作 |
+| `SessionTurnCompletion.ts` | 是 | 结果映射、Turn Mutation、committed Hook 与 Context 释放顺序 |
+| `SessionTurnFileDiff.ts` | 是 | 把 Tool effects 投影为实时摘要与最终 canonical data part |
+| `SessionTurnFileDiffBuilder.ts` | 是 | 从 Tool effects 中只选出 Workspace 文件修改事实 |
+| `SessionState.ts` | 否 | 配置与 Metadata 状态；跨轮存活，写 `session_state` 表 |
+| `SessionTitle.ts` | 否 | 标题生成与持久化 |
+| `SessionTitleTask.ts` | 否 | 标题后台任务；不得阻塞 Turn 主链路 |
+
+## 为什么配置状态和轮次编排同处一室
+
+`SessionState` 与 `SessionTitle` 不随轮次销毁，但它们的驱动者只有 `SessionLoop`：
+配置在开轮时读取，标题在轮末生成。`SessionLoop` 直接持有 `this.state` 并在检查点
+使用它，拆成两个目录只会让这条唯一驱动关系变得不显眼。
+
+## 关键约束
+
+- Queue 是唯一的输入顺序权威；Prompt 与维护类 Command 共用同一条 FIFO。
+- `SessionTitleTask` 是 metadata 增强任务，失败只记日志，不改变 Turn 结果。