@downcity/agent 1.1.287 → 1.1.310

package/src/session/runtime/SessionCompactOperation.ts

@@ -0,0 +1,93 @@
+/**
+ * Session 显式压缩操作生命周期。
+ *
+ * 该模块只负责把队列 Command 的异步执行映射为公开 Compact Handle；压缩计划、
+ * canonical 历史提交与事件发布仍由 Session 领域拥有。
+ */
+
+import type {
+  AgentSessionCompactHandle,
+  AgentSessionCompactResult,
+} from "@/types/sdk/AgentSessionCompact.js";
+import type { SessionCompactHistory } from "@/types/session/SessionExecution.js";
+
+/** 创建显式压缩操作所需的领域回调。 */
+export interface CreateSessionCompactOperationOptions {
+  /** 当前显式压缩请求的稳定标识。 */
+  compact_id: string;
+  /** 在 Session Queue 检查点执行统一历史压缩。 */
+  run: () => ReturnType<SessionCompactHistory>;
+  /** 发布最终 Compact Mutation；观测失败不能改变结果。 */
+  publish_finish: (result: AgentSessionCompactResult) => void;
+  /** 尽力记录未被压缩领域入口吸收的异常。 */
+  log_error: (error_message: string) => Promise<void>;
+}
+
+/** 显式压缩操作暴露给 Session Queue 的内部能力。 */
+export interface SessionCompactOperation {
+  /** 立即返回给 SDK 调用方的等待句柄。 */
+  handle: AgentSessionCompactHandle;
+  /** 由排队的 Session Command 调用并负责最终兑现句柄。 */
+  execute: () => Promise<void>;
+}
+
+/** 创建一个与单次 Session Compact Command 绑定的操作生命周期。 */
+export function create_session_compact_operation(
+  options: CreateSessionCompactOperationOptions,
+): SessionCompactOperation {
+  let result: AgentSessionCompactResult | null = null;
+  let resolve_finished!: (value: AgentSessionCompactResult) => void;
+  const finished = new Promise<AgentSessionCompactResult>((resolve) => {
+    resolve_finished = resolve;
+  });
+
+  return {
+    handle: {
+      id: options.compact_id,
+      get result() {
+        return result;
+      },
+      finished,
+    },
+    execute: async () => {
+      let final_result: AgentSessionCompactResult;
+      try {
+        const outcome = await options.run();
+        const reason = outcome.compacted
+          ? "compacted"
+          : outcome.reason === "nothing_to_compact"
+            ? "nothing_to_compact"
+            : "compact_failed";
+        final_result = {
+          compact_id: options.compact_id,
+          success: reason !== "compact_failed",
+          compacted: outcome.compacted,
+          reason,
+          ...(outcome.error ? { error: outcome.error } : {}),
+        };
+      } catch (error) {
+        const error_message = error instanceof Error ? error.message : String(error);
+        final_result = {
+          compact_id: options.compact_id,
+          success: false,
+          compacted: false,
+          reason: "compact_failed",
+          error: error_message,
+        };
+        try {
+          await options.log_error(error_message);
+        } catch {
+          // 关键点（中文）：日志属于观测侧，失败不能阻止 Handle 收口。
+        }
+      }
+
+      result = final_result;
+      try {
+        options.publish_finish(final_result);
+      } catch {
+        // 关键点（中文）：事件发布失败不能让已完成的 Command 反向失败。
+      }
+      resolve_finished(final_result);
+    },
+  };
+}

package/src/session/runtime/SessionHistoryCompaction.ts

