@downcity/agent 1.1.1

package/src/session/Session.ts

@@ -0,0 +1,237 @@
+/**
+ * Session：单个会话实例。
+ *
+ * 关键点（中文）
+ * - 一个 Session 只对应一个固定的 `sessionId`。
+ * - 对外直接暴露 `run / appendUserMessage / appendAssistantMessage / getExecutor / getHistoryComposer`。
+ * - 运行态（如 executing）直接收在实例内部，不再拆 `Facade / Runner / ExecutionRegistry`。
+ */
+
+import { SessionHistoryWriter } from "@session/composer/history/SessionHistoryWriter.js";
+import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
+import { withSessionRunScope } from "@session/SessionRunScope.js";
+import type { SessionRunScope } from "@session/SessionRunScope.js";
+import { buildSessionStepEventMessages } from "@session/messages/SessionStepEventMapper.js";
+import type { JsonObject } from "@/shared/types/Json.js";
+import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
+import type { SessionExecutor } from "@/types/session/SessionExecutor.js";
+import type { SessionRunResult } from "@/types/session/SessionRun.js";
+
+type SessionOptions = {
+  /**
+   * 当前会话 ID。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 对应的 history Composer。
+   */
+  historyComposer: SessionHistoryComposer;
+
+  /**
+   * 创建当前 session 对应的执行器。
+   */
+  createExecutor: (historyComposer: SessionHistoryComposer) => SessionExecutor;
+
+  /**
+   * session 更新后的异步回调。
+   */
+  runAfterSessionUpdated?: (sessionId: string) => Promise<void>;
+};
+
+/**
+ * Session 单实例实现。
+ */
+export class Session {
+  /**
+   * 当前 session 标识。
+   */
+  readonly sessionId: string;
+
+  private readonly historyComposer: SessionHistoryComposer;
+  private readonly createExecutor: SessionOptions["createExecutor"];
+  private readonly historyWriter: SessionHistoryWriter;
+
+  private executor: SessionExecutor | null = null;
+  private executing = false;
+
+  constructor(options: SessionOptions) {
+    const sessionId = String(options.sessionId || "").trim();
+    if (!sessionId) {
+      throw new Error("Session requires a non-empty sessionId");
+    }
+
+    this.sessionId = sessionId;
+    this.historyComposer = options.historyComposer;
+    this.createExecutor = options.createExecutor;
+    this.historyWriter = new SessionHistoryWriter({
+      sessionId,
+      getHistoryComposer: () => this.getHistoryComposer(),
+      runAfterSessionUpdated: options.runAfterSessionUpdated,
+    });
+  }
+
+  /**
+   * 返回当前 session 是否正在执行。
+   */
+  isExecuting(): boolean {
+    return this.executing;
+  }
+
+  /**
+   * 获取当前 session 的 history Composer。
+   */
+  getHistoryComposer(): SessionHistoryComposer {
+    return this.historyComposer;
+  }
+
+  /**
+   * 获取当前 session 的执行器。
+   */
+  getExecutor(): SessionExecutor {
+    if (this.executor) return this.executor;
+    const created = this.createExecutor(this.getHistoryComposer());
+    this.executor = created;
+    return created;
+  }
+
+  /**
+   * 清理当前 session 的执行器缓存。
+   *
+   * 关键点（中文）
+   * - 这里只清 executor，不清 history Composer。
+   * - history 是事实源，不应随着 executor 一起丢失。
+   */
+  clearExecutor(): void {
+    const current = this.executor;
+    this.executor = null;
+    
+  }
+
+  /**
+   * 触发 session 更新后的异步回调。
+   */
+  async afterSessionUpdatedAsync(): Promise<void> {
+    await this.historyWriter.afterSessionUpdatedAsync();
+  }
+
+  /**
+   * 追加一条 user 消息。
+   */
+  async appendUserMessage(params: {
+    message?: SessionMessageV1 | null;
+    text?: string;
+    extra?: JsonObject;
+  }): Promise<void> {
+    await this.historyWriter.appendUserMessage(params);
+  }
+
+  /**
+   * 追加一条 assistant 消息。
+   */
+  async appendAssistantMessage(params: {
+    message?: SessionMessageV1 | null;
+    fallbackText?: string;
+    extra?: JsonObject;
+  }): Promise<void> {
+    await this.historyWriter.appendAssistantMessage(params);
+  }
+
+  /**
+   * 运行当前 session 的一次请求。
+   *
+   * 关键点（中文）
+   * - 这里直接承接单个 Session 实例的一次 run 外层编排。
+   * - scope 绑定、assistant step 持久化、executing 状态都收在实例内部。
+   */
+  async run(params: {
+    query: string;
+    onStepCallback?: SessionRunScope["onStepCallback"];
+    onAssistantStepCallback?: SessionRunScope["onAssistantStepCallback"];
+  }): Promise<SessionRunResult> {
+    if (this.executing) {
+      // 关键点（中文）：同一个 Session 实例只允许一个活跃 run，
+      // 否则 step 回调、scope 与执行器状态都会互相污染。
+      throw new Error("Session.run does not support concurrent execution");
+    }
+    const query = String(params.query || "").trim();
+    const sessionRunScope: Omit<SessionRunScope, "sessionId"> = {
+      ...(typeof params.onStepCallback === "function"
+        ? { onStepCallback: params.onStepCallback }
+        : {}),
+      ...(typeof params.onAssistantStepCallback === "function"
+        ? { onAssistantStepCallback: params.onAssistantStepCallback }
+        : {}),
+    };
+    let persistedAssistantStepCount = 0;
+    const providedOnAssistantStepCallback =
+      sessionRunScope.onAssistantStepCallback;
+
+    const wrappedOnAssistantStepCallback = async (step: {
+      text: string;
+      stepIndex: number;
+      visibility?: "visible" | "internal";
+      stepResult?: unknown;
+    }): Promise<void> => {
+      const stepMessages = buildSessionStepEventMessages({
+        sessionId: this.sessionId,
+        stepIndex: step.stepIndex,
+        stepResult: step.stepResult,
+        text: step.text,
+        visibility: step.visibility,
+      });
+      if (stepMessages.length > 0) {
+        for (const stepMessage of stepMessages) {
+          await this.appendAssistantMessage({
+            message: stepMessage,
+          });
+          persistedAssistantStepCount += 1;
+        }
+      }
+
+      if (typeof providedOnAssistantStepCallback === "function") {
+        await providedOnAssistantStepCallback(step);
+      }
+    };
+
+    this.executing = true;
+    try {
+      const result = await withSessionRunScope(
+        {
+          sessionId: this.sessionId,
+          ...sessionRunScope,
+          onAssistantStepCallback: wrappedOnAssistantStepCallback,
+        },
+        () => this.getExecutor().run({ query }),
+      );
+      if (persistedAssistantStepCount <= 0) return result;
+
+      return {
+        ...result,
+        assistantMessage: {
+          ...result.assistantMessage,
+          metadata: {
+            ...(result.assistantMessage.metadata || {
+              v: 1 as const,
+              ts: Date.now(),
+              sessionId: this.sessionId,
+            }),
+            extra: {
+              ...(
+                result.assistantMessage.metadata?.extra &&
+                  typeof result.assistantMessage.metadata.extra === "object" &&
+                  !Array.isArray(result.assistantMessage.metadata.extra)
+                  ? result.assistantMessage.metadata.extra
+                  : {}
+              ),
+              assistantStepMessagesPersisted: true,
+              assistantStepCount: persistedAssistantStepCount,
+            },
+          },
+        },
+      };
+    } finally {
+      this.executing = false;
+    }
+  }
+}

