@downcity/agent 1.1.237 → 1.1.258

package/src/agent/local/services/AgentBackgroundService.ts

@@ -1,115 +0,0 @@
-/**
- * AgentBackgroundService：本地 Agent 后台能力生命周期服务。
- *
- * 关键点（中文）
- * - 统一管理 plugins 与 ActionSchedule 的启动 / 停止。
- * - 在 Agent 构造阶段自动启动后台能力，调用方通过 `await agent.ready()` 等待启动完成。
- * - RPC / HTTP 等 transport 不再属于 Agent 内部职责，由 `@downcity/server` 等外部包按需挂载。
- */
-
-import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { ActionScheduleRuntimeHandle } from "@/plugin/core/ActionScheduleRuntime.js";
-import { startActionScheduleRuntime } from "@/plugin/core/ActionScheduleRuntime.js";
-import type { Shell } from "@downcity/shell";
-
-type AgentBackgroundServiceOptions = {
-  /**
-   * 当前统一日志器。
-   */
-  logger: Logger;
-
-  /**
-   * 当前 agent context。
-   */
-  agent_context: AgentContext;
-
-  /**
-   * 读取当前 agent 挂载的 Shell。
-   */
-  get_shell?: () => Shell | undefined;
-};
-
-/**
- * 本地 Agent 后台能力生命周期服务。
- *
- * 关键点（中文）
- * - 构造时自动触发 plugin lifecycle 与 ActionSchedule 启动。
- * - 失败由 logger.error 记录，不抛错；调用方通过 `ready()` 等待启动完成。
- */
-export class AgentBackgroundService {
-  private readonly logger: Logger;
-  private readonly agent_context: AgentContext;
-  private readonly get_shell: AgentBackgroundServiceOptions["get_shell"];
-
-  private plugins_started = false;
-  private action_schedule_runtime: ActionScheduleRuntimeHandle | null = null;
-  private ready_promise: Promise<void> | null = null;
-
-  constructor(options: AgentBackgroundServiceOptions) {
-    this.logger = options.logger;
-    this.agent_context = options.agent_context;
-    this.get_shell = options.get_shell;
-    // 关键点（中文）：Agent 构造完成即触发后台启动，不再要求外部显式 `start()`。
-    this.ready_promise = this.boot();
-  }
-
-  /**
-   * 等待后台能力启动完成。
-   */
-  async ready(): Promise<void> {
-    if (!this.ready_promise) return;
-    await this.ready_promise;
-  }
-
-  /**
-   * 释放当前 Agent 的后台能力。
-   */
-  async dispose(): Promise<void> {
-    if (this.ready_promise) {
-      await this.ready_promise.catch(() => undefined);
-      this.ready_promise = null;
-    }
-    if (this.plugins_started) {
-      await this.stop_action_schedule_runtime();
-      await this.agent_context.plugins.unregisterAll();
-      this.plugins_started = false;
-    }
-    await this.get_shell?.()?.dispose();
-  }
-
-  private async boot(): Promise<void> {
-    await this.ensure_plugins_started();
-  }
-
-  private async ensure_plugins_started(): Promise<void> {
-    if (this.plugins_started) return;
-    const snapshots = await this.agent_context.plugins.startAll();
-    this.plugins_started = true;
-    for (const item of snapshots) {
-      if (item.status === "error") {
-        this.logger.error(
-          `Plugin start failed: ${item.name} - ${item.last_error || "unknown error"}`,
-        );
-      }
-    }
-    await this.ensure_action_schedule_runtime_started();
-  }
-
-  private async ensure_action_schedule_runtime_started(): Promise<void> {
-    if (this.action_schedule_runtime) return;
-    try {
-      this.action_schedule_runtime = await startActionScheduleRuntime(
-        this.agent_context,
-      );
-    } catch (error) {
-      this.logger.error(`ActionSchedule start failed: ${String(error)}`);
-    }
-  }
-
-  private async stop_action_schedule_runtime(): Promise<void> {
-    const runtime = this.action_schedule_runtime;
-    this.action_schedule_runtime = null;
-    runtime?.stop();
-  }
-}

package/src/executor/SessionRunScope.ts

