@downcity/agent 1.1.188 → 1.1.195

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

@@ -0,0 +1,182 @@
+/**
+ * @file 验证 operation message 的持久化、模型输入过滤与 timeline 投影。
+ *
+ * 关键点（中文）
+ * - operation message 会作为 UIMessage 写入 JSONL。
+ * - history composer 组装 LLM 输入时必须过滤 operation message。
+ * - timeline view 可以把 operation message 投影成前端可识别的 operation 事件。
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+import { JsonlSessionHistoryStore } from "../bin/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import { JsonlSessionHistoryComposer } from "../bin/executor/composer/history/jsonl/JsonlSessionHistoryComposer.js";
+import { toSessionTimelineEvents } from "../bin/session/browse/Browse.js";
+import { Agent } from "../bin/index.js";
+
+test("operation message is persisted but filtered from LLM history", async () => {
+  const root_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-operation-message-"),
+  );
+  const session_id = "operation_session";
+  const store = new JsonlSessionHistoryStore({
+    rootPath: root_path,
+    agentId: "operation_agent",
+    sessionId: session_id,
+  });
+  const composer = new JsonlSessionHistoryComposer({ store });
+
+  await store.append(
+    store.userText({
+      text: "hello",
+      metadata: { sessionId: session_id },
+      id: "u:1",
+    }),
+  );
+  await store.append(
+    store.operation({
+      operation: {
+        operationId: "op-1",
+        name: "compacting",
+        status: "started",
+        label: "Compacting session history",
+        turnId: "turn-1",
+      },
+      metadata: { sessionId: session_id },
+      id: "op:1",
+    }),
+  );
+  await store.append(
+    store.assistantText({
+      text: "world",
+      metadata: { sessionId: session_id },
+      id: "a:1",
+    }),
+  );
+
+  const persisted_messages = await store.list();
+  assert.equal(persisted_messages.length, 3);
+  assert.equal(persisted_messages[1].metadata.kind, "operation");
+  assert.equal(persisted_messages[1].metadata.operation.operationId, "op-1");
+
+  const model_messages = await composer.prepare({
+    query: "",
+    tools: {},
+    system: [],
+    model: {},
+    retryCount: 0,
+  });
+  assert.deepEqual(
+    model_messages.map((message) => message.id),
+    ["u:1", "a:1"],
+  );
+
+  const timeline_events = toSessionTimelineEvents(persisted_messages[1]);
+  assert.equal(timeline_events.length, 1);
+  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");
+});
+
+test("session.set persists and publishes model-switching operations", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-model-switching-"),
+  );
+  const agent = new Agent({
+    id: "model_switching_agent",
+    path: agent_path,
+  });
+  try {
+    const session = await agent.session_collection().create_session({
+      sessionId: "model_switching_session",
+    });
+    const events = [];
+    const unsubscribe = session.subscribe((event) => {
+      if (event.type === "operation") events.push(event);
+    });
+
+    await session.set({
+      model: {
+        modelId: "test-model",
+        provider: "test",
+      },
+    });
+    unsubscribe();
+
+    assert.deepEqual(
+      events.map((event) => `${event.name}:${event.status}`),
+      ["model-switching:started", "model-switching:finished"],
+    );
+
+    const history = await session.history({ view: "timeline" });
+    const operation_events = history.items.filter(
+      (item) => item.role === "operation",
+    );
+    assert.deepEqual(
+      operation_events.map((event) => `${event.operationName}:${event.operationStatus}`),
+      ["model-switching:started", "model-switching:finished"],
+    );
+  } finally {
+    await agent.dispose();
+  }
+});
+
+test("session.fork persists and publishes history-forking operations on source session", async () => {
+  const agent_path = await fs.mkdtemp(
+    path.join(os.tmpdir(), "downcity-agent-history-forking-"),
+  );
+  const agent = new Agent({
+    id: "history_forking_agent",
+    path: agent_path,
+  });
+  try {
+    const session = await agent.session_collection().create_session({
+      sessionId: "history_forking_session",
+    });
+    await session.set({
+      model: {
+        modelId: "fork-test-model",
+        provider: "test",
+      },
+    });
+    await session.appendUserMessage({ text: "source message" });
+
+    const events = [];
+    const unsubscribe = session.subscribe((event) => {
+      if (event.type === "operation" && event.name === "history-forking") {
+        events.push(event);
+      }
+    });
+    const forked = await session.fork();
+    unsubscribe();
+
+    assert.deepEqual(
+      events.map((event) => `${event.name}:${event.status}`),
+      ["history-forking:started", "history-forking:finished"],
+    );
+    assert.notEqual(forked.id, session.id);
+
+    const source_history = await session.history({ view: "timeline" });
+    const source_fork_operations = source_history.items.filter(
+      (item) => item.operationName === "history-forking",
+    );
+    assert.deepEqual(
+      source_fork_operations.map((event) => event.operationStatus),
+      ["started", "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);
+  } finally {
+    await agent.dispose();
+  }
+});

package/src/executor/Executor.ts

@@ -22,11 +22,13 @@ import type { SessionContextComposer } from "@executor/composer/context/SessionC
 import type { SessionSystemComposer } from "@executor/composer/system/SessionSystemComposer.js";
 import { ExecutorInflightService } from "@executor/services/ExecutorInflightService.js";
 import { ExecutorRecoveryPolicy } from "@executor/services/ExecutorRecoveryPolicy.js";
+import { generateId } from "@/utils/Id.js";
 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 { SessionExecutor } from "@/executor/types/SessionExecutor.js";
 import type { SessionRunContext } from "@/types/executor/SessionRunContext.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 import type {
   SessionExecuteInput,
   SessionRunResult,
@@ -360,6 +362,7 @@ export class Executor implements SessionExecutor {
     const composed_context = await this.contextComposer.compose(run_context);
     const tools = this.bind_run_scope_to_tools(composed_context.tools, run_context);
     const system = await this.systemComposer.resolve(run_context);
+    let compaction_operation_id = "";
 
     try {
       if (retry_count > 0) {
@@ -368,13 +371,33 @@ export class Executor implements SessionExecutor {
         });
       }
 
+      const emit_compaction_operation = async (
+        operation: AgentSessionOperationRecord,
+      ): Promise<void> => {
+        if (operation.status === "started") {
+          compaction_operation_id = operation.operationId;
+        }
+        await this.emitOperation(run_context, operation);
+      };
+
       await this.compactionComposer.run({
         historyStore: this.historyStore,
         model,
         system,
         retryCount: retry_count,
+        onOperation: emit_compaction_operation,
+      });
+    } catch (error) {
+      await this.emitOperation(run_context, {
+        operationId:
+          compaction_operation_id ||
+          `compacting:${this.sessionId}:failed:${Date.now()}:${generateId()}`,
+        name: "compacting",
+        status: "failed",
+        label: "Session history compact failed",
+        error: error instanceof Error ? error.message : String(error),
+        visible: false,
       });
-    } catch {
       // 压缩失败不阻断主流程，继续使用当前历史消息执行。
     }
 
@@ -469,6 +492,9 @@ export class Executor implements SessionExecutor {
       ...(typeof input?.onUiMessageChunkCallback === "function"
         ? { onUiMessageChunkCallback: input.onUiMessageChunkCallback }
         : {}),
+      ...(typeof input?.onOperationCallback === "function"
+        ? { onOperationCallback: input.onOperationCallback }
+        : {}),
       ...(input?.abortSignal ? { abortSignal: input.abortSignal } : {}),
       injectedUserMessages: Array.isArray(input?.injectedUserMessages)
         ? [...input.injectedUserMessages]
@@ -484,6 +510,28 @@ export class Executor implements SessionExecutor {
     };
   }
 
+  /**
+   * 发布一次 session operation。
+   */
+  private async emitOperation(
+    run_context: SessionRunContext,
+    operation: AgentSessionOperationRecord,
+  ): Promise<void> {
+    if (typeof run_context.onOperationCallback !== "function") return;
+    const operation_id =
+      String(operation.operationId || "").trim() ||
+      `operation:${this.sessionId}:${Date.now()}:${generateId()}`;
+    await run_context.onOperationCallback({
+      type: "operation",
+      sessionId: run_context.sessionId || this.sessionId,
+      ...operation,
+      operationId: operation_id,
+      ...(run_context.turnId && !operation.turnId
+        ? { turnId: run_context.turnId }
+        : {}),
+    });
+  }
+
   /**
    * 读取当前 session 模型。
    */

