@truedat/ai 8.8.7 → 8.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truedat/ai",
-  "version": "8.8.7",
+  "version": "8.9.0",
   "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.8.7",
+    "@truedat/test": "8.9.0",
     "identity-obj-proxy": "^3.0.0",
     "jest": "^29.7.0",
     "redux-saga-test-plan": "^4.0.6"
@@ -80,5 +80,5 @@
     "semantic-ui-react": "^3.0.0-beta.2",
     "swr": "^2.3.3"
   },
-  "gitHead": "ece3f2e166776ff7827198a134bad5a28b029dc7"
+  "gitHead": "beff9d7e01556d63d42e54c9f7b641503ee658b2"
 }

package/src/api.js

@@ -10,9 +10,6 @@ const API_PROMPT_SET_ACTIVE = "/api/prompts/:id/set_active";
 const API_PROVIDERS = "/api/providers";
 const API_PROVIDER = "/api/providers/:id";
 const API_PROVIDER_CHAT = "/api/providers/:id/chat_completion";
-const API_SUGGESTIONS_AVAILABILITY_CHECK =
-  "/api/suggestions/availability_check";
-const API_SUGGESTIONS_REQUEST = "/api/suggestions/request";
 const API_TRANSLATIONS_AVAILABILITY_CHECK =
   "/api/translations/availability_check";
 const API_TRANSLATIONS_REQUEST = "/api/translations/request";
