@downcity/agent 1.1.408 → 1.1.437

package/src/session/SessionQueue.ts

@@ -5,7 +5,7 @@
  * 也不持有 active Turn。
  */
 
-import { SessionCommand } from "@/session/SessionCommand.js";
+import type { SessionCommand } from "@/types/session/SessionCommand.js";
 
 /** 单个 Session 的进程内 FIFO。 */
 export class SessionQueue {
@@ -41,7 +41,8 @@ export class SessionQueue {
     let cancelled_count = 0;
     const retained_commands: SessionCommand[] = [];
     for (const command of this.commands) {
-      if (command.cancel()) {
+      if (command.cancel) {
+        command.cancel();
         cancelled_count += 1;
       } else {
         retained_commands.push(command);

package/src/session/SessionState.ts

@@ -8,9 +8,10 @@
  */
 
 import {
-  infer_agent_model_label,
-  read_agent_model_context_window,
-} from "@/agent/AgentModel.js";
+  read_model_context_window,
+  read_model_label,
+  type ModelClient,
+} from "@downcity/type";
 import {
   normalize_session_title,
   resolve_system_timezone,
@@ -19,16 +20,27 @@ import { ensure_session_title } from "@/session/SessionTitle.js";
 import type {
   AgentSessionConfigSnapshot,
 } from "@/types/agent/SessionTypes.js";
-import type { AgentModel } from "@/agent/AgentModel.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import { generate_id } from "@/utils/Id.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import { SessionMessages } from "@/session/SessionMessages.js";
 import { SessionTitleTask } from "@/session/runtime/SessionTitleTask.js";
-import type { SessionMessage } from "@/types/session/SessionMessage.js";
 import type { SessionStateOptions } from "@/types/session/SessionState.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
-import type { SessionApprovalMode } from "@/types/session/SessionInteraction.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type { SessionApprovalMode } from "@downcity/type";
+import { create_session_model_request_warning } from "@/session/runtime/SessionModelRequestWarning.js";
+
+/** 创建单个 Session 唯一的可变内存状态。 */
+export function create_session_local_state(): SessionLocalState {
+  return {
+    session_config: {},
+    effective_session_config: {},
+    configured_approval_mode: "ask",
+    created_at: Date.now(),
+    timezone: resolve_system_timezone(),
+    initialize_promise: null,
+    ensure_configured_promise: null,
+  };
+}
 
 /** Session 模型配置写入结果。 */
 export interface SessionModelSetResult {
@@ -44,9 +56,8 @@ export interface SessionModelSetResult {
 export class SessionState {
   private readonly agent_id: string;
   private readonly session_id: string;
-  private readonly origin?: SessionStateOptions["origin"];
-  private readonly store: SessionDataStore;
-  private readonly messages: SessionMessages;
+  private readonly origin: SessionStateOptions["origin"];
+  private readonly store: SessionStorage;
   private readonly state: SessionLocalState;
   private readonly logger: Logger;
   private readonly ensure_configured_hook?: SessionStateOptions["ensure_configured_hook"];
@@ -60,7 +71,6 @@ export class SessionState {
     this.session_id = options.session_id;
     this.origin = options.origin;
     this.store = options.store;
-    this.messages = options.messages;
     this.state = options.state;
     this.logger = options.logger;
     this.ensure_configured_hook = options.ensure_configured_hook;
@@ -104,36 +114,42 @@ export class SessionState {
    * 初始化当前 session metadata 与内存快照。
    */
   async initialize(): Promise<void> {
-    if (this.state.initialize_promise) {
-      await this.state.initialize_promise;
-      return;
+    if (!this.state.initialize_promise) {
+      this.state.initialize_promise = (async () => {
+        const metadata = await this.store.read_metadata();
+        const created_at =
+          typeof metadata.created_at === "number" ? metadata.created_at : Date.now();
+        const timezone =
+          typeof metadata.timezone === "string" && metadata.timezone.trim()
+            ? metadata.timezone.trim()
+            : resolve_system_timezone();
+        await this.store.write_metadata({
+          ...metadata,
+          agent_id: this.agent_id,
+          created_at: created_at,
+          timezone,
+          origin: this.origin,
+        });
+        this.state.created_at = created_at;
+        this.state.timezone = timezone;
+        this.state.session_config = {
+          ...(metadata.model_label ? { model_label: metadata.model_label } : {}),
+        };
+        this.state.effective_session_config = {
+          ...this.state.session_config,
+        };
+        this.state.configured_approval_mode = metadata.approval_mode || "ask";
+      })();
+    }
+    const initialize_promise = this.state.initialize_promise;
+    try {
+      await initialize_promise;
+    } catch (error) {
+      if (this.state.initialize_promise === initialize_promise) {
+        this.state.initialize_promise = null;
+      }
+      throw error;
     }
-    this.state.initialize_promise = (async () => {
-      const metadata = await this.store.read_metadata();
-      const created_at =
-        typeof metadata.created_at === "number" ? metadata.created_at : Date.now();
-      const timezone =
-        typeof metadata.timezone === "string" && metadata.timezone.trim()
-          ? metadata.timezone.trim()
-          : resolve_system_timezone();
-      await this.store.write_metadata({
-        ...metadata,
-        agent_id: this.agent_id,
-        created_at: created_at,
-        timezone,
-        ...(this.origin ? { origin: this.origin } : {}),
-      });
-      this.state.created_at = created_at;
-      this.state.timezone = timezone;
-      this.state.session_config = {
-        ...(metadata.model_label ? { model_label: metadata.model_label } : {}),
-      };
-      this.state.effective_session_config = {
-        ...this.state.session_config,
-      };
-      this.state.configured_approval_mode = metadata.approval_mode || "ask";
-    })();
-    await this.state.initialize_promise;
   }
 
   /**
@@ -170,14 +186,14 @@ export class SessionState {
   /**
    * 写入当前 session 配置。
    */
-  async set_model(model: AgentModel): Promise<SessionModelSetResult> {
-    const next_model_label = infer_agent_model_label(model);
+  async set_model(model: ModelClient): Promise<SessionModelSetResult> {
+    const next_model_label = read_model_label(model);
     const changed = next_model_label !== this.state.session_config.model_label;
     const next_config: AgentSessionConfigSnapshot = {
       ...this.state.session_config,
       model,
       model_label: next_model_label,
-      model_context_window: read_agent_model_context_window(model),
+      model_context_window: read_model_context_window(model),
     };
     if (changed) {
       await this.run_metadata_mutation(async () => {
@@ -246,73 +262,38 @@ export class SessionState {
     };
   }
 
-  /**
-   * 仅刷新当前 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 this.run_metadata_mutation(async () => {
-      const metadata = await this.store.read_metadata();
-      await this.store.write_metadata({
-        ...metadata,
-        agent_id: this.agent_id,
-        updated_at: Date.now(),
-        ...(this.state.session_config.model_label
-          ? { model_label: this.state.session_config.model_label }
-          : {}),
-        message_count: stats.message_count,
-        historyBytes: stats.history_bytes,
-        ...(preview_text ? { preview_text: preview_text } : {}),
-      });
-    });
-  }
-
-  /** 在后台刷新 Session metadata，不阻塞当前 Turn。 */
-  touch_metadata_in_background(): void {
-    void this.touch_metadata().catch(async (error) => {
-      try {
-        await this.logger.log("warn", "[agent] session_metadata.background_update_failed", {
-          session_id: this.session_id,
-          error: error instanceof Error ? error.message : String(error),
-        });
-      } catch {
-        // metadata 诊断日志失败不能影响当前 Turn。
-      }
-    });
-  }
-
   /** 异步调度首条用户消息的 Session 标题生成。 */
   schedule_title_generation(): void {
     this.title_task.schedule(async (signal) => {
       const before_metadata = await this.store.read_metadata();
       if (String(before_metadata.title || "").trim()) return;
-      const messages = (await this.messages.context_snapshot()).messages;
-      const first_user_message = messages.find(
-        (message) => message.type === "user",
-      );
+      const first_user_message = await this.store.read_first_user_message();
       if (!first_user_message) return;
       const first_user_message_id = first_user_message.message_id;
       const before_title = String(before_metadata.title || "").trim();
       const next_metadata = await ensure_session_title({
         session_id: this.session_id,
         store: this.store,
-        messages,
+        messages: [first_user_message],
         model: this.get_model(),
         model_label: this.state.session_config.model_label,
         logger: this.logger,
         generate: true,
         signal,
+        on_model_request_failure: (notice) => {
+          this.publish_event(create_session_model_request_warning({
+            session_id: this.session_id,
+            notice,
+          }));
+        },
         commit_title: async (title) => await this.run_metadata_mutation(async () => {
           const latest_metadata = await this.store.read_metadata();
           if (signal.aborted) return latest_metadata;
           if (String(latest_metadata.title || "").trim()) return latest_metadata;
-          const latest_messages = (await this.messages.context_snapshot()).messages;
-          const source_exists = latest_messages.some(
-            (message) => message.message_id === first_user_message_id,
+          const source_message = await this.store.read_message(
+            first_user_message_id,
           );
+          const source_exists = source_message?.role === "user";
           if (!source_exists || signal.aborted) return latest_metadata;
           const next_metadata = { ...latest_metadata, title };
           await this.store.write_metadata(next_metadata);
@@ -348,23 +329,3 @@ export class SessionState {
   }
 
 }
-
-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

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 面向 `Agent` SDK 的本地会话执行场景。
- * - 注入调用方显式传入的静态 instruction、受托管 plugin system 与显式注册 plugin system。
+ * - 注入调用方显式传入的静态 instruction 与 Plugin system blocks。
  * - SDK 不在 system 中注入动态变量；动态上下文应由调用方放入 user message。
  */
 
@@ -11,14 +11,19 @@ import type {
   AgentSessionSystemBlock,
   AgentSessionSystemSessionInfo,
 } from "@/types/agent/SessionTypes.js";
-import type { BuildSessionSystemBlocksInput } from "@/types/session/SessionSystem.js";
+import type {
+  BuildSessionSystemBlocksInput,
+  ResolveSessionPluginSystemBlocksInput,
+} from "@/types/session/SessionSystem.js";
+import type { JsonValue, SessionSystemContextHookValue } from "@downcity/type";
+import { SESSION_HOOK_POINTS } from "@/session/SessionHookPoints.js";
 
 function normalize_system_blocks(
   blocks: AgentSessionSystemBlock[],
 ): AgentSessionSystemBlock[] {
   if (!Array.isArray(blocks)) return [];
   return blocks
-    .map((block) => {
+    .map((block): AgentSessionSystemBlock | null => {
       const content = String(block?.content || "").trim();
       if (!content) return null;
       const source = block.source;
@@ -39,6 +44,51 @@ function normalize_system_blocks(
     .filter((block): block is AgentSessionSystemBlock => Boolean(block));
 }
 
+/** 把 system pipeline 输出限制为稳定的 Plugin 命名内容块。 */
+export function normalize_plugin_system_blocks(
+  input: unknown,
+): AgentSessionSystemBlock[] {
+  if (!Array.isArray(input)) return [];
+  return input.flatMap((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return [];
+    const record = item as Record<string, unknown>;
+    const name = String(record.name || "").trim();
+    const content = String(record.content || "").trim();
+    if (!name || !content) return [];
+    return [{ source: "plugin" as const, name, content }];
+  });
+}
+
+/** 使用统一 Hook 检查点解析当前 Session 的 Plugin system blocks。 */
+export async function resolve_session_plugin_system_blocks(
+  input: ResolveSessionPluginSystemBlocksInput,
+): Promise<AgentSessionSystemBlock[]> {
+  let blocks: AgentSessionSystemBlock[];
+  try {
+    blocks = normalize_plugin_system_blocks(
+      await input.hooks.system_blocks(input.context),
+    );
+  } catch (error) {
+    await input.on_error?.(error);
+    return [];
+  }
+  const value: SessionSystemContextHookValue = {
+    session_id: input.session_id,
+    ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+    blocks,
+  };
+  try {
+    const output = await input.hooks.pipeline(
+      SESSION_HOOK_POINTS.system_context,
+      value as unknown as JsonValue,
+    ) as unknown as SessionSystemContextHookValue;
+    return normalize_plugin_system_blocks(output?.blocks);
+  } catch (error) {
+    await input.on_error?.(error);
+    return blocks;
+  }
+}
+
 function create_session_info(
   input: Pick<
     BuildSessionSystemBlocksInput,

package/src/session/SessionTitle.ts

@@ -2,7 +2,7 @@
  * SDK Session 标题生成与持久化辅助。
  *
  * 关键点（中文）
- * - session title 是 `meta.json` 顶层字段，列表与详情都以它为准。
+ * - session title 是 `session_state` 的字段，列表与详情都以它为准。
  * - title 默认允许为空；只有模型成功生成标题时才会写入。
  * - 当 title 仍为空时，后续执行链路可以再次尝试生成。
  */
@@ -12,12 +12,13 @@ import {
   build_text_model_messages,
   generate_model,
 } from "@executor/model/ModelGenerate.js";
-import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionHistoryMeta } from "@/executor/types/SessionHistoryMeta.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import { normalize_session_title } from "@/session/storage/Metadata.js";
-import type { SessionDataStore } from "@/types/store/SessionDataStore.js";
-import type { SessionMessage } from "@/types/session/SessionMessage.js";
+import type { SessionStorage } from "@/types/store/SessionStorage.js";
+import type { SessionMessage } from "@downcity/type";
 import { extract_session_message_text } from "@/session/messages/SessionMessageText.js";
+import type { ModelRequestFailureReporter } from "@/types/executor/ModelRequest.js";
 
 const GENERATED_SESSION_TITLE_MAX_CHARS = 24;
 
@@ -26,7 +27,7 @@ const GENERATED_SESSION_TITLE_MAX_CHARS = 24;
  */
 export interface EnsureSessionTitleParams {
   /** 当前 Session 的领域持久化入口。 */
-  store: SessionDataStore;
+  store: SessionStorage;
 
   /**
    * 当前 session_id。
@@ -61,43 +62,46 @@ export interface EnsureSessionTitleParams {
   /** 可选的标题请求取消信号。 */
   signal?: AbortSignal;
 
+  /** 可选的模型请求逐次失败通知入口。 */
+  on_model_request_failure?: ModelRequestFailureReporter;
+
   /** 可选的标题提交入口，用于与其他 metadata mutation 串行化。 */
-  commit_title?: (title: string) => Promise<SessionHistoryMetaV1>;
+  commit_title?: (title: string) => Promise<SessionHistoryMeta>;
 }
 
-function truncateTitle(input: string, maxChars: number): string {
+function truncate_title(input: string, max_chars: number): string {
   const title = String(input || "").replace(/\s+/g, " ").trim();
   if (!title) return "";
-  if (title.length <= maxChars) return title;
-  return title.slice(0, maxChars).trimEnd();
+  if (title.length <= max_chars) return title;
+  return title.slice(0, max_chars).trimEnd();
 }
 
-function resolveFirstUserText(messages: SessionMessage[]): string {
+function resolve_first_user_text(messages: SessionMessage[]): string {
   for (const message of messages) {
-    if (message.type !== "user") continue;
+    if (message.role !== "user") continue;
     const text = extract_session_message_text(message);
     if (text) return text;
   }
   return "";
 }
 
-function normalizeGeneratedTitle(input: string): string | undefined {
-  const firstLine = String(input || "")
+function normalize_generated_title(input: string): string | undefined {
+  const first_line = String(input || "")
     .split("\n")
     .map((line) => line.trim())
     .find(Boolean);
   const title = normalize_session_title(
-    String(firstLine || "")
+    String(first_line || "")
       .replace(/^["'`“”‘’]+|["'`“”‘’]+$/g, "")
       .replace(/^标题[:：]\s*/i, "")
       .trim(),
   );
   return title
-    ? truncateTitle(title, GENERATED_SESSION_TITLE_MAX_CHARS)
+    ? truncate_title(title, GENERATED_SESSION_TITLE_MAX_CHARS)
     : undefined;
 }
 
-function summarizeTitleError(error: unknown): {
+function summarize_title_error(error: unknown): {
   /**
    * 错误对象名称。
    */
@@ -124,7 +128,7 @@ function summarizeTitleError(error: unknown): {
   };
 }
 
-async function logSessionTitleDiagnostic(input: {
+async function log_session_title_diagnostic(input: {
   /**
    * 当前 session 标识。
    */
@@ -161,7 +165,8 @@ async function logSessionTitleDiagnostic(input: {
   }
 }
 
-async function generateSessionTitle(input: {
+/** 根据首条用户消息生成规范化后的会话标题。 */
+export async function generate_session_title(input: {
   /**
    * 当前模型实例。
    */
@@ -180,7 +185,7 @@ async function generateSessionTitle(input: {
   /**
    * 首条用户消息文本。
    */
-  firstUserText: string;
+  first_user_text: string;
 
   /**
    * 当前 session 运行日志器。
@@ -189,6 +194,9 @@ async function generateSessionTitle(input: {
 
   /** 标题请求取消信号。 */
   signal?: AbortSignal;
+
+  /** 可选的模型请求逐次失败通知入口。 */
+  on_model_request_failure?: ModelRequestFailureReporter;
 }): Promise<string | undefined> {
   try {
     const result = await generate_model(input.model, {
@@ -198,37 +206,41 @@ async function generateSessionTitle(input: {
         "Generate a short conversation title from the first user message below.",
         "Requirements: 3 to 12 Chinese characters or 2 to 6 English words; no period; no prefix.",
         "",
-        input.firstUserText,
+        input.first_user_text,
         ].join("\n"),
       ),
-    }, input.signal);
+    }, {
+      request_kind: "session_title",
+      signal: input.signal,
+      on_failure: input.on_model_request_failure,
+    });
     const text = result.text;
-    const generatedTitle = normalizeGeneratedTitle(text);
-    if (!generatedTitle) {
-      await logSessionTitleDiagnostic({
+    const generated_title = normalize_generated_title(text);
+    if (!generated_title) {
+      await log_session_title_diagnostic({
         logger: input.logger,
         session_id: input.session_id,
         level: "warn",
         message: "[agent] session_title.empty",
         details: {
           model_label: input.model_label || null,
-          firstUserTextLength: input.firstUserText.length,
+          firstUserTextLength: input.first_user_text.length,
           rawTitleLength: String(text || "").length,
         },
       });
     }
-    return generatedTitle;
+    return generated_title;
   } catch (error) {
-    const effectiveError = error;
-    await logSessionTitleDiagnostic({
+    const effective_error = error;
+    await log_session_title_diagnostic({
       logger: input.logger,
       session_id: input.session_id,
       level: "warn",
       message: "[agent] session_title.generate_failed",
       details: {
         model_label: input.model_label || null,
-        firstUserTextLength: input.firstUserText.length,
-        ...summarizeTitleError(effectiveError),
+        firstUserTextLength: input.first_user_text.length,
+        ...summarize_title_error(effective_error),
       },
     });
     // 关键点（中文）：标题生成失败不能影响 session 主流程。
@@ -241,16 +253,16 @@ async function generateSessionTitle(input: {
  */
 export async function ensure_session_title(
   input: EnsureSessionTitleParams,
-): Promise<SessionHistoryMetaV1> {
+): Promise<SessionHistoryMeta> {
   const current = await input.store.read_metadata();
   if (current.title) return current;
 
-  const firstUserText = resolveFirstUserText(input.messages);
+  const first_user_text = resolve_first_user_text(input.messages);
   if (input.generate !== true) {
     return current;
   }
-  if (!input.model || !firstUserText) {
-    await logSessionTitleDiagnostic({
+  if (!input.model || !first_user_text) {
+    await log_session_title_diagnostic({
       logger: input.logger,
       session_id: input.session_id,
       level: "debug",
@@ -264,21 +276,22 @@ export async function ensure_session_title(
     return current;
   }
 
-  const generatedTitle = await generateSessionTitle({
+  const generated_title = await generate_session_title({
     model: input.model,
     session_id: input.session_id,
     model_label: input.model_label,
-    firstUserText,
+    first_user_text,
     logger: input.logger,
     signal: input.signal,
+    on_model_request_failure: input.on_model_request_failure,
   });
-  if (!generatedTitle) return current;
+  if (!generated_title) return current;
 
-  if (input.commit_title) return await input.commit_title(generatedTitle);
-  const generatedMeta: SessionHistoryMetaV1 = {
+  if (input.commit_title) return await input.commit_title(generated_title);
+  const generated_meta: SessionHistoryMeta = {
     ...(await input.store.read_metadata()),
-    title: generatedTitle,
+    title: generated_title,
   };
-  await input.store.write_metadata(generatedMeta);
-  return generatedMeta;
+  await input.store.write_metadata(generated_meta);
+  return generated_meta;
 }