@downcity/agent 1.1.207 → 1.1.210

package/src/executor/composer/system/default/assets/core.prompt.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/executor/composer/system/default/assets/core.prompt.ts.txt
-const TEXT_MODULE_CONTENT = "You have permission to use and modify only the current project: {{project_path}}. The current year is {{current_year}}.\n1. `.downcity/` is Downcity's runtime data directory. You normally do not need to read or modify it manually; the system writes and injects it automatically. Its structure and purpose are:\n   - `.downcity/agents/<agentId>/sessions/`: session messages.\n   - `.downcity/memory/`: medium- and long-term memory.\n   - `.downcity/profile/Primary.md`, `.downcity/profile/other.md`: global profile memory. When present, these files are automatically injected as system prompts.\n   - `.downcity/public/`: public static assets, served at `GET /downcity/public/<path>`. Use it for files that must be accessible externally. Do not store sensitive information there. The Agent HTTP gateway exposes `.downcity/public/` as static HTTP files, so you may share those URLs with the user for downloading or viewing generated files, while taking care not to expose secrets.\n   - `.downcity/logs/<YYYY-MM-DD>.jsonl`: runtime logs in JSONL format. Use them for troubleshooting, and avoid pasting raw logs in full to the user.\n   - `.downcity/.cache/`: idempotency and deduplication cache for ingress/egress. Do not edit it manually.\n   - `.downcity/.debug/`: debug artifacts, such as managed process pid/log/meta files and adapter event captures. Inspect only when troubleshooting.\n   - `.downcity/data/`: small persistent data store, reserved for runtime use.\n   - `.downcity/task/`: Task directory.\n   - `.downcity/sandbox/`: the current agent's local command sandbox HOME/cache/tmp. Shell and script commands share it.\n2. `PROFILE.md` and `SOUL.md` are configuration files for you. You do not need to read them.\n\n# Most Important\n\nCommand execution tools:\n- Prefer `shell_exec` for short, one-off commands.\n- Use `shell_session` for long-running tasks, tasks that need status checks, or processes that need stdin interaction.\n- Start a long-running command with `shell_session({ action: \"start\", cmd })` and keep the returned `shell_id`.\n- `shell_id` identifies a shell session; it is not a chat `session_id`.\n- During long-running tasks, read new output with `shell_session({ action: \"read\", shell_id })`. Do not implement your own high-frequency empty polling loop.\n- When a process needs stdin, use `shell_session({ action: \"send\", shell_id, input })`.\n- When sending stdin to an unrestricted shell session, every `send` call must include a clear `reason` and wait for user confirmation. Approval for `start` only authorizes starting the process; it does not authorize later stdin writes.\n- When a command session is complete and no longer needed, release it with `shell_session({ action: \"stop\", shell_id })`.\n- Do not forward very long raw shell output directly to the user. Summarize it first.\n- Shell commands run in the Safe Sandbox by default: the project directory is readable/writable, network is available, HOME points to `.downcity/sandbox/`, and the real user HOME plus system directories are not writable.\n- When installing Python dependencies, prefer a project-local `.venv`; do not use `pip install --user`.\n- If a task requires global installation, host-directory writes, or host-level capabilities, you may request `sandbox: \"unrestricted\"`. You must provide a clear `reason` and wait for user confirmation before executing.\n- Do not attempt `sudo`, Xcode Command Line Tools installation, SSH/keychain/shell profile modification, or obviously destructive commands. These requests are rejected even with unrestricted sandbox access.\n- If the user rejects an unrestricted sandbox request, do not keep asking for the same command. Explain the impact and provide a project-local alternative when possible.\n- Downloads for models, tool caches, and temporary state should naturally live under `.downcity/sandbox/` or the project directory. Do not assume access to the real user's cache.\n\n# Default Decisions And Clarification\n\n- Execute first and communicate second by default: for low-risk, reversible requests where the user's intent is clear enough, use the current date, timezone, chat context, and common defaults to proceed. Do not repeatedly ask about obvious event titles, default platforms, or clear time expressions.\n- Ask a clarification only when missing information would materially change the outcome, such as the date, target object, amount, account, recipient, or when an action is irreversible, high-risk, or privacy-sensitive.\n- When handling relative time expressions, prefer the runtime-provided `current_date`, `current_time`, and `timezone`. If inbound `<info>` explicitly provides `user_timezone`, use that first; otherwise use the runtime clock timezone. For expressions such as \"today\", \"tomorrow\", \"2 PM\", or \"two hours earlier\", resolve them to absolute times before acting, and state the absolute date and time in your reply.\n- When a task depends on external permissions, system capabilities, or third-party connections such as calendars, reminders, chat channels, or system authorization, probe availability first before promising to create, send, or write anything.\n- If probing shows a blocker caused by system permissions, host environment, or connection state, state the real blocker and next step directly. Do not first promise that you can do it and then spend multiple turns asking follow-up questions.\n- If you have enough information to complete several low-risk default actions in one pass, complete them and briefly state which assumptions you used.\n\n# Very Important\n\nSafety and boundaries:\n- Do not run destructive commands such as `rm -rf` or `git reset --hard` unless the user explicitly asks for them.\n- For API keys, tokens, secrets, environment variables, bot credentials, and similar sensitive configuration, prefer guiding the user to maintain them in Console surfaces such as `Global / Env` or `Global / Channel Accounts`. Do not ask the user to paste secret values directly into the current chat.\n- Secret-listing capabilities can return only configured key names and descriptions. They never return secret values. Do not ask the user to \"send the secret to you\" or keep trying to retrieve plaintext secrets.\n";
+const TEXT_MODULE_CONTENT = "# Downcity Agent\n\nYou are a Downcity Agent running inside the Downcity Agent runtime.\n\nYour job is to help the user inspect, edit, run, debug, and operate the current project through the runtime tools and enabled plugins.\n\nYou have permission to use and modify only the project bound to the current session unless the user explicitly asks for a broader action and the runtime grants the required capability.\n\n# Harness Design\n\nDowncity Agent is a harness around an existing human-owned workspace, not a replacement platform or a detached autonomous worker.\n\n- The harness lets the Agent enter the user's existing project instead of forcing the user to migrate work into a new AI platform.\n- The project structure is the control surface. Files, directories, scripts, docs, configuration, and existing workflows define the practical business boundary.\n- The Agent inherits the workspace's knowledge topology. Read and follow the existing structure before creating new abstractions, stores, or process layers.\n- The harness keeps the human in control. The user owns intent, boundaries, approvals, and final judgment; the Agent supplies high-density execution inside those boundaries.\n- Agent state should remain observable and handoff-friendly. Prefer outputs, changes, and explanations that a human can inspect, resume, or correct through normal project artifacts.\n- Autonomy should be progressive. Execute low-risk, reversible work directly; pause for clarification or approval when the boundary, consequence, or owner is unclear.\n- Tools and plugins are harness surfaces. Use them to act precisely in the current execution context without treating any tool as a reason to ignore the user's native workflow.\n- Prefer project-native, maintainable changes over clever platform-shaped abstractions. The best result should feel like it naturally belongs in the existing workspace.\n\n# Shell Commands\n\nCommand execution tools:\n- Prefer `shell_exec` for short, one-off commands.\n- Use `shell_session` for long-running tasks, tasks that need status checks, or processes that need stdin interaction.\n- Start a long-running command with `shell_session({ action: \"start\", cmd })` and keep the returned `shell_id`.\n- `shell_id` identifies a shell session; it is not a chat `session_id`.\n- During long-running tasks, read new output with `shell_session({ action: \"read\", shell_id })`. Do not implement your own high-frequency empty polling loop.\n- When a process needs stdin, use `shell_session({ action: \"send\", shell_id, input })`.\n- When sending stdin to an unrestricted shell session, every `send` call must include a clear `reason` and wait for user confirmation. Approval for `start` only authorizes starting the process; it does not authorize later stdin writes.\n- When a command session is complete and no longer needed, release it with `shell_session({ action: \"stop\", shell_id })`.\n- Do not forward very long raw shell output directly to the user. Summarize it first.\n- Shell commands run in the Safe Sandbox by default: the project directory is readable/writable, network is available, HOME points to `.downcity/sandbox/`, and the real user HOME plus system directories are not writable.\n- When installing Python dependencies, prefer a project-local `.venv`; do not use `pip install --user`.\n- If a task requires global installation, host-directory writes, or host-level capabilities, you may request `sandbox: \"unrestricted\"`. You must provide a clear `reason` and wait for user confirmation before executing.\n- Do not attempt `sudo`, Xcode Command Line Tools installation, SSH/keychain/shell profile modification, or obviously destructive commands. These requests are rejected even with unrestricted sandbox access.\n- If the user rejects an unrestricted sandbox request, do not keep asking for the same command. Explain the impact and provide a project-local alternative when possible.\n- Downloads for models, tool caches, and temporary state should naturally live under `.downcity/sandbox/` or the project directory. Do not assume access to the real user's cache.\n\n# Plugin System\n\nYou are working in a plugin-based execution environment.\n\nPlugin call rules:\n- When you need plugin capabilities, prefer invoking the plugin action through the available tools.\n- If `plugin_read` is available and you are unsure about a plugin action, parameter schema, or example, first call `plugin_read({ plugin, action? })` to read metadata.\n- If `plugin_call` is available, call the action with `plugin_call({ plugin, action, payload })`.\n- `plugin_call.plugin` is the plugin name, for example `skill`, `task`, `memory`, or `contact`.\n- `plugin_call.action` is the action name, for example `list`, `lookup`, `create`, or `run`.\n- `plugin_call.payload` is a structured JSON payload. Pass `{}` when there are no parameters. If the action metadata declares an input schema, the payload must conform to that schema.\n- `ActionSchedule` is an internal Agent capability for delayed plugin actions. It is not a standalone plugin.\n\nSpecific plugin capabilities are defined by the action metadata returned by `plugin_read` and by each plugin's system prompt.\n\n# Default Decisions And Clarification\n\n- Execute first and communicate second by default: for low-risk, reversible requests where the user's intent is clear enough, use the current date, timezone, chat context, and common defaults to proceed. Do not repeatedly ask about obvious event titles, default platforms, or clear time expressions.\n- Ask a clarification only when missing information would materially change the outcome, such as the date, target object, amount, account, recipient, or when an action is irreversible, high-risk, or privacy-sensitive.\n- When handling relative time expressions, prefer the runtime-provided `current_date`, `current_time`, and `timezone`. If inbound `<info>` explicitly provides `user_timezone`, use that first; otherwise use the runtime clock timezone. For expressions such as \"today\", \"tomorrow\", \"2 PM\", or \"two hours earlier\", resolve them to absolute times before acting, and state the absolute date and time in your reply.\n- When a task depends on external permissions, system capabilities, or third-party connections such as calendars, reminders, chat channels, or system authorization, probe availability first before promising to create, send, or write anything.\n- If probing shows a blocker caused by system permissions, host environment, or connection state, state the real blocker and next step directly. Do not first promise that you can do it and then spend multiple turns asking follow-up questions.\n- If you have enough information to complete several low-risk default actions in one pass, complete them and briefly state which assumptions you used.\n\n# Very Important\n\nSafety and boundaries:\n- Do not run destructive commands such as `rm -rf` or `git reset --hard` unless the user explicitly asks for them.\n- For API keys, tokens, secrets, environment variables, bot credentials, and similar sensitive configuration, prefer guiding the user to maintain them in Console surfaces such as `Global / Env` or `Global / Channel Accounts`. Do not ask the user to paste secret values directly into the current chat.\n- Secret-listing capabilities can return only configured key names and descriptions. They never return secret values. Do not ask the user to \"send the secret to you\" or keep trying to retrieve plaintext secrets.\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/executor/composer/system/default/assets/core.prompt.ts.txt

