@axiom-lattice/protocols 4.3.1 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/CapabilityBundleStoreProtocol.ts

@@ -47,9 +47,9 @@ export interface UpdateCapabilityBundleInput extends Partial<CreateCapabilityBun
   expectedUpdatedAt: string;
 }
 
-/** Store input retained for internal maintenance callers that may omit CAS. */
+/** Store input for updating a bundle; the stable key is immutable and the revision is always required for CAS. */
 export interface InternalUpdateCapabilityBundleInput extends Partial<CreateCapabilityBundleInput> {
-  expectedUpdatedAt?: string;
+  expectedUpdatedAt: string;
 }
 
 /** Result returned when an update's expected revision no longer matches. */
@@ -70,8 +70,7 @@ export interface CapabilityBundleStore {
   getManyByIds(tenantId: string, ids: string[]): Promise<CapabilityBundle[]>;
   /** Creates a bundle for a tenant. */
   create(tenantId: string, input: InternalCreateCapabilityBundleInput): Promise<CapabilityBundle>;
-  /** Updates a bundle, or returns null when it does not exist. */
-  /** Omitted expectedUpdatedAt is reserved for internal maintenance callers. */
+  /** Updates a bundle with mandatory revision CAS, or returns null when it does not exist. */
   update(tenantId: string, id: string, input: InternalUpdateCapabilityBundleInput): Promise<CapabilityBundle | CapabilityBundleUpdateConflict | null>;
   /** Atomically deletes a bundle unless a tenant project references it. */
   deleteIfUnreferenced(tenantId: string, id: string): Promise<CapabilityBundleDeleteResult>;

package/src/McpUiProtocol.ts

@@ -0,0 +1,76 @@
+/** Display modes supported by MCP Apps. */
+export type McpUiDisplayMode = "inline" | "fullscreen" | "pip";
+
+/** CSP origins declared by a UI resource. */
+export interface McpUiCsp {
+  connectDomains?: string[];
+  resourceDomains?: string[];
+  frameDomains?: string[];
+  baseUriDomains?: string[];
+}
+
+/** Sandbox permissions requested by a UI resource. */
+export interface McpUiPermissions {
+  camera?: boolean;
+  microphone?: boolean;
+  geolocation?: boolean;
+  clipboardWrite?: boolean;
+}
+
+/** A UI ref carried in the `mcp_app` content fence. */
+export type McpUiRef =
+  | {
+      kind: "mcp";
+      serverKey: string;
+      resourceUri: string;
+      displayMode: McpUiDisplayMode;
+      title?: string;
+      /**
+       * Retained only for backward compatibility with pre-unification
+       * messages; no longer emitted. Rich tool results now travel via
+       * `ToolCall.ui`.
+       */
+      structuredContent?: unknown;
+    }
+  | { kind: "plugin"; pluginType: string; resource: string; displayMode: McpUiDisplayMode; title?: string };
+
+/** Resolved UI resource body returned by the gateway. */
+export interface McpUiResourcePayload {
+  mimeType: string;
+  html: string;
+  csp?: McpUiCsp;
+  permissions?: McpUiPermissions;
+  prefersBorder?: boolean;
+  stale?: boolean;
+}
+
+const MODES: McpUiDisplayMode[] = ["inline", "fullscreen", "pip"];
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
+
+/** Type guard for a parsed `McpUiRef`. */
+export function isMcpUiRef(value: unknown): value is McpUiRef {
+  return parseMcpUiRef(value) !== null;
+}
+
+/** Parse and normalize an unknown value into a `McpUiRef`, or `null`. */
+export function parseMcpUiRef(value: unknown): McpUiRef | null {
+  if (!isObj(value)) return null;
+  const displayMode = MODES.includes(value.displayMode as McpUiDisplayMode)
+    ? (value.displayMode as McpUiDisplayMode)
+    : "inline";
+  const title = typeof value.title === "string" ? value.title : undefined;
+  if (value.kind === "mcp" && typeof value.serverKey === "string" && typeof value.resourceUri === "string") {
+    return {
+      kind: "mcp",
+      serverKey: value.serverKey,
+      resourceUri: value.resourceUri,
+      displayMode,
+      ...(title ? { title } : {}),
+      ...(value.structuredContent !== undefined ? { structuredContent: value.structuredContent } : {}),
+    };
+  }
+  if (value.kind === "plugin" && typeof value.pluginType === "string" && typeof value.resource === "string") {
+    return { kind: "plugin", pluginType: value.pluginType, resource: value.resource, displayMode, ...(title ? { title } : {}) };
+  }
+  return null;
+}

package/src/MenuProtocol.ts

@@ -5,9 +5,12 @@
  * Menu items are merged with built-in defaults at the React SDK layer.
  */
 
+import type { McpUiDisplayMode } from "./McpUiProtocol";
+import type { ToolCallUi } from "./MessageProtocol";
+
 export type MenuTarget = 'sidebar' | 'workspace';
 
-export type MenuContentType = 'agent' | 'html' | 'custom';
+export type MenuContentType = 'agent' | 'html' | 'custom' | 'file' | 'mcpApp';
 
 export interface AgentMenuConfig {
   agentId: string;
@@ -25,7 +28,52 @@ export interface CustomMenuConfig {
   componentKey: string;
 }
 
-export type MenuContentConfig = AgentMenuConfig | HtmlMenuConfig | CustomMenuConfig;
+/**
+ * A pinned MCP App menu item.
+ *
+ * The identity (`kind` + server/plugin + resource) is enough to re-open the
+ * App; `toolInput` lets a self-refreshing App re-run the same query. The pin
+ * flow also captures the current `toolResult` and `ui` so the pinned view has
+ * the same initial data as the chat view did (an App that refreshes itself can
+ * still re-query).
+ */
+export type McpAppMenuConfig =
+  | {
+      kind: 'mcp';
+      serverKey: string;
+      resourceUri: string;
+      displayMode?: McpUiDisplayMode;
+      title?: string;
+      toolInput?: Record<string, unknown>;
+      toolResult?: unknown;
+      ui?: ToolCallUi;
+    }
+  | {
+      kind: 'plugin';
+      pluginType: string;
+      resource: string;
+      displayMode?: McpUiDisplayMode;
+      title?: string;
+      toolInput?: Record<string, unknown>;
+      toolResult?: unknown;
+      ui?: ToolCallUi;
+    };
+
+/** A pinned workspace file rendered by the file viewer. */
+export interface FileMenuConfig {
+  resourcePath: string;
+  fileName?: string;
+  workspaceId?: string;
+  projectId?: string;
+  assistantId?: string;
+}
+
+export type MenuContentConfig =
+  | AgentMenuConfig
+  | HtmlMenuConfig
+  | CustomMenuConfig
+  | FileMenuConfig
+  | McpAppMenuConfig;
 
 export interface MenuItem {
   id: string;

package/src/MessageProtocol.ts

@@ -24,6 +24,22 @@ export interface UserMessage extends BaseMessage {
   files?: Array<{ name: string; id: string }>; // Optional files attached to the message
 }
 
+/**
+ * UI-only rich payload for a tool call.
+ *
+ * Populated by the client-side message merger from the tool message's raw
+ * LangChain `artifact` and non-text content blocks. It is never part of the
+ * model-visible text: the model only sees `ToolCall.response`.
+ */
+export interface ToolCallUi {
+  /** MCP `CallToolResult.structuredContent`, when the tool produced one. */
+  structuredContent?: unknown;
+  /** MCP `CallToolResult._meta`, when present. */
+  meta?: Record<string, unknown>;
+  /** Non-text content blocks (image / audio / resource / file). */
+  contentBlocks?: Array<{ type: string; [key: string]: unknown }>;
+}
+
 /**
  * Tool call interface
  */
@@ -33,6 +49,12 @@ export interface ToolCall {
   args: Record<string, any>; // Arguments as an object
   type: "tool_call"; // Type of tool call
   response?: string; // Optional response from the tool execution
+  /** UI-only rich result (MCP Apps). Never part of the model-visible text. */
+  ui?: ToolCallUi;
+  /** Execution status reported by the client-side message merger. */
+  status?: "success" | "pending" | "error";
+  /** Correlation id of the originating tool message (internal). */
+  original_tool_message_id?: string;
 }
 
 /**
@@ -106,6 +128,8 @@ export interface MessageChunk {
       id?: string;
       index: number;
     }>;
+    // Wire shape: intentionally lacks `ui`, which is client-populated on ToolCall
+    // from the tool message's `artifact` and never sent by the server.
     tool_calls?: Array<{
       name: string;
       args: Record<string, any>;
@@ -120,6 +144,12 @@ export interface MessageChunk {
       }>;
     };
     tool_call_id?: string;
+    /**
+     * Raw LangChain tool message `artifact` (e.g. MCP `structuredContent`
+     * and non-text content blocks). Present on `tool` chunks; consumed by the
+     * client-side message merger to populate `ToolCall.ui`.
+     */
+    artifact?: unknown;
   };
 }
 

package/src/OpenProtocol.ts

@@ -20,7 +20,7 @@ export interface OpenExecutionContext {
   projectId: string;
   /** Addressing only, not an authorization dimension (see design §6.2). */
   workspaceId?: string;
-  /** Synthesized runConfig (mirrors the Agent path, incl. _resolvedConnections). */
+  /** Synthesized run identity (mirrors the Agent path's runConfig; plugin tools resolve their own connections). */
   runConfig: Record<string, unknown>;
 }
 

package/src/PluginProtocol.ts

@@ -1,4 +1,5 @@
 import type { AgentConfig } from "./AgentLatticeProtocol";
+import type { McpUiDisplayMode, McpUiCsp, McpUiPermissions } from "./McpUiProtocol";
 
 /**
  * Plugin Connection 字段 schema（驱动前端表单渲染）
@@ -80,6 +81,37 @@ export interface PluginConnection {
   resourceLabel?: string;
 }
 
+/**
+ * UI declaration for a plugin tool: an HTML file rendered as an MCP App when
+ * the tool runs.
+ *
+ * @property resource - Safe relative path (within the plugin directory) to an `.html` file.
+ * @property displayMode - Preferred display mode; defaults to `inline` (resolved by the compiler).
+ * @property csp - Origins the UI needs (see `McpUiCsp`).
+ * @property permissions - Sandbox permissions requested (see `McpUiPermissions`).
+ * @property prefersBorder - Visual boundary preference.
+ */
+export interface PluginToolUi {
+  resource: string;
+  displayMode?: McpUiDisplayMode;
+  csp?: McpUiCsp;
+  permissions?: McpUiPermissions;
+  prefersBorder?: boolean;
+}
+
+/**
+ * Inline UI resource served by a GLOBAL (non-sandbox) plugin.
+ *
+ * @property html - Full HTML document served for a `ui://` resource.
+ * @property mimeType - Defaults to `text/html;profile=mcp-app` when omitted.
+ * @property csp - Origins the UI needs.
+ */
+export interface PluginUiResource {
+  html: string;
+  mimeType?: string;
+  csp?: McpUiCsp;
+}
+
 /**
  * 工具元信息（用于前端 allowedTools 筛选）
  *
@@ -92,6 +124,8 @@ export interface PluginToolMeta {
   description: string;
   /** When true, this tool surfaces on the Open API (MCP) surface. */
   expose?: boolean;
+  /** Optional UI (HTML) declaration for this tool. */
+  ui?: PluginToolUi;
 }
 
 /** Open-surface exposure entry with MCP annotation hints. */