@@ -1,122 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { FileUIPart } from "ai";
-import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
-import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
-
-/**
- * SessionRunScope（单次请求作用域）。
- *
- * 关键点（中文）
- * - 这是 session run 层请求作用域上下文，不属于具体 plugin 业务模块。
- * - 当前阶段仅作为深层工具回调读取 `runContext` 的薄包装。
- */
-export type SessionRunScope = {
-  /**
-   * 当前显式运行上下文。
-   */
-  runContext: SessionRunContext;
-};
-
-/**
- * AsyncLocalStorage 容器（请求作用域）。
- *
- * 关键点（中文）
- * - 同一条异步调用链内可读取一致的 SessionRunScope。
- * - 当前主要用于 tool 深层桥接层读取活跃 runContext。
- */
-export const sessionRunScopeStorage = new AsyncLocalStorage<SessionRunScope>();
-
-/**
- * 在当前异步调用链内绑定 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();
-}
-
-/**
- * 读取当前异步链路上的显式 runContext。
- */
-export function getSessionRunContext(): SessionRunContext | undefined {
-  return sessionRunScopeStorage.getStore()?.runContext;
-}
-
-/**
- * 入队一条“待注入 user 消息”。
- *
- * 关键点（中文）
- * - 若当前不在 session run 作用域内，静默忽略（fail-open）。
- */
-export function enqueueInjectedUserMessage(
-  message: SessionUserMessageV1,
-): void {
-  const run_context = getSessionRunContext();
-  if (!run_context || !message) return;
-  run_context.injectedUserMessages.push(message);
-}
-
-/**
- * 读取并清空“待注入 user 消息”队列。
- *
- * 关键点（中文）
- * - 采用 drain 语义，确保每条注入消息只在下一 step 使用一次。
- */
-export function drainInjectedUserMessages(): SessionUserMessageV1[] {
-  const run_context = getSessionRunContext();
-  if (!run_context) return [];
-  const out = [...run_context.injectedUserMessages];
-  run_context.injectedUserMessages = [];
-  return out;
-}
-
-/**
- * 入队一条“待持久化 user 消息”。
- */
-export function enqueueDeferredPersistedUserMessage(
-  sessionId: string,
-  message: SessionUserMessageV1,
-): void {
-  const run_context = getSessionRunContext();
-  const key = String(sessionId || "").trim();
-  if (!run_context || !key || !message) return;
-  if (run_context.sessionId !== key) return;
-  run_context.deferredPersistedUserMessages.push(message);
-}
-
-/**
- * 读取并清空指定 session 的待持久化 user 消息。
- */
-export function drainDeferredPersistedUserMessages(
-  sessionId: string,
-): SessionUserMessageV1[] {
-  const run_context = getSessionRunContext();
-  const key = String(sessionId || "").trim();
-  if (!run_context || !key || run_context.sessionId !== key) return [];
-  const current = [...run_context.deferredPersistedUserMessages];
-  run_context.deferredPersistedUserMessages = [];
-  return current;
-}
-
-/**
- * 入队一组“待并入 assistant 消息的 file parts”。
- */
-export function enqueueAssistantFileParts(parts: FileUIPart[]): void {
-  const run_context = getSessionRunContext();
-  if (!run_context || !Array.isArray(parts) || parts.length === 0) return;
-  run_context.pendingAssistantFileParts.push(...parts);
-}
-
-/**
- * 读取当前 run 内待并入 assistant 消息的 file parts。
- */
-export function readPendingAssistantFileParts(): FileUIPart[] {
-  const run_context = getSessionRunContext();
-  if (!run_context) return [];
-  return [...run_context.pendingAssistantFileParts];
-}

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

