@truedat/ai 8.3.5 → 8.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truedat/ai",
-  "version": "8.3.5",
+  "version": "8.3.6",
   "description": "Truedat Web Artificial Intelligence package",
   "sideEffects": false,
   "module": "src/index.js",
@@ -50,7 +50,7 @@
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@truedat/test": "8.3.5",
+    "@truedat/test": "8.3.6",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^29.7.0",
     "redux-saga-test-plan": "^4.0.6"
@@ -62,6 +62,7 @@
     "lodash": "^4.17.21",
     "moment": "^2.30.1",
     "path-to-regexp": "^8.2.0",
+    "phoenix": "^1.7.10",
     "prop-types": "^15.8.1",
     "query-string": "^7.1.3",
     "react": "^19.1.0",
@@ -79,5 +80,5 @@
     "semantic-ui-react": "^3.0.0-beta.2",
     "swr": "^2.3.3"
   },
-  "gitHead": "12d1969c3403861d360fbdc24fd270ab1fece070"
+  "gitHead": "767585383b6373e75fa50d7440e9ecf67b0573c2"
 }

package/src/api.js

@@ -16,6 +16,8 @@ const API_SUGGESTIONS_REQUEST = "/api/suggestions/request";
 const API_TRANSLATIONS_AVAILABILITY_CHECK =
   "/api/translations/availability_check";
 const API_TRANSLATIONS_REQUEST = "/api/translations/request";
+const API_AGENT_LAYER_CONVERSATION = "/api/agent_layer/conversation";
+const API_SOCKET_ENDPOINT = "/api/socket";
 
 export {
   API_ACTION,
@@ -34,4 +36,6 @@ export {
   API_SUGGESTIONS_REQUEST,
   API_TRANSLATIONS_AVAILABILITY_CHECK,
   API_TRANSLATIONS_REQUEST,
+  API_AGENT_LAYER_CONVERSATION,
+  API_SOCKET_ENDPOINT,
 };

package/src/components/assistant/Assistant.js

@@ -0,0 +1,126 @@
+import { useRef, useState, useCallback, useEffect } from "react";
+import { useWebContext } from "@truedat/core/webContext";
+
+import useAssistantSocket from "./hooks/useAssistantSocket";
+import useAgentConversation from "./hooks/useAgentConversation";
+import AssistantBubble from "./AssistantBubble";
+import AssistantChat from "./AssistantChat";
+
+const FADE_DURATION_MS = 150;
+const EMPTY_CONVERSATION = [];
+
+const Assistant = () => {
+  const { disable_td_ai: disableTdAi = false } = useWebContext();
+
+  const [isOpen, setIsOpen] = useState(false);
+  const { conversationId, startNewConversation } = useAgentConversation(isOpen);
+  const [contentFadeOut, setContentFadeOut] = useState(false);
+  const [contentFadeIn, setContentFadeIn] = useState(false);
+
+  const [conversation, setConversation] = useState(EMPTY_CONVERSATION);
+  const prevConversationIdRef = useRef(null);
+
+  const containerRef = useRef(null);
+  const serverMessageHandlerRef = useRef(null);
+  const pendingTransitionEndRef = useRef(false);
+  const fadeTimeoutRef = useRef(null);
+  const fadeInTimeoutRef = useRef(null);
+
+  useEffect(() => {
+    if (conversationId !== prevConversationIdRef.current) {
+      prevConversationIdRef.current = conversationId;
+      if (conversationId != null) {
+        setConversation(EMPTY_CONVERSATION);
+      }
+    }
+  }, [conversationId]);
+
+  const onChannelJoined = useCallback(() => {}, []);
+  const handleServerMessage = useCallback((event, payload) => {
+    serverMessageHandlerRef.current?.(event, payload);
+  }, []);
+  const handleNewChat = useCallback(() => {
+    setConversation(EMPTY_CONVERSATION);
+    startNewConversation();
+  }, [startNewConversation]);
+
+  const effectiveConversationId = isOpen ? conversationId : null;
+  const { socketReady, sendPrompt } = useAssistantSocket(disableTdAi, {
+    conversationId: effectiveConversationId,
+    onChannelJoined,
+    onServerMessage: handleServerMessage,
+  });
+
+  const handleTransitionEnd = useCallback(() => {
+    if (!pendingTransitionEndRef.current) return;
+    pendingTransitionEndRef.current = false;
+    setContentFadeIn(true);
+    fadeInTimeoutRef.current = setTimeout(() => {
+      setContentFadeIn(false);
+    }, FADE_DURATION_MS);
+  }, []);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    el.addEventListener("transitionend", handleTransitionEnd);
+    return () => {
+      el.removeEventListener("transitionend", handleTransitionEnd);
+    };
+  }, [handleTransitionEnd]);
+
+  useEffect(() => {
+    return () => {
+      if (fadeTimeoutRef.current) clearTimeout(fadeTimeoutRef.current);
+      if (fadeInTimeoutRef.current) clearTimeout(fadeInTimeoutRef.current);
+    };
+  }, []);
+
+  const startOpenTransition = useCallback(() => {
+    setContentFadeOut(true);
+    fadeTimeoutRef.current = setTimeout(() => {
+      setContentFadeOut(false);
+      setIsOpen(true);
+      pendingTransitionEndRef.current = true;
+    }, FADE_DURATION_MS);
+  }, []);
+
+  const startCloseTransition = useCallback(() => {
+    setContentFadeOut(true);
+    fadeTimeoutRef.current = setTimeout(() => {
+      setContentFadeOut(false);
+      setIsOpen(false);
+      pendingTransitionEndRef.current = true;
+    }, FADE_DURATION_MS);
+  }, []);
+
+  if (!socketReady) return null;
+
+  return (
+    <div
+      ref={containerRef}
+      className={`assistant-container assistant-container--${isOpen ? "open" : "closed"}`}
+    >
+      {isOpen ? (
+        <AssistantChat
+          conversation={conversation}
+          setConversation={setConversation}
+          onNewChat={handleNewChat}
+          onClose={startCloseTransition}
+          onSendMessage={sendPrompt}
+          serverMessageHandlerRef={serverMessageHandlerRef}
+          fadeOut={contentFadeOut}
+          fadeIn={contentFadeIn}
+        />
+      ) : (
+        <AssistantBubble
+          onClick={startOpenTransition}
+          fadeOut={contentFadeOut}
+          fadeIn={contentFadeIn}
+        />
+      )}
+    </div>
+  );
+};
+
+export default Assistant;