package/src/session/SessionRunScope.ts

@@ -0,0 +1,134 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { SessionUserMessageV1 } from "@/types/session/SessionMessages.js";
+import type { SessionAssistantStepCallback } from "@/types/session/SessionRun.js";
+
+/**
+ * SessionRunScope（单次请求作用域）。
+ *
+ * 关键点（中文）
+ * - 这是 session run 层请求作用域上下文，不属于具体 service 模块。
+ * - 统一承载请求链需要透传的字段（如 `sessionId`）。
+ */
+export type SessionRunScope = {
+  sessionId?: string;
+  /**
+   * step 边界合并回调（可选）。
+   *
+   * 关键点（中文）
+   * - 由调用侧（如 chat queue）注入。
+   * - Orchestrator 从 SessionRunScope 读取并编排到本轮运行上下文。
+   */
+  onStepCallback?: () => Promise<SessionUserMessageV1[]>;
+
+  /**
+   * assistant step 完成回调（可选）。
+   *
+   * 关键点（中文）
+   * - 在每个 LLM step 结束时触发。
+   * - 用于把中间文本增量派发到外部通道（如 direct 模式分步发送）。
+   */
+  onAssistantStepCallback?: SessionAssistantStepCallback;
+
+  /**
+   * 运行时注入的 user 消息队列（可选）。
+   *
+   * 关键点（中文）
+   * - 用于在 tool 执行后向下一 step 注入结构化 user 消息。
+   * - 队列内容由 service 侧通过统一协议下发，main 不感知业务语义。
+   */
+  injectedUserMessages?: SessionUserMessageV1[];
+};
+
+/**
+ * AsyncLocalStorage 容器（请求作用域）。
+ *
+ * 关键点（中文）
+ * - 同一条异步调用链内可读取一致的 SessionRunScope。
+ * - 用于把 `sessionId` 从入口透传到 service 与工具层。
+ */
+export const sessionRunScopeStorage = new AsyncLocalStorage<SessionRunScope>();
+
+/**
+ * 待持久化的运行时注入 user 消息队列（按 sessionId）。
+ *
+ * 关键点（中文）
+ * - sessionRunScopeStorage 中的 injectedUserMessages 只负责“下一 step 临时可见”。
+ * - 为了让时间线顺序稳定，这里把“真正写入历史”的动作延后到
+ *   assistant message 落盘之后再统一执行。
+ */
+const deferredPersistedUserMessagesBySession = new Map<
+  string,
+  SessionUserMessageV1[]
+>();
+
+/**
+ * 在当前异步调用链内绑定 session run 作用域。
+ */
+export function withSessionRunScope<T>(ctx: SessionRunScope, fn: () => T): T {
+  return sessionRunScopeStorage.run(ctx, fn);
+}
+
+/**
+ * 读取当前异步链路上的 session run 作用域。
+ */
+export function getSessionRunScope(): SessionRunScope | undefined {
+  return sessionRunScopeStorage.getStore();
+}
+
+/**
+ * 入队一条“待注入 user 消息”。
+ *
+ * 关键点（中文）
+ * - 若当前不在 session run 作用域内，静默忽略（fail-open）。
+ */
+export function enqueueInjectedUserMessage(
+  message: SessionUserMessageV1,
+): void {
+  const store = sessionRunScopeStorage.getStore();
+  if (!store || !message) return;
+  if (!Array.isArray(store.injectedUserMessages)) {
+    store.injectedUserMessages = [];
+  }
+  store.injectedUserMessages.push(message);
+}
+
+/**
+ * 读取并清空“待注入 user 消息”队列。
+ *
+ * 关键点（中文）
+ * - 采用 drain 语义，确保每条注入消息只在下一 step 使用一次。
+ */
+export function drainInjectedUserMessages(): SessionUserMessageV1[] {
+  const store = sessionRunScopeStorage.getStore();
+  if (!store || !Array.isArray(store.injectedUserMessages)) return [];
+  const out = [...store.injectedUserMessages];
+  store.injectedUserMessages = [];
+  return out;
+}
+
+/**
+ * 入队一条“待持久化 user 消息”。
+ */
+export function enqueueDeferredPersistedUserMessage(
+  sessionId: string,
+  message: SessionUserMessageV1,
+): void {
+  const key = String(sessionId || "").trim();
+  if (!key || !message) return;
+  const current = deferredPersistedUserMessagesBySession.get(key) || [];
+  current.push(message);
+  deferredPersistedUserMessagesBySession.set(key, current);
+}
+
+/**
+ * 读取并清空指定 session 的待持久化 user 消息。
+ */
+export function drainDeferredPersistedUserMessages(
+  sessionId: string,
+): SessionUserMessageV1[] {
+  const key = String(sessionId || "").trim();
+  if (!key) return [];
+  const current = deferredPersistedUserMessagesBySession.get(key) || [];
+  deferredPersistedUserMessagesBySession.delete(key);
+  return [...current];
+}

