@downcity/agent 1.1.189 → 1.1.196

package/src/executor/types/SessionMessages.ts

@@ -9,6 +9,7 @@
 
 import type { UIMessage } from "ai";
 import type { JsonObject } from "@/types/common/Json.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 /**
  * Session 消息：以 UIMessage[] 作为唯一事实源。
@@ -18,7 +19,7 @@ import type { JsonObject } from "@/types/common/Json.js";
  * - 默认只存 `role=user|assistant`
  * - compact 会把更早消息压缩为一条 `assistant` 摘要消息
  */
-export type SessionMessageKind = "normal" | "summary";
+export type SessionMessageKind = "normal" | "summary" | "operation";
 
 /**
  * Session 消息来源类型。
@@ -28,7 +29,11 @@ export type SessionMessageKind = "normal" | "summary";
  * - `egress`：模型或 agent 输出写入的 assistant 消息。
  * - `compact`：由 compact 过程生成的摘要消息。
  */
-export type SessionMessageSource = "ingress" | "egress" | "compact";
+export type SessionMessageSource =
+  | "ingress"
+  | "egress"
+  | "compact"
+  | "operation";
 
 /**
  * 入站消息细分类型。
@@ -68,6 +73,14 @@ export type SessionMetadataV1 = {
   archiveId?: string;
   /** compact 摘要所覆盖的原始消息范围。 */
   sourceRange?: SessionMessageSourceRangeV1;
+  /**
+   * operation message 对应的结构化操作记录。
+   *
+   * 说明（中文）
+   * - 仅当 `kind=operation` 或 `source=operation` 时存在。
+   * - 该字段供前端恢复时间线状态，不会进入 LLM 输入。
+   */
+  operation?: AgentSessionOperationRecord;
   /**
    * 扩展元信息。
    *
@@ -90,3 +103,14 @@ export type SessionUserMessageV1 = SessionMessageV1 & {
   /** 消息角色固定为 `user`。 */
   role: "user";
 };
+
+/**
+ * 判断一条消息是否为 operation message。
+ */
+export function isSessionOperationMessage(
+  message: SessionMessageV1 | null | undefined,
+): boolean {
+  if (!message || typeof message !== "object") return false;
+  const metadata = (message.metadata || null) as SessionMetadataV1 | null;
+  return metadata?.kind === "operation" || metadata?.source === "operation";
+}

package/src/index.ts

@@ -55,6 +55,13 @@ export type {
   AgentSessionSubscriber,
   AgentSessionUnsubscribe,
 } from "./types/sdk/AgentSessionEvent.js";
+export type {
+  AgentSessionOperationCallback,
+  AgentSessionOperationEvent,
+  AgentSessionOperationName,
+  AgentSessionOperationRecord,
+  AgentSessionOperationStatus,
+} from "./types/sdk/AgentSessionOperation.js";
 export type { AgentSessionPromptInput, SessionUserMessagePart } from "./types/sdk/AgentSessionPrompt.js";
 export type { AgentSessionStopResult } from "./types/sdk/AgentSessionStop.js";
 export type {

package/src/plugin/core/PluginRegistry.ts

@@ -522,12 +522,8 @@ export class PluginRegistry implements AgentPlugins {
         pluginName: record.plugin.name,
         actionName,
       });
-      if (!result.success) {
-        update_record_state(record, "error", result.error || result.message);
-      }
       return result;
     } catch (error) {
-      update_record_state(record, "error", String(error));
       return {
         success: false,
         error: String(error),

package/src/session/browse/Browse.ts

@@ -29,6 +29,7 @@ import type {
   SessionMessageV1,
   SessionMetadataV1,
 } 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";
@@ -240,6 +241,15 @@ 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 }
+      : {}),
   };
 }
 