package/src/components/assistant/AssistantBubble.js

@@ -0,0 +1,56 @@
+import PropTypes from "prop-types";
+import { useIntl } from "react-intl";
+import { Icon } from "semantic-ui-react";
+import truedatLogo from "assets/truedat-logo-home-no-text.png";
+
+const AssistantBubble = ({ onClick, fadeOut, fadeIn }) => {
+  const { formatMessage } = useIntl();
+  const className = [
+    "assistant-bubble",
+    fadeOut && "assistant-content--fade-out",
+    fadeIn && "assistant-content--fade-in",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const isLogoSrcString = typeof truedatLogo === "string";
+
+  return (
+    <div
+      className={className}
+      role="button"
+      aria-label={formatMessage({ id: "assistant.bubble.label" })}
+      onClick={onClick}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          onClick();
+        }
+      }}
+      tabIndex={0}
+    >
+      {isLogoSrcString ? (
+        <img
+          src={truedatLogo}
+          alt={formatMessage({ id: "assistant.bubble.label" })}
+          className="assistant-bubble__logo"
+        />
+      ) : (
+        <Icon name="comments" />
+      )}
+    </div>
+  );
+};
+
+AssistantBubble.propTypes = {
+  onClick: PropTypes.func.isRequired,
+  fadeOut: PropTypes.bool,
+  fadeIn: PropTypes.bool,
+};
+
+AssistantBubble.defaultProps = {
+  fadeOut: false,
+  fadeIn: false,
+};
+
+export default AssistantBubble;

package/src/components/assistant/AssistantChat.js

