@downcity/agent 1.1.237 → 1.1.258

package/src/executor/composer/history/jsonl/JsonlSessionHistoryComposer.ts

@@ -1,133 +0,0 @@
-/**
- * JsonlSessionHistoryComposer：基于 JSONL store 的 history 组装器。
- *
- * 关键点（中文）
- * - 只负责 `prepare()`，把 history store 中的消息组装成本轮模型输入。
- * - 不负责 append / list / meta / compact 等落盘能力。
- * - JSONL 文件事实源由 `JsonlSessionHistoryStore` 承担。
- */
-
-import type { Tool } from "ai";
-import {
-  is_session_action_record,
-  is_session_message_record,
-  type SessionRecordV1,
-  type SessionMessageRecordV1,
-} from "@/executor/types/SessionRecords.js";
-import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type {
-  SessionHistoryComposer,
-  SessionHistoryPrepareInput,
-} from "@executor/composer/history/SessionHistoryComposer.js";
-
-/**
- * JSONL history composer 构造参数。
- */
-export type JsonlSessionHistoryComposerOptions = {
-  /**
-   * 当前 history 事实源。
-   */
-  store: SessionHistoryStore;
-};
-
-/**
- * JSONL history composer。
- */
-export class JsonlSessionHistoryComposer implements SessionHistoryComposer {
-  readonly name = "jsonl_history_composer";
-  readonly sessionId: string;
-
-  private readonly store: SessionHistoryStore;
-
-  constructor(options: JsonlSessionHistoryComposerOptions) {
-    this.store = options.store;
-    this.sessionId = String(options.store?.sessionId || "").trim();
-    if (!this.sessionId) {
-      throw new Error("JsonlSessionHistoryComposer requires a non-empty sessionId");
-    }
-  }
-
-  private normalizeTools(tools: Record<string, Tool>): Record<string, Tool> {
-    return tools && typeof tools === "object" ? { ...tools } : {};
-  }
-
-  private readUserSessionMessageText(message: SessionMessageRecordV1): string {
-    if (!message || typeof message !== "object" || message.role !== "user") {
-      return "";
-    }
-    const parts = Array.isArray(message.parts) ? message.parts : [];
-    return parts
-      .map((part) => {
-        if (!part || typeof part !== "object") return "";
-        const candidate = part as { type?: unknown; text?: unknown };
-        if (candidate.type === "text" && typeof candidate.text === "string") {
-          return candidate.text;
-        }
-        return "";
-      })
-      .join("\n")
-      .trim();
-  }
-
-  private hasTrailingUserQuery(
-    messages: SessionRecordV1[],
-    query: string,
-  ): boolean {
-    const target = String(query || "").trim();
-    if (!target) return true;
-    for (let index = messages.length - 1; index >= 0; index -= 1) {
-      const item = messages[index];
-      if (!item || typeof item !== "object") continue;
-      if (!is_session_message_record(item) || item.role !== "user") continue;
-      return this.readUserSessionMessageText(item) === target;
-    }
-    return false;
-  }
-
-  private sanitizeMessages(messages: SessionRecordV1[]): SessionRecordV1[] {
-    if (!Array.isArray(messages)) return [];
-    return messages
-      .filter((message) => !is_session_action_record(message))
-      .filter(is_session_message_record)
-      .map((message) => {
-        const parts = Array.isArray(message.parts)
-          ? message.parts.filter((part) => part && typeof part === "object")
-          : [];
-        return {
-          ...message,
-          parts,
-        };
-      })
-      .filter((message) => Array.isArray(message.parts) && message.parts.length > 0);
-  }
-
-  async prepare(input: SessionHistoryPrepareInput): Promise<SessionRecordV1[]> {
-    const query = String(input.query || "").trim();
-    const tools = this.normalizeTools(input.tools);
-    void tools;
-
-    let baseMessages = this.sanitizeMessages(await this.store.list_records());
-    if ((!Array.isArray(baseMessages) || baseMessages.length === 0) && query) {
-      baseMessages = [
-        this.store.userText({
-          text: query,
-          metadata: {
-            sessionId: this.sessionId,
-          },
-        }),
-      ];
-    }
-    if (query && !this.hasTrailingUserQuery(baseMessages, query)) {
-      baseMessages = [
-        ...baseMessages,
-        this.store.userText({
-          text: query,
-          metadata: {
-            sessionId: this.sessionId,
-          },
-        }),
-      ];
-    }
-    return baseMessages;
-  }
-}

package/src/executor/messages/AssistantResultPersistence.ts

