@downcity/agent 1.1.14 → 1.1.17

package/src/session/store/history/SessionHistoryStore.ts

@@ -0,0 +1,145 @@
+/**
+ * SessionHistoryStore：会话历史事实源接口。
+ *
+ * 关键点（中文）
+ * - Store 负责消息、meta、archive、lock 等持久化能力。
+ * - Composer 只负责把 Store 中的历史组装成本轮模型输入。
+ * - 这个接口刻意独立于 Composer，避免把“落盘事实源”误当成“组装策略”。
+ */
+
+import type { LanguageModel } from "ai";
+import type {
+  SessionMessageV1,
+  SessionMetadataV1,
+} from "@/session/types/SessionMessages.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
+
+/**
+ * compact 输入参数。
+ */
+export type SessionHistoryCompactInput = {
+  /**
+   * 当前模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 当前轮 system messages。
+   */
+  system: SessionSystemMessage[];
+
+  /**
+   * 保留最近消息条数。
+   */
+  keepLastMessages: number;
+
+  /**
+   * 输入 token 近似上限。
+   */
+  maxInputTokensApprox: number;
+
+  /**
+   * compact 时是否归档旧消息。
+   */
+  archiveOnCompact: boolean;
+
+  /**
+   * 前段压缩比例（0-1）。
+   */
+  compactRatio: number;
+};
+
+/**
+ * 会话历史事实源。
+ */
+export interface SessionHistoryStore {
+  /**
+   * 当前会话 ID。
+   */
+  readonly sessionId: string;
+
+  /**
+   * 追加一条消息到历史。
+   */
+  append(message: SessionMessageV1): Promise<void>;
+
+  /**
+   * 读取完整消息历史。
+   */
+  list(): Promise<SessionMessageV1[]>;
+
+  /**
+   * 读取消息区间 [start, end)。
+   */
+  slice(start: number, end: number): Promise<SessionMessageV1[]>;
+
+  /**
+   * 读取消息总条数。
+   */
+  size(): Promise<number>;
+
+  /**
+   * 读取元信息。
+   */
+  meta(): Promise<Record<string, unknown>>;
+
+  /**
+   * 执行一次 compact（best-effort）。
+   */
+  compact(input: SessionHistoryCompactInput): Promise<{
+    compacted: boolean;
+    reason?: string;
+  }>;
+
+  /**
+   * 构造 user 文本消息。
+   */
+  userText(input: {
+    /**
+     * 用户文本内容。
+     */
+    text: string;
+
+    /**
+     * 消息元信息（除 schema 字段）。
+     */
+    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+
+    /**
+     * 可选消息 ID（默认自动生成）。
+     */
+    id?: string;
+  }): SessionMessageV1;
+
+  /**
+   * 构造 assistant 文本消息。
+   */
+  assistantText(input: {
+    /**
+     * 助手文本内容。
+     */
+    text: string;
+
+    /**
+     * 消息元信息（除 schema 字段）。
+     */
+    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+
+    /**
+     * 可选消息 ID（默认自动生成）。
+     */
+    id?: string;
+
+    /**
+     * 消息种类（普通/摘要）。
+     */
+    kind?: "normal" | "summary";
+
+    /**
+     * 消息来源（egress/compact）。
+     */
+    source?: "egress" | "compact";
+  }): SessionMessageV1;
+}

