@agent-native/core 0.72.1 → 0.72.3

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 1160
-- template files: 4005
+- template files: 4008

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @agent-native/core
 
+## 0.72.3
+
+### Patch Changes
+
+- 6605885: Add opt-in URL sync for durable chat threads and route chat-first templates (chat, assets, and Dispatch) through `/chat/:threadId` deep links.
+
+## 0.72.2
+
+### Patch Changes
+
+- cc21a1c: Build the audit-redaction test fixture from concatenated parts so Netlify's
+  secret scanner no longer flags a literal `sk-` token pattern and blocks the
+  deploy.
+
 ## 0.72.1
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.72.1",
+  "version": "0.72.3",
   "type": "module",
   "engines": {
     "node": ">=22"

package/corpus/core/src/client/AgentPanel.tsx

@@ -75,7 +75,10 @@ const MultiTabAssistantChatLazy = lazy(() =>
     default: m.MultiTabAssistantChat,
   })),
 );
-import type { MultiTabAssistantChatHeaderProps } from "./MultiTabAssistantChat.js";
+import type {
+  MultiTabAssistantChatHeaderProps,
+  MultiTabAssistantChatProps,
+} from "./MultiTabAssistantChat.js";
 import type { AssistantChatProps } from "./AssistantChat.js";
 import { assistantUiRecoverableRenderErrorKind } from "./assistant-ui-recovery.js";
 import { useDevMode } from "./use-dev-mode.js";
@@ -518,6 +521,8 @@ export interface AgentPanelProps extends Omit<
   scope?: import("./use-chat-threads.js").ChatThreadScope | null;
   /** Stable browser tab id used for tab-scoped app-state context. */
   browserTabId?: string;
+  /** Keep chat thread selection in URL state. */
+  threadUrlSync?: MultiTabAssistantChatProps["threadUrlSync"];
   /** Optional notice rendered below the main header while Chat mode is active. */
   chatNotice?: React.ReactNode;
   /** Show the chat thread tab row when the panel header is hidden. Default: true. */