package/src/session/composer/SessionComposer.ts

@@ -0,0 +1,34 @@
+/**
+ * SessionComposer：Session Composer 层的最小公共基类。
+ *
+ * 关键点（中文）
+ * - 这里只提供统一的生命周期壳，不承载具体业务语义。
+ * - 具体职责必须由子类自己表达，例如 HistoryStore / CompactionPolicy / SystemResolver / ExecutionComposer。
+ */
+export abstract class SessionComposer {
+  /**
+   * Composer 名称（用于日志与诊断）。
+   */
+  abstract readonly name: string;
+
+  /**
+   * 可选初始化钩子。
+   *
+   * 关键点（中文）
+   * - LocalSessionExecutor 启动时可统一调用。
+   * - 无需初始化的 Composer 可不实现。
+   */
+  async init(): Promise<void> {
+    // no-op
+  }
+
+  /**
+   * 可选释放钩子。
+   *
+   * 关键点（中文）
+   * - Session 运行时关停时统一释放资源（连接、句柄、缓存等）。
+   */
+  async dispose(): Promise<void> {
+    // no-op
+  }
+}

package/src/session/composer/compaction/SessionCompactionComposer.ts

@@ -0,0 +1,68 @@
+/**
+ * SessionCompactionComposer：上下文压缩 Composer 抽象。
+ *
+ * 关键点（中文）
+ * - 负责“何时压缩 + 压缩策略参数”决策。
+ * - 具体读写由 SessionHistoryComposer 执行（CompactionComposer 不直接落盘）。
+ */
+
+import type { LanguageModel, SystemModelMessage } from "ai";
+import { SessionComposer } from "@session/composer/SessionComposer.js";
+import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
+
+/**
+ * compaction Composer 执行输入。
+ */
+export type SessionCompactionInput = {
+  /**
+   * 当前会话 history Composer。
+   */
+  historyComposer: SessionHistoryComposer;
+
+  /**
+   * 当前模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前轮 system messages。
+   */
+  system: SystemModelMessage[];
+
+  /**
+   * 当前重试次数（由 LocalSessionCore 递增）。
+   */
+  retryCount: number;
+};
+
+/**
+ * Compaction Composer 抽象类。
+ */
+export abstract class SessionCompactionComposer extends SessionComposer {
+  /**
+   * Composer 名（由具体实现声明）。
+   */
+  abstract readonly name: string;
+
+  /**
+   * 执行 compact（best-effort）。
+   */
+  abstract run(input: SessionCompactionInput): Promise<{
+    compacted: boolean;
+    reason?: string;
+  }>;
+
+  /**
+   * 判断某次执行错误是否应该触发“压缩后重试”。
+   *
+   * 关键点（中文）
+   * - 由 compaction Composer 实现侧维护错误识别策略。
+   * - LocalSessionCore 不感知具体错误文案，只按该布尔结果决定是否重试。
+   */
+  abstract shouldCompactOnError(error: unknown): boolean;
+
+  /**
+   * 可选初始化钩子。
+   */
+  // 生命周期沿用 SessionComposer 默认实现。
+}