@@ -249,6 +259,20 @@ 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 (message.role !== "assistant") {
     return [
       toTimelineEvent({

package/src/session/services/SessionStateService.ts

@@ -30,6 +30,10 @@ import type {
 import type {
   AgentSessionEvent,
 } from "@/types/sdk/AgentSessionEvent.js";
+import type {
+  AgentSessionOperationEvent,
+  AgentSessionOperationRecord,
+} from "@/types/sdk/AgentSessionOperation.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   SessionMessageV1,
@@ -80,6 +84,20 @@ type SessionStateServiceOptions = {
   publish_event: (event: AgentSessionEvent) => void;
 };
 
+type SessionSetOptions = {
+  /**
+   * 是否写入并发布 model-switching operation。
+   *
+   * 说明（中文）
+   * - 公开 `session.set()` 应保持默认开启。
+   * - fork 内部复制模型配置时关闭，避免污染 forked session 历史。
+   */
+  emit_operation?: boolean;
+};
+
+type EmitOperationInput = Omit<AgentSessionOperationRecord, "operationId"> &
+  Partial<Pick<AgentSessionOperationRecord, "operationId">>;
+
 /**
  * 本地 Session 状态与持久化服务。
  */
@@ -203,18 +221,66 @@ export class SessionStateService {
   /**
    * 写入当前 session 配置。
    */
-  async set(input: AgentSessionSetInput): Promise<void> {
-    if (input.model) {
-      this.state.sessionConfig.model = normalizeAgentModel(input.model);
-      this.state.sessionConfig.modelLabel = inferAgentModelLabel(input.model);
-      this.executor.clearExecutor();
+  async set(input: AgentSessionSetInput, options?: SessionSetOptions): Promise<void> {
+    const should_emit_operation = options?.emit_operation !== 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 } : {}),
+        },
+      });
+    }
+
+    try {
+      if (input.model) {
+        this.state.sessionConfig.model = normalizeAgentModel(input.model);
+        this.state.sessionConfig.modelLabel = next_model_label;
+        this.executor.clearExecutor();
+      }
+      await patchSessionModelLabel({
+        projectRoot: this.project_root,
+        agentId: this.agent_id,
+        sessionId: this.session_id,
+        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),
+        });
+      }
+      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 }
+            : {}),
+        },
+      });
     }
-    await patchSessionModelLabel({
-      projectRoot: this.project_root,
-      agentId: this.agent_id,
-      sessionId: this.session_id,
-      model: this.state.sessionConfig.model,
-    });
   }
 
   /**
@@ -301,6 +367,54 @@ export class SessionStateService {
     });
   }
 
+  /**
+   * 持久化一条 operation message。
+   */
+  async persist_operation_event(
+    event: AgentSessionOperationEvent,
+  ): Promise<void> {
+    const message = this.history_store.operation({
+      operation: {
+        operationId: event.operationId,
+        name: event.name,
+        status: event.status,
+        ...(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,
+      },
+    });
+    await this.history_store.append(message);
+    await this.touch_metadata();
+  }
+
+  /**
+   * 写入并发布一条 operation。
+   */
+  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",
+      sessionId: this.session_id,
+      ...input,
+      operationId: operation_id,
+    };
+    try {
+      await this.persist_operation_event(event);
+    } catch {
+      // operation 持久化失败不应阻断宿主操作。
+    }
+    this.publish_event(event);
+  }
+
   /**
    * 构造并持久化一条 prompt user 消息。
    */

package/src/session/services/SessionTurnService.ts

@@ -198,6 +198,14 @@ export class SessionTurnService {
           this.publish_event(session_event);
         }
       },
+      onOperationCallback: async (event) => {
+        try {
+          await this.state_service.persist_operation_event(event);
+        } catch {
+          // operation 持久化失败不应阻断当前 turn。
+        }
+        this.publish_event(event);
+      },
       injectedUserMessages: [],
       deferredPersistedUserMessages: [],
       pendingAssistantFileParts: [],

package/src/session/services/SessionViewService.ts

@@ -278,19 +278,56 @@ 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 forked_bundle = await this.create_fork_session(
-      `fork-${Date.now()}-${nanoid(8)}`,
-    );
-    const forked = forked_bundle.session;
-    const session_config = this.state_service.get_config();
-    if (session_config.model) {
-      await forked.set({
-        model: session_config.model,
+    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 } : {}),
+      },
+    });
+
+    try {
+      const forked_bundle = await this.create_fork_session(
+        `fork-${Date.now()}-${nanoid(8)}`,
+      );
+      const forked = forked_bundle.session;
+      const session_config = this.state_service.get_config();
+      if (session_config.model) {
+        await forked_bundle.state_service.set(
+          {
+            model: session_config.model,
+          },
+          { emit_operation: 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 } : {}),
+        },
+      });
+      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),
       });
+      throw error;
     }
