@downcity/agent 1.1.408 → 1.1.437

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

@@ -7,19 +7,25 @@
  * - Plugin 每次只获得新建的只读快照，不能越过扩展边界访问内核运行能力。
  */
 
-import type { SessionUserMessage } from "@/types/session/SessionMessage.js";
-import type { SessionAssistantResultPart } from "@/types/session/SessionContent.js";
+import type { RuntimeToolEffect } from "@downcity/type";
+import type { SessionUserMessage } from "@downcity/type";
+import type { SessionAgentContent } from "@downcity/type";
 import type {
   SessionTurnContext,
   SessionTurnContextInit,
 } from "@/types/executor/SessionTurnContext.js";
-import type { AgentPluginExecutionLease } from "@/types/plugin/PluginRuntime.js";
-import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
+import type { SessionHookContext } from "@downcity/type";
+import type { SessionHookScopeRuntime } from "@downcity/type";
+import type { SessionOrigin } from "@downcity/type";
+import { normalize_session_origin } from "@downcity/type";
+import type { SessionHookContextBlock } from "@downcity/type";
 
 /** 非 Turn 查询创建 Plugin 只读快照所需的稳定 Session 状态。 */
-export interface CreateSessionPluginExecutionContextInput {
+export interface CreateSessionHookContextInput {
   /** 当前 Session 标识。 */
   session_id: string;
+  /** 当前 Session 的完整来源元数据。 */
+  session_origin: SessionOrigin;
   /** 当前 Session 所属项目根目录。 */
   project_root: string;
   /** 当前 Session 已生效的 Workspace 环境变量。 */
@@ -40,15 +46,20 @@ class DefaultSessionTurnContext implements SessionTurnContext {
   private disposed = false;
   private workspace_env_snapshot?: Readonly<Record<string, string>>;
   private agent_systems_snapshot: readonly string[] = Object.freeze([]);
-  private plugin_lease?: AgentPluginExecutionLease;
-  private injected_user_messages: SessionUserMessage[] = [];
-  private deferred_messages: SessionUserMessage[] = [];
-  private pending_assistant_parts: SessionAssistantResultPart[] = [];
+  private hook_scope?: SessionHookScopeRuntime;
+  /** 整个 Turn 共享的 Plugin 动态上下文，不随 Step lease 切换而失效。 */
+  private plugin_context_blocks_snapshot: readonly SessionHookContextBlock[] = Object.freeze([]);
+  /** 并发或重复解析时复用的唯一 Promise。 */
+  private plugin_context_blocks_promise?: Promise<readonly SessionHookContextBlock[]>;
+  private observed_user_messages: SessionUserMessage[] = [];
+  private pending_assistant_parts: SessionAgentContent[] = [];
+  private turn_effects: RuntimeToolEffect[] = [];
 
   readonly lifecycle: SessionTurnContext["lifecycle"];
   readonly step: SessionTurnContext["step"];
   readonly input: SessionTurnContext["input"];
   readonly output: SessionTurnContext["output"];
+  readonly effects: SessionTurnContext["effects"];
 
   constructor(private readonly init: SessionTurnContextInit) {
     const session_id = String(init.session_id || "").trim();
@@ -62,6 +73,7 @@ class DefaultSessionTurnContext implements SessionTurnContext {
     const project_root = String(init.project_root || "").trim();
     this.session = Object.freeze({
       session_id,
+      origin: Object.freeze(normalize_session_origin(init.session_origin)),
       turn_id,
       ...(project_root ? { project_root } : {}),
     });
@@ -106,8 +118,11 @@ class DefaultSessionTurnContext implements SessionTurnContext {
       get agent_systems() {
         return context.agent_systems_snapshot;
       },
-      get plugins() {
-        return context.plugin_lease;
+      get hooks() {
+        return context.hook_scope;
+      },
+      get plugin_context_blocks() {
+        return context.plugin_context_blocks_snapshot;
       },
       commit: (input) => {
         context.workspace_env_snapshot = Object.freeze({
@@ -117,38 +132,40 @@ class DefaultSessionTurnContext implements SessionTurnContext {
           ...input.agent_systems,
         ]);
       },
-      replace_plugins: async (plugins) => {
-        const previous = context.plugin_lease;
-        context.plugin_lease = plugins;
-        if (previous && previous !== plugins) await previous.release();
+      replace_hooks: async (hooks) => {
+        const previous = context.hook_scope;
+        context.hook_scope = hooks;
+        if (previous && previous !== hooks) await previous.close();
       },
-      release: async () => await context.release_plugins(),
-      plugin_execution_context: (call_id?: string) =>
-        context.create_plugin_execution_context(call_id),
+      resolve_plugin_context_blocks: async (resolver) =>
+        await context.resolve_plugin_context_blocks(resolver),
+      release: async () => await context.release_extensions(),
+      hook_context: (call_id?: string) =>
+        context.create_hook_context(call_id),
     });
 
     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({
@@ -164,14 +181,46 @@ class DefaultSessionTurnContext implements SessionTurnContext {
       publish_action: async (event) => {
         await context.init.publish_action?.(event);
       },
+      report_model_request_failure: (notice) => {
+        context.init.report_model_request_failure?.(notice);
+      },
     });
+
+    this.effects = Object.freeze({
+      append: (effects) => {
+        if (effects.length === 0) return;
+        context.turn_effects.push(...effects);
+        init.on_effects_changed?.(Object.freeze([...context.turn_effects]));
+      },
+      snapshot: () => Object.freeze([...context.turn_effects]),
+    });
+  }
+
+  /** 每个 Turn 只执行一次 Plugin 动态上下文解析，并保存不可变快照。 */
+  private async resolve_plugin_context_blocks(
+    resolver: () => Promise<readonly SessionHookContextBlock[]>,
+  ): Promise<readonly SessionHookContextBlock[]> {
+    this.plugin_context_blocks_promise ??= (async () => {
+      const blocks = await resolver();
+      this.plugin_context_blocks_snapshot = Object.freeze(
+        (Array.isArray(blocks) ? blocks : []).map((block) => Object.freeze({
+          ...block,
+          ...(block.citations
+            ? { citations: Object.freeze([...block.citations]) as unknown as string[] }
+            : {}),
+        })),
+      );
+      return this.plugin_context_blocks_snapshot;
+    })();
+    return await this.plugin_context_blocks_promise;
   }
 
-  /** 为 Plugin 生成不共享根对象引用的只读快照。 */
-  private create_plugin_execution_context(call_id?: string): PluginExecutionContext {
+  /** 为 City 扩展生成不共享根对象引用的只读快照。 */
+  private create_hook_context(call_id?: string): SessionHookContext {
     const normalized_call_id = String(call_id || "").trim();
     return Object.freeze({
       session_id: this.session.session_id,
+      session_origin: this.session.origin,
       turn_id: this.session.turn_id,
       ...(normalized_call_id ? { call_id: normalized_call_id } : {}),
       ...(this.session.project_root
@@ -185,11 +234,11 @@ class DefaultSessionTurnContext implements SessionTurnContext {
     });
   }
 
-  /** 释放当前 Step 捕获的 Plugin lease。 */
-  private async release_plugins(): Promise<void> {
-    const plugins = this.plugin_lease;
-    this.plugin_lease = undefined;
-    await plugins?.release();
+  /** 释放当前 Step 捕获的 Plugin Hook 作用域。 */
+  private async release_extensions(): Promise<void> {
+    const extensions = this.hook_scope;
+    this.hook_scope = undefined;
+    await extensions?.close();
   }
 
   /** 闭合当前运行拥有的全部资源。 */
@@ -200,7 +249,7 @@ class DefaultSessionTurnContext implements SessionTurnContext {
       "abort",
       this.abort_from_upstream,
     );
-    await this.release_plugins();
+    await this.release_extensions();
   }
 }
 
@@ -212,11 +261,12 @@ export function create_session_turn_context(
 }
 
 /** 为非 Turn 的 system 查询创建 Plugin 可读取的 Session 快照。 */
-export function create_session_plugin_execution_context(
-  input: CreateSessionPluginExecutionContextInput,
-): PluginExecutionContext {
+export function create_session_hook_context(
+  input: CreateSessionHookContextInput,
+): SessionHookContext {
   return Object.freeze({
     session_id: input.session_id,
+    session_origin: Object.freeze(normalize_session_origin(input.session_origin)),
     project_root: input.project_root,
     workspace_env: Object.freeze({ ...input.workspace_env }),
     agent_systems: Object.freeze([...input.agent_systems]),

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/{workspace/store → session/storage}/LocalSessionAttachmentStore.ts

@@ -1,12 +1,13 @@
 /**
- * Workspace 内 Session 附件的本地实现。
+ * Agent 私有 Storage 内 Session 附件的本地实现。
  *
- * Data URL 在这里解码为文件；Message 层保存 Agent 私有目录中的绝对路径。
+ * Data URL 在这里解码为文件；fork 来源附件在同一 Agent Storage 内复制；
+ * Message 层保存 Agent 私有目录中的绝对路径。
  */
 
 import path from "node:path";
 import { generate_id } from "@/utils/Id.js";
-import type { FileSystem } from "@downcity/workspace";
+import type { FileSystem } from "@downcity/type";
 import type { SessionAttachmentStore } from "@/types/store/SessionAttachmentStore.js";
 
 const DATA_URL_PATTERN = /^data:([^;,]+)?((?:;[^;,]+)*),(.*)$/s;
@@ -23,7 +24,7 @@ const MEDIA_TYPE_EXTENSIONS: Record<string, string> = {
 };
 
 export interface LocalSessionAttachmentStoreOptions {
-  /** Workspace 文件能力。 */
+  /** 当前 Agent 私有 Storage 的文件能力。 */
   files: FileSystem;
   /** 当前 Session 附件目录的绝对路径。 */
   attachments_dir_path: string;
@@ -39,6 +40,12 @@ export class LocalSessionAttachmentStore implements SessionAttachmentStore {
     this.attachments_dir_path = path.resolve(options.attachments_dir_path);
   }
 
+  owns_local_file(url: string): boolean {
+    const candidate = path.resolve(String(url || ""));
+    const relative = path.relative(this.attachments_dir_path, candidate);
+    return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+  }
+
   async persist_data_url(input: {
     data_url: string;
     media_type: string;
@@ -52,6 +59,20 @@ export class LocalSessionAttachmentStore implements SessionAttachmentStore {
     await this.files.write_file_atomically(absolute_path, parsed.bytes);
     return absolute_path;
   }
+
+  async copy_local_file(input: {
+    source_url: string;
+    media_type: string;
+    filename?: string;
+  }): Promise<string> {
+    const extension = resolve_extension(input.media_type, input.filename);
+    const attachment_name = `att_${generate_id()}${extension}`;
+    const absolute_path = path.join(this.attachments_dir_path, attachment_name);
+    const bytes = await this.files.read_file(input.source_url);
+    await this.files.ensure_directory(this.attachments_dir_path);
+    await this.files.write_file_atomically(absolute_path, bytes);
+    return absolute_path;
+  }
 }
 
 function parse_data_url(data_url: string, fallback_media_type: string): {

package/src/session/storage/LocalSessionDataStore.ts

@@ -0,0 +1,41 @@
+/**
+ * 本地 Agent 单 Session 的 SQLite Storage。
+ *
+ * 本类只负责把 Agent 私有目录、数据库位置和附件目录装配给通用 SQLite 实现；
+ * Session 领域不在这里拼接任何物理路径。
+ */
+
+import { LocalSessionAttachmentStore } from "@/session/storage/LocalSessionAttachmentStore.js";
+import {
+  get_agent_session_attachments_path,
+  get_agent_session_database_path,
+} from "@/session/storage/LocalStorePaths.js";
+import { SqliteSessionStorage } from "@/session/storage/SqliteSessionStorage.js";
+import type { LocalSessionDataStoreOptions } from "@/types/store/LocalStore.js";
+
+/** Agent 私有 Session 的默认 SQLite Storage。 */
+export class LocalSessionDataStore extends SqliteSessionStorage {
+  constructor(options: LocalSessionDataStoreOptions) {
+    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,
+        ),
+      }),
+    });
+  }
+}