@downcity/agent 1.1.198 → 1.1.200

package/src/executor/types/SessionMessages.ts

@@ -3,23 +3,27 @@
  *
  * 关键点（中文）
  * - 这里统一描述 session 消息落盘格式与元信息结构。
- * - session 的唯一事实源是 `UIMessage[]`，不会再维护第二套平行消息结构。
+ * - session 的唯一事实源是消息 JSONL，模型消息继续使用 AI SDK `UIMessage`。
  * - 这些类型会被 history Store、history Composer、compact、control UI、task runtime 共同复用。
  */
 
 import type { UIMessage } from "ai";
 import type { JsonObject } from "@/types/common/Json.js";
-import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
+import type {
+  AgentSessionActionRecord,
+  AgentSessionActionState,
+} from "@/types/sdk/AgentSessionAction.js";
 
 /**
  * Session 消息：以 UIMessage[] 作为唯一事实源。
  *
  * 关键点（中文）
  * - 持久化存储在 `.downcity/agents/<encodedAgentId>/sessions/<encodedSessionId>/messages/messages.jsonl`
- * - 默认只存 `role=user|assistant`
+ * - 默认只存模型消息，或 `type=action` 的 UI 状态消息。
  * - compact 会把更早消息压缩为一条 `assistant` 摘要消息
+ * - action 只用于 UI timeline，不进入 LLM 输入
  */
-export type SessionMessageKind = "normal" | "summary" | "operation";
+export type SessionMessageKind = "normal" | "summary";
 
 /**
  * Session 消息来源类型。
@@ -32,8 +36,7 @@ export type SessionMessageKind = "normal" | "summary" | "operation";
 export type SessionMessageSource =
   | "ingress"
   | "egress"
-  | "compact"
-  | "operation";
+  | "compact";
 
 /**
  * 入站消息细分类型。
@@ -73,14 +76,6 @@ export type SessionMetadataV1 = {
   archiveId?: string;
   /** compact 摘要所覆盖的原始消息范围。 */
   sourceRange?: SessionMessageSourceRangeV1;
-  /**
-   * operation message 对应的结构化操作记录。
-   *
-   * 说明（中文）
-   * - 仅当 `kind=operation` 或 `source=operation` 时存在。
-   * - 该字段供前端恢复时间线状态，不会进入 LLM 输入。
-   */
-  operation?: AgentSessionOperationRecord;
   /**
    * 扩展元信息。
    *
@@ -92,25 +87,100 @@ export type SessionMetadataV1 = {
 };
 
 /**
- * Session UI 消息结构。
+ * 模型可消费的 Session UI 消息结构。
+ */
+export type SessionModelMessageV1 = UIMessage<SessionMetadataV1>;
+
+/**
+ * action 消息元信息。
+ */
+export type SessionActionMetadataV1 = {
+  /** 元信息 schema 版本号。 */
+  v: 1;
+  /** 当前 action 写入时的毫秒时间戳。 */
+  ts: number;
+  /** 当前 action 所属的 session ID。 */
+  sessionId: string;
+  /** 当前 action 关联的 turn 标识。 */
+  turnId?: string;
+};
+
+/**
+ * action 类型的 Session 消息结构。
+ *
+ * 关键点（中文）
+ * - `action` 不是 AI SDK 原生模型消息。
+ * - 它只存在于 JSONL history 与前端 timeline，进入 LLM 前必须过滤。
+ */
+export type SessionActionMessageV1 = {
+  /** item 类型固定为 `action`。 */
+  type: "action";
+  /** 同一个 action 生命周期内稳定复用的 ID。 */
+  id: string;
+  /** 当前 action 标题。 */
+  title: string;
+  /** 当前 action 描述。 */
+  description?: string;
+  /** 当前 action 状态。 */
+  state: AgentSessionActionState;
+  /** action 元信息。 */
+  metadata: SessionActionMetadataV1;
+};
+
+/**
+ * Session 持久化消息结构。
  */
-export type SessionMessageV1 = UIMessage<SessionMetadataV1>;
+export type SessionMessageV1 = SessionModelMessageV1 | SessionActionMessageV1;
 
 /**
  * user 角色的 Session 消息结构。
  */
