@ai-matrx/chat 0.7.27 → 0.7.29

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @ai-matrx/chat
 
+## 0.7.29
+### the agents messenger
+
+- **`messenger/agents/AgentsMessenger`: "agents you know" on the messenger shell.** A short roster —
+  the starter seats `MESSENGER_STARTER_MANDATE_KEYS` (messenger.answer_anything, chat.default_new_chat,
+  personal_staff.front_line, resolved through the mandate resolver) plus agents the person added, minus
+  seats they removed — and pinned threads as their own rows. Per-person state is
+  `platform.user_entity_state.metadata.messenger`, written only through `platform.ues_merge_metadata`.
+  The thread body is THE chat room (`ChatRoomClient`); the header title is the thread dropdown (current,
+  past, + New chat, Pin); "Manage agents" adds through THE agent picker. Pure rules in
+  `messenger/agents/roster`. Consumer action: mount it (matrx-frontend: `/messenger/agents`).
+- **`ChatRoomClient`: `onOpenConversation` and `surfaceBasePath` props.** A host that keeps the open
+  conversation in its own state receives the persisted / fork / retry id instead of a `router.replace`.
+  Defaults unchanged. Consumer action: none.
+- **Messenger contract:** menu items take `detail`, `checked`, `keepOpen`; a source may return
+  `renderMain` (a screen in the thread area); a contact with no title entries opens details.
+
+## 0.7.28
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/chat/v0.7.27..npm/chat/v0.7.28 -- apps/shared/chat`).
+No source changes intended and no consumer action required.
+
 ## 0.7.27
 ### Unreleased
 

package/dist/agents/components/chat/ChatRoomClient.d.ts

@@ -43,6 +43,22 @@ interface ChatRoomClientProps {
      * mid-sentence in.
      */
     buildConversationHref?: (conversationId: string) => string;
+    /**
+     * How this room OPENS a conversation it moved to — the fresh chat's id once
+     * it persists, and fork / retry / delete targets. Default:
+     * `router.replace(buildConversationHref(id))`, the route-owned rooms.
+     *
+     * A host that keeps the open conversation in its own state rather than in
+     * the URL (the messenger's agents source, where a thread is a row and a
+     * dropdown, not a path) passes this and owns the switch; the room never
+     * navigates for it.
+     */
+    onOpenConversation?: (conversationId: string) => void;
+    /**
+     * The page path pattern this room registers for its surface (action bars
+     * read it to know they are on a page). Default `/chat/[conversationId]`.
+     */
+    surfaceBasePath?: string;
     /**
      * THE MANDATE DOOR for this room. When the surface knows WHICH JOB it is
      * (`/chat/new` is the `chat.default_new_chat` mandate), pass the key: the
@@ -116,5 +132,5 @@ interface ChatRoomClientProps {
  *   (`ready: false`) and we load the existing conversation. The prop is the
  *   single source of truth — no parallel state.
  */
-export declare function ChatRoomClient({ agentId, audience, conversationId: conversationIdProp, landingContent, aboveInput, buildConversationHref, mandateKey, variablesPanelStyle, sandboxBinding, conversationMaterialization, sourceFeature, composer: composerOptions, }: ChatRoomClientProps): import("react").JSX.Element;
+export declare function ChatRoomClient({ agentId, audience, conversationId: conversationIdProp, landingContent, aboveInput, buildConversationHref, onOpenConversation, surfaceBasePath, mandateKey, variablesPanelStyle, sandboxBinding, conversationMaterialization, sourceFeature, composer: composerOptions, }: ChatRoomClientProps): import("react").JSX.Element;
 export {};

package/dist/agents/components/chat/ChatRoomClient.js

@@ -2,7 +2,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { logFailure } from "../../../ui/expectedRefusal.js";
 import { usePreparedResourceSeed } from "./usePreparedResourceSeed.js";
-import { Suspense, useEffect, useRef, useState } from "react";
+import { Suspense, useCallback, useEffect, useRef, useState } from "react";
 import { shallowEqual } from "react-redux";
 import { useRouter, useSearchParams } from "../../../host/navigation.js";
 import { commitUrlParams } from "@ai-matrx/kit/url-state";
@@ -64,6 +64,7 @@ import { selectUserId, isNotAuthenticatedError } from "../../../host/identity.js
 import { selectOrganizationId } from "../../../host/org.js";
 import { selectAuthReady } from "../../../host/identity.js";
 const defaultConversationHref = (conversationId) => `/chat/${conversationId}`;
+const DEFAULT_SURFACE_BASE_PATH = "/chat/[conversationId]";
 const SOURCE_FEATURE = "chat";
 const CHAT_INITIAL_MESSAGE_LIMIT = 12;
 function ChatRoomClient({
@@ -73,6 +74,8 @@ function ChatRoomClient({
   landingContent,
   aboveInput,
   buildConversationHref = defaultConversationHref,
+  onOpenConversation,
+  surfaceBasePath = DEFAULT_SURFACE_BASE_PATH,
   mandateKey,
   variablesPanelStyle,
   sandboxBinding = null,
@@ -100,13 +103,20 @@ function ChatRoomClient({
       registerSurface({
         surfaceKey,
         kind: "page",
-        basePath: "/chat/[conversationId]"
+        basePath: surfaceBasePath
       })
     );
     return () => {
       dispatch(unregisterSurface(surfaceKey));
     };
-  }, [dispatch, surfaceKey]);
+  }, [dispatch, surfaceKey, surfaceBasePath]);
+  const openConversation = useCallback(
+    (id) => {
+      if (onOpenConversation) onOpenConversation(id);
+      else router.replace(buildConversationHref(id));
+    },
+    [onOpenConversation, router, buildConversationHref]
+  );
   const executionPayload = useAppSelector(
     (state) => selectAgentExecutionPayload(state, agentId)
   );
@@ -194,9 +204,9 @@ function ChatRoomClient({
   const pendingNavigation = useAppSelector(selectPendingNavigation(surfaceKey));
   useEffect(() => {
     if (!pendingNavigation) return;
-    router.replace(buildConversationHref(pendingNavigation.conversationId));
+    openConversation(pendingNavigation.conversationId);
     dispatch(clearPendingNavigation({ surfaceKey }));
-  }, [pendingNavigation, router, dispatch, surfaceKey, buildConversationHref]);
+  }, [pendingNavigation, dispatch, surfaceKey, openConversation]);
   const draftInputEntryReady = useAppSelector(
     (state) => liveConversationId ? selectUserInputEntryExists(liveConversationId)(state) : false
   );
@@ -401,7 +411,7 @@ function ChatRoomClient({
       const focusNow = store.getState().conversationFocus?.bySurface[surfaceKey]?.input ?? null;
       if (focusNow !== target) return;
       promotedRef.current = target;
-      router.replace(buildConversationHref(target));
+      openConversation(target);
     })();
     return () => {
       ctrl.abort();
@@ -410,10 +420,9 @@ function ChatRoomClient({
   }, [
     readyToPromote,
     liveConversationId,
-    router,
     store,
     surfaceKey,
-    buildConversationHref
+    openConversation
   ]);
   const conversationId = conversationIdProp ?? liveConversationId ?? null;
   const canRenderLandingDuringInit = !!landingContent && !conversationIdProp && !!conversationId;

package/dist/messenger/MessengerContactList.js

@@ -154,7 +154,7 @@ function MessengerContactList({
             }
           ) : /* @__PURE__ */ jsx("span", {})
         ] }),
-        /* @__PURE__ */ jsx("div", { className: "shrink-0 px-3 pb-2", children: /* @__PURE__ */ jsxs("label", { className: "flex h-9 w-full min-w-0 items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground focus-within:border-ring", children: [
+        /* @__PURE__ */ jsx("div", { className: "shrink-0 px-3 pb-2", children: /* @__PURE__ */ jsxs("div", { className: "flex h-9 w-full min-w-0 items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground focus-within:border-ring", children: [
           /* @__PURE__ */ jsx(Search, { className: "h-4 w-4 shrink-0" }),
           /* @__PURE__ */ jsx(
             "input",

package/dist/messenger/MessengerMenu.js

@@ -1,5 +1,6 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Check } from "lucide-react";
 import {
   ContextMenu,
   ContextMenuContent,
@@ -12,6 +13,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger
 } from "@ai-matrx/design-system";
+import { cn } from "@ai-matrx/design-system/cn";
 import { isMenuSeparator } from "./contract.js";
 function Entries({ entries, kind }) {
   const Item = kind === "context" ? ContextMenuItem : DropdownMenuItem;
@@ -23,12 +25,18 @@ function Entries({ entries, kind }) {
       Item,
       {
         disabled: entry.disabled,
-        onSelect: () => entry.onSelect(),
+        onSelect: (event) => {
+          if (entry.keepOpen) event.preventDefault();
+          entry.onSelect();
+        },
         className: entry.destructive ? "text-destructive focus:text-destructive" : void 0,
         "data-menu-item": entry.id,
+        "data-checked": entry.checked ? "" : void 0,
         children: [
           Icon ? /* @__PURE__ */ jsx(Icon, { className: "mr-2 h-4 w-4 shrink-0" }) : null,
-          /* @__PURE__ */ jsx("span", { className: "truncate", children: entry.label })
+          /* @__PURE__ */ jsx("span", { className: cn("min-w-0 flex-1 truncate", entry.checked && "font-medium"), children: entry.label }),
+          entry.detail ? /* @__PURE__ */ jsx("span", { className: "ml-3 shrink-0 text-[12px] text-muted-foreground", children: entry.detail }) : null,
+          entry.checked ? /* @__PURE__ */ jsx(Check, { className: "ml-2 h-4 w-4 shrink-0 text-primary", "aria-label": "Current" }) : null
         ]
       },
       entry.id
@@ -49,7 +57,7 @@ function MessengerDropdownMenu({
 }) {
   return /* @__PURE__ */ jsxs(DropdownMenu, { modal: false, children: [
     /* @__PURE__ */ jsx(DropdownMenuTrigger, { asChild: true, children: trigger }),
-    /* @__PURE__ */ jsx(DropdownMenuContent, { align, className: "min-w-48", children: /* @__PURE__ */ jsx(Entries, { entries: entries(), kind: "dropdown" }) })
+    /* @__PURE__ */ jsx(DropdownMenuContent, { align, className: "max-h-[min(70vh,32rem)] min-w-48 max-w-[22rem] overflow-y-auto", children: /* @__PURE__ */ jsx(Entries, { entries: entries(), kind: "dropdown" }) })
   ] });
 }
 export {

package/dist/messenger/MessengerShell.js

@@ -28,7 +28,8 @@ function MessengerShell({ source, className }) {
   const filter = source.filters?.find((f) => f.id === filterId) ?? null;
   const contacts = useMemo(() => visibleContacts(source.contacts, query, filter), [source.contacts, query, filter]);
   const active = source.contacts.find((c) => c.id === source.activeContactId) ?? null;
-  const showThread = pane === "thread" && active !== null;
+  const main = source.renderMain?.() ?? null;
+  const showThread = main !== null || pane === "thread" && active !== null;
   const shellSource = useMemo(
     () => ({
       ...source,
@@ -69,7 +70,7 @@ function MessengerShell({ source, className }) {
             )
           }
         ),
-        /* @__PURE__ */ jsx("main", { className: cn("flex min-h-0 min-w-0 flex-1 flex-col", !showThread && "max-md:hidden"), "aria-label": "Conversation", children: active ? /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx("main", { className: cn("flex min-h-0 min-w-0 flex-1 flex-col", !showThread && "max-md:hidden"), "aria-label": "Conversation", children: main !== null ? /* @__PURE__ */ jsx("div", { className: "flex min-h-0 min-w-0 flex-1 flex-col", "data-messenger-main": true, children: main }) : active ? /* @__PURE__ */ jsxs(Fragment, { children: [
           /* @__PURE__ */ jsx(
             MessengerThreadHeader,
             {
@@ -85,7 +86,7 @@ function MessengerShell({ source, className }) {
           /* @__PURE__ */ jsx(MessageCircle, { className: "h-10 w-10", strokeWidth: 1.25 }),
           /* @__PURE__ */ jsx("span", { className: "text-[14px]", children: "Pick a conversation" })
         ] }) }),
-        active && renderDetails && detailsOpen ? /* @__PURE__ */ jsxs(
+        main === null && active && renderDetails && detailsOpen ? /* @__PURE__ */ jsxs(
           "aside",
           {
             "aria-label": "Details",

package/dist/messenger/MessengerThreadHeader.js

@@ -14,7 +14,7 @@ function MessengerThreadHeader({
 }) {
   const info = source.header(contact);
   const headerMenu = source.headerMenu;
-  const titleMenu = source.titleMenu;
+  const titleMenu = source.titleMenu && source.titleMenu(contact).length > 0 ? source.titleMenu : void 0;
   const titleBlock = /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 items-center gap-1", children: [
       /* @__PURE__ */ jsx("span", { className: "truncate text-[15px] font-semibold text-foreground", "data-header-title": true, children: info.title }),

package/dist/messenger/agents/AgentDetailsPanel.d.ts

@@ -0,0 +1,20 @@
+import type { MessengerAvatar } from "../contract.js";
+import { type ThreadSummary } from "./roster.js";
+export interface AgentDetailsPanelProps {
+    readonly agentId: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly modelId: string | null;
+    readonly avatar?: MessengerAvatar;
+    /** What seat this agent fills ("Starter"), shown under the name. */
+    readonly seatLabel: string | null;
+    readonly threads: readonly ThreadSummary[];
+    readonly currentConversationId: string | null;
+    readonly pinnedIds: ReadonlySet<string>;
+    readonly hasMore: boolean;
+    readonly onLoadMore: () => void;
+    readonly onOpenThread: (conversationId: string) => void;
+    readonly onOpenAgent: () => void;
+    readonly onEditAgent: () => void;
+}
+export declare function AgentDetailsPanel(props: AgentDetailsPanelProps): import("react").JSX.Element;

package/dist/messenger/agents/AgentDetailsPanel.js

@@ -0,0 +1,98 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Brain, ExternalLink, History, MessageSquareText, Pencil, Pin, Settings2 } from "lucide-react";
+import { MessengerDetails } from "../MessengerDetails.js";
+import { useModelLabel } from "../../agents/identity/model-catalog.js";
+import {
+  useHasChatWindowOpener,
+  useOpenAgentMemoryWindow,
+  useOpenAgentRunHistoryWindow,
+  useOpenAgentSettingsWindow
+} from "../../host/window-openers.js";
+import { relativeDate, threadTitle } from "./roster.js";
+function DoorRow({ icon: Icon, label, onClick }) {
+  return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs(
+    "button",
+    {
+      type: "button",
+      onClick,
+      className: "flex w-full min-w-0 items-center gap-3 rounded-lg px-2 py-2 text-left text-[14px] text-foreground hover:bg-accent",
+      children: [
+        /* @__PURE__ */ jsx(Icon, { className: "h-4 w-4 shrink-0 text-muted-foreground" }),
+        /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate", children: label })
+      ]
+    }
+  ) });
+}
+function AgentDetailsPanel(props) {
+  const modelLabel = useModelLabel(props.modelId);
+  const hasSettings = useHasChatWindowOpener("openAgentSettingsWindow");
+  const hasMemory = useHasChatWindowOpener("openAgentMemoryWindow");
+  const hasHistory = useHasChatWindowOpener("openAgentRunHistoryWindow");
+  const openSettings = useOpenAgentSettingsWindow();
+  const openMemory = useOpenAgentMemoryWindow();
+  const openHistory = useOpenAgentRunHistoryWindow();
+  const details = /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-4", children: [
+    /* @__PURE__ */ jsxs("dl", { className: "flex flex-col gap-3 px-2 pt-1 text-[13px]", children: [
+      /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-0.5", children: [
+        /* @__PURE__ */ jsx("dt", { className: "text-[12px] text-muted-foreground", children: "Model" }),
+        /* @__PURE__ */ jsx("dd", { className: "truncate text-foreground", children: modelLabel ?? (props.modelId ? "Loading\u2026" : "Default") })
+      ] }),
+      props.description ? /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-0.5", children: [
+        /* @__PURE__ */ jsx("dt", { className: "text-[12px] text-muted-foreground", children: "About" }),
+        /* @__PURE__ */ jsx("dd", { className: "line-clamp-4 text-foreground", children: props.description })
+      ] }) : null
+    ] }),
+    /* @__PURE__ */ jsxs("ul", { className: "flex flex-col", children: [
+      /* @__PURE__ */ jsx(DoorRow, { icon: ExternalLink, label: "Open agent", onClick: props.onOpenAgent }),
+      /* @__PURE__ */ jsx(DoorRow, { icon: Pencil, label: "Edit agent", onClick: props.onEditAgent }),
+      hasSettings ? /* @__PURE__ */ jsx(DoorRow, { icon: Settings2, label: "Settings", onClick: () => openSettings({ initialAgentId: props.agentId }) }) : null,
+      hasMemory ? /* @__PURE__ */ jsx(DoorRow, { icon: Brain, label: "Memory", onClick: () => openMemory() }) : null,
+      hasHistory ? /* @__PURE__ */ jsx(DoorRow, { icon: History, label: "Run history", onClick: () => openHistory({ agentId: props.agentId }) }) : null
+    ] })
+  ] });
+  const threads = /* @__PURE__ */ jsxs("ul", { className: "flex flex-col", children: [
+    props.threads.length === 0 ? /* @__PURE__ */ jsx("li", { className: "px-2 py-3 text-[13px] text-muted-foreground", children: "No chats yet" }) : null,
+    props.threads.map((thread) => {
+      const current = thread.conversationId === props.currentConversationId;
+      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs(
+        "button",
+        {
+          type: "button",
+          onClick: () => props.onOpenThread(thread.conversationId),
+          "aria-current": current ? "true" : void 0,
+          className: "flex w-full min-w-0 items-center gap-3 rounded-lg px-2 py-2 text-left hover:bg-accent " + (current ? "bg-accent/70" : ""),
+          children: [
+            props.pinnedIds.has(thread.conversationId) ? /* @__PURE__ */ jsx(Pin, { className: "h-4 w-4 shrink-0 rotate-45 text-muted-foreground", "aria-label": "Pinned" }) : /* @__PURE__ */ jsx(MessageSquareText, { className: "h-4 w-4 shrink-0 text-muted-foreground" }),
+            /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-[14px] text-foreground", children: threadTitle(thread) }),
+            /* @__PURE__ */ jsx("span", { className: "shrink-0 text-[12px] text-muted-foreground", children: relativeDate(thread.updatedAt) })
+          ]
+        }
+      ) }, thread.conversationId);
+    }),
+    props.hasMore ? /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        onClick: props.onLoadMore,
+        className: "w-full rounded-lg px-2 py-2 text-left text-[13px] text-muted-foreground hover:bg-accent hover:text-foreground",
+        children: "Show more"
+      }
+    ) }) : null
+  ] });
+  return /* @__PURE__ */ jsx(
+    MessengerDetails,
+    {
+      name: props.name,
+      avatar: props.avatar,
+      subtitle: props.seatLabel ?? void 0,
+      tabs: [
+        { id: "details", label: "Details", content: details },
+        { id: "threads", label: "Threads", content: threads }
+      ]
+    }
+  );
+}
+export {
+  AgentDetailsPanel
+};

package/dist/messenger/agents/AgentsMessenger.d.ts

@@ -0,0 +1,63 @@
+/**
+ * THE AGENTS SOURCE — "agents you know": a short, curated roster of agents
+ * (the starter seats + agents the person added − seats they removed) and the
+ * threads the person pinned, as a MessengerSource on the shared shell.
+ *
+ *  - Roster: `MESSENGER_STARTER_MANDATE_KEYS` resolved through the ONE mandate
+ *    resolver (`useMandateSet`), merged with the person's
+ *    `platform.user_entity_state.metadata.messenger` rows (./roster.ts).
+ *  - Listing: the chat package's own conversation-history reads
+ *    (`fetchConversationHistory`, one scope per roster agent) — no parallel query layer.
+ *  - Thread body: THE chat room, `ChatRoomClient` (streaming, tools, composer,
+ *    renderer). The room never navigates here: it hands the persisted id back
+ *    through `onOpenConversation`. A seat with ONE fixed thread (the Chief of
+ *    Staff) mounts the host's own door for it via `renderSeatRoom`.
+ *  - Header title: the thread dropdown (current, past, + New chat, Pin).
+ *
+ * `<AgentsMessenger>` is the shell + this source + the rename dialog.
+ * Doc: ../FEATURE.md.
+ */
+import { type ReactNode } from "react";
+import type { MessengerProfile, MessengerSource } from "../contract.js";
+import { type MessengerStarterKey } from "./roster.js";
+/** Where the person is: an agent and its open thread (null = a new chat). */
+export interface AgentsMessengerLocation {
+    readonly agentId: string | null;
+    readonly conversationId: string | null;
+}
+export interface AgentsMessengerOptions {
+    /** The list title. Default "Agents". */
+    readonly title?: string;
+    readonly profile?: MessengerProfile;
+    /** Open on this agent / thread (the host's deep link). */
+    readonly initialLocation?: AgentsMessengerLocation;
+    /** Every move, so the host can keep its URL in step (replaceState, never a navigation). */
+    readonly onLocationChange?: (location: AgentsMessengerLocation) => void;
+    /** An absolute link to a place in this messenger (Copy link). */
+    readonly linkTo?: (location: AgentsMessengerLocation) => string;
+    /** Doors onto the rest of the app. Defaults are matrx-frontend's routes. */
+    readonly hrefs?: {
+        readonly agent?: (agentId: string) => string;
+        readonly editAgent?: (agentId: string) => string;
+        readonly conversation?: (conversationId: string) => string;
+    };
+    /**
+     * A seat whose thread is fixed by its own door (the Chief of Staff's ONE
+     * staff thread): the host returns that room. Null / absent: the chat room.
+     */
+    readonly renderSeatRoom?: (seat: {
+        mandateKey: MessengerStarterKey;
+        agentId: string;
+    }) => ReactNode | null;
+}
+export interface AgentsMessengerModel {
+    readonly source: MessengerSource;
+    /** Dialogs the source opens (Rename). Render beside the shell. */
+    readonly overlays: ReactNode;
+}
+export declare function useAgentsMessengerSource(options?: AgentsMessengerOptions): AgentsMessengerModel;
+export interface AgentsMessengerProps extends AgentsMessengerOptions {
+    readonly className?: string;
+}
+/** The agents messenger: the shared shell over the agents source, plus its dialogs. */
+export declare function AgentsMessenger({ className, ...options }: AgentsMessengerProps): import("react").JSX.Element;