@iloveagents/foundry-agent 0.3.1 → 0.4.0

package/dist/client/service-fetch.js

@@ -0,0 +1,244 @@
+/**
+ * Per-service fetch factory.
+ *
+ * Returns an authenticated `fetch`-shaped function that:
+ * 1. Rewrites local-relative URLs to a configured router base in production
+ *    (Vite proxy in dev → httpRouteConfigs FQDN in prod).
+ * 2. Acquires a Bearer token via the supplied `acquireToken` callback and
+ *    attaches it as the `Authorization` header.
+ *
+ * `@iloveagents/foundry-agent` stays auth-mechanism-agnostic — `acquireToken` is
+ * supplied by the host (apps/web wires it to MSAL via the `/msal` subpath;
+ * future shells could plug in a different token source).
+ */
+/**
+ * Wrapper thrown when ``acquireToken`` rejects inside the fetch
+ * interceptor. Lets the outer 401-retry layer distinguish
+ * token-acquisition failures (which warrant interactive recovery) from
+ * generic ``fetch`` rejections like network drops, aborts, or CORS
+ * preflight failures (which do NOT — those would needlessly bounce the
+ * user through ``loginRedirect`` on a transient transport error).
+ *
+ * Exported so hosts that wrap ``serviceFetch`` further can ``instanceof``
+ * against the same class without re-declaring it.
+ */
+export class TokenAcquisitionError extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.name = "TokenAcquisitionError";
+        this.cause = cause;
+    }
+}
+const defaultOriginResolver = () => typeof window !== "undefined" ? window.location.origin : "";
+/**
+ * Build a service-fetch function. Returns a function with the same shape as
+ * `fetch` that rewrites URLs + attaches the Bearer token from `acquireToken`.
+ */
+export function createServiceFetch(options) {
+    const routerBase = (options.baseUrl ?? "").replace(/\/+$/, "");
+    const resolveOrigin = options.originResolver ?? defaultOriginResolver;
+    function resolveUrl(url) {
+        if (!routerBase)
+            return url; // dev: Vite proxy handles routing
+        const origin = resolveOrigin();
+        const rel = origin && url.startsWith(origin) ? url.slice(origin.length) : url;
+        return `${routerBase}${rel}`;
+    }
+    return async function serviceFetch(input, init) {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        const resolvedUrl = resolveUrl(url);
+        // Merge headers from a `Request` input (if provided), then `init`. The
+        // Request-input branch must preserve method / body / credentials /
+        // signal / etc. — silently dropping them by reading only `.url` would
+        // turn POST/PUT into GET and drop required headers.
+        const baseHeaders = new Headers(input instanceof Request ? input.headers : undefined);
+        if (init?.headers) {
+            new Headers(init.headers).forEach((value, key) => baseHeaders.set(key, value));
+        }
+        const callerSuppliedAuth = baseHeaders.has("Authorization");
+        function buildRequestInitFrom(req) {
+            // ReadableStream bodies are single-consume. ``req.clone()`` returns a
+            // fresh Request whose body stream is independent — call it once per
+            // dispatch attempt so the 401 retry can replay POST/PUT bodies
+            // intact.
+            const fresh = req.clone();
+            const ri = {
+                method: fresh.method,
+                body: fresh.method === "GET" || fresh.method === "HEAD" ? undefined : fresh.body,
+                credentials: fresh.credentials,
+                mode: fresh.mode,
+                cache: fresh.cache,
+                redirect: fresh.redirect,
+                referrer: fresh.referrer,
+                integrity: fresh.integrity,
+                signal: fresh.signal,
+            };
+            // Streaming bodies need duplex: "half"; harmless when there's no body.
+            if (fresh.body !== null) {
+                ri.duplex = "half";
+            }
+            return ri;
+        }
+        async function dispatch(forceRefreshToken) {
+            const headers = new Headers(baseHeaders);
+            if (!callerSuppliedAuth) {
+                try {
+                    const token = await options.acquireToken(forceRefreshToken ? { forceRefresh: true } : undefined);
+                    if (token) {
+                        headers.set("Authorization", `Bearer ${token}`);
+                    }
+                }
+                catch (error) {
+                    // A thrown token-acquisition error usually means the auth layer
+                    // is starting an interactive recovery. Do not downgrade
+                    // protected API calls to anonymous requests; that creates
+                    // noisy 401s and stale UI. Wrap the error so the outer
+                    // 401-retry layer can distinguish it from generic ``fetch``
+                    // rejections (network drops, aborts, CORS preflight fails)
+                    // and only escalate to ``recoverFromHardAuthFailure`` for
+                    // genuine auth failures.
+                    throw new TokenAcquisitionError(error);
+                }
+            }
+            if (input instanceof Request) {
+                // Re-clone for THIS attempt — the body stream of the original is
+                // either still pristine (first attempt) or already consumed
+                // (second attempt); ``clone()`` always returns a fresh, replayable
+                // copy.
+                const requestInit = buildRequestInitFrom(input);
+                return fetch(resolvedUrl, { ...requestInit, ...init, headers });
+            }
+            return fetch(resolvedUrl, { ...init, headers });
+        }
+        const response = await dispatch(false);
+        // Long-lived tab recovery: when the resource server returns 401 the
+        // local MSAL cache may still hold a token MSAL itself thinks is valid
+        // (claims challenge, conditional-access re-eval, audience drift, or
+        // the user simply left the tab open past the cached access token's
+        // server-side validity). Force-refresh the token via the refresh
+        // token grant and replay the request once. If the refresh-token is
+        // also gone (24h SPA cap), ``acquireToken`` will throw an
+        // interaction-required error and the auth layer kicks off
+        // ``loginRedirect`` — that's the only correct UX for a hard expiry.
+        //
+        // Conditions for retry: 401, no caller-supplied auth header (we own
+        // the token), and the server didn't already see a fresh token (we
+        // only retry once).
+        if (response.status !== 401 || callerSuppliedAuth) {
+            return response;
+        }
+        // Drain the failed response body — letting it sit unread keeps the
+        // underlying connection occupied on some runtimes.
+        response.body?.cancel().catch(() => undefined);
+        // Two failure shapes for the retry:
+        //   (a) The force-refreshed token grant FAILS — refresh token gone
+        //       (24h SPA cap), interaction-required claims challenge, etc.
+        //       ``acquireToken`` throws inside ``dispatch`` BEFORE the fetch
+        //       leaves the browser. ``dispatch`` re-throws wrapped in
+        //       ``TokenAcquisitionError`` so we can distinguish this case
+        //       from network errors below.
+        //   (b) The grant succeeds but the resource server STILL rejects
+        //       the token (audience drift, server-side policy change). The
+        //       retried response status is 401.
+        // Both must funnel into ``recoverFromHardAuthFailure`` so the auth
+        // layer can kick off ``loginRedirect`` — the only correct UX for a
+        // hard expiry. We treat the two auth paths symmetrically.
+        //
+        // We deliberately do NOT trigger recovery on generic ``dispatch``
+        // throws (TypeError from network drops, AbortError from caller
+        // cancellation, CORS-preflight failures, etc.) — those are
+        // transient transport problems, not auth state corruption, and
+        // bouncing the user through ``loginRedirect`` for a flaky network
+        // would be a much worse UX than letting the error propagate.
+        let retried;
+        try {
+            retried = await dispatch(true);
+        }
+        catch (err) {
+            if (err instanceof TokenAcquisitionError && options.recoverFromHardAuthFailure) {
+                // ``recoverFromHardAuthFailure`` is expected to throw once the
+                // redirect is in flight; if it returns (e.g. test stub) we
+                // re-throw the wrapped original so the caller still sees the
+                // auth failure rather than a phantom recovery. We pass the
+                // unwrapped ``cause`` to recovery so it sees the real MSAL
+                // error (InteractionRequiredAuthError etc.) for telemetry.
+                await options.recoverFromHardAuthFailure(err.cause);
+            }
+            throw err;
+        }
+        // Hard auth failure path (b): even the force-refreshed token got
+        // rejected. A token minted from the cached refresh token carries
+        // the same identity claims as the original, so it'll keep getting
+        // rejected for the same reason. Only a brand-new ``loginRedirect``
+        // produces a token bound to the current server policy. Without
+        // this branch the user sees an endless 401 loop until they
+        // manually log out.
+        if (retried.status === 401 && options.recoverFromHardAuthFailure) {
+            // Continuous Access Evaluation / Conditional-Access claims
+            // challenge passthrough. When the resource server requires a
+            // step-up (MFA, device compliance, revocation invalidation),
+            // it returns 401 with ``WWW-Authenticate: Bearer ... claims="…"``.
+            // We forward the payload through the recovery callback so the
+            // auth layer's redirect carries it to Entra ID and the
+            // re-minted token satisfies the exact challenge. Without it,
+            // Entra re-issues the same already-rejected claims set and the
+            // user loops back into the broken state.
+            const claims = parseClaimsChallengeFromWwwAuthenticate(retried.headers.get("www-authenticate"));
+            retried.body?.cancel().catch(() => undefined);
+            const reason = new AuthInteractionRequiredError("API returned 401 after force-refresh retry", claims ? { claims } : undefined);
+            // ``recoverFromHardAuthFailure`` throws once the redirect is in
+            // flight; the throw stops the calling pipeline so we don't
+            // return a stale 401 the caller might handle as a real failure.
+            await options.recoverFromHardAuthFailure(reason);
+        }
+        return retried;
+    };
+}
+/**
+ * Error class the fetch interceptor raises (and forwards through
+ * ``recoverFromHardAuthFailure``) when a 401 needs interactive
+ * recovery. Exposed so the auth-layer recovery can pick up a
+ * ``claims`` field if one was extracted from the
+ * ``WWW-Authenticate`` header.
+ */
+export class AuthInteractionRequiredError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "AuthInteractionRequiredError";
+        this.claims = options?.claims;
+    }
+}
+/**
+ * Extract the claims challenge string from a resource server's
+ * ``WWW-Authenticate: Bearer ... claims="…"`` header. Returns
+ * ``undefined`` when the header is missing, malformed, or carries
+ * no claims directive.
+ *
+ * The value is forwarded VERBATIM to MSAL's
+ * ``acquireTokenRedirect({ claims })``; MSAL handles the
+ * base64-url decode + JSON parse itself. We don't try to validate
+ * the inner shape — letting Entra speak for itself avoids drift if
+ * the schema evolves.
+ *
+ * Spec: RFC 6750 ``WWW-Authenticate`` + CAE claims-challenge
+ * supplement (Microsoft Identity Platform docs).
+ */
+export function parseClaimsChallengeFromWwwAuthenticate(header) {
+    if (!header)
+        return undefined;
+    // ``WWW-Authenticate`` can carry multiple challenges separated by
+    // commas (e.g. ``Basic realm="x", Bearer ...``). We only care
+    // about the Bearer challenge.
+    const bearer = header.match(/Bearer\s+([^,]+(?:,(?!\s*[A-Za-z]+\s)[^,]*)*)/i);
+    if (!bearer)
+        return undefined;
+    // Inside the Bearer params, find ``claims="..."`` (quoted) or
+    // ``claims=token68`` (unquoted, base64url).
+    const quoted = bearer[1].match(/claims\s*=\s*"([^"]*)"/i);
+    if (quoted)
+        return quoted[1].length > 0 ? quoted[1] : undefined;
+    const unquoted = bearer[1].match(/claims\s*=\s*([A-Za-z0-9_\-+/=]+)/i);
+    if (unquoted)
+        return unquoted[1].length > 0 ? unquoted[1] : undefined;
+    return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { AGUIRunner, type AGUIRunnerOptions, type AGUIRunInput } from "./client/agui-runner.js";
+export type { RunnerEvent } from "./client/runner-events.js";
+export { createServiceFetch, type ServiceFetch, type ServiceFetchOptions, } from "./client/service-fetch.js";
+export { clientToolRegistry, type ClientToolEntry, type ToolRegistry } from "./tools/registry.js";
+export { streamingStatusStore, type StreamingStatus } from "./store/streaming-status-store.js";
+export { citationStore, type CitationResult, type CitationHandler, } from "./store/citation-store.js";
+export { linkStore, resolveLinkHandler, type LinkHandler, type ResolvedLinkHandler, } from "./store/link-store.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+// --- AG-UI runner ---
+export { AGUIRunner } from "./client/agui-runner.js";
+// --- Service fetch factory ---
+export { createServiceFetch, } from "./client/service-fetch.js";
+// --- Tool registry ---
+export { clientToolRegistry } from "./tools/registry.js";
+// --- Stores (vanilla) ---
+export { streamingStatusStore } from "./store/streaming-status-store.js";
+export { citationStore, } from "./store/citation-store.js";
+export { linkStore, resolveLinkHandler, } from "./store/link-store.js";

