@downcity/agent 1.1.196 → 1.1.199

package/bin/session/storage/Persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Persistence.d.ts","sourceRoot":"","sources":["../../../src/session/storage/Persistence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAM9E;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,aAAa,EAAE,0BAA0B,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,+BACf,SAAQ,0BAA0B;IAClC;;OAEG;IACH,QAAQ,EAAE;QACR,sBAAsB,CAAC,MAAM,EAAE;YAC7B;;eAEG;YACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;YAClC;;eAEG;YACH,YAAY,CAAC,EAAE,MAAM,CAAC;SACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACnB,CAAC;IACF;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,+BAA+B,GACtC,OAAO,CAAC,IAAI,CAAC,CASf"}
+{"version":3,"file":"Persistence.d.ts","sourceRoot":"","sources":["../../../src/session/storage/Persistence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAM9E;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,aAAa,EAAE,0BAA0B,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,+BACf,SAAQ,0BAA0B;IAClC;;OAEG;IACH,QAAQ,EAAE;QACR,sBAAsB,CAAC,MAAM,EAAE;YAC7B;;eAEG;YACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;YAClC;;eAEG;YACH,YAAY,CAAC,EAAE,MAAM,CAAC;SACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACnB,CAAC;IACF;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACjD;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,+BAA+B,GACtC,OAAO,CAAC,IAAI,CAAC,CASf"}

package/bin/session/storage/Persistence.js.map

@@ -1 +1 @@
-{"version":3,"file":"Persistence.js","sourceRoot":"","sources":["../../../src/session/storage/Persistence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAGvF,OAAO,EAAE,sBAAsB,EAAE,MAAM,mDAAmD,CAAC;AAE3F,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAsDvC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAkC;IAElC,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC;QACxC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAC;IACH,MAAM,IAAI,GAAyB;QACjC,GAAG,OAAO;QACV,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EACP,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QACxE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU;YACjC,CAAC,CAAC;gBACE,UAAU,EAAE,MAAM,CAAC,aAAa,CAAC,UAAU;aAC5C;YACH,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IACF,MAAM,oBAAoB,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAuC;IAEvC,MAAM,sBAAsB,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC,QAAQ;QACvB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,YAAY,EAAE,MAAM,CAAC,gBAAgB;YACnC,CAAC,CAAC,wBAAwB,CAAC,MAAM,CAAC,gBAAgB,CAAC;YACnD,CAAC,CAAC,SAAS;KACd,CAAC,CAAC;IACH,MAAM,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"Persistence.js","sourceRoot":"","sources":["../../../src/session/storage/Persistence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAMvF,OAAO,EAAE,sBAAsB,EAAE,MAAM,mDAAmD,CAAC;AAE3F,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAsDvC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAkC;IAElC,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC;QACxC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAC;IACH,MAAM,IAAI,GAAyB;QACjC,GAAG,OAAO;QACV,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EACP,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;QACxE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU;YACjC,CAAC,CAAC;gBACE,UAAU,EAAE,MAAM,CAAC,aAAa,CAAC,UAAU;aAC5C;YACH,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IACF,MAAM,oBAAoB,CAAC;QACzB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAuC;IAEvC,MAAM,sBAAsB,CAAC;QAC3B,MAAM,EAAE,MAAM,CAAC,QAAQ;QACvB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,YAAY,EAAE,MAAM,CAAC,gBAAgB;YACnC,CAAC,CAAC,wBAAwB,CAAC,MAAM,CAAC,gBAAgB,CAAC;YACnD,CAAC,CAAC,SAAS;KACd,CAAC,CAAC;IACH,MAAM,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/bin/types/sdk/AgentSessionTurn.d.ts

@@ -6,7 +6,7 @@
  * - 同一个 turn 可以吸收多条 prompt，因此多个 prompt 可能返回相同 `id` 的 turn handle。
  * - 增量过程继续通过 `session.subscribe()` 观察；turn handle 只负责等待最终完成结果。
  */
-import type { SessionMessageV1 } from "../../executor/types/SessionMessages.js";
+import type { SessionModelMessageV1 } from "../../executor/types/SessionMessages.js";
 /**
  * 单个 Session turn 的最终结果。
  */
@@ -30,7 +30,7 @@ export interface AgentSessionTurnResult {
      * - `turn.finished` 返回的结果以这条消息作为最终事实源。
      * - transport / runtime service 若需要读取最终结构化输出，应优先消费这里。
      */
-    assistantMessage?: SessionMessageV1;
+    assistantMessage?: SessionModelMessageV1;
     /**
      * 当前 turn 失败时的错误文本。
      */

package/bin/types/sdk/AgentSessionTurn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentSessionTurn.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionTurn.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;;OAMG;IACH,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEtC;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC3C"}
+{"version":3,"file":"AgentSessionTurn.d.ts","sourceRoot":"","sources":["../../../src/types/sdk/AgentSessionTurn.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IAEzC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;;OAMG;IACH,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEtC;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC3C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.196",
+  "version": "1.1.199",
   "type": "module",
   "description": "Downcity Agent 运行时 — 单 Agent 执行壳与本机 RPC 能力",
   "main": "./bin/index.js",
@@ -17,8 +17,8 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.48",
-    "@downcity/shell": "^0.1.66",
-    "@downcity/type": "0.1.99",
+    "@downcity/shell": "^0.1.68",
+    "@downcity/type": "0.1.101",
     "ai": "^6.0.193",
     "commander": "^15.0.0",
     "dotenv": "^17.4.2",

package/scripts/session-operation-message.test.mjs

@@ -2,7 +2,7 @@
  * @file 验证 operation message 的持久化、模型输入过滤与 timeline 投影。
  *
  * 关键点（中文）
- * - operation message 会作为 UIMessage 写入 JSONL。
+ * - operation message 会作为 operation role 消息写入 JSONL。
  * - history composer 组装 LLM 输入时必须过滤 operation message。
  * - timeline view 可以把 operation message 投影成前端可识别的 operation 事件。
  */
@@ -42,8 +42,8 @@ test("operation message is persisted but filtered from LLM history", async () =>
       operation: {
         operationId: "op-1",
         name: "compacting",
-        status: "started",
-        label: "Compacting session history",
+        status: "finished",
+        label: "Session history compacted",
         turnId: "turn-1",
       },
       metadata: { sessionId: session_id },
@@ -60,6 +60,7 @@ test("operation message is persisted but filtered from LLM history", async () =>
 
   const persisted_messages = await store.list();
   assert.equal(persisted_messages.length, 3);
+  assert.equal(persisted_messages[1].role, "operation");
   assert.equal(persisted_messages[1].metadata.kind, "operation");
   assert.equal(persisted_messages[1].metadata.operation.operationId, "op-1");
 
@@ -80,8 +81,22 @@ test("operation message is persisted but filtered from LLM history", async () =>
   assert.equal(timeline_events[0].role, "operation");
   assert.equal(timeline_events[0].operationId, "op-1");
   assert.equal(timeline_events[0].operationName, "compacting");
-  assert.equal(timeline_events[0].operationStatus, "started");
-  assert.equal(timeline_events[0].text, "Compacting session history");
+  assert.equal(timeline_events[0].operationStatus, "finished");
+  assert.equal(timeline_events[0].text, "Session history compacted");
+
+  const hidden_started_events = toSessionTimelineEvents(
+    store.operation({
+      operation: {
+        operationId: "op-started",
+        name: "compacting",
+        status: "started",
+        label: "Compacting session history",
+      },
+      metadata: { sessionId: session_id },
+      id: "op:started",
+    }),
+  );
+  assert.deepEqual(hidden_started_events, []);
 });
 
 test("session.set persists and publishes model-switching operations", async () => {
@@ -120,7 +135,7 @@ test("session.set persists and publishes model-switching operations", async () =
     );
     assert.deepEqual(
       operation_events.map((event) => `${event.operationName}:${event.operationStatus}`),
-      ["model-switching:started", "model-switching:finished"],
+      ["model-switching:finished"],
     );
   } finally {
     await agent.dispose();
@@ -168,14 +183,14 @@ test("session.fork persists and publishes history-forking operations on source s
     );
     assert.deepEqual(
       source_fork_operations.map((event) => event.operationStatus),
-      ["started", "finished"],
+      ["finished"],
     );
 
     const forked_history = await forked.history({ view: "timeline" });
     const forked_model_operations = forked_history.items.filter(
       (item) => item.operationName === "model-switching",
     );
-    assert.equal(forked_model_operations.length, 2);
+    assert.equal(forked_model_operations.length, 1);
   } finally {
     await agent.dispose();
   }

package/src/executor/composer/context/LocalSessionContextComposer.ts

@@ -12,7 +12,10 @@ import type {
   SessionContextComposer,
   SessionContextComposeResult,
 } from "@executor/composer/context/SessionContextComposer.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { Tool } from "ai";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
@@ -147,7 +150,7 @@ export class LocalSessionContextComposer implements SessionContextComposer {
   buildFallbackAssistantMessage(
     text: string,
     run_context: SessionRunContext,
-  ): SessionMessageV1 {
+  ): SessionModelMessageV1 {
     const sessionId = String(
       run_context.sessionId || this.sessionId || "",
     ).trim();

package/src/executor/composer/context/SessionContextComposer.ts

@@ -7,7 +7,10 @@
  */
 
 import type { ModelMessage, Tool } from "ai";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
@@ -76,5 +79,5 @@ export interface SessionContextComposer {
   buildFallbackAssistantMessage(
     text: string,
     run_context: SessionRunContext,
-  ): SessionMessageV1;
+  ): SessionModelMessageV1;
 }

package/src/executor/core-engine/CoreEngineRunner.ts

@@ -41,7 +41,10 @@ import type {
   SessionExecuteInput,
   SessionRunResult,
 } from "@/executor/types/SessionRun.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 
 const TURN_STOPPED_MESSAGE = "Turn stopped";
 
@@ -61,9 +64,9 @@ function build_file_part_key(part: FileUIPart): string {
  * 把 tool/plugin 运行期产生的 file parts 并入最终 assistant UIMessage。
  */
 function mergePendingAssistantFileParts(
-  message: SessionMessageV1,
+  message: SessionModelMessageV1,
   parts: FileUIPart[],
-): SessionMessageV1 {
+): SessionModelMessageV1 {
   if (!Array.isArray(parts) || parts.length === 0) return message;
   const current_parts = Array.isArray(message.parts) ? message.parts : [];
   const seen = new Set<string>();
@@ -151,7 +154,7 @@ export class CoreEngineRunner {
       : [];
     const tools = input.execute_input.tools;
     let last_observed_stream_error: unknown = undefined;
-    let final_assistant_ui_message: SessionMessageV1 | null = null;
+    let final_assistant_ui_message: SessionModelMessageV1 | null = null;
 
     try {
       const message_state = await CoreEngineMessageState.create({

package/src/executor/core-engine/CoreEngineSignals.ts

@@ -12,7 +12,7 @@ import {
   isTextUIPart,
   isToolUIPart,
 } from "ai";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { JsonObject } from "@/types/common/Json.js";
 
 /**
@@ -192,7 +192,7 @@ export function summarizeStepForDebug(stepResult: unknown): JsonObject {
  * 汇总最终 assistant UI 消息的调试摘要。
  */
 export function summarizeUiMessageForDebug(
-  message: SessionMessageV1 | null | undefined,
+  message: SessionModelMessageV1 | null | undefined,
 ): JsonObject {
   const parts = Array.isArray(message?.parts) ? message.parts : [];
   const text = parts
@@ -230,9 +230,9 @@ export function summarizeUiMessageForDebug(
  * - 多 step 场景下，最终 assistant message 需要把各 step 的 UI part 串起来。
  */
 export function mergeAssistantUiMessages(
-  base: SessionMessageV1 | null,
-  incoming: SessionMessageV1,
-): SessionMessageV1 {
+  base: SessionModelMessageV1 | null,
+  incoming: SessionModelMessageV1,
+): SessionModelMessageV1 {
   if (!base) return incoming;
   const baseMetadata = base.metadata;
   const incomingMetadata = incoming.metadata;
@@ -254,7 +254,7 @@ export function mergeAssistantUiMessages(
 }
 
 function pickIncompleteToolParts(
-  message: SessionMessageV1 | null | undefined,
+  message: SessionModelMessageV1 | null | undefined,
 ): Array<{
   toolName: string;
   state: string;
@@ -304,7 +304,7 @@ export function buildIncompleteResponseRecoveryNudge(
  */
 export function detectIncompleteResponse(params: {
   stepResult: unknown;
-  assistantMessage: SessionMessageV1 | null | undefined;
+  assistantMessage: SessionModelMessageV1 | null | undefined;
 }): {
   reason: string;
   details: JsonObject;

package/src/executor/core-engine/CoreEngineUiStreamCollector.ts

@@ -10,7 +10,7 @@
 import type { streamText } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
 import type { SessionUiMessageChunkCallback } from "@/executor/types/SessionRun.js";
 import { generateId } from "@/utils/Id.js";
 import {
@@ -37,7 +37,7 @@ export async function collectFinalAssistantMessageFromUiStream(params: {
   /**
    * 构造 fallback assistant 消息的工厂函数。
    */
-  buildFallbackAssistantMessage: (text: string) => SessionMessageV1;
+  buildFallbackAssistantMessage: (text: string) => SessionModelMessageV1;
   /**
    * UI stream chunk 回调。
    */
@@ -50,12 +50,12 @@ export async function collectFinalAssistantMessageFromUiStream(params: {
    * - 此时仍应尽量用已经收到的 text delta 构造可持久化 assistant 消息。
    */
   abortSignal?: AbortSignal;
-}): Promise<SessionMessageV1> {
-  let streamedAssistantMessage: SessionMessageV1 | null = null;
+}): Promise<SessionModelMessageV1> {
+  let streamedAssistantMessage: SessionModelMessageV1 | null = null;
   let uiFinishSummary: JsonObject | null = null;
   let streamed_text = "";
 
-  const uiStream = params.result.toUIMessageStream<SessionMessageV1>({
+  const uiStream = params.result.toUIMessageStream<SessionModelMessageV1>({
     // 关键点（中文）：SDK stream 需要 reasoning 旁路事件时可直接消费；最终落盘仍由 responseMessage 收敛。
     originalMessages: [],
     generateMessageId: () => `a:${params.sessionId}:${generateId()}`,

package/src/executor/messages/AssistantResultPersistence.ts

@@ -7,7 +7,10 @@
  * - 运行中 step/tool 的持久化由 inflight 快照承担；run 结束时只关心最终 assistant 如何收口。
  */
 
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import { resolveAssistantMessageForPersistence } from "@/executor/messages/UserVisibleText.js";
 
 /**
@@ -40,7 +43,7 @@ export interface PersistAssistantResultParams {
   /**
    * 本轮执行得到的 assistant message。
    */
-  assistantMessage: SessionMessageV1 | null | undefined;
+  assistantMessage: SessionModelMessageV1 | null | undefined;
   /**
    * 可选兜底文本。
    *
@@ -65,7 +68,7 @@ export function buildAssistantResultPersistencePayload(
   /**
    * 已构造好的完整 assistant message。
    */
-  message?: SessionMessageV1 | null;
+  message?: SessionModelMessageV1 | null;
   /**
    * 允许写入的兜底文本。
    */

package/src/executor/messages/SessionAttachmentMapper.ts

@@ -17,7 +17,10 @@ import {
   type FileUIPart,
 } from "ai";
 import type { SessionUserMessagePart } from "@/types/sdk/AgentSessionPrompt.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import { parseChatMessageMarkup } from "@/executor/messages/ChatMessageMarkup.js";
 
 /**
@@ -171,12 +174,12 @@ export async function hydrateUserPromptFileParts(
  * - 新历史保留 Agent 根目录相对路径，旧历史的 `file://` 仍继续兼容。
  */
 export async function hydrateFileUrlPartsForModel(
-  messages: SessionMessageV1[],
+  messages: SessionModelMessageV1[],
   projectRoot?: string,
-): Promise<SessionMessageV1[]> {
+): Promise<SessionModelMessageV1[]> {
   if (!Array.isArray(messages) || messages.length === 0) return messages;
 
-  const out: SessionMessageV1[] = [];
+  const out: SessionModelMessageV1[] = [];
   for (const message of messages) {
     const parts = Array.isArray(message?.parts) ? message.parts : [];
     if (!parts.some((part) => isFileUIPart(part as FileUIPart))) {
@@ -206,13 +209,13 @@ export async function hydrateFileUrlPartsForModel(
  * 在 user 消息上注入 FileUIPart，以便多模态模型直接消费本地附件。
  */
 export async function injectFilePartsFromAttachments(
-  messages: SessionMessageV1[],
+  messages: SessionModelMessageV1[],
   projectRoot?: string,
-): Promise<SessionMessageV1[]> {
+): Promise<SessionModelMessageV1[]> {
   if (!Array.isArray(messages) || messages.length === 0) return messages;
 
   const root = path.resolve(String(projectRoot || "").trim() || process.cwd());
-  const out: SessionMessageV1[] = [];
+  const out: SessionModelMessageV1[] = [];
 
   for (const message of messages) {
     if (!message || typeof message !== "object" || message.role !== "user") {

package/src/executor/messages/SessionMessageCodec.ts

@@ -15,7 +15,7 @@ import {
   type ToolSet,
 } from "ai";
 import {
-  isSessionOperationMessage,
+  isSessionModelMessage,
   type SessionMessageV1,
 } from "@/executor/types/SessionMessages.js";
 import {
@@ -81,9 +81,7 @@ export async function toModelMessages(
   if (!Array.isArray(messages) || messages.length === 0) return [];
 
   // operation message 只服务前端时间线，不能传入模型。
-  const model_messages = messages.filter(
-    (message) => !isSessionOperationMessage(message),
-  );
+  const model_messages = messages.filter(isSessionModelMessage);
   if (model_messages.length === 0) return [];
 
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。

package/src/executor/messages/SessionMessageLog.ts

@@ -9,12 +9,14 @@
 
 import { isTextUIPart } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type { SessionModelMessageV1 } from "@/executor/types/SessionMessages.js";
 
 /**
  * 从 UI message 中提取 assistant 文本部分。
  */
-export function extractAssistantTextForLog(message: SessionMessageV1): string {
+export function extractAssistantTextForLog(
+  message: SessionModelMessageV1,
+): string {
   if (!Array.isArray(message.parts)) return "";
   return message.parts
     .filter(isTextUIPart)
@@ -28,7 +30,7 @@ export function extractAssistantTextForLog(message: SessionMessageV1): string {
  */
 export async function logAssistantMessageNow(
   logger: Logger,
-  message: SessionMessageV1,
+  message: SessionModelMessageV1,
 ): Promise<void> {
   const text = extractAssistantTextForLog(message) || "-";
   const normalized = text.replace(/\r\n/g, "\n");

package/src/executor/messages/UserVisibleText.ts

@@ -7,7 +7,11 @@
  * - 因此需要一个稳定的、与 Agent 解耦的提取逻辑（属于 chat/egress 语义）
  */
 
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import {
+  isSessionModelMessage,
+  type SessionMessageV1,
+  type SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import {
   extractTextFromUiMessage,
   extractToolCallsFromUiMessage,
@@ -22,8 +26,9 @@ import {
  */
 export function resolveAssistantMessageForPersistence(
   message: SessionMessageV1 | null | undefined,
-): SessionMessageV1 | null {
+): SessionModelMessageV1 | null {
   if (!message || typeof message !== "object") return null;
+  if (!isSessionModelMessage(message)) return null;
   return message;
 }
 
@@ -37,6 +42,7 @@ export function resolveAssistantMessageForPersistence(
 export function pickLastSuccessfulChatSendText(
   message: SessionMessageV1 | null | undefined,
 ): string {
+  if (!isSessionModelMessage(message)) return "";
   const toolCalls = extractToolCallsFromUiMessage(message);
   // 关键点（中文）：优先从 chat_send 的 input.text 还原"用户可见回复"。
   for (let i = toolCalls.length - 1; i >= 0; i -= 1) {

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

@@ -218,7 +218,9 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     if (!input || typeof input !== "object") return null;
     const candidate = input as Partial<SessionMessageV1>;
     const role = String(candidate.role || "");
-    if (role !== "user" && role !== "assistant") return null;
+    if (role !== "user" && role !== "assistant" && role !== "operation") {
+      return null;
+    }
     if (!Array.isArray(candidate.parts)) return null;
     return candidate as SessionMessageV1;
   }
@@ -687,7 +689,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     const { ts, ...metadata } = input.metadata;
     return {
       id: input.id || `op:${this.sessionId}:${operation.operationId}:${generateId()}`,
-      role: "assistant",
+      role: "operation",
       metadata: {
         v: 1,
         ts: typeof ts === "number" ? ts : Date.now(),

package/src/executor/types/SessionMessages.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 这里统一描述 session 消息落盘格式与元信息结构。
- * - session 的唯一事实源是 `UIMessage[]`，不会再维护第二套平行消息结构。
+ * - session 的唯一事实源是消息 JSONL，模型消息继续使用 AI SDK `UIMessage`。
  * - 这些类型会被 history Store、history Composer、compact、control UI、task runtime 共同复用。
  */
 
@@ -16,8 +16,9 @@ import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperat
  *
  * 关键点（中文）
  * - 持久化存储在 `.downcity/agents/<encodedAgentId>/sessions/<encodedSessionId>/messages/messages.jsonl`
- * - 默认只存 `role=user|assistant`
+ * - 默认只存 `role=user|assistant|operation`
  * - compact 会把更早消息压缩为一条 `assistant` 摘要消息
+ * - operation 只用于 UI timeline，不进入 LLM 输入
  */
 export type SessionMessageKind = "normal" | "summary" | "operation";
 
@@ -92,9 +93,26 @@ export type SessionMetadataV1 = {
 };
 
 /**
- * Session UI 消息结构。
+ * 模型可消费的 Session UI 消息结构。
  */
-export type SessionMessageV1 = UIMessage<SessionMetadataV1>;
+export type SessionModelMessageV1 = UIMessage<SessionMetadataV1>;
+
+/**
+ * operation 角色的 Session 消息结构。
+ *
+ * 关键点（中文）
+ * - `operation` 不是 AI SDK 原生模型 role。
+ * - 它只存在于 JSONL history 与前端 timeline，进入 LLM 前必须过滤。
+ */
+export type SessionOperationMessageV1 = Omit<SessionModelMessageV1, "role"> & {
+  /** 消息角色固定为 `operation`。 */
+  role: "operation";
+};
+
+/**
+ * Session 持久化消息结构。
+ */
+export type SessionMessageV1 = SessionModelMessageV1 | SessionOperationMessageV1;
 
 /**
  * user 角色的 Session 消息结构。
@@ -112,5 +130,19 @@ export function isSessionOperationMessage(
 ): boolean {
   if (!message || typeof message !== "object") return false;
   const metadata = (message.metadata || null) as SessionMetadataV1 | null;
-  return metadata?.kind === "operation" || metadata?.source === "operation";
+  return (
+    message.role === "operation" ||
+    metadata?.kind === "operation" ||
+    metadata?.source === "operation"
+  );
+}
+
+/**
+ * 判断一条消息是否为模型可消费的 UIMessage。
+ */
+export function isSessionModelMessage(
+  message: SessionMessageV1 | null | undefined,
+): message is SessionModelMessageV1 {
+  if (!message || typeof message !== "object") return false;
+  return message.role !== "operation" && !isSessionOperationMessage(message);
 }

package/src/executor/types/SessionRun.ts

@@ -8,8 +8,11 @@
  */
 
 import type { Tool, UIMessageChunk } from "ai";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
-import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+  SessionUserMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
 
@@ -99,7 +102,7 @@ export interface SessionRunResult {
    * - stop/abort 且没有任何 assistant 内容时可以为空。
    * - turn 状态通过 `success` / `error` 表达，不应伪造成 assistant 正文。
    */
-  assistantMessage?: SessionMessageV1 | null;
+  assistantMessage?: SessionModelMessageV1 | null;
 
   /**
    * 本轮执行结束后待写入长期历史的 user 消息。

package/src/session/browse/Browse.ts

@@ -261,6 +261,7 @@ export function toSessionTimelineEvents(
 ): AgentSessionTimelineEvent[] {
   if (isSessionOperationMessage(message)) {
     const metadata = (message.metadata || null) as SessionMetadataV1 | null;
+    if (metadata?.operation?.status !== "finished") return [];
     return [
       toTimelineEvent({
         message,
@@ -367,7 +368,13 @@ export async function loadSessionMessagesFromPath(
       try {
         const parsed = JSON.parse(line) as SessionMessageV1;
         if (!parsed || typeof parsed !== "object") continue;
-        if (parsed.role !== "user" && parsed.role !== "assistant") continue;
+        if (
+          parsed.role !== "user" &&
+          parsed.role !== "assistant" &&
+          parsed.role !== "operation"
+        ) {
+          continue;
+        }
         messages.push(parsed);
       } catch {
         // 关键点（中文）：单行损坏不影响整个 session 的可读性。
@@ -412,7 +419,11 @@ export async function loadSessionArchiveMessagesFromPath(
       if (!item || typeof item !== "object") return false;
       const candidate = item as Partial<SessionMessageV1>;
       return (
-        (candidate.role === "user" || candidate.role === "assistant") &&
+        (
+          candidate.role === "user" ||
+          candidate.role === "assistant" ||
+          candidate.role === "operation"
+        ) &&
         Array.isArray(candidate.parts)
       );
     });

package/src/session/runtime/SessionPromptRuntime.ts

@@ -9,7 +9,10 @@
 
 import { nanoid } from "nanoid";
 import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
@@ -106,7 +109,7 @@ export interface SessionPromptRuntimeOptions {
   }) => Promise<{
     text: string;
     success: boolean;
-    assistantMessage?: SessionMessageV1 | null;
+    assistantMessage?: SessionModelMessageV1 | null;
     error?: string;
   }>;
 
@@ -346,7 +349,7 @@ export class SessionPromptRuntime {
 function buildPromptRuntimeErrorAssistantMessage(input: {
   sessionId: string;
   message: string;
-}): SessionMessageV1 {
+}): SessionModelMessageV1 {
   return {
     id: `a:${input.sessionId}:${Date.now()}:${nanoid(6)}`,
     role: "assistant",