@@ -0,0 +1,312 @@
+import { useState, useCallback, useMemo, useRef, useEffect } from "react";
+import PropTypes from "prop-types";
+import { FormattedMessage, useIntl } from "react-intl";
+import { Icon } from "semantic-ui-react";
+import { MarkdownReader } from "@truedat/core/components";
+
+const SCROLL_AT_BOTTOM_THRESHOLD = 50;
+
+function getVisibleMessages(conversation) {
+  if (!conversation || conversation.length === 0) return [];
+  let lastRequestOrResponseIndex = -1;
+  for (let i = conversation.length - 1; i >= 0; i--) {
+    const eventType = conversation[i].eventType;
+    if (eventType === "request" || eventType === "response") {
+      lastRequestOrResponseIndex = i;
+      break;
+    }
+  }
+  return conversation
+    .map((item, idx) => ({ ...item, index: idx }))
+    .filter(
+      (item) =>
+        item.eventType === "request" ||
+        item.eventType === "response" ||
+        (item.eventType === "log" && item.index > lastRequestOrResponseIndex)
+    );
+}
+
+function getContentFromPayload(event, payload) {
+  if (!payload || typeof payload !== "object") return { content: "", isError: false };
+  switch (event) {
+    case "stream": {
+      const c = payload.content;
+      const streamChunk =
+        typeof c === "string"
+          ? c
+          : c && typeof c === "object" && typeof c.message === "string"
+            ? c.message
+            : "";
+      return { content: streamChunk, isError: false };
+    }
+    case "error": {
+      const err = payload.error;
+      const errMsg =
+        err && typeof err === "object"
+          ? err.message ?? err.reason ?? JSON.stringify(err)
+          : String(err ?? "");
+      return { content: errMsg, isError: true };
+    }
+    case "log": {
+      const log = payload.content;
+      const logMsg =
+        log && typeof log === "object"
+          ? log.message ?? log.level ?? JSON.stringify(log)
+          : String(log ?? "");
+      return { content: logMsg, isError: false };
+    }
+    default:
+      return { content: "", isError: false };
+  }
+}
+
+function appendStreamChunk(prev, source, chunk) {
+  const last = prev[prev.length - 1];
+  const sameSource =
+    last?.eventType === "response" &&
+    last?.streaming &&
+    last?.source === source;
+  if (sameSource) {
+    return [
+      ...prev.slice(0, -1),
+      { ...last, content: last.content + chunk },
+    ];
+  }
+  return [
+    ...prev,
+    {
+      eventType: "response",
+      side: "agent",
+      content: chunk || " ",
+      streaming: true,
+      source,
+    },
+  ];
+}
+
+const AssistantChat = ({
+  conversation,
+  setConversation,
+  onNewChat,
+  onClose,
+  onSendMessage,
+  serverMessageHandlerRef,
+  fadeOut,
+  fadeIn,
+}) => {
+  const { formatMessage } = useIntl();
+  const [inputValue, setInputValue] = useState("");
+  const [showScrollToBottom, setShowScrollToBottom] = useState(false);
+  const messagesRef = useRef(null);
+  const scrollToBottomAfterSendRef = useRef(false);
+
+  useEffect(() => {
+    const ref = serverMessageHandlerRef;
+    if (!ref) return;
+    ref.current = (event, payload) => {
+      const { content, isError } = getContentFromPayload(event, payload);
+      if (event === "stream") {
+        const source = payload?.source ?? null;
+        requestAnimationFrame(() => {
+          setConversation((prev) => appendStreamChunk(prev, source, content));
+        });
+      } else if (event === "log") {
+        setConversation((prev) => [
+          ...prev,
+          { eventType: "log", side: "agent", content: content || " " },
+        ]);
+      } else {
+        setConversation((prev) => [
+          ...prev,
+          {
+            eventType: "response",
+            side: "agent",
+            content: content || "Error",
+            isError: true,
+          },
+        ]);
+      }
+      scrollToBottomAfterSendRef.current = true;
+    };
+    return () => {
+      ref.current = null;
+    };
+  }, [serverMessageHandlerRef, setConversation]);
+
+  const visibleMessages = useMemo(
+    () => getVisibleMessages(conversation),
+    [conversation]
+  );
+
+  const handleSubmit = useCallback(
+    (e) => {
+      e?.preventDefault?.();
+      const text = inputValue.trim();
+      if (!text) return;
+      scrollToBottomAfterSendRef.current = true;
+      setConversation((prev) => [
+        ...prev,
+        { eventType: "request", side: "user", content: text },
+      ]);
+      setInputValue("");
+      if (typeof onSendMessage === "function") {
+        onSendMessage(text);
+      }
+    },
+    [inputValue, onSendMessage]
+  );
+
+  const handleKeyDown = useCallback(
+    (e) => {
+      if (e.key === "Enter" && !e.shiftKey) {
+        e.preventDefault();
+        handleSubmit();
+      }
+    },
+    [handleSubmit]
+  );
+
+  const handleNewChat = useCallback(() => {
+    if (typeof onNewChat === "function") onNewChat();
+    setInputValue("");
+  }, [onNewChat]);
+
+  const scrollToBottom = useCallback(() => {
+    const el = messagesRef.current;
+    if (el) {
+      el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+    }
+  }, []);
+
+  const checkScrollPosition = useCallback(() => {
+    const el = messagesRef.current;
+    if (!el) return;
+    const atBottom =
+      el.scrollHeight - el.scrollTop - el.clientHeight <=
+      SCROLL_AT_BOTTOM_THRESHOLD;
+    setShowScrollToBottom((prev) => (prev !== !atBottom ? !atBottom : prev));
+  }, []);
+
+  useEffect(() => {
+    const el = messagesRef.current;
+    if (!el) return;
+    checkScrollPosition();
+    if (scrollToBottomAfterSendRef.current) {
+      scrollToBottomAfterSendRef.current = false;
+      requestAnimationFrame(() => {
+        el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+      });
+    }
+    el.addEventListener("scroll", checkScrollPosition);
+    return () => el.removeEventListener("scroll", checkScrollPosition);
+  }, [checkScrollPosition, visibleMessages.length]);
+
+  const className = [
+    "assistant-chat",
+    fadeOut && "assistant-content--fade-out",
+    fadeIn && "assistant-content--fade-in",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div className={className}>
+      <div className="assistant-chat__actions">
+        <button
+          type="button"
+          className="assistant-chat__action assistant-chat__action--new-chat"
+          onClick={handleNewChat}
+          aria-label={formatMessage({ id: "assistant.actions.newChat" })}
+        >
+          <Icon name="comment outline" />
+          <FormattedMessage id="assistant.actions.newChat" />
+        </button>
+        <button
+          type="button"
+          className="assistant-chat__action assistant-chat__action--close"
+          onClick={onClose}
+          aria-label={formatMessage({ id: "assistant.actions.close" })}
+        >
+          <Icon name="close" />
+        </button>
+      </div>
+      <div className="assistant-chat__messages-wrapper">
+        <div
+          ref={messagesRef}
+          className="assistant-chat__messages"
+          role="log"
+          aria-label={formatMessage({ id: "assistant.messages.history" })}
+        >
+          {visibleMessages.map((msg) => (
+            <div
+              key={`${msg.eventType}-${msg.index}`}
+              className={`assistant-chat__message assistant-chat__message--${msg.eventType} assistant-chat__message--${msg.side}`}
+            >
+              <div className="assistant-chat__message-content">
+                {msg.side === "agent" && msg.content?.trim() ? (
+                  <MarkdownReader content={msg.content} />
+                ) : (
+                  msg.content
+                )}
+              </div>
+            </div>
+          ))}
+        </div>
+        {showScrollToBottom && (
+          <button
+            type="button"
+            className="assistant-chat__scroll-to-bottom"
+            onClick={scrollToBottom}
+            aria-label={formatMessage({ id: "assistant.actions.scrollToBottom" })}
+          >
+            <Icon name="chevron down" />
+          </button>
+        )}
+      </div>
+      <div className="assistant-chat__footer">
+        <form className="assistant-chat__input-row" onSubmit={handleSubmit}>
+          <input
+            type="text"
+            className="assistant-chat__input"
+            placeholder={formatMessage({ id: "assistant.input.placeholder" })}
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            onKeyDown={handleKeyDown}
+            aria-label={formatMessage({ id: "assistant.input.label" })}
+          />
+          <button
+            type="submit"
+            className="assistant-chat__send"
+            aria-label={formatMessage({ id: "assistant.actions.send" })}
+          >
+            <Icon name="send" />
+          </button>
+        </form>
+        <div className="assistant-chat__disclaimer">
+          <FormattedMessage id="assistant.disclaimer" />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+AssistantChat.propTypes = {
+  conversation: PropTypes.arrayOf(PropTypes.object).isRequired,
+  setConversation: PropTypes.func.isRequired,
+  onNewChat: PropTypes.func,
+  onClose: PropTypes.func.isRequired,
+  onSendMessage: PropTypes.func,
+  serverMessageHandlerRef: PropTypes.shape({ current: PropTypes.any }),
+  fadeOut: PropTypes.bool,
+  fadeIn: PropTypes.bool,
+};
+
+AssistantChat.defaultProps = {
+  onNewChat: undefined,
+  onSendMessage: undefined,
+  serverMessageHandlerRef: null,
+  fadeOut: false,
+  fadeIn: false,
+};
+
+export default AssistantChat;

package/src/components/assistant/__tests__/Assistant.spec.js

@@ -0,0 +1,45 @@
+import React from "react";
+import { render, waitForLoad } from "@truedat/test/render";
+
+import Assistant from "../Assistant";
+import useAssistantSocket from "../hooks/useAssistantSocket";
+
+jest.mock("@truedat/core/webContext", () => ({
+  useWebContext: jest.fn(() => ({ disable_td_ai: false })),
+}));
+
+jest.mock("../hooks/useAssistantSocket", () =>
+  jest.fn(() => ({
+    socketReady: false,
+    sendPrompt: jest.fn(),
+  }))
+);
+
+jest.mock("../hooks/useAgentConversation", () =>
+  jest.fn(() => ({
+    conversationId: null,
+    startNewConversation: jest.fn(),
+  }))
+);
+
+describe("<Assistant />", () => {
+  it("renders nothing when socket is not ready", async () => {
+    useAssistantSocket.mockReturnValue({
+      socketReady: false,
+      sendPrompt: jest.fn(),
+    });
+    const rendered = render(<Assistant />);
+    await waitForLoad(rendered);
+    expect(rendered.container).toMatchSnapshot();
+  });
+
+  it("matches the latest snapshot when socket is ready", async () => {
+    useAssistantSocket.mockReturnValue({
+      socketReady: true,
+      sendPrompt: jest.fn(),
+    });
+    const rendered = render(<Assistant />);
+    await waitForLoad(rendered);
+    expect(rendered.container).toMatchSnapshot();
+  });
+});

package/src/components/assistant/__tests__/AssistantBubble.spec.js

@@ -0,0 +1,14 @@
+import React from "react";
+import { render, waitForLoad } from "@truedat/test/render";
+
+import AssistantBubble from "../AssistantBubble";
+
+describe("<AssistantBubble />", () => {
+  it("matches the latest snapshot", async () => {
+    const rendered = render(
+      <AssistantBubble onClick={jest.fn()} />
+    );
+    await waitForLoad(rendered);
+    expect(rendered.container).toMatchSnapshot();
+  });
+});

package/src/components/assistant/__tests__/AssistantChat.spec.js

@@ -0,0 +1,27 @@
+import React from "react";
+import { render, waitForLoad } from "@truedat/test/render";
+
+import AssistantChat from "../AssistantChat";
+
+const defaultProps = {
+  conversation: [
+    {
+      eventType: "log",
+      side: "agent",
+      content: "Requesting connection",
+    },
+  ],
+  setConversation: jest.fn(),
+  onClose: jest.fn(),
+  channelJoined: false,
+  conversationId: null,
+  serverMessageHandlerRef: { current: null },
+};
+
+describe("<AssistantChat />", () => {
+  it("matches the latest snapshot", async () => {
+    const rendered = render(<AssistantChat {...defaultProps} />);
+    await waitForLoad(rendered);
+    expect(rendered.container).toMatchSnapshot();
+  });
+});

package/src/components/assistant/__tests__/__snapshots__/Assistant.spec.js.snap

@@ -0,0 +1,23 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`<Assistant /> matches the latest snapshot when socket is ready 1`] = `
+<div>
+  <div
+    class="assistant-container assistant-container--closed"
+  >
+    <div
+      aria-label="assistant.bubble.label"
+      class="assistant-bubble"
+      role="button"
+      tabindex="0"
+    >
+      <i
+        aria-hidden="true"
+        class="comments icon"
+      />
+    </div>
+  </div>
+</div>
+`;
+
+exports[`<Assistant /> renders nothing when socket is not ready 1`] = `<div />`;

package/src/components/assistant/__tests__/__snapshots__/AssistantBubble.spec.js.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`<AssistantBubble /> matches the latest snapshot 1`] = `
+<div>
+  <div
+    aria-label="assistant.bubble.label"
+    class="assistant-bubble"
+    role="button"
+    tabindex="0"
+  >
+    <i
+      aria-hidden="true"
+      class="comments icon"
+    />
+  </div>
+</div>
+`;

