@iloveagents/foundry-web-shell 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @iloveagents/foundry-web-shell
 
+## 0.2.0
+
+### Minor Changes
+
+- shell: ChatConversationConfig API + sticky-runtime threadId
+
+  Lets a downstream module (e.g. `@ltwlf/spaces-web-ui`) attach a
+  `ChatConversationConfig` to its `ChatModule`. The shell then:
+  - Pre-mints a fresh thread UUID via `useRef` so the AG-UI runtime's
+    `threadId` is defined from first render — no `undefined → defined`
+    remount mid-conversation when the user sends the first message.
+  - Calls `config.useStickyConversationId()` (when declared) and
+    feeds the resulting id into the runtime so the chat stays "live"
+    while the user browses non-chat routes (Workspaces, Jobs, etc.).
+  - Per-config keyed child components (`StickyAwareRuntime` vs
+    `UrlOnlyRuntime`) so optional hooks satisfy Rules-of-Hooks across
+    multi-module config swaps.
+
+### Patch Changes
+
+- Move `@iloveagents/foundry-agent`, `-web-primitives`, `-web-ui` from
+  `peerDependencies` to `dependencies`. They always ship together as a
+  coordinated fixed group from this monorepo — they were never
+  independently-versioned peers. Declaring them as peerDeps caused
+  changesets' `shouldBumpMajor` cascade to promote the entire group to
+  a major version on every minor changeset. See the root `foundry-agent`
+  CHANGELOG entry for details.
+
+- Updated dependencies
+  - @iloveagents/foundry-web-ui@0.2.0
+  - @iloveagents/foundry-agent@0.2.0
+  - @iloveagents/foundry-web-primitives@0.2.0
+
+### NOTE: 1.0.1 was accidental
+
+Version 1.0.1 was published briefly on 2026-05-27 due to the peerDep
+cascade bug described above (1.0.0 was reserved but not published —
+1.0.1 was the retry). It has been unpublished. Both 1.0.0 and 1.0.1
+are now permanently reserved on npm and CANNOT be re-published. Do
+not depend on 1.0.x.
+
 ## 0.1.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-web-shell",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "types": "./src/index.ts",
@@ -16,10 +16,12 @@
     "react-router": "^7.0.0",
     "@assistant-ui/react": "^0.12.25",
     "lucide-react": ">=0.400.0",