@@ -163,6 +197,8 @@ export interface PluginMeta {
   icon?: string;
   /** 工具清单（可选，middleware 能自动提取时不需要写） */
   tools?: PluginToolMeta[];
+  /** Inline `ui://` resources for this plugin's tool UIs (global plugins only). */
+  uiResources?: Record<string, PluginUiResource>;
   /**
    * Open 面（MCP）暴露的工具名清单——独立于 tools 声明，一行即生长。
    * 声明后 OpenCredentialService 的 grants 匹配 domain=<meta.type>。

package/src/SandboxPluginProtocol.ts

@@ -1,5 +1,5 @@
 import type { AgentConfig } from "./AgentLatticeProtocol";
-import type { PluginConnectionFieldSchema, PluginSkillDefinition } from "./PluginProtocol";
+import type { PluginConnectionFieldSchema, PluginSkillDefinition, PluginToolUi } from "./PluginProtocol";
 
 /**
  * A single tool contributed by a sandbox-authored tenant plugin.
@@ -19,6 +19,8 @@ export interface SandboxPluginToolDef {
   destructive?: boolean;
   timeoutMs?: number;
   maxResultBytes?: number;
+  /** Optional UI (HTML) rendered as an MCP App when this tool runs. */
+  ui?: PluginToolUi;
 }
 
 /**

package/src/TaskStoreProtocol.ts

@@ -331,6 +331,25 @@ export interface UpdateTaskRequest {
   files?: TaskFileRef[];
 }
 
+/**
+ * Normalizes a task metadata scalar to its JSON text form so every task store
+ * backend compares metadata filters identically.
+ *
+ * The contract is JSON scalar value equality, type-tolerant: `1` and `"1"`
+ * are equal, `true` and `"true"` are equal, and `true` never equals `1`.
+ * PostgreSQL's `metadata->>` naturally yields this form; InMemory and SQLite
+ * use this helper to match it.
+ *
+ * @param value Candidate filter or stored metadata value.
+ * @returns JSON text form for string/number/boolean, otherwise `undefined`.
+ */
+export function normalizeTaskMetadataScalar(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : undefined;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  return undefined;
+}
+
 /**
  * Task list filter criteria
  */