@@ -1,84 +0,0 @@
-/**
- * SessionCompactionComposer：上下文压缩 Composer 抽象。
- *
- * 关键点（中文）
- * - 负责“何时压缩 + 压缩策略参数”决策。
- * - 具体读写由 SessionHistoryStore 执行（CompactionComposer 不直接落盘）。
- */
-
-import type { LanguageModel, SystemModelMessage } from "ai";
-import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
-import type { SessionActionRecordV1 } from "@/executor/types/SessionRecords.js";
-
-/**
- * compaction Composer 执行输入。
- */
-export type SessionCompactionInput = {
-  /**
-   * 当前会话 history Store。
-   */
-  historyStore: SessionHistoryStore;
-
-  /**
-   * 当前模型实例。
-   */
-  model: LanguageModel;
-
-  /**
-   * 当前模型支持的总上下文窗口长度，单位为 token。
-   */
-  context_window?: number;
-
-  /**
-   * 当前轮 system messages。
-   */
-  system: SystemModelMessage[];
-
-  /**
-   * 当前重试次数（由 Executor 递增）。
-   */
-  retryCount: number;
-
-  /**
-   * 可选 action 发布回调。
-   *
-   * 说明（中文）
-   * - 默认 compaction Composer 可在真正开始压缩时发布 action。
-   * - 回调由上层 Session 负责转成订阅事件与 action record。
-   */
-  onAction?: (action: SessionActionRecordV1) => Promise<void>;
-
-  /**
-   * 是否明确要求持久化 deep compact。
-   *
-   * 普通模型调用不应因为历史字符数量而触发 compact；仅 usage 反馈或超限恢复会设置此值。
-   */
-  force?: boolean;
-};
-
-/**
- * Compaction Composer 协议。
- */
-export interface SessionCompactionComposer {
-  /**
-   * Composer 名（由具体实现声明）。
-   */
-  readonly name: string;
-
-  /**
-   * 执行 compact（best-effort）。
-   */
-  run(input: SessionCompactionInput): Promise<{
-    compacted: boolean;
-    reason?: string;
-  }>;
-
-  /**
-   * 判断某次执行错误是否应该触发“压缩后重试”。
-   *
-   * 关键点（中文）
-   * - 由 compaction Composer 实现侧维护错误识别策略。
-   * - Executor 不感知具体错误文案，只按该布尔结果决定是否重试。
-   */
-  shouldCompactOnError(error: unknown): boolean;
-}

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