package/src/executor/composer/compaction/SessionCompactionComposer.ts

@@ -8,6 +8,7 @@
 
 import type { LanguageModel, SystemModelMessage } from "ai";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 /**
  * compaction Composer 执行输入。
@@ -32,6 +33,15 @@ export type SessionCompactionInput = {
    * 当前重试次数（由 Executor 递增）。
    */
   retryCount: number;
+
+  /**
+   * 可选 operation 发布回调。
+   *
+   * 说明（中文）
+   * - 默认 compaction Composer 可在真正开始压缩时发布 `compacting`。
+   * - 回调由上层 Session 负责转成订阅事件与 operation message。
+   */
+  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
 };
 
 /**

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionComposer.ts

@@ -79,6 +79,7 @@ export class JsonlSessionCompactionComposer implements SessionCompactionComposer
       maxInputTokensApprox: policy.maxInputTokensApprox,
       archiveOnCompact: policy.archiveOnCompact,
       compactRatio: policy.compactRatio,
+      ...(input.onOperation ? { onOperation: input.onOperation } : {}),
     });
   }
 

package/src/executor/composer/compaction/jsonl/JsonlSessionCompactionExecutor.ts

@@ -21,7 +21,9 @@ 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 type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 export type SessionCompactParams = {
   model: LanguageModel;
@@ -30,6 +32,7 @@ export type SessionCompactParams = {
   maxInputTokensApprox: number;
   archiveOnCompact: boolean;
   compactRatio: number;
+  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
 };
 
 type SessionCompactDeps = {
@@ -60,6 +63,19 @@ export async function compactSessionMessagesIfNeeded(
   params: SessionCompactParams,
 ): Promise<{ compacted: boolean; reason?: string }> {
   const logger = getLogger(deps.rootPath, "info");
+  const operation_id = `compacting:${deps.sessionId}:${Date.now()}:${generateId()}`;
+  let operation_started = false;
+
+  const publish_operation = async (
+    operation: Omit<AgentSessionOperationRecord, "operationId" | "name">,
+  ): Promise<void> => {
+    if (typeof params.onOperation !== "function") return;
+    await params.onOperation({
+      operationId: operation_id,
+      name: "compacting",
+      ...operation,
+    });
+  };
 
   // 算法阶段（中文）
   // phase 1：snapshot（短锁）
@@ -68,7 +84,9 @@ export async function compactSessionMessagesIfNeeded(
   let snapshot: SessionMessageV1[] = [];
   let snapshotTailId = "";
   await deps.withWriteLock(async () => {
-    snapshot = await deps.loadAll();
+    snapshot = (await deps.loadAll()).filter(
+      (message) => !isSessionOperationMessage(message),
+    );
     snapshotTailId =
       snapshot.length > 0
         ? String(snapshot[snapshot.length - 1].id || "")
@@ -100,6 +118,13 @@ export async function compactSessionMessagesIfNeeded(
   const older = snapshot.slice(0, compactCount);
   if (older.length === 0) return { compacted: false, reason: "nothing_to_compact" };
 
+  operation_started = true;
+  await publish_operation({
+    status: "started",
+    label: "Compacting session history",
+    progress: 0,
+  });
+
   const olderTextAll = extractPlainTextFromMessages(older);
   const maxOlderChars = 24_000;
   const olderText =
@@ -138,6 +163,12 @@ export async function compactSessionMessagesIfNeeded(
       },
     );
     summary = "（系统自动压缩：摘要生成失败，已丢弃更早历史，仅保留最近对话。）";
+    await publish_operation({
+      status: "progress",
+      label: "Compacting session history",
+      reason: "summary_fallback",
+      progress: 0.5,
+    });
   }
 
   const fromId = String(older[0]?.id || "");
@@ -159,10 +190,20 @@ export async function compactSessionMessagesIfNeeded(
     // snapshotTailId 用于 debug，不作为强一致性依赖。
     void snapshotTailId;
 
-    const currentCompactCount = resolveCompactCount(current.length, compactRatio);
-    const currentOlder = current.slice(0, currentCompactCount);
-    const currentKept = current.slice(currentCompactCount);
+    const current_model_messages = current.filter(
+      (message) => !isSessionOperationMessage(message),
+    );
+    const currentCompactCount = resolveCompactCount(
+      current_model_messages.length,
+      compactRatio,
+    );
+    const currentOlder = current_model_messages.slice(0, currentCompactCount);
     if (currentOlder.length === 0) return;
+    const compacted_ids = new Set(
+      currentOlder
+        .map((message) => String(message.id || "").trim())
+        .filter(Boolean),
+    );
 
     if (params.archiveOnCompact) {
       const archivePath = path.join(
@@ -181,7 +222,13 @@ export async function compactSessionMessagesIfNeeded(
       );
     }
 
-    const next = [summaryMsg, ...currentKept];
+    const next = [
+      summaryMsg,
+      ...current.filter((message) => {
+        const id = String(message.id || "").trim();
+        return !id || !compacted_ids.has(id);
+      }),
+    ];
 
     const messagesPath = deps.getMessagesFilePath();
     const tmp = messagesPath + ".tmp";
@@ -195,6 +242,18 @@ export async function compactSessionMessagesIfNeeded(
     });
   });
 
+  if (operation_started) {
+    await publish_operation({
+      status: "finished",
+      label: "Session history compacted",
+      progress: 1,
+      result: {
+        archiveId,
+        compactedCount: older.length,
+      },
+    });
+  }
+
   return { compacted: true };
 }
 

package/src/executor/composer/history/jsonl/JsonlSessionHistoryComposer.ts

@@ -8,7 +8,10 @@
  */
 
 import type { Tool } from "ai";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import {
+  isSessionOperationMessage,
+  type SessionMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import type { SessionHistoryStore } from "@/executor/store/history/SessionHistoryStore.js";
 import type {
   SessionHistoryComposer,
@@ -91,6 +94,7 @@ export class JsonlSessionHistoryComposer implements SessionHistoryComposer {
           parts,
         };
       })
