@iloveagents/foundry-agent 0.3.0 → 0.4.0

package/dist/msal/auth-store.js

@@ -0,0 +1,372 @@
+import { createStore } from "zustand/vanilla";
+import { getMsalInstance, getMsalConfig } from "./auth-config.js";
+export class AuthInteractionRequiredError extends Error {
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "AuthInteractionRequiredError";
+        this.code = options.code;
+        this.cause = options.cause;
+    }
+}
+/** Recoverable error codes per MSAL.js docs — every one of these has the
+ * documented remedy "invoke an interactive API". */
+const RECOVERABLE_ERROR_CODES = new Set([
+    // InteractionRequiredAuthError — canonical fallback case.
+    "interaction_required",
+    "login_required",
+    "consent_required",
+    // BrowserAuthError: monitor_window_timeout. Documented remedy includes
+    // "Invoke an interactive API" (Microsoft Learn → "Common errors in
+    // MSAL JS" → monitor_window_timeout → "Throttling" + "X-Frame-Options
+    // Deny"). Real-world trigger on Chrome 120+ is third-party-iframe
+    // storage partitioning blocking the silent SSO frame.
+    "monitor_window_timeout",
+]);
+/** `InteractionRequiredAuthError` always triggers the redirect — match by
+ * class name as a fallback when the error code isn't set. */
+const INTERACTION_REQUIRED_NAME = "InteractionRequiredAuthError";
+/** Module-level deduplication: when N parallel API calls all trip the
+ * recovery path simultaneously, the second-onwards must reuse the first
+ * one's promise rather than each issuing their own redirect. Without
+ * this, MSAL throws ``interaction_in_progress`` on N-1 of them and the
+ * cascading errors mask the actual recovery state. Mirrors the pattern
+ * in the msal-react ``useMsalAuthentication`` hook + the production
+ * patterns linked from Microsoft Learn's "Common errors" guide. */
+let activeRecoveryPromise = null;
+function isRecoverableAuthError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const name = err.name ?? "";
+    const code = err.errorCode ?? "";
+    return name === INTERACTION_REQUIRED_NAME || RECOVERABLE_ERROR_CODES.has(code);
+}
+function authErrorName(err) {
+    return err && typeof err === "object" ? err.name : undefined;
+}
+function authErrorCode(err) {
+    return err && typeof err === "object" ? err.errorCode : undefined;
+}
+function authErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return err && typeof err === "object" ? err.message : undefined;
+}
+function describeAuthError(err) {
+    const parts = [
+        authErrorName(err) ? `name=${authErrorName(err)}` : undefined,
+        authErrorCode(err) ? `code=${authErrorCode(err)}` : undefined,
+        authErrorMessage(err) ? `message=${authErrorMessage(err)}` : undefined,
+    ].filter(Boolean);
+    return parts.join(", ");
+}
+function createInteractionRequiredError(tokenError, redirectError) {
+    const tokenDetail = describeAuthError(tokenError) || "unknown token acquisition error";
+    const redirectDetail = redirectError ? describeAuthError(redirectError) : "";
+    if (redirectError) {
+        return new AuthInteractionRequiredError(`Authentication interaction required, but redirect failed (${redirectDetail}). Original token error: ${tokenDetail}.`, {
+            code: authErrorCode(redirectError) ?? authErrorCode(tokenError),
+            cause: redirectError,
+        });
+    }
+    return new AuthInteractionRequiredError(`Authentication interaction required after token acquisition failed (${tokenDetail}).`, {
+        code: authErrorCode(tokenError),
+        cause: tokenError,
+    });
+}
+/** Storage probe: does the browser have orphaned MSAL token entries with
+ * no matching account record? That state is the "stuck on 401 forever"
+ * signature — getAllAccounts() returns [] but the SPA still has tokens
+ * lingering from a previous session that recovery half-cleaned. Returns
+ * the list of MSAL keys to nuke; empty array means cache is coherent. */
+function findOrphanedMsalKeys() {
+    if (typeof window === "undefined" || !window.localStorage)
+        return [];
+    const allKeys = [];
+    for (let i = 0; i < window.localStorage.length; i++) {
+        const k = window.localStorage.key(i);
+        if (k && k.startsWith("msal."))
+            allKeys.push(k);
+    }
+    const tokenKeys = allKeys.filter((k) => /\|(?:access|refresh|id)token\|/.test(k));
+    // No tokens = clean (or never logged in). Tokens AND empty
+    // getAllAccounts means orphaned — caller is the only one who knows
+    // the accounts state, so caller decides whether to nuke.
+    return tokenKeys.length > 0 ? allKeys : [];
+}
+function nukeMsalLocalStorage() {
+    if (typeof window === "undefined")
+        return;
+    for (const store of [window.localStorage, window.sessionStorage]) {
+        if (!store)
+            continue;
+        const toRemove = [];
+        for (let i = 0; i < store.length; i++) {
+            const k = store.key(i);
+            if (k && k.startsWith("msal."))
+                toRemove.push(k);
+        }
+        toRemove.forEach((k) => store.removeItem(k));
+    }
+}
+async function startInteractiveRecovery(msal, account, scope, reason) {
+    // Deduplicate concurrent recovery attempts. Multiple in-flight API
+    // calls can simultaneously detect a stale token and trip recovery;
+    // without this, MSAL throws ``interaction_in_progress`` on every
+    // call after the first.
+    if (activeRecoveryPromise) {
+        return activeRecoveryPromise;
+    }
+    // Extract a claims challenge from the failure reason (if any).
+    // Production scenarios that surface here with a payload:
+    //   * Conditional Access re-eval (MFA step-up required).
+    //   * Continuous Access Evaluation revocation.
+    //   * Device-compliance change mid-session.
+    // The service-fetch interceptor parses WWW-Authenticate when it
+    // can and stamps the payload onto the recovery reason — we pass
+    // it through to MSAL so the next token explicitly satisfies the
+    // challenge. Without this, Entra would silently re-issue the same
+    // already-rejected claims set and we'd loop right back.
+    const claims = extractClaimsChallenge(reason);
+    activeRecoveryPromise = (async () => {
+        let redirectError;
+        authStore.setState({ user: null, isAuthenticated: false });
+        // Step 0: strip a lingering MSAL error hash from the URL before
+        // attempting any redirect. MSAL.js's redirect primitives refuse
+        // to navigate with ``BrowserAuthError: block_iframe_reload`` when
+        // the current page URL still carries a previous silent-auth
+        // failure in its fragment (e.g.
+        // ``#error=interaction_required&error_description=AADSTS160021…``
+        // from an earlier ``handleRedirectPromise`` that surfaced
+        // "user session does not exist"). The SDK's own anti-loop guard
+        // sees the unconsumed error and aborts — leaving the user
+        // permanently stuck unless they manually clear browser state.
+        //
+        // We can defuse that guard cleanly by replacing the URL with a
+        // fragment-less copy via ``history.replaceState`` before the
+        // redirect call. MSAL then sees a "clean" page and proceeds.
+        // The original page state (path + search) is preserved so the
+        // user lands back where they started after re-auth.
+        //
+        // Reference:
+        //   https://aka.ms/msal.js.errors#block_iframe_reload
+        //   https://github.com/AzureAD/microsoft-authentication-library-for-js/issues/5623
+        stripStaleMsalErrorHash();
+        // Step 1: surgically evict the bad account record from MSAL's
+        // own token cache BEFORE redirecting. Two reasons:
+        //
+        //  (a) The bad refresh token / claims set is what's causing the
+        //      hard-auth failure. Leaving it in cache means MSAL's
+        //      acquireTokenSilent (called by every other in-flight or
+        //      post-redirect request) hands out the SAME poisoned token
+        //      until the entry naturally expires.
+        //  (b) Microsoft's "orphaned-state" anti-pattern is about
+        //      clearing AFTER initiating a redirect (i.e. clearing while
+        //      MSAL is mid-flight). Clearing the SPECIFIC account
+        //      BEFORE the redirect is the documented pattern — see
+        //      https://github.com/AzureAD/microsoft-authentication-library-for-js/issues/6840
+        //      and the SDK's own ``IPublicClientApplication.clearCache``
+        //      contract which accepts ``{ account }``.
+        //
+        // Wrapped in a try/catch so a cache-removal hiccup doesn't
+        // strand the user without ever attempting the redirect.
+        if (account) {
+            try {
+                await msal.clearCache({ account });
+            }
+            catch (err) {
+                // Telemetry only — keep flowing into the redirect path.
+                // eslint-disable-next-line no-console
+                console.warn("[msal-recovery] clearCache(account) failed; continuing with redirect", err);
+            }
+        }
+        // Step 2: ``acquireTokenRedirect`` with ``prompt: "login"`` —
+        // forces a fresh interactive authentication even if Entra still
+        // has a live SSO session for the user. Without ``prompt: "login"``
+        // the redirect silently round-trips through Entra and returns a
+        // token built from the SAME state we just tried to escape from
+        // (this is the "silent redirect loop" users actually experience:
+        // the page bounces to login.microsoftonline.com and back, still
+        // broken). The full re-auth path produces a fresh refresh-token
+        // + fresh claims bound to current server policy.
+        if (account) {
+            try {
+                await msal.acquireTokenRedirect({
+                    scopes: [scope],
+                    account,
+                    prompt: "login",
+                    ...(claims ? { claims } : {}),
+                });
+                // If we reach here without navigating, MSAL settled the
+                // promise before browser navigation kicked in (test envs,
+                // blocked redirects, etc.). Fall through to loginRedirect.
+            }
+            catch (err) {
+                redirectError = err;
+            }
+        }
+        // Step 3: full ``loginRedirect`` fallback. Same ``prompt: "login"``
+        // contract so even this path can't loop back into broken state.
+        // Used when:
+        //   * No account was passed (orphaned-state caller already
+        //     wiped localStorage upstream).
+        //   * acquireTokenRedirect threw a non-navigation error.
+        //   * acquireTokenRedirect settled without navigating.
+        try {
+            await msal.loginRedirect({
+                scopes: [scope],
+                prompt: "login",
+                ...(claims ? { claims } : {}),
+            });
+        }
+        catch (err) {
+            redirectError = err;
+        }
+        throw createInteractionRequiredError(reason, redirectError);
+    })();
+    try {
+        return await activeRecoveryPromise;
+    }
+    finally {
+        activeRecoveryPromise = null;
+    }
+}
+/**
+ * Pull a CAE / Conditional-Access claims-challenge payload out of a
+ * recovery-trigger error. Two shapes are produced upstream:
+ *
+ *   * The fetch interceptor (``service-fetch``) parses the
+ *     ``WWW-Authenticate`` header on a 401 response and constructs
+ *     an error whose ``claims`` (or ``cause.claims``) field carries
+ *     the base64 payload it found.
+ *   * MSAL.js's own ``InteractionRequiredAuthError`` instances expose
+ *     ``claims`` directly when Azure returned one.
+ *
+ * Return ``undefined`` when none is present — callers should NOT
+ * pass an empty string to MSAL (the SDK treats that as "ignore" but
+ * older versions choke on the empty key).
+ */
+/**
+ * Replace the page's URL fragment with an empty one when it carries
+ * a leftover MSAL/Entra error response (``#error=…``,
+ * ``#error_description=…``, ``#error_code=…``, or
+ * ``#error_uri=…``). Preserves path + query string so the user
+ * lands back on the same page after the imminent recovery redirect.
+ *
+ * Why this is necessary:
+ *   MSAL.js's redirect primitives include an anti-loop guard that
+ *   refuses to navigate when the current URL fragment encodes a
+ *   prior auth error — the SDK raises ``block_iframe_reload``
+ *   instead of redirecting. In production we hit this when an
+ *   earlier ``acquireTokenSilent`` had its hidden iframe receive an
+ *   ``AADSTS160021: Application requested a user session which does
+ *   not exist`` response, MSAL surfaced it via
+ *   ``handleRedirectPromise`` but left the fragment intact.
+ *   Subsequent recovery redirects all aborted with
+ *   ``block_iframe_reload`` and the user was stuck until they
+ *   manually cleared browser storage.
+ *
+ * This helper is a no-op on non-browser environments and a no-op
+ * when no error fragment is present.
+ */
+function stripStaleMsalErrorHash() {
+    if (typeof window === "undefined" || typeof history === "undefined")
+        return;
+    const hash = window.location.hash || "";
+    if (!hash)
+        return;
+    // ``hash`` is e.g. ``#error=interaction_required&error_description=…``.
+    // We look for any of the error-shaped keys MSAL emits.
+    if (!/(?:^|[#&])error(?:_description|_code|_uri)?=/.test(hash))
+        return;
+    try {
+        const cleanUrl = window.location.pathname + window.location.search;
+        history.replaceState(null, "", cleanUrl);
+    }
+    catch {
+        // Some embedded environments lock down history.replaceState
+        // (sandboxed iframes etc.). If that happens we still try the
+        // redirect — MSAL may or may not succeed; nothing we can do.
+    }
+}
+function extractClaimsChallenge(reason) {
+    if (!reason || typeof reason !== "object")
+        return undefined;
+    const direct = reason.claims;
+    if (typeof direct === "string" && direct.length > 0)
+        return direct;
+    const cause = reason.cause;
+    if (cause && typeof cause === "object") {
+        const fromCause = cause.claims;
+        if (typeof fromCause === "string" && fromCause.length > 0) {
+            return fromCause;
+        }
+    }
+    return undefined;
+}
+export const authStore = createStore((set) => ({
+    user: null,
+    isAuthenticated: false,
+    signIn: (user) => set({ user, isAuthenticated: true }),
+    signOut: () => {
+        set({ user: null, isAuthenticated: false });
+        const msal = getMsalInstance();
+        if (msal) {
+            msal.logoutRedirect();
+        }
+    },
+    getAccessToken: async (_audience = "api", options) => {
+        const msal = getMsalInstance();
+        const config = getMsalConfig();
+        if (!msal || !config)
+            return null;
+        const accounts = msal.getAllAccounts();
+        const scope = config.apiScope;
+        // Orphaned-state recovery: ``getAllAccounts()`` returns [] BUT
+        // localStorage still holds MSAL token entries. That happens when a
+        // previous recovery attempt cleared the account record but its
+        // redirect didn't navigate (browser policy, popup blocker, async
+        // race). The SPA renders "logged in" but every API call goes
+        // anonymous. Nuke the orphans + force a fresh redirect so the
+        // user gets unstuck without manually clearing browser storage.
+        if (accounts.length === 0) {
+            const orphans = findOrphanedMsalKeys();
+            if (orphans.length > 0) {
+                nukeMsalLocalStorage();
+                return startInteractiveRecovery(msal, null, scope, new Error(`Detected orphaned MSAL state (${orphans.length} cache entries with no account record); cleaned up + redirecting`));
+            }
+            // Truly logged out — ``AuthGuard`` will call ``loginRedirect`` on
+            // its next render. Don't double-redirect from here.
+            return null;
+        }
+        const forceRefresh = options?.forceRefresh === true;
+        try {
+            const result = await msal.acquireTokenSilent({
+                scopes: [scope],
+                account: accounts[0],
+                forceRefresh,
+            });
+            return result.accessToken;
+        }
+        catch (err) {
+            if (isRecoverableAuthError(err)) {
+                return startInteractiveRecovery(msal, accounts[0], scope, err);
+            }
+            return null;
+        }
+    },
+    recoverFromHardAuthFailure: async (reason) => {
+        // Fetch interceptor's escape hatch: silent path produced a token
+        // but the resource server rejected it (audience drift, conditional-
+        // access re-eval, claims challenge, tenant-policy change, etc.).
+        // Same recovery primitive as the silent-failure path —
+        // acquireTokenRedirect → loginRedirect — invoked from the
+        // resource-server signal rather than an MSAL exception.
+        const msal = getMsalInstance();
+        const config = getMsalConfig();
+        if (!msal || !config) {
+            throw new AuthInteractionRequiredError("Authentication interaction required (no MSAL instance configured).", { cause: reason });
+        }
+        const accounts = msal.getAllAccounts();
+        return startInteractiveRecovery(msal, accounts[0] ?? null, config.apiScope, reason);
+    },
+}));

package/dist/msal/index.d.ts

@@ -0,0 +1,3 @@
+export { AuthInteractionRequiredError, authStore, type AuthUser, } from "./auth-store.js";
+export { type MsalAuthConfig, type MsalAccountInfo, type MsalClientApplication, initializeMsal, getMsalInstance, getMsalConfig, } from "./auth-config.js";
+export { tokenFetch } from "./token-fetch.js";

package/dist/msal/index.js

@@ -0,0 +1,3 @@
+export { AuthInteractionRequiredError, authStore, } from "./auth-store.js";
+export { initializeMsal, getMsalInstance, getMsalConfig, } from "./auth-config.js";
+export { tokenFetch } from "./token-fetch.js";

package/dist/msal/token-fetch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Token-aware fetch wrapper.
+ *
+ * Acquires a Bearer token from MSAL (if configured) and attaches it to
+ * every outgoing request. All requests use the API scope — the API backend
+ * acts as a gateway and exchanges tokens server-side via OBO when calling
+ * downstream services (e.g., Spaces).
+ *
+ * When MSAL is not configured, behaves identically to native `fetch()`.
+ *
+ * Long-lived tab recovery: on 401 the wrapper retries once with
+ * ``forceRefresh: true`` so the resource server doesn't keep seeing a
+ * stale-but-cached access token. See ``service-fetch.ts`` for the same
+ * pattern with URL rewriting + the deeper rationale.
+ */
+export declare function tokenFetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;

package/dist/msal/token-fetch.js

@@ -0,0 +1,57 @@
+/**
+ * Token-aware fetch wrapper.
+ *
+ * Acquires a Bearer token from MSAL (if configured) and attaches it to
+ * every outgoing request. All requests use the API scope — the API backend
+ * acts as a gateway and exchanges tokens server-side via OBO when calling
+ * downstream services (e.g., Spaces).
+ *
+ * When MSAL is not configured, behaves identically to native `fetch()`.
+ *
+ * Long-lived tab recovery: on 401 the wrapper retries once with
+ * ``forceRefresh: true`` so the resource server doesn't keep seeing a
+ * stale-but-cached access token. See ``service-fetch.ts`` for the same
+ * pattern with URL rewriting + the deeper rationale.
+ */
+import { authStore } from "./auth-store.js";
+export async function tokenFetch(input, init) {
+    async function dispatch(forceRefreshToken) {
+        const token = await authStore
+            .getState()
+            .getAccessToken("api", forceRefreshToken ? { forceRefresh: true } : undefined);
+        // Clone Request inputs per-attempt: ReadableStream bodies are single-
+        // consume, so the 401 retry would otherwise see an empty body.
+        // ``input.clone()`` returns a fresh Request whose body stream is
+        // independent of the original.
+        const target = input instanceof Request ? input.clone() : input;
+        if (!token) {
+            return fetch(target, init);
+        }
+        const headers = new Headers(input instanceof Request ? input.headers : undefined);
+        if (init?.headers) {
+            new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+        }
+        headers.set("Authorization", `Bearer ${token}`);
+        return fetch(target, { ...init, headers });
+    }
+    const response = await dispatch(false);
+    if (response.status !== 401) {
+        return response;
+    }
+    response.body?.cancel().catch(() => undefined);
+    const retried = await dispatch(true);
+    if (retried.status === 401) {
+        // Second 401 after a force-refresh retry — the silent token path
+        // can't recover this (refresh-token grant produces the same
+        // identity claims that just got rejected). Kick off interactive
+        // recovery so a fresh ``loginRedirect`` mints a token bound to
+        // current server policy. ``recoverFromHardAuthFailure`` throws
+        // once the redirect is in flight so we don't return a stale 401
+        // the caller might handle as a real failure.
+        retried.body?.cancel().catch(() => undefined);
+        await authStore
+            .getState()
+            .recoverFromHardAuthFailure(new Error("API returned 401 after force-refresh retry"));
+    }
+    return retried;
+}

package/dist/store/citation-store.d.ts

@@ -0,0 +1,42 @@
+/** Citation result shape — matches the search result format. */
+export interface CitationResult {
+    chunk_id: string;
+    entity_id: string;
+    entity_name: string;
+    content: string;
+    page_number: number;
+    bounding_regions: string;
+    /** Semantic reranker score (0-4) or RRF score (~0.03) */
+    score: number;
+}
+/** Handler for citation clicks — registered by feature modules (e.g., SPACES). */
+export interface CitationHandler {
+    openCitation: (result: CitationResult) => void;
+}
+interface CitationState {
+    /** Current search results (from the most recent search tool call) */
+    results: CitationResult[];
+    /** Optional handler for opening citations (registered by feature modules) */
+    handler: CitationHandler | null;
+    /** Store search results for citation resolution */
+    setResults: (results: CitationResult[]) => void;
+    /** Register a handler for citation click actions */
+    setHandler: (handler: CitationHandler) => void;
+    /**
+     * Reset per-conversation state. Clears ``results`` only — the handler
+     * is module-level state registered once at app boot by feature modules
+     * (e.g. ``registerSpacesCitationHandler``) and must persist across
+     * conversations. Wiping it on "New Thread" produced inert ``[n]``
+     * markers for the rest of the session, since the registration guard
+     * (``registerOnce`` in spaces ``use-spaces-init``) suppresses re-binding.
+     */
+    clear: () => void;
+}
+/**
+ * Vanilla store for the citation cache so `[n]` markers in chat messages
+ * resolve to clickable deep links. Search tool calls populate results; the
+ * markdown renderer looks them up by index. A `CitationHandler` (registered
+ * by feature modules) handles the click action.
+ */
+export declare const citationStore: import("zustand/vanilla").StoreApi<CitationState>;
+export {};

package/dist/store/citation-store.js

@@ -0,0 +1,14 @@
+import { createStore } from "zustand/vanilla";
+/**
+ * Vanilla store for the citation cache so `[n]` markers in chat messages
+ * resolve to clickable deep links. Search tool calls populate results; the
+ * markdown renderer looks them up by index. A `CitationHandler` (registered
+ * by feature modules) handles the click action.
+ */
+export const citationStore = createStore((set) => ({
+    results: [],
+    handler: null,
+    setResults: (results) => set({ results }),
+    setHandler: (handler) => set({ handler }),
+    clear: () => set({ results: [] }),
+}));

package/dist/store/link-store.d.ts

@@ -0,0 +1,29 @@
+export interface LinkHandler {
+    canHandle: (href: string) => boolean;
+    normalizeHref?: (href: string) => string | null;
+    openLink: (href: string) => void;
+}
+export interface ResolvedLinkHandler {
+    handler: LinkHandler;
+    href: string;
+}
+interface LinkState {
+    /**
+     * Latest registered handler kept for backwards-compatible consumers.
+     * New code should use `handlers` or `resolveLinkHandler`.
+     */
+    handler: LinkHandler | null;
+    handlers: LinkHandler[];
+    setHandler: (handler: LinkHandler) => void;
+    clear: () => void;
+}
+/**
+ * Generic markdown-link extension point.
+ *
+ * Feature modules register a handler for their own deep-link namespace
+ * (for example Spaces handles `/spaces/...`). The chat renderer stays
+ * module-agnostic while still letting app-local links navigate in-place.
+ */
+export declare const linkStore: import("zustand/vanilla").StoreApi<LinkState>;
+export declare function resolveLinkHandler(rawHref: string): ResolvedLinkHandler | null;
+export {};

package/dist/store/link-store.js

@@ -0,0 +1,28 @@
+import { createStore } from "zustand/vanilla";
+/**
+ * Generic markdown-link extension point.
+ *
+ * Feature modules register a handler for their own deep-link namespace
+ * (for example Spaces handles `/spaces/...`). The chat renderer stays
+ * module-agnostic while still letting app-local links navigate in-place.
+ */
+export const linkStore = createStore((set) => ({
+    handler: null,
+    handlers: [],
+    setHandler: (handler) => set((state) => ({
+        handler,
+        handlers: [...state.handlers.filter((item) => item !== handler), handler],
+    })),
+    clear: () => set({ handler: null, handlers: [] }),
+}));
+export function resolveLinkHandler(rawHref) {
+    const handlers = linkStore.getState().handlers;
+    for (let i = handlers.length - 1; i >= 0; i -= 1) {
+        const handler = handlers[i];
+        const href = handler.normalizeHref ? handler.normalizeHref(rawHref) : rawHref;
+        if (href && handler.canHandle(href)) {
+            return { handler, href };
+        }
+    }
+    return null;
+}

package/dist/store/streaming-status-store.d.ts

@@ -0,0 +1,15 @@
+/** Streaming status emitted by the AG-UI runner. */
+export interface StreamingStatus {
+    status: "thinking" | "calling" | "streaming" | "idle";
+    toolName?: string;
+}
+interface StreamingStatusState {
+    streamingStatus: StreamingStatus;
+    setStreamingStatus: (status: StreamingStatus) => void;
+}
+/**
+ * Vanilla store for streaming status. Use `useStore(streamingStatusStore, ...)`
+ * from the React entry of zustand for hook-style subscriptions.
+ */
+export declare const streamingStatusStore: import("zustand/vanilla").StoreApi<StreamingStatusState>;
+export {};

package/dist/store/streaming-status-store.js

@@ -0,0 +1,9 @@
+import { createStore } from "zustand/vanilla";
+/**
+ * Vanilla store for streaming status. Use `useStore(streamingStatusStore, ...)`
+ * from the React entry of zustand for hook-style subscriptions.
+ */
+export const streamingStatusStore = createStore((set) => ({
+    streamingStatus: { status: "idle" },
+    setStreamingStatus: (streamingStatus) => set({ streamingStatus }),
+}));

package/dist/tools/registry.d.ts

@@ -0,0 +1,48 @@
+import type { Tool as AGUITool } from "@ag-ui/core";
+/**
+ * Dynamic Client Tool Registry — vanilla zustand store for client-side AG-UI
+ * tools.
+ *
+ * Tools are split into two categories:
+ * - **Global tools**: always available (navigate, set_theme, open_panel, ...)
+ * - **Page tools**: registered by the active page via the host shell, removed
+ *   on unmount.
+ *
+ * The runner reads from this store on every request to get the current tool
+ * schemas and executors. Pages declare their capabilities by calling
+ * `registerPageTools()` — no need to edit core files.
+ */
+export interface ClientToolEntry {
+    /** Tool name (must be unique across global + page tools) */
+    name: string;
+    /** Tool description for the LLM */
+    description: string;
+    /** JSON Schema for tool parameters */
+    parameters: Record<string, unknown>;
+    /** Execution function — called by the runner at TOOL_CALL_END */
+    execute: (argsJson: string) => Promise<string>;
+}
+interface ClientToolRegistryState {
+    globalTools: Map<string, ClientToolEntry>;
+    pageTools: Map<string, ClientToolEntry>;
+    /** Register a global tool (called once at app init) */
+    registerGlobal: (tool: ClientToolEntry) => void;
+    /** Register page-scoped tools (called by the host on mount) */
+    registerPageTools: (tools: ClientToolEntry[]) => void;
+    /** Remove page-scoped tools (called by the host on unmount) */
+    clearPageTools: () => void;
+    /** Get all active tool schemas for the runner */
+    getActiveSchemas: () => AGUITool[];
+    /** Check if a tool name is registered */
+    isRegistered: (name: string) => boolean;
+    /** Execute a registered tool by name */
+    executeTool: (name: string, argsJson: string) => Promise<string>;
+}
+export declare const clientToolRegistry: import("zustand/vanilla").StoreApi<ClientToolRegistryState>;
+/** Read-only registry view — what the runner consumes. */
+export interface ToolRegistry {
+    isRegistered: (name: string) => boolean;
+    executeTool: (name: string, argsJson: string) => Promise<string>;
+    getActiveSchemas: () => AGUITool[];
+}
+export {};