@downcity/agent 1.1.198 → 1.1.200

package/src/session/services/SessionViewService.ts

@@ -278,17 +278,13 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
       !message_id
         ? messages
         : this.resolve_fork_messages(messages, message_id);
-    const operation_id = `history-forking:${this.session_id}:${Date.now()}:${nanoid(8)}`;
+    const action_id = `history-forking:${this.session_id}:${Date.now()}:${nanoid(8)}`;
 
-    await this.state_service.emit_operation_event({
-      operationId: operation_id,
-      name: "history-forking",
-      status: "started",
-      label: "Forking session history",
-      result: {
-        messageCount: fork_messages.length,
-        ...(message_id ? { messageId: message_id } : {}),
-      },
+    await this.state_service.emit_action_event({
+      id: action_id,
+      title: "Forking session history",
+      description: `Preparing ${String(fork_messages.length)} messages for the new session.`,
+      state: "running",
     });
 
     try {
@@ -302,29 +298,23 @@ export class SessionViewService<TSession extends Pick<AgentSession, "set">> {
           {
             model: session_config.model,
           },
-          { emit_operation: false },
+          { emit_action: false },
         );
       }
       await this.append_fork_messages(forked_bundle, fork_messages);
-      await this.state_service.emit_operation_event({
-        operationId: operation_id,
-        name: "history-forking",
-        status: "finished",
-        label: "Session history forked",
-        result: {
-          forkedSessionId: String((forked as { id?: unknown }).id || ""),
-          messageCount: fork_messages.length,
-          ...(message_id ? { messageId: message_id } : {}),
-        },
+      await this.state_service.emit_action_event({
+        id: action_id,
+        title: "Session history forked",
+        description: `Created ${String((forked as { id?: unknown }).id || "")} with ${String(fork_messages.length)} messages.`,
+        state: "completed",
       });
       return forked;
     } catch (error) {
-      await this.state_service.emit_operation_event({
-        operationId: operation_id,
-        name: "history-forking",
-        status: "failed",
-        label: "Session history fork failed",
-        error: error instanceof Error ? error.message : String(error),
+      await this.state_service.emit_action_event({
+        id: action_id,
+        title: "Session history fork failed",
+        description: error instanceof Error ? error.message : String(error),
+        state: "failed",
       });
       throw error;
     }

package/src/session/storage/Persistence.ts

@@ -8,7 +8,10 @@
 
 import { extractTextFromUiMessage } from "@/executor/messages/UIMessageTransformer.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import type {
+  SessionMessageV1,
+  SessionModelMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import { persistAssistantResult } from "@/executor/messages/AssistantResultPersistence.js";
 import type { AgentSessionConfigSnapshot } from "@/types/agent/AgentTypes.js";
 import {
@@ -65,7 +68,7 @@ export interface PersistSdkAssistantResultParams
    * - stop/abort 且没有 assistant 内容时允许为空。
    * - 为空时仅刷新 metadata，不写入伪造 assistant 正文。
    */
-  assistantMessage?: SessionMessageV1 | null;
+  assistantMessage?: SessionModelMessageV1 | null;
 }
 
 /**

package/src/types/agent/SessionTypes.ts

@@ -99,7 +99,7 @@ export interface AgentSessionTimelineEvent {
    * 说明（中文）
    * - `tool-call` / `tool-result` 用于把 assistant 内部工具过程平铺给 UI。
    */
-  role: "user" | "assistant" | "tool-call" | "tool-result" | "operation";
+  role: "user" | "assistant" | "tool-call" | "tool-result" | "action";
   /** 事件时间戳（毫秒）。 */
   ts?: number;
   /** 事件所属消息种类。 */
@@ -116,26 +116,26 @@ export interface AgentSessionTimelineEvent {
    */
   toolName?: string;
   /**
-   * 当前 operation ID。
+   * 当前 action 标题。
    *
    * 说明（中文）
-   * - 仅 `role=operation` 的事件通常会携带该字段。
+   * - 仅 `role=action` 的事件通常会携带该字段。
    */
-  operationId?: string;
+  actionTitle?: string;
   /**
-   * 当前 operation 名称。
+   * 当前 action 描述。
    *
    * 说明（中文）
-   * - 仅 `role=operation` 的事件通常会携带该字段。
+   * - 仅 `role=action` 的事件通常会携带该字段。
    */
-  operationName?: string;
+  actionDescription?: string;
   /**
-   * 当前 operation 状态。
+   * 当前 action 状态。
    *
    * 说明（中文）
-   * - 仅 `role=operation` 的事件通常会携带该字段。
+   * - 仅 `role=action` 的事件通常会携带该字段。
    */
-  operationStatus?: string;
+  actionState?: string;
 }
 
 /**

package/src/types/executor/SessionRunContext.ts

@@ -8,10 +8,10 @@
  */
 
 import type {
-  AgentSessionOperationCallback,
-  AgentSessionOperationEvent,
-  AgentSessionOperationRecord,
-} from "@/types/sdk/AgentSessionOperation.js";
+  AgentSessionActionCallback,
+  AgentSessionActionEvent,
+  AgentSessionActionRecord,
+} from "@/types/sdk/AgentSessionAction.js";
 import type {
   SessionAssistantStepCallback,
   SessionUiMessageChunkCallback,
@@ -72,13 +72,13 @@ export interface SessionRunContext {
   onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
 
   /**
-   * operation 发布回调。
+   * action 发布回调。
    *
    * 关键点（中文）
-   * - 用于把 compaction 等辅助操作转成 session event 与 operation message。
-   * - operation 不代表 assistant 正文，也不会进入 LLM 输入。
+   * - 用于把 compaction 等辅助动作转成 session event 与 action message。
+   * - action 不代表 assistant 正文，也不会进入 LLM 输入。
    */
-  onOperationCallback?: AgentSessionOperationCallback;
+  onActionCallback?: AgentSessionActionCallback;
 
   /**
    * 当前 turn 的取消信号。
@@ -117,7 +117,7 @@ export interface SessionRunContext {
 }
 
 export type {
-  AgentSessionOperationCallback,
-  AgentSessionOperationEvent,
-  AgentSessionOperationRecord,
+  AgentSessionActionCallback,
+  AgentSessionActionEvent,
+  AgentSessionActionRecord,
 };

package/src/types/sdk/AgentSessionAction.ts

@@ -0,0 +1,79 @@
+/**
+ * Agent Session action 类型定义。
+ *
+ * 关键点（中文）
+ * - action 描述 session 内部正在发生的辅助动作，不代表 assistant 正文。
+ * - action 同时用于 `session.subscribe()` 实时事件与 JSONL history item。
+ * - action 只服务前端状态展示与历史回放，不进入 LLM 输入。
+ */
+
+/**
+ * Session action 当前状态。
+ */
+export type AgentSessionActionState = "running" | "completed" | "failed";
+
+/**
+ * Session action 记录。
+ */
+export interface AgentSessionActionRecord {
+  /**
+   * 同一个 action 生命周期内稳定复用的 ID。
+   *
+   * 说明（中文）
+   * - 这是 history item envelope 字段，用于把同一个动作更新为一条记录。
+   * - 前端展示语义只依赖 `type/title/description/state`。
+   */
+  id: string;
+
+  /**
+   * 当前 action 标题。
+   */
+  title: string;
+
+  /**
+   * 当前 action 描述。
+   */
+  description?: string;
+
+  /**
+   * 当前 action 状态。
+   */
+  state: AgentSessionActionState;
+
+  /**
+   * 当前 action 关联的 turn 标识。
+   */
+  turnId?: string;
+
+  /**
+   * 是否建议前端展示。
+   *
+   * 说明（中文）
+   * - 默认视为 `true`。
+   * - 调试或审计类辅助事件可显式写入 `false`。
+   */
+  visible?: boolean;
+}
+
+/**
+ * Session action 订阅事件。
+ */
+export interface AgentSessionActionEvent
+  extends Omit<AgentSessionActionRecord, "visible"> {
+  /**
+   * 当前事件类型。
+   */
+  type: "action";
+
+  /**
+   * 当前 session 唯一标识。
+   */
+  sessionId: string;
+}
+
+/**
+ * Session action 发布回调。
+ */
+export type AgentSessionActionCallback = (
+  action: AgentSessionActionEvent,
+) => Promise<void>;

package/src/types/sdk/AgentSessionEvent.ts

@@ -8,7 +8,7 @@
 
 import type { JsonValue } from "@/types/common/Json.js";
 import type { SessionAssistantStepVisibility } from "@/executor/types/SessionRun.js";
-import type { AgentSessionOperationEvent } from "@/types/sdk/AgentSessionOperation.js";
+import type { AgentSessionActionEvent } from "@/types/sdk/AgentSessionAction.js";
 
 /**
  * 单个 turn 开始事件。
@@ -355,7 +355,7 @@ export type AgentSessionEvent =
   | AgentSessionToolApprovalResultEvent
   | AgentSessionAssistantStepEvent
   | AgentSessionTitleEvent
-  | AgentSessionOperationEvent
+  | AgentSessionActionEvent
   | AgentSessionTurnFinishEvent
   | AgentSessionErrorEvent;
 

package/src/types/sdk/AgentSessionTurn.ts

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