@@ -1,106 +0,0 @@
-/**
- * AssistantResultPersistence：统一处理一次 run 结束后的 assistant 落盘决策。
- *
- * 关键点（中文）
- * - 负责收敛“写完整 assistant message / 写 fallback 文本 / 完全跳过”三种分支。
- * - 避免 SDK、HTTP execute、control execute、chat queue 各自复制一套判断。
- * - 运行中 step/tool 的持久化由 inflight 快照承担；run 结束时只关心最终 assistant 如何收口。
- */
-
-import type {
-  SessionRecordV1,
-  SessionMessageRecordV1,
-} from "@/executor/types/SessionRecords.js";
-import { resolveAssistantMessageForPersistence } from "@/executor/messages/UserVisibleText.js";
-
-/**
- * assistant 写入端口。
- */
-export interface AssistantResultPersistenceWriter {
-  /**
-   * 追加 assistant 消息。
-   */
-  append_assistant_message(params: {
-    /**
-     * 已构造好的完整 assistant 消息。
-     */
-    message?: SessionRecordV1 | null;
-    /**
-     * 在没有完整 message 可写时的兜底文本。
-     */
-    fallbackText?: string;
-  }): Promise<void>;
-}
-
-/**
- * 一次 run 结束后的 assistant 落盘参数。
- */
-export interface PersistAssistantResultParams {
-  /**
-   * assistant 写入端口。
-   */
-  writer: AssistantResultPersistenceWriter;
-  /**
-   * 本轮执行得到的 assistant message。
-   */
-  assistantMessage: SessionMessageRecordV1 | null | undefined;
-  /**
-   * 可选兜底文本。
-   *
-   * 关键点（中文）
-   * - 仅在没有完整 assistant message 时才允许写入。
-   * - inflight 快照的正式收口由 history store 负责，这里不再处理旧的 step 独立落盘分支。
-   */
-  fallbackText?: string;
-}
-
-function normalizeFallbackText(input: string | undefined): string | undefined {
-  const text = String(input || "").trim();
-  return text || undefined;
-}
-
-/**
- * 解析本轮 run 最终应该如何持久化 assistant。
- */
-export function buildAssistantResultPersistencePayload(
-  params: Omit<PersistAssistantResultParams, "writer">,
-): {
-  /**
-   * 已构造好的完整 assistant message。
-   */
-  message?: SessionMessageRecordV1 | null;
-  /**
-   * 允许写入的兜底文本。
-   */
-  fallbackText?: string;
-} | null {
-  const persistedMessage = resolveAssistantMessageForPersistence(
-    params.assistantMessage,
-  );
-  if (persistedMessage) {
-    return {
-      message: persistedMessage,
-    };
-  }
-
-  const fallbackText = normalizeFallbackText(params.fallbackText);
-  if (!fallbackText) return null;
-  return {
-    fallbackText,
-  };
-}
-
-/**
- * 按统一规则持久化一次 run 的 assistant 结果。
- */
-export async function persistAssistantResult(
-  params: PersistAssistantResultParams,
-): Promise<boolean> {
-  const payload = buildAssistantResultPersistencePayload({
-    assistantMessage: params.assistantMessage,
-    fallbackText: params.fallbackText,
-  });
-  if (!payload) return false;
-  await params.writer.append_assistant_message(payload);
-  return true;
-}

package/src/executor/services/ExecutorInflightService.ts

@@ -1,95 +0,0 @@
-/**
- * ExecutorInflightService：运行中 assistant 快照写入服务。
- *
- * 关键点（中文）
- * - 只负责把 step/tool 增量写入当前 inflight assistant 快照。
- * - 不负责长期 history 组装，不负责主执行循环。
- * - 保持与 SessionHistoryStore 的交互边界清晰，避免 Executor 自身同时承担编排与写入细节。
- */
-
-import { generateId } from "@/utils/Id.js";
-import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type { SessionMessageRecordV1 } from "@/executor/types/SessionRecords.js";
-import { is_session_message_record } from "@/executor/types/SessionRecords.js";
-
-interface ExecutorInflightServiceOptions {
-  /**
-   * 当前 session 标识。
-   */
-  session_id: string;
-
-  /**
-   * 当前 session 对应的 history 事实源。
-   */
-  history_store: SessionHistoryStore;
-
-}
-
-/**
- * 运行中 assistant 快照写入服务。
- */
-export class ExecutorInflightService {
-  private readonly session_id: string;
-  private readonly history_store: SessionHistoryStore;
-
-  constructor(options: ExecutorInflightServiceOptions) {
-    this.session_id = String(options.session_id || "").trim();
-    this.history_store = options.history_store;
-
-    if (!this.session_id) {
-      throw new Error("ExecutorInflightService requires a non-empty session_id");
-    }
-  }
-
-  /**
-   * 把 step/tool 过程增量写入当前运行中的 assistant 快照。
-   */
-  async append_assistant_step_parts(
-    parts: SessionMessageRecordV1["parts"],
-  ): Promise<void> {
-    const normalized_parts = Array.isArray(parts)
-      ? parts.filter((part) => part && typeof part === "object")
-      : [];
-    if (normalized_parts.length === 0) return;
-
-    const current_inflight = await this.history_store.read_inflight();
-    const normalized_inflight = is_session_message_record(current_inflight)
-      ? current_inflight
-      : null;
-    const next_message: SessionMessageRecordV1 = normalized_inflight
-      ? {
-          ...normalized_inflight,
-          metadata: {
-            ...(normalized_inflight.metadata || {
-              v: 1 as const,
-              ts: Date.now(),
-              sessionId: this.session_id,
-            }),
-            ts: Date.now(),
-            sessionId: this.session_id,
-            source: "egress",
-            kind: "normal",
-          },
-          parts: [
-            ...(Array.isArray(normalized_inflight.parts)
-              ? normalized_inflight.parts
-              : []),
-            ...normalized_parts,
-          ],
-        }
-      : {
-          id: `a:${this.session_id}:${generateId()}`,
-          role: "assistant",
-          metadata: {
-            v: 1,
-            ts: Date.now(),
-            sessionId: this.session_id,
-            source: "egress",
-            kind: "normal",
-          },
-          parts: normalized_parts,
-        };
-
-    await this.history_store.write_inflight(next_message);
-  }
-}

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