package/src/components/assistant/__tests__/__snapshots__/AssistantChat.spec.js.snap

@@ -0,0 +1,92 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`<AssistantChat /> matches the latest snapshot 1`] = `
+<div>
+  <div
+    class="assistant-chat"
+  >
+    <div
+      class="assistant-chat__actions"
+    >
+      <button
+        aria-label="assistant.actions.newChat"
+        class="assistant-chat__action assistant-chat__action--new-chat"
+        type="button"
+      >
+        <i
+          aria-hidden="true"
+          class="comment outline icon"
+        />
+        assistant.actions.newChat
+      </button>
+      <button
+        aria-label="assistant.actions.close"
+        class="assistant-chat__action assistant-chat__action--close"
+        type="button"
+      >
+        <i
+          aria-hidden="true"
+          class="close icon"
+        />
+      </button>
+    </div>
+    <div
+      class="assistant-chat__messages-wrapper"
+    >
+      <div
+        aria-label="assistant.messages.history"
+        class="assistant-chat__messages"
+        role="log"
+      >
+        <div
+          class="assistant-chat__message assistant-chat__message--log assistant-chat__message--agent"
+        >
+          <div
+            class="assistant-chat__message-content"
+          >
+            <div
+              class="markdown-reader"
+            >
+              <p>
+                Requesting connection
+              </p>
+              
+
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+    <div
+      class="assistant-chat__footer"
+    >
+      <form
+        class="assistant-chat__input-row"
+      >
+        <input
+          aria-label="assistant.input.label"
+          class="assistant-chat__input"
+          placeholder="assistant.input.placeholder"
+          type="text"
+          value=""
+        />
+        <button
+          aria-label="assistant.actions.send"
+          class="assistant-chat__send"
+          type="submit"
+        >
+          <i
+            aria-hidden="true"
+            class="send icon"
+          />
+        </button>
+      </form>
+      <div
+        class="assistant-chat__disclaimer"
+      >
+        assistant.disclaimer
+      </div>
+    </div>
+  </div>
+</div>
+`;