package/src/TrustedRunContextProtocol.ts

@@ -16,6 +16,12 @@ export interface ProjectRoomTrustedRunContext {
   role: "coordinator" | "specialist";
   title: string;
   responsibility?: string;
+  /**
+   * Host-provided provenance string, persisted unchanged. Optional; a non-empty string when present;
+   * `undefined` is treated as absent. Core copies and compares this value without interpreting or
+   * naming any specific value (ADR-118).
+   */
+  source?: string;
 }
 
 /** Trusted Project Task identity persisted with a privileged queue message. */
@@ -29,6 +35,12 @@ export interface ProjectTaskTrustedRunContext {
   taskId: string;
   threadId: string;
   inputMessageId: string;
+  /**
+   * Host-provided provenance string, persisted unchanged. Optional; a non-empty string when present;
+   * `undefined` is treated as absent. Core copies and compares this value without interpreting or
+   * naming any specific value (ADR-118).
+   */
+  source?: string;
 }
 
 /** Host-authenticated metadata that cannot be supplied through public Agent APIs. */
@@ -54,37 +66,47 @@ export function parseTrustedRunContext(value: unknown): TrustedRunContext {
       "tenantId", "workspaceId", "projectId", "roomId", "membershipId",
       "assistantId", "taskId", "threadId", "inputMessageId",
     ] as const;
