@downcity/city 1.1.1 → 1.1.4

package/src/session/Session.ts

@@ -1,237 +0,0 @@
-/**
- * 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

@@ -1,134 +0,0 @@
-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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,68 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-/**
- * 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")
-    );
-  }
-}