@downcity/agent 1.1.199 → 1.1.200

package/src/session/services/SessionStateService.ts

@@ -31,9 +31,9 @@ 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,
@@ -87,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 状态与持久化服务。
@@ -223,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",
       });
     }
 
@@ -256,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",
       });
     }
   }
@@ -369,23 +362,18 @@ export class SessionStateService {
   }
 
   /**
-   * 持久化一条 operation message。
+   * 持久化一条 action message。
    */
-  async persist_operation_event(
-    event: AgentSessionOperationEvent,
+  async persist_action_event(
+    event: AgentSessionActionEvent,
   ): Promise<void> {
-    if (event.status !== "finished" || event.visible === false) return;
-    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 } : {}),
       },
       metadata: {
         sessionId: this.session_id,
@@ -396,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

@@ -199,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);
       },

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/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;