-    const projectTaskValues = snapshotExactRecord(contextValues.projectTask, requiredKeys);
+    const projectTaskValues = snapshotExactRecord(contextValues.projectTask, requiredKeys, ["source"]);
+    const projectTaskHasSource = projectTaskValues !== undefined
+      && Object.prototype.hasOwnProperty.call(projectTaskValues, "source");
     if (!projectTaskValues
-      || requiredKeys.some((key) => typeof projectTaskValues[key] !== "string" || projectTaskValues[key].length === 0)) {
+      || requiredKeys.some((key) => typeof projectTaskValues[key] !== "string" || projectTaskValues[key].length === 0)
+      || (projectTaskHasSource && projectTaskValues.source !== undefined
+        && (typeof projectTaskValues.source !== "string" || projectTaskValues.source.length === 0))) {
       throw new Error("Invalid trusted agent run context");
     }
-    return {
-      projectTask: {
-        tenantId: projectTaskValues.tenantId as string,
-        workspaceId: projectTaskValues.workspaceId as string,
-        projectId: projectTaskValues.projectId as string,
-        roomId: projectTaskValues.roomId as string,
-        membershipId: projectTaskValues.membershipId as string,
-        assistantId: projectTaskValues.assistantId as string,
-        taskId: projectTaskValues.taskId as string,
-        threadId: projectTaskValues.threadId as string,
-        inputMessageId: projectTaskValues.inputMessageId as string,
-      },
+    const parsedProjectTask: ProjectTaskTrustedRunContext = {
+      tenantId: projectTaskValues.tenantId as string,
+      workspaceId: projectTaskValues.workspaceId as string,
+      projectId: projectTaskValues.projectId as string,
+      roomId: projectTaskValues.roomId as string,
+      membershipId: projectTaskValues.membershipId as string,
+      assistantId: projectTaskValues.assistantId as string,
+      taskId: projectTaskValues.taskId as string,
+      threadId: projectTaskValues.threadId as string,
+      inputMessageId: projectTaskValues.inputMessageId as string,
     };
+    if (projectTaskHasSource && typeof projectTaskValues.source === "string") {
+      parsedProjectTask.source = projectTaskValues.source;
+    }
+    return { projectTask: parsedProjectTask };
   }
   const projectRoomValue = contextValues?.projectRoom;
   const requiredKeys = [
     "tenantId", "workspaceId", "projectId", "roomId", "sourceRoomMessageId", "membershipId",
     "assistantId", "inputMessageId", "role", "title",
   ] as const;