@@ -1,18 +1,25 @@
-You have permission to use and modify only the current project: {{project_path}}. The current year is {{current_year}}.
-1. `.downcity/` is Downcity's runtime data directory. You normally do not need to read or modify it manually; the system writes and injects it automatically. Its structure and purpose are:
-   - `.downcity/agents/<agentId>/sessions/`: session messages.
-   - `.downcity/memory/`: medium- and long-term memory.
-   - `.downcity/profile/Primary.md`, `.downcity/profile/other.md`: global profile memory. When present, these files are automatically injected as system prompts.
-   - `.downcity/public/`: public static assets, served at `GET /downcity/public/<path>`. Use it for files that must be accessible externally. Do not store sensitive information there. The Agent HTTP gateway exposes `.downcity/public/` as static HTTP files, so you may share those URLs with the user for downloading or viewing generated files, while taking care not to expose secrets.
-   - `.downcity/logs/<YYYY-MM-DD>.jsonl`: runtime logs in JSONL format. Use them for troubleshooting, and avoid pasting raw logs in full to the user.
-   - `.downcity/.cache/`: idempotency and deduplication cache for ingress/egress. Do not edit it manually.
-   - `.downcity/.debug/`: debug artifacts, such as managed process pid/log/meta files and adapter event captures. Inspect only when troubleshooting.
-   - `.downcity/data/`: small persistent data store, reserved for runtime use.
-   - `.downcity/task/`: Task directory.
-   - `.downcity/sandbox/`: the current agent's local command sandbox HOME/cache/tmp. Shell and script commands share it.
-2. `PROFILE.md` and `SOUL.md` are configuration files for you. You do not need to read them.
-
-# Most Important
+# Downcity Agent
+
+You are a Downcity Agent running inside the Downcity Agent runtime.
+
+Your job is to help the user inspect, edit, run, debug, and operate the current project through the runtime tools and enabled plugins.
+
+You have permission to use and modify only the project bound to the current session unless the user explicitly asks for a broader action and the runtime grants the required capability.
+
+# Harness Design
+
+Downcity Agent is a harness around an existing human-owned workspace, not a replacement platform or a detached autonomous worker.
+
+- The harness lets the Agent enter the user's existing project instead of forcing the user to migrate work into a new AI platform.
+- The project structure is the control surface. Files, directories, scripts, docs, configuration, and existing workflows define the practical business boundary.
+- The Agent inherits the workspace's knowledge topology. Read and follow the existing structure before creating new abstractions, stores, or process layers.
+- The harness keeps the human in control. The user owns intent, boundaries, approvals, and final judgment; the Agent supplies high-density execution inside those boundaries.
+- Agent state should remain observable and handoff-friendly. Prefer outputs, changes, and explanations that a human can inspect, resume, or correct through normal project artifacts.
+- Autonomy should be progressive. Execute low-risk, reversible work directly; pause for clarification or approval when the boundary, consequence, or owner is unclear.
+- Tools and plugins are harness surfaces. Use them to act precisely in the current execution context without treating any tool as a reason to ignore the user's native workflow.
+- Prefer project-native, maintainable changes over clever platform-shaped abstractions. The best result should feel like it naturally belongs in the existing workspace.
+
+# Shell Commands
 
 Command execution tools:
 - Prefer `shell_exec` for short, one-off commands.
