@downcity/agent 1.1.237 → 1.1.258

package/src/session/SessionQueue.ts

@@ -0,0 +1,86 @@
+/**
+ * Session FIFO 输入队列。
+ *
+ * 只负责保存和按顺序取出 Prompt/Command，不执行命令，也不持有 active Turn。
+ */
+
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
+import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+import type {
+  SessionQueueCommand,
+  SessionQueueDeferred,
+  SessionQueueItem,
+  SessionQueuedPrompt,
+} from "@/types/session/SessionQueue.js";
+
+/** 单个 Session 的进程内 FIFO。 */
+export class SessionQueue {
+  private readonly items: SessionQueueItem[] = [];
+
+  /** 追加 Prompt 并返回等待 Turn Handle 的 Promise。 */
+  enqueue_prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
+    const deferred_handle = create_deferred<AgentSessionTurnHandle>();
+    this.items.push({ type: "prompt", input, deferred_handle });
+    return deferred_handle.promise;
+  }
+
+  /** 追加明确的领域命令。 */
+  enqueue_command(command: SessionQueueCommand): void {
+    this.items.push(command);
+  }
+
+  /** 当前队列是否包含 Prompt。 */
+  has_prompt(): boolean {
+    return this.items.some((item) => item.type === "prompt");
+  }
+
+  /** 当前队列是否包含 Command。 */
+  has_command(): boolean {
+    return this.items.some((item) => item.type !== "prompt");
+  }
+
+  /** 取出第一条 Prompt，以及它之前按顺序排队的命令。 */
+  take_next_prompt(): {
+    /** 当前 Prompt 之前的命令。 */
+    commands: SessionQueueCommand[];
+    /** 当前等待执行的 Prompt。 */
+    prompt: SessionQueuedPrompt;
+  } | null {
+    const prompt_index = this.items.findIndex((item) => item.type === "prompt");
+    if (prompt_index < 0) return null;
+    const commands = this.items.splice(0, prompt_index) as SessionQueueCommand[];
+    const prompt = this.items.shift();
+    return prompt?.type === "prompt" ? { commands, prompt } : null;
+  }
+
+  /** 取出当前全部输入，供下一个 Step 检查点按顺序提交。 */
+  drain(): SessionQueueItem[] {
+    return this.items.splice(0, this.items.length);
+  }
+
+  /** 把尚未处理的输入恢复到队列头部。 */
+  restore_front(items: SessionQueueItem[]): void {
+    this.items.unshift(...items);
+  }
+
+  /** 取消全部排队 Prompt，同时保留等待下一 Step 的命令。 */
+  cancel_prompts(): SessionQueuedPrompt[] {
+    const prompts = this.items.filter(
+      (item): item is SessionQueuedPrompt => item.type === "prompt",
+    );
+    const commands = this.items.filter(
+      (item): item is SessionQueueCommand => item.type !== "prompt",
+    );
+    this.items.splice(0, this.items.length, ...commands);
+    return prompts;
+  }
+}
+
+/** 创建最小 Promise 控制器。 */
+function create_deferred<T>(): SessionQueueDeferred<T> {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((next) => {
+    resolve = next;
+  });
+  return { promise, resolve };
+}

package/src/session/SessionState.ts