-  const projectRoomValues = snapshotExactRecord(projectRoomValue, requiredKeys, ["responsibility"]);
+  const projectRoomValues = snapshotExactRecord(projectRoomValue, requiredKeys, ["responsibility", "source"]);
   const hasResponsibility = projectRoomValues !== undefined
     && Object.prototype.hasOwnProperty.call(projectRoomValues, "responsibility");
+  const hasSource = projectRoomValues !== undefined
+    && Object.prototype.hasOwnProperty.call(projectRoomValues, "source");
   if (!projectRoomValues
     || requiredKeys.some((key) => typeof projectRoomValues[key] !== "string" || projectRoomValues[key].length === 0)
     || (hasResponsibility && projectRoomValues.responsibility !== undefined
       && (typeof projectRoomValues.responsibility !== "string" || projectRoomValues.responsibility.length === 0))
+    || (hasSource && projectRoomValues.source !== undefined
+      && (typeof projectRoomValues.source !== "string" || projectRoomValues.source.length === 0))
     || (projectRoomValues.role !== "coordinator" && projectRoomValues.role !== "specialist")) {
     throw new Error("Invalid trusted agent run context");
   }
@@ -103,6 +125,9 @@ export function parseTrustedRunContext(value: unknown): TrustedRunContext {
   if (hasResponsibility && typeof projectRoomValues.responsibility === "string") {
     parsedProjectRoom.responsibility = projectRoomValues.responsibility;
   }
+  if (hasSource && typeof projectRoomValues.source === "string") {
+    parsedProjectRoom.source = projectRoomValues.source;
+  }
   return { projectRoom: parsedProjectRoom };
 }
 