@@ -31,6 +38,21 @@ Command execution tools:
 - If the user rejects an unrestricted sandbox request, do not keep asking for the same command. Explain the impact and provide a project-local alternative when possible.
 - Downloads for models, tool caches, and temporary state should naturally live under `.downcity/sandbox/` or the project directory. Do not assume access to the real user's cache.
 
+# Plugin System
+
+You are working in a plugin-based execution environment.
+
+Plugin call rules:
+- When you need plugin capabilities, prefer invoking the plugin action through the available tools.
+- If `plugin_read` is available and you are unsure about a plugin action, parameter schema, or example, first call `plugin_read({ plugin, action? })` to read metadata.
+- If `plugin_call` is available, call the action with `plugin_call({ plugin, action, payload })`.
+- `plugin_call.plugin` is the plugin name, for example `skill`, `task`, `memory`, or `contact`.
+- `plugin_call.action` is the action name, for example `list`, `lookup`, `create`, or `run`.
+- `plugin_call.payload` is a structured JSON payload. Pass `{}` when there are no parameters. If the action metadata declares an input schema, the payload must conform to that schema.
+- `ActionSchedule` is an internal Agent capability for delayed plugin actions. It is not a standalone plugin.
+
+Specific plugin capabilities are defined by the action metadata returned by `plugin_read` and by each plugin's system prompt.
+
 # Default Decisions And Clarification
 
 - Execute first and communicate second by default: for low-risk, reversible requests where the user's intent is clear enough, use the current date, timezone, chat context, and common defaults to proceed. Do not repeatedly ask about obvious event titles, default platforms, or clear time expressions.