@@ -636,6 +641,7 @@ function AgentPanelInner({
   restoreActiveThread = true,
   scope,
   browserTabId,
+  threadUrlSync,
   chatNotice,
   showTabBar = true,
   codeAccess,
@@ -1589,6 +1595,7 @@ function AgentPanelInner({
               restoreActiveThread={restoreActiveThread}
               scope={scope}
               browserTabId={browserTabId}
+              threadUrlSync={threadUrlSync}
             />
           </Suspense>
         )}
@@ -2240,6 +2247,8 @@ export interface AgentSidebarProps {
   scope?: import("./use-chat-threads.js").ChatThreadScope | null;
   /** Stable browser tab id used for tab-scoped app-state context. */
   browserTabId?: string;
+  /** Keep chat thread selection in URL state. */
+  threadUrlSync?: MultiTabAssistantChatProps["threadUrlSync"];
 }
 
 /**
@@ -2262,6 +2271,7 @@ export function AgentSidebar({
   onFullscreenRequest,
   scope,
   browserTabId,
+  threadUrlSync,
 }: AgentSidebarProps) {
   const initialWidth = defaultSidebarWidth ?? sidebarWidth ?? 380;
   const [open, setOpen] = useState(() =>
@@ -2730,6 +2740,7 @@ export function AgentSidebar({
           storageKey={storageKey}
           scope={scope}
           browserTabId={browserTabId}
+          threadUrlSync={threadUrlSync}
         />
       </div>
       {showResizeHandle && isLeft && (

package/corpus/core/src/client/MultiTabAssistantChat.tsx

@@ -38,7 +38,7 @@ import {
   type ChatThreadScope,
   type ChatThreadSummary,
 } from "./use-chat-threads.js";
-import { agentNativePath } from "./api-path.js";
+import { agentNativePath, appPath } from "./api-path.js";
 import { callAction } from "./use-action.js";
 import { RunStuckBanner } from "./RunStuckBanner.js";
 import { DEFAULT_MODEL } from "../agent/default-model.js";
@@ -781,6 +781,107 @@ function chatTabStatusFromAgentTeamStatus(
 }
 
 const STALE_THREAD_THRESHOLD_MS = 12 * 60 * 60 * 1000;
+const DEFAULT_THREAD_URL_PARAM = "thread";
+const THREAD_URL_CHANGED_EVENT = "agent-chat:url-thread-changed";
+const hasOwn = Object.prototype.hasOwnProperty;
+
+// The history patch is installed once and shared via a ref count so that
+// multiple synced chats (or a remount) don't restore a stale `pushState`
+// reference and silently drop a wrapper installed by another instance.
+let historyPatchRefCount = 0;
+let restoreHistoryPatch: (() => void) | null = null;
+
+function installHistoryThreadUrlPatch(): () => void {
+  if (typeof window === "undefined") return () => {};
+  historyPatchRefCount += 1;
+  if (historyPatchRefCount === 1) {
+    const originalPushState = window.history.pushState;
+    const originalReplaceState = window.history.replaceState;
+    const dispatchUrlChange = () => {
+      window.dispatchEvent(new Event(THREAD_URL_CHANGED_EVENT));
+    };
+    window.history.pushState = function pushState(...args) {
+      const result = originalPushState.apply(this, args);
+      dispatchUrlChange();
+      return result;
+    };
+    window.history.replaceState = function replaceState(...args) {
+      const result = originalReplaceState.apply(this, args);
+      dispatchUrlChange();
+      return result;
+    };
+    restoreHistoryPatch = () => {
+      window.history.pushState = originalPushState;
+      window.history.replaceState = originalReplaceState;
+    };
+  }
+  return () => {
+    historyPatchRefCount = Math.max(0, historyPatchRefCount - 1);
+    if (historyPatchRefCount === 0) {
+      restoreHistoryPatch?.();
+      restoreHistoryPatch = null;
+    }
+  };
+}
+
+export interface ChatThreadUrlSyncOptions {
+  /** Query-string parameter used by the generic URL adapter. Default: `thread`. */
+  paramName?: string;
+  /**
+   * Route-owned thread id. Pass `null` for the create route and a string for
+   * thread routes like `/chat/:threadId`.
+   */
+  routeThreadId?: string | null;
+  /** Build the URL path for a thread id, or for create mode when id is null. */
+  getPath?: (threadId: string | null) => string;
+  /** Optional router navigation callback used with `getPath`. */
+  navigate?: (path: string, options?: { replace?: boolean }) => void;
+}
+
+function normalizeUrlThreadId(value: string | null | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+function resolveThreadUrlSync(
+  value: MultiTabAssistantChatProps["threadUrlSync"],
+): {
+  enabled: boolean;
+  paramName: string;
+  routeThreadId?: string | null;
+  getPath?: (threadId: string | null) => string;
+  navigate?: (path: string, options?: { replace?: boolean }) => void;
+} {
+  if (!value) return { enabled: false, paramName: DEFAULT_THREAD_URL_PARAM };
+  if (value === true) {
+    return { enabled: true, paramName: DEFAULT_THREAD_URL_PARAM };
+  }
+  return {
+    enabled: true,
+    paramName: value.paramName?.trim() || DEFAULT_THREAD_URL_PARAM,
+    ...(hasOwn.call(value, "routeThreadId")
+      ? { routeThreadId: normalizeUrlThreadId(value.routeThreadId) }
+      : {}),
+    ...(value.getPath ? { getPath: value.getPath } : {}),
+    ...(value.navigate ? { navigate: value.navigate } : {}),
+  };
+}
+
+function readUrlThreadId(paramName: string): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const params = new URLSearchParams(window.location.search);
+    return normalizeUrlThreadId(
+      params.get(paramName) ??
+        (paramName === DEFAULT_THREAD_URL_PARAM
+          ? params.get("threadId")
+          : null),
+    );
+  } catch {
+    return null;
+  }
+}
 
 function runToAgentTeamTabInfo(
   run: AgentTeamRunSummary,
@@ -845,6 +946,12 @@ export type MultiTabAssistantChatProps = Omit<
   restoreActiveThread?: boolean;
   /** Stable browser tab id used for tab-scoped app-state context. */
   browserTabId?: string;
+  /**
+   * Keep the active thread in URL state. `true` uses the generic `?thread=id`
+   * adapter; passing `routeThreadId` + `getPath` lets an app bind chats to
+   * route params such as `/chat/:threadId`.
+   */
+  threadUrlSync?: boolean | ChatThreadUrlSyncOptions;
   /**
    * Bind new chats to a resource (deck, design, dashboard, etc.). When set,
    * new chats automatically inherit this scope and scoped chats tuck away when
@@ -864,15 +971,114 @@ export function MultiTabAssistantChat({
   storageKey,
   restoreActiveThread = true,
   browserTabId,
+  threadUrlSync = false,
   scope = null,
   ...props
 }: MultiTabAssistantChatProps) {
+  const {
+    enabled: threadUrlSyncEnabled,
+    paramName: threadUrlParamName,
+    routeThreadId,
+    getPath: getThreadPath,
+    navigate: navigateThreadUrl,
+  } = resolveThreadUrlSync(threadUrlSync);
+  const threadRouteControlsActiveThread =
+    threadUrlSyncEnabled &&
+    threadUrlSync !== true &&
+    typeof threadUrlSync === "object" &&
+    hasOwn.call(threadUrlSync, "routeThreadId");
+  const [urlThreadId, setUrlThreadId] = useState<string | null>(() =>
+    threadUrlSyncEnabled
+      ? threadRouteControlsActiveThread
+        ? (routeThreadId ?? null)
+        : readUrlThreadId(threadUrlParamName)
+      : null,
+  );
+  const urlThreadIdRef = useRef(urlThreadId);
+  urlThreadIdRef.current = urlThreadId;
+
+  useEffect(() => {
+    if (!threadUrlSyncEnabled || threadRouteControlsActiveThread) return;
+    const update = () => setUrlThreadId(readUrlThreadId(threadUrlParamName));
+    const uninstallHistoryPatch = installHistoryThreadUrlPatch();
+    update();
+    window.addEventListener("popstate", update);
+    window.addEventListener(THREAD_URL_CHANGED_EVENT, update);
+    return () => {
+      uninstallHistoryPatch();
+      window.removeEventListener("popstate", update);
+      window.removeEventListener(THREAD_URL_CHANGED_EVENT, update);
+    };
+  }, [
+    threadRouteControlsActiveThread,
+    threadUrlParamName,
+    threadUrlSyncEnabled,
+  ]);
+
+  useEffect(() => {
+    if (!threadUrlSyncEnabled || !threadRouteControlsActiveThread) return;
+    setUrlThreadId(routeThreadId ?? null);
+  }, [routeThreadId, threadRouteControlsActiveThread, threadUrlSyncEnabled]);
+
+  const writeThreadUrl = useCallback(
+    (threadId: string | null, options: { replace?: boolean } = {}): void => {
+      if (!threadUrlSyncEnabled || typeof window === "undefined") return;
+      try {
+        const normalizedThreadId = normalizeUrlThreadId(threadId);
+        let next: string;
+        if (getThreadPath) {
+          next = getThreadPath(normalizedThreadId);
+        } else {
+          const url = new URL(window.location.href);
+          if (normalizedThreadId) {
+            url.searchParams.set(threadUrlParamName, normalizedThreadId);
+          } else {
+            url.searchParams.delete(threadUrlParamName);
+          }
+          if (threadUrlParamName !== "threadId") {
+            url.searchParams.delete("threadId");
+          }
+          next = `${url.pathname}${url.search}${url.hash}`;
+        }
+        const current = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+        if (next === current) {
+          setUrlThreadId(normalizedThreadId);
+          return;
+        }
+        if (getThreadPath && navigateThreadUrl) {
+          navigateThreadUrl(next, { replace: options.replace === true });
+          setUrlThreadId(normalizedThreadId);
+          return;
+        }
+        const method = options.replace ? "replaceState" : "pushState";
+        // `getThreadPath` returns a router-local path (no app basename). When we
+        // fall back to the raw History API instead of a router navigate, resolve
+        // the basename so deep-link reloads work in mounted apps.
+        const historyTarget = getThreadPath ? appPath(next) : next;
+        window.history[method](window.history.state, "", historyTarget);
+        setUrlThreadId(normalizedThreadId);
+        window.dispatchEvent(new Event(THREAD_URL_CHANGED_EVENT));
+        const popstate =
+          typeof PopStateEvent === "function"
+            ? new PopStateEvent("popstate", { state: window.history.state })
+            : new Event("popstate");
+        window.dispatchEvent(popstate);
+      } catch {}
+    },
+    [
+      getThreadPath,
+      navigateThreadUrl,
+      threadUrlParamName,
+      threadUrlSyncEnabled,
+    ],
+  );
+
   const {
     threads,
     activeThreadId,
     isLoading,
     createThread,
-    switchThread,
+    switchThread: switchThreadState,
     detachThread,
     forkThread,
     saveThreadData,
@@ -880,7 +1086,18 @@ export function MultiTabAssistantChat({
     searchThreads,
     refreshThreads,
     isNewThread,
-  } = useChatThreads(apiUrl, storageKey, scope, { restoreActiveThread });
+  } = useChatThreads(apiUrl, storageKey, scope, {
+    restoreActiveThread,
+    routeThreadId: threadUrlSyncEnabled ? urlThreadId : undefined,
+  });
+
+  const switchThread = useCallback(
+    (threadId: string, options: { replace?: boolean } = {}) => {
+      switchThreadState(threadId);
+      writeThreadUrl(threadId, options);
+    },
+    [switchThreadState, writeThreadUrl],
+  );
 
   // Namespace all localStorage keys by storageKey when provided (for per-app isolation in frame)
   const keyPrefix = storageKey ? `:${storageKey}` : "";
@@ -1370,9 +1587,18 @@ export function MultiTabAssistantChat({
 
     // If active thread is stale, start fresh
     if (!parentMap[activeThreadId] && isStale(activeThreadId)) {
-      createThread();
+      createThread().then((id) => {
+        if (id) writeThreadUrl(null);
+      });
     }
-  }, [activeThreadId, threads, parentMap, switchThread, createThread]);
+  }, [
+    activeThreadId,
+    threads,
+    parentMap,
+    switchThread,
+    createThread,
+    writeThreadUrl,
+  ]);
 
   // Ensure active thread is always in open tabs.
   // Use functional update to check inside the setter — avoids race with the
@@ -1412,10 +1638,11 @@ export function MultiTabAssistantChat({
         if (id) {
           newThreadIds.current.add(id);
           setOpenTabIds([id]);
+          writeThreadUrl(null, { replace: true });
         }
       });
     }
-  }, [isLoading, openTabIds, activeThreadId, createThread]);
+  }, [isLoading, openTabIds, activeThreadId, createThread, writeThreadUrl]);
 
   useEffect(() => {
     let stopped = false;
@@ -1700,9 +1927,12 @@ export function MultiTabAssistantChat({
             setOpenTabIds((prev) =>
               prev.includes(newId) ? prev : [...prev, newId],
             );
+            if (!background) {
+              writeThreadUrl(newId);
+            }
             sendToTab(newId);
             if (background && previousTabId) {
-              switchThread(previousTabId);
+              switchThreadState(previousTabId);
             }
           }
         });
@@ -1729,6 +1959,8 @@ export function MultiTabAssistantChat({
     removeContextInTab,
     setContextInTab,
     switchThread,
+    switchThreadState,
+    writeThreadUrl,
   ]);
 
   // Replay submits posted before this lazy panel's listener attached. Dedup in
@@ -1800,9 +2032,10 @@ export function MultiTabAssistantChat({
     const id = await createThread();
     if (id) {
       newThreadIds.current.add(id);
+      writeThreadUrl(null);
     }
     return id;
-  }, [createThread]);
+  }, [createThread, writeThreadUrl]);
 
   const cleanupClosedTab = useCallback((tabId: string) => {
     if (parentMapRef.current[tabId]) {
@@ -1842,6 +2075,7 @@ export function MultiTabAssistantChat({
             if (newId) {
               newThreadIds.current.add(newId);
               setOpenTabIds([newId]);
+              writeThreadUrl(null);
             }
           });
           return prev; // Keep old tab until new one is ready
@@ -1855,7 +2089,7 @@ export function MultiTabAssistantChat({
       });
       cleanupClosedTab(tabId);
     },
-    [switchThread, createThread, cleanupClosedTab],
+    [switchThread, createThread, cleanupClosedTab, writeThreadUrl],
   );
 
   const closeOtherTabs = useCallback(
@@ -1906,7 +2140,8 @@ export function MultiTabAssistantChat({
     if (id) {
       newThreadIds.current.add(id);
       setOpenTabIds([id]);
-      switchThread(id);
+      switchThreadState(id);
+      writeThreadUrl(null);
       dismissedSubAgentTabsRef.current.clear();
       // Clean up all old refs
       chatRefs.current.clear();
@@ -1917,7 +2152,7 @@ export function MultiTabAssistantChat({
       setSubAgentNames({});
       setSubAgentStatuses({});
     }
-  }, [createThread, switchThread]);
+  }, [createThread, switchThreadState, writeThreadUrl]);
 
   // Keyboard shortcuts dispatched from AgentPanel based on the active mode
   useEffect(() => {
@@ -1955,6 +2190,14 @@ export function MultiTabAssistantChat({
 
       if (detail?.newThread === true) {
         newThreadIds.current.add(threadId);
+        void createThread(threadId).then((createdId) => {
+          if (!createdId) return;
+          setOpenTabIds((prev) =>
+            prev.includes(createdId) ? prev : [...prev, createdId],
+          );
+          writeThreadUrl(null);
+        });
+        return;
       }
       setOpenTabIds((prev) =>
         prev.includes(threadId) ? prev : [...prev, threadId],
@@ -1965,7 +2208,7 @@ export function MultiTabAssistantChat({
     window.addEventListener("agent-chat:open-thread", handleOpenThread);
     return () =>
       window.removeEventListener("agent-chat:open-thread", handleOpenThread);
-  }, [switchThread]);
+  }, [createThread, switchThread, writeThreadUrl]);
 
   const clearActiveTab = useCallback(() => {
     const tabIdToClear = activeThreadIdRef.current;
@@ -2125,8 +2368,15 @@ export function MultiTabAssistantChat({
       },
     ) => {
       saveThreadData(threadId, data);
+      if (
+        data.messageCount > 0 &&
+        threadId === activeThreadIdRef.current &&
+        urlThreadIdRef.current !== threadId
+      ) {
+        writeThreadUrl(threadId);
+      }
     },
-    [saveThreadData],
+    [saveThreadData, writeThreadUrl],
   );
 
   // ─── Slash command handler ──────────────────────────────────────────

package/corpus/core/src/client/use-agent-chat-home-handoff.ts

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { useLocation, useNavigate } from "react-router";
 import { appBasePath } from "./api-path.js";
 import {
@@ -21,6 +21,12 @@ export interface UseAgentChatHomeHandoffLinksOptions {
   storageKey?: string | null;
   /** Router-local path for the full-page chat route. Defaults to "/". */
   chatPath?: string;
+  /**
+   * Matches every router-local pathname owned by the full-page chat surface.
+   * Defaults to an exact match against `chatPath`. Pass this to cover deep
+   * links such as `/chat/:threadId`.
+   */
+  isChatPath?: (pathname: string) => boolean;
   /** Disable link interception without changing hook call order. */
   enabled?: boolean;
 }