package/src/__tests__/McpUiProtocol.test.ts

@@ -0,0 +1,43 @@
+import { parseMcpUiRef, isMcpUiRef } from "../McpUiProtocol";
+
+describe("parseMcpUiRef", () => {
+  it("parses a valid mcp ref", () => {
+    const ref = { kind: "mcp", serverKey: "weather", resourceUri: "ui://weather/dashboard", displayMode: "inline" };
+    expect(parseMcpUiRef(ref)).toEqual(ref);
+  });
+
+  it("defaults displayMode to inline", () => {
+    const ref = parseMcpUiRef({ kind: "mcp", serverKey: "a", resourceUri: "ui://a/x" });
+    expect(ref?.displayMode).toBe("inline");
+  });
+
+  it("preserves structuredContent on an mcp ref", () => {
+    const ref = parseMcpUiRef({
+      kind: "mcp",
+      serverKey: "weather",
+      resourceUri: "ui://weather/dashboard",
+      structuredContent: { a: 1 },
+    });
+    expect(ref).toEqual({
+      kind: "mcp",
+      serverKey: "weather",
+      resourceUri: "ui://weather/dashboard",
+      displayMode: "inline",
+      structuredContent: { a: 1 },
+    });
+  });
+
+  it("omits structuredContent when absent", () => {
+    const ref = parseMcpUiRef({ kind: "mcp", serverKey: "a", resourceUri: "ui://a/x" });
+    expect(ref && "structuredContent" in ref).toBe(false);
+  });
+
+  it("rejects unknown kind", () => {
+    expect(parseMcpUiRef({ kind: "nope" })).toBeNull();
+  });
+
+  it("isMcpUiRef narrows", () => {
+    expect(isMcpUiRef({ kind: "plugin", pluginType: "p", resource: "ui/x.html", displayMode: "inline" })).toBe(true);
+    expect(isMcpUiRef("x")).toBe(false);
+  });
+});

package/src/__tests__/MenuProtocol.test.ts

@@ -0,0 +1,28 @@
+import type { McpAppMenuConfig, MenuContentConfig, MenuContentType } from "../MenuProtocol";
+
+describe("MenuProtocol mcpApp content type", () => {
+  it("round-trips both mcp and plugin McpAppMenuConfig variants", () => {
+    const mcp: McpAppMenuConfig = {
+      kind: "mcp",
+      serverKey: "srv",
+      resourceUri: "ui://srv/a.html",
+      displayMode: "inline",
+      title: "App",
+      toolInput: { area: "eu" },
+    };
+    const plugin: McpAppMenuConfig = {
+      kind: "plugin",
+      pluginType: "my-plugin",
+      resource: "ui/report.html",
+      title: "Report",
+    };
+    for (const cfg of [mcp, plugin] as MenuContentConfig[]) {
+      expect(JSON.parse(JSON.stringify(cfg))).toEqual(cfg);
+    }
+  });
+
+  it("includes file and mcpApp in MenuContentType", () => {
+    const types: MenuContentType[] = ["agent", "html", "custom", "file", "mcpApp"];
+    expect(new Set(types).size).toBe(5);
+  });
+});

package/src/__tests__/ProjectRoomStores.test.ts

@@ -268,6 +268,10 @@ class FakeProjectRoomMessageStore implements ProjectRoomMessageStore {
   async countAfter(input: Parameters<ProjectRoomMessageStore["countAfter"]>[0]): Promise<number> {
     return input.tenantId === "tenant-1" && input.roomId === "room-1" ? 1 : 0;
   }
+
+  async deleteChatOlderThan(input: Parameters<ProjectRoomMessageStore["deleteChatOlderThan"]>[0]): Promise<number> {
+    return input.limit > 0 ? 1 : 0;
+  }
 }
 
 describe("ProjectRoomStore", () => {
@@ -363,5 +367,7 @@ describe("ProjectRoomMessageStore", () => {
     expect(await store.list({ tenantId: "tenant-1", roomId: "room-1", before: cursor, limit: 10 })).toEqual([message]);
     expect(await store.findById("tenant-1", "message-1")).toEqual(message);
     expect(await store.findById("tenant-1", "missing-message")).toBeNull();
+    expect(await store.deleteChatOlderThan({ before: message.createdAt, limit: 10 })).toBe(1);
+    expect(await store.deleteChatOlderThan({ before: message.createdAt, limit: 0 })).toBe(0);
   });
 });