package/dist/msal/auth-config.d.ts

@@ -0,0 +1,91 @@
+/**
+ * MSAL configuration types and PublicClientApplication singleton.
+ *
+ * `initializeMsal()` creates and caches the singleton PublicClientApplication.
+ * `getMsalInstance()` returns null until initialization has completed.
+ *
+ * `@azure/msal-browser` is loaded via dynamic import so `@iloveagents/foundry-agent`
+ * does not pull MSAL into bundles that don't need it.
+ */
+export interface MsalAuthConfig {
+    clientId: string;
+    authority: string;
+    redirectUri: string;
+    apiScope: string;
+    postLogoutRedirectUri?: string;
+}
+export interface MsalAccountInfo {
+    username: string;
+    localAccountId: string;
+    name?: string | null;
+}
+export interface MsalClientApplication {
+    initialize(): Promise<void>;
+    handleRedirectPromise(): Promise<unknown>;
+    clearCache(request?: {
+        account?: MsalAccountInfo;
+    }): Promise<void>;
+    getAllAccounts(): MsalAccountInfo[];
+    loginRedirect(request: {
+        scopes: string[];
+        prompt?: string;
+        /** Same claims-challenge passthrough as ``acquireTokenRedirect``. */
+        claims?: string;
+    }): Promise<void>;
+    logoutRedirect(): Promise<void>;
+    setActiveAccount(account: MsalAccountInfo | null): void;
+    acquireTokenSilent(request: {
+        scopes: string[];
+        account: MsalAccountInfo;
+        /**
+         * Skip MSAL's local cache and force a round-trip to the token
+         * endpoint using the cached refresh token. The fetch interceptor
+         * uses this on a 401 retry — the first attempt may have served a
+         * cached access token MSAL still thought valid (within
+         * ``tokenRenewalOffsetSeconds``) that the resource server has
+         * since rejected (claims challenge, conditional access re-eval,
+         * audience drift).
+         */
+        forceRefresh?: boolean;
+    }): Promise<{
+        accessToken: string;
+    }>;
+    acquireTokenRedirect(request: {
+        scopes: string[];
+        account: MsalAccountInfo;
+        /**
+         * Force a fresh interactive login regardless of Entra SSO state.
+         * Without ``prompt: "login"``, when the user still has a live
+         * Entra session, the redirect silently round-trips and returns
+         * THE SAME stale token / claims — leaving the SPA back in the
+         * exact broken state we tried to recover from. See
+         * https://learn.microsoft.com/entra/identity-platform/msal-error-handling-js
+         * "Hard expiry / silent redirect loop" pattern.
+         */
+        prompt?: string;
+        /**
+         * Optional Continuous Access Evaluation / Conditional Access
+         * claims challenge payload, parsed from a resource-server 401
+         * response's ``WWW-Authenticate: Bearer ... claims="..."``
+         * header. When present, MSAL passes it through to Entra so the
+         * issued token explicitly satisfies the challenge (MFA step-up,
+         * device-compliance refresh, revocation invalidation, etc.).
+         */
+        claims?: string;
+    }): Promise<void>;
+    acquireTokenPopup(request: {
+        scopes: string[];
+        account: MsalAccountInfo;
+    }): Promise<{
+        accessToken: string;
+    }>;
+}
+/**
+ * Initialize the MSAL singleton. Must be called once before rendering.
+ * Dynamically imports `@azure/msal-browser` so the dependency stays optional.
+ */
+export declare function initializeMsal(config: MsalAuthConfig): Promise<MsalClientApplication>;
+/** Get the MSAL instance (null when not configured). */
+export declare function getMsalInstance(): MsalClientApplication | null;
+/** Get the MSAL auth config (null when not configured). */
+export declare function getMsalConfig(): MsalAuthConfig | null;