@@ -120,13 +126,19 @@ export function useAgentChatHomeHandoff({
 export function useAgentChatHomeHandoffLinks({
   storageKey,
   chatPath = "/",
+  isChatPath,
   enabled = true,
 }: UseAgentChatHomeHandoffLinksOptions): void {
   const location = useLocation();
   const navigate = useNavigate();
+  const matchesChatPathRef = useRef<(pathname: string) => boolean>(() => false);
+  matchesChatPathRef.current =
+    isChatPath ?? ((pathname: string) => pathname === chatPath);
 
   useEffect(() => {
-    if (!enabled || stripBasePath(location.pathname) !== chatPath) return;
+    const matchesChatPath = (pathname: string) =>
+      matchesChatPathRef.current(pathname);
+    if (!enabled || !matchesChatPath(stripBasePath(location.pathname))) return;
     if (typeof document === "undefined") return;
 
     function handleClick(event: MouseEvent) {
@@ -141,7 +153,7 @@ export function useAgentChatHomeHandoffLinks({
       const pathname = path ? pathnameFromLocalPath(path) : "";
       if (
         !path ||
-        pathname === chatPath ||
+        matchesChatPath(pathname) ||
         isFrameworkOrApiPath(pathname) ||
         isStaticAssetPath(pathname)
       ) {
@@ -155,5 +167,5 @@ export function useAgentChatHomeHandoffLinks({
 
     document.addEventListener("click", handleClick, true);
     return () => document.removeEventListener("click", handleClick, true);
-  }, [chatPath, enabled, location.pathname, navigate, storageKey]);
+  }, [enabled, location.pathname, navigate, storageKey]);
 }