@ai-matrx/chat 0.4.15 → 0.4.18

package/dist/canvas/workspace/ShellChatDock.js

@@ -2,7 +2,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useEffect, useEffectEvent, useRef, useState } from "react";
 import { Maximize2, PictureInPicture2 } from "lucide-react";
-import { usePathname } from "../../host/navigation.js";
+import { usePathname, useSearchParams } from "../../host/navigation.js";
 import {
   Drawer,
   DrawerContent,
@@ -23,6 +23,14 @@ import { CanvasChatColumn } from "./CanvasChatColumn.js";
 import { ChatPanelTitleMenu, useChatPanelTitle } from "./ChatPanelTitleMenu.js";
 import { useCanvasWorkspaceConversation } from "./useCanvasWorkspaceConversation.js";
 import { useShellChatPageContext } from "./shell-chat-page-context.js";
+import { useComposerMode } from "../../agents/components/inputs/smart-input/composer/useComposerMode.js";
+import { replaceAddressWithoutNavigating } from "@ai-matrx/rich-content/utils/addressWithoutNavigating";
+import {
+  addressAfterSideChatLink,
+  readSideChatLink,
+  sideChatOpen,
+  sideChatSignature
+} from "./side-chat-address.js";
 import {
   CANVAS_CHAT_SIZES,
   CANVAS_PANEL_IDS,
@@ -77,6 +85,8 @@ function useCanvasFullScreenActive() {
 }
 function ShellChatDock({ initialChat, initialWidth, initialMode = null, signedIn, initialPathname }) {
   const pathname = usePathname() ?? initialPathname;
+  const searchParams = useSearchParams();
+  const linkSignature = sideChatSignature((name) => searchParams?.get(name) ?? null);
   const home = shellChatHome(pathname, signedIn);
   const hostedElsewhere = shellChatHostedElsewhere(pathname);
   const viewportCompact = useMediaQueryState(COMPACT_QUERY);
@@ -88,6 +98,9 @@ function ShellChatDock({ initialChat, initialWidth, initialMode = null, signedIn
   });
   const [wideDefault, setWideDefault] = useState(false);
   const [sheetOpen, setSheetOpen] = useState(false);
+  const [visit, setVisit] = useState(null);
+  const ownWrite = useRef(null);
+  const { setMode } = useComposerMode(initialMode, { enabled: signedIn });
   if (choice.layoutId !== home.layoutId) {
     setChoice({
       layoutId: home.layoutId,
@@ -97,21 +110,57 @@ function ShellChatDock({ initialChat, initialWidth, initialMode = null, signedIn
   useEffect(() => {
     setWideDefault(window.matchMedia(SHELL_CHAT_WIDE_QUERY).matches);
   }, []);
+  const visitHere = visit && visit.pathname === pathname && visit.surfaceKey === home.surfaceKey ? visit : null;
+  const link = visitHere?.link ?? null;
+  const standsAside = hostedElsewhere && !link;
   const placement = choice.state?.placement ?? "side";
-  const open = !hostedElsewhere && (choice.state?.open ?? home.defaultOpen ?? wideDefault);
+  const open = sideChatOpen({
+    hostedElsewhere,
+    link,
+    personActed: visitHere?.acted ?? false,
+    remembered: choice.state?.open ?? home.defaultOpen ?? wideDefault
+  });
   const shown = open && !fullScreen;
   const docked = shown && placement === "side";
   const floating = !compact && shown && placement === "floating";
-  const chatOnScreen = !hostedElsewhere && (compact ? sheetOpen : viewportCompact === false && shown);
+  const chatOnScreen = !standsAside && (compact ? sheetOpen : viewportCompact === false && shown);
+  const readLink = useEffectEvent(() => {
+    const search = window.location.search;
+    if (visitHere && ownWrite.current === search) return;
+    const read = readSideChatLink(search);
+    setVisit({ pathname, surfaceKey: home.surfaceKey, link: read, acted: false });
+    if (!linkSignature) return;
+    const consumed = addressAfterSideChatLink(search, read, { hostedElsewhere });
+    ownWrite.current = consumed;
+    if (consumed !== search) {
+      replaceAddressWithoutNavigating(`${window.location.pathname}${consumed}${window.location.hash}`);
+    }
+    if (!read) return;
+    const opens = read.open ?? (hostedElsewhere ? true : null);
+    if (opens !== null) setSheetOpen(opens);
+    if (opens) window.dispatchEvent(new Event(SHELL_CHAT_REVEAL_EVENT));
+    if (read.mode) setMode(read.mode);
+  });
+  useEffect(() => {
+    if (signedIn) readLink();
+  }, [signedIn, pathname, home.surfaceKey, linkSignature]);
   const chat = useCanvasWorkspaceConversation(home.surfaceKey, {
     enabled: signedIn && chatOnScreen,
-    addressParam: home.addressParam
+    address: {
+      link: visitHere ? visitHere.link : void 0,
+      open: compact ? sheetOpen : open,
+      hostedElsewhere,
+      onWrite: (search) => {
+        ownWrite.current = search;
+      }
+    }
   });
   const conversationId = chat.conversationId;
   const chatTitle = useChatPanelTitle(conversationId);
   const pageContext = useShellChatPageContext();
   const floatingSize = readFloatingSize(useSessionKnob(COMPOSER_KNOBS.floatingPanelSize));
   const setChat = (next) => {
+    setVisit((current) => current && !current.acted ? { ...current, acted: true } : current);
     setChoice({ layoutId: home.layoutId, state: next });
     writeCanvasChatCookie(home.layoutId, next);
   };
@@ -132,14 +181,14 @@ function ShellChatDock({ initialChat, initialWidth, initialMode = null, signedIn
     const root = document.querySelector(".shell-root");
     if (!root || !signedIn) return void 0;
     root.toggleAttribute("data-shell-chat-open", docked && wideKnown);
-    root.toggleAttribute("data-shell-chat-available", !hostedElsewhere);
+    root.toggleAttribute("data-shell-chat-available", !standsAside);
     return () => {
       root.removeAttribute("data-shell-chat-open");
       root.removeAttribute("data-shell-chat-available");
     };
-  }, [docked, wideKnown, hostedElsewhere, signedIn]);
+  }, [docked, wideKnown, standsAside, signedIn]);
   useEffect(() => {
-    if (!signedIn || !wideKnown || hostedElsewhere) return;
+    if (!signedIn || !wideKnown || standsAside) return;
     const root = document.querySelector(".shell-root");
     const sidebarToggle = document.getElementById("shell-sidebar-toggle");
     if (!root?.hasAttribute("data-domain-panel") || !sidebarToggle) return;
@@ -155,17 +204,18 @@ function ShellChatDock({ initialChat, initialWidth, initialMode = null, signedIn
       const want = saved?.split("=")[1] !== "0";
       if (sidebarToggle.checked !== want) sidebarToggle.checked = want;
     }
-  }, [docked, choice.state, wideKnown, hostedElsewhere, signedIn, home.layoutId]);
+  }, [docked, choice.state, wideKnown, standsAside, signedIn, home.layoutId]);
   const onToggle = useEffectEvent(() => {
-    if (!hostedElsewhere) toggle();
+    if (!standsAside) toggle();
   });
+  const takesToggle = useEffectEvent(() => !standsAside);
   useEffect(() => {
     const onEvent = () => onToggle();
     const onKey = (e) => {
       if (!signedIn || !shellChatTakesToggleKey(e)) return;
       const inChat = e.target instanceof Element && e.target.closest(".shell-chat-dock, .shell-chat-floating");
       if (isTypingTarget(e.target) && !inChat) return;
-      if (shellChatHostedElsewhere(window.location.pathname)) return;
+      if (!takesToggle()) return;
       e.preventDefault();
       onToggle();
     };

package/dist/canvas/workspace/shell-chat-route.d.ts

@@ -30,7 +30,8 @@ export declare function shellChatWorkspaceId(family: string): string;
  * The only pages the shell's chat stands aside on: the full chat itself and
  * the code workspace (it docks its own coding agent). Every other page —
  * the Board and Education included — shows THE chat (owner, 2026-10-05: one
- * chat, on every page).
+ * chat, on every page). A side_chat* link brings it in here too
+ * (side-chat-address.ts `sideChatOpen`, owner 2026-10-07).
  */
 export declare function shellChatHostedElsewhere(pathname: string): boolean;
 /**
@@ -46,14 +47,14 @@ export declare function shellChatPageSurfaceKey(pathname: string): string;
  *   - `layoutId`     — its remembered open / closed + docked / floating
  *                      (`canvasChatCookieName(layoutId)`);
  *   - `surfaceKey`   — the conversation it shows (and this device's memory of it);
- *   - `addressParam` — the query param that conversation lives at;
+ *                      the address names it as `?side_chat=` on every home
+ *                      (side-chat-address.ts);
  *   - `defaultOpen`  — open with no remembered choice; null = open on a wide
  *                      screen only (SHELL_CHAT_WIDE_QUERY).
  */
 export interface ShellChatHome {
     layoutId: string;
     surfaceKey: string;
-    addressParam: string;
     defaultOpen: boolean | null;
 }
 /**
@@ -64,7 +65,7 @@ export interface ShellChatHome {
 export declare const SHELL_CHAT_CLOSED_BY_DEFAULT_PAGES: readonly RegExp[];
 /**
  * A page with a chat of its OWN keeps it inside the shell chat: each board
- * has its conversation, signed-in Education has one. The ids, params and
+ * has its conversation, signed-in Education has one. The ids and
  * defaults are exactly the ones those pages used when they drew their own chat
  * column (ChatCanvasWorkspace, until 2026-10-05), so a person's remembered
  * layout and conversation carry over untouched. Every other page remembers its

package/dist/canvas/workspace/shell-chat-route.js

@@ -31,16 +31,14 @@ function shellChatHome(pathname, signedIn) {
   const board = BOARD_PAGE.exec(pathname);
   if (board) {
     const layoutId = `board-${board[1]}`;
-    return { layoutId, surfaceKey: `canvas-workspace:${layoutId}`, addressParam: "chat", defaultOpen: true };
+    return { layoutId, surfaceKey: `canvas-workspace:${layoutId}`, defaultOpen: true };
   }
   if (signedIn && EDUCATION_PAGES.test(pathname)) {
-    return { layoutId: "education", surfaceKey: "canvas-workspace:education", addressParam: "chat", defaultOpen: false };
+    return { layoutId: "education", surfaceKey: "canvas-workspace:education", defaultOpen: false };
   }
   return {
     layoutId: shellChatWorkspaceId(shellChatFamily(pathname)),
     surfaceKey: shellChatPageSurfaceKey(pathname),
-    // `pageChat`, not `chat`: /code keeps its own `?chat=`.
-    addressParam: "pageChat",
     defaultOpen: SHELL_CHAT_CLOSED_BY_DEFAULT_PAGES.some((p) => p.test(pathname)) ? false : null
   };
 }

package/dist/canvas/workspace/side-chat-address.d.ts

@@ -0,0 +1,91 @@
+/**
+ * THE SIDE CHAT'S LINK CONTRACT (owner, 2026-10-07) — the ONE param family that
+ * opens, closes and aims the chat beside every page, on every home (an ordinary
+ * page, a board, Education — and /chat and /code, where the Side Chat is absent
+ * unless a link asks for it).
+ *
+ *   side_chat        open | closed | new | <conversation uuid>
+ *   side_chat_agent  <agent uuid> | mandate:<key>   (the agent picker's ref shape)
+ *   side_chat_mode   chat | work | advanced         (the composer's mode)
+ *
+ * The link WINS over the remembered state (the per-page conversation, the family
+ * cookie, the defaults) for that visit; it never writes the person's open / closed
+ * choice — only the person's own act does. Once read, the address keeps naming
+ * what the panel shows: `side_chat=<uuid>` for a conversation the server has,
+ * `side_chat=open` / `closed` otherwise; `side_chat_agent` / `side_chat_mode` and
+ * `side_chat=new` are consumed so a reload never starts yet another new chat.
+ *
+ * Plain module, no React: the dock, the conversation hook and the tests share it.
+ * A value it cannot use is IGNORED with a console warning naming it — never silently.
+ */
+import { type AnyMandateKey } from "@ai-matrx/agents/mandates";
+import { type ComposerMode } from "../../agents/components/inputs/smart-input/composer/composer-types.js";
+export declare const SIDE_CHAT_PARAM = "side_chat";
+export declare const SIDE_CHAT_AGENT_PARAM = "side_chat_agent";
+export declare const SIDE_CHAT_MODE_PARAM = "side_chat_mode";
+export declare const SIDE_CHAT_PARAMS: readonly ["side_chat", "side_chat_agent", "side_chat_mode"];
+/** What a link asks the Side Chat's conversation to be. */
+export type SideChatLinkConversation = {
+    kind: "new";
+} | {
+    kind: "open";
+    conversationId: string;
+} | {
+    kind: "agent";
+    agentId: string;
+} | {
+    kind: "mandate";
+    mandateKey: AnyMandateKey;
+    agentRef: string;
+};
+export interface SideChatLink {
+    /** true / false = the link sets the panel; null = it says nothing about it. */
+    open: boolean | null;
+    conversation: SideChatLinkConversation | null;
+    mode: ComposerMode | null;
+}
+export type SideChatWarn = (message: string) => void;
+/**
+ * The Side Chat link in `search`, or null when it carries no usable side_chat*
+ * instruction (absent, or every value invalid — each invalid one is warned).
+ */
+export declare function readSideChatLink(search: string, warn?: SideChatWarn): SideChatLink | null;
+/**
+ * Whether the Side Chat is open. The link wins for its visit until the person
+ * acts; then their remembered choice does again. On a page that hosts its own
+ * chat (/chat, /code) the Side Chat is absent unless a link summoned it, and a
+ * link that names no open / closed (only a mode) still brings it in.
+ */
+export declare function sideChatOpen({ hostedElsewhere, link, personActed, remembered, }: {
+    hostedElsewhere: boolean;
+    /** This visit's link; null = none. */
+    link: SideChatLink | null;
+    /** The person opened / closed / docked the chat since the link was read. */
+    personActed: boolean;
+    /** The remembered choice, else the home's default. */
+    remembered: boolean;
+}): boolean;
+/**
+ * The address right after a link is read: `side_chat_agent`, `side_chat_mode`,
+ * `side_chat=new` and any invalid side_chat* value are consumed, and `side_chat`
+ * says what the panel now is (`open` / `closed`, or the conversation id it was
+ * asked to open). Everything else in the address is untouched.
+ */
+export declare function addressAfterSideChatLink(search: string, link: SideChatLink | null, { hostedElsewhere }: {
+    hostedElsewhere: boolean;
+}): string;
+/**
+ * The address while the Side Chat shows a conversation: open on a conversation
+ * the server has → `side_chat=<uuid>` (a copied link reproduces it); open on an
+ * unsent chat → `side_chat=open` where it already said so or where the page
+ * hosts its own chat (else nothing, as before); closed → no conversation in the
+ * address (a `side_chat=closed` the link set stays). The one-shot params never
+ * survive.
+ */
+export declare function sideChatAddress(search: string, { conversationId, open, hostedElsewhere }: {
+    conversationId: string | null;
+    open: boolean;
+    hostedElsewhere: boolean;
+}): string;
+/** The side_chat* values of `search`, as one comparable string ("" when none). */
+export declare function sideChatSignature(get: (name: string) => string | null): string;

package/dist/canvas/workspace/side-chat-address.js

@@ -0,0 +1,110 @@
+import { isUuidShape } from "@ai-matrx/kit/uuid";
+import { isMandateAgentId, mandateAgentId } from "@ai-matrx/agents/catalog";
+import { storedMandateKey } from "@ai-matrx/agents/mandates";
+import { isComposerMode } from "../../agents/components/inputs/smart-input/composer/composer-types.js";
+const SIDE_CHAT_PARAM = "side_chat";
+const SIDE_CHAT_AGENT_PARAM = "side_chat_agent";
+const SIDE_CHAT_MODE_PARAM = "side_chat_mode";
+const SIDE_CHAT_PARAMS = [SIDE_CHAT_PARAM, SIDE_CHAT_AGENT_PARAM, SIDE_CHAT_MODE_PARAM];
+const defaultWarn = (message) => console.warn(`[side-chat] ${message}`);
+const MANDATE_KEY_SHAPE = /^[a-z0-9][a-z0-9_.:-]*$/i;
+function readAgent(value, warn) {
+  if (isUuidShape(value)) return { kind: "agent", agentId: value };
+  if (isMandateAgentId(value)) {
+    const key = value.slice("mandate:".length);
+    if (MANDATE_KEY_SHAPE.test(key)) {
+      return { kind: "mandate", mandateKey: storedMandateKey(key), agentRef: mandateAgentId(key) };
+    }
+  }
+  warn(`ignored ${SIDE_CHAT_AGENT_PARAM}="${value}": expected an agent id or mandate:<key>`);
+  return null;
+}
+function readSideChatLink(search, warn = defaultWarn) {
+  const params = new URLSearchParams(search);
+  const rawChat = params.get(SIDE_CHAT_PARAM);
+  const rawAgent = params.get(SIDE_CHAT_AGENT_PARAM);
+  const rawMode = params.get(SIDE_CHAT_MODE_PARAM);
+  if (rawChat === null && rawAgent === null && rawMode === null) return null;
+  let open = null;
+  let conversation = null;
+  if (rawChat !== null) {
+    if (rawChat === "open") open = true;
+    else if (rawChat === "closed") open = false;
+    else if (rawChat === "new") {
+      open = true;
+      conversation = { kind: "new" };
+    } else if (isUuidShape(rawChat)) {
+      open = true;
+      conversation = { kind: "open", conversationId: rawChat };
+    } else {
+      warn(`ignored ${SIDE_CHAT_PARAM}="${rawChat}": expected open, closed, new or a conversation id`);
+    }
+  }
+  if (rawAgent !== null) {
+    const agent = readAgent(rawAgent, warn);
+    if (agent) {
+      if (conversation?.kind === "open") {
+        warn(`${SIDE_CHAT_AGENT_PARAM} wins over ${SIDE_CHAT_PARAM}=${conversation.conversationId}: a new chat with that agent opens`);
+      }
+      if (open === false) warn(`${SIDE_CHAT_AGENT_PARAM} wins over ${SIDE_CHAT_PARAM}=closed: the chat opens`);
+      conversation = agent;
+      open = true;
+    }
+  }
+  let mode = null;
+  if (rawMode !== null) {
+    if (isComposerMode(rawMode)) mode = rawMode;
+    else warn(`ignored ${SIDE_CHAT_MODE_PARAM}="${rawMode}": expected chat, work or advanced`);
+  }
+  if (open === null && conversation === null && mode === null) return null;
+  return { open, conversation, mode };
+}
+function sideChatOpen({
+  hostedElsewhere,
+  link,
+  personActed,
+  remembered
+}) {
+  if (hostedElsewhere && !link) return false;
+  if (link && !personActed) return link.open ?? (hostedElsewhere ? true : remembered);
+  return remembered;
+}
+function addressAfterSideChatLink(search, link, { hostedElsewhere }) {
+  const params = new URLSearchParams(search);
+  for (const name of SIDE_CHAT_PARAMS) params.delete(name);
+  const open = link ? link.open ?? (hostedElsewhere ? true : null) : null;
+  if (open !== null) {
+    const named = link?.conversation?.kind === "open" ? link.conversation.conversationId : null;
+    params.set(SIDE_CHAT_PARAM, open ? named ?? "open" : "closed");
+  }
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+function sideChatAddress(search, { conversationId, open, hostedElsewhere }) {
+  const params = new URLSearchParams(search);
+  const current = params.get(SIDE_CHAT_PARAM);
+  params.delete(SIDE_CHAT_AGENT_PARAM);
+  params.delete(SIDE_CHAT_MODE_PARAM);
+  if (open && conversationId) params.set(SIDE_CHAT_PARAM, conversationId);
+  else if (open) {
+    if (current === "open" || hostedElsewhere) params.set(SIDE_CHAT_PARAM, "open");
+    else params.delete(SIDE_CHAT_PARAM);
+  } else if (current !== "closed") params.delete(SIDE_CHAT_PARAM);
+  const qs = params.toString();
+  return qs ? `?${qs}` : "";
+}
+function sideChatSignature(get) {
+  const parts = SIDE_CHAT_PARAMS.map((name) => get(name));
+  return parts.every((p) => p === null) ? "" : parts.map((p) => p ?? "").join("|");
+}
+export {
+  SIDE_CHAT_AGENT_PARAM,
+  SIDE_CHAT_MODE_PARAM,
+  SIDE_CHAT_PARAM,
+  SIDE_CHAT_PARAMS,
+  addressAfterSideChatLink,
+  readSideChatLink,
+  sideChatAddress,
+  sideChatOpen,
+  sideChatSignature
+};

package/dist/canvas/workspace/useCanvasWorkspaceConversation.d.ts

@@ -1,3 +1,4 @@
+import { type SideChatLink } from "./side-chat-address.js";
 import type { AnyMandateKey } from "@ai-matrx/agents/mandates";
 export type CanvasWorkspaceConversation = {
     state: "opening";
@@ -39,18 +40,28 @@ export type CanvasWorkspaceConversationOptions = {
      */
     surfaceName?: null;
     /**
-     * The query param this conversation lives at (`?chat=<id>`), so a reload
-     * returns the person to it the way `/chat/<id>` does. Read once on mount
-     * (it wins over the default new chat), written once the server has the
-     * conversation, removed by New chat. With no `?<param>=`, the conversation
-     * this chat last showed on this device opens instead (see
-     * `recallWorkspaceConversation`). Omitted = neither the address nor the memory
-     * is touched (board chat TILES: many conversations, one page).
+     * THE SIDE CHAT'S ADDRESS (side-chat-address.ts): the conversation lives at
+     * `?side_chat=<id>`, so a reload returns the person to it the way `/chat/<id>`
+     * does. The link is read once per home (it wins over the remembered
+     * conversation and the default new chat); a later link on the same home is
+     * applied when it arrives. The address names the conversation once the server
+     * has it and while the panel is open. With no link, the conversation this
+     * chat last showed on this device opens instead (`recallWorkspaceConversation`).
+     * Omitted = neither the address nor the memory is touched (board chat TILES:
+     * many conversations, one page).
      */
-    addressParam?: string;
+    address?: SideChatAddressOptions;
 };
-/** The conversation `?<param>=` names in the current address, or null. */
-export declare function conversationInAddress(param: string, search: string): string | null;
+export interface SideChatAddressOptions {
+    /** This visit's link: undefined = not read yet (nothing launches), null = none. */
+    link: SideChatLink | null | undefined;
+    /** The panel is open — the address names the conversation only while it is. */
+    open: boolean;
+    /** The page hosts its own chat (/chat, /code): an unsent chat keeps `side_chat=open`. */
+    hostedElsewhere: boolean;
+    /** Told every address this hook writes, so the reader never re-reads its own write as a link. */
+    onWrite?: (search: string) => void;
+}
 /**
  * THIS CHAT'S LAST CONVERSATION, remembered on this device (2026-10-05).
  * `?<param>=` alone was not enough: any address without it — the board opened
@@ -74,8 +85,16 @@ export declare function rememberWorkspaceConversation(surfaceKey: string, conver
 export declare function reservedChatKey(surfaceKey: string): string;
 export declare function reserveWorkspaceConversationId(surfaceKey: string, fresh: boolean): string | undefined;
 export declare function releaseWorkspaceConversationId(surfaceKey: string): void;
-/** `search` with `?<param>=` set to `conversationId`, or removed when null. */
-export declare function addressWithConversation(param: string, search: string, conversationId: string | null): string;
+/**
+ * The server refused a new chat's id because it is already TAKEN (409
+ * `conversation_already_exists`, run-ai-stream): a reserved id another tab
+ * already sent with, or one kept past a send. Retrying the same id can never
+ * succeed.
+ */
+export declare function isConversationIdTaken(error: {
+    message?: unknown;
+    error_type?: unknown;
+} | undefined): boolean;
 export interface CanvasWorkspaceConversationController {
     conversation: CanvasWorkspaceConversation;
     /** The id when ready, else null. */