@copilotz/chat-adapter 0.7.1 → 0.7.3

package/dist/index.js

@@ -424,10 +424,17 @@ async function runCopilotzStream(options) {
   let buffer = "";
   let aggregatedText = "";
   let aggregatedReasoning = "";
+  let lastCompletedText = "";
   let lastTokenWasReasoning = false;
   let hadNonReasoningContent = false;
   const collectedMessages = [];
   let collectedMedia = null;
+  const resetTokenAggregation = () => {
+    aggregatedText = "";
+    aggregatedReasoning = "";
+    lastTokenWasReasoning = false;
+    hadNonReasoningContent = false;
+  };
   const processEvent = (eventChunk) => {
     if (!eventChunk.trim()) return;
     const lines = eventChunk.split("\n");
@@ -475,6 +482,12 @@ async function runCopilotzStream(options) {
         if (chunk || isComplete) {
           const tokenText = isReasoning ? aggregatedReasoning : aggregatedText;
           onToken?.(tokenText, isComplete, payload2, { isReasoning });
+          if (isComplete) {
+            if (!isReasoning && tokenText) {
+              lastCompletedText = tokenText;
+            }
+            resetTokenAggregation();
+          }
         }
         break;
       }
@@ -493,8 +506,11 @@ async function runCopilotzStream(options) {
       }
       case "TOOL_RESULT":
       case "LLM_RESULT": {
-        hadNonReasoningContent = true;
-        lastTokenWasReasoning = false;
+        const resultAnswer = typeof payload2?.payload?.answer === "string" ? payload2.payload.answer : typeof payload2?.answer === "string" ? payload2.answer : void 0;
+        if (resultAnswer) {
+          lastCompletedText = resultAnswer;
+        }
+        resetTokenAggregation();
         onMessageEvent?.(payload2);
         break;
       }
@@ -540,7 +556,7 @@ async function runCopilotzStream(options) {
     processEvent(buffer);
   }
   return {
-    text: aggregatedText,
+    text: lastCompletedText || aggregatedText,
     messages: collectedMessages,
     media: collectedMedia
   };
@@ -672,64 +688,6 @@ async function deleteThread(threadId, getRequestHeaders) {
   return true;
 }
 
-// src/assetsService.ts
-var rawBaseValue2 = import.meta.env?.VITE_API_URL;
-var rawBase2 = typeof rawBaseValue2 === "string" && rawBaseValue2.length > 0 ? rawBaseValue2 : "/api";
-var normalizedBase2 = rawBase2.replace(/\/$/, "");
-var API_BASE2 = normalizedBase2.startsWith("http") || normalizedBase2.startsWith("/") ? normalizedBase2 : `/${normalizedBase2}`;
-var apiUrl2 = (path) => `${API_BASE2}${path}`;
-var extractAssetId = (refOrId) => refOrId.startsWith("asset://") ? refOrId.slice("asset://".length) : refOrId;
-async function getAssetDataUrl(refOrId) {
-  const id = extractAssetId(refOrId);
-  const res = await fetch(apiUrl2(`/v1/assets/${encodeURIComponent(id)}?format=dataUrl`), {
-    method: "GET",
-    headers: { Accept: "application/json" }
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => res.statusText);
-    throw new Error(text || `Failed to fetch asset ${refOrId}`);
-  }
-  const body = await res.json();
-  const data = body?.data ?? body;
-  if (!data?.dataUrl) {
-    throw new Error(data?.error || `Asset ${refOrId} has no dataUrl`);
-  }
-  return { dataUrl: data.dataUrl, mime: data.mime, assetId: data.assetId };
-}
-async function resolveAssetsInMessages(messages) {
-  const inFlightByRef = /* @__PURE__ */ new Map();
-  const resolveAssetRef = (assetRef) => {
-    if (!inFlightByRef.has(assetRef)) {
-      inFlightByRef.set(assetRef, getAssetDataUrl(assetRef));
-    }
-    return inFlightByRef.get(assetRef);
-  };
-  return Promise.all(messages.map(async (msg) => {
-    const meta = msg.metadata ?? void 0;
-    const attachments = Array.isArray(meta?.attachments) ? meta.attachments : void 0;
-    if (!attachments || attachments.length === 0) {
-      return msg;
-    }
-    const newAttachments = await Promise.all(attachments.map(async (att) => {
-      const assetRef = typeof att?.assetRef === "string" ? att.assetRef : void 0;
-      if (!assetRef) return att;
-      try {
-        const { dataUrl, mime } = await resolveAssetRef(assetRef);
-        const kind = typeof att.kind === "string" ? att.kind : "image";
-        return {
-          kind,
-          dataUrl,
-          mimeType: typeof att.mimeType === "string" ? att.mimeType : mime ?? void 0
-        };
-      } catch {
-        return att;
-      }
-    }));
-    const newMeta = { ...meta ?? {}, attachments: newAttachments };
-    return { ...msg, metadata: newMeta };
-  }));
-}
-
 // src/useUrlState.ts
 import { useState, useEffect, useCallback, useRef } from "react";
 var DEFAULT_PARAMS = {
@@ -835,194 +793,397 @@ function useUrlState(config = {}) {
 }
 
 // src/activity.ts
-var isToolCallActive = (toolCall) => toolCall.status === "pending" || toolCall.status === "running";
+var thinkingId = "thinking";
+var answeringId = "answering";
+var getItems = (message) => Array.isArray(message.activity?.items) ? message.activity.items : [];
+var setItems = (message, items) => ({
+  ...message,
+  activity: items.length > 0 ? { items } : void 0
+});
+var toolStatusToActivityStatus = (status) => {
+  if (status === "failed") return "failed";
+  if (status === "completed") return "complete";
+  return "active";
+};
+var upsertItem = (message, item) => {
+  const items = getItems(message);
+  const index = items.findIndex((current) => current.id === item.id);
+  if (index === -1) return setItems(message, [...items, item]);
+  const next = [...items];
+  next[index] = {
+    ...next[index],
+    ...item,
+    details: {
+      ...next[index].details ?? {},
+      ...item.details ?? {}
+    }
+  };
+  return setItems(message, next);
+};
+var completeItems = (message, shouldComplete) => setItems(message, getItems(message).map((item) => item.status === "active" && shouldComplete(item) ? { ...item, status: "complete", completedAt: Date.now() } : item));
 var hasVisibleAssistantOutput = (message) => {
   if (message.role !== "assistant") return false;
   if (typeof message.content === "string" && message.content.trim().length > 0) return true;
   if (Array.isArray(message.attachments) && message.attachments.length > 0) return true;
-  if (Array.isArray(message._activityToolCalls) && message._activityToolCalls.length > 0) return true;
-  return false;
-};
-var buildAssistantActivity = (message) => {
-  const toolCalls = Array.isArray(message._activityToolCalls) ? message._activityToolCalls : [];
-  const hasReasoning = typeof message._activityReasoning === "string" && message._activityReasoning.length > 0;
-  const hasToolCalls = toolCalls.length > 0;
-  const runningTools = toolCalls.filter(isToolCallActive);
-  const hasRunningTools = runningTools.length > 0;
-  const isStreaming = message.isStreaming === true;
-  const isReasoningStreaming = message._activityReasoningStreaming === true;
-  const hasContent = typeof message.content === "string" && message.content.trim().length > 0;
-  if (!hasReasoning && !hasToolCalls && !isStreaming && !isReasoningStreaming) {
-    return void 0;
-  }
-  const isActive = isStreaming || isReasoningStreaming || hasRunningTools;
-  const summary = hasRunningTools ? {
-    kind: "using_tools",
-    ...runningTools.length === 1 ? { toolName: runningTools[0].name } : {},
-    ...runningTools.length > 1 ? { toolCount: runningTools.length } : {}
-  } : isStreaming && hasToolCalls && !hasContent ? {
-    kind: "using_tools",
-    ...toolCalls.length === 1 ? { toolName: toolCalls[0].name } : {},
-    ...toolCalls.length > 1 ? { toolCount: toolCalls.length } : {}
-  } : isReasoningStreaming || !hasContent && hasReasoning ? { kind: "thinking" } : isStreaming && hasContent ? { kind: "preparing_answer" } : isStreaming ? { kind: "working" } : hasToolCalls ? {
-    kind: "using_tools",
-    ...toolCalls.length === 1 ? { toolName: toolCalls[0].name } : {},
-    ...toolCalls.length > 1 ? { toolCount: toolCalls.length } : {}
-  } : { kind: "thinking" };
-  return {
-    isActive,
-    ...isActive ? {} : { isComplete: true },
-    summary,
-    ...hasReasoning ? { reasoning: message._activityReasoning } : {},
-    ...hasToolCalls ? { toolCalls } : {}
-  };
-};
-var syncAssistantActivity = (message) => {
-  if (message.role !== "assistant") {
-    const { _activityReasoning, _activityReasoningStreaming, _activityToolCalls, ...rest } = message;
-    return rest;
-  }
-  return {
-    ...message,
-    activity: buildAssistantActivity(message)
-  };
+  return getItems(message).length > 0;
 };
 var toPublicChatMessage = (message) => {
-  const { _activityReasoning, _activityReasoningStreaming, _activityToolCalls, ...rest } = syncAssistantActivity(message);
+  if (message.role === "assistant") return message;
+  const { activity, ...rest } = message;
   return rest;
 };
 var updateAssistantMessageToken = (message, params) => {
   if (message.role !== "assistant") return message;
-  const next = params.isReasoning ? {
-    ...message,
-    ...params.agentIdentity,
-    _activityReasoning: params.partial,
-    _activityReasoningStreaming: true,
-    isStreaming: true,
-    isComplete: false
-  } : {
+  if (params.isReasoning) {
+    return upsertItem({
+      ...message,
+      isStreaming: true,
+      isComplete: false
+    }, {
+      id: thinkingId,
+      kind: "thinking",
+      status: "active",
+      startedAt: getItems(message).find((item) => item.id === thinkingId)?.startedAt ?? Date.now(),
+      details: { reasoning: params.partial }
+    });
+  }
+  return upsertItem(completeItems({
     ...message,
-    ...params.agentIdentity,
     content: params.partial,
-    _activityReasoningStreaming: false,
     isStreaming: true,
     isComplete: false
-  };
-  return syncAssistantActivity(next);
+  }, (item) => item.kind === "thinking" || item.kind === "tool"), {
+    id: answeringId,
+    kind: "answering",
+    status: "active",
+    startedAt: getItems(message).find((item) => item.id === answeringId)?.startedAt ?? Date.now()
+  });
 };
 var appendAssistantToolCall = (message, toolCall) => {
   if (message.role !== "assistant") return message;
-  return syncAssistantActivity({
+  const status = toolStatusToActivityStatus(toolCall.status);
+  return upsertItem({
     ...message,
-    _activityToolCalls: [
-      ...Array.isArray(message._activityToolCalls) ? message._activityToolCalls : [],
-      toolCall
-    ],
     isStreaming: true,
     isComplete: false
+  }, {
+    id: toolCall.id,
+    kind: "tool",
+    status,
+    toolName: toolCall.name,
+    startedAt: toolCall.startTime ?? Date.now(),
+    ...status !== "active" ? { completedAt: toolCall.endTime ?? Date.now() } : {},
+    details: {
+      toolCall,
+      ...toolCall.result !== void 0 ? { result: toolCall.result } : {}
+    }
   });
 };
 var applyAssistantToolResult = (message, update) => {
   if (message.role !== "assistant") return message;
-  const toolCalls = Array.isArray(message._activityToolCalls) ? message._activityToolCalls : [];
-  const nextToolCalls = toolCalls.map((toolCall) => {
-    const matchesById = update.id && toolCall.id === update.id;
-    const matchesByName = !update.id && toolCall.name === update.name;
-    if (!matchesById && !matchesByName) return toolCall;
-    return {
-      ...toolCall,
-      ...update
-    };
-  });
-  return syncAssistantActivity({
-    ...message,
-    _activityToolCalls: nextToolCalls
-  });
+  const items = getItems(message);
+  const index = items.findIndex((item2) => item2.kind === "tool" && (update.id && item2.id === update.id || !update.id && item2.toolName === update.name));
+  if (index === -1) return message;
+  const item = items[index];
+  const toolCall = item.details?.toolCall;
+  const nextToolCall = toolCall ? { ...toolCall, ...update } : {
+    id: update.id ?? item.id,
+    name: update.name,
+    arguments: {},
+    status: update.status,
+    ...update.result !== void 0 ? { result: update.result } : {},
+    ...update.endTime !== void 0 ? { endTime: update.endTime } : {}
+  };
+  const status = toolStatusToActivityStatus(update.status);
+  const next = [...items];
+  next[index] = {
+    ...item,
+    status,
+    toolName: update.name,
+    ...status !== "active" ? { completedAt: update.endTime ?? Date.now() } : {},
+    details: {
+      ...item.details ?? {},
+      toolCall: nextToolCall,
+      ...update.result !== void 0 ? { result: update.result } : {}
+    }
+  };
+  return setItems(message, next);
 };
 var finalizeAssistantMessage = (message, finalAnswer) => {
   if (message.role !== "assistant") return message;
-  return syncAssistantActivity({
+  const completed = completeItems({
     ...message,
     ...typeof finalAnswer === "string" && finalAnswer.length > 0 ? { content: finalAnswer } : {},
     isStreaming: false,
-    isComplete: true,
-    _activityReasoningStreaming: false
-  });
+    isComplete: true
+  }, (item) => item.kind === "thinking" || item.kind === "answering");
+  return setItems(completed, getItems(completed).filter((item) => item.kind !== "answering"));
 };
 var closeAssistantMessage = (message) => {
   if (message.role !== "assistant") return message;
-  return syncAssistantActivity({
+  return completeItems({
     ...message,
     isStreaming: false,
-    isComplete: true,
-    _activityReasoningStreaming: false
-  });
+    isComplete: true
+  }, () => true);
 };
 
-// src/useCopilotzChat.ts
-var nowTs = () => Date.now();
-var generateId = () => globalThis.crypto?.randomUUID?.() ?? `id-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-var isAbortError = (error) => error instanceof DOMException && error.name === "AbortError" || typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
-var getEventPayload = (event) => event?.payload ?? event;
-var getEventSenderType = (payload) => payload?.senderType || payload?.sender?.type;
-var isInternalMessageMetadata = (metadata) => metadata?.visibility === "internal";
-var normalizeAgentIdentity = (agent) => {
-  const senderAgentId = typeof agent?.id === "string" && agent.id.length > 0 ? agent.id : void 0;
-  const senderName = typeof agent?.name === "string" && agent.name.length > 0 ? agent.name : senderAgentId;
-  return {
-    ...senderAgentId ? { senderAgentId } : {},
-    ...senderName ? { senderName } : {}
-  };
+// src/contract.ts
+var ContractViolation = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ContractViolation";
+  }
 };
-var messageAgentKey = (message) => {
-  if (message.role !== "assistant") return null;
-  return message.senderAgentId ?? message.senderName ?? null;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var expectRecord = (value, path) => {
+  if (!isRecord(value)) throw new ContractViolation(`${path} must be an object`);
+  return value;
+};
+var expectString = (value, path) => {
+  if (typeof value !== "string" || value.trim().length === 0) throw new ContractViolation(`${path} must be a non-empty string`);
+  return value;
+};
+var expectOptionalString = (value, path) => {
+  if (value === void 0 || value === null) return void 0;
+  return expectString(value, path);
+};
+var expectStringValue = (value, path) => {
+  if (typeof value !== "string") throw new ContractViolation(`${path} must be a string`);
+  return value;
+};
+
+// src/senders.ts
+var clean = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+var expectSenderType = (value, path) => {
+  if (value === "user" || value === "agent" || value === "tool" || value === "system") return value;
+  throw new ContractViolation(`${path} must be user, agent, tool, or system`);
+};
+var defined = (value) => Object.fromEntries(
+  Object.entries(value).filter(([, entry]) => entry !== void 0)
+);
+var findAgent = (agents, ...candidates) => {
+  const values = candidates.filter(Boolean).map((value) => value.toLowerCase());
+  if (!agents || values.length === 0) return void 0;
+  return agents.find(
+    (agent) => values.includes(agent.id.toLowerCase()) || values.includes(agent.name.toLowerCase())
+  );
 };
-var resolveLiveAgentIdentity = (event) => {
-  const payload = getEventPayload(event);
-  const agent = payload?.agent && typeof payload.agent === "object" ? payload.agent : event?.agent && typeof event.agent === "object" ? event.agent : null;
+var fromAgent = (agent, overrides = {}) => defined({
+  type: overrides.type ?? "agent",
+  id: agent.id,
+  name: agent.name,
+  agentId: agent.id,
+  avatarUrl: agent.avatarUrl,
+  color: agent.color,
+  ...overrides
+});
+var resolveUserSender = (user) => defined({
+  type: "user",
+  id: user.id,
+  externalId: user.id,
+  name: clean(user.name) ?? user.id,
+  avatarUrl: clean(user.avatarUrl)
+});
+var resolveAssistantFallbackSender = (options = {}) => ({
+  type: "agent",
+  id: "assistant",
+  name: clean(options.assistantName) ?? "Assistant",
+  agentId: "assistant"
+});
+var resolveAgentSender = (identity, options = {}, overrides = {}) => {
+  const id = expectString(identity.id, "agent.id");
+  const name = expectString(identity.name, "agent.name");
+  const agent = findAgent(options.agents, id, name);
   if (agent) {
-    return normalizeAgentIdentity(agent);
+    return fromAgent(agent, defined({
+      ...overrides,
+      externalId: id && id !== agent.id ? id : void 0
+    }));
   }
-  const sender = payload?.sender && typeof payload.sender === "object" ? payload.sender : event?.sender && typeof event.sender === "object" ? event.sender : null;
-  return normalizeAgentIdentity({
-    id: typeof payload?.senderId === "string" ? payload.senderId : typeof sender?.id === "string" ? sender.id : null,
-    name: typeof payload?.senderName === "string" ? payload.senderName : typeof sender?.name === "string" ? sender.name : null
+  return defined({
+    type: overrides.type ?? "agent",
+    id,
+    name,
+    agentId: id,
+    ...overrides
   });
 };
-var canAttachToStreamingAssistant = (message, incomingAgentKey) => {
-  if (!message || message.role !== "assistant" || !message.isStreaming) {
-    return false;
+var resolveHydratedMessageSender = (message, options = {}) => {
+  const metadata = message.metadata ? expectRecord(message.metadata, "message.metadata") : {};
+  const type = expectSenderType(message.senderType, "message.senderType");
+  const storedId = expectOptionalString(message.senderId, "message.senderId");
+  const participantId = expectOptionalString(metadata.senderParticipantId, "message.metadata.senderParticipantId") ?? expectOptionalString(message.senderUserId, "message.senderUserId");
+  const externalId = expectString(metadata.senderExternalId, "message.metadata.senderExternalId");
+  const displayName = expectString(metadata.senderDisplayName, "message.metadata.senderDisplayName");
+  if (type === "agent" || type === "tool") {
+    const agent = findAgent(options.agents, externalId, displayName, storedId);
+    if (agent) {
+      return fromAgent(agent, defined({
+        type,
+        participantId: participantId ?? storedId,
+        externalId: externalId && externalId !== agent.id ? externalId : void 0
+      }));
+    }
+    return defined({
+      type,
+      id: externalId,
+      name: displayName,
+      agentId: externalId,
+      participantId: participantId ?? storedId,
+      externalId
+    });
   }
-  const currentAgentKey = messageAgentKey(message);
-  return !incomingAgentKey || !currentAgentKey || currentAgentKey === incomingAgentKey;
+  if (type === "user") {
+    return defined({
+      type: "user",
+      id: externalId,
+      externalId,
+      name: displayName,
+      avatarUrl: clean(options.user?.avatarUrl),
+      participantId: participantId ?? storedId
+    });
+  }
+  return defined({
+    type: "system",
+    id: externalId,
+    name: displayName,
+    participantId: participantId ?? storedId,
+    externalId
+  });
 };
-var THREAD_MESSAGES_PAGE_SIZE = 50;
-var createEmptyMessagePageInfo = () => ({
-  hasMoreBefore: false,
-  oldestMessageId: null,
-  newestMessageId: null
-});
-var normalizeToolStatus = (status) => {
+var resolveLiveEventSender = (event, options = {}) => {
+  const raw = expectRecord(event, "stream event");
+  const payload = raw.payload === void 0 ? raw : expectRecord(raw.payload, "stream event.payload");
+  const agent = payload.agent ?? raw.agent;
+  if (isRecord(agent)) {
+    return resolveAgentSender({
+      id: expectString(agent.id, "stream event.payload.agent.id"),
+      name: expectString(agent.name, "stream event.payload.agent.name")
+    }, options);
+  }
+  const sender = payload.sender ?? raw.sender;
+  if (!isRecord(sender)) {
+    throw new ContractViolation("stream event sender contract requires payload.agent or payload.sender");
+  }
+  const type = expectSenderType(sender.type ?? payload.senderType, "stream event.payload.sender.type");
+  if (type !== "user") {
+    return resolveAgentSender({
+      id: expectString(sender.id ?? sender.externalId, "stream event.payload.sender.id"),
+      name: expectString(sender.name, "stream event.payload.sender.name")
+    }, options, { type });
+  }
+  if (!options.user) {
+    throw new ContractViolation("user stream sender requires current user context");
+  }
+  return resolveUserSender(options.user);
+};
+
+// src/assetsService.ts
+var ContractViolation2 = class extends Error {
+  name = "ContractViolation";
+};
+var expectRecord2 = (value, path) => {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) return value;
+  throw new ContractViolation2(`${path} must be an object`);
+};
+var expectString2 = (value, path) => {
+  if (typeof value === "string" && value.trim().length > 0) return value;
+  throw new ContractViolation2(`${path} must be a non-empty string`);
+};
+var rawBaseValue2 = import.meta.env?.VITE_API_URL;
+var rawBase2 = typeof rawBaseValue2 === "string" && rawBaseValue2.length > 0 ? rawBaseValue2 : "/api";
+var normalizedBase2 = rawBase2.replace(/\/$/, "");
+var API_BASE2 = normalizedBase2.startsWith("http") || normalizedBase2.startsWith("/") ? normalizedBase2 : `/${normalizedBase2}`;
+var apiUrl2 = (path) => `${API_BASE2}${path}`;
+var extractAssetId = (refOrId) => refOrId.startsWith("asset://") ? refOrId.slice("asset://".length) : refOrId;
+async function getAssetDataUrl(refOrId) {
+  const id = extractAssetId(refOrId);
+  const res = await fetch(apiUrl2(`/v1/assets/${encodeURIComponent(id)}?format=dataUrl`), {
+    method: "GET",
+    headers: { Accept: "application/json" }
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(text || `Failed to fetch asset ${refOrId}`);
+  }
+  const body = await res.json();
+  const envelope = expectRecord2(body, "asset response");
+  const data = expectRecord2(envelope.data, "asset response.data");
+  if (typeof data.error === "string" && data.error.length > 0) {
+    throw new Error(data.error);
+  }
+  if (typeof data.dataUrl !== "string" || data.dataUrl.length === 0) {
+    throw new ContractViolation2(`asset response.data.dataUrl is required for ${refOrId}`);
+  }
+  return {
+    dataUrl: data.dataUrl,
+    mime: typeof data.mime === "string" ? data.mime : void 0,
+    assetId: expectString2(data.assetId, "asset response.data.assetId")
+  };
+}
+async function resolveAssetsInMessages(messages) {
+  const inFlightByRef = /* @__PURE__ */ new Map();
+  const resolveAssetRef = (assetRef) => {
+    if (!inFlightByRef.has(assetRef)) {
+      inFlightByRef.set(assetRef, getAssetDataUrl(assetRef));
+    }
+    return inFlightByRef.get(assetRef);
+  };
+  return Promise.all(messages.map(async (msg) => {
+    const meta = msg.metadata === null || msg.metadata === void 0 ? void 0 : expectRecord2(msg.metadata, "message.metadata");
+    const attachments = meta?.attachments === void 0 ? void 0 : Array.isArray(meta.attachments) ? meta.attachments.map(
+      (att, index) => expectRecord2(att, `message.metadata.attachments[${index}]`)
+    ) : (() => {
+      throw new ContractViolation2("message.metadata.attachments must be an array");
+    })();
+    if (!attachments || attachments.length === 0) {
+      return msg;
+    }
+    const newAttachments = await Promise.all(attachments.map(async (att, index) => {
+      const assetRef = typeof att.assetRef === "string" ? att.assetRef : void 0;
+      if (!assetRef) return att;
+      const { dataUrl, mime } = await resolveAssetRef(assetRef);
+      const kind = expectString2(att.kind, `message.metadata.attachments[${index}].kind`);
+      const mimeType = typeof att.mimeType === "string" ? att.mimeType : expectString2(mime, `asset ${assetRef}.mime`);
+      return {
+        ...att,
+        kind,
+        dataUrl,
+        mimeType
+      };
+    }));
+    const newMeta = { ...meta, attachments: newAttachments };
+    return { ...msg, metadata: newMeta };
+  }));
+}
+
+// src/toolActivity.ts
+var fail = (message) => {
+  throw new ContractViolation(message);
+};
+var expectToolStatus = (status, path) => {
   if (status === "pending") return "pending";
   if (status === "running" || status === "processing") return "running";
   if (status === "failed") return "failed";
-  return "completed";
+  if (status === "completed") return "completed";
+  return fail(`${path} must be pending, running, processing, completed, or failed`);
 };
-var parseToolArguments = (value) => {
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    return value;
-  }
+var expectToolArguments = (value, path) => {
+  if (isRecord(value)) return value;
   if (typeof value === "string") {
     try {
       const parsed = JSON.parse(value);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-        return parsed;
-      }
+      return expectRecord(parsed, path);
     } catch {
+      return fail(`${path} must be an object or JSON object string`);
     }
   }
-  return {};
+  return fail(`${path} must be an object or JSON object string`);
+};
+var expectToolName = (tool, path) => {
+  const name = typeof tool.name === "string" && tool.name.trim().length > 0 ? tool.name : tool.id;
+  return expectString(name, path);
 };
 var matchesToolResultUpdate = (target, update) => {
   if (update.id && target.id) {
@@ -1030,92 +1191,84 @@ var matchesToolResultUpdate = (target, update) => {
   }
   return Boolean(update.name && target.name && update.name === target.name);
 };
-var findMatchingToolCallIndex = (toolCalls, update) => toolCalls.findIndex((toolCall) => matchesToolResultUpdate(
-  { id: toolCall.id, name: toolCall.name },
+var findMatchingToolItem = (toolItems, update) => toolItems.find((item) => matchesToolResultUpdate(
+  { id: item.id, name: item.toolName },
   update
-) && (toolCall.status === "pending" || toolCall.status === "running" || typeof toolCall.result === "undefined"));
+) && (item.status === "active" || item.details?.result === void 0));
 var applyToolResultUpdateToMessages = (messages, update, assistantPatch) => {
   const nextMessages = [...messages];
   for (let i = nextMessages.length - 1; i >= 0; i--) {
     const message = nextMessages[i];
-    if (message.role !== "assistant" || !Array.isArray(message._activityToolCalls) || message._activityToolCalls.length === 0) {
+    const toolItems = message.activity?.items.filter((item) => item.kind === "tool") ?? [];
+    if (message.role !== "assistant" || toolItems.length === 0) {
       continue;
     }
-    const toolCallIndex = findMatchingToolCallIndex(message._activityToolCalls, update);
-    if (toolCallIndex === -1) continue;
-    nextMessages[i] = syncAssistantActivity({
+    const toolItem = findMatchingToolItem(toolItems, update);
+    if (!toolItem) continue;
+    nextMessages[i] = {
       ...applyAssistantToolResult(message, {
         ...update.id ? { id: update.id } : {},
-        name: update.name ?? message._activityToolCalls[toolCallIndex].name,
+        name: update.name ?? toolItem.toolName ?? toolItem.id,
         status: update.status,
         ...update.result !== void 0 ? { result: update.result } : {},
         endTime: update.endTime
       }),
       ...assistantPatch ?? {}
-    });
+    };
     return { messages: nextMessages, matched: true };
   }
   return { messages, matched: false };
 };
 var extractLiveToolCall = (payload) => {
-  const toolCall = payload?.toolCall;
-  if (!toolCall) return null;
-  const tool = toolCall.tool;
-  const name = typeof tool?.name === "string" ? tool.name : typeof tool?.id === "string" ? tool.id : "tool";
-  const result = toolCall.output !== void 0 ? toolCall.output : void 0;
+  const payloadRecord = expectRecord(payload, "TOOL_CALL payload");
+  const toolCall = expectRecord(payloadRecord.toolCall, "TOOL_CALL payload.toolCall");
+  const tool = expectRecord(toolCall.tool, "TOOL_CALL payload.toolCall.tool");
   return {
-    ...typeof toolCall.id === "string" ? { id: toolCall.id } : {},
-    name,
-    arguments: parseToolArguments(toolCall.args),
-    status: normalizeToolStatus(toolCall.status ?? payload?.status ?? "running"),
-    ...result !== void 0 ? { result } : {}
+    id: expectString(toolCall.id, "TOOL_CALL payload.toolCall.id"),
+    name: expectToolName(tool, "TOOL_CALL payload.toolCall.tool.id"),
+    arguments: expectToolArguments(toolCall.args, "TOOL_CALL payload.toolCall.args"),
+    status: toolCall.status === void 0 ? "running" : expectToolStatus(toolCall.status, "TOOL_CALL payload.toolCall.status"),
+    ...toolCall.output !== void 0 ? { result: toolCall.output } : {}
   };
 };
-var extractLiveToolResultUpdate = (payload) => {
-  const tool = payload?.tool;
-  const result = payload?.projectedOutput !== void 0 ? payload.projectedOutput : payload?.output !== void 0 ? payload.output : payload?.content;
+var extractLiveToolResultUpdate = (payload, now = () => Date.now()) => {
+  const payloadRecord = expectRecord(payload, "TOOL_RESULT payload");
+  const tool = expectRecord(payloadRecord.tool, "TOOL_RESULT payload.tool");
+  const result = payloadRecord.projectedOutput !== void 0 ? payloadRecord.projectedOutput : payloadRecord.output;
+  if (result === void 0) fail("TOOL_RESULT payload requires output or projectedOutput");
   return {
-    ...typeof payload?.toolCallId === "string" ? { id: payload.toolCallId } : {},
-    ...typeof tool?.name === "string" ? { name: tool.name } : typeof tool?.id === "string" ? { name: tool.id } : {},
-    status: normalizeToolStatus(payload?.status),
-    ...result !== void 0 ? { result } : {},
-    endTime: nowTs()
+    id: expectString(payloadRecord.toolCallId, "TOOL_RESULT payload.toolCallId"),
+    name: expectToolName(tool, "TOOL_RESULT payload.tool.id"),
+    status: expectToolStatus(payloadRecord.status, "TOOL_RESULT payload.status"),
+    result,
+    endTime: now()
   };
 };
 var extractToolCallsFromServerMessage = (msg) => {
-  const metadata = msg.metadata ?? void 0;
-  const topLevelToolCalls = Array.isArray(msg.toolCalls) ? msg.toolCalls || [] : [];
-  const metadataToolCalls = Array.isArray(metadata?.toolCalls) ? metadata.toolCalls : [];
+  const metadata = msg.metadata === null || msg.metadata === void 0 ? void 0 : expectRecord(msg.metadata, "message.metadata");
+  const topLevelToolCalls = readToolCallArray(msg.toolCalls, "message.toolCalls");
+  const metadataToolCalls = readToolCallArray(metadata?.toolCalls, "message.metadata.toolCalls");
   const usedMetadataIndexes = /* @__PURE__ */ new Set();
   const parsed = [];
-  const extractToolName = (obj) => {
-    if (typeof obj.name === "string") return obj.name;
-    const t = obj.tool;
-    if (typeof t?.name === "string") return t.name;
-    if (typeof t?.id === "string") return t.id;
-    return void 0;
-  };
   const findMatchingMetadataIndex = (toolCall) => {
-    const id = typeof toolCall.id === "string" ? toolCall.id : void 0;
-    const name = extractToolName(toolCall);
-    const byId = id ? metadataToolCalls.findIndex((candidate, idx) => !usedMetadataIndexes.has(idx) && candidate?.id === id) : -1;
-    if (byId >= 0) return byId;
-    return name ? metadataToolCalls.findIndex((candidate, idx) => !usedMetadataIndexes.has(idx) && extractToolName(candidate) === name) : -1;
+    const id = expectString(toolCall.id, "message.toolCalls[].id");
+    return metadataToolCalls.findIndex(
+      (candidate, idx) => !usedMetadataIndexes.has(idx) && candidate.id === id
+    );
   };
   const parseToolCall = (primary, secondary) => {
-    const id = typeof primary.id === "string" ? primary.id : typeof secondary?.id === "string" ? secondary.id : void 0;
-    const toolObj = primary.tool;
-    const secondaryToolObj = secondary?.tool;
-    const name = typeof primary.name === "string" ? primary.name : typeof toolObj?.name === "string" ? toolObj.name : typeof toolObj?.id === "string" ? toolObj.id : typeof secondary?.name === "string" ? secondary.name : typeof secondaryToolObj?.name === "string" ? secondaryToolObj.name : typeof secondaryToolObj?.id === "string" ? secondaryToolObj.id : "tool";
-    const argsRaw = primary.args ?? primary.arguments ?? secondary?.args ?? secondary?.arguments;
-    const result = primary.output !== void 0 ? primary.output : primary.result !== void 0 ? primary.result : secondary?.output !== void 0 ? secondary.output : secondary?.result;
-    const status = normalizeToolStatus(primary.status ?? secondary?.status);
+    const id = expectString(primary.id ?? secondary?.id, "toolCall.id");
+    const tool = expectRecord(primary.tool ?? secondary?.tool, "toolCall.tool");
+    const name = expectToolName(tool, "toolCall.tool.id");
+    const argsRaw = primary.args ?? secondary?.args;
+    const result = primary.output !== void 0 ? primary.output : secondary?.output !== void 0 ? secondary.output : primary.projectedOutput !== void 0 ? primary.projectedOutput : secondary?.projectedOutput;
+    const rawStatus = primary.status ?? secondary?.status;
     return {
-      ...id ? { id } : {},
+      id,
       name,
-      arguments: parseToolArguments(argsRaw),
+      arguments: expectToolArguments(argsRaw, "toolCall.args"),
       ...result !== void 0 ? { result } : {},
-      status
+      status: rawStatus === void 0 ? "running" : expectToolStatus(rawStatus, "toolCall.status")
     };
   };
   topLevelToolCalls.forEach((toolCall) => {
@@ -1130,20 +1283,24 @@ var extractToolCallsFromServerMessage = (msg) => {
   });
   return parsed;
 };
-var extractToolResultUpdateFromMessage = (msg) => {
+var readToolCallArray = (value, path) => {
+  if (value === null || value === void 0) return [];
+  if (!Array.isArray(value)) fail(`${path} must be an array`);
+  return value.map((toolCall, index) => expectRecord(toolCall, `${path}[${index}]`));
+};
+var extractToolResultUpdateFromMessage = (msg, now = () => Date.now()) => {
   if (msg.senderType !== "tool") return null;
   const toolCalls = extractToolCallsFromServerMessage(msg);
-  if (!Array.isArray(toolCalls) || toolCalls.length === 0) return null;
+  if (toolCalls.length === 0) fail("tool message requires metadata.toolCalls");
   const firstToolCall = toolCalls[0];
-  const metadata = msg.metadata ?? void 0;
-  const fallbackResult = metadata?.output;
-  const result = firstToolCall.result !== void 0 ? firstToolCall.result : fallbackResult;
+  if (firstToolCall.result === void 0) fail("tool result message requires tool call output");
+  expectStringValue(msg.createdAt, "tool result message.createdAt");
   return {
-    ...firstToolCall.id ? { id: firstToolCall.id } : {},
-    ...firstToolCall.name ? { name: firstToolCall.name } : {},
-    ...result !== void 0 ? { result } : {},
+    id: firstToolCall.id,
+    name: firstToolCall.name,
+    result: firstToolCall.result,
     status: firstToolCall.status,
-    endTime: msg.createdAt ? new Date(msg.createdAt).getTime() : nowTs()
+    endTime: new Date(msg.createdAt).getTime()
   };
 };
 var mergePersistedToolResults = (messages, updates) => {
@@ -1166,42 +1323,95 @@ var prependUniqueMessages = (olderMessages, currentMessages) => {
   }
   return combined;
 };
-var convertServerMessage = (msg) => {
-  const timestamp = msg.createdAt ? new Date(msg.createdAt).getTime() : nowTs();
-  const metadata = msg.metadata ?? void 0;
-  const attachmentsMeta = Array.isArray(metadata?.attachments) ? metadata.attachments : [];
-  const attachments = attachmentsMeta.flatMap((att) => {
-    const kind = typeof att.kind === "string" ? att.kind : void 0;
-    const dataUrl = typeof att.dataUrl === "string" ? att.dataUrl : void 0;
-    const mimeType = typeof att.mimeType === "string" ? att.mimeType : void 0;
-    if (!dataUrl) return [];
-    if (kind === "image") {
-      return [{ kind: "image", dataUrl, mimeType: mimeType ?? "image/jpeg" }];
-    }
-    if (kind === "audio") {
-      return [{
-        kind: "audio",
-        dataUrl,
-        mimeType: mimeType ?? "audio/webm",
-        durationMs: typeof att.durationMs === "number" ? att.durationMs : void 0
-      }];
-    }
-    if (kind === "video") {
-      return [{
-        kind: "video",
-        dataUrl,
-        mimeType: mimeType ?? "video/mp4",
-        durationMs: typeof att.durationMs === "number" ? att.durationMs : void 0,
-        poster: typeof att.poster === "string" ? att.poster : void 0
-      }];
-    }
-    return [];
+var messageAgentKey = (message) => {
+  if (message.role !== "assistant") return null;
+  if (message.sender?.type === "agent" || message.sender?.type === "tool") {
+    return message.sender.agentId ?? message.sender.id;
+  }
+  return null;
+};
+var canAttachToStreamingAssistant = (message, incomingAgentKey) => {
+  if (!message || message.role !== "assistant" || !message.isStreaming) {
+    return false;
+  }
+  const currentAgentKey = messageAgentKey(message);
+  return !incomingAgentKey || !currentAgentKey || currentAgentKey === incomingAgentKey;
+};
+
+// src/messageContract.ts
+var isInternalMessageMetadata = (metadata) => metadata?.visibility === "internal";
+var defaultCreateId = () => globalThis.crypto?.randomUUID?.() ?? `id-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+var defaultNow = () => Date.now();
+var roleBySender = {
+  user: "user",
+  agent: "assistant",
+  tool: "assistant",
+  system: "system"
+};
+var expectNumber = (value, path) => {
+  if (typeof value !== "number" || Number.isNaN(value)) throw new ContractViolation(`${path} must be a number`);
+  return value;
+};
+var extractAttachments = (metadata) => {
+  if (metadata?.attachments === void 0) return [];
+  if (!Array.isArray(metadata.attachments)) {
+    throw new ContractViolation("message.metadata.attachments must be an array");
+  }
+  return metadata.attachments.map((value, index) => {
+    const path = `message.metadata.attachments[${index}]`;
+    const att = expectRecord(value, path);
+    const base = {
+      kind: expectString(att.kind, `${path}.kind`),
+      dataUrl: expectString(att.dataUrl, `${path}.dataUrl`),
+      mimeType: expectString(att.mimeType, `${path}.mimeType`)
+    };
+    if (base.kind === "image") return base;
+    if (base.kind === "audio") return {
+      ...base,
+      ...att.durationMs !== void 0 ? { durationMs: expectNumber(att.durationMs, `${path}.durationMs`) } : {}
+    };
+    if (base.kind === "video") return {
+      ...base,
+      ...att.durationMs !== void 0 ? { durationMs: expectNumber(att.durationMs, `${path}.durationMs`) } : {},
+      ...att.poster !== void 0 ? { poster: expectString(att.poster, `${path}.poster`) } : {}
+    };
+    throw new ContractViolation(`${path}.kind must be image, audio, or video`);
   });
-  const role = msg.senderType === "agent" ? "assistant" : msg.senderType === "user" ? "user" : "assistant";
+};
+var assertRestMessageContract = (msg) => {
+  expectString(msg.id, "message.id");
+  expectString(msg.threadId, "message.threadId");
+  if (!(msg.senderType in roleBySender)) throw new ContractViolation("message.senderType must be user, agent, tool, or system");
+  expectStringValue(msg.content, "message.content");
+  if (msg.metadata !== void 0 && msg.metadata !== null) expectRecord(msg.metadata, "message.metadata");
+  if (msg.createdAt !== void 0) expectString(msg.createdAt, "message.createdAt");
+};
+var shouldRenderHydratedMessage = (msg) => {
+  assertRestMessageContract(msg);
+  const meta = msg.metadata ?? {};
+  if (isInternalMessageMetadata(meta)) {
+    return false;
+  }
+  const text = expectStringValue(msg.content, "message.content").trim();
+  const hasText = text.length > 0;
+  const hasToolCalls = extractToolCallsFromServerMessage(msg).length > 0;
+  const hasAttachments = extractAttachments(meta).length > 0;
+  if (msg.senderType === "tool") {
+    return hasAttachments;
+  }
+  return hasText || hasToolCalls || hasAttachments;
+};
+var convertServerMessage = (msg, options = {}) => {
+  assertRestMessageContract(msg);
+  const timestamp = msg.createdAt ? new Date(msg.createdAt).getTime() : (options.now ?? defaultNow)();
+  const metadata = msg.metadata ?? void 0;
+  const attachments = extractAttachments(metadata);
+  const messageContent = expectStringValue(msg.content, "message.content");
+  const role = roleBySender[msg.senderType];
   const parsedToolCalls = extractToolCallsFromServerMessage(msg);
   const shouldRenderToolCalls = msg.senderType !== "tool";
   const mappedToolCalls = parsedToolCalls.map((toolCall) => ({
-    id: toolCall.id ?? generateId(),
+    id: toolCall.id ?? (options.createId ?? defaultCreateId)(),
     name: toolCall.name,
     arguments: toolCall.arguments,
     status: toolCall.status,
@@ -1209,11 +1419,31 @@ var convertServerMessage = (msg) => {
   }));
   const hasToolCalls = shouldRenderToolCalls && mappedToolCalls.length > 0;
   const isToolSender = msg.senderType === "tool";
-  const content = isToolSender ? "" : (msg.content ?? "") || (hasToolCalls ? "" : "");
+  const content = isToolSender ? "" : messageContent;
   const reasoning = typeof msg.reasoning === "string" && msg.reasoning.length > 0 ? msg.reasoning : void 0;
-  const senderAgentId = msg.senderType === "agent" ? msg.senderId ?? void 0 : void 0;
-  const senderName = msg.senderType === "agent" ? typeof msg.senderName === "string" ? msg.senderName : msg.senderId ?? void 0 : void 0;
-  return syncAssistantActivity({
+  const activityItems = [
+    ...reasoning ? [{
+      id: `${msg.id}:thinking`,
+      kind: "thinking",
+      status: "complete",
+      completedAt: timestamp,
+      details: { reasoning }
+    }] : [],
+    ...hasToolCalls ? mappedToolCalls.map((toolCall) => ({
+      id: toolCall.id,
+      kind: "tool",
+      status: toolCall.status === "failed" ? "failed" : toolCall.status === "completed" ? "complete" : "active",
+      toolName: toolCall.name,
+      startedAt: toolCall.startTime,
+      completedAt: toolCall.endTime,
+      details: {
+        toolCall,
+        ...toolCall.result !== void 0 ? { result: toolCall.result } : {}
+      }
+    })) : []
+  ];
+  const sender = resolveHydratedMessageSender(msg, options.senderOptions);
+  return {
     id: msg.id,
     role,
     content,
@@ -1222,14 +1452,49 @@ var convertServerMessage = (msg) => {
     isStreaming: false,
     isComplete: true,
     metadata,
-    _activityToolCalls: hasToolCalls ? mappedToolCalls : void 0,
-    ...reasoning ? { _activityReasoning: reasoning } : {},
-    ...senderAgentId ? { senderAgentId } : {},
-    ...senderName ? { senderName } : {}
+    activity: activityItems.length > 0 ? { items: activityItems } : void 0,
+    sender
+  };
+};
+var prepareHydratedMessages = async (rawMessages, options = {}) => {
+  rawMessages.forEach(assertRestMessageContract);
+  const resolvedMessages = await resolveAssetsInMessages(rawMessages);
+  resolvedMessages.forEach((msg) => {
+    if (msg.senderType === "tool") {
+      const metadata = msg.metadata ?? void 0;
+      if (!metadata) {
+        throw new ContractViolation("tool message requires metadata");
+      }
+      options.onToolOutput?.(metadata.output === void 0 ? metadata : { output: metadata.output });
+    }
   });
+  const now = options.now ?? defaultNow;
+  const toolResultUpdates = resolvedMessages.map((msg) => extractToolResultUpdateFromMessage(msg, now)).filter((update) => update !== null);
+  const viewMessages = resolvedMessages.filter(shouldRenderHydratedMessage).map((msg) => convertServerMessage(msg, options));
+  return {
+    viewMessages,
+    toolResultUpdates
+  };
 };
+
+// src/useCopilotzChat.ts
+var nowTs = () => Date.now();
+var generateId = () => globalThis.crypto?.randomUUID?.() ?? `id-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+var isAbortError = (error) => error instanceof DOMException && error.name === "AbortError" || typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+var getEventPayload = (event) => event?.payload ?? event;
+var getEventSenderType = (payload) => payload?.senderType || payload?.sender?.type;
+var THREAD_MESSAGES_PAGE_SIZE = 50;
+var createEmptyMessagePageInfo = () => ({
+  hasMoreBefore: false,
+  oldestMessageId: null,
+  newestMessageId: null
+});
 function useCopilotz({
   userId,
+  userName,
+  userAvatar,
+  assistantName,
+  agentOptions = [],
   initialContext,
   bootstrap,
   defaultThreadName,
@@ -1269,6 +1534,11 @@ function useCopilotz({
   const userContextSeedRef = useRef2(userContextSeed);
   const messagePageInfoRef = useRef2(messagePageInfo);
   const isLoadingOlderMessagesRef = useRef2(isLoadingOlderMessages);
+  const senderOptionsRef = useRef2({
+    agents: agentOptions,
+    user: userId ? { id: userId, name: userName, avatarUrl: userAvatar } : null,
+    assistantName
+  });
   const persistedToolUpdatesRef = useRef2([]);
   const liveToolUpdatesRef = useRef2([]);
   threadsRef.current = threads;
@@ -1279,6 +1549,11 @@ function useCopilotz({
   userContextSeedRef.current = userContextSeed;
   messagePageInfoRef.current = messagePageInfo;
   isLoadingOlderMessagesRef.current = isLoadingOlderMessages;
+  senderOptionsRef.current = {
+    agents: agentOptions,
+    user: userId ? { id: userId, name: userName, avatarUrl: userAvatar } : null,
+    assistantName
+  };
   preferredAgentRef.current = preferredAgentName ?? null;
   participantsRef.current = participants ?? null;
   targetAgentNameRef.current = targetAgentName ?? null;
@@ -1335,20 +1610,20 @@ function useCopilotz({
     }
     const senderType = getEventSenderType(payload);
     if (senderType !== "agent" || typeof payload.content !== "string") return;
-    const agentIdentity = resolveLiveAgentIdentity(event);
-    const incomingAgentKey = agentIdentity.senderAgentId ?? agentIdentity.senderName ?? null;
+    const sender = resolveLiveEventSender(event, senderOptionsRef.current);
+    const incomingAgentKey = sender.agentId ?? sender.id;
     setMessages((prev) => {
       const next = [...prev];
       for (let i = next.length - 1; i >= 0; i--) {
         const m = next[i];
         if (canAttachToStreamingAssistant(m, incomingAgentKey)) {
-          next[i] = syncAssistantActivity({
+          next[i] = {
             ...m,
             content: payload.content,
             isStreaming: false,
             isComplete: true,
-            ...agentIdentity
-          });
+            sender
+          };
           return next;
         }
       }
@@ -1358,7 +1633,7 @@ function useCopilotz({
       }
       return [
         ...next,
-        syncAssistantActivity({
+        {
           id: generateId(),
           role: "assistant",
           content: payload.content,
@@ -1366,8 +1641,8 @@ function useCopilotz({
           isStreaming: false,
           isComplete: true,
           metadata: liveMetadata,
-          ...agentIdentity
-        })
+          sender
+        }
       ];
     });
   }, []);
@@ -1424,33 +1699,12 @@ function useCopilotz({
     }
   }, [updateThreadsState, getRequestHeaders]);
   const prepareThreadMessages = useCallback2(async (rawMessages) => {
-    const resolvedMessages = await resolveAssetsInMessages(rawMessages);
-    resolvedMessages.forEach((msg) => {
-      if (msg.senderType === "tool") {
-        const metadata = msg.metadata;
-        const output = metadata?.output ?? metadata;
-        if (output) processToolOutput(output);
-      }
+    return prepareHydratedMessages(rawMessages, {
+      senderOptions: senderOptionsRef.current,
+      createId: generateId,
+      now: nowTs,
+      onToolOutput: processToolOutput
     });
-    const toolResultUpdates = resolvedMessages.map((msg) => extractToolResultUpdateFromMessage(msg)).filter((update) => update !== null);
-    const viewMessages = resolvedMessages.filter((msg) => {
-      const meta = msg.metadata ?? {};
-      if (isInternalMessageMetadata(meta)) {
-        return false;
-      }
-      const text = (typeof msg.content === "string" ? msg.content : "").trim();
-      const hasText = text.length > 0;
-      const hasToolCalls = extractToolCallsFromServerMessage(msg).length > 0;
-      const hasAttachments = Array.isArray(meta.attachments) && meta.attachments.length > 0;
-      if (msg.senderType === "tool") {
-        return hasAttachments;
-      }
-      return hasText || hasToolCalls || hasAttachments;
-    }).map(convertServerMessage);
-    return {
-      viewMessages,
-      toolResultUpdates
-    };
   }, [processToolOutput]);
   const loadThreadMessages = useCallback2(async (threadId) => {
     const requestId = messagesRequestRef.current + 1;
@@ -1658,14 +1912,14 @@ function useCopilotz({
       dataUrl,
       mimeType
     };
-    setMessages((prev) => prev.map((msg) => msg.id === assistantMessageId ? syncAssistantActivity({
+    setMessages((prev) => prev.map((msg) => msg.id === assistantMessageId ? {
       ...msg,
       attachments: [...msg.attachments || [], mediaAttachment]
-    }) : msg));
+    } : msg));
   }, []);
   const sendCopilotzMessage = useCallback2(async (params) => {
-    let currentAssistantId = generateId();
-    let currentAssistantIdentity = {};
+    let currentAssistantId = params.assistantMessageId ?? generateId();
+    let currentAssistantSender = params.assistantSender;
     params.onBeforeStart?.(currentAssistantId);
     let hasStreamProgress = false;
     const updateStreamingMessage = (partial, opts) => {
@@ -1673,28 +1927,26 @@ function useCopilotz({
         hasStreamProgress = true;
       }
       const isReasoning = opts?.isReasoning ?? false;
-      const nextIdentity = normalizeAgentIdentity(opts?.agent ?? null);
-      if (nextIdentity.senderAgentId || nextIdentity.senderName) {
-        currentAssistantIdentity = {
-          ...currentAssistantIdentity,
-          ...nextIdentity
-        };
+      const nextSender = opts?.agent ? resolveAgentSender(opts.agent, senderOptionsRef.current) : currentAssistantSender;
+      if (nextSender) {
+        currentAssistantSender = nextSender;
       }
-      const agentIdentity = currentAssistantIdentity;
-      const nextAgentKey = agentIdentity.senderAgentId ?? agentIdentity.senderName ?? null;
+      const nextAgentKey = currentAssistantSender?.agentId ?? currentAssistantSender?.id ?? null;
       const applyUpdate = (msg) => {
-        return updateAssistantMessageToken(msg, {
-          partial,
-          isReasoning,
-          agentIdentity
-        });
+        return {
+          ...updateAssistantMessageToken(msg, {
+            partial,
+            isReasoning
+          }),
+          ...currentAssistantSender ? { sender: currentAssistantSender } : {}
+        };
       };
       setMessages((prev) => {
         const idx = prev.findIndex((m) => m.id === currentAssistantId);
         if (idx >= 0 && canAttachToStreamingAssistant(prev[idx], nextAgentKey)) {
           const msg = prev[idx];
           const next = applyUpdate(msg);
-          if (msg.content === next.content && msg._activityReasoning === next._activityReasoning && msg._activityReasoningStreaming === next._activityReasoningStreaming && msg.isStreaming === next.isStreaming && msg.isComplete === next.isComplete) {
+          if (msg.content === next.content && msg.activity === next.activity && msg.isStreaming === next.isStreaming && msg.isComplete === next.isComplete) {
             return prev;
           }
           const updated = [...prev];
@@ -1705,7 +1957,7 @@ function useCopilotz({
         if (canAttachToStreamingAssistant(last, nextAgentKey)) {
           currentAssistantId = last.id;
           const next = applyUpdate(last);
-          if (last.content === next.content && last._activityReasoning === next._activityReasoning && last._activityReasoningStreaming === next._activityReasoningStreaming && last.isStreaming === next.isStreaming && last.isComplete === next.isComplete) {
+          if (last.content === next.content && last.activity === next.activity && last.isStreaming === next.isStreaming && last.isComplete === next.isComplete) {
             return prev;
           }
           const updated = [...prev];
@@ -1723,7 +1975,7 @@ function useCopilotz({
             timestamp: nowTs(),
             isStreaming: true,
             isComplete: false,
-            ...currentAssistantIdentity
+            ...currentAssistantSender ? { sender: currentAssistantSender } : {}
           };
           return [...prev, applyUpdate(base)];
         }
@@ -1770,7 +2022,7 @@ function useCopilotz({
         if (fallbackIdx < 0) return prev;
         const message = prev[fallbackIdx];
         const nextMessage = finalizeAssistantMessage(message, finalAnswer);
-        if (message.content === nextMessage.content && message.isStreaming === nextMessage.isStreaming && message.isComplete === nextMessage.isComplete && message._activityReasoningStreaming === nextMessage._activityReasoningStreaming) {
+        if (message.content === nextMessage.content && message.isStreaming === nextMessage.isStreaming && message.isComplete === nextMessage.isComplete && message.activity === nextMessage.activity) {
           return prev;
         }
         const updated = [...prev];
@@ -1785,7 +2037,6 @@ function useCopilotz({
       const payload = event?.payload ?? event;
       if (type === "TOOL_CALL") {
         const parsedToolCall = extractLiveToolCall(payload);
-        if (!parsedToolCall) return null;
         return {
           id: generateId(),
           threadId: curThreadId ?? "",
@@ -1871,14 +2122,9 @@ function useCopilotz({
             const parsedToolCall = extractLiveToolCall(
               payload ?? {}
             );
-            if (!parsedToolCall) return;
-            const eventAgentIdentity = resolveLiveAgentIdentity(event);
-            if (eventAgentIdentity.senderAgentId || eventAgentIdentity.senderName) {
-              currentAssistantIdentity = {
-                ...currentAssistantIdentity,
-                ...eventAgentIdentity
-              };
-            }
+            const eventSender = resolveLiveEventSender(event, senderOptionsRef.current);
+            currentAssistantSender = eventSender;
+            const eventAgentKey = currentAssistantSender.agentId ?? currentAssistantSender.id;
             const callId = parsedToolCall.id ?? generateId();
             const toolName = parsedToolCall.name;
             const bufferedUpdates = liveToolUpdatesRef.current;
@@ -1892,6 +2138,10 @@ function useCopilotz({
             const endTime = bufferedUpdate?.endTime;
             setMessages(
               (prev) => (() => {
+                const canHostActivity = (message) => {
+                  if (!message) return false;
+                  return message.role === "assistant" && message.isStreaming && message.content.trim().length === 0 && !message.attachments?.length;
+                };
                 const appendToolCall = (msg) => ({
                   ...appendAssistantToolCall(msg, {
                     id: callId,
@@ -1903,21 +2153,21 @@ function useCopilotz({
                     ...endTime !== void 0 ? { endTime } : {}
                   })
                 });
-                const currentIdx = prev.findIndex((message) => message.id === currentAssistantId && message.role === "assistant" && message.isStreaming);
+                const currentIdx = prev.findIndex((message) => message.id === currentAssistantId && message.role === "assistant" && message.isStreaming && canHostActivity(message));
                 if (currentIdx >= 0) {
                   const next = [...prev];
                   next[currentIdx] = appendToolCall({
                     ...next[currentIdx],
                     isStreaming: true,
                     isComplete: false,
-                    ...currentAssistantIdentity
+                    ...currentAssistantSender ? { sender: currentAssistantSender } : {}
                   });
                   return next;
                 }
                 const last = prev[prev.length - 1];
-                if (canAttachToStreamingAssistant(
+                if (canHostActivity(last) && canAttachToStreamingAssistant(
                   last,
-                  currentAssistantIdentity.senderAgentId ?? currentAssistantIdentity.senderName ?? null
+                  eventAgentKey
                 )) {
                   currentAssistantId = last.id;
                   const next = [...prev];
@@ -1925,7 +2175,7 @@ function useCopilotz({
                     ...last,
                     isStreaming: true,
                     isComplete: false,
-                    ...currentAssistantIdentity
+                    ...currentAssistantSender ? { sender: currentAssistantSender } : {}
                   });
                   return next;
                 }
@@ -1940,7 +2190,7 @@ function useCopilotz({
                     timestamp: nowTs(),
                     isStreaming: true,
                     isComplete: false,
-                    ...currentAssistantIdentity
+                    ...currentAssistantSender ? { sender: currentAssistantSender } : {}
                   })
                 ];
               })()
@@ -1950,7 +2200,11 @@ function useCopilotz({
           }
           const sm = await toServerMessageFromEvent(event);
           if (sm) {
-            const viewMsg = convertServerMessage(sm);
+            const viewMsg = convertServerMessage(sm, {
+              senderOptions: senderOptionsRef.current,
+              createId: generateId,
+              now: nowTs
+            });
             finalizeCurrentAssistantBubble();
             setMessages((prev) => [...prev, viewMsg]);
             return;
@@ -2008,8 +2262,19 @@ function useCopilotz({
       content,
       timestamp,
       attachments: attachments.length > 0 ? attachments : void 0,
-      isComplete: true
+      isComplete: true,
+      sender: resolveUserSender({
+        id: userId,
+        name: userContextSeedRef.current?.profile?.full_name ?? userId
+      })
     };
+    const assistantSender = targetAgentNameRef.current ? resolveAgentSender(
+      { id: targetAgentNameRef.current, name: targetAgentNameRef.current },
+      senderOptionsRef.current
+    ) : preferredAgentRef.current ? resolveAgentSender(
+      { id: preferredAgentRef.current, name: preferredAgentRef.current },
+      senderOptionsRef.current
+    ) : resolveAssistantFallbackSender(senderOptionsRef.current);
     const assistantPlaceholder = {
       id: generateId(),
       role: "assistant",
@@ -2017,9 +2282,9 @@ function useCopilotz({
       timestamp: timestamp + 1,
       isStreaming: true,
       isComplete: false,
-      ...targetAgentNameRef.current ? { senderName: targetAgentNameRef.current } : {}
+      sender: assistantSender
     };
-    setMessages((prev) => [...prev, userMessage, syncAssistantActivity(assistantPlaceholder)]);
+    setMessages((prev) => [...prev, userMessage, assistantPlaceholder]);
     setSpecialState(null);
     if (!threadsRef.current.some((t) => t.id === conversationKey)) {
       const newThread = {
@@ -2043,6 +2308,8 @@ function useCopilotz({
         // userName can be anything, but let's try to find it in context or just fallback
         userName: userContextSeedRef.current?.profile?.full_name ?? userId,
         agentName: preferredAgentRef.current,
+        assistantMessageId: assistantPlaceholder.id,
+        assistantSender,
         // Include pending title for new threads
         threadMetadata: pendingTitle ? { name: pendingTitle } : void 0
       });
@@ -2066,24 +2333,26 @@ function useCopilotz({
           const message = finalized[i];
           if (message.role !== "assistant") continue;
           const updated = [...finalized];
-          updated[i] = syncAssistantActivity({
+          updated[i] = {
             ...message,
             content: "Desculpe, ocorreu um erro ao gerar a resposta. Por favor, tente novamente.",
             isStreaming: false,
-            isComplete: true
-          });
+            isComplete: true,
+            sender: message.sender ?? resolveAssistantFallbackSender(senderOptionsRef.current)
+          };
           return updated;
         }
         return [
           ...finalized,
-          syncAssistantActivity({
+          {
             id: generateId(),
             role: "assistant",
             content: "Desculpe, ocorreu um erro ao gerar a resposta. Por favor, tente novamente.",
             timestamp: nowTs(),
             isStreaming: false,
-            isComplete: true
-          })
+            isComplete: true,
+            sender: resolveAssistantFallbackSender(senderOptionsRef.current)
+          }
         ];
       });
     }
@@ -2122,14 +2391,15 @@ function useCopilotz({
         return;
       }
       setMessages([
-        syncAssistantActivity({
+        {
           id: generateId(),
           role: "assistant",
           content: "N\xE3o foi poss\xEDvel iniciar a conversa. Tente novamente mais tarde.",
           timestamp: nowTs(),
           isStreaming: false,
-          isComplete: true
-        })
+          isComplete: true,
+          sender: resolveAssistantFallbackSender(senderOptionsRef.current)
+        }
       ]);
     }
   }, [fetchAndSetThreadsState, loadThreadMessages, sendCopilotzMessage, bootstrap, defaultThreadName, getSpecialStateFromError]);
@@ -2275,6 +2545,10 @@ var CopilotzChat = ({
     loadOlderMessages
   } = useCopilotz({
     userId,
+    userName,
+    userAvatar,
+    assistantName: userConfig?.branding?.title,
+    agentOptions,
     initialContext,
     bootstrap,
     defaultThreadName: userConfig?.labels?.defaultThreadName,