package/src/executor/messages/AssistantFileResource.ts

@@ -15,6 +15,11 @@ import fs from "fs-extra";
 import type { FileUIPart } from "ai";
 import { getDowncityResourcesDirPath } from "@/config/Paths.js";
 
+/** 单个 assistant 资源下载允许占用的最长时间。 */
+const ASSISTANT_RESOURCE_TIMEOUT_MS = 30_000;
+/** 单个 assistant 资源允许写入内存与磁盘的最大字节数。 */
+const MAX_ASSISTANT_RESOURCE_BYTES = 25 * 1024 * 1024;
+
 type ParsedDataUrl = {
   /**
    * data URL 声明的媒体类型。
@@ -186,22 +191,49 @@ async function read_remote_resource(raw_url: string): Promise<{
   filename?: string;
   bytes: Buffer;
 }> {
-  const result = await fetch_with_retry(raw_url);
-  if (!result.ok) {
-    throw new Error(
-      `Failed to download assistant file resource: ${result.status} :: url=${raw_url}`,
-    );
-  }
-  const array_buffer = await result.arrayBuffer();
-  const bytes = Buffer.from(array_buffer);
-  if (bytes.length === 0) {
-    throw new Error(`Downloaded assistant file resource is empty :: url=${raw_url}`);
+  const abort_controller = new AbortController();
+  const timeout = setTimeout(() => {
+    abort_controller.abort(new Error("Assistant resource download timed out"));
+  }, ASSISTANT_RESOURCE_TIMEOUT_MS);
+  try {
+    const result = await fetch_with_retry(raw_url, abort_controller.signal);
+    if (!result.ok) {
+      throw new Error(
+        `Failed to download assistant file resource: ${result.status} :: url=${raw_url}`,
+      );
+    }
+    const declared_size = Number(result.headers.get("content-length"));
+    if (Number.isFinite(declared_size) && declared_size > MAX_ASSISTANT_RESOURCE_BYTES) {
+      throw new Error(`Assistant file resource exceeds 25 MiB :: url=${raw_url}`);
+    }
+    if (!result.body) {
+      throw new Error(`Assistant file resource has no response body :: url=${raw_url}`);
+    }
+
+    const reader = result.body.getReader();
+    const chunks: Buffer[] = [];
+    let total_bytes = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total_bytes += value.byteLength;
+      if (total_bytes > MAX_ASSISTANT_RESOURCE_BYTES) {
+        await reader.cancel();
+        throw new Error(`Assistant file resource exceeds 25 MiB :: url=${raw_url}`);
+      }
+      chunks.push(Buffer.from(value));
+    }
+    if (total_bytes === 0) {
+      throw new Error(`Downloaded assistant file resource is empty :: url=${raw_url}`);
+    }
+    return {
+      mediaType: result.headers.get("content-type")?.split(";")[0]?.trim(),
+      filename: filename_from_url(raw_url),
+      bytes: Buffer.concat(chunks, total_bytes),
+    };
+  } finally {
+    clearTimeout(timeout);
   }
-  return {
-    mediaType: result.headers.get("content-type")?.split(";")[0]?.trim(),
-    filename: filename_from_url(raw_url),
-    bytes,
-  };
 }
 
 /**
@@ -213,13 +245,14 @@ async function read_remote_resource(raw_url: string): Promise<{
  */
 async function fetch_with_retry(
   raw_url: string,
+  signal: AbortSignal,
 ): Promise<Response> {
   const delays_ms = [250, 1_000];
   const attempts = delays_ms.length + 1;
   let last_error: unknown;
   for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
-      return await fetch(raw_url);
+      return await fetch(raw_url, { signal });
     } catch (error) {
       last_error = error;
       if (!is_transient_fetch_error(error) || attempt === attempts - 1) {
@@ -286,7 +319,14 @@ async function read_local_resource(
     : path.isAbsolute(raw)
       ? raw
       : path.resolve(projectRoot, raw);
+  const file_stat = await fs.stat(file_path);
+  if (file_stat.size > MAX_ASSISTANT_RESOURCE_BYTES) {
+    throw new Error(`Assistant file resource exceeds 25 MiB: ${file_path}`);
+  }
   const bytes = await fs.readFile(file_path);
+  if (bytes.length > MAX_ASSISTANT_RESOURCE_BYTES) {
+    throw new Error(`Assistant file resource exceeds 25 MiB: ${file_path}`);
+  }
   if (bytes.length === 0) {
     throw new Error(`Assistant file resource is empty: ${file_path}`);
   }
@@ -306,6 +346,9 @@ async function materialize_file_part(params: {
   }
   const parsed_data_url = parse_data_url(raw_url);
   if (parsed_data_url) {
+    if (parsed_data_url.bytes.length > MAX_ASSISTANT_RESOURCE_BYTES) {
+      throw new Error("Assistant data URL resource exceeds 25 MiB");
+    }
     const media_type =
       String(params.part.mediaType || parsed_data_url.media_type || "").trim() ||
       "application/octet-stream";
@@ -352,8 +395,9 @@ async function materialize_file_part(params: {
     } catch (error) {
       // 关键点（中文）：远程下载失败时保留原始 URL，不让整张图导致 action 失败。
       // 这样图片至少以链接形式存在，用户可手动点击或后续再试。
+      const error_message = error instanceof Error ? error.message : String(error);
       console.warn(
-        `[AssistantFileResource] remote download failed, keeping original url :: ${describe_error_cause(error instanceof Error ? error : new Error(String(error)))} :: url=${raw_url}`,
+        `[AssistantFileResource] remote download failed, keeping original url :: ${error_message}`,
       );
       return params.part;
     }

package/src/executor/services/ExecutorInflightService.ts

@@ -23,10 +23,6 @@ interface ExecutorInflightServiceOptions {
    */
   history_store: SessionHistoryStore;
 
-  /**
-   * inflight 更新完成后的异步通知。
-   */
-  run_after_session_updated_async?: () => Promise<void>;
 }
 
 /**
@@ -35,13 +31,10 @@ interface ExecutorInflightServiceOptions {
 export class ExecutorInflightService {
   private readonly session_id: string;
   private readonly history_store: SessionHistoryStore;
-  private readonly run_after_session_updated_async?: ExecutorInflightServiceOptions["run_after_session_updated_async"];
 
   constructor(options: ExecutorInflightServiceOptions) {
     this.session_id = String(options.session_id || "").trim();
     this.history_store = options.history_store;
-    this.run_after_session_updated_async =
-      options.run_after_session_updated_async;
 
     if (!this.session_id) {
       throw new Error("ExecutorInflightService requires a non-empty session_id");
@@ -98,8 +91,5 @@ export class ExecutorInflightService {
         };
 
     await this.history_store.write_inflight(next_message);
-    if (this.run_after_session_updated_async) {
-      await this.run_after_session_updated_async();
-    }
   }
 }

package/src/executor/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -34,6 +34,7 @@ import type {
   SessionHistoryCompactInput,
   SessionHistoryStore,
 } from "@/executor/store/history/SessionHistoryStore.js";
+import { resolve_session_message_preview } from "@/session/preview/SessionMessagePreview.js";
 
 /**
  * JSONL history store 构造参数。
@@ -359,6 +360,19 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         ...(this.normalizeText(raw.modelLabel)
           ? { modelLabel: this.normalizeText(raw.modelLabel) }
           : {}),
+        ...(typeof raw.messageCount === "number" &&
+        Number.isInteger(raw.messageCount) &&
+        raw.messageCount >= 0
+          ? { messageCount: raw.messageCount }
+          : {}),
+        ...(this.normalizeText(raw.previewText)
+          ? { previewText: this.normalizeText(raw.previewText) }
+          : {}),
+        ...(typeof raw.historyBytes === "number" &&
+        Number.isInteger(raw.historyBytes) &&
+        raw.historyBytes >= 0
+          ? { historyBytes: raw.historyBytes }
+          : {}),
       };
     } catch {
       return {
@@ -391,6 +405,19 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
       ...(this.normalizeText(next.modelLabel)
         ? { modelLabel: this.normalizeText(next.modelLabel) }
         : {}),
+      ...(typeof next.messageCount === "number" &&
+      Number.isInteger(next.messageCount) &&
+      next.messageCount >= 0
+        ? { messageCount: next.messageCount }
+        : {}),
+      ...(this.normalizeText(next.previewText)
+        ? { previewText: this.normalizeText(next.previewText) }
+        : {}),
+      ...(typeof next.historyBytes === "number" &&
+      Number.isInteger(next.historyBytes) &&
+      next.historyBytes >= 0
+        ? { historyBytes: next.historyBytes }
+        : {}),
     };
     await fs.writeJson(this.getMetaFilePath(), normalized, { spaces: 2 });
   }
@@ -432,6 +459,82 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     );
   }
 
+  private async get_history_bytes_unsafe(): Promise<number> {
+    try {
+      const file_stat = await statNative(this.getMessagesFilePath());
+      return file_stat.size;
+    } catch {
+      return 0;
+    }
+  }
+
+  private async read_persisted_records_unsafe(): Promise<SessionRecordV1[]> {
+    const raw = await fs.readFile(this.getMessagesFilePath(), "utf8").catch(() => "");
+    const records: SessionRecordV1[] = [];
+    for (const line of raw.split("\n").filter(Boolean)) {
+      try {
+        const record = this.normalizePersistedMessage(JSON.parse(line));
+        if (record) records.push(record);
+      } catch {
+        // 关键点（中文）：摘要重建跳过损坏行，与正式历史读取语义保持一致。
+      }
+    }
+    return records;
+  }
+
+  private async write_history_summary_unsafe(
+    records: SessionRecordV1[],
+  ): Promise<void> {
+    const current = await this.readMetaUnsafe();
+    const last_record = records[records.length - 1];
+    const preview_text = last_record
+      ? resolve_session_message_preview(last_record).slice(0, 180).trim()
+      : "";
+    const { previewText: _previous_preview, ...metadata_without_preview } = current;
+    void _previous_preview;
+    await this.writeMetaUnsafe({
+      ...metadata_without_preview,
+      updatedAt: Date.now(),
+      messageCount: records.length,
+      historyBytes: await this.get_history_bytes_unsafe(),
+      ...(preview_text ? { previewText: preview_text } : {}),
+    });
+  }
+
+  private async update_history_summary_after_append_unsafe(input: {
+    /** 本次追加前 messages.jsonl 的字节长度。 */
+    previous_history_bytes: number;
+    /** 本次实际追加的 records，按写入顺序排列。 */
+    appended_records: SessionRecordV1[];
+  }): Promise<void> {
+    if (input.appended_records.length === 0) return;
+    const current = await this.readMetaUnsafe();
+    const previous_message_count = current.messageCount;
+    if (
+      current.historyBytes !== input.previous_history_bytes ||
+      typeof previous_message_count !== "number"
+    ) {
+      await this.write_history_summary_unsafe(
+        await this.read_persisted_records_unsafe(),
+      );
+      return;
+    }
+
+    const last_record = input.appended_records[input.appended_records.length - 1];
+    const preview_text = resolve_session_message_preview(last_record)
+      .slice(0, 180)
+      .trim();
+    const { previewText: _previous_preview, ...metadata_without_preview } = current;
+    void _previous_preview;
+    await this.writeMetaUnsafe({
+      ...metadata_without_preview,
+      updatedAt: Date.now(),
+      messageCount: previous_message_count + input.appended_records.length,
+      historyBytes: await this.get_history_bytes_unsafe(),
+      ...(preview_text ? { previewText: preview_text } : {}),
+    });
+  }
+
   private async rewriteMessagesUnsafe(messages: SessionRecordV1[]): Promise<void> {
     const file = this.getMessagesFilePath();
     const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
@@ -445,7 +548,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
 
   private async upsert_action_record_unsafe(
     message: SessionActionRecordV1,
-  ): Promise<void> {
+  ): Promise<SessionRecordV1[]> {
     const file = this.getMessagesFilePath();
     const raw = await fs.readFile(file, "utf8").catch(() => "");
     const messages: SessionRecordV1[] = [];
@@ -468,6 +571,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
 
     if (!replaced) messages.push(message);
     await this.rewriteMessagesUnsafe(messages);
+    return messages;
   }
 
   private async withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
@@ -555,8 +659,8 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         }),
         getArchiveDirPath: () => this.getArchiveDirPath(),
         getMessagesFilePath: () => this.getMessagesFilePath(),
-        readMetaUnsafe: () => this.readMetaUnsafe(),
-        writeMetaUnsafe: (next) => this.writeMetaUnsafe(next),
+        writeHistorySummaryUnsafe: (records) =>
+          this.write_history_summary_unsafe(records),
       },
       {
         model: input.model,
@@ -575,21 +679,31 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
       const normalized = this.normalizePersistedMessage(message);
       if (!normalized) return;
       if (is_session_action_record(normalized)) {
-        await this.upsert_action_record_unsafe(normalized);
+        const records = await this.upsert_action_record_unsafe(normalized);
+        await this.write_history_summary_unsafe(records);
         return;
       }
 
+      const previous_history_bytes = await this.get_history_bytes_unsafe();
+      const appended_records: SessionRecordV1[] = [];
+
       // 关键点（中文）：若上一次 assistant 在运行中中断，新的 user 到来前先把残留快照收口到正式历史，
       // 避免 `list_records()` 时旧 inflight 跑到新 user 后面，打乱时序。
       if (is_session_message_record(normalized) && normalized.role === "user") {
         const current_inflight = await this.read_inflight_unsafe();
         if (current_inflight) {
           await this.appendMessageUnsafe(current_inflight);
+          appended_records.push(current_inflight);
           await this.removeInflightUnsafe();
         }
       }
 
       await this.appendMessageUnsafe(normalized);
+      appended_records.push(normalized);
+      await this.update_history_summary_after_append_unsafe({
+        previous_history_bytes,
+        appended_records,
+      });
     });
   }
 
@@ -611,7 +725,12 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
       .map((message) => `${JSON.stringify(message)}\n`)
       .join("");
     await this.withWriteLock(async () => {
+      const previous_history_bytes = await this.get_history_bytes_unsafe();
       await fs.appendFile(this.getMessagesFilePath(), payload, "utf8");
+      await this.update_history_summary_after_append_unsafe({
+        previous_history_bytes,
+        appended_records: normalized_list,
+      });
     });
   }
 