-export type SessionUserMessageV1 = SessionMessageV1 & {
+export type SessionUserMessageV1 = SessionModelMessageV1 & {
   /** 消息角色固定为 `user`。 */
   role: "user";
 };
 
 /**
- * 判断一条消息是否为 operation message。
+ * 判断一条消息是否为 action message。
+ */
+export function isSessionActionMessage(
+  message: SessionMessageV1 | null | undefined,
+): message is SessionActionMessageV1 {
+  if (!message || typeof message !== "object") return false;
+  return (message as { type?: unknown }).type === "action";
+}
+
+/**
+ * 从订阅事件构造 action message。
+ */
+export function toSessionActionMessage(
+  action: AgentSessionActionRecord,
+  session_id: string,
+): SessionActionMessageV1 {
+  const title = String(action.title || "").trim() || "Action";
+  const description = String(action.description || "").trim();
+  const id = String(action.id || "").trim() || `action:${session_id}:${Date.now()}`;
+  return {
+    type: "action",
+    id,
+    title,
+    ...(description ? { description } : {}),
+    state: action.state,
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: session_id,
+      ...(action.turnId ? { turnId: action.turnId } : {}),
+    },
+  };
+}
+
+/**
+ * 判断一条消息是否为模型可消费的 UIMessage。
  */