@@ -35,8 +32,6 @@ export {
   API_PROVIDERS,
   API_PROVIDER,
   API_PROVIDER_CHAT,
-  API_SUGGESTIONS_AVAILABILITY_CHECK,
-  API_SUGGESTIONS_REQUEST,
   API_TRANSLATIONS_AVAILABILITY_CHECK,
   API_TRANSLATIONS_REQUEST,
   API_AGENT_LAYER_CONVERSATION,

package/src/components/suggestions/SuggestionsWidget.js

@@ -1,31 +1,98 @@
 import _ from "lodash/fp";
-import { useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import {
   Button,
   Checkbox,
   Container,
   Divider,
+  Form,
   Icon,
   List,
   Message,
   Segment,
   Popup,
 } from "semantic-ui-react";
-import { FormattedMessage } from "react-intl";
+import { FormattedMessage, useIntl } from "react-intl";
+import { MarkdownReader } from "@truedat/core/components";
+import { useWebContext } from "@truedat/core/webContext";
+import { useAgentLayerRun } from "../../hooks/useAgentLayerRun";
+import { useAvailabilityCheck } from "../../hooks/useSuggestions";
+import useAssistantSocket from "../assistant/hooks/useAssistantSocket";
+import ThinkingOutLoud from "../ThinkingOutLoud";
+
+const parseStreamResult = (content) => {
+  try {
+    const raw = typeof content === "string" ? JSON.parse(content) : content;
+    return raw?.result ?? raw ?? {};
+  } catch {
+    return {};
+  }
+};
+
+const formatLogContent = (log) =>
+  log && typeof log === "object"
+    ? (log.message ?? log.level ?? JSON.stringify(log))
+    : String(log ?? "");
+
+const formatErrorContent = (err) =>
+  err && typeof err === "object"
+    ? (err.message ?? err.reason ?? JSON.stringify(err))
+    : String(err ?? "");
 
 export default function SuggestionsWidget({
-  requestAiSuggestion,
+  suggestionParams,
   applySuggestions,
   template,
   isModification,
   enableRequestButton = true,
   disabledButtonMessage = "",
 }) {
-  const [loadingSuggestion, setLoadingSuggestion] = useState();
+  const { formatMessage } = useIntl();
+
+  const [requested, setRequested] = useState(false);
+  const [promptPopupOpen, setPromptPopupOpen] = useState(false);
+  const [prompt, setPrompt] = useState("");
   const [suggestions, setSuggestions] = useState();
   const [suggestionsError, setSuggestionsError] = useState();
   const [selectedSuggestions, setSelectedSuggestions] = useState([]);
+  const [logItems, setLogItems] = useState([]);
+
+  const { disable_td_ai } = useWebContext();
+  const { trigger: checkAvailability } = useAvailabilityCheck();
+  const availabilityRequestId = useRef(0);
+  const [available, setAvailable] = useState(false);
+
+  const availabilityTemplateId = suggestionParams?.template_id;
+  const availabilityResourceType = suggestionParams?.resource_type;
+  const availabilityDomainIds = suggestionParams?.domain_ids;
+  const availabilityDomainKey = JSON.stringify(availabilityDomainIds ?? []);
+
+  useEffect(() => {
+    if (disable_td_ai || !availabilityTemplateId) {
+      setAvailable(false);
+      return;
+    }
+    // Only apply the latest response; params can change while a check is pending.
+    availabilityRequestId.current += 1;
+    const requestId = availabilityRequestId.current;
+    setAvailable(false);
+    checkAvailability({
+      template_id: availabilityTemplateId,
+      domain_ids: availabilityDomainIds || [],
+      resource_type: availabilityResourceType,
+    }).then((res) => {
+      if (availabilityRequestId.current === requestId) {
+        setAvailable(res.available);
+      }
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    disable_td_ai,
+    availabilityTemplateId,
+    availabilityResourceType,
+    availabilityDomainKey,
+  ]);
 
   const suggestionKeys = _.keys(suggestions);
   const fieldInSuggestions = ({ name }) => _.includes(name)(suggestionKeys);
@@ -49,33 +116,82 @@ export default function SuggestionsWidget({
   )(template);
 
   const validFields = _.keys(fieldTypes);
+  // Keeps handleServerMessage's identity stable (see below) while still
+  // reading the latest validFields when a stream result arrives.
+  const validFieldsRef = useRef(validFields);
+  validFieldsRef.current = validFields;
 
-  const handleRequestSuggestions = () => {
-    setLoadingSuggestion(true);
-    setSuggestionsError(null);
-    setSelectedSuggestions([]);
-    setSuggestions(null);
+  const { trigger: fetchSuggestions, data: runData } = useAgentLayerRun();
+  const agentStateId = runData?.data?.data?.agent_state_id
+    ? String(runData.data.data.agent_state_id)
+    : null;
+
+  const handleServerMessage = useCallback((event, payload) => {
+    const priority = payload?.priority ?? null;
 
-    requestAiSuggestion(({ data: { data: suggestions } }) => {
-      if (_.prop("[0]")(suggestions) === "error") {
-        setSuggestionsError(
-          _.prop("[1].error.message")(suggestions) ||
-            _.prop("[1]")(suggestions),
-        );
-      } else {
-        setSuggestions(suggestions);
-        const selectedFields = _.flow(
+    if (event === "stream" && Number(priority) === 0) {
+      const parsed = parseStreamResult(payload?.content);
+      setSuggestions(parsed);
+      setSelectedSuggestions(
+        _.flow(
           _.keys,
           _.filter(
             (key) =>
-              _.includes(key)(validFields) && !_.isEmpty(suggestions[key]),
+              _.includes(key)(validFieldsRef.current) &&
+              !_.isEmpty(parsed[key]),
           ),
-        )(suggestions);
-        setSelectedSuggestions(selectedFields);
-      }
-      setLoadingSuggestion(false);
+        )(parsed),
+      );
+      return;
+    }
+
+    if (event === "error" && Number(priority) !== 2) {
+      setSuggestionsError(formatErrorContent(payload?.error));
+      return;
+    }
+
+    if (event === "log" || (event === "error" && Number(priority) === 2)) {
+      const source = payload?.source ?? null;
+      const content =
+        event === "log"
+          ? formatLogContent(payload?.content)
+          : formatErrorContent(payload?.error);
+
+      setLogItems((prev) => [
+        ...prev,
+        { eventType: event, content: content || " ", priority, source },
+      ]);
+    }
+  }, []);
+
+  useAssistantSocket(!agentStateId, {
+    conversationId: agentStateId,
+    onServerMessage: handleServerMessage,
+  });
+
+  const inProgress = requested && !suggestions && !suggestionsError;
+  const requestDisabled = !enableRequestButton || inProgress;
+
+  const resetState = () => {
+    setRequested(false);
+    setSuggestions(null);
+    setSuggestionsError(null);
+    setSelectedSuggestions([]);
+    setLogItems([]);
+  };
+
+  const handleRequestSuggestions = (requestPrompt) => {
+    setSuggestionsError(null);
+    setSelectedSuggestions([]);
+    setSuggestions(null);
+    setLogItems([]);
+    setRequested(true);
+    fetchSuggestions({
+      workflow: "suggest_content",
+      params: { ...suggestionParams, prompt: requestPrompt },
     });
   };
+
   const handleApplySuggestions = () => {
     _.flow(
       _.pick(selectedSuggestions),
@@ -91,8 +207,7 @@ export default function SuggestionsWidget({
       applySuggestions,
     )(suggestions);
 
-    setSelectedSuggestions([]);
-    setSuggestions(null);
+    resetState();
   };
 
   const toggleSelectedSuggestion = (name) => {
@@ -103,8 +218,66 @@ export default function SuggestionsWidget({
     );
   };
 
+  const renderRequestControl = () => {
+    if (!enableRequestButton && disabledButtonMessage) {
+      return (
+        <Popup
+          content={disabledButtonMessage}
+          trigger={
+            <span>
+              <Button disabled>
+                <FormattedMessage id="actions.ai_suggestion" />
+              </Button>
+            </span>
+          }
+        />
+      );
+    }
+    return (
+      <Popup
+        on="click"
+        open={promptPopupOpen}
+        onOpen={() => setPromptPopupOpen(true)}
+        onClose={() => setPromptPopupOpen(false)}
+        disabled={requestDisabled}
+        content={
+          <Form style={{ minWidth: "300px" }}>
+            <Form.Field>
+              <label>{formatMessage({ id: "suggestions.prompt.label" })}</label>
+              <Form.Input
+                value={prompt}
+                onChange={(_e, { value }) => setPrompt(value)}
+                placeholder={formatMessage({
+                  id: "suggestions.prompt.placeholder",
+                })}
+              />
+            </Form.Field>
+            <Button
+              primary
+              content={formatMessage({ id: "suggestions.prompt.submit" })}
+              onClick={() => {
+                setPromptPopupOpen(false);
+                handleRequestSuggestions(prompt);
+              }}
+            />
+          </Form>
+        }
+        position="bottom center"
+        trigger={
+          <span>
+            <Button disabled={requestDisabled}>
+              <FormattedMessage id="actions.ai_suggestion" />
+            </Button>
+          </span>
+        }
+      />
+    );
+  };
+
+  if (!available) return null;
+
   return (
-    <Segment loading={loadingSuggestion}>
+    <Segment>
       <Container style={{ display: "flex", justifyContent: "space-between" }}>
         <h4>
           {suggestions ? (
@@ -115,33 +288,27 @@ export default function SuggestionsWidget({
           <FormattedMessage id="structure_note.ai_suggestion.header" />
         </h4>
         <Divider hidden />
-        {suggestions ? null : !enableRequestButton && disabledButtonMessage ? (
-          <Popup
-            content={disabledButtonMessage}
-            trigger={
-              <span>
-                <Button onClick={handleRequestSuggestions} disabled>
-                  <FormattedMessage id="actions.ai_suggestion" />
-                </Button>
-              </span>
-            }
-          />
-        ) : (
-          <Button
-            onClick={handleRequestSuggestions}
-            disabled={!enableRequestButton}
-          >
-            <FormattedMessage id="actions.ai_suggestion" />
-          </Button>
-        )}
+        {renderRequestControl()}
       </Container>
       {suggestionsError ? (
-        <Message negative>
-          <Message.Header>
-            <FormattedMessage id="structure_note.ai_suggestion.error" />
-          </Message.Header>
-          <p>{suggestionsError}</p>
-        </Message>
+        <>
+          <Message negative>
+            <Message.Header>
+              <FormattedMessage id="structure_note.ai_suggestion.error" />
+            </Message.Header>
+            <p>{suggestionsError}</p>
+          </Message>
+          <Container textAlign="right">
+            <Button basic onClick={resetState}>
+              <FormattedMessage id="actions.discard_ai_suggestion" />
+            </Button>
+          </Container>
+        </>
+      ) : null}
+      {inProgress ? (
+        <Segment loading={logItems.length === 0} basic>
+          <ThinkingOutLoud items={logItems} active />
+        </Segment>
       ) : null}
       {suggestions ? (
         <>
@@ -150,12 +317,12 @@ export default function SuggestionsWidget({
               <>
                 <h5>{groupName ? groupName : ""}</h5>
                 <List>
-                  {_.map(({ name, label, editable = true }) => (
+                  {_.map(({ name, label, editable = true, widget }) => (
                     <List.Item
                       key={name}
                       style={{
                         display: "flex",
-                        alignItems: "center",
+                        alignItems: "flex-start",
                         gap: "12px",
                       }}
                     >
@@ -175,9 +342,13 @@ export default function SuggestionsWidget({
                       >
                         <List.Header>{label}</List.Header>
                         <List.Description>
-                          {_.isEmpty(suggestions[name])
-                            ? "-"
-                            : suggestions[name]}
+                          {_.isEmpty(suggestions[name]) ? (
+                            "-"
+                          ) : widget === "markdown" ? (
+                            <MarkdownReader content={suggestions[name]} />
+                          ) : (
+                            suggestions[name]
+                          )}
                         </List.Description>
                       </label>
                     </List.Item>
@@ -188,6 +359,13 @@ export default function SuggestionsWidget({
             </Container>
           ))(templateFields)}
           <Container textAlign="right">
+            <Button
+              className="td-icon-text-control"
+              secondary
+              onClick={resetState}
+            >
+              <FormattedMessage id="actions.discard_ai_suggestion" />
+            </Button>
             <Button
               primary
               onClick={handleApplySuggestions}
@@ -203,7 +381,7 @@ export default function SuggestionsWidget({
 }
 
 SuggestionsWidget.propTypes = {
-  requestAiSuggestion: PropTypes.func,
+  suggestionParams: PropTypes.object,
   applySuggestions: PropTypes.func,
   template: PropTypes.object,
   isModification: PropTypes.bool,

package/src/components/suggestions/__tests__/SuggestionsWidget.spec.js

@@ -1,153 +1,442 @@
-import { Suspense } from "react";
-import { waitFor } from "@testing-library/react";
+import { act, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { render } from "@truedat/test/render";
+import useAssistantSocket from "../../assistant/hooks/useAssistantSocket";
+import { useAgentLayerRun } from "../../../hooks/useAgentLayerRun";
+import { useAvailabilityCheck } from "../../../hooks/useSuggestions";
 import SuggestionsWidget from "../SuggestionsWidget";
 
-const mockSuggestions = {
-  editable_field: "editable_field_value",
-  non_editable_field: "non_editable_field_value",
-  unselect_field: "unselect_field_value",
-};
+jest.mock("../../assistant/hooks/useAssistantSocket", () => jest.fn());
+
+jest.mock("../../../hooks/useAgentLayerRun", () => ({
+  useAgentLayerRun: jest.fn(),
+}));
+
+jest.mock("../../../hooks/useSuggestions", () => ({
+  useAvailabilityCheck: jest.fn(),
+}));
+
+const mockCheckAvailability = jest.fn();
 
 const messages = {
   en: {
-    "actions.cancel": "cancel",
-    "actions.save": "save",
-    "structure_note.ai_suggestion.header": "header",
     "actions.apply_ai_suggestion": "actions.apply_ai_suggestion",
+    "actions.discard_ai_suggestion": "actions.discard_ai_suggestion",
     "actions.ai_suggestion": "actions.ai_suggestion",
+    "structure_note.ai_suggestion.header": "header",
     "structure_note.ai_suggestion.error": "error",
+    "suggestions.prompt.label": "suggestions.prompt.label",
+    "suggestions.prompt.placeholder": "suggestions.prompt.placeholder",
+    "suggestions.prompt.submit": "suggestions.prompt.submit",
   },
 };
 
-const requestAiSuggestion = (mock) => (callback) => {
-  callback({
-    data: {
-      data:
-        mock === "suggestions"
-          ? mockSuggestions
-          : mock === "error_message"
-            ? ["error", { error: { message: "ERROR MESSAGE" } }]
-            : ["error", "ERROR TEXT"],
+const template = {
+  content: [
+    {
+      fields: [
+        { name: "editable_field", label: "EditableField", editable: true },
+      ],
     },
-  });
+    {
+      name: "Group2",
+      fields: [
+        {
+          name: "non_editable_field",
+          label: "NonEditableField",
+          editable: false,
+        },
+        {
+          name: "unselect_field",
+          label: "UnselectedField",
+          editable: true,
+        },
+      ],
+    },
+  ],
+};
+
+const mockSuggestions = {
+  editable_field: "editable_field_value",
+  non_editable_field: "non_editable_field_value",
+  unselect_field: "unselect_field_value",
+};
+
+const user = userEvent.setup({ delay: null });
+
+const requestSuggestions = async (findByText) => {
+  await user.click(await findByText(/actions.ai_suggestion/i));
+  await user.click(await findByText(/suggestions.prompt.submit/i));
+};
+
+// Reads the onServerMessage callback the component most recently registered
+// with the mocked useAssistantSocket, instead of capturing it via a `let`.
+const emitServerMessage = (event, payload) => {
+  const [, options] = useAssistantSocket.mock.calls.at(-1);
+  act(() => options.onServerMessage(event, payload));
 };
 
 describe("<SuggestionsWidget />", () => {
-  it("matches the latest snapshot", () => {
+  const mockFetchSuggestions = jest.fn();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: null,
+    });
+    mockCheckAvailability.mockResolvedValue({ available: true });
+    useAvailabilityCheck.mockReturnValue({ trigger: mockCheckAvailability });
+  });
+
+  it("renders nothing when suggestions are not available", async () => {
+    mockCheckAvailability.mockResolvedValue({ available: false });
     const props = {
-      template: {},
-      requestAiSuggestion: requestAiSuggestion("suggestions"),
+      template,
+      suggestionParams: { template_id: 1, resource_type: "data_structure" },
     };
-    const { container } = render(
-      <Suspense fallback={null}>
-        <SuggestionsWidget {...props} />
-      </Suspense>,
+    const { queryByText } = render(<SuggestionsWidget {...props} />, {
+      messages,
+    });
+
+    await waitFor(() =>
+      expect(mockCheckAvailability).toHaveBeenCalledWith({
+        template_id: 1,
+        domain_ids: [],
+        resource_type: "data_structure",
+      }),
+    );
+    expect(queryByText(/actions.ai_suggestion/i)).not.toBeInTheDocument();
+  });
+
+  it("ignores a stale availability response when the params change", async () => {
+    const notAllowed = Promise.resolve({ available: false });
+    // template 1 is allowed but settles after template 2's "not allowed"
+    mockCheckAvailability
+      .mockReturnValueOnce(notAllowed.then(() => ({ available: true })))
+      .mockReturnValueOnce(notAllowed);
+
+    const { rerender, queryByText } = render(
+      <SuggestionsWidget
+        template={template}
+        suggestionParams={{ template_id: 1, resource_type: "data_structure" }}
+      />,
       { messages },
     );
-    expect(container).toMatchSnapshot();
+
+    rerender(
+      <SuggestionsWidget
+        template={template}
+        suggestionParams={{ template_id: 2, resource_type: "data_structure" }}
+      />,
+    );
+
+    // Flush both availability responses (incl. the late, stale "allowed" one).
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(queryByText(/actions.ai_suggestion/i)).not.toBeInTheDocument();
+  });
+
+  it("requests suggestions with suggestionParams and the entered prompt", async () => {
+    const props = { template, suggestionParams: { template_id: 7 } };
+    const { findByText } = render(<SuggestionsWidget {...props} />, {
+      messages,
+    });
+
+    await requestSuggestions(findByText);
+
+    await waitFor(() =>
+      expect(mockFetchSuggestions).toHaveBeenCalledWith({
+        workflow: "suggest_content",
+        params: { template_id: 7, prompt: "" },
+      }),
+    );
+  });
+
+  it("disables the request control when enableRequestButton is false", async () => {
+    const props = {
+      template,
+      suggestionParams: { template_id: 1 },
+      enableRequestButton: false,
+      disabledButtonMessage: "name required",
+    };
+    const { findByText } = render(<SuggestionsWidget {...props} />, {
+      messages,
+    });
+
+    const button = await findByText(/actions.ai_suggestion/i);
+    expect(button.closest("button")).toBeDisabled();
   });
 
-  it("component lifecycle", async () => {
+  it("shows a spinner and disables the request control once requested", async () => {
+    const props = { template, suggestionParams: { template_id: 1 } };
+    const { findByText, container } = render(<SuggestionsWidget {...props} />, {
+      messages,
+    });
+
+    await requestSuggestions(findByText);
+
+    await waitFor(() => {
+      const button = container.querySelector("button");
+      expect(button).toBeDisabled();
+      expect(container.querySelector(".segment.loading")).toBeInTheDocument();
+    });
+  });
+
+  it("connects the socket using the agent_state_id returned by the run", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
+    const props = { template, suggestionParams: { template_id: 1 } };
+    render(<SuggestionsWidget {...props} />, { messages });
+
+    expect(useAssistantSocket).toHaveBeenCalledWith(
+      false,
+      expect.objectContaining({ conversationId: "state-1" }),
+    );
+  });
+
+  it("renders selectable suggestions once a priority-0 stream event arrives", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
     const applySuggestions = jest.fn();
     const props = {
-      requestAiSuggestion: requestAiSuggestion("suggestions"),
+      template,
+      suggestionParams: { template_id: 1 },
       applySuggestions,
-      template: {
-        content: [
-          {
-            fields: [
-              {
-                name: "editable_field",
-                label: "EditableField",
-                editable: true,
-              },
-            ],
-          },
-          {
-            name: "Group2",
-            fields: [
-              {
-                name: "non_editable_field",
-                label: "NonEditableField",
-                editable: false,
-              },
-              {
-                name: "unselect_field",
-                label: "UnselectedField",
-                editable: true,
-              },
-            ],
-          },
-        ],
-      },
       isModification: true,
     };
-    const { container, findByText, queryByText } = render(
-      <Suspense fallback={null}>
-        <SuggestionsWidget {...props} />
-      </Suspense>,
+    const { findByText, queryByText } = render(
+      <SuggestionsWidget {...props} />,
       { messages },
     );
 
-    userEvent.click(await findByText(/actions.ai_suggestion/i));
+    emitServerMessage("stream", {
+      priority: 0,
+      content: JSON.stringify({ result: mockSuggestions }),
+    });
+
     await waitFor(() =>
-      expect(queryByText(/actions.ai_suggestion/i)).not.toBeInTheDocument(),
+      // exact text: a regex match here would also match "NonEditableField"
+      expect(queryByText("EditableField")).toBeInTheDocument(),
     );
 
-    expect(container).toMatchSnapshot();
+    await user.click(await findByText("UnselectedField"));
+    await user.click(await findByText("UnselectedField"));
+    await user.click(await findByText("UnselectedField"));
 
-    userEvent.click(await findByText(/UnselectedField/i));
-    userEvent.click(await findByText(/UnselectedField/i));
-    userEvent.click(await findByText(/UnselectedField/i));
+    await user.click(await findByText(/actions.apply_ai_suggestion/i));
 
-    userEvent.click(await findByText(/actions.apply_ai_suggestion/i));
-    await waitFor(() =>
-      expect(
-        queryByText(/actions.apply_ai_suggestion/i),
-      ).not.toBeInTheDocument(),
-    );
     expect(applySuggestions).toHaveBeenCalledWith(
       expect.objectContaining({
         editable_field: { origin: "ai", value: "editable_field_value" },
       }),
     );
+  });
+
+  it("renders markdown suggestion values with the markdown reader", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
 
-    expect(container).toMatchSnapshot();
+    const markdownTemplate = {
+      content: [
+        {
+          fields: [
+            {
+              name: "rich_field",
+              label: "RichField",
+              editable: true,
+              widget: "markdown",
+            },
+          ],
+        },
+      ],
+    };
+    const props = {
+      template: markdownTemplate,
+      suggestionParams: { template_id: 1 },
+    };
+    const { container, queryByText } = render(
+      <SuggestionsWidget {...props} />,
+      {
+        messages,
+      },
+    );
+
+    emitServerMessage("stream", {
+      priority: 0,
+      content: JSON.stringify({ result: { rich_field: "# Heading\n\nbody" } }),
+    });
+
+    await waitFor(() =>
+      expect(container.querySelector(".markdown-reader")).toBeInTheDocument(),
+    );
+    // rendered as HTML, so the raw markdown source is not present as text
+    expect(queryByText("# Heading")).not.toBeInTheDocument();
   });
 
-  it("renders error with message", async () => {
+  it("returns to the request state after applying suggestions", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
     const props = {
-      requestAiSuggestion: requestAiSuggestion("error_message"),
+      template,
+      suggestionParams: { template_id: 1 },
+      applySuggestions: jest.fn(),
     };
-    const { container, findByText, queryByText } = render(
-      <Suspense fallback={null}>
-        <SuggestionsWidget {...props} />
-      </Suspense>,
+    const { findByText, queryByText } = render(
+      <SuggestionsWidget {...props} />,
+      { messages },
+    );
+
+    emitServerMessage("stream", {
+      priority: 0,
+      content: JSON.stringify({ result: mockSuggestions }),
+    });
+    await waitFor(() =>
+      expect(queryByText("EditableField")).toBeInTheDocument(),
+    );
+
+    await user.click(await findByText(/actions.apply_ai_suggestion/i));
+
+    await waitFor(() =>
+      expect(queryByText("EditableField")).not.toBeInTheDocument(),
+    );
+    const requestButton = (await findByText(/actions.ai_suggestion/i)).closest(
+      "button",
+    );
+    expect(requestButton).not.toBeDisabled();
+  });
+
+  it("discards the suggestions and returns to the request state", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
+    const props = { template, suggestionParams: { template_id: 1 } };
+    const { findByText, queryByText } = render(
+      <SuggestionsWidget {...props} />,
+      { messages },
+    );
+
+    emitServerMessage("stream", {
+      priority: 0,
+      content: JSON.stringify({ result: mockSuggestions }),
+    });
+    await waitFor(() =>
+      expect(queryByText("EditableField")).toBeInTheDocument(),
+    );
+
+    await user.click(await findByText(/actions.discard_ai_suggestion/i));
+
+    await waitFor(() =>
+      expect(queryByText("EditableField")).not.toBeInTheDocument(),
+    );
+    expect(queryByText(/actions.apply_ai_suggestion/i)).not.toBeInTheDocument();
+  });
+
+  it("dismisses an error and returns to the request state", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
+    const props = { template, suggestionParams: { template_id: 1 } };
+    const { findByText, queryByText } = render(
+      <SuggestionsWidget {...props} />,
+      { messages },
+    );
+
+    await requestSuggestions(findByText);
+    emitServerMessage("error", { priority: 0, error: "ERROR TEXT" });
+    await waitFor(() => expect(queryByText(/ERROR TEXT/i)).toBeInTheDocument());
+
+    await user.click(await findByText(/actions.discard_ai_suggestion/i));
+
+    await waitFor(() =>
+      expect(queryByText(/ERROR TEXT/i)).not.toBeInTheDocument(),
+    );
+  });
+
+  it("shows ThinkingOutLoud-driven log items while the agent is reasoning", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
+    const props = { template, suggestionParams: { template_id: 1 } };
+    const { findByText, queryByText } = render(
+      <SuggestionsWidget {...props} />,
+      { messages },
+    );
+
+    await requestSuggestions(findByText);
+
+    emitServerMessage("log", {
+      priority: 1,
+      source: "agent_x",
+      content: "Processing...",
+    });
+
+    await waitFor(() =>
+      expect(queryByText(/Processing.../i)).toBeInTheDocument(),
+    );
+  });
+
+  it("renders error with message", async () => {
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
+    const props = { template, suggestionParams: { template_id: 1 } };
+    const { findByText, queryByText } = render(
+      <SuggestionsWidget {...props} />,
       { messages },
     );
 
-    userEvent.click(await findByText(/actions.ai_suggestion/i));
+    await requestSuggestions(findByText);
+
+    emitServerMessage("error", {
+      priority: 0,
+      error: { message: "ERROR MESSAGE" },
+    });
+
     await waitFor(() =>
-      expect(queryByText(/error message/i)).toBeInTheDocument(),
+      expect(queryByText(/ERROR MESSAGE/i)).toBeInTheDocument(),
     );
-    expect(container).toMatchSnapshot();
   });
 
   it("renders error with text", async () => {
-    const props = {
-      requestAiSuggestion: requestAiSuggestion("error_text"),
-    };
-    const { container, findByText, queryByText } = render(
-      <Suspense fallback={null}>
-        <SuggestionsWidget {...props} />
-      </Suspense>,
+    useAgentLayerRun.mockReturnValue({
+      trigger: mockFetchSuggestions,
+      data: { data: { data: { agent_state_id: "state-1" } } },
+    });
+
+    const props = { template, suggestionParams: { template_id: 1 } };
+    const { findByText, queryByText } = render(
+      <SuggestionsWidget {...props} />,
       { messages },
     );
 
-    userEvent.click(await findByText(/actions.ai_suggestion/i));
-    await waitFor(() => expect(queryByText(/error text/i)).toBeInTheDocument());
-    expect(container).toMatchSnapshot();
+    await requestSuggestions(findByText);
+
+    emitServerMessage("error", { priority: 0, error: "ERROR TEXT" });
+
+    await waitFor(() => expect(queryByText(/ERROR TEXT/i)).toBeInTheDocument());
   });
 });

package/src/hooks/__mocks__/useSuggestions.js

@@ -1,5 +1,5 @@
 export const useAvailabilityCheck = jest.fn(() => ({
   trigger: () => ({
-    then: () => ({ data: { data: { status: "ok" } } }),
+    then: () => ({ available: true }),
   }),
 }));

package/src/hooks/useSuggestions.js

@@ -1,9 +1,17 @@
+import _ from "lodash/fp";
 import useSWRMutations from "swr/mutation";
-import { apiJsonPost } from "@truedat/core/services/api";
-import { API_SUGGESTIONS_AVAILABILITY_CHECK } from "../api";
+import { apiJsonOptions } from "@truedat/core/services/api";
+import { API_AGENT_LAYER_RUN } from "../api";
 
-export const useAvailabilityCheck = () => {
-  return useSWRMutations(API_SUGGESTIONS_AVAILABILITY_CHECK, (url, { arg }) =>
-    apiJsonPost(url, arg),
+// The suggestion availability gate is an OPTIONS request: the backend answers
+// with an `Allow` header listing the methods enabled for the caller. POST being
+// allowed means the "AI suggest content" button should be shown.
+const isPostAllowed = ({ headers }) =>
+  _.includes("POST")(_.getOr("", "allow", headers));
+
+export const useAvailabilityCheck = () =>
+  useSWRMutations(API_AGENT_LAYER_RUN, (url, { arg }) =>
+    apiJsonOptions(url, {
+      params: { workflow: "suggest_content", ...arg },
+    }).then((res) => ({ available: isPostAllowed(res) })),
   );
-};

package/src/components/suggestions/__tests__/__snapshots__/SuggestionsWidget.spec.js.snap

@@ -1,313 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`<SuggestionsWidget /> component lifecycle 1`] = `
-<div>
-  <div
-    class="ui segment"
-  >
-    <div
-      class="ui container"
-      style="display: flex; justify-content: space-between;"
-    >
-      <h4>
-        <i
-          aria-hidden="true"
-          class="lightbulb outline icon"
-        />
-        header
-      </h4>
-      <div
-        class="ui hidden divider"
-      />
-    </div>
-    <div
-      class="ui container"
-    >
-      <h5 />
-      <div
-        class="ui list"
-        role="list"
-      >
-        <div
-          class="item"
-          role="listitem"
-          style="display: flex; align-items: center; gap: 12px;"
-        >
-          <div
-            class="ui checked fitted checkbox"
-          >
-            <input
-              checked=""
-              class="hidden"
-              id="editable_field"
-              readonly=""
-              tabindex="0"
-              type="checkbox"
-            />
-            <label
-              for="editable_field"
-            />
-          </div>
-          <label
-            disabled=""
-            for="editable_field"
-            style="cursor: pointer;"
-          >
-            <div
-              class="header"
-            >
-              EditableField
-            </div>
-            <div
-              class="description"
-            >
-              editable_field_value
-            </div>
-          </label>
-        </div>
-      </div>
-      <div
-        class="ui hidden divider"
-      />
-    </div>
-    <div
-      class="ui container"
-    >
-      <h5>
-        Group2
-      </h5>
-      <div
-        class="ui list"
-        role="list"
-      >
-        <div
-          class="item"
-          role="listitem"
-          style="display: flex; align-items: center; gap: 12px;"
-        >
-          <div
-            class="ui disabled fitted checkbox"
-          >
-            <input
-              class="hidden"
-              disabled=""
-              id="non_editable_field"
-              readonly=""
-              tabindex="-1"
-              type="checkbox"
-            />
-            <label
-              for="non_editable_field"
-            />
-          </div>
-          <label
-            disabled=""
-            for="non_editable_field"
-            style="cursor: pointer;"
-          >
-            <div
-              class="header"
-            >
-              NonEditableField
-            </div>
-            <div
-              class="description"
-            >
-              non_editable_field_value
-            </div>
-          </label>
-        </div>
-        <div
-          class="item"
-          role="listitem"
-          style="display: flex; align-items: center; gap: 12px;"
-        >
-          <div
-            class="ui checked fitted checkbox"
-          >
-            <input
-              checked=""
-              class="hidden"
-              id="unselect_field"
-              readonly=""
-              tabindex="0"
-              type="checkbox"
-            />
-            <label
-              for="unselect_field"
-            />
-          </div>
-          <label
-            disabled=""
-            for="unselect_field"
-            style="cursor: pointer;"
-          >
-            <div
-              class="header"
-            >
-              UnselectedField
-            </div>
-            <div
-              class="description"
-            >
-              unselect_field_value
-            </div>
-          </label>
-        </div>
-      </div>
-      <div
-        class="ui hidden divider"
-      />
-    </div>
-    <div
-      class="ui right aligned container"
-    >
-      <button
-        class="ui primary button"
-      >
-        actions.apply_ai_suggestion
-      </button>
-    </div>
-  </div>
-</div>
-`;
-
-exports[`<SuggestionsWidget /> component lifecycle 2`] = `
-<div>
-  <div
-    class="ui segment"
-  >
-    <div
-      class="ui container"
-      style="display: flex; justify-content: space-between;"
-    >
-      <h4>
-        <i
-          aria-hidden="true"
-          class="lightbulb icon"
-        />
-        header
-      </h4>
-      <div
-        class="ui hidden divider"
-      />
-      <button
-        class="ui button"
-      >
-        actions.ai_suggestion
-      </button>
-    </div>
-  </div>
-</div>
-`;
-
-exports[`<SuggestionsWidget /> matches the latest snapshot 1`] = `
-<div>
-  <div
-    class="ui segment"
-  >
-    <div
-      class="ui container"
-      style="display: flex; justify-content: space-between;"
-    >
-      <h4>
-        <i
-          aria-hidden="true"
-          class="lightbulb icon"
-        />
-        header
-      </h4>
-      <div
-        class="ui hidden divider"
-      />
-      <button
-        class="ui button"
-      >
-        actions.ai_suggestion
-      </button>
-    </div>
-  </div>
-</div>
-`;
-
-exports[`<SuggestionsWidget /> renders error with message 1`] = `
-<div>
-  <div
-    class="ui segment"
-  >
-    <div
-      class="ui container"
-      style="display: flex; justify-content: space-between;"
-    >
-      <h4>
-        <i
-          aria-hidden="true"
-          class="lightbulb icon"
-        />
-        header
-      </h4>
-      <div
-        class="ui hidden divider"
-      />
-      <button
-        class="ui button"
-      >
-        actions.ai_suggestion
-      </button>
-    </div>
-    <div
-      class="ui negative message"
-    >
-      <div
-        class="header"
-      >
-        error
-      </div>
-      <p>
-        ERROR MESSAGE
-      </p>
-    </div>
-  </div>
-</div>
-`;
-
-exports[`<SuggestionsWidget /> renders error with text 1`] = `
-<div>
-  <div
-    class="ui segment"
-  >
-    <div
-      class="ui container"
-      style="display: flex; justify-content: space-between;"
-    >
-      <h4>
-        <i
-          aria-hidden="true"
-          class="lightbulb icon"
-        />
-        header
-      </h4>
-      <div
-        class="ui hidden divider"
-      />
-      <button
-        class="ui button"
-      >
-        actions.ai_suggestion
-      </button>
-    </div>
-    <div
-      class="ui negative message"
-    >
-      <div
-        class="header"
-      >
-        error
-      </div>
-      <p>
-        ERROR TEXT
-      </p>
-    </div>
-  </div>
-</div>
-`;