@ai-matrx/chat 0.4.15 → 0.4.16

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ai-matrx/chat
 
+## 0.4.16 — the Side Chat's URL contract
+
+- ONE param family on every home opens, closes and aims the Side Chat (the shell chat dock):
+  `side_chat` = `open` | `closed` | `new` | `<conversation uuid>`; `side_chat_agent` =
+  `<agent uuid>` | `mandate:<key>`; `side_chat_mode` = `chat` | `work` | `advanced`. The link wins
+  over the remembered conversation, the family cookie and the defaults for its visit, and never
+  writes the person's open / closed choice. Invalid values are ignored with a `[side-chat]` warning.
+- After reading, the one-shot params are consumed; the address names the shown conversation as
+  `side_chat=<uuid>` while the panel is open, and drops it when the person closes the panel.
+- `/chat` and `/code` show the Side Chat when (and only when) a `side_chat*` param asks.
+- New module `canvas/workspace/side-chat-address` (`readSideChatLink`, `sideChatOpen`,
+  `addressAfterSideChatLink`, `sideChatAddress`, `sideChatSignature`, the param names).
+- Removed (no legacy): `?pageChat=` and the boards / Education `?chat=`, `ShellChatHome.addressParam`,
+  `conversationInAddress`, `addressWithConversation`; `useCanvasWorkspaceConversation`'s
+  `addressParam` option is now `address: { link, open, hostedElsewhere, onWrite? }`.
+
+Consumer action: any link that opened the dock with `?pageChat=<id>` or a board's / Education's
+`?chat=<id>` now writes `?side_chat=<id>` (matrx-frontend: `continueWithAgentHref`). A host calling
+`useCanvasWorkspaceConversation` with `addressParam` passes `address` instead.
+
 ## 0.4.15
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

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,6 @@ 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;
 export interface CanvasWorkspaceConversationController {
     conversation: CanvasWorkspaceConversation;
     /** The id when ready, else null. */

package/dist/canvas/workspace/useCanvasWorkspaceConversation.js

@@ -9,6 +9,7 @@ import { selectShouldPromptForOrganization } from "../../host/ui-slots.js";
 import { selectIsCacheOnly } from "../../agents/redux/execution-system/conversations/conversations.selectors.js";
 import { replaceAddressWithoutNavigating } from "@ai-matrx/rich-content/utils/addressWithoutNavigating";
 import { describeLaunchError } from "./describe-launch-error.js";
+import { sideChatAddress } from "./side-chat-address.js";
 import { selectOrganizationId, ensureOrganizationContext, isOrganizationSelectionCancelled } from "../../host/org.js";
 function initialRequest(start) {
   if (start?.kind === "agent") return { kind: "agent", agentId: start.agentId, nonce: 0 };
@@ -16,9 +17,13 @@ function initialRequest(start) {
     return { kind: "open", conversationId: start.conversationId, agentId: start.agentId ?? null, nonce: 0 };
   return { kind: "new", nonce: 0 };
 }
-function conversationInAddress(param, search) {
-  const value = new URLSearchParams(search).get(param);
-  return value && isUuidShape(value) ? value : null;
+function requestFromLink(link) {
+  const c = link?.conversation;
+  if (!c) return null;
+  if (c.kind === "new") return { kind: "new", nonce: 1 };
+  if (c.kind === "agent") return { kind: "agent", agentId: c.agentId, nonce: 1 };
+  if (c.kind === "mandate") return { kind: "new", nonce: 1, mandateKey: c.mandateKey };
+  return { kind: "open", conversationId: c.conversationId, agentId: null, nonce: 0 };
 }
 function workspaceChatMemoryKey(surfaceKey) {
   return `matrx:workspace-chat:${surfaceKey}`;
@@ -60,29 +65,30 @@ function releaseWorkspaceConversationId(surfaceKey) {
   } catch {
   }
 }
-function addressWithConversation(param, search, conversationId) {
-  const params = new URLSearchParams(search);
-  if (conversationId) params.set(param, conversationId);
-  else params.delete(param);
-  const qs = params.toString();
-  return qs ? `?${qs}` : "";
-}
 function isCanvasWorkspaceStart(input) {
   return "kind" in input;
 }
 function resolveStartOptions(input) {
-  if (!input) return { enabled: true, start: void 0, ownSurface: false, addressParam: null };
+  if (!input) return { enabled: true, start: void 0, ownSurface: false, address: null };
   if (isCanvasWorkspaceStart(input))
-    return { enabled: true, start: input, ownSurface: false, addressParam: null };
+    return { enabled: true, start: input, ownSurface: false, address: null };
   return {
     enabled: input.enabled ?? true,
     start: input.start,
     ownSurface: input.surfaceName === null,
-    addressParam: input.addressParam ?? null
+    address: input.address ?? null
   };
 }
 function useCanvasWorkspaceConversation(surfaceKey, input) {
-  const { enabled, start, ownSurface, addressParam } = resolveStartOptions(input);
+  const { enabled, start, ownSurface, address } = resolveStartOptions(input);
+  const hasAddress = address !== null;
+  const link = address?.link;
+  const addressOpen = address?.open ?? false;
+  const hostedElsewhere = address?.hostedElsewhere ?? false;
+  const onAddressWrite = useRef(address?.onWrite);
+  useEffect(() => {
+    onAddressWrite.current = address?.onWrite;
+  });
   const dispatch = useAppDispatch();
   const { launchMandate, launchAgent } = useAgentLauncher();
   const [request, setRequest] = useState(() => initialRequest(start));
@@ -92,39 +98,57 @@ function useCanvasWorkspaceConversation(surfaceKey, input) {
   const organizationId = useAppSelector(selectOrganizationId);
   const promptForOrganization = useAppSelector(selectShouldPromptForOrganization);
   const waitingForOrganization = request.kind !== "open" && !organizationId;
-  const [addressRead, setAddressRead] = useState(addressParam === null);
+  const [addressRead, setAddressRead] = useState(!hasAddress);
+  const appliedLink = useRef(null);
   const serverHasIt = useAppSelector(
     (state) => conversationId ? !selectIsCacheOnly(conversationId)(state) : false
   );
-  const [keyedFor, setKeyedFor] = useState({ surfaceKey, addressParam });
-  if (keyedFor.surfaceKey !== surfaceKey || keyedFor.addressParam !== addressParam) {
-    setKeyedFor({ surfaceKey, addressParam });
+  const [keyedFor, setKeyedFor] = useState({ surfaceKey, hasAddress });
+  if (keyedFor.surfaceKey !== surfaceKey || keyedFor.hasAddress !== hasAddress) {
+    setKeyedFor({ surfaceKey, hasAddress });
     setRequest(initialRequest(start));
     setConversationId(null);
     setFailure(null);
-    setAddressRead(addressParam === null);
+    setAddressRead(!hasAddress);
   }
   useEffect(() => {
-    if (addressRead || addressParam === null) return;
-    const named = conversationInAddress(addressParam, window.location.search);
-    const recalled = named ? null : recallWorkspaceConversation(surfaceKey);
-    const target = named ?? recalled;
-    if (target && !start) {
-      setRequest(
-        (current) => current.kind === "new" && current.nonce === 0 ? { kind: "open", conversationId: target, agentId: null, nonce: 0, recalled: !named } : current
-      );
+    if (addressRead || !hasAddress || link === void 0) return;
+    appliedLink.current = link;
+    const linked = requestFromLink(link);
+    if (linked && !start) setRequest(linked);
+    else if (!start) {
+      const recalled = recallWorkspaceConversation(surfaceKey);
+      if (recalled) {
+        setRequest(
+          (current) => current.kind === "new" && current.nonce === 0 ? { kind: "open", conversationId: recalled, agentId: null, nonce: 0, recalled: true } : current
+        );
+      }
     }
     setAddressRead(true);
-  }, [addressRead, addressParam, start, surfaceKey]);
+  }, [addressRead, hasAddress, link, start, surfaceKey]);
   useEffect(() => {
-    if (addressParam === null || !addressRead || !conversationId) return;
-    const shown = request.kind === "open" || serverHasIt ? conversationId : null;
-    rememberWorkspaceConversation(surfaceKey, shown);
-    if (shown) releaseWorkspaceConversationId(surfaceKey);
-    const search = addressWithConversation(addressParam, window.location.search, shown);
+    if (!addressRead || !link || link === appliedLink.current) return;
+    appliedLink.current = link;
+    const linked = requestFromLink(link);
+    if (!linked) return;
+    if (linked.kind === "open" && linked.conversationId === conversationId) return;
+    setConversationId(null);
+    setFailure(null);
+    setRequest((current) => ({ ...linked, nonce: current.nonce + 1 }));
+  }, [addressRead, link, conversationId]);
+  useEffect(() => {
+    if (!hasAddress || !addressRead) return;
+    if (!conversationId && addressOpen) return;
+    const shown = conversationId && (request.kind === "open" || serverHasIt) ? conversationId : null;
+    if (conversationId) {
+      rememberWorkspaceConversation(surfaceKey, shown);
+      if (shown) releaseWorkspaceConversationId(surfaceKey);
+    }
+    const search = sideChatAddress(window.location.search, { conversationId: shown, open: addressOpen, hostedElsewhere });
     if (search === window.location.search) return;
+    onAddressWrite.current?.(search);
     replaceAddressWithoutNavigating(`${window.location.pathname}${search}${window.location.hash}`);
-  }, [addressParam, addressRead, conversationId, request.kind, serverHasIt, surfaceKey]);
+  }, [hasAddress, addressRead, addressOpen, hostedElsewhere, conversationId, request.kind, serverHasIt, surfaceKey]);
   useEffect(() => {
     if (!enabled || waitingForOrganization || !addressRead) return;
     const key = `${surfaceKey}#${request.kind}#${request.nonce}`;
@@ -133,7 +157,7 @@ function useCanvasWorkspaceConversation(surfaceKey, input) {
     const stale = () => handled.current !== key;
     if (request.kind === "new" || request.kind === "agent") {
       const runtime = ownSurface ? { runtime: { surfaceName: null } } : {};
-      const reserved = addressParam !== null ? reserveWorkspaceConversationId(surfaceKey, request.nonce > 0) : void 0;
+      const reserved = hasAddress ? reserveWorkspaceConversationId(surfaceKey, request.nonce > 0) : void 0;
       const reservation = reserved ? { conversationId: reserved } : {};
       const launch = request.kind === "agent" ? launchAgent(request.agentId, { surfaceKey, sourceFeature: "chat", ...reservation, ...runtime }) : launchMandate(request.mandateKey ?? DEFAULT_NEW_CHAT_MANDATE_KEY, {
         surfaceKey,
@@ -215,8 +239,6 @@ function useCanvasWorkspaceConversation(surfaceKey, input) {
   return { conversation, conversationId, startNew, openExisting, startWith };
 }
 export {
-  addressWithConversation,
-  conversationInAddress,
   recallWorkspaceConversation,
   releaseWorkspaceConversationId,
   rememberWorkspaceConversation,

package/dist/host/db-types.d.ts

@@ -28706,6 +28706,15 @@ export type ChatDatabase = {
                 };
                 Returns: Json;
             };
+            _knob_steward_refusal: {
+                Args: {
+                    p_organization_id: string;
+                    p_scope_id: string;
+                    p_scope_kind: string;
+                    p_uid: string;
+                };
+                Returns: Json;
+            };
             _lifecycle_partition_guard: {
                 Args: {
                     p_partition: string;
@@ -43832,18 +43841,6 @@ export type ChatDatabase = {
                 };
                 Returns: Json;
             };
-            mnd_run_history: {
-                Args: {
-                    p_limit?: number;
-                    p_mandate_key: string;
-                    p_offset?: number;
-                    p_org_id?: string;
-                    p_status?: string;
-                    p_user_id?: string;
-                    p_view?: string;
-                };
-                Returns: Json;
-            };
             move_file: {
                 Args: {
                     p_file_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/chat",
-  "version": "0.4.15",
+  "version": "0.4.16",
   "description": "THE one AI Matrx person-to-agent chat system: the full chat (running agents, conversations, tool calls, streaming, context, surfaces, voice) as per-module subpaths @ai-matrx/chat/<domain>/<module> over a host contract (/host, /host/react) whose only required value is a db; plus the kernel compatibility entries (., /external-store, /matrx, /react, /tools, styles.css, tokens.css) until P28.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -228,24 +228,24 @@
     "zod": "^4.6.5",
     "@ai-matrx/agents": "latest",
     "@ai-matrx/alchemy": "latest",
-    "@ai-matrx/associations": "latest",
     "@ai-matrx/browser-audio": "latest",
     "@ai-matrx/canvas": "latest",
     "@ai-matrx/content-ir": "latest",
+    "@ai-matrx/content-ir-react": "latest",
+    "@ai-matrx/associations": "latest",
     "@ai-matrx/data": "latest",
-    "@ai-matrx/design-system": "latest",
-    "@ai-matrx/diff": "latest",
-    "@ai-matrx/icons": "latest",
     "@ai-matrx/kit": "latest",
+    "@ai-matrx/design-system": "latest",
     "@ai-matrx/media": "latest",
+    "@ai-matrx/icons": "latest",
     "@ai-matrx/print": "latest",
     "@ai-matrx/realtime": "latest",
+    "@ai-matrx/records": "latest",
     "@ai-matrx/records-ui": "latest",
     "@ai-matrx/rich-content": "latest",
-    "@ai-matrx/rich-editor": "latest",
+    "@ai-matrx/diff": "latest",
     "@ai-matrx/tap-target": "latest",
-    "@ai-matrx/records": "latest",
-    "@ai-matrx/content-ir-react": "latest"
+    "@ai-matrx/rich-editor": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",