-export function isSessionOperationMessage(
+export function isSessionModelMessage(
   message: SessionMessageV1 | null | undefined,
-): boolean {
+): message is SessionModelMessageV1 {
   if (!message || typeof message !== "object") return false;
-  const metadata = (message.metadata || null) as SessionMetadataV1 | null;
-  return metadata?.kind === "operation" || metadata?.source === "operation";
+  return !isSessionActionMessage(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/index.ts

@@ -56,12 +56,11 @@ export type {
   AgentSessionUnsubscribe,
 } from "./types/sdk/AgentSessionEvent.js";
 export type {
-  AgentSessionOperationCallback,
-  AgentSessionOperationEvent,
-  AgentSessionOperationName,
-  AgentSessionOperationRecord,
-  AgentSessionOperationStatus,
-} from "./types/sdk/AgentSessionOperation.js";
+  AgentSessionActionCallback,
+  AgentSessionActionEvent,
+  AgentSessionActionRecord,
+  AgentSessionActionState,
+} from "./types/sdk/AgentSessionAction.js";
 export type { AgentSessionPromptInput, SessionUserMessagePart } from "./types/sdk/AgentSessionPrompt.js";
 export type { AgentSessionStopResult } from "./types/sdk/AgentSessionStop.js";
 export type {

package/src/session/SessionTitle.ts

@@ -10,6 +10,7 @@
 import { generateText, type LanguageModel } from "ai";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import { isSessionModelMessage } from "@/executor/types/SessionMessages.js";
 import {
   normalizeSessionTitle,
   readSessionMetadata,
@@ -61,6 +62,7 @@ function truncateTitle(input: string, maxChars: number): string {
 }
 
 function extractTextFromMessage(message: SessionMessageV1): string {
+  if (!isSessionModelMessage(message)) return "";
   if (!Array.isArray(message.parts)) return "";
   const texts: string[] = [];
   for (const part of message.parts) {
@@ -76,6 +78,7 @@ function extractTextFromMessage(message: SessionMessageV1): string {
 
 function resolveFirstUserText(messages: SessionMessageV1[]): string {
   for (const message of messages) {
+    if (!isSessionModelMessage(message)) continue;
     if (message.role !== "user") continue;
     const text = extractTextFromMessage(message);
     if (text) return text;

package/src/session/browse/Browse.ts

@@ -26,10 +26,15 @@ import type {
   AgentSessionTimelineEvent,
 } from "@/types/agent/AgentTypes.js";
 import type {
+  SessionActionMessageV1,
   SessionMessageV1,
   SessionMetadataV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
+import {
+  isSessionActionMessage,
+  isSessionModelMessage,
 } from "@/executor/types/SessionMessages.js";
-import { isSessionOperationMessage } from "@/executor/types/SessionMessages.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import { pickLastSuccessfulChatSendText } from "@/executor/messages/UserVisibleText.js";
 import { getSdkAgentSessionMessagesPath } from "@/session/storage/Paths.js";
@@ -172,7 +177,7 @@ function extractMessageText(parts: unknown): string {
   return texts.join("\n").trim();
 }
 
-function extractAssistantToolSummary(message: SessionMessageV1): string {
+function extractAssistantToolSummary(message: SessionModelMessageV1): string {
   if (!Array.isArray(message.parts)) return "";
   const toolNames = new Set<string>();
   for (const part of message.parts as AnyUiPart[]) {
@@ -189,6 +194,12 @@ function extractAssistantToolSummary(message: SessionMessageV1): string {
  * 解析单条 session 消息的用户可见预览文本。
  */
 export function resolveSessionMessagePreview(message: SessionMessageV1): string {
+  if (isSessionActionMessage(message)) {
+    return message.description
+      ? `${message.title}\n${message.description}`
+      : message.title;
+  }
+  if (!isSessionModelMessage(message)) return "";
   const plainText = extractMessageText(message.parts);
   if (plainText) return plainText;
   if (message.role !== "assistant") return "";
@@ -226,7 +237,7 @@ function extractToolResultOutput(part: ToolPartCompatShape): unknown {
 }
 
 function toTimelineEvent(params: {
-  message: SessionMessageV1;
+  message: SessionModelMessageV1;
   role: AgentSessionTimelineEvent["role"];
   text: string;
   sequence: number;
@@ -241,15 +252,21 @@ function toTimelineEvent(params: {
     ...(typeof metadata?.source === "string" ? { source: metadata.source } : {}),
     text: params.text,
     ...(params.toolName ? { toolName: params.toolName } : {}),
-    ...(params.role === "operation" && metadata?.operation?.operationId
-      ? { operationId: metadata.operation.operationId }
-      : {}),
-    ...(params.role === "operation" && metadata?.operation?.name
-      ? { operationName: metadata.operation.name }
-      : {}),
-    ...(params.role === "operation" && metadata?.operation?.status
-      ? { operationStatus: metadata.operation.status }
-      : {}),
+  };
+}
+
+function toActionTimelineEvent(
+  message: SessionActionMessageV1,
+): AgentSessionTimelineEvent {
+  const metadata = message.metadata || null;
+  return {
+    id: `${String(message.id || "")}:0`,
+    role: "action",
+    ...(typeof metadata?.ts === "number" ? { ts: metadata.ts } : {}),
+    text: resolveSessionMessagePreview(message),
+    actionTitle: message.title,
+    ...(message.description ? { actionDescription: message.description } : {}),
+    actionState: message.state,
   };
 }
 
@@ -259,20 +276,11 @@ function toTimelineEvent(params: {
 export function toSessionTimelineEvents(
   message: SessionMessageV1,
 ): AgentSessionTimelineEvent[] {
-  if (isSessionOperationMessage(message)) {
-    const metadata = (message.metadata || null) as SessionMetadataV1 | null;
-    return [
-      toTimelineEvent({
-        message,
-        role: "operation",
-        text:
-          String(metadata?.operation?.label || "").trim() ||
-          resolveSessionMessagePreview(message),
-        sequence: 0,
-      }),
-    ];
+  if (isSessionActionMessage(message)) {
+    return [toActionTimelineEvent(message)];
   }
 
+  if (!isSessionModelMessage(message)) return [];
   if (message.role !== "assistant") {
     return [
       toTimelineEvent({
@@ -367,7 +375,14 @@ 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;
+        const candidate = parsed as { type?: unknown; role?: unknown };
+        if (
+          candidate.type !== "action" &&
+          candidate.role !== "user" &&
+          candidate.role !== "assistant"
+        ) {
+          continue;
+        }
         messages.push(parsed);
       } catch {
         // 关键点（中文）：单行损坏不影响整个 session 的可读性。
@@ -380,8 +395,7 @@ export async function loadSessionMessagesFromPath(
     try {
       const parsed = (await fs.readJson(inflight_path)) as SessionMessageV1;
       if (
-        parsed &&
-        typeof parsed === "object" &&
+        isSessionModelMessage(parsed) &&
         parsed.role === "assistant" &&
         Array.isArray(parsed.parts)
       ) {
@@ -410,10 +424,14 @@ export async function loadSessionArchiveMessagesFromPath(
     const items = Array.isArray(raw?.messages) ? raw.messages : [];
     return items.filter((item): item is SessionMessageV1 => {
       if (!item || typeof item !== "object") return false;
-      const candidate = item as Partial<SessionMessageV1>;
+      const candidate = item as { type?: unknown; role?: unknown; parts?: unknown };
       return (
-        (candidate.role === "user" || candidate.role === "assistant") &&
-        Array.isArray(candidate.parts)
+        (
+          candidate.type === "action" ||
+          candidate.role === "user" ||
+          candidate.role === "assistant"
+        ) &&
+        (candidate.type === "action" || Array.isArray(candidate.parts))
       );
     });
   } catch {
@@ -422,6 +440,7 @@ export async function loadSessionArchiveMessagesFromPath(
 }
 
 function isCompactSummaryMessage(message: SessionMessageV1): boolean {
+  if (!isSessionModelMessage(message)) return false;
   const metadata = (message.metadata || null) as SessionMetadataV1 | null;
   return metadata?.source === "compact" || metadata?.kind === "summary";
 }

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",

package/src/session/services/SessionStateService.ts

@@ -31,12 +31,13 @@ import type {
   AgentSessionEvent,
 } from "@/types/sdk/AgentSessionEvent.js";
 import type {
-  AgentSessionOperationEvent,
-  AgentSessionOperationRecord,
-} from "@/types/sdk/AgentSessionOperation.js";
+  AgentSessionActionEvent,
+  AgentSessionActionRecord,
+} from "@/types/sdk/AgentSessionAction.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   SessionMessageV1,
+  SessionModelMessageV1,
   SessionUserMessageV1,
 } from "@/executor/types/SessionMessages.js";
 import type { SessionLocalState } from "@/types/session/SessionLocalState.js";
@@ -86,17 +87,17 @@ type SessionStateServiceOptions = {
 
 type SessionSetOptions = {
   /**
-   * 是否写入并发布 model-switching operation。
+   * 是否写入并发布 model-switching action。
    *
    * 说明（中文）
    * - 公开 `session.set()` 应保持默认开启。
    * - fork 内部复制模型配置时关闭，避免污染 forked session 历史。
    */
-  emit_operation?: boolean;
+  emit_action?: boolean;
 };
 
-type EmitOperationInput = Omit<AgentSessionOperationRecord, "operationId"> &
-  Partial<Pick<AgentSessionOperationRecord, "operationId">>;
+type EmitActionInput = Omit<AgentSessionActionRecord, "id"> &
+  Partial<Pick<AgentSessionActionRecord, "id">>;
 
 /**
  * 本地 Session 状态与持久化服务。
@@ -222,23 +223,21 @@ export class SessionStateService {
    * 写入当前 session 配置。
    */
   async set(input: AgentSessionSetInput, options?: SessionSetOptions): Promise<void> {
-    const should_emit_operation = options?.emit_operation !== false;
+    const should_emit_action = options?.emit_action !== false;
     const previous_model_label = this.state.sessionConfig.modelLabel;
     const next_model_label = input.model
       ? inferAgentModelLabel(input.model)
       : undefined;
-    const operation_id = `model-switching:${this.session_id}:${Date.now()}:${generateId()}`;
-
-    if (input.model && should_emit_operation) {
-      await this.emit_operation_event({
-        operationId: operation_id,
-        name: "model-switching",
-        status: "started",
-        label: "Switching session model",
-        result: {
-          ...(previous_model_label ? { previousModelLabel: previous_model_label } : {}),
-          ...(next_model_label ? { modelLabel: next_model_label } : {}),
-        },
+    const action_id = `model-switching:${this.session_id}:${Date.now()}:${generateId()}`;
+
+    if (input.model && should_emit_action) {
+      await this.emit_action_event({
+        id: action_id,
+        title: "Switching session model",
+        description: next_model_label
+          ? `Switching to ${next_model_label}.`
+          : undefined,
+        state: "running",
       });
     }
 
@@ -255,30 +254,25 @@ export class SessionStateService {
         model: this.state.sessionConfig.model,
       });
     } catch (error) {
-      if (input.model && should_emit_operation) {
-        await this.emit_operation_event({
-          operationId: operation_id,
-          name: "model-switching",
-          status: "failed",
-          label: "Session model switch failed",
-          error: error instanceof Error ? error.message : String(error),
+      if (input.model && should_emit_action) {
+        await this.emit_action_event({
+          id: action_id,
+          title: "Session model switch failed",
+          description: error instanceof Error ? error.message : String(error),
+          state: "failed",
         });
       }
       throw error;
     }
 
-    if (input.model && should_emit_operation) {
-      await this.emit_operation_event({
-        operationId: operation_id,
-        name: "model-switching",
-        status: "finished",
-        label: "Session model switched",
-        result: {
-          ...(previous_model_label ? { previousModelLabel: previous_model_label } : {}),
-          ...(this.state.sessionConfig.modelLabel
-            ? { modelLabel: this.state.sessionConfig.modelLabel }
-            : {}),
-        },
+    if (input.model && should_emit_action) {
+      await this.emit_action_event({
+        id: action_id,
+        title: "Session model switched",
+        description: this.state.sessionConfig.modelLabel
+          ? `Using ${this.state.sessionConfig.modelLabel}.`
+          : undefined,
+        state: "completed",
       });
     }
   }
@@ -355,7 +349,7 @@ export class SessionStateService {
    * 持久化最终 assistant 结果。
    */
   async persist_assistant_result(
-    assistant_message?: SessionMessageV1 | null,
+    assistant_message?: SessionModelMessageV1 | null,
   ): Promise<void> {
     await persistSdkAssistantResult({
       projectRoot: this.project_root,
@@ -368,23 +362,18 @@ export class SessionStateService {
   }
 
   /**
-   * 持久化一条 operation message。
+   * 持久化一条 action message。
    */
-  async persist_operation_event(
-    event: AgentSessionOperationEvent,
+  async persist_action_event(
+    event: AgentSessionActionEvent,
   ): Promise<void> {
-    const message = this.history_store.operation({
-      operation: {
-        operationId: event.operationId,
-        name: event.name,
-        status: event.status,
+    const message = this.history_store.action({
+      action: {
+        id: event.id,
+        title: event.title,
+        state: event.state,
+        ...(event.description ? { description: event.description } : {}),
         ...(event.turnId ? { turnId: event.turnId } : {}),
-        ...(event.label ? { label: event.label } : {}),
-        ...(event.reason ? { reason: event.reason } : {}),
-        ...(typeof event.progress === "number" ? { progress: event.progress } : {}),
-        ...(event.result !== undefined ? { result: event.result } : {}),
-        ...(event.error ? { error: event.error } : {}),
-        ...(event.visible === false ? { visible: false } : {}),
       },
       metadata: {
         sessionId: this.session_id,
@@ -395,22 +384,24 @@ export class SessionStateService {
   }
 
   /**
-   * 写入并发布一条 operation。
+   * 写入并发布一条 action。
    */
-  async emit_operation_event(input: EmitOperationInput): Promise<void> {
-    const operation_id =
-      String(input.operationId || "").trim() ||
-      `${input.name}:${this.session_id}:${Date.now()}:${generateId()}`;
-    const event: AgentSessionOperationEvent = {
-      type: "operation",
+  async emit_action_event(input: EmitActionInput): Promise<void> {
+    if (input.visible === false) return;
+    const action_id =
+      String(input.id || "").trim() ||
+      `action:${this.session_id}:${Date.now()}:${generateId()}`;
+    const { visible: _visible, ...public_input } = input;
+    const event: AgentSessionActionEvent = {
+      type: "action",
       sessionId: this.session_id,
-      ...input,
-      operationId: operation_id,
+      ...public_input,
+      id: action_id,
     };
     try {
-      await this.persist_operation_event(event);
+      await this.persist_action_event(event);
     } catch {
-      // operation 持久化失败不应阻断宿主操作。
+      // action 持久化失败不应阻断宿主操作。
     }
     this.publish_event(event);
   }

package/src/session/services/SessionTurnService.ts

@@ -20,6 +20,7 @@ import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type {
   SessionMessageV1,
+  SessionModelMessageV1,
   SessionUserMessageV1,
 } from "@/executor/types/SessionMessages.js";
 import { mapAgentEventToSessionEvent, mapUiMessageChunkToAgentEvent } from "@/session/SessionEventMapper.js";
@@ -144,7 +145,7 @@ export class SessionTurnService {
   }): Promise<{
     text: string;
     success: boolean;
-    assistantMessage?: SessionMessageV1 | null;
+    assistantMessage?: SessionModelMessageV1 | null;
     error?: string;
   }> {
     const tool_name_by_call_id = new Map<string, string>();
@@ -198,11 +199,11 @@ export class SessionTurnService {
           this.publish_event(session_event);
         }
       },
-      onOperationCallback: async (event) => {
+      onActionCallback: async (event) => {
         try {
-          await this.state_service.persist_operation_event(event);
+          await this.state_service.persist_action_event(event);
         } catch {
-          // operation 持久化失败不应阻断当前 turn。
+          // action 持久化失败不应阻断当前 turn。
         }
         this.publish_event(event);
       },