-    await this.append_fork_messages(forked_bundle, fork_messages);
-    return forked;
   }
 
   private resolve_fork_messages(

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";
+  role: "user" | "assistant" | "tool-call" | "tool-result" | "operation";
   /** 事件时间戳（毫秒）。 */
   ts?: number;
   /** 事件所属消息种类。 */
@@ -115,6 +115,27 @@ export interface AgentSessionTimelineEvent {
    * - 仅 `tool-call` / `tool-result` 这类事件通常会携带该字段。
    */
   toolName?: string;
+  /**
+   * 当前 operation ID。
+   *
+   * 说明（中文）
+   * - 仅 `role=operation` 的事件通常会携带该字段。
+   */
+  operationId?: string;
+  /**
+   * 当前 operation 名称。
+   *
+   * 说明（中文）
+   * - 仅 `role=operation` 的事件通常会携带该字段。
+   */
+  operationName?: string;
+  /**
+   * 当前 operation 状态。
+   *
+   * 说明（中文）
+   * - 仅 `role=operation` 的事件通常会携带该字段。
+   */
+  operationStatus?: string;
 }
 
 /**

package/src/types/executor/SessionRunContext.ts

@@ -7,6 +7,11 @@
  * - tool 深层回调等无法直接传参的场景，才通过 run scope 间接读取这个对象。
  */
 
+import type {
+  AgentSessionOperationCallback,
+  AgentSessionOperationEvent,
+  AgentSessionOperationRecord,
+} from "@/types/sdk/AgentSessionOperation.js";
 import type {
   SessionAssistantStepCallback,
   SessionUiMessageChunkCallback,
@@ -66,6 +71,15 @@ export interface SessionRunContext {
    */
   onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
 
+  /**
+   * operation 发布回调。
+   *
+   * 关键点（中文）
+   * - 用于把 compaction 等辅助操作转成 session event 与 operation message。
+   * - operation 不代表 assistant 正文，也不会进入 LLM 输入。
+   */
+  onOperationCallback?: AgentSessionOperationCallback;
+
   /**
    * 当前 turn 的取消信号。
    *
@@ -101,3 +115,9 @@ export interface SessionRunContext {
    */
   pendingAssistantFileParts: FileUIPart[];
 }
+
+export type {
+  AgentSessionOperationCallback,
+  AgentSessionOperationEvent,
+  AgentSessionOperationRecord,
+};

package/src/types/plugin/PluginToolRuntime.ts

@@ -0,0 +1,86 @@
+/**
+ * Plugin tool runtime 绑定类型。
+ *
+ * 关键点（中文）
+ * - plugin_call / plugin_read 必须绑定当前 Agent 自己的 plugin registry。
+ * - 这些类型描述 tool 工厂与 bridge 调用时需要的显式 runtime 依赖。
+ */
+
+import type { Tool } from "ai";
+import type { AgentPlugins } from "@/types/plugin/PluginRuntime.js";
+import type {
+  PluginCallInput,
+  PluginReadInput,
+} from "@/executor/tools/plugin/types/PluginTool.js";
+
+/**
+ * 创建 plugin tools 的参数。
+ */
+export interface CreatePluginToolsOptions {
+  /**
+   * 当前 Agent 自己的 plugin 调用面。
+   *
+   * 关键点（中文）
+   * - 该引用必须来自当前 Agent 装配出的 plugin registry。
+   * - tool 执行时只能通过它访问 plugin，避免跨 Agent 读到其他 registry。
+   */
+  plugins: AgentPlugins;
+}
+
+/**
+ * 当前 Agent 专属 plugin tools。
+ */
+export interface AgentPluginTools {
+  /**
+   * 读取 plugin metadata 的模型工具。
+   *
+   * 关键点（中文）
+   * - 该 tool 通过闭包绑定当前 Agent 的 `plugins`。
+   * - 不读取任何模块级全局 runtime。
+   */
+  plugin_read: Tool;
+
+  /**
+   * 执行 plugin action 的模型工具。
+   *
+   * 关键点（中文）
+   * - 该 tool 通过闭包绑定当前 Agent 的 `plugins`。
+   * - 多 Agent 并发时，每个 Agent 都有自己的 tool 实例。
+   */
+  plugin_call: Tool;
+}
+
+/**
+ * 调用 plugin_call bridge 的参数。
+ */
+export interface InvokePluginCallToolOptions {
+  /**
+   * 当前 Agent 自己的 plugin 调用面。
+   *
+   * 关键点（中文）
+   * - 由 Agent 级 tool 工厂注入。
+   * - 不能在 bridge 内通过全局变量读取。
+   */
+  plugins: AgentPlugins;
+
+  /**
+   * 模型提交给 plugin_call 的结构化输入。
+   */
+  input: PluginCallInput;
+}
+
+/**
+ * 调用 plugin_read bridge 的参数。
+ */
+export interface InvokePluginReadToolOptions {
+  /**
+   * 当前 Agent 自己的 plugin 调用面。
+   */
+  plugins: AgentPlugins;
+
+  /**
+   * 模型提交给 plugin_read 的结构化输入。
+   */
+  input: PluginReadInput;
+}
+

package/src/types/sdk/AgentSessionEvent.ts

@@ -8,6 +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";
 
 /**
  * 单个 turn 开始事件。
@@ -354,6 +355,7 @@ export type AgentSessionEvent =
   | AgentSessionToolApprovalResultEvent
   | AgentSessionAssistantStepEvent
   | AgentSessionTitleEvent
+  | AgentSessionOperationEvent
   | AgentSessionTurnFinishEvent
   | AgentSessionErrorEvent;
 

package/src/types/sdk/AgentSessionOperation.ts

@@ -0,0 +1,125 @@
+/**
+ * Agent Session operation 类型定义。
+ *
+ * 关键点（中文）
+ * - operation 描述 session 内部正在发生的辅助操作，不代表 assistant 正文。
+ * - operation 可以同时作为订阅事件发布，也可以作为 UIMessage 持久化到 JSONL。
+ * - operation message 只用于前端时间线与调试，不应进入 LLM 输入。
+ */
+
+import type { JsonValue } from "@/types/common/Json.js";
+
+/**
+ * Session operation 当前状态。
+ */
+export type AgentSessionOperationStatus =
+  | "started"
+  | "progress"
+  | "finished"
+  | "skipped"
+  | "failed";
+
+/**
+ * Session operation 名称。
+ *
+ * 说明（中文）
+ * - 内置名称用于 SDK 与前端约定常见辅助操作。
+ * - 字符串扩展允许 plugin 或宿主运行时声明自己的 operation。
+ */
+export type AgentSessionOperationName =
+  | "compacting"
+  | "model-switching"
+  | "history-forking"
+  | (string & {});
+
+/**
+ * Session operation 记录。
+ */
+export interface AgentSessionOperationRecord {
+  /**
+   * 同一个 operation 生命周期内稳定复用的 ID。
+   */
+  operationId: string;
+
+  /**
+   * 当前 operation 名称。
+   */
+  name: AgentSessionOperationName;
+
+  /**
+   * 当前 operation 状态。
+   */
+  status: AgentSessionOperationStatus;
+
+  /**
+   * 当前 operation 关联的 turn 标识。
+   *
+   * 说明（中文）
+   * - turn 内触发的 operation 应写入该字段。
+   * - session 级 operation 可以省略。
+   */
+  turnId?: string;
+
+  /**
+   * 面向用户展示的短文本。
+   */
+  label?: string;
+
+  /**
+   * 机器可读原因。
+   *
+   * 示例（中文）
+   * - `under_budget`：未达到压缩阈值。
+   * - `summary_fallback`：摘要生成失败后使用降级摘要。
+   */
+  reason?: string;
+
+  /**
+   * 当前 operation 进度，范围 0 到 1。
+   *
+   * 说明（中文）
+   * - 无法估算进度时省略。
+   */
+  progress?: number;
+
+  /**
+   * operation 完成后产生的轻量结果。
+   */
+  result?: JsonValue;
+
+  /**
+   * operation 失败时的错误文本。
+   */
+  error?: string;
+
+  /**
+   * 是否建议前端展示。
+   *
+   * 说明（中文）
+   * - 默认视为 `true`。
+   * - 调试或审计类辅助事件可显式写入 `false`。
+   */
+  visible?: boolean;
+}
+
+/**
+ * Session operation 订阅事件。
+ */
+export interface AgentSessionOperationEvent extends AgentSessionOperationRecord {
+  /**
+   * 当前事件类型。
+   */
+  type: "operation";
+
+  /**
+   * 当前 session 唯一标识。
+   */
+  sessionId: string;
+}
+
+/**
+ * Session operation 发布回调。
+ */
+export type AgentSessionOperationCallback = (
+  operation: AgentSessionOperationEvent,
+) => Promise<void>;