package/dist/msal/auth-config.js

@@ -0,0 +1,70 @@
+/**
+ * MSAL configuration types and PublicClientApplication singleton.
+ *
+ * `initializeMsal()` creates and caches the singleton PublicClientApplication.
+ * `getMsalInstance()` returns null until initialization has completed.
+ *
+ * `@azure/msal-browser` is loaded via dynamic import so `@iloveagents/foundry-agent`
+ * does not pull MSAL into bundles that don't need it.
+ */
+let msalInstance = null;
+let msalConfig = null;
+/**
+ * Initialize the MSAL singleton. Must be called once before rendering.
+ * Dynamically imports `@azure/msal-browser` so the dependency stays optional.
+ */
+export async function initializeMsal(config) {
+    if (msalInstance)
+        return msalInstance;
+    const { PublicClientApplication: PCA } = await import("@azure/msal-browser");
+    // Token-renewal config — see Microsoft Learn:
+    // https://learn.microsoft.com/entra/msal/javascript/browser/errors
+    //
+    // SPA refresh tokens are 24 h, non-sliding, non-renewable. After that
+    // window the user MUST re-auth; nothing the SPA can do silently saves
+    // it. Goal of these knobs is to make the unavoidable interactive
+    // bounce predictable and to keep the silent path healthy in between.
+    const msalConfiguration = {
+        auth: {
+            clientId: config.clientId,
+            authority: config.authority,
+            redirectUri: config.redirectUri,
+            postLogoutRedirectUri: config.postLogoutRedirectUri ?? config.redirectUri,
+        },
+        cache: {
+            // localStorage is required for Playwright E2E tests — sessionStorage
+            // is not preserved across page navigations in the Playwright context.
+            cacheLocation: "localStorage",
+            // Cache key includes a hash of any `claims` parameter. Without
+            // this, MSAL serves the same cached access token even after a
+            // claims-challenge / token revocation / role change. The MSAL
+            // team has signalled this will become the default; opt in early.
+            claimsBasedCachingEnabled: true,
+        },
+        system: {
+            // Treat access tokens as "expired" 10 min before the actual exp
+            // claim instead of MSAL's default 5 min. Eliminates the race
+            // where the SPA's clock thinks the token is still valid but the
+            // resource server rejects it as expired (clock skew, slow request
+            // queueing, etc.).
+            tokenRenewalOffsetSeconds: 600,
+            // Default 6 s is too tight on modern browsers — third-party
+            // storage partitioning + slower CPUs in the silent iframe can
+            // push the round-trip past it. 10 s is the value MSAL Angular
+            // and React samples ship with.
+            iframeHashTimeout: 10000,
+        },
+    };
+    msalInstance = new PCA(msalConfiguration);
+    await msalInstance.initialize();
+    msalConfig = config;
+    return msalInstance;
+}
+/** Get the MSAL instance (null when not configured). */
+export function getMsalInstance() {
+    return msalInstance;
+}
+/** Get the MSAL auth config (null when not configured). */
+export function getMsalConfig() {
+    return msalConfig;
+}