package/src/components/assistant/hooks/useAgentConversation.js

@@ -0,0 +1,38 @@
+import { useCallback, useEffect, useState } from "react";
+
+import { apiJsonPost } from "@truedat/core/services/api";
+
+import { API_AGENT_LAYER_CONVERSATION } from "../../../api";
+
+const useAgentConversation = (isOpen) => {
+  const [conversationId, setConversationId] = useState(null);
+
+  useEffect(() => {
+    if (!isOpen || conversationId != null) return;
+
+    apiJsonPost(API_AGENT_LAYER_CONVERSATION, {})
+      .then((res) => {
+        const data = res?.data;
+        const payload = data?.data != null ? data.data : data;
+        const rawId =
+          payload?.agent_state_id ??
+          payload?.id ??
+          data?.agent_state_id ??
+          data?.id;
+        const id =
+          typeof rawId === "string" || typeof rawId === "number"
+            ? String(rawId)
+            : null;
+        if (id != null) setConversationId(id);
+      })
+      .catch(() => { });
+  }, [isOpen, conversationId]);
+
+  const startNewConversation = useCallback(() => {
+    setConversationId(null);
+  }, []);
+
+  return { conversationId, startNewConversation };
+};
+
+export default useAgentConversation;

package/src/components/assistant/hooks/useAssistantSocket.js