@@ -0,0 +1,45 @@
+/**
+ * Session 历史压缩结果收口器。
+ *
+ * Session 仍提供 Composer 输入和 canonical 提交回调；本模块统一成功、空计划、
+ * 失败与 best-effort 日志的结果映射，供显式压缩和自动恢复共同复用。
+ */
+
+import type { SessionCompactionPlan } from "@/types/session/SessionComposer.js";
+import type { SessionCompactHistory } from "@/types/session/SessionExecution.js";
+
+/** 执行一次历史压缩所需的 Session 领域回调。 */
+export interface RunSessionHistoryCompactionOptions {
+  /** 当前压缩所属 Turn；空值表示显式队列命令尚未进入 Turn。 */
+  turn_id?: string;
+  /** 让 Composer 基于只读 Session 快照生成压缩计划。 */
+  create_plan: () => Promise<SessionCompactionPlan | null>;
+  /** 原子提交 Composer 返回的 canonical 压缩计划。 */
+  commit_plan: (plan: SessionCompactionPlan) => Promise<void>;
+  /** 尽力记录压缩错误，不得覆盖领域结果。 */
+  log_error: (error_message: string) => Promise<void>;
+}
+
+/** 执行并收口一次统一 Session 历史压缩。 */
+export async function run_session_history_compaction(
+  options: RunSessionHistoryCompactionOptions,
+): ReturnType<SessionCompactHistory> {
+  try {
+    const plan = await options.create_plan();
+    if (!plan) return { compacted: false, reason: "nothing_to_compact" };
+    await options.commit_plan(plan);
+    return { compacted: true };
+  } catch (error) {
+    const error_message = error instanceof Error ? error.message : String(error);
+    try {
+      await options.log_error(error_message);
+    } catch {
+      // 关键点（中文）：日志失败不能覆盖稳定的压缩领域结果。
+    }
+    return {
+      compacted: false,
+      reason: "compact_failed",
+      error: error_message,
+    };
+  }
+}

package/src/session/runtime/SessionTurnContext.ts

