@downcity/agent 1.1.202 → 1.1.204

package/scripts/session-title-event.test.mjs

@@ -45,6 +45,27 @@ function create_mock_title_model(title_text) {
   });
 }
 
+function create_failing_title_model() {
+  return new MockLanguageModelV3({
+    modelId: "mock-session-title-failing-model",
+    doGenerate: async () => {
+      throw new Error("mock title generation failed");
+    },
+  });
+}
+
+async function read_log_lines(agent_path) {
+  const logs_path = path.join(agent_path, ".downcity", "logs");
+  const entries = await fs.readdir(logs_path);
+  const lines = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const content = await fs.readFile(path.join(logs_path, entry), "utf8");
+    lines.push(...content.split("\n").filter(Boolean));
+  }
+  return lines;
+}
+
 test("Session keeps title empty when no model is available", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-session-title-"),
@@ -75,6 +96,51 @@ test("Session keeps title empty when no model is available", async () => {
   }
 });
 
+test("Session logs title generation failure without blocking the session", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-session-title-log-"),
+  );
+  const agent = new Agent({
+    id: "title_log_agent",
+    path: agent_path,
+    model: create_failing_title_model(),
+  });
+  const session = await agent.sessions.create();
+
+  try {
+    await session.append_user_message({
+      text: "Diagnose why session title generation is flaky",
+    });
+
+    const records = await session.records();
+    assert.equal(records.session.title, undefined);
+
+    await agent.getLogger().saveAllLogs();
+    const log_lines = await read_log_lines(agent_path);
+    const title_failure_log = log_lines
+      .map((line) => JSON.parse(line))
+      .find((entry) => entry.message.includes("session_title.generate_failed"));
+
+    assert.ok(title_failure_log);
+    assert.equal(title_failure_log.type, "warn");
+    assert.equal(title_failure_log.details.sessionId, session.id);
+    assert.equal(
+      title_failure_log.details.modelLabel,
+      "mock-session-title-failing-model",
+    );
+    assert.equal(
+      title_failure_log.details.message,
+      "mock title generation failed",
+    );
+    assert.equal(
+      title_failure_log.details.firstUserTextLength,
+      "Diagnose why session title generation is flaky".length,
+    );
+  } finally {
+    await agent.dispose();
+  }
+});
+
 test("Session retries title generation after model becomes available", async () => {
   const agent_path = await fs.mkdtemp(
     path.join(os.tmpdir(), "downcity-agent-session-title-retry-"),

package/src/session/Session.ts

@@ -120,6 +120,7 @@ export class Session implements AgentSession {
       history_store: this.historyStore,
       executor: this.executor,
       state: this.localState,
+      logger: this.logger,
       ensure_configured_hook: this.ensureConfiguredHook
         ? async () => {
             await this.ensureConfiguredHook?.(this);
@@ -142,6 +143,7 @@ export class Session implements AgentSession {
       session_id: this.id,
       history_store: this.historyStore,
       state_service: this.stateService,
+      logger: this.logger,
       is_executing: () => this.isExecuting(),
       get_instruction_system_blocks: this.getInstructionSystemBlocks,
       get_managed_plugin_system_blocks: this.getManagedPluginSystemBlocks,

package/src/session/SessionTitle.ts

@@ -11,6 +11,7 @@ import { generateText, type LanguageModel } from "ai";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 import { is_session_message_record } from "@/executor/types/SessionRecords.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 import {
   normalizeSessionTitle,
   readSessionMetadata,
@@ -48,6 +49,16 @@ export interface EnsureSessionTitleParams {
    */
   model?: LanguageModel;
 
+  /**
+   * 当前模型展示标签；仅用于排障日志，不参与生成逻辑。
+   */
+  modelLabel?: string;
+
+  /**
+   * 当前 session 运行日志器；标题生成失败时仅记录摘要，不影响主流程。
+   */
+  logger?: Logger;
+
   /**
    * 是否允许调用模型生成标题。
    */
@@ -102,16 +113,95 @@ function normalizeGeneratedTitle(input: string): string | undefined {
     : undefined;
 }
 
+function summarizeTitleError(error: unknown): {
+  /**
+   * 错误对象名称。
+   */
+  name: string | null;
+
+  /**
+   * 错误消息摘要。
+   */
+  message: string | null;
+
+  /**
+   * 字符串化后的错误摘要。
+   */
+  error: string;
+} {
+  const record =
+    error && typeof error === "object" && !Array.isArray(error)
+      ? (error as Record<string, unknown>)
+      : {};
+  return {
+    name: typeof record.name === "string" ? record.name : null,
+    message: typeof record.message === "string" ? record.message : null,
+    error: String(error),
+  };
+}
+
+async function logSessionTitleDiagnostic(input: {
+  /**
+   * 当前 session 标识。
+   */
+  sessionId: string;
+
+  /**
+   * 日志级别。
+   */
+  level: "debug" | "warn";
+
+  /**
+   * 日志消息。
+   */
+  message: string;
+
+  /**
+   * 结构化日志字段。
+   */
+  details: Record<string, string | number | boolean | null | undefined>;
+
+  /**
+   * 当前 session 运行日志器。
+   */
+  logger?: Logger;
+}): Promise<void> {
+  if (!input.logger) return;
+  try {
+    await input.logger.log(input.level, input.message, {
+      sessionId: input.sessionId,
+      ...input.details,
+    });
+  } catch {
+    // 关键点（中文）：标题诊断日志失败不能影响 session 主流程。
+  }
+}
+
 async function generateSessionTitle(input: {
   /**
    * 当前模型实例。
    */
   model: LanguageModel;
 
+  /**
+   * 当前 session 标识。
+   */
+  sessionId: string;
+
+  /**
+   * 当前模型展示标签；仅用于排障日志。
+   */
+  modelLabel?: string;
+
   /**
    * 首条用户消息文本。
    */
   firstUserText: string;
+
+  /**
+   * 当前 session 运行日志器。
+   */
+  logger?: Logger;
 }): Promise<string | undefined> {
   try {
     const result = await generateText({
@@ -125,8 +215,33 @@ async function generateSessionTitle(input: {
         input.firstUserText,
       ].join("\n"),
     });
-    return normalizeGeneratedTitle(result.text);
-  } catch {
+    const generatedTitle = normalizeGeneratedTitle(result.text);
+    if (!generatedTitle) {
+      await logSessionTitleDiagnostic({
+        logger: input.logger,
+        sessionId: input.sessionId,
+        level: "warn",
+        message: "[agent] session_title.empty",
+        details: {
+          modelLabel: input.modelLabel || null,
+          firstUserTextLength: input.firstUserText.length,
+          rawTitleLength: String(result.text || "").length,
+        },
+      });
+    }
+    return generatedTitle;
+  } catch (error) {
+    await logSessionTitleDiagnostic({
+      logger: input.logger,
+      sessionId: input.sessionId,
+      level: "warn",
+      message: "[agent] session_title.generate_failed",
+      details: {
+        modelLabel: input.modelLabel || null,
+        firstUserTextLength: input.firstUserText.length,
+        ...summarizeTitleError(error),
+      },
+    });
     // 关键点（中文）：标题生成失败不能影响 session 主流程。
     return undefined;
   }
@@ -142,13 +257,30 @@ export async function ensureSessionTitle(
   if (current.title) return current;
 
   const firstUserText = resolveFirstUserText(input.messages);
-  if (input.generate !== true || !input.model || !firstUserText) {
+  if (input.generate !== true) {
+    return current;
+  }
+  if (!input.model || !firstUserText) {
+    await logSessionTitleDiagnostic({
+      logger: input.logger,
+      sessionId: input.sessionId,
+      level: "debug",
+      message: "[agent] session_title.skipped",
+      details: {
+        reason: !input.model ? "missing_model" : "missing_first_user_text",
+        modelLabel: input.modelLabel || null,
+        messageCount: input.messages.length,
+      },
+    });
     return current;
   }
 
   const generatedTitle = await generateSessionTitle({
     model: input.model,
+    sessionId: input.sessionId,
+    modelLabel: input.modelLabel,
     firstUserText,
+    logger: input.logger,
   });
   if (!generatedTitle) return current;
 

package/src/session/services/SessionStateService.ts

@@ -41,6 +41,7 @@ import type {
 import { to_session_action_record } from "@/executor/types/SessionRecords.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
 import { generateId } from "@/utils/Id.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 
 type SessionStateServiceOptions = {
   /**
@@ -73,6 +74,11 @@ type SessionStateServiceOptions = {
    */
   state: SessionLocalState;
 
+  /**
+   * 当前 session 运行日志器。
+   */
+  logger: Logger;
+
   /**
    * 在执行前补齐宿主级配置。
    */
@@ -107,6 +113,7 @@ export class SessionStateService {
   private readonly history_store: JsonlSessionHistoryStore;
   private readonly executor: Executor;
   private readonly state: SessionLocalState;
+  private readonly logger: Logger;
   private readonly ensure_configured_hook?: SessionStateServiceOptions["ensure_configured_hook"];
   private readonly publish_event: SessionStateServiceOptions["publish_event"];
 
@@ -117,6 +124,7 @@ export class SessionStateService {
     this.history_store = options.history_store;
     this.executor = options.executor;
     this.state = options.state;
+    this.logger = options.logger;
     this.ensure_configured_hook = options.ensure_configured_hook;
     this.publish_event = options.publish_event;
   }
@@ -226,9 +234,17 @@ export class SessionStateService {
     const next_model_label = input.model
       ? inferAgentModelLabel(input.model)
       : undefined;
+    const should_emit_model_switch_action = Boolean(
+      input.model &&
+        should_emit_action &&
+        this.state.sessionConfig.model &&
+        previous_model_label &&
+        next_model_label &&
+        previous_model_label !== next_model_label,
+    );
     const action_id = `model-switching:${this.session_id}:${Date.now()}:${generateId()}`;
 
-    if (input.model && should_emit_action) {
+    if (should_emit_model_switch_action) {
       await this.emit_action_event({
         id: action_id,
         title: "Switching session model",
@@ -252,7 +268,7 @@ export class SessionStateService {
         model: this.state.sessionConfig.model,
       });
     } catch (error) {
-      if (input.model && should_emit_action) {
+      if (should_emit_model_switch_action) {
         await this.emit_action_event({
           id: action_id,
           title: "Session model switch failed",
@@ -263,7 +279,7 @@ export class SessionStateService {
       throw error;
     }
 
-    if (input.model && should_emit_action) {
+    if (should_emit_model_switch_action) {
       await this.emit_action_event({
         id: action_id,
         title: "Session model switched",
@@ -332,6 +348,10 @@ export class SessionStateService {
       sessionId: this.session_id,
       messages,
       ...(input?.generate ? { model: this.state.sessionConfig.model } : {}),
+      ...(this.state.sessionConfig.modelLabel
+        ? { modelLabel: this.state.sessionConfig.modelLabel }
+        : {}),
+      logger: this.logger,
       generate: input?.generate === true,
     });
     const next_title = String(next_metadata.title || "").trim();

package/src/session/services/SessionViewService.ts

@@ -31,6 +31,7 @@ import type {
 import type { SessionRecordV1 } from "@/executor/types/SessionRecords.js";
 import { SessionStateService } from "@/session/services/SessionStateService.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { Logger } from "@/utils/logger/Logger.js";
 
 type SessionViewServiceOptions<TSession extends Pick<AgentSession, "set">> = {
   /**
@@ -58,6 +59,11 @@ type SessionViewServiceOptions<TSession extends Pick<AgentSession, "set">> = {
    */
   state_service: SessionStateService;
 
+  /**
+   * 当前 session 运行日志器。
+   */
+  logger: Logger;
+
   /**
    * 判断当前 session 是否正在执行。
    */
@@ -106,6 +112,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
   private readonly session_id: string;
   private readonly history_store: JsonlSessionHistoryStore;
   private readonly state_service: SessionStateService;
+  private readonly logger: Logger;
   private readonly is_executing: SessionViewServiceOptions<TSession>["is_executing"];
   private readonly get_instruction_system_blocks: SessionViewServiceOptions<TSession>["get_instruction_system_blocks"];
   private readonly get_managed_plugin_system_blocks: SessionViewServiceOptions<TSession>["get_managed_plugin_system_blocks"];
@@ -119,6 +126,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
     this.session_id = options.session_id;
     this.history_store = options.history_store;
     this.state_service = options.state_service;
+    this.logger = options.logger;
     this.is_executing = options.is_executing;
     this.get_instruction_system_blocks = options.get_instruction_system_blocks;
     this.get_managed_plugin_system_blocks =
@@ -164,6 +172,7 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
           agentId: this.agent_id,
           sessionId: this.session_id,
           messages: input.messages,
+          logger: this.logger,
         });
     return buildSessionInfo({
       projectRoot: this.project_root,