@@ -0,0 +1,120 @@
+import { useRef, useState, useEffect, useCallback } from "react";
+import { Socket } from "phoenix";
+
+import { readToken } from "@truedat/core/services/storage";
+
+import { API_SOCKET_ENDPOINT } from "../../../api";
+
+const KEEP_ALIVE_INTERVAL_MS = 20000;
+const CONNECT_DELAY_MS = 150;
+const RECONNECT_DELAY_MS = 2000;
+
+const useAssistantSocket = (disabled = false, options = {}) => {
+  const { conversationId = null, onChannelJoined, onServerMessage } = options;
+  const [socketReady, setSocketReady] = useState(false);
+  const socketRef = useRef(null);
+  const channelRef = useRef(null);
+
+  useEffect(() => {
+    if (disabled) return;
+
+    const token = readToken();
+    if (!token) return;
+
+    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const host = window.location.host;
+
+    const socket = new Socket(protocol + host + API_SOCKET_ENDPOINT, {
+      params: { token },
+      heartbeatIntervalMs: KEEP_ALIVE_INTERVAL_MS,
+    });
+    socketRef.current = socket;
+
+    const disconnectRequestedRef = { current: false };
+    let reconnectTimeoutId = null;
+    let connectTimeoutId = null;
+
+    socket.onOpen(() => setSocketReady(true));
+    socket.onClose(() => {
+      setSocketReady(false);
+      if (disconnectRequestedRef.current) return;
+      reconnectTimeoutId = setTimeout(() => {
+        if (!socketRef.current || disconnectRequestedRef.current) return;
+        socketRef.current.connect();
+      }, RECONNECT_DELAY_MS);
+    });
+    socket.onError(() => setSocketReady(false));
+
+    connectTimeoutId = setTimeout(() => {
+      if (disconnectRequestedRef.current || !socketRef.current) return;
+      socket.connect();
+    }, CONNECT_DELAY_MS);
+
+    return () => {
+      disconnectRequestedRef.current = true;
+      if (connectTimeoutId) clearTimeout(connectTimeoutId);
+      if (reconnectTimeoutId) clearTimeout(reconnectTimeoutId);
+      if (socketRef.current) {
+        socketRef.current.disconnect();
+        socketRef.current = null;
+      }
+      setSocketReady(false);
+    };
+  }, [disabled]);
+
+  useEffect(() => {
+    if (!socketReady || !conversationId || !socketRef.current) return;
+    const topic = `agent_layer:${conversationId}`;
+    const channel = socketRef.current.channel(topic, {});
+    channelRef.current = channel;
+
+    const handleEvent = (event, payload) => {
+      if (typeof onServerMessage === "function") {
+        onServerMessage(event, payload);
+      }
+    };
+
+    const refLog = channel.on("log", (payload) => handleEvent("log", payload));
+    const refError = channel.on("error", (payload) =>
+      handleEvent("error", payload),
+    );
+    const refStream = channel.on("stream", (payload) =>
+      handleEvent("stream", payload),
+    );
+
+    channel
+      .join()
+      .receive("ok", () => {
+        if (typeof onChannelJoined === "function") onChannelJoined();
+      })
+      .receive("error", () => {});
+
+    return () => {
+      channel.off("log", refLog);
+      channel.off("error", refError);
+      channel.off("stream", refStream);
+      channelRef.current = null;
+      channel.leave();
+    };
+  }, [socketReady, conversationId, onChannelJoined, onServerMessage]);
+
+  const sendPrompt = useCallback(
+    (prompt) => {
+      if (
+        !socketReady ||
+        !channelRef.current ||
+        !prompt ||
+        typeof prompt !== "string"
+      )
+        return;
+      const trimmed = prompt.trim();
+      if (!trimmed) return;
+      channelRef.current.push("prompt", { prompt: trimmed });
+    },
+    [socketReady],
+  );
+
+  return { socketReady, socketRef, sendPrompt };
+};
+
+export default useAssistantSocket;