@@ -0,0 +1,222 @@
+/**
+ * SessionTurnContext 运行时实现。
+ *
+ * 关键点（中文）
+ * - Session 创建并拥有上下文，Executor 和 Tool 通过领域分区协作。
+ * - 所有可变数组、Plugin lease 与取消监听都封装在本模块内。
+ * - Plugin 每次只获得新建的只读快照，不能越过扩展边界访问内核运行能力。
+ */
+
+import type { UIMessage } from "ai";
+import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
+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";
+
+/** 非 Turn 查询创建 Plugin 只读快照所需的稳定 Session 状态。 */
+export interface CreateSessionPluginExecutionContextInput {
+  /** 当前 Session 标识。 */
+  session_id: string;
+  /** 当前 Session 所属项目根目录。 */
+  project_root: string;
+  /** 当前 Session 已生效的 Workspace 环境变量。 */
+  workspace_env: Readonly<Record<string, string>>;
+  /** 当前 Session 已生效的 Agent instruction 文本。 */
+  agent_systems: readonly string[];
+}
+
+/** SessionTurnContext 的唯一内置实现。 */
+class DefaultSessionTurnContext implements SessionTurnContext {
+  readonly session: SessionTurnContext["session"];
+  readonly interactions: SessionTurnContext["interactions"];
+  readonly shell: SessionTurnContext["shell"];
+
+  private readonly abort_controller = new AbortController();
+  private readonly upstream_abort_signal?: AbortSignal;
+  private readonly abort_from_upstream: () => void;
+  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: SessionUserMessageV1[] = [];
+  private deferred_messages: SessionUserMessageV1[] = [];
+  private pending_assistant_parts: UIMessage["parts"] = [];
+
+  readonly lifecycle: SessionTurnContext["lifecycle"];
+  readonly step: SessionTurnContext["step"];
+  readonly input: SessionTurnContext["input"];
+  readonly output: SessionTurnContext["output"];
+
+  constructor(private readonly init: SessionTurnContextInit) {
+    const session_id = String(init.session_id || "").trim();
+    if (!session_id) {
+      throw new Error("SessionTurnContext requires a non-empty session_id");
+    }
+    const turn_id = String(init.turn_id || "").trim();
+    if (!turn_id) {
+      throw new Error("SessionTurnContext requires a non-empty turn_id");
+    }
+    const project_root = String(init.project_root || "").trim();
+    this.session = Object.freeze({
+      session_id,
+      turn_id,
+      ...(project_root ? { project_root } : {}),
+    });
+    this.interactions = init.interactions;
+    this.shell = Object.freeze({
+      ...(init.shell_approval_gateway
+        ? { approval_gateway: init.shell_approval_gateway }
+        : {}),
+    });
+
+    this.upstream_abort_signal = init.abort_signal;
+    this.abort_from_upstream = () => {
+      if (!this.abort_controller.signal.aborted) {
+        this.abort_controller.abort(this.upstream_abort_signal?.reason);
+      }
+    };
+    if (this.upstream_abort_signal?.aborted) {
+      this.abort_from_upstream();
+    } else {
+      this.upstream_abort_signal?.addEventListener(
+        "abort",
+        this.abort_from_upstream,
+        { once: true },
+      );
+    }
+
+    this.lifecycle = Object.freeze({
+      abort_signal: this.abort_controller.signal,
+      abort: (reason?: unknown) => {
+        if (!this.abort_controller.signal.aborted) {
+          this.abort_controller.abort(reason);
+        }
+      },
+      dispose: async () => await this.dispose(),
+    });
+
+    const context = this;
+    this.step = Object.freeze({
+      get workspace_env() {
+        return context.workspace_env_snapshot;
+      },
+      get agent_systems() {
+        return context.agent_systems_snapshot;
+      },
+      get plugins() {
+        return context.plugin_lease;
+      },
+      commit: (input) => {
+        context.workspace_env_snapshot = Object.freeze({
+          ...input.workspace_env,
+        });
+        context.agent_systems_snapshot = Object.freeze([
+          ...input.agent_systems,
+        ]);
+      },
+      replace_plugins: async (plugins) => {
+        const previous = context.plugin_lease;
+        context.plugin_lease = plugins;
+        if (previous && previous !== plugins) await previous.release();
+      },
+      release: async () => await context.release_plugins(),
+      plugin_execution_context: () =>
+        context.create_plugin_execution_context(),
+    });
+
+    this.input = Object.freeze({
+      checkpoint: async () => {
+        const injected = context.injected_user_messages;
+        context.injected_user_messages = [];
+        let queued: SessionUserMessageV1[] = [];
+        try {
+          queued = (await context.init.merge_step_input?.()) || [];
+        } catch {
+          queued = [];
+        }
+        return [...injected, ...queued];
+      },
+      has_pending: () => context.init.has_pending_step_input?.() === true,
+      inject_user_message: (message) => {
+        context.injected_user_messages.push(message);
+      },
+      defer_user_message: (message) => {
+        context.deferred_messages.push(message);
+      },
+      deferred_user_messages: () => Object.freeze([...context.deferred_messages]),
+      consume_history_reload: () =>
+        context.init.consume_history_reload?.() === true,
+    });
+
+    this.output = Object.freeze({
+      ...(init.assistant_output ? { assistant: init.assistant_output } : {}),
+      enqueue_assistant_parts: (parts) => {
+        context.pending_assistant_parts.push(...parts);
+      },
+      take_assistant_parts: () => {
+        const parts = context.pending_assistant_parts;
+        context.pending_assistant_parts = [];
+        return [...parts];
+      },
+      publish_action: async (event) => {
+        await context.init.publish_action?.(event);
+      },
+    });
+  }
+
+  /** 为 Plugin 生成不共享根对象引用的只读快照。 */
+  private create_plugin_execution_context(): PluginExecutionContext {
+    return Object.freeze({
+      session_id: this.session.session_id,
+      turn_id: this.session.turn_id,
+      ...(this.session.project_root
+        ? { project_root: this.session.project_root }
+        : {}),
+      ...(this.workspace_env_snapshot
+        ? { workspace_env: this.workspace_env_snapshot }
+        : {}),
+      agent_systems: this.agent_systems_snapshot,
+      abort_signal: this.abort_controller.signal,
+    });
+  }
+
+  /** 释放当前 Step 捕获的 Plugin lease。 */
+  private async release_plugins(): Promise<void> {
+    const plugins = this.plugin_lease;
+    this.plugin_lease = undefined;
+    await plugins?.release();
+  }
+
+  /** 闭合当前运行拥有的全部资源。 */
+  private async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.upstream_abort_signal?.removeEventListener(
+      "abort",
+      this.abort_from_upstream,
+    );
+    await this.release_plugins();
+  }
+}
+
+/** 创建一次由 Session Turn 拥有的统一执行上下文。 */
+export function create_session_turn_context(
+  init: SessionTurnContextInit,
+): SessionTurnContext {
+  return new DefaultSessionTurnContext(init);
+}
+
+/** 为非 Turn 的 system 查询创建 Plugin 可读取的 Session 快照。 */
+export function create_session_plugin_execution_context(
+  input: CreateSessionPluginExecutionContextInput,
+): PluginExecutionContext {
+  return Object.freeze({
+    session_id: input.session_id,
+    project_root: input.project_root,
+    workspace_env: Object.freeze({ ...input.workspace_env }),
+    agent_systems: Object.freeze([...input.agent_systems]),
+  });
+}