@@ -0,0 +1,322 @@
+/**
+ * SessionState：本地 Session 配置与 Metadata 状态。
+ *
+ * 关键点（中文）
+ * - 统一管理本地 Session 的初始化、配置、标题与 metadata。
+ * - Message 持久化统一交给 `SessionMessages`，这里仅读取 Message 快照更新 metadata。
+ * - 不负责 Turn 编排、Message 创建或 Action 生命周期。
+ */
+
+import {
+  inferAgentModelLabel,
+  read_agent_model_context_window,
+} from "@/agent/AgentModel.js";
+import {
+  patchSessionModelLabel,
+  readSessionMetadata,
+  resolveSystemTimezone,
+  writeSessionMetadata,
+} from "@/session/storage/Metadata.js";
+import { touchSessionMetadata } from "@/session/storage/Metadata.js";
+import { ensureSessionTitle } from "@/session/SessionTitle.js";
+import type {
+  AgentSessionConfigSnapshot,
+  AgentSessionSetInput,
+} from "@/types/agent/SessionTypes.js";
+import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
+import type { SessionModelQueueCommand } from "@/types/session/SessionQueue.js";
+import { generateId } from "@/utils/Id.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import { SessionMessages } from "@/session/SessionMessages.js";
+import { to_executor_history } from "@/session/messages/SessionMessageCodec.js";
+import type { SessionMessage } from "@/types/session/SessionMessage.js";
+import type {
+  SessionConfiguredCommandResult,
+  SessionSetOptions,
+  SessionStateOptions,
+} from "@/types/session/SessionState.js";
+
+/**
+ * 本地 Session 配置与 Metadata 状态管理器。
+ */
+export class SessionState {
+  private readonly agent_id: string;
+  private readonly project_root: string;
+  private readonly session_id: string;
+  private readonly messages: SessionMessages;
+  private readonly state: SessionLocalState;
+  private readonly logger: Logger;
+  private readonly ensure_configured_hook?: SessionStateOptions["ensure_configured_hook"];
+  private readonly get_model: SessionStateOptions["get_model"];
+  private readonly publish_event: SessionStateOptions["publish_event"];
+
+  constructor(options: SessionStateOptions) {
+    this.agent_id = options.agent_id;
+    this.project_root = options.project_root;
+    this.session_id = options.session_id;
+    this.messages = options.messages;
+    this.state = options.state;
+    this.logger = options.logger;
+    this.ensure_configured_hook = options.ensure_configured_hook;
+    this.get_model = options.get_model;
+    this.publish_event = options.publish_event;
+  }
+
+  /**
+   * 读取当前 session 配置快照。
+   */
+  get_config(): AgentSessionConfigSnapshot {
+    return {
+      ...this.state.session_config,
+    };
+  }
+
+  /**
+   * 读取当前 session 创建时间。
+   */
+  get_created_at(): number {
+    return this.state.created_at;
+  }
+
+  /**
+   * 读取当前 session 参考时区。
+   */
+  get_timezone(): string {
+    return this.state.timezone;
+  }
+
+  /**
+   * 初始化当前 session metadata 与内存快照。
+   */
+  async initialize(): Promise<void> {
+    if (this.state.initialize_promise) {
+      await this.state.initialize_promise;
+      return;
+    }
+    this.state.initialize_promise = (async () => {
+      const metadata = await readSessionMetadata({
+        projectRoot: this.project_root,
+        agentId: this.agent_id,
+        sessionId: this.session_id,
+      });
+      const created_at =
+        typeof metadata.createdAt === "number" ? metadata.createdAt : Date.now();
+      const timezone =
+        typeof metadata.timezone === "string" && metadata.timezone.trim()
+          ? metadata.timezone.trim()
+          : resolveSystemTimezone();
+      await writeSessionMetadata({
+        projectRoot: this.project_root,
+        agentId: this.agent_id,
+        sessionId: this.session_id,
+        meta: {
+          ...metadata,
+          agentId: this.agent_id,
+          createdAt: created_at,
+          timezone,
+        },
+      });
+      this.state.created_at = created_at;
+      this.state.timezone = timezone;
+      this.state.session_config = {};
+      this.state.effective_session_config = {
+        ...this.state.session_config,
+      };
+    })();
+    await this.state.initialize_promise;
+  }
+
+  /**
+   * 在执行前确保当前 session 已完成初始化与宿主装配。
+   */
+  async ensure_ready_for_execution(): Promise<void> {
+    await this.initialize();
+    if (this.state.ensure_configured_promise) {
+      await this.state.ensure_configured_promise;
+      return;
+    }
+    this.state.ensure_configured_promise = (async () => {
+      if (!this.ensure_configured_hook) return;
+      await this.ensure_configured_hook();
+    })();
+    try {
+      await this.state.ensure_configured_promise;
+    } catch (error) {
+      this.state.ensure_configured_promise = null;
+      throw error;
+    }
+  }
+
+  /**
+   * 在 prompt 执行前确保当前 session 已可运行。
+   */
+  async ensure_runnable(): Promise<void> {
+    await this.ensure_ready_for_execution();
+    if (!this.get_model()) {
+      throw new Error("requires a configured model.");
+    }
+  }
+
+  /**
+   * 写入当前 session 配置。
+   */
+  async set(
+    input: AgentSessionSetInput,
+    options?: SessionSetOptions,
+  ): Promise<SessionConfiguredCommandResult> {
+    const should_emit_action = options?.emit_action !== false;
+    const previous_model_label = this.state.session_config.modelLabel;
+    const next_model = input.model;
+    const next_model_label = next_model
+      ? inferAgentModelLabel(next_model)
+      : undefined;
+    const previous_model_name = String(previous_model_label || "").trim();
+    const next_model_name = String(next_model_label || "").trim();
+    const should_emit_model_switch_action = Boolean(
+      next_model &&
+        should_emit_action &&
+        this.state.session_config.model &&
+        previous_model_name &&
+        next_model_name &&
+        previous_model_name !== next_model_name,
+    );
+    const action_id = `model-switching:${this.session_id}:${Date.now()}:${generateId()}`;
+
+    const next_config: AgentSessionConfigSnapshot = {
+      ...this.state.session_config,
+    };
+    if (next_model) {
+      next_config.model = next_model;
+      next_config.modelLabel = next_model_label;
+      next_config.model_context_window =
+        read_agent_model_context_window(next_model);
+    }
+    await patchSessionModelLabel({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      sessionId: this.session_id,
+      model: next_config.model,
+    });
+    this.state.session_config = next_config;
+
+    if (options?.emit_action === false) {
+      await this.apply_model_command({
+        type: "session_model",
+        command_id: generateId(),
+        config: next_config,
+      });
+      return {};
+    }
+
+    return {
+      command: {
+        type: "session_model",
+        command_id: generateId(),
+        config: next_config,
+        ...(should_emit_model_switch_action
+          ? {
+              action_id,
+              action_title:
+                `Session model switched from ${previous_model_name} to ${next_model_name}`,
+            }
+          : {}),
+      },
+    };
+  }
+
+  /** 在 Session Step 检查点提交模型配置。 */
+  async apply_model_command(
+    command: SessionModelQueueCommand,
+  ): Promise<void> {
+    this.state.effective_session_config = {
+      ...command.config,
+    };
+  }
+
+  /**
+   * 仅刷新当前 session metadata。
+   */
+  async touch_metadata(): Promise<void> {
+    const stats = await this.messages.storage_stats();
+    const preview_text = resolve_message_preview(
+      stats.latest_message || undefined,
+    ).slice(0, 180);
+    await touchSessionMetadata({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      sessionId: this.session_id,
+      sessionConfig: this.state.session_config,
+      message_count: stats.message_count,
+      history_bytes: stats.history_bytes,
+      ...(preview_text ? { preview_text } : {}),
+    });
+  }
+
+  /**
+   * 确保当前 session 已持久化 title。
+   */
+  async ensure_title_from_history(input?: {
+    /**
+     * 是否允许调用模型生成标题。
+     */
+    generate?: boolean;
+  }): Promise<void> {
+    const messages = to_executor_history(
+      this.session_id,
+      await this.messages.context_snapshot(),
+    );
+    const before_metadata = await readSessionMetadata({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      sessionId: this.session_id,
+    });
+    const before_title = String(before_metadata.title || "").trim();
+    const next_metadata = await ensureSessionTitle({
+      projectRoot: this.project_root,
+      agentId: this.agent_id,
+      sessionId: this.session_id,
+      messages,
+      ...(input?.generate
+        ? {
+            model: this.get_model(),
+          }
+        : {}),
+      ...(this.state.session_config.modelLabel
+        ? { modelLabel: this.state.session_config.modelLabel }
+        : {}),
+      logger: this.logger,
+      generate: input?.generate === true,
+    });
+    const next_title = String(next_metadata.title || "").trim();
+    if (!next_title || next_title === before_title) return;
+    this.publish_event({
+      mutation_id: generateId(),
+      variant: "session",
+      type: "title",
+      session_id: this.session_id,
+      created_at: Date.now(),
+      title: next_title,
+    });
+  }
+
+}
+
+function resolve_message_preview(message: SessionMessage | undefined): string {
+  if (!message) return "";
+  if (message.type === "user") {
+    return message.parts
+      .flatMap((part) => part.type === "text" ? [part.text] : [])
+      .join("")
+      .trim();
+  }
+  if (message.type === "assistant") {
+    return message.parts
+      .flatMap((part) => part.type === "text" ? [part.text] : [])
+      .join("")
+      .trim();
+  }
+  if (message.type === "action") {
+    return [message.title, message.description].filter(Boolean).join("\n");
+  }
+  return message.message.trim();
+}