package/src/session/composer/compaction/jsonl/JsonlSessionCompactionComposer.ts

@@ -0,0 +1,100 @@
+/**
+ * JsonlSessionCompactionComposer：默认上下文压缩 Composer。
+ *
+ * 关键点（中文）
+ * - 只负责压缩参数策略（retry 越多，窗口越紧）。
+ * - 真正的读写与 compact 执行交由 history Composer。
+ */
+
+import type { SessionCompactionInput } from "@session/composer/compaction/SessionCompactionComposer.js";
+import { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
+
+type JsonlSessionCompactionComposerOptions = {
+  keepLastMessages?: number;
+  maxInputTokensApprox?: number;
+  archiveOnCompact?: boolean;
+  compactRatio?: number;
+};
+
+/**
+ * JsonlSessionCompactionComposer 默认实现。
+ */
+export class JsonlSessionCompactionComposer extends SessionCompactionComposer {
+  readonly name = "summary_compaction_composer";
+  private readonly options: JsonlSessionCompactionComposerOptions;
+
+  constructor(options?: JsonlSessionCompactionComposerOptions) {
+    super();
+    this.options = options || {};
+  }
+
+  private resolvePolicy(retryCount: number): {
+    keepLastMessages: number;
+    maxInputTokensApprox: number;
+    archiveOnCompact: boolean;
+    compactRatio: number;
+  } {
+    const baseKeepLastMessages =
+      typeof this.options.keepLastMessages === "number"
+        ? Math.max(6, Math.min(5000, Math.floor(this.options.keepLastMessages)))
+        : 30;
+    const baseMaxInputTokensApprox =
+      typeof this.options.maxInputTokensApprox === "number"
+        ? Math.max(2000, Math.min(200_000, Math.floor(this.options.maxInputTokensApprox)))
+        : 128000;
+    const retryFactor = Math.max(1, Math.pow(2, retryCount));
+    const keepLastMessages = Math.max(6, Math.floor(baseKeepLastMessages / retryFactor));
+    const maxInputTokensApprox = Math.max(
+      2000,
+      Math.floor(baseMaxInputTokensApprox / retryFactor),
+    );
+    const archiveOnCompact =
+      this.options.archiveOnCompact === undefined
+        ? true
+        : Boolean(this.options.archiveOnCompact);
+    const compactRatioRaw =
+      typeof this.options.compactRatio === "number" &&
+      Number.isFinite(this.options.compactRatio)
+        ? this.options.compactRatio
+        : 0.5;
+    const compactRatio = Math.max(0.1, Math.min(0.9, compactRatioRaw));
+    return {
+      keepLastMessages,
+      maxInputTokensApprox,
+      archiveOnCompact,
+      compactRatio,
+    };
+  }
+
+  async run(input: SessionCompactionInput): Promise<{
+    compacted: boolean;
+    reason?: string;
+  }> {
+    const policy = this.resolvePolicy(input.retryCount);
+    return await input.historyComposer.compact({
+      model: input.model,
+      system: input.system,
+      keepLastMessages: policy.keepLastMessages,
+      maxInputTokensApprox: policy.maxInputTokensApprox,
+      archiveOnCompact: policy.archiveOnCompact,
+      compactRatio: policy.compactRatio,
+    });
+  }
+
+  /**
+   * 判断错误是否属于“应先 compact 再重试”的类型。
+   *
+   * 关键点（中文）
+   * - 当前实现基于主流模型 provider 的超限关键词。
+   * - 后续若接入新 provider，可在此处统一扩展识别规则。
+   */
+  shouldCompactOnError(error: unknown): boolean {
+    const errorMsg = String(error ?? "");
+    return (
+      errorMsg.includes("context_length") ||
+      errorMsg.includes("too long") ||
+      errorMsg.includes("maximum context") ||
+      errorMsg.includes("context window")
+    );
+  }
+}