package/src/session/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -0,0 +1,465 @@
+/**
+ * JsonlSessionHistoryStore：基于 JSONL 的 session history 事实源。
+ *
+ * 关键点（中文）
+ * - 负责 `.downcity/.../messages/messages.jsonl`、`meta.json`、archive 与文件锁。
+ * - append 与 compact 共用同一把文件锁，避免并发覆盖。
+ * - 不负责为模型组装 messages；组装逻辑放在 `JsonlSessionHistoryComposer`。
+ */
+
+import fs from "fs-extra";
+import {
+  open as openFile,
+  readFile as readFileNative,
+  stat as statNative,
+} from "node:fs/promises";
+import path from "node:path";
+import { generateId } from "@/utils/Id.js";
+import { getLogger } from "@/utils/logger/Logger.js";
+import { compactSessionMessagesIfNeeded } from "@session/composer/compaction/jsonl/JsonlSessionCompactionExecutor.js";
+import type {
+  SessionMessageV1,
+  SessionMetadataV1,
+} from "@/session/types/SessionMessages.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
+import type { SessionHistoryMetaV1 } from "@/session/types/SessionHistoryMeta.js";
+import type { SessionHistoryPathOverrides } from "@/session/types/SessionHistoryPaths.js";
+import type {
+  SessionHistoryCompactInput,
+  SessionHistoryStore,
+} from "@/session/store/history/SessionHistoryStore.js";
+
+/**
+ * JSONL history store 构造参数。
+ */
+export type JsonlSessionHistoryStoreOptions = {
+  /**
+   * 当前项目根目录。
+   */
+  rootPath: string;
+  /**
+   * 当前 sessionId。
+   */
+  sessionId?: string;
+  /**
+   * 可选路径覆盖，供 SDK session / task run 复用同一 JSONL store。
+   */
+  paths?: SessionHistoryPathOverrides;
+};
+
+function getDowncityDirPath(rootPath: string): string {
+  return path.join(rootPath, ".downcity");
+}
+
+function getDowncitySessionRootDirPath(rootPath: string): string {
+  return path.join(getDowncityDirPath(rootPath), "session");
+}
+
+function getDowncitySessionDirPath(rootPath: string, sessionId: string): string {
+  return path.join(
+    getDowncitySessionRootDirPath(rootPath),
+    encodeURIComponent(sessionId),
+  );
+}
+
+function getDowncitySessionMessagesDirPath(
+  rootPath: string,
+  sessionId: string,
+): string {
+  return path.join(getDowncitySessionDirPath(rootPath, sessionId), "messages");
+}
+
+/**
+ * JSONL Session history store。
+ */
+export class JsonlSessionHistoryStore implements SessionHistoryStore {
+  readonly sessionId: string;
+
+  private readonly rootPath: string;
+  private readonly overrideSessionDirPath?: string;
+  private readonly overrideMessagesDirPath?: string;
+  private readonly overrideMessagesFilePath?: string;
+  private readonly overrideMetaFilePath?: string;
+  private readonly overrideArchiveDirPath?: string;
+
+  constructor(options: JsonlSessionHistoryStoreOptions) {
+    const rootPath = String(options.rootPath || "").trim();
+    if (!rootPath) {
+      throw new Error("JsonlSessionHistoryStore requires a non-empty rootPath");
+    }
+    const sessionId = String(options.sessionId || "").trim();
+    if (!sessionId) {
+      throw new Error("JsonlSessionHistoryStore requires a non-empty sessionId");
+    }
+
+    this.rootPath = rootPath;
+    this.sessionId = sessionId;
+    this.overrideSessionDirPath = this.readOptionalPath(
+      options.paths?.sessionDirPath,
+    );
+    this.overrideMessagesDirPath = this.readOptionalPath(
+      options.paths?.messagesDirPath,
+    );
+    this.overrideMessagesFilePath = this.readOptionalPath(
+      options.paths?.messagesFilePath,
+    );
+    this.overrideMetaFilePath = this.readOptionalPath(
+      options.paths?.metaFilePath,
+    );
+    this.overrideArchiveDirPath = this.readOptionalPath(
+      options.paths?.archiveDirPath,
+    );
+  }
+
+  private readOptionalPath(value: string | undefined): string | undefined {
+    const out = String(value || "").trim();
+    return out || undefined;
+  }
+
+  private getMessagesDirPath(): string {
+    if (this.overrideMessagesDirPath) return this.overrideMessagesDirPath;
+    if (this.overrideSessionDirPath) {
+      return path.join(this.overrideSessionDirPath, "messages");
+    }
+    return getDowncitySessionMessagesDirPath(this.rootPath, this.sessionId);
+  }
+
+  private getMessagesFilePath(): string {
+    if (this.overrideMessagesFilePath) return this.overrideMessagesFilePath;
+    if (this.overrideMessagesDirPath) {
+      return path.join(this.overrideMessagesDirPath, "messages.jsonl");
+    }
+    return path.join(this.getMessagesDirPath(), "messages.jsonl");
+  }
+
+  private getMetaFilePath(): string {
+    if (this.overrideMetaFilePath) return this.overrideMetaFilePath;
+    if (this.overrideMessagesDirPath) {
+      return path.join(this.overrideMessagesDirPath, "meta.json");
+    }
+    return path.join(this.getMessagesDirPath(), "meta.json");
+  }
+
+  private getArchiveDirPath(): string {
+    if (this.overrideArchiveDirPath) return this.overrideArchiveDirPath;
+    if (this.overrideMessagesDirPath) {
+      return path.join(this.overrideMessagesDirPath, "archive");
+    }
+    return path.join(this.getMessagesDirPath(), "archive");
+  }
+
+  private getLockFilePath(): string {
+    return path.join(this.getMessagesDirPath(), ".session.lock");
+  }
+
+  private async ensureLayout(): Promise<void> {
+    // 关键点（中文）：以 messages 目录为最小落盘单元，统一保证 messages/meta/archive 可写。
+    await fs.ensureDir(this.getMessagesDirPath());
+    await fs.ensureDir(this.getArchiveDirPath());
+    await fs.ensureFile(this.getMessagesFilePath());
+  }
+
+  private normalizePinnedSkillIds(input: string[] | undefined): string[] {
+    if (!Array.isArray(input)) return [];
+    const out: string[] = [];
+    for (const raw of input) {
+      const id = typeof raw === "string" ? raw.trim() : "";
+      if (!id) continue;
+      out.push(id);
+    }
+    return Array.from(new Set(out)).slice(0, 2000);
+  }
+
+  private normalizeSdkConfig(
+    input: SessionHistoryMetaV1["sdkConfig"],
+  ): SessionHistoryMetaV1["sdkConfig"] {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return undefined;
+    }
+    const modelLabel =
+      typeof input.modelLabel === "string" ? input.modelLabel.trim() : "";
+    if (!modelLabel) return undefined;
+    return {
+      modelLabel,
+    };
+  }
+
+  private async readMetaUnsafe(): Promise<SessionHistoryMetaV1> {
+    const file = this.getMetaFilePath();
+    try {
+      const raw = (await fs.readJson(
+        file,
+      )) as Partial<SessionHistoryMetaV1> | null;
+      if (!raw || typeof raw !== "object") throw new Error("invalid_meta");
+      return {
+        v: 1,
+        sessionId: this.sessionId,
+        ...(typeof raw.agentId === "string" && raw.agentId.trim()
+          ? { agentId: raw.agentId.trim() }
+          : {}),
+        ...(typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
+          ? { createdAt: raw.createdAt }
+          : {}),
+        updatedAt: typeof raw.updatedAt === "number" ? raw.updatedAt : 0,
+        pinnedSkillIds: this.normalizePinnedSkillIds(raw.pinnedSkillIds),
+        ...(typeof raw.lastArchiveId === "string" && raw.lastArchiveId.trim()
+          ? { lastArchiveId: raw.lastArchiveId.trim() }
+          : {}),
+        ...(typeof raw.keepLastMessages === "number" &&
+        Number.isFinite(raw.keepLastMessages)
+          ? { keepLastMessages: raw.keepLastMessages }
+          : {}),
+        ...(typeof raw.maxInputTokensApprox === "number" &&
+        Number.isFinite(raw.maxInputTokensApprox)
+          ? { maxInputTokensApprox: raw.maxInputTokensApprox }
+          : {}),
+        ...(typeof raw.compactRatio === "number" && Number.isFinite(raw.compactRatio)
+          ? { compactRatio: raw.compactRatio }
+          : {}),
+        ...(this.normalizeSdkConfig(raw.sdkConfig)
+          ? { sdkConfig: this.normalizeSdkConfig(raw.sdkConfig) }
+          : {}),
+      };
+    } catch {
+      return {
+        v: 1,
+        sessionId: this.sessionId,
+        createdAt: Date.now(),
+        updatedAt: 0,
+        pinnedSkillIds: [],
+      };
+    }
+  }
+
+  private async writeMetaUnsafe(next: SessionHistoryMetaV1): Promise<void> {
+    const normalized: SessionHistoryMetaV1 = {
+      v: 1,
+      sessionId: this.sessionId,
+      ...(typeof next.agentId === "string" && next.agentId.trim()
+        ? { agentId: next.agentId.trim() }
+        : {}),
+      ...(typeof next.createdAt === "number" && Number.isFinite(next.createdAt)
+        ? { createdAt: next.createdAt }
+        : {}),
+      updatedAt:
+        typeof next.updatedAt === "number" ? next.updatedAt : Date.now(),
+      pinnedSkillIds: this.normalizePinnedSkillIds(next.pinnedSkillIds),
+      ...(typeof next.lastArchiveId === "string" && next.lastArchiveId.trim()
+        ? { lastArchiveId: next.lastArchiveId.trim() }
+        : {}),
+      ...(typeof next.keepLastMessages === "number" &&
+      Number.isFinite(next.keepLastMessages)
+        ? { keepLastMessages: next.keepLastMessages }
+        : {}),
+      ...(typeof next.maxInputTokensApprox === "number" &&
+      Number.isFinite(next.maxInputTokensApprox)
+        ? { maxInputTokensApprox: next.maxInputTokensApprox }
+        : {}),
+      ...(typeof next.compactRatio === "number" &&
+      Number.isFinite(next.compactRatio)
+        ? { compactRatio: next.compactRatio }
+        : {}),
+      ...(this.normalizeSdkConfig(next.sdkConfig)
+        ? { sdkConfig: this.normalizeSdkConfig(next.sdkConfig) }
+        : {}),
+    };
+    await fs.writeJson(this.getMetaFilePath(), normalized, { spaces: 2 });
+  }
+
+  private async withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+    await this.ensureLayout();
+    const lockPath = this.getLockFilePath();
+    const token = `${process.pid}:${Date.now()}:${generateId()}`;
+    const logger = getLogger(this.rootPath, "info");
+
+    // 关键点（中文）：append 与 compact 共用同一把文件锁，防止 rewrite 覆盖 append。
+    const staleMs = 30_000;
+    const start = Date.now();
+    while (true) {
+      try {
+        const fh = await openFile(lockPath, "wx");
+        await fh.writeFile(token, "utf8");
+        await fh.close();
+        break;
+      } catch (error) {
+        const err = error as NodeJS.ErrnoException;
+        if (err.code !== "EEXIST") throw err;
+        try {
+          const stat = await statNative(lockPath);
+          const age = Date.now() - stat.mtimeMs;
+          if (age > staleMs) {
+            await fs.remove(lockPath);
+            await logger.log("warn", "Removed stale session lock", {
+              sessionId: this.sessionId,
+              lockPath,
+              ageMs: age,
+            });
+            continue;
+          }
+        } catch {
+          // ignore
+        }
+        if (Date.now() - start > staleMs * 2) {
+          throw new Error(`Context lock timeout: ${lockPath}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 60));
+      }
+    }
+
+    try {
+      return await fn();
+    } finally {
+      try {
+        const current = await readFileNative(lockPath, "utf8");
+        if (String(current || "").trim() === token) {
+          await fs.remove(lockPath);
+        }
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  private normalizeSystem(system: SessionSystemMessage[]): SessionSystemMessage[] {
+    if (!Array.isArray(system)) return [];
+    return system.filter((item) => item && typeof item === "object");
+  }
+
+  async compact(input: SessionHistoryCompactInput): Promise<{
+    compacted: boolean;
+    reason?: string;
+  }> {
+    return await compactSessionMessagesIfNeeded(
+      {
+        rootPath: this.rootPath,
+        sessionId: this.sessionId,
+        withWriteLock: (fn) => this.withWriteLock(fn),
+        loadAll: () => this.list(),
+        createSummaryMessage: ({ text, sourceRange }) => ({
+          id: `a:${this.sessionId}:${generateId()}`,
+          role: "assistant",
+          metadata: {
+            v: 1,
+            ts: Date.now(),
+            sessionId: this.sessionId,
+            source: "compact",
+            kind: "summary",
+            ...(sourceRange ? { sourceRange } : {}),
+          },
+          parts: [{ type: "text", text: String(text ?? "") }],
+        }),
+        getArchiveDirPath: () => this.getArchiveDirPath(),
+        getMessagesFilePath: () => this.getMessagesFilePath(),
+        readMetaUnsafe: () => this.readMetaUnsafe(),
+        writeMetaUnsafe: (next) => this.writeMetaUnsafe(next),
+      },
+      {
+        model: input.model,
+        system: this.normalizeSystem(input.system),
+        keepLastMessages: input.keepLastMessages,
+        maxInputTokensApprox: input.maxInputTokensApprox,
+        archiveOnCompact: input.archiveOnCompact,
+        compactRatio: input.compactRatio,
+      },
+    );
+  }
+
+  async append(message: SessionMessageV1): Promise<void> {
+    await this.withWriteLock(async () => {
+      await fs.appendFile(
+        this.getMessagesFilePath(),
+        JSON.stringify(message) + "\n",
+        "utf8",
+      );
+    });
+  }
+
+  async list(): Promise<SessionMessageV1[]> {
+    await this.ensureLayout();
+    const file = this.getMessagesFilePath();
+    const raw = await fs.readFile(file, "utf8");
+    const lines = raw.split("\n").filter(Boolean);
+    const out: SessionMessageV1[] = [];
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line) as Partial<SessionMessageV1>;
+        if (!obj || typeof obj !== "object") continue;
+        const role = String(obj.role || "");
+        if (role !== "user" && role !== "assistant") continue;
+        if (!Array.isArray(obj.parts)) continue;
+        out.push(obj as SessionMessageV1);
+      } catch {
+        // ignore invalid lines
+      }
+    }
+    return out;
+  }
+
+  async slice(start: number, end: number): Promise<SessionMessageV1[]> {
+    const msgs = await this.list();
+    const startIndex = Math.max(0, Math.floor(start));
+    const endIndex = Math.max(startIndex, Math.floor(end));
+    return msgs.slice(startIndex, endIndex);
+  }
+
+  async size(): Promise<number> {
+    const msgs = await this.list();
+    return msgs.length;
+  }
+
+  async meta(): Promise<Record<string, unknown>> {
+    await this.ensureLayout();
+    const metadata = await this.readMetaUnsafe();
+    return (
+      metadata && typeof metadata === "object" ? { ...metadata } : {}
+    ) as Record<string, unknown>;
+  }
+
+  userText(input: {
+    text: string;
+    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+    id?: string;
+  }): SessionMessageV1 {
+    const { ts, ...metadata } = input.metadata;
+    const md: SessionMetadataV1 = {
+      v: 1,
+      ts: typeof ts === "number" ? ts : Date.now(),
+      ...metadata,
+      source: "ingress",
+      kind: "normal",
+    };
+    const id = input.id || `u:${this.sessionId}:${generateId()}`;
+    return {
+      id,
+      role: "user",
+      metadata: md,
+      parts: [{ type: "text", text: String(input.text ?? "") }],
+    };
+  }
+
+  assistantText(input: {
+    text: string;
+    metadata: Omit<SessionMetadataV1, "v" | "ts"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+    id?: string;
+    kind?: "normal" | "summary";
+    source?: "egress" | "compact";
+  }): SessionMessageV1 {
+    const { ts, ...metadata } = input.metadata;
+    const md: SessionMetadataV1 = {
+      v: 1,
+      ts: typeof ts === "number" ? ts : Date.now(),
+      ...metadata,
+      source: input.source || "egress",
+      kind: input.kind || "normal",
+    };
+    const id = input.id || `a:${this.sessionId}:${generateId()}`;
+    return {
+      id,
+      role: "assistant",
+      metadata: md,
+      parts: [{ type: "text", text: String(input.text ?? "") }],
+    };
+  }
+}

package/src/session/tools/shell/ShellToolFormatting.ts

@@ -6,7 +6,7 @@
  * - 这里仅保留当前仍被 tool 与测试复用的最小能力：命令安全校验与 env 注入。
  */
 
-import { stripInvocationAuthEnv } from "@/server/http/auth/AuthEnv.js";
+import { stripInvocationAuthEnv } from "@/runtime/server/http/auth/AuthEnv.js";
 import { getSessionRunScope } from "@session/SessionRunScope.js";
 
 function setEnvString(

package/src/session/types/SessionHistoryPaths.ts

@@ -1,8 +1,8 @@
 /**
- * JsonlSessionHistoryComposer 路径覆盖类型。
+ * JsonlSessionHistoryStore 路径覆盖类型。
  *
  * 关键点（中文）
- * - 用于把 history Composer 落盘路径定向到自定义目录（例如 task run 目录）。
+ * - 用于把 history Store 落盘路径定向到自定义目录（例如 task run 目录）。
  * - 每个字段都为可选，未提供时回退到默认 `.downcity/session/<encodedSessionId>/messages/*`。
  */
 export type SessionHistoryPathOverrides = {

package/src/session/types/SessionLoop.ts

@@ -1,5 +1,5 @@
 /**
- * Runner tool-loop 决策相关类型。
+ * Session tool-loop 决策相关类型。
  *
  * 关键点（中文）
  * - 这里只描述“是否继续下一轮”的纯决策输入/输出。

package/src/session/types/SessionMessages.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这里统一描述 session 消息落盘格式与元信息结构。
  * - session 的唯一事实源是 `UIMessage[]`，不会再维护第二套平行消息结构。
- * - 这些类型会被 history Composer、compact、control UI、task runtime 共同复用。
+ * - 这些类型会被 history Store、history Composer、compact、control UI、task runtime 共同复用。
  */
 
 import type { UIMessage } from "ai";

package/src/session/types/SessionRun.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - `SessionRunInput` 表示上层会话入口输入（例如 context query）。
- * - `SessionExecuteInput` 表示 Runner 通过 Composer 装配后的中间运行态。
+ * - `SessionExecuteInput` 表示 Executor 通过 Composer 装配后的中间运行态。
  * - 输出仅暴露 assistantMessage（UIMessage）。
  */
 
@@ -107,7 +107,7 @@ export interface SessionRunInput {
 }
 
 /**
- * Runner 通过 Composer 装配后的中间运行态。
+ * Executor 通过 Composer 装配后的中间运行态。
  */
 export interface SessionExecuteInput {
   /**

package/src/types/config/DowncityConfig.ts

@@ -8,7 +8,7 @@
 import type { LlmConfig } from "@/types/config/LlmConfig.js";
 import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SandboxProjectConfig } from "@/sandbox/types/Sandbox.js";
+import type { SandboxProjectConfig } from "@/runtime/sandbox/types/Sandbox.js";
 
 export interface DowncityConfig {
   $schema?: string;
@@ -143,8 +143,9 @@ export interface DowncityConfig {
    * LLM 全量配置（通常来自平台全局层合并结果）。
    *
    * 关键点（中文）
-   * - 运行时会读取该字段创建真实模型实例。
-   * - 对于项目内 `downcity.json`，通常不需要显式写该字段。
+   * - `@downcity/agent` 本地 SDK 不直接消费该字段。
+   * - 宿主侧（例如 `@downcity/city`）可读取该字段控制模型工厂行为，例如 `llm.logMessages`。
+   * - 对于项目内 `downcity.json`，通常不需要显式写 provider/model 明细。
    */
   llm?: LlmConfig;
   /**