+      .filter((message) => !isSessionOperationMessage(message))
       .filter((message) => Array.isArray(message.parts) && message.parts.length > 0);
   }
 

package/src/executor/messages/SessionMessageCodec.ts

@@ -14,7 +14,10 @@ import {
   type Tool,
   type ToolSet,
 } from "ai";
-import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import {
+  isSessionOperationMessage,
+  type SessionMessageV1,
+} from "@/executor/types/SessionMessages.js";
 import {
   hydrateFileUrlPartsForModel,
   injectFilePartsFromAttachments,
@@ -77,9 +80,15 @@ export async function toModelMessages(
   // 空输入快速返回，避免调用转换器的额外开销。
   if (!Array.isArray(messages) || messages.length === 0) return [];
 
+  // operation message 只服务前端时间线，不能传入模型。
+  const model_messages = messages.filter(
+    (message) => !isSessionOperationMessage(message),
+  );
+  if (model_messages.length === 0) return [];
+
   // 第一步（中文）：在 user 消息上注入 file parts（多模态附件）。
   const enrichedMessages = await injectFilePartsFromAttachments(
-    messages,
+    model_messages,
     projectRoot,
   );
 

package/src/executor/store/history/SessionHistoryStore.ts

@@ -13,6 +13,7 @@ import type {
   SessionMetadataV1,
 } from "@/executor/types/SessionMessages.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 
 /**
  * compact 输入参数。
@@ -47,6 +48,11 @@ export type SessionHistoryCompactInput = {
    * 前段压缩比例（0-1）。
    */
   compactRatio: number;
+
+  /**
+   * 可选 operation 发布回调。
+   */
+  onOperation?: (operation: AgentSessionOperationRecord) => Promise<void>;
 };
 
 /**
@@ -157,4 +163,25 @@ export interface SessionHistoryStore {
      */
     source?: "egress" | "compact";
   }): SessionMessageV1;