package/src/components/index.js

@@ -1,3 +1,4 @@
 import AiRoutes from "./AiRoutes";
 import TranslationModal from "./TranslationModal";
-export { AiRoutes, TranslationModal };
+import Assistant from "./assistant/Assistant";
+export { AiRoutes, TranslationModal, Assistant };

package/src/styles/assistant.less

@@ -0,0 +1,353 @@
+.assistant-container {
+  position: fixed;
+  bottom: calc(1.5rem + 10px);
+  right: calc(1.5rem + 10px);
+  z-index: 1000;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
+  transition:
+    width 0.3s ease,
+    height 0.3s ease,
+    border-radius 0.3s ease,
+    background 0.2s ease 0s,
+    color 0.2s ease 0s;
+
+  &--closed {
+    width: 5rem;
+    height: 5rem;
+    border-radius: 50%;
+    align-items: center;
+    justify-content: center;
+    background: #fff;
+    color: #013c54;
+    border: 2px solid #013c54;
+    cursor: pointer;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
+    transition:
+      width 0.3s ease,
+      height 0.3s ease,
+      border-radius 0.3s ease,
+      box-shadow 0.3s ease,
+      background 0.2s ease 0.3s,
+      color 0.2s ease 0.3s;
+
+    &:hover {
+      animation: assistant-aurora-halo 0.65s ease-in 1 forwards;
+      width: 5.15rem;
+      height: 5.15rem;
+    }
+  }
+
+  &--open {
+    width: 33vw;
+    min-width: 400px;
+    height: 80vh;
+    border-radius: 1rem;
+    background: #fff;
+    color: inherit;
+    transition:
+      width 0.3s ease,
+      height 0.3s ease,
+      border-radius 0.3s ease,
+      background 0.2s ease 0s,
+      color 0.2s ease 0s;
+  }
+}
+
+.assistant-content--fade-out {
+  opacity: 0;
+  transition: opacity 0.15s ease-out;
+}
+
+.assistant-content--fade-in {
+  opacity: 0;
+  animation: assistant-fade-in 0.15s ease-out forwards;
+}
+
+@keyframes assistant-fade-in {
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes assistant-aurora-halo {
+  0% {
+    box-shadow:
+      0 0 0 rgba(1, 60, 84, 0),
+      0 0 0 rgba(1, 60, 84, 0),
+      0 2px 8px rgba(0, 0, 0, 0.2);
+  }
+  20% {
+    box-shadow:
+      8px 0 14px rgba(1, 60, 84, 0.55),
+      0 0 22px rgba(1, 60, 84, 0.2),
+      0 2px 8px rgba(0, 0, 0, 0.2);
+  }
+  40% {
+    box-shadow:
+      0 8px 14px rgba(1, 60, 84, 0.55),
+      0 0 22px rgba(1, 60, 84, 0.2),
+      0 2px 8px rgba(0, 0, 0, 0.2);
+  }
+  60% {
+    box-shadow:
+      -8px 0 14px rgba(1, 60, 84, 0.55),
+      0 0 22px rgba(1, 60, 84, 0.2),
+      0 2px 8px rgba(0, 0, 0, 0.2);
+  }
+  80% {
+    box-shadow:
+      0 -8px 14px rgba(1, 60, 84, 0.55),
+      0 0 22px rgba(1, 60, 84, 0.2),
+      0 2px 8px rgba(0, 0, 0, 0.2);
+  }
+  100% {
+    box-shadow:
+      0 0 18px rgba(1, 60, 84, 0.75),
+      0 0 28px rgba(1, 60, 84, 0.4),
+      0 2px 8px rgba(0, 0, 0, 0.2);
+  }
+}
+
+.assistant-bubble {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  transition: opacity 0.15s ease-out;
+
+  .ui.icon {
+    margin: 0;
+    font-size: 1.5rem;
+  }
+
+  &__logo {
+    display: block;
+    width: 70%;
+    height: 70%;
+    object-fit: contain;
+  }
+}
+
+.assistant-chat {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+
+  &__actions {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+    padding: 0.75rem 1rem;
+    background: #013c54;
+    color: #fff;
+  }
+
+  &__action {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35rem;
+    padding: 0;
+    border: none;
+    border-radius: 0.25rem;
+    background: transparent;
+    color: inherit;
+    font-size: 0.875rem;
+    cursor: pointer;
+
+    .ui.icon {
+      margin: 0;
+    }
+
+    &--new-chat {
+      font-weight: 600;
+      cursor: default;
+    }
+
+    &--close {
+      margin-left: auto;
+      padding: 0.25rem;
+      width: 2rem;
+      height: 2rem;
+      border-radius: 999px;
+      background: transparent;
+
+      &:hover,
+      &:focus,
+      &:active {
+        background: transparent;
+      }
+    }
+  }
+
+  &__topic {
+    font-size: 0.75rem;
+    color: rgba(0, 0, 0, 0.5);
+    font-family: monospace;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 12rem;
+  }
+
+  &__messages-wrapper {
+    position: relative;
+    flex: 1;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+  }
+
+  &__messages {
+    flex: 1;
+    padding: 1rem;
+    overflow: auto;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+
+  &__scroll-to-bottom {
+    position: absolute;
+    bottom: 1rem;
+    right: 1rem;
+    width: 2.25rem;
+    height: 2.25rem;
+    padding: 0;
+    border: none;
+    border-radius: 50%;
+    background: #2185d0;
+    color: #fff;
+    cursor: pointer;
+    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.2);
+    z-index: 1;
+
+    .ui.icon {
+      margin: 0;
+      font-size: 1.125rem;
+    }
+
+    &:hover {
+      background: #1678c2;
+    }
+  }
+
+  &__message {
+    max-width: 85%;
+    padding: 0.4rem 0.75rem;
+    border-radius: 1rem;
+    font-size: 0.875rem;
+    line-height: 1.4;
+    word-break: break-word;
+
+    &--user {
+      align-self: flex-end;
+    }
+
+    &--agent {
+      align-self: flex-start;
+    }
+
+    &--request {
+      background: #ed5c17;
+      color: #fff;
+    }
+
+    &--response {
+      background: #e8e8e8;
+      color: #333;
+    }
+
+    &--log {
+      background: transparent;
+      color: #666;
+      font-style: italic;
+      font-size: 0.8125rem;
+    }
+  }
+
+  &__message-content {
+
+    .markdown-reader {
+      h1 {
+        font-size: 1.05rem;
+      }
+
+      h2 {
+        font-size: 1rem;
+      }
+
+      h3 {
+        font-size: 0.95rem;
+      }
+
+      h4,
+      h5,
+      h6 {
+        font-size: 0.9rem;
+      }
+    }
+  }
+
+  &__input-row {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.35rem 0.5rem;
+    border-radius: 999px;
+    background: #f4f6f8;
+  }
+
+  &__input {
+    flex: 1;
+    padding: 0.35rem 0.75rem;
+    border: none;
+    border-radius: 999px;
+    background: transparent;
+    font-size: 0.875rem;
+    outline: none;
+
+    &:focus {
+      border-color: #2185d0;
+    }
+  }
+
+  &__send {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.25rem;
+    height: 2.25rem;
+    padding: 0;
+    border: none;
+    border-radius: 999px;
+    background: #013c54;
+    color: #fff;
+    cursor: pointer;
+
+    .ui.icon {
+      margin: 0;
+    }
+  }
+
+  &__footer {
+    padding: 0.75rem 1rem 1rem;
+    border-top: 1px solid rgba(0, 0, 0, 0.06);
+    background: #fff;
+  }
+
+  &__disclaimer {
+    margin-top: 0.5rem;
+    font-size: 0.75rem;
+    color: #8e8e8e;
+    text-align: center;
+  }
+}