@downcity/agent 1.1.430 → 1.1.438

package/src/session/preview/SessionMessagePreview.ts

@@ -12,7 +12,7 @@ import {
 } from "@/session/messages/SessionMessageText.js";
 import type { SessionMessage } from "@downcity/type";
 
-function extract_assistant_tool_summary(message: Extract<SessionMessage, { type: "assistant" }>): string {
+function extract_assistant_tool_summary(message: Extract<SessionMessage, { role: "agent" }>): string {
   const tool_names = new Set<string>();
   for (const part of message.parts) {
     if (part.type !== "tool") continue;
@@ -30,16 +30,33 @@ function extract_assistant_tool_summary(message: Extract<SessionMessage, { type:
 export function resolve_session_message_preview(
   message: SessionMessage,
 ): string {
-  if (message.type === "action") {
-    return message.description
-      ? `${message.title}\n${message.description}`
-      : message.title;
-  }
-  if (message.type === "error") return message.message;
   const plain_text = extract_session_message_text(message);
   if (plain_text) return plain_text;
-  if (message.type !== "assistant") return "";
+  if (message.role !== "agent") return "";
 
   const user_visible = resolve_session_assistant_visible_text(message).trim();
-  return user_visible || extract_assistant_tool_summary(message);
+  if (user_visible) return user_visible;
+  for (const part of message.parts) {
+    switch (part.type) {
+      case "action":
+        return part.description ? `${part.title}\n${part.description}` : part.title;
+      case "error":
+        return part.message;
+      case "text":
+      case "reasoning":
+      case "tool":
+      case "interaction":
+      case "file":
+      case "data":
+        break;
+      default:
+        assert_never(part);
+    }
+  }
+  return extract_assistant_tool_summary(message);
+}
+
+/** canonical Agent Part 增加成员时强制预览投影显式处理。 */
+function assert_never(value: never): never {
+  throw new Error(`Unsupported preview Session Part: ${String((value as { type?: unknown }).type)}`);
 }

package/src/session/runtime/SessionTurnCompletion.ts

@@ -0,0 +1,159 @@
+/**
+ * Session Turn 结果收口。
+ *
+ * 本模块统一结果映射、Turn Mutation、committed Hook 与 Context 释放顺序。它不消费
+ * Queue，也不持有 Active Turn 引用或 Handle；这些调度状态仍由 SessionLoop 收口。
+ */
+
+import { nanoid } from "nanoid";
+import type { JsonValue, SessionMessage } from "@downcity/type";
+import type { AgentSessionTurnResult } from "@/types/sdk/AgentSessionTurn.js";
+import type { SessionTurnExecutionResult } from "@/types/session/SessionExecution.js";
+import type { ActiveSessionTurnState } from "@/types/session/SessionLoop.js";
+import type { SessionTurnCompletionOptions } from "@/types/session/SessionTurnCompletion.js";
+import type { SessionTurnCommittedHookValue } from "@downcity/type";
+import { SESSION_HOOK_POINTS } from "@/session/SessionHookPoints.js";
+
+/** 使用 Executor 结果完成当前 Turn。 */
+export async function complete_session_turn(
+  options: SessionTurnCompletionOptions,
+  active_turn: ActiveSessionTurnState,
+  result: SessionTurnExecutionResult,
+): Promise<AgentSessionTurnResult> {
+  const stopped = active_turn.turn_context?.lifecycle.abort_signal.aborted === true;
+  const final_result: AgentSessionTurnResult = {
+    turn_id: active_turn.turn_id,
+    text: result.text,
+    success: stopped ? false : result.success,
+    ...(stopped
+      ? { error: options.stopped_message }
+      : result.error ? { error: result.error } : {}),
+  };
+  active_turn.result = final_result;
+  options.events.publish({
+    mutation_id: nanoid(),
+    variant: "turn",
+    type: "finish",
+    session_id: options.session_id,
+    turn_id: active_turn.turn_id,
+    status: stopped ? "stopped" : final_result.success ? "completed" : "failed",
+    created_at: Date.now(),
+    text: final_result.text,
+    ...(final_result.error ? { error: final_result.error } : {}),
+  });
+  await notify_turn_committed(
+    options,
+    active_turn,
+    stopped ? "stopped" : final_result.success ? "completed" : "failed",
+  );
+  await dispose_turn_context(options, active_turn);
+  return final_result;
+}
+
+/** 使用稳定失败结果结束当前 Turn。 */
+export async function fail_session_turn(
+  options: SessionTurnCompletionOptions,
+  active_turn: ActiveSessionTurnState,
+  error: unknown,
+): Promise<AgentSessionTurnResult> {
+  if (active_turn.result) return active_turn.result;
+  const stopped = active_turn.turn_context?.lifecycle.abort_signal.aborted === true;
+  const message = stopped
+    ? options.stopped_message
+    : error instanceof Error ? error.message : String(error);
+  const final_result: AgentSessionTurnResult = {
+    turn_id: active_turn.turn_id,
+    text: "",
+    success: false,
+    error: message,
+  };
+  active_turn.result = final_result;
+  if (message !== options.stopped_message) {
+    try {
+      await options.messages.append_error_part({
+        scope: "turn",
+        turn_id: active_turn.turn_id,
+        code: "turn_execution_failed",
+        message,
+        recoverable: true,
+      });
+    } catch {
+      // Error Part 兜底写入失败不能阻止 Turn Handle 收口。
+    }
+  }
+  options.events.publish({
+    mutation_id: nanoid(),
+    variant: "turn",
+    type: "finish",
+    session_id: options.session_id,
+    turn_id: active_turn.turn_id,
+    status: stopped ? "stopped" : "failed",
+    created_at: Date.now(),
+    text: "",
+    error: message,
+  });
+  await notify_turn_committed(options, active_turn, stopped ? "stopped" : "failed");
+  await dispose_turn_context(options, active_turn);
+  return final_result;
+}
+
+/** 在释放当前 Hook lease 前触发 Turn committed effect。 */
+async function notify_turn_committed(
+  options: SessionTurnCompletionOptions,
+  active_turn: ActiveSessionTurnState,
+  status: SessionTurnCommittedHookValue["status"],
+): Promise<void> {
+  const hooks = active_turn.turn_context?.step.hooks;
+  if (!hooks) return;
+  try {
+    const messages = (await options.messages.list_history_messages())
+      .filter((message) => message.turn_id === active_turn.turn_id)
+      .map((message) => structuredClone(message));
+    const value: SessionTurnCommittedHookValue = {
+      session_id: options.session_id,
+      turn_id: active_turn.turn_id,
+      status,
+      messages: messages as SessionMessage[],
+    };
+    await hooks.effect(
+      SESSION_HOOK_POINTS.turn_committed,
+      value as unknown as JsonValue,
+    );
+  } catch (error) {
+    await log_turn_warning(options, active_turn, "session plugin effect failed", error, {
+      point_name: SESSION_HOOK_POINTS.turn_committed,
+    });
+  }
+}
+
+/** 尽力释放当前 Turn 唯一拥有的 Context。 */
+async function dispose_turn_context(
+  options: SessionTurnCompletionOptions,
+  active_turn: ActiveSessionTurnState,
+): Promise<void> {
+  try {
+    await active_turn.turn_context?.lifecycle.dispose();
+  } catch (error) {
+    await log_turn_warning(options, active_turn, "turn context disposal failed", error);
+  }
+}
+
+/** Turn 已经确定结果后使用的 best-effort 日志入口。 */
+async function log_turn_warning(
+  options: SessionTurnCompletionOptions,
+  active_turn: ActiveSessionTurnState,
+  message: string,
+  error: unknown,
+  detail: Record<string, string> = {},
+): Promise<void> {
+  try {
+    await options.logger.log("warn", `[agent] ${message}`, {
+      session_id: options.session_id,
+      turn_id: active_turn.turn_id,
+      ...detail,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  } catch {
+    // Turn 结果已经确定，日志失败不能阻止 Handle 收口。
+  }
+}

package/src/session/runtime/SessionTurnContext.ts

@@ -9,7 +9,7 @@
 
 import type { RuntimeToolEffect } from "@downcity/type";
 import type { SessionUserMessage } from "@downcity/type";
-import type { SessionAssistantResultPart } from "@downcity/type";
+import type { SessionAgentContent } from "@downcity/type";
 import type {
   SessionTurnContext,
   SessionTurnContextInit,
@@ -51,9 +51,8 @@ class DefaultSessionTurnContext implements SessionTurnContext {
   private plugin_context_blocks_snapshot: readonly SessionHookContextBlock[] = Object.freeze([]);
   /** 并发或重复解析时复用的唯一 Promise。 */
   private plugin_context_blocks_promise?: Promise<readonly SessionHookContextBlock[]>;
-  private injected_user_messages: SessionUserMessage[] = [];
-  private deferred_messages: SessionUserMessage[] = [];
-  private pending_assistant_parts: SessionAssistantResultPart[] = [];
+  private observed_user_messages: SessionUserMessage[] = [];
+  private pending_assistant_parts: SessionAgentContent[] = [];
   private turn_effects: RuntimeToolEffect[] = [];
 
   readonly lifecycle: SessionTurnContext["lifecycle"];
@@ -146,27 +145,27 @@ class DefaultSessionTurnContext implements SessionTurnContext {
     });
 
     this.input = Object.freeze({
-      checkpoint: async () => {
-        const injected = context.injected_user_messages;
-        context.injected_user_messages = [];
-        let queued: SessionUserMessage[] = [];
-        try {
-          queued = (await context.init.merge_step_input?.()) || [];
-        } catch {
-          queued = [];
+      observe_user_message: (message) => {
+        if (message.turn_id !== context.session.turn_id) {
+          throw new Error(`Observed User Message belongs to another Turn: ${message.message_id}`);
         }
-        return [...injected, ...queued];
+        context.observed_user_messages.push(structuredClone(message));
       },
-      has_pending: () => context.init.has_pending_step_input?.() === true,
-      inject_user_message: (message) => {
-        context.injected_user_messages.push(message);
+      user_messages: () => Object.freeze(
+        context.observed_user_messages.map((message) => structuredClone(message)),
+      ),
+      checkpoint: async () => {
+        await context.init.commit_step_input?.();
       },
-      defer_user_message: (message) => {
-        context.deferred_messages.push(message);
+      has_pending: () => context.init.has_pending_step_input?.() === true,
+      append_internal: async (parts) => {
+        if (!context.init.append_internal_user_message) {
+          throw new Error("SessionTurnContext cannot persist internal User input");
+        }
+        return await context.init.append_internal_user_message(
+          parts.map((part) => structuredClone(part)),
+        );
       },
-      deferred_user_messages: () => Object.freeze([...context.deferred_messages]),
-      consume_history_reload: () =>
-        context.init.consume_history_reload?.() === true,
     });
 
     this.output = Object.freeze({

package/src/session/runtime/SessionTurnFileDiff.ts

@@ -0,0 +1,105 @@
+/**
+ * Session Turn 文件修改观测。
+ *
+ * 本模块把 Tool effects 投影为实时摘要和最终 canonical data part。所有失败都只记录
+ * warning，不得反向改变 Turn 结果。
+ */
+
+import { nanoid } from "nanoid";
+import {
+  build_session_turn_file_diff,
+  build_session_turn_file_diff_summary,
+} from "@/session/messages/SessionTurnFileDiffBuilder.js";
+import { SESSION_TURN_FILE_DIFF_DATA_TYPE } from "@/session/messages/SessionTurnFileDiffData.js";
+import type {
+  AppendSessionTurnFileDiffInput,
+  PublishSessionTurnFileDiffInput,
+} from "@/types/session/SessionTurnFileDiff.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+
+/** 把当前 Turn 成功的结构化文件修改写入 canonical Assistant data part。 */
+export async function append_session_turn_file_diff(
+  input: AppendSessionTurnFileDiffInput,
+): Promise<void> {
+  try {
+    const file_diff = build_session_turn_file_diff(
+      input.workspace_path,
+      input.turn_context.effects.snapshot(),
+    );
+    if (!file_diff) return;
+    await input.assistant_output.append_result_parts([{
+      type: "data",
+      data_type: SESSION_TURN_FILE_DIFF_DATA_TYPE,
+      data_id: `turn-file-diff:${input.turn_id}`,
+      data: {
+        files: file_diff.files.map((file) => ({
+          file: file.file,
+          status: file.status,
+          additions: file.additions,
+          deletions: file.deletions,
+          patch: file.patch,
+        })),
+        additions: file_diff.additions,
+        deletions: file_diff.deletions,
+      },
+    }]);
+  } catch (error) {
+    await log_file_diff_warning(
+      input.logger,
+      input.session_id,
+      input.turn_id,
+      "failed to persist structured file edits",
+      error,
+    );
+  }
+}
+
+/** 发布当前 Turn 的实时文件修改摘要。 */
+export function publish_session_turn_file_diff(
+  input: PublishSessionTurnFileDiffInput,
+): void {
+  try {
+    const summary = build_session_turn_file_diff_summary(
+      input.workspace_path,
+      input.effects,
+    );
+    if (summary.files_count === 0) return;
+    input.publish({
+      mutation_id: nanoid(),
+      variant: "file_diff",
+      session_id: input.session_id,
+      turn_id: input.turn_id,
+      created_at: Date.now(),
+      files_count: summary.files_count,
+      additions: summary.additions,
+      deletions: summary.deletions,
+    });
+  } catch (error) {
+    void log_file_diff_warning(
+      input.logger,
+      input.session_id,
+      input.turn_id,
+      "failed to publish live file edit summary",
+      error,
+    );
+  }
+}
+
+/** 文件修改观测失败使用的 best-effort 日志入口。 */
+async function log_file_diff_warning(
+  logger: Logger,
+  session_id: string,
+  turn_id: string,
+  message: string,
+  error: unknown,
+): Promise<void> {
+  try {
+    await logger.log("warn", `[agent] ${message}`, {
+      session_id,
+      turn_id,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  } catch {
+    // 文件编辑观测失败不影响 canonical 对话执行。
+  }
+}

package/src/session/storage/LocalSessionDataStore.ts

@@ -1,190 +1,41 @@
 /**
- * LocalSessionDataStore：Agent 内单个 Session 的 JSONL 持久化视图。
+ * 本地 Agent 单 Session 的 SQLite Storage。
  *
- * 职责说明（中文）
- * - 集中创建 Message Store，并封装 Metadata 与 Instruction 的物理路径。
- * - Session 领域只持有本对象，不再自行拼接任何存储路径。
+ * 本类只负责把 Agent 私有目录、数据库位置和附件目录装配给通用 SQLite 实现；
+ * Session 领域不在这里拼接任何物理路径。
  */
 
-import { isDeepStrictEqual } from "node:util";
-import { JsonlSessionMessageStore } from "@/session/storage/JsonlSessionMessageStore.js";
+import { LocalSessionAttachmentStore } from "@/session/storage/LocalSessionAttachmentStore.js";
 import {
-  get_agent_session_instruction_path,
-  get_agent_session_meta_path,
-  get_agent_session_assistant_message_path,
-  get_agent_session_active_messages_path,
   get_agent_session_attachments_path,
+  get_agent_session_database_path,
 } from "@/session/storage/LocalStorePaths.js";
-import { normalize_session_metadata } from "@/session/storage/Metadata.js";
-import type { SessionHistoryMeta } from "@/executor/types/SessionHistoryMeta.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
-import type { FileSystem } from "@downcity/type";
+import { SqliteSessionStorage } from "@/session/storage/SqliteSessionStorage.js";
 import type { LocalSessionDataStoreOptions } from "@/types/store/LocalStore.js";
-import { LocalSessionAttachmentStore } from "@/session/storage/LocalSessionAttachmentStore.js";
-import type { SessionOrigin } from "@downcity/type";
-
-/** 本地 Session Store。 */
-export class LocalSessionDataStore implements SessionDataStore {
-  /** 当前 Session 的稳定标识。 */
-  readonly session_id: string;
-
-  /** 当前 Session 的 JSONL Message Store。 */
-  readonly messages: JsonlSessionMessageStore;
-
-  /** 当前 Session 的附件持久化能力。 */
-  readonly attachments: LocalSessionAttachmentStore;
-
-  /** 当前 Session 的创建来源与物理存储分区。 */
-  readonly origin: SessionOrigin;
-
-  /** 当前 Agent 内部数据文件能力。 */
-  private readonly files: FileSystem;
-
-  /** 当前 Agent 的稳定标识。 */
-  private readonly agent_id: string;
-
-  /** 当前 Workspace 的稳定标识。 */
-  private readonly workspace_id?: string;
-
-  /** 当前 Agent 内部数据根路径。 */
-  private readonly storage_root_path: string;
 
+/** Agent 私有 Session 的默认 SQLite Storage。 */
+export class LocalSessionDataStore extends SqliteSessionStorage {
   constructor(options: LocalSessionDataStoreOptions) {
-    this.files = options.files;
-    this.agent_id = options.agent_id;
-    this.workspace_id = options.workspace_id;
-    this.storage_root_path = options.storage_root_path;
-    this.session_id = options.session_id;
-    this.origin = options.origin;
-    this.messages = new JsonlSessionMessageStore({
-      files: this.files,
-      session_id: this.session_id,
-      file_path: get_agent_session_active_messages_path(
-        this.storage_root_path,
-        this.origin.type,
-        this.session_id,
-      ),
-      assistant_message_file_path: get_agent_session_assistant_message_path(
-        this.storage_root_path,
-        this.origin.type,
-        this.session_id,
+    super({
+      session_id: options.session_id,
+      agent_id: options.agent_id,
+      ...(options.workspace_id ? { workspace_id: options.workspace_id } : {}),
+      origin: options.origin,
+      database_path: get_agent_session_database_path(
+        options.storage_root_path,
+        options.origin.type,
+        options.session_id,
       ),
+      database_location: options.database_location,
+      files: options.files,
+      attachments: new LocalSessionAttachmentStore({
+        files: options.files,
+        attachments_dir_path: get_agent_session_attachments_path(
+          options.storage_root_path,
+          options.origin.type,
+          options.session_id,
+        ),
+      }),
     });
-    this.attachments = new LocalSessionAttachmentStore({
-      files: this.files,
-      attachments_dir_path: get_agent_session_attachments_path(
-        this.storage_root_path,
-        this.origin.type,
-        this.session_id,
-      ),
-    });
-  }
-
-  /** 读取规范化 Session Metadata。 */
-  async read_metadata(): Promise<SessionHistoryMeta> {
-    try {
-      const raw = JSON.parse(
-        (await this.files.read_file(this.metadata_path())).toString("utf8"),
-      ) as Partial<SessionHistoryMeta>;
-      const metadata = normalize_session_metadata(
-        raw,
-        this.session_id,
-        this.agent_id,
-        this.origin,
-        this.workspace_id,
-      );
-      if (raw.agent_id !== this.agent_id) {
-        throw new Error(
-          `Session "${this.session_id}" belongs to another Agent`,
-        );
-      }
-      return metadata;
-    } catch {
-      if (await this.files.path_exists(this.metadata_path())) {
-        throw new Error(
-          `Invalid Session ownership metadata: ${this.session_id}`,
-        );
-      }
-      return normalize_session_metadata(
-        {},
-        this.session_id,
-        this.agent_id,
-        this.origin,
-        this.workspace_id,
-      );
-    }
-  }
-
-  /** 写入完整 Session Metadata。 */
-  async write_metadata(metadata: SessionHistoryMeta): Promise<void> {
-    const normalized = normalize_session_metadata(
-      metadata,
-      this.session_id,
-      this.agent_id,
-      this.origin,
-      this.workspace_id,
-    );
-    if (!isDeepStrictEqual(normalized.origin, this.origin)) {
-      throw new Error(`Session "${this.session_id}" origin is immutable`);
-    }
-    const metadata_path = this.metadata_path();
-    await this.files.with_file_lock(`${metadata_path}.lock`, async () => {
-      if (await this.files.path_exists(metadata_path)) {
-        const existing = JSON.parse(
-          (await this.files.read_file(metadata_path)).toString("utf8"),
-        ) as Partial<SessionHistoryMeta>;
-        if (existing.session_id !== this.session_id || existing.agent_id !== this.agent_id) {
-          throw new Error(
-            `Session "${this.session_id}" belongs to another Agent`,
-          );
-        }
-        if (!isDeepStrictEqual(existing.origin, normalized.origin)) {
-          throw new Error(`Session "${this.session_id}" origin is immutable`);
-        }
-      }
-      await this.files.write_file_atomically(
-        metadata_path,
-        `${JSON.stringify(normalized, null, 2)}\n`,
-      );
-    });
-  }
-
-  /** 判断显式 system 快照是否存在。 */
-  async has_instruction(): Promise<boolean> {
-    return await this.files.path_exists(this.instruction_path());
-  }
-
-  /** 读取显式 system 快照。 */
-  async read_instruction(): Promise<string | null> {
-    if (!(await this.has_instruction())) return null;
-    return (await this.files.read_file(this.instruction_path())).toString("utf8");
-  }
-
-  /** 写入显式 system 快照。 */
-  async write_instruction(instruction: string): Promise<void> {
-    const instruction_path = get_agent_session_instruction_path(
-      this.storage_root_path,
-      this.origin.type,
-      this.session_id,
-    );
-    await this.files.write_file_atomically(instruction_path, instruction);
-  }
-
-  /** 返回当前 Session instruction.md 的 Agent Storage 路径。 */
-  private instruction_path(): string {
-    return get_agent_session_instruction_path(
-      this.storage_root_path,
-      this.origin.type,
-      this.session_id,
-    );
-  }
-
-  /** 返回当前 Session meta.json 的 Agent Storage 路径。 */
-  private metadata_path(): string {
-    return get_agent_session_meta_path(
-      this.storage_root_path,
-      this.origin.type,
-      this.session_id,
-    );
   }
 }