+
+  /**
+   * 构造 operation 消息。
+   */
+  operation(input: {
+    /**
+     * 当前 operation 结构化记录。
+     */
+    operation: AgentSessionOperationRecord;
+
+    /**
+     * 消息元信息（除 schema 字段、kind、source 与 operation 字段）。
+     */
+    metadata: Omit<SessionMetadataV1, "v" | "ts" | "kind" | "source" | "operation"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+
+    /**
+     * 可选消息 ID（默认自动生成）。
+     */
+    id?: string;
+  }): SessionMessageV1;
 }

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

@@ -21,6 +21,7 @@ import type {
   SessionMessageV1,
   SessionMetadataV1,
 } from "@/executor/types/SessionMessages.js";
+import type { AgentSessionOperationRecord } from "@/types/sdk/AgentSessionOperation.js";
 import type { SessionSystemMessage } from "@/executor/types/SessionPrompts.js";
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import type { SessionHistoryPathOverrides } from "@/executor/types/SessionHistoryPaths.js";
@@ -435,6 +436,44 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     return system.filter((item) => item && typeof item === "object");
   }
 
+  private normalizeOperation(
+    operation: AgentSessionOperationRecord,
+  ): AgentSessionOperationRecord {
+    const operation_id = String(operation.operationId || "").trim() || generateId();
+    const name = String(operation.name || "").trim() || "operation";
+    const status = String(operation.status || "").trim();
+    const normalized_status: AgentSessionOperationRecord["status"] =
+      status === "started" ||
+      status === "progress" ||
+      status === "finished" ||
+      status === "skipped" ||
+      status === "failed"
+        ? status
+        : "progress";
+    return {
+      operationId: operation_id,
+      name,
+      status: normalized_status,
+      ...(typeof operation.turnId === "string" && operation.turnId.trim()
+        ? { turnId: operation.turnId.trim() }
+        : {}),
+      ...(typeof operation.label === "string" && operation.label.trim()
+        ? { label: operation.label.trim() }
+        : {}),
+      ...(typeof operation.reason === "string" && operation.reason.trim()
+        ? { reason: operation.reason.trim() }
+        : {}),
+      ...(typeof operation.progress === "number" && Number.isFinite(operation.progress)
+        ? { progress: Math.max(0, Math.min(1, operation.progress)) }
+        : {}),
+      ...(operation.result !== undefined ? { result: operation.result } : {}),
+      ...(typeof operation.error === "string" && operation.error.trim()
+        ? { error: operation.error.trim() }
+        : {}),
+      ...(operation.visible === false ? { visible: false } : {}),
+    };
+  }
+
   async compact(input: SessionHistoryCompactInput): Promise<{
     compacted: boolean;
     reason?: string;
@@ -471,6 +510,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
         maxInputTokensApprox: input.maxInputTokensApprox,
         archiveOnCompact: input.archiveOnCompact,
         compactRatio: input.compactRatio,
+        ...(input.onOperation ? { onOperation: input.onOperation } : {}),
       },
     );
   }
@@ -633,4 +673,30 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
       parts: [{ type: "text", text: String(input.text ?? "") }],
     };
   }
+
+  operation(input: {
+    operation: AgentSessionOperationRecord;
+    metadata: Omit<SessionMetadataV1, "v" | "ts" | "kind" | "source" | "operation"> &
+      Partial<Pick<SessionMetadataV1, "ts">>;
+    id?: string;
+  }): SessionMessageV1 {
+    const operation = this.normalizeOperation(input.operation);
+    const label = String(
+      operation.label || `${operation.name}: ${operation.status}`,
+    ).trim();
+    const { ts, ...metadata } = input.metadata;
+    return {
+      id: input.id || `op:${this.sessionId}:${operation.operationId}:${generateId()}`,
+      role: "assistant",
+      metadata: {
+        v: 1,
+        ts: typeof ts === "number" ? ts : Date.now(),
+        ...metadata,
+        source: "operation",
+        kind: "operation",
+        operation,
+      },
+      parts: [{ type: "text", text: label }],
+    };
+  }
 }

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";
+}