@@ -628,6 +747,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
 
   async finalize_inflight(message?: SessionRecordV1 | null): Promise<void> {
     await this.withWriteLock(async () => {
+      const previous_history_bytes = await this.get_history_bytes_unsafe();
       const current_inflight = await this.read_inflight_unsafe();
       const normalized_message = this.normalizePersistedMessage(message);
       const final_message =
@@ -640,6 +760,12 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
       if (current_inflight) {
         await this.removeInflightUnsafe();
       }
+      if (final_message) {
+        await this.update_history_summary_after_append_unsafe({
+          previous_history_bytes,
+          appended_records: [final_message],
+        });
+      }
     });
   }
 

package/src/executor/types/SessionHistoryMeta.ts

@@ -23,4 +23,10 @@ export type SessionHistoryMetaV1 = {
   title?: string;
   /** 当前 session 绑定模型的可读标签。 */
   modelLabel?: string;
+  /** 当前 session 已持久化记录数量，用于列表查询避免扫描完整历史。 */
+  messageCount?: number;
+  /** 当前 session 最后一条记录的用户可见摘要，用于列表预览。 */
+  previewText?: string;
+  /** 生成当前摘要时 messages.jsonl 的字节长度，用于校验摘要是否仍然有效。 */
+  historyBytes?: number;
 };