package/src/session/SessionSystem.ts

@@ -0,0 +1,117 @@
+/**
+ * SDK Session 默认 system block 组装逻辑。
+ *
+ * 关键点（中文）
+ * - 面向 `Agent` SDK 的本地会话执行场景。
+ * - 注入调用方显式传入的静态 instruction、受托管 plugin system 与显式注册 plugin system。
+ * - SDK 不在 system 中注入动态变量；动态上下文应由调用方放入 user message。
+ */
+
+import type {
+  AgentSessionSystemBlock,
+  AgentSessionSystemSessionInfo,
+} from "@/types/agent/SessionTypes.js";
+import type { BuildSessionSystemBlocksInput } from "@/types/session/SessionSystem.js";
+
+function normalize_system_blocks(
+  blocks: AgentSessionSystemBlock[],
+): AgentSessionSystemBlock[] {
+  if (!Array.isArray(blocks)) return [];
+  return blocks
+    .map((block) => {
+      const content = String(block?.content || "").trim();
+      if (!content) return null;
+      const source = block.source;
+      if (
+        source !== "core" &&
+        source !== "instruction" &&
+        source !== "plugin" &&
+        source !== "session"
+      ) {
+        return null;
+      }
+      return {
+        source,
+        name: String(block.name || source).trim() || source,
+        content,
+      } satisfies AgentSessionSystemBlock;
+    })
+    .filter((block): block is AgentSessionSystemBlock => Boolean(block));
+}
+
+function create_session_info(
+  input: Pick<
+    BuildSessionSystemBlocksInput,
+    "agent_id" | "session_id" | "project_root" | "created_at" | "timezone"
+  >,
+): AgentSessionSystemSessionInfo {
+  const created_at = Number.isFinite(input.created_at) ? input.created_at : 0;
+  return {
+    agentId: String(input.agent_id || "").trim(),
+    sessionId: String(input.session_id || "").trim(),
+    projectRoot: String(input.project_root || "").trim(),
+    createdAt: new Date(created_at).toISOString(),
+    timezone: String(input.timezone || "").trim() || "UTC",
+  };
+}
+
+function create_session_system_block(
+  session: AgentSessionSystemSessionInfo,
+): AgentSessionSystemBlock {
+  const content = [
+    "当前会话上下文：",
+    `你正在服务 agent "${session.agentId}" 的 session "${session.sessionId}"。`,
+    `当前项目根目录是 "${session.projectRoot}"。`,
+    `本会话创建于 ${session.createdAt}，参考时区是 ${session.timezone}。`,
+    "这个创建时间是当前会话的稳定参考时间，不代表每轮运行时的当前时间。",
+    "如果用户消息中提供了新的当前时间、相对时间或其他动态上下文，应优先使用用户消息中的动态信息。",
+  ].join("\n");
+  return {
+    source: "session",
+    name: "context",
+    content,
+  };
+}
+
+/**
+ * 解析 SDK session 当前生效的 system blocks。
+ */
+export async function build_session_system_blocks(
+  input: BuildSessionSystemBlocksInput,
+): Promise<AgentSessionSystemBlock[]> {
+  const agent_id = String(input.agent_id || "").trim();
+  const project_root = String(input.project_root || "").trim();
+  const session_id = String(input.session_id || "").trim();
+  const created_at = Number(input.created_at || 0);
+  const timezone = String(input.timezone || "").trim();
+  if (!agent_id) {
+    throw new Error("build_session_system_blocks requires a non-empty agent_id");
+  }
+  if (!project_root) {
+    throw new Error("build_session_system_blocks requires a non-empty project_root");
+  }
+  if (!session_id) {
+    throw new Error("build_session_system_blocks requires a non-empty session_id");
+  }
+  if (!Number.isFinite(created_at) || created_at <= 0) {
+    throw new Error("build_session_system_blocks requires a valid created_at");
+  }
+  if (!timezone) {
+    throw new Error("build_session_system_blocks requires a non-empty timezone");
+  }
+  return [
+    ...normalize_system_blocks(input.get_instruction_system_blocks()),
+    ...normalize_system_blocks(await input.get_managed_plugin_system_blocks()),
+    ...normalize_system_blocks(await input.get_plugin_system_blocks()),
+    // session block 放在最后，尽量保留前缀 system blocks 的跨 session 缓存命中。
+    create_session_system_block(
+      create_session_info({
+        agent_id,
+        project_root,
+        session_id,
+        created_at,
+        timezone,
+      }),
+    ),
+  ];
+}