package/dist/msal/auth-store.d.ts

@@ -0,0 +1,95 @@
+export interface AuthUser {
+    name: string;
+    email: string;
+    avatar?: string;
+    oid?: string;
+}
+export declare class AuthInteractionRequiredError extends Error {
+    readonly code?: string;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+interface AuthState {
+    user: AuthUser | null;
+    isAuthenticated: boolean;
+    /** Sign in with the given user. Called by AuthProvider after MSAL login. */
+    signIn: (user: AuthUser) => void;
+    /** Sign out and clear user state. Triggers MSAL logout when configured. */
+    signOut: () => void;
+    /**
+     * Acquire an access token for the given audience.
+     * Returns null when MSAL is not configured (local dev).
+     *
+     * Recovery semantics — follows the canonical MSAL.js pattern documented
+     * at https://learn.microsoft.com/entra/msal/javascript/browser/errors:
+     *
+     * 1. ``acquireTokenSilent`` first. Pass-through on success.
+     * 2. On a recoverable error (``InteractionRequiredAuthError``,
+     *    ``monitor_window_timeout`` from blocked silent-SSO iframes,
+     *    ``login_required`` / ``consent_required``), call
+     *    :func:`startInteractiveRecovery` to navigate the user through a
+     *    fresh interactive auth.
+     *
+     * Recovery uses ``acquireTokenRedirect`` (NOT ``loginRedirect``) as
+     * the first step — that's the documented primitive for refreshing a
+     * known account's tokens without forcing a full re-login. Falls back
+     * to ``loginRedirect`` only when ``acquireTokenRedirect`` itself
+     * fails to navigate (browser policy, popup blocker, etc.).
+     *
+     * Critically: cache is NEVER cleared before the redirect. The
+     * previous version cleared the account record before calling
+     * ``loginRedirect``; when the redirect failed silently (browser
+     * blocking the navigation), the account record was gone but the
+     * tokens lingered, leaving every subsequent API call to find
+     * ``getAllAccounts() === []``, return null, and ship anonymously
+     * to the API — endless 401s, only manual ``localStorage.clear()``
+     * recovers. This bug is documented in
+     * AzureAD/microsoft-authentication-library-for-js#7551.
+     *
+     * Recoverable auth failures reject with ``AuthInteractionRequiredError``
+     * after recovery has been started. The error exposes ``code`` and
+     * ``cause`` so callers can distinguish a normal interaction-required
+     * redirect from a blocked/failed redirect attempt.
+     *
+     * Other ``BrowserAuthError`` codes (``hash_empty_error``,
+     * ``hash_does_not_contain_known_properties``, ``block_iframe_reload``)
+     * are config / race-condition bugs that another redirect won't fix —
+     * propagate them as null without navigating.
+     *
+     * The "no account in cache" case is handled by detecting ORPHANED
+     * STATE (no accounts but localStorage has MSAL token entries) and
+     * cleaning the half-corrupted cache before redirecting. Without this,
+     * the page renders authenticated UI but every API call goes anonymous.
+     *
+     * Errors are matched by ``name`` / ``errorCode`` rather than
+     * ``instanceof`` because ``@azure/msal-browser`` is loaded via
+     * dynamic import; the error class identity isn't shared across
+     * module boundaries.
+     *
+     * ``forceRefresh: true`` skips MSAL's local cache and goes back to the
+     * token endpoint with the cached refresh token. Use it from the
+     * fetch interceptor when a protected API returns 401 — the first
+     * attempt may have used a stale cached access token (claims
+     * challenge, conditional-access re-eval, audience drift, etc.) that
+     * MSAL still considered valid against its own clock.
+     */
+    getAccessToken: (audience?: "api" | "spaces", options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+    /**
+     * Force interactive recovery: start an ``acquireTokenRedirect`` (or
+     * ``loginRedirect`` fallback). Use this from the fetch interceptor
+     * when even a force-refreshed access token still gets rejected by
+     * the resource server (the silent path can't tell us "this is
+     * fundamentally the wrong token" — it has to come from the protected
+     * API saying 401 after we already retried). Throws
+     * ``AuthInteractionRequiredError`` once the redirect has been kicked
+     * off so the caller can stop processing.
+     */
+    recoverFromHardAuthFailure: (reason: unknown) => Promise<never>;
+}
+export declare const authStore: import("zustand/vanilla").StoreApi<AuthState>;
+export {};