@@ -1,51 +0,0 @@
-/**
- * JsonlSessionCompactionComposer：默认上下文压缩 Composer。
- *
- * 关键点（中文）
- * - 只负责压缩参数策略（retry 越多，窗口越紧）。
- * - 真正的读写与 compact 执行交由 history Store。
- */
-
-import type {
-  SessionCompactionComposer,
-  SessionCompactionInput,
-} from "@executor/composer/compaction/SessionCompactionComposer.js";
-
-/**
- * JsonlSessionCompactionComposer 默认实现。
- */
-export class JsonlSessionCompactionComposer implements SessionCompactionComposer {
-  readonly name = "summary_compaction_composer";
-
-  async run(input: SessionCompactionInput): Promise<{
-    compacted: boolean;
-    reason?: string;
-  }> {
-    if (!input.force && input.retryCount <= 0) {
-      return { compacted: false, reason: "not_requested" };
-    }
-    return await input.historyStore.compact({
-      model: input.model,
-      system: input.system,
-      force: true,
-      ...(input.onAction ? { onAction: input.onAction } : {}),
-    });
-  }
-
-  /**
-   * 判断错误是否属于“应先 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")
-    );
-  }
-}

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionExecutor.ts

@@ -1,294 +0,0 @@
-/**
- * JsonlSessionCompactionExecutor：JSONL session 压缩执行模块。
- *
- * 关键职责（中文）
- * - 评估当前消息是否超出输入预算。
- * - 在锁外生成“更早历史摘要”，降低锁持有时间。
- * - 在锁内完成归档与 messages.jsonl 重写，保证并发安全。
- */
-
-import fs from "fs-extra";
-import path from "node:path";
-import {
-  generateText,
-  isTextUIPart,
-  type LanguageModel,
-  type SystemModelMessage,
-} from "ai";
-import { generateId } from "@/utils/Id.js";
-import { getLogger } from "@/utils/logger/Logger.js";
-import type {
-  SessionActionRecordV1,
-  SessionRecordV1,
-  SessionMetadataV1,
-  SessionMessageRecordV1,
-} from "@/executor/types/SessionRecords.js";
-import {
-  is_session_message_record,
-} from "@/executor/types/SessionRecords.js";
-import {
-  append_session_compaction_file_operations,
-  build_initial_session_compaction_prompt,
-  build_update_session_compaction_prompt,
-  SESSION_COMPACTION_SYSTEM_PROMPT,
-} from "@executor/composer/compaction/jsonl/JsonlSessionCompactionPrompts.js";
-import { format_session_compaction_file_operations } from "@executor/composer/compaction/jsonl/JsonlSessionCompactionFileOperations.js";
-
-export type SessionCompactParams = {
-  model: LanguageModel;
-  system: Array<SystemModelMessage>;
-  archiveOnCompact: boolean;
-  force?: boolean;
-  onAction?: (action: SessionActionRecordV1) => Promise<void>;
-};
-
-type SessionCompactDeps = {
-  rootPath: string;
-  sessionId: string;
-  withWriteLock: <T>(fn: () => Promise<T>) => Promise<T>;
-  loadAll: () => Promise<SessionRecordV1[]>;
-  createSummaryMessage: (params: {
-    text: string;
-    archiveId?: string;
-    sourceRange?: SessionMetadataV1["sourceRange"];
-  }) => SessionRecordV1;
-  getArchiveDirPath: () => string;
-  getMessagesFilePath: () => string;
-  writeHistorySummaryUnsafe: (records: SessionRecordV1[]) => Promise<void>;
-};
-
-/**
- * 对当前 session messages 做一次 best-effort compact（必要时）。
- *
- * 注意（中文）
- * - compact 会 rewrite `messages.jsonl`（不是纯 append-only），因此必须防并发覆盖
- * - 这里做两阶段锁：先 snapshot 再生成摘要，最后再锁定写入，降低锁持有时间
- */
-export async function compactSessionMessagesIfNeeded(
-  deps: SessionCompactDeps,
-  params: SessionCompactParams,
-): Promise<{ compacted: boolean; reason?: string }> {
-  const logger = getLogger(deps.rootPath, "info");
-  const action_id = `compacting:${deps.sessionId}:${Date.now()}:${generateId()}`;
-  let action_started = false;
-
-  const publish_action = async (
-    action: Omit<SessionActionRecordV1, "type" | "id" | "metadata">,
-  ): Promise<void> => {
-    if (typeof params.onAction !== "function") return;
-    await params.onAction({
-      type: "action",
-      id: action_id,
-      ...action,
-      metadata: {
-        v: 1,
-        ts: Date.now(),
-        sessionId: deps.sessionId,
-      },
-    });
-  };
-
-  // 算法阶段（中文）
-  // phase 1：snapshot（短锁）
-  // - 仅负责拿一致性快照，不做耗时的模型调用。
-  // - 目的是把锁持有时间降到最低。
-  let snapshot: SessionMessageRecordV1[] = [];
-  let snapshotTailId = "";
-  await deps.withWriteLock(async () => {
-    snapshot = (await deps.loadAll()).filter(is_session_message_record);
-    snapshotTailId =
-      snapshot.length > 0
-        ? String(snapshot[snapshot.length - 1].id || "")
-        : "";
-  });
-
-  if (snapshot.length === 0) {
-    return { compacted: false, reason: "nothing_to_compact" };
-  }
-  if (!params.force) {
-    return { compacted: false, reason: "not_requested" };
-  }
-
-  // 关键点（中文）：明确 compact 时归档全部当前模型历史，避免单条巨大 assistant 永远留在 Active。
-  const older = snapshot;
-  if (older.length === 0) return { compacted: false, reason: "nothing_to_compact" };
-
-  action_started = true;
-  await publish_action({
-    title: "Compacting session records",
-    state: "running",
-  });
-
-  const previous_summary = extract_existing_compaction_summary(older[0]);
-  const conversation_messages = previous_summary ? older.slice(1) : older;
-  const olderTextAll = extractPlainTextFromMessages(conversation_messages);
-  const maxOlderChars = 24_000;
-  const olderText =
-    olderTextAll.length > maxOlderChars
-      ? "(Note: earlier history was too long and was truncated to keep the tail.)\n"
-        + olderTextAll.slice(-maxOlderChars)
-      : olderTextAll;
-  const prompt = previous_summary
-    ? build_update_session_compaction_prompt({
-        previous_summary,
-        new_conversation_text: olderText || "(none)",
-      })
-    : build_initial_session_compaction_prompt({
-        conversation_text: olderText || "(none)",
-      });
-  const file_operations_xml = format_session_compaction_file_operations(older);
-
-  // phase 1.5：生成摘要（不持锁）
-  // - 这一步最耗时，必须在锁外执行，避免阻塞 append。
-  let summary = "";
-  try {
-    const r = await generateText({
-      model: params.model,
-      system: [
-        {
-          role: "system",
-          content: SESSION_COMPACTION_SYSTEM_PROMPT,
-        },
-      ],
-      prompt,
-    });
-    summary = append_session_compaction_file_operations({
-      summary: String(r.text || "").trim(),
-      file_operations_xml,
-    });
-  } catch (e) {
-    await logger.log(
-      "warn",
-      "Session messages compact summary failed, fallback to lossy truncation",
-      {
-        sessionId: deps.sessionId,
-        error: String(e),
-      },
-    );
-    summary = append_session_compaction_file_operations({
-      summary:
-        "(Automatic session compaction: summary generation failed, so earlier history was discarded and only recent conversation was retained.)",
-      file_operations_xml,
-    });
-    await publish_action({
-      title: "Compacting session records",
-      description: "Summary generation failed; using a fallback summary.",
-      state: "running",
-    });
-  }
-
-  const fromId = String(older[0]?.id || "");
-  const toId = String(older[older.length - 1]?.id || "");
-  const archiveId = `compact-${Date.now()}-${generateId()}`;
-  const summaryMsg = deps.createSummaryMessage({
-    text: summary,
-    archiveId,
-    sourceRange: fromId && toId ? { fromId, toId, count: older.length } : undefined,
-  });
-
-  // phase 2：写入（短锁，且避免覆盖新追加）
-  // - 以“当前最新 session messages”为准重算 currentOlder / currentKept，避免覆盖并发新消息。
-  await deps.withWriteLock(async () => {
-    const current = await deps.loadAll();
-    if (!current.length) return;
-
-    // 如果 tail 不同，说明期间有新消息追加；我们仍可安全 compact：按“当前长度 + 相同比例”重算。
-    // snapshotTailId 用于 debug，不作为强一致性依赖。
-    void snapshotTailId;
-
-    const current_model_messages = current.filter(
-      is_session_message_record,
-    );
-    const currentOlder = current_model_messages;
-    if (currentOlder.length === 0) return;
-    const compacted_ids = new Set(
-      currentOlder
-        .map((message) => String(message.id || "").trim())
-        .filter(Boolean),
-    );
-
-    if (params.archiveOnCompact) {
-      const archivePath = path.join(
-        deps.getArchiveDirPath(),
-        `${encodeURIComponent(String(archiveId || "").trim())}.json`,
-      );
-      await fs.writeJson(
-        archivePath,
-        {
-          v: 1,
-          sessionId: deps.sessionId,
-          archivedAt: Date.now(),
-          messages: currentOlder,
-        },
-        { spaces: 2 },
-      );
-    }
-
-    const next = [
-      summaryMsg,
-      ...current.filter((message) => {
-        const id = String(message.id || "").trim();
-        return !id || !compacted_ids.has(id);
-      }),
-    ];
-
-    const messagesPath = deps.getMessagesFilePath();
-    const tmp = messagesPath + ".tmp";
-    await fs.writeFile(tmp, next.map((m) => JSON.stringify(m)).join("\n") + "\n", "utf8");
-    await fs.move(tmp, messagesPath, { overwrite: true });
-
-    await deps.writeHistorySummaryUnsafe(next);
-  });
-
-  if (action_started) {
-    await publish_action({
-      title: "Session records compacted",
-      description: `Compacted ${String(older.length)} earlier messages into ${archiveId}.`,
-      state: "completed",
-    });
-  }
-
-  return { compacted: true };
-}
-
-/**
- * 从 UIMessage 提取可摘要的纯文本。
- *
- * 关键点（中文）
- * - 统一把 user / assistant 内容线性化，作为 compact 摘要输入。
- * - tool 原始结构不会原样输出，避免把噪声日志喂给摘要模型。
- */
-function extractPlainTextFromMessages(messages: SessionMessageRecordV1[]): string {
-  const lines: string[] = [];
-  for (const m of messages) {
-    if (!m || typeof m !== "object") continue;
-    const role = m.role === "user" ? "user" : "assistant";
-    const parts = Array.isArray(m.parts) ? m.parts : [];
-    const textParts = parts.filter(isTextUIPart).map((p) => String(p.text ?? ""));
-    const text = textParts.join("\n").trim();
-    if (!text) continue;
-    lines.push(`${role}: ${text}`);
-  }
-  return lines.join("\n");
-}
-
-/**
- * 从已有 compact summary 消息中提取旧摘要。
- *
- * 关键点（中文）
- * - 旧摘要通常位于 messages.jsonl 第一条，后续 compact 应基于它迭代更新。
- * - 只识别 compact 生成的 summary，避免误把普通 assistant 文本当作旧摘要。
- */
-function extract_existing_compaction_summary(
-  message: SessionMessageRecordV1 | undefined,
-): string {
-  if (!message || typeof message !== "object") return "";
-  const metadata = message.metadata;
-  if (metadata?.source !== "compact" || metadata.kind !== "summary") return "";
-  const parts = Array.isArray(message.parts) ? message.parts : [];
-  return parts
-    .filter(isTextUIPart)
-    .map((part) => String(part.text ?? ""))
-    .join("\n")
-    .trim();
-}