-    "zustand": "^5.0.0",
-    "@iloveagents/foundry-agent": "0.1.5",
-    "@iloveagents/foundry-web-primitives": "0.1.5",
-    "@iloveagents/foundry-web-ui": "0.1.5"
+    "zustand": "^5.0.0"
+  },
+  "dependencies": {
+    "@iloveagents/foundry-web-primitives": "0.2.0",
+    "@iloveagents/foundry-web-ui": "0.2.0",
+    "@iloveagents/foundry-agent": "0.2.0"
   },
   "devDependencies": {
     "typescript": "~5.9.3",

package/src/index.ts

@@ -6,6 +6,7 @@ export { defaultAgentFetch } from "./service-fetch-default.ts";
 export { defineChatModule } from "./types.ts";
 export type {
   ChatModule,
+  ChatConversationConfig,
   ShellPage,
   AuthAdapter,
   BootstrapShellOptions,

package/src/shell-app.tsx

@@ -1,8 +1,12 @@
-import { type ReactNode, Suspense, useMemo } from "react";
-import { BrowserRouter, Routes, Route } from "react-router";
+import { type ReactNode, Suspense, useCallback, useMemo, useRef } from "react";
+import { BrowserRouter, Routes, Route, useLocation } from "react-router";
 import { AGUIRuntimeProvider } from "@iloveagents/foundry-web-ui";
+import type {
+  AGUIChatConversationFactoryArgs,
+  AGUIHistoryAdapterFactory,
+} from "@iloveagents/foundry-web-ui";
 import type { ThemeLayer } from "@iloveagents/foundry-web-ui";
-import type { ChatModule, AuthAdapter, ShellPage } from "./types.ts";
+import type { ChatConversationConfig, ChatModule, AuthAdapter, ShellPage } from "./types.ts";
 import { ShellAuth } from "./auth-default.tsx";
 import { ShellLayout } from "./shell-layout.tsx";
 import { defaultAgentFetch } from "./service-fetch-default.ts";
@@ -65,12 +69,22 @@ export function ShellApp({
 
   const fetchFn = agentFetch ?? defaultAgentFetch;
 
+  // Aggregate chatConversation configs from all modules. First-match
+  // wins at URL-match time (rare to have more than one anyway).
+  const chatConversationConfigs = useMemo(
+    () => modules.flatMap((m) => (m.chatConversation ? [m.chatConversation] : [])),
+    [modules],
+  );
+
   return (
     <BrowserRouter>
       <ShellAuth adapter={authProvider}>
         <ComposedWrappers wrappers={wrappers}>
-          <AGUIRuntimeProvider fetchFn={fetchFn}>
-            {toolUIs}
+          <ChatConversationAwareRuntime
+            fetchFn={fetchFn}
+            configs={chatConversationConfigs}
+            toolUIs={toolUIs}
+          >
             <Suspense fallback={null}>
               <Routes>
                 <Route element={<ShellLayout modules={modules} baseThemeLayers={baseThemeLayers} />}>
@@ -80,17 +94,248 @@ export function ShellApp({
                 </Route>
               </Routes>
             </Suspense>
-          </AGUIRuntimeProvider>
+          </ChatConversationAwareRuntime>
         </ComposedWrappers>
       </ShellAuth>
     </BrowserRouter>
   );
 }
 
+/**
+ * Reads the current pathname (only meaningful inside ``<BrowserRouter>``),
+ * matches it against any module-declared :type:`ChatConversationConfig`,
+ * and hands the matched config + URL-extracted id down into
+ * :type:`AGUIRuntimeProvider` as a :type:`AGUIHistoryAdapterFactory`.
+ *
+ * Why a factory (not a pre-built adapter)
+ * =======================================
+ * The history adapter needs *both* the URL-extracted conversation id
+ * (when present) *and* the AG-UI adapter's freshly-minted thread id
+ * (always set — covers fresh chats). The AG-UI adapter only exists
+ * once :type:`AGUIRuntimeProvider` mounts, so the factory is invoked
+ * inside that mount with both pieces available. This makes "fresh
+ * chats also persist" a built-in property of the contract, not an
+ * afterthought.
+ */
+function ChatConversationAwareRuntime({
+  children,
+  toolUIs,
+  fetchFn,
+  configs,
+}: {
+  children: ReactNode;
+  toolUIs: ReactNode[];
+  fetchFn: typeof fetch;
+  configs: ChatConversationConfig[];
+}) {
+  const { pathname } = useLocation();
+
+  // Pick the matching config (URL-pattern match) OR fall back to the
+  // first config registered — modules without a URL match still want
+  // their fresh-chat persistence. With ≥1 config the runtime always
+  // gets a factory; without configs it stays in the legacy in-memory
+  // mode.
+  const { config, urlMatch } = useMemo(() => {
+    for (const cfg of configs) {
+      const m = pathname.match(cfg.pathPattern);
+      if (m && m[1]) {
+        return { config: cfg, urlMatch: m[1] };
+      }
+    }
+    return { config: configs[0], urlMatch: undefined as string | undefined };
+  }, [pathname, configs]);
+
+  if (!config) {
+    // No chatConversation configs registered → legacy in-memory
+    // runtime, no history / no sticky concerns.
+    return (
+      <AGUIRuntimeProvider fetchFn={fetchFn}>
+        {toolUIs}
+        {children}
+      </AGUIRuntimeProvider>
+    );
+  }
+
+  // Per-config child component, KEYED by config identity. Why a
+  // key/child split: ``config.useStickyConversationId`` is optional.
+  // Calling it inline with the optional chain ``config?.useSticky?.()``
+  // would be a Rules-of-Hooks violation the moment a second
+  // ChatConversationConfig registers with different hook-shape — URL
+  // navigation flips which cfg matches, the hook count flips, React
+  // crashes. The key makes a config swap a full remount, which is a
+  // legitimate way to change the hook lineage without violating the
+  // rules. ``configIndex`` is stable per config because ``configs`` is
+  // memoised in ShellApp.
+  const configIndex = configs.indexOf(config);
+  if (config.useStickyConversationId) {
+    return (
+      <StickyAwareRuntime
+        key={`sticky:${configIndex}`}
+        config={config}
+        useSticky={config.useStickyConversationId}
+        urlMatch={urlMatch}
+        fetchFn={fetchFn}
+        toolUIs={toolUIs}
+      >
+        {children}
+      </StickyAwareRuntime>
+    );
+  }
+  return (
+    <UrlOnlyRuntime
+      key={`url:${configIndex}`}
+      config={config}
+      urlMatch={urlMatch}
+      fetchFn={fetchFn}
+      toolUIs={toolUIs}
+    >
+      {children}
+    </UrlOnlyRuntime>
+  );
+}
+
+interface ChildRuntimeProps {
+  config: ChatConversationConfig;
+  urlMatch: string | undefined;
+  fetchFn: typeof fetch;
+  toolUIs: ReactNode[];
+  children: ReactNode;
+}
+
+/**
+ * Branch for configs that DECLARE :attr:`useStickyConversationId`.
+ * Calls the hook unconditionally so React's hook-count invariant
+ * holds across every render of this mount.
+ */
+function StickyAwareRuntime({
+  config,
+  useSticky,
+  urlMatch,
+  fetchFn,
+  toolUIs,
+  children,
+}: ChildRuntimeProps & { useSticky: () => string | null }) {
+  const sticky = useSticky();
+  return (
+    <RuntimeBody
+      config={config}
+      sticky={sticky}
+      urlMatch={urlMatch}
+      fetchFn={fetchFn}
+      toolUIs={toolUIs}
+    >
+      {children}
+    </RuntimeBody>
+  );
+}
+
+/**
+ * Branch for configs that DO NOT declare :attr:`useStickyConversationId`.
+ * No hook is ever called for sticky state — the runtime threadId
+ * follows URL match and the shell-minted fresh UUID only.
+ */
+function UrlOnlyRuntime({ config, urlMatch, fetchFn, toolUIs, children }: ChildRuntimeProps) {
+  return (
+    <RuntimeBody
+      config={config}
+      sticky={null}
+      urlMatch={urlMatch}
+      fetchFn={fetchFn}
+      toolUIs={toolUIs}
+    >
+      {children}
+    </RuntimeBody>
+  );
+}
+
+/**
+ * Shared rendering body — same useRef/useMemo/useCallback shape for
+ * both branches. The hook lineage here is stable per mount because
+ * the parent decides which branch (and which key) to use.
+ */
+function RuntimeBody({
+  config,
+  sticky,
+  urlMatch,
+  fetchFn,
+  toolUIs,
+  children,
+}: ChildRuntimeProps & { sticky: string | null }) {
+  // Pre-mint a fresh UUID so the runtime's ``threadId`` is set from
+  // the very first render — never goes through ``undefined → defined``,
+  // which would otherwise force a remount of the assistant-ui runtime
+  // (and wipe in-flight messages) the moment the user sent their first
+  // message on a fresh chat. The backend collapse (``conversation_id ==
+  // agui_thread_id``) ensures the id the runtime uses from the start
+  // matches the row the lazy ``ensureConversationId`` creates — same
+  // value, no mid-conversation switch.
+  //
+  // Mint a new one only when the user actually starts a new thread:
+  // ``sticky`` transitions from a value back to ``null`` (the module
+  // clears it on the ``/`` "New Thread" landing).
+  const freshIdRef = useRef<string>(_genUuid());
+  const prevStickyRef = useRef<string | null>(sticky);
+  if (sticky === null && prevStickyRef.current !== null) {
+    // User just navigated back to "/" (New Thread). The previous chat
+    // is being abandoned; mint a fresh UUID for the next session.
+    freshIdRef.current = _genUuid();
+  }
+  prevStickyRef.current = sticky;
+
+  // Effective id seen by AGUIRuntimeProvider — always defined.
+  //   sticky (current conversation) wins, else fall back to the
+  //   shell-minted UUID for fresh chats.
+  const effectiveThreadId: string = sticky ?? urlMatch ?? freshIdRef.current;
+
+  const historyAdapterFactory = useCallback<AGUIHistoryAdapterFactory>(
+    (args: AGUIChatConversationFactoryArgs) =>
+      config.buildHistoryAdapter({
+        urlMatch: args.urlMatch,
+        aguiThreadId: args.aguiThreadId,
+      }),
+    [config],
+  );
+
+  return (
+    <AGUIRuntimeProvider
+      fetchFn={fetchFn}
+      threadId={effectiveThreadId}
+      // ``urlMatch`` carries the URL-derived resume signal verbatim.
+      // ``effectiveThreadId`` is always defined (sticky / urlMatch /
+      // freshly minted UUID) so passing it in place of ``urlMatch``
+      // would erase the "fresh vs resumed" distinction the history
+      // adapter needs to decide whether to load() past messages.
+      urlMatch={urlMatch}
+      historyAdapterFactory={historyAdapterFactory}
+    >
+      {toolUIs}
+      {children}
+    </AGUIRuntimeProvider>
+  );
+}
+
 function ToolUIGroup({ children }: { children: ReactNode }) {
   return <>{children}</>;
 }
 
+/**
+ * RFC 4122 v4 UUID. Use ``crypto.randomUUID`` when available; fall
+ * back to a math-random shim for the rare environments without it
+ * (older Safari on non-HTTPS dev hosts). The shim is fine for our
+ * use — these UUIDs identify a conversation row in our backend; they
+ * don't need cryptographic strength.
+ */
+function _genUuid(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
 interface ComposedWrappersProps {
   wrappers: React.ComponentType<{ children: ReactNode }>[];
   children: ReactNode;

package/src/types.ts

@@ -1,6 +1,86 @@
 import type { ComponentType, ReactNode } from "react";
 import type { ThemeLayer } from "@iloveagents/foundry-web-ui";
 
+/**
+ * Per-mount inputs the shell hands the module's history-adapter
+ * factory. Either ``urlMatch`` (resumed chat — the user clicked a
+ * Recents entry) or ``aguiThreadId`` alone (fresh chat — assistant-ui
+ * just minted a UUID) drives the canonical conversation id, depending
+ * on what the module's backend treats as authoritative.
+ */
+export interface ChatConversationFactoryArgs {
+  /**
+   * The conversation id captured from the URL via
+   * :attr:`ChatConversationConfig.pathPattern`. Set when the user
+   * resumed a known chat; ``undefined`` on a fresh thread.
+   */
+  urlMatch?: string;
+  /**
+   * The assistant-ui adapter's stable thread id (a client-minted
+   * UUID, unique per "New Thread" click). Always set. Use this as the
+   * key for a lazy ``create_or_get`` when ``urlMatch`` is missing so
+   * fresh chats also persist.
+   */
+  aguiThreadId: string;
+}
+
+/**
+ * URL-driven chat persistence wiring. Modules declare this so the
+ * shell can stand up an assistant-ui :type:`ThreadHistoryAdapter` on
+ * every mount of :type:`AGUIRuntimeProvider` — both resumed chats
+ * (matched URL) and fresh chats.
+ *
+ * The shell stays free of feature-specific knowledge: it captures
+ * the URL match (if any) and the assistant-ui-minted thread id, and
+ * hands both to :attr:`buildHistoryAdapter`. The module owns the
+ * actual backend API shape and "fresh chat vs. resume" semantics.
+ */
+export interface ChatConversationConfig {
+  /**
+   * Regex with exactly one capture group that yields the conversation
+   * id from ``window.location.pathname``. Example:
+   * ``/^\/chat\/([^/]+)$/``.
+   */
+  pathPattern: RegExp;
+  /**
+   * Optional hook giving the module's view of "what conversation is
+   * the user currently engaged with" — separate from the URL.
+   *
+   * Why this exists: ChatGPT-style UX wants the chat runtime to stay
+   * alive while the user browses Workspaces, Jobs, etc. If we drove
+   * the runtime's ``threadId`` from the URL only, every non-chat
+   * navigation would remount the runtime and wipe in-flight messages.
+   *
+   * When provided, the shell prefers this value over the URL match
+   * for the ``AGUIRuntimeProvider.threadId`` prop. The module is
+   * expected to update its sticky state on URL transitions itself
+   * (e.g. via :type:`useTrackActiveChatFromUrl` in Spaces).
+   *
+   * Return ``null`` when the user has no active chat (initial app
+   * load, or just clicked "New Thread"). The shell then lets the
+   * AG-UI adapter mint a fresh UUID, same as before this hook.
+   */
+  useStickyConversationId?: () => string | null;
+  /**
+   * Build an assistant-ui :type:`ThreadHistoryAdapter` for the
+   * current mount. Called inside the runtime provider once the
+   * AG-UI adapter has minted (or accepted) its thread id, so both
+   * ``urlMatch`` and ``aguiThreadId`` are available.
+   *
+   * The returned adapter is wired into ``useLocalRuntime``'s
+   * ``adapters.history`` slot — assistant-ui calls ``load()`` on
+   * mount and ``append()`` after every completed turn.
+   *
+   * Modules typically:
+   *   - On resume (``urlMatch`` set): use it directly as the
+   *     conversation id for load/append.
+   *   - On fresh (``urlMatch`` undefined): lazily ``create_or_get``
+   *     a server row keyed by ``aguiThreadId``, cache the resulting
+   *     conversation id, then load/append against that.
+   */
+  buildHistoryAdapter: (args: ChatConversationFactoryArgs) => import("@assistant-ui/react").ThreadHistoryAdapter;
+}
+
 /** Route entry contributed by a module or the host app. */
 export interface ShellPage {
   path: string;
@@ -38,6 +118,27 @@ export interface ChatModule {
   useThemeLayers?: () => ThemeLayer[];
   pages?: ShellPage[];
   fetchInterceptor?: () => void;
+  /**
+   * URL-driven chat persistence.
+   *
+   * Selection order (see ``ChatConversationAwareRuntime`` in
+   * ``shell-app.tsx``):
+   *
+   * 1. URL match. If a module's ``pathPattern`` matches the current
+   *    pathname and captures a non-empty group, that module's config
+   *    wins and its captured id is fed to the history adapter as
+   *    ``urlMatch``.
+   * 2. Fallback. If nothing matches the URL, the shell falls back to
+   *    the FIRST registered config (``configs[0]``) so a fresh-chat
+   *    runtime still gets a history adapter and the chat persists
+   *    from the very first message. ``urlMatch`` is ``undefined``
+   *    in this case.
+   * 3. None. With zero configs registered, the runtime stays in
+   *    legacy in-memory mode (no persistence).
+   *
+   * Modules without a config don't participate in selection.
+   */
+  chatConversation?: ChatConversationConfig;
 }
 
 /**