@artooi/ag-ui-web-component 0.28.0 → 0.29.0

package/src/constants.ts

@@ -54,6 +54,71 @@ export const ATTACHMENT_EVENT = "ag-ui-attachments";
  */
 export const RUN_FINISHED_EVENT = "ag-ui-run-finished";
 
+/**
+ * The agent sent an AG-UI `CUSTOM` event. `detail` is {@link CustomAgentDetail}.
+ *
+ * `CUSTOM` is one of exactly two carriers whose payload name the protocol leaves
+ * an open string, and it is the **imperative** one: something for the host page
+ * to *do*, with no place in the transcript. Its sibling `ACTIVITY_SNAPSHOT`
+ * carries transcript **content**, which is why that one is materialised into a
+ * message, persisted, and replayed on restore while this one is not.
+ *
+ * That asymmetry is the rule for choosing between them. Content has a place in
+ * the conversation and should replay; an imperative has no place and no meaning
+ * once acted on, so replaying it on a thread load would be a bug. Anything that
+ * must survive a reload belongs on the other carrier.
+ *
+ * The element takes no view of what a name means -- it forwards every one. A
+ * host that does not recognise a name ignores the event, which is the graceful
+ * outcome the open field exists for.
+ */
+export const CUSTOM_AGENT_EVENT = "ag-ui-custom";
+
+/**
+ * The agent named resources its write has moved. `detail` is
+ * {@link InvalidateDetail}.
+ *
+ * A convention on top of {@link CUSTOM_AGENT_EVENT}, not a second channel: the
+ * wire carries an ordinary AG-UI `CUSTOM` event whose `name` is
+ * {@link INVALIDATE_CUSTOM_NAME}, and this is that one name routed to its own
+ * DOM event so a host does not have to string-match. Every other name still
+ * arrives as `ag-ui-custom`.
+ *
+ * Fires **as each announcement arrives**, during the run, which is what makes a
+ * long multi-step run feel live: the list refreshes as the third of eight writes
+ * lands rather than when everything finishes. {@link RUN_FINISHED_EVENT} carries
+ * the same keys again at the end, de-duplicated, for a host that would rather
+ * refetch once.
+ */
+export const INVALIDATE_EVENT = "ag-ui-invalidate";
+
+/**
+ * Fired when the user rates an assistant message from its action row.
+ *
+ * `detail` is a {@link FeedbackDetail}: the rated message's text and the
+ * rating. **Nothing is stored** -- a rating belongs to whatever the host
+ * already uses to hold product signals, and a write-only table inside a chat
+ * widget is a schema nobody reads.
+ */
+export const FEEDBACK_EVENT = "ag-ui-feedback";
+
+/**
+ * The `activity_type` carrying server-pushed follow-up prompts.
+ *
+ * Matches django-ag-ui's `SUGGESTIONS_ACTIVITY_TYPE`. A convention inside the
+ * protocol's open `activity_type` field, not an extension of it -- so a client
+ * that has never heard of it ignores the event, and this one is not privileged.
+ */
+export const SUGGESTIONS_ACTIVITY_TYPE = "suggestions";
+
+/**
+ * The AG-UI `CUSTOM` event `name` that carries an invalidation.
+ *
+ * Matched exactly. Namespaced so it cannot collide with a host's own custom
+ * events, which share the field.
+ */
+export const INVALIDATE_CUSTOM_NAME = "ag_ui.invalidate";
+
 /** Roles a chat message can take. */
 export const MESSAGE_ROLE = {
   USER: "user",
@@ -221,3 +286,13 @@ export const ICON_FILE_TEXT = `<svg class="glyph" viewBox="0 0 24 24" aria-hidde
  * event, which is the graceful outcome.
  */
 export const CHART_ACTIVITY_TYPE = "chart";
+
+/**
+ * How long a screen-reader status stays in the announcer before it is emptied.
+ *
+ * Long enough for a reader to pick the change up, short enough that the region
+ * is empty again before the next status lands. Emptying is what makes an
+ * identical consecutive message announce at all -- a live region is read on
+ * *change*, and setting the same string twice is not one.
+ */
+export const ANNOUNCE_CLEAR_MS = 150;