package/src/session/storage/Metadata.ts

@@ -2,53 +2,12 @@
  * SDK Session 元数据辅助。
  *
  * 关键点（中文）
- * - 统一负责 `.downcity/agents/<agentId>/sessions/<sessionId>/messages/meta.json` 的 SDK 字段读写。
+ * - 统一负责 `.downcity/agents/<agent_id>/sessions/<session_id>/messages/meta.json` 的规范化读取。
  * - 仅处理轻量配置摘要与索引信息，不负责消息 JSONL 的读写。
  */
 
-import fs from "fs-extra";
-import {
-  inferAgentModelLabel,
-  type AgentModel,
-} from "@/agent/AgentModel.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
-import { getSdkAgentSessionMetaPath } from "@/session/storage/Paths.js";
-import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
-
-/** 刷新 Session metadata 的参数。 */
-export interface TouchSessionMetadataParams {
-  /** 当前项目根目录。 */
-  projectRoot: string;
-  /** 当前 Agent 稳定标识。 */
-  agentId: string;
-  /** 当前 Session 稳定标识。 */
-  sessionId: string;
-  /** 当前 Session configured state。 */
-  sessionConfig: AgentSessionConfigSnapshot;
-  /** 当前 canonical Message 总数。 */
-  message_count?: number;
-  /** 当前 Message 日志总字节数。 */
-  history_bytes?: number;
-  /** 最近一条用户可见 Message 的文本摘要。 */
-  preview_text?: string;
-}
-
-type ReadSessionMetadataInput = {
-  /**
-   * 项目根目录。
-   */
-  projectRoot: string;
-
-  /**
-   * 当前 agentId。
-   */
-  agentId: string;
-
-  /**
-   * 当前 sessionId。
-   */
-  sessionId: string;
-};
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
 
 function normalizeModelLabel(input: unknown): string | undefined {
   const label = typeof input === "string" ? input.trim() : "";
@@ -58,7 +17,7 @@ function normalizeModelLabel(input: unknown): string | undefined {
 /**
  * 归一化 session 标题。
  */
-export function normalizeSessionTitle(input: unknown): string | undefined {
+export function normalize_session_title(input: unknown): string | undefined {
   const title = typeof input === "string" ? input.trim() : "";
   return title || undefined;
 }
@@ -66,7 +25,7 @@ export function normalizeSessionTitle(input: unknown): string | undefined {
 /**
  * 读取当前系统时区。
  */
-export function resolveSystemTimezone(): string {
+export function resolve_system_timezone(): string {
   const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
   return typeof timezone === "string" && timezone.trim()
     ? timezone.trim()
@@ -95,33 +54,6 @@ function normalize_history_bytes(input: unknown): number | undefined {
     : undefined;
 }
 
-/**
- * 从模型实例推导轻量可读标签。
- */
-export function inferModelLabel(
-  model: AgentModel | undefined,
-): string | undefined {
-  return inferAgentModelLabel(model);
-}
-
-/**
- * 读取当前 session 的 meta.json。
- */
-export async function readSessionMetadata(
-  input: ReadSessionMetadataInput,
-): Promise<SessionHistoryMetaV1> {
-  const filePath = getSdkAgentSessionMetaPath(
-    input.projectRoot,
-    input.agentId,
-    input.sessionId,
-  );
-  return await readSessionMetadataFromPath({
-    filePath,
-    sessionId: input.sessionId,
-    agentId: input.agentId,
-  });
-}
-
 /**
  * 从指定路径读取 session meta.json。
  *
@@ -129,140 +61,59 @@ export async function readSessionMetadata(
  * - 供归档 session 等需要脱离默认 `sessions/` 目录的场景复用。
  * - 路径本身不做校验，调用方需保证可访问。
  */
-export async function readSessionMetadataFromPath(input: {
+export async function read_session_metadata_from_path(input: {
   /** meta.json 文件路径。 */
   filePath: string;
-  /** 当前 sessionId。 */
-  sessionId: string;
-  /** 当前 agentId。 */
-  agentId: string;
+  /** 当前 session_id。 */
+  session_id: string;
+  /** 当前 agent_id。 */
+  agent_id: string;
+  /** 当前 Workspace 的统一文件能力。 */
+  files: FileSystem;
 }): Promise<SessionHistoryMetaV1> {
   try {
-    const raw = (await fs.readJson(input.filePath)) as Partial<SessionHistoryMetaV1>;
-    return {
-      v: 1,
-      sessionId: input.sessionId,
-      agentId: input.agentId,
-      createdAt:
-        typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
-          ? raw.createdAt
-          : Date.now(),
-      timezone: normalizeTimezone(raw.timezone) || resolveSystemTimezone(),
-      updatedAt:
-        typeof raw.updatedAt === "number" && Number.isFinite(raw.updatedAt)
-          ? raw.updatedAt
-          : 0,
-      ...(normalizeSessionTitle(raw.title)
-        ? { title: normalizeSessionTitle(raw.title) }
-        : {}),
-      ...(normalizeModelLabel(raw.modelLabel)
-        ? { modelLabel: normalizeModelLabel(raw.modelLabel) }
-        : {}),
-      ...(normalize_message_count(raw.messageCount) !== undefined
-        ? { messageCount: normalize_message_count(raw.messageCount) }
-        : {}),
-      ...(normalize_preview_text(raw.previewText)
-        ? { previewText: normalize_preview_text(raw.previewText) }
-        : {}),
-      ...(normalize_history_bytes(raw.historyBytes) !== undefined
-        ? { historyBytes: normalize_history_bytes(raw.historyBytes) }
-        : {}),
-    };
+    const raw = JSON.parse(
+      (await input.files.read_file(input.filePath)).toString("utf8"),
+    ) as Partial<SessionHistoryMetaV1>;
+    return normalize_session_metadata(raw, input.session_id, input.agent_id);
   } catch {
-    return {
-      v: 1,
-      sessionId: input.sessionId,
-      agentId: input.agentId,
-      createdAt: Date.now(),
-      timezone: resolveSystemTimezone(),
-      updatedAt: 0,
-    };
+    return normalize_session_metadata({}, input.session_id, input.agent_id);
   }
 }
 
-/**
- * 写回当前 session 的 meta.json。
- */
-export async function writeSessionMetadata(
-  input: ReadSessionMetadataInput & {
-    /**
-     * 下一份 meta 数据。
-     */
-    meta: SessionHistoryMetaV1;
-  },
-): Promise<void> {
-  const filePath = getSdkAgentSessionMetaPath(
-    input.projectRoot,
-    input.agentId,
-    input.sessionId,
-  );
-  await fs.ensureFile(filePath);
-  await fs.writeJson(filePath, input.meta, { spaces: 2 });
-}
-
-/**
- * 更新当前 session 的 SDK 配置摘要。
- */
-export async function patchSessionModelLabel(
-  input: ReadSessionMetadataInput & {
-    /**
-     * 当前模型实例。
-     */
-    model?: AgentModel;
-  },
-): Promise<SessionHistoryMetaV1> {
-  const current = await readSessionMetadata(input);
-  const modelLabel = inferModelLabel(input.model);
-  const next: SessionHistoryMetaV1 = {
-    ...current,
-    agentId: input.agentId,
-    createdAt:
-      typeof current.createdAt === "number" ? current.createdAt : Date.now(),
-    timezone: normalizeTimezone(current.timezone) || resolveSystemTimezone(),
-    updatedAt: Date.now(),
-    ...(modelLabel
-      ? {
-          modelLabel,
-        }
+/** 将未知 Metadata 内容规范化为当前 Session 的稳定结构。 */
+export function normalize_session_metadata(
+  raw: Partial<SessionHistoryMetaV1>,
+  session_id: string,
+  agent_id: string,
+): SessionHistoryMetaV1 {
+  return {
+    v: 1,
+    session_id: session_id,
+    agent_id: agent_id,
+    created_at:
+      typeof raw.created_at === "number" && Number.isFinite(raw.created_at)
+        ? raw.created_at
+        : Date.now(),
+    timezone: normalizeTimezone(raw.timezone) || resolve_system_timezone(),
+    updated_at:
+      typeof raw.updated_at === "number" && Number.isFinite(raw.updated_at)
+        ? raw.updated_at
+        : 0,
+    ...(normalize_session_title(raw.title)
+      ? { title: normalize_session_title(raw.title) }
       : {}),
-  };
-  await writeSessionMetadata({
-    ...input,
-    meta: next,
-  });
-  return next;
-}
-
-/** 根据 canonical Message 统计刷新当前 Session metadata。 */
-export async function touchSessionMetadata(
-  params: TouchSessionMetadataParams,
-): Promise<void> {
-  const current = await readSessionMetadata({
-    projectRoot: params.projectRoot,
-    agentId: params.agentId,
-    sessionId: params.sessionId,
-  });
-  const next: SessionHistoryMetaV1 = {
-    ...current,
-    agentId: params.agentId,
-    createdAt:
-      typeof current.createdAt === "number" ? current.createdAt : Date.now(),
-    updatedAt: Date.now(),
-    ...(params.sessionConfig.modelLabel
-      ? { modelLabel: params.sessionConfig.modelLabel }
+    ...(normalizeModelLabel(raw.model_label)
+      ? { model_label: normalizeModelLabel(raw.model_label) }
+      : {}),
+    ...(normalize_message_count(raw.message_count) !== undefined
+      ? { message_count: normalize_message_count(raw.message_count) }
       : {}),
-    ...(typeof params.message_count === "number"
-      ? { messageCount: params.message_count }
+    ...(normalize_preview_text(raw.preview_text)
+      ? { preview_text: normalize_preview_text(raw.preview_text) }
       : {}),
-    ...(typeof params.history_bytes === "number"
-      ? { historyBytes: params.history_bytes }
+    ...(normalize_history_bytes(raw.historyBytes) !== undefined
+      ? { historyBytes: normalize_history_bytes(raw.historyBytes) }
       : {}),
-    ...(params.preview_text ? { previewText: params.preview_text } : {}),
   };
-  await writeSessionMetadata({
-    projectRoot: params.projectRoot,
-    agentId: params.agentId,
-    sessionId: params.sessionId,
-    meta: next,
-  });
 }