package/src/__tests__/TaskMetadataFilter.test.ts

@@ -0,0 +1,27 @@
+import { normalizeTaskMetadataScalar } from "../TaskStoreProtocol";
+
+describe("normalizeTaskMetadataScalar", () => {
+  it("returns strings unchanged", () => {
+    expect(normalizeTaskMetadataScalar("p1")).toBe("p1");
+    expect(normalizeTaskMetadataScalar("1")).toBe("1");
+  });
+
+  it("stringifies finite numbers and rejects non-finite ones", () => {
+    expect(normalizeTaskMetadataScalar(1)).toBe("1");
+    expect(normalizeTaskMetadataScalar(1.5)).toBe("1.5");
+    expect(normalizeTaskMetadataScalar(Number.NaN)).toBeUndefined();
+    expect(normalizeTaskMetadataScalar(Infinity)).toBeUndefined();
+  });
+
+  it("stringifies booleans as JSON text", () => {
+    expect(normalizeTaskMetadataScalar(true)).toBe("true");
+    expect(normalizeTaskMetadataScalar(false)).toBe("false");
+  });
+
+  it("rejects non-scalar values", () => {
+    expect(normalizeTaskMetadataScalar(null)).toBeUndefined();
+    expect(normalizeTaskMetadataScalar(undefined)).toBeUndefined();
+    expect(normalizeTaskMetadataScalar({ a: 1 })).toBeUndefined();
+    expect(normalizeTaskMetadataScalar([1])).toBeUndefined();
+  });
+});

package/src/__tests__/ToolCallUi.test.ts

@@ -0,0 +1,46 @@
+import type { MessageChunk, ToolCall } from "../MessageProtocol";
+
+describe("ToolCall.ui", () => {
+  it("round-trips structuredContent, meta, and content blocks through JSON", () => {
+    const toolCall: ToolCall = {
+      id: "t1",
+      name: "get_widget",
+      args: {},
+      type: "tool_call",
+      response: "ok",
+      ui: {
+        structuredContent: { cpu: 42 },
+        meta: { source: "mock" },
+        contentBlocks: [
+          { type: "image", source_type: "base64", data: "AAAA", mime_type: "image/png" },
+        ],
+      },
+    };
+
+    const parsed = JSON.parse(JSON.stringify(toolCall)) as ToolCall;
+
+    expect(parsed.ui?.structuredContent).toEqual({ cpu: 42 });
+    expect(parsed.ui?.meta).toEqual({ source: "mock" });
+    expect(parsed.ui?.contentBlocks).toHaveLength(1);
+  });
+
+  it("has no ui property after a JSON round-trip of a plain tool call", () => {
+    const parsed = JSON.parse(
+      JSON.stringify({ id: "t2", name: "echo", args: {}, type: "tool_call" })
+    ) as ToolCall;
+    expect("ui" in parsed).toBe(false);
+  });
+
+  it("lets a tool chunk carry the raw LangChain artifact", () => {
+    const chunk: MessageChunk = {
+      type: "tool",
+      data: {
+        id: "t3",
+        tool_call_id: "c3",
+        content: "done",
+        artifact: [{ type: "mcp_structured_content", data: { a: 1 } }],
+      },
+    };
+    expect(Array.isArray(chunk.data.artifact)).toBe(true);
+  });
+});