@@ -1,172 +0,0 @@
-/**
- * SessionHistoryStore：会话 record 事实源接口。
- *
- * 关键点（中文）
- * - Store 负责 records、meta、archive、lock 等持久化能力。
- * - Composer 只负责把 Store 中的模型消息 record 组装成本轮模型输入。
- * - 这个接口刻意独立于 Composer，避免把“落盘事实源”误当成“组装策略”。
- */
-
-import type { LanguageModel } from "ai";
-import type {
-  SessionActionRecordV1,
-  SessionRecordV1,
-  SessionMetadataV1,
-} from "@/executor/types/SessionRecords.js";
-import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
-
-/**
- * compact 输入参数。
- */
-export type SessionHistoryCompactInput = {
-  /**
-   * 当前模型实例。
-   */
-  model: LanguageModel;
-
-  /**
-   * 当前轮 system messages。
-   */
-  system: SessionSystemMessage[];
-
-  /**
-   * 是否明确要求本次执行持久化 deep compact。
-   *
-   * 真实 usage 触发与内存消息折叠由 CoreEngine 决定；Store 只负责归档已经完成的历史。
-   */
-  force?: boolean;
-
-  /**
-   * 可选 action 发布回调。
-   */
-  onAction?: (action: SessionActionRecordV1) => Promise<void>;
-};
-
-/**
- * 会话历史事实源。
- */
-export interface SessionHistoryStore {
-  /**
-   * 当前会话 ID。
-   */
-  readonly sessionId: string;
-
-  /**
-   * 写入一条 session record。
-   *
-   * 说明（中文）
-   * - 模型消息会追加到 JSONL。
-   * - action record 会按稳定 ID upsert 为同一条 record。
-   */
-  write_record(message: SessionRecordV1): Promise<void>;
-
-  /**
-   * 读取当前运行中的 assistant 快照。
-   */
-  read_inflight(): Promise<SessionRecordV1 | null>;
-
-  /**
-   * 写入当前运行中的 assistant 快照。
-   */
-  write_inflight(message: SessionRecordV1): Promise<void>;
-
-  /**
-   * 用最终 assistant 收口 inflight 快照。
-   */
-  finalize_inflight(message?: SessionRecordV1 | null): Promise<void>;
-
-  /** 读取当前模型上下文所需的 session records。 */
-  list_records(): Promise<SessionRecordV1[]>;
-
-  /** 读取当前模型上下文 record 区间 [start, end)。 */
-  slice_records(start: number, end: number): Promise<SessionRecordV1[]>;
-
-  /** 读取当前模型上下文 record 总条数。 */
-  record_count(): 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;
-  }): SessionRecordV1;
-
-  /**
-   * 构造 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";
-  }): SessionRecordV1;
-
-  /**
-   * 构造 action 消息。
-   */
-  action(input: {
-    /**
-     * 当前 action 结构化记录。
-     */
-    action: SessionActionRecordV1;
-
-    /**
-     * 消息元信息（除 schema 字段）。
-     */
-    metadata: Pick<SessionMetadataV1, "sessionId"> &
-      Partial<Pick<SessionMetadataV1, "ts">>;
-
-    /**
-     * 可选消息 ID（默认自动生成）。
-     */
-    id?: string;
-  }): SessionActionRecordV1;
-}