@iloveagents/foundry-agent 0.1.0

package/src/client/service-fetch.ts

@@ -0,0 +1,112 @@
+/**
+ * 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).
+ */
+
+export interface ServiceFetchOptions {
+  /**
+   * Acquire an access token for outgoing requests. Return `null` to skip
+   * token attachment (callers without auth — e.g. local dev — pass through
+   * to native fetch).
+   */
+  acquireToken: () => Promise<string | null>;
+
+  /**
+   * Router FQDN for production (e.g. `https://lastspace-prod.eastus2.example.com`).
+   * Empty / undefined leaves the URL untouched (Vite proxy handles routing
+   * in dev).
+   */
+  baseUrl?: string;
+
+  /**
+   * Resolve `window.location.origin` (or equivalent) for the current runtime.
+   * Defaults to a browser-aware lookup; non-browser callers can override.
+   */
+  originResolver?: () => string;
+}
+
+export type ServiceFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+const defaultOriginResolver = (): string =>
+  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: ServiceFetchOptions): ServiceFetch {
+  const routerBase = (options.baseUrl ?? "").replace(/\/+$/, "");
+  const resolveOrigin = options.originResolver ?? defaultOriginResolver;
+
+  function resolveUrl(url: string): string {
+    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): Promise<Response> {
+    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 headers = new Headers(input instanceof Request ? input.headers : undefined);
+    if (init?.headers) {
+      new Headers(init.headers).forEach((value, key) => headers.set(key, value));
+    }
+    if (!headers.has("Authorization")) {
+      try {
+        const token = await options.acquireToken();
+        if (token) {
+          headers.set("Authorization", `Bearer ${token}`);
+        }
+      } catch {
+        // Token acquisition failed — proceed without
+      }
+    }
+
+    if (input instanceof Request) {
+      // Build a fresh Request against the rewritten URL, copying every
+      // field the runtime exposes on the original — explicit field copy
+      // is more portable than `new Request(url, originalRequest)`, which
+      // some runtimes (older undici/JSDOM in particular) do not honor
+      // for method/body. `init` then overrides anything the caller passed.
+      const cloned = input.clone();
+      const requestInit: RequestInit = {
+        method: cloned.method,
+        body:
+          cloned.method === "GET" || cloned.method === "HEAD" ? undefined : cloned.body,
+        headers,
+        credentials: cloned.credentials,
+        mode: cloned.mode,
+        cache: cloned.cache,
+        redirect: cloned.redirect,
+        referrer: cloned.referrer,
+        integrity: cloned.integrity,
+        signal: cloned.signal,
+      };
+      // Streaming bodies need duplex: "half"; harmless when there's no body.
+      if (cloned.body !== null) {
+        (requestInit as RequestInit & { duplex?: string }).duplex = "half";
+      }
+      return fetch(resolvedUrl, { ...requestInit, ...init, headers });
+    }
+    return fetch(resolvedUrl, { ...init, headers });
+  };
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// --- AG-UI runner ---
+export { AGUIRunner, type AGUIRunnerOptions, type AGUIRunInput } from "./client/agui-runner.ts";
+export type { RunnerEvent } from "./client/runner-events.ts";
+
+// --- Service fetch factory ---
+export {
+  createServiceFetch,
+  type ServiceFetch,
+  type ServiceFetchOptions,
+} from "./client/service-fetch.ts";
+
+// --- Tool registry ---
+export {
+  clientToolRegistry,
+  type ClientToolEntry,
+  type ToolRegistry,
+} from "./tools/registry.ts";
+
+// --- Stores (vanilla) ---
+export {
+  streamingStatusStore,
+  type StreamingStatus,
+} from "./store/streaming-status-store.ts";
+export {
+  citationStore,
+  type CitationResult,
+  type CitationHandler,
+} from "./store/citation-store.ts";

package/src/msal/auth-config.ts

@@ -0,0 +1,90 @@
+/**
+ * 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; // https://login.microsoftonline.com/{tenantId}
+  redirectUri: string; // window.location.origin
+  apiScope: string; // api://{apiClientId}/access_as_user
+  postLogoutRedirectUri?: string;
+}
+
+export interface MsalAccountInfo {
+  username: string;
+  localAccountId: string;
+  name?: string | null;
+}
+
+export interface MsalClientApplication {
+  initialize(): Promise<void>;
+  handleRedirectPromise(): Promise<unknown>;
+  getAllAccounts(): MsalAccountInfo[];
+  loginRedirect(request: { scopes: string[]; prompt?: string }): Promise<void>;
+  logoutRedirect(): Promise<void>;
+  setActiveAccount(account: MsalAccountInfo | null): void;
+  acquireTokenSilent(request: {
+    scopes: string[];
+    account: MsalAccountInfo;
+  }): Promise<{ accessToken: string }>;
+  acquireTokenRedirect(request: {
+    scopes: string[];
+    account: MsalAccountInfo;
+  }): Promise<void>;
+  acquireTokenPopup(request: {
+    scopes: string[];
+    account: MsalAccountInfo;
+  }): Promise<{ accessToken: string }>;
+}
+
+let msalInstance: MsalClientApplication | null = null;
+let msalConfig: MsalAuthConfig | null = 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: MsalAuthConfig,
+): Promise<MsalClientApplication> {
+  if (msalInstance) return msalInstance;
+
+  const { PublicClientApplication: PCA } = await import("@azure/msal-browser");
+
+  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",
+    },
+  };
+
+  msalInstance = new (PCA as new (config: typeof msalConfiguration) => MsalClientApplication)(
+    msalConfiguration,
+  );
+  await msalInstance.initialize();
+  msalConfig = config;
+  return msalInstance;
+}
+
+/** Get the MSAL instance (null when not configured). */
+export function getMsalInstance(): MsalClientApplication | null {
+  return msalInstance;
+}
+
+/** Get the MSAL auth config (null when not configured). */
+export function getMsalConfig(): MsalAuthConfig | null {
+  return msalConfig;
+}

package/src/msal/auth-store.ts

@@ -0,0 +1,72 @@
+import { createStore } from "zustand/vanilla";
+import { getMsalInstance, getMsalConfig } from "./auth-config.ts";
+
+export interface AuthUser {
+  name: string;
+  email: string;
+  avatar?: string;
+  oid?: string;
+}
+
+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).
+   */
+  getAccessToken: (audience?: "api" | "spaces") => Promise<string | null>;
+}
+
+export const authStore = createStore<AuthState>((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") => {
+    const msal = getMsalInstance();
+    const config = getMsalConfig();
+    if (!msal || !config) return null;
+
+    const accounts = msal.getAllAccounts();
+    if (accounts.length === 0) return null;
+
+    // Single API-scoped token — Spaces accepts both audiences (multi-audience JWT)
+    const scope = config.apiScope;
+
+    try {
+      const result = await msal.acquireTokenSilent({
+        scopes: [scope],
+        account: accounts[0],
+      });
+      return result.accessToken;
+    } catch {
+      // Silent acquisition failed — trigger interactive redirect
+      try {
+        await msal.acquireTokenRedirect({
+          scopes: [scope],
+          account: accounts[0],
+        });
+      } catch {
+        // Redirect will navigate away; nothing to return
+      }
+      return null;
+    }
+  },
+}));

package/src/msal/index.ts

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

package/src/msal/token-fetch.ts

@@ -0,0 +1,30 @@
+/**
+ * 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()`.
+ */
+
+import { authStore } from "./auth-store.ts";
+
+export async function tokenFetch(
+  input: string | URL | Request,
+  init?: RequestInit,
+): Promise<Response> {
+  const token = await authStore.getState().getAccessToken("api");
+
+  if (!token) {
+    return fetch(input, 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(input, { ...init, headers });
+}

package/src/store/citation-store.ts

@@ -0,0 +1,45 @@
+import { createStore } from "zustand/vanilla";
+
+/** 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;
+  /** Clear all citations (e.g. on new conversation) */
+  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 const citationStore = createStore<CitationState>((set) => ({
+  results: [],
+  handler: null,
+  setResults: (results) => set({ results }),
+  setHandler: (handler) => set({ handler }),
+  clear: () => set({ results: [], handler: null }),
+}));

package/src/store/streaming-status-store.ts

@@ -0,0 +1,21 @@
+import { createStore } from "zustand/vanilla";
+
+/** 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 const streamingStatusStore = createStore<StreamingStatusState>((set) => ({
+  streamingStatus: { status: "idle" },
+  setStreamingStatus: (streamingStatus) => set({ streamingStatus }),
+}));

package/src/tools/registry.ts

@@ -0,0 +1,112 @@
+import { createStore } from "zustand/vanilla";
+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 const clientToolRegistry = createStore<ClientToolRegistryState>((set, get) => ({
+  globalTools: new Map(),
+  pageTools: new Map(),
+
+  registerGlobal: (tool) => {
+    const { globalTools } = get();
+    const next = new Map(globalTools);
+    next.set(tool.name, tool);
+    set({ globalTools: next });
+  },
+
+  registerPageTools: (tools) => {
+    const next = new Map<string, ClientToolEntry>();
+    for (const tool of tools) {
+      next.set(tool.name, tool);
+    }
+    set({ pageTools: next });
+  },
+
+  clearPageTools: () => {
+    set({ pageTools: new Map() });
+  },
+
+  getActiveSchemas: () => {
+    const { globalTools, pageTools } = get();
+    // Merge: page tools override global tools with the same name
+    const merged = new Map<string, ClientToolEntry>();
+    for (const tool of globalTools.values()) {
+      merged.set(tool.name, tool);
+    }
+    for (const tool of pageTools.values()) {
+      merged.set(tool.name, tool); // page overrides global
+    }
+    return Array.from(merged.values()).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    }));
+  },
+
+  isRegistered: (name) => {
+    const { globalTools, pageTools } = get();
+    return pageTools.has(name) || globalTools.has(name);
+  },
+
+  executeTool: async (name, argsJson) => {
+    const { globalTools, pageTools } = get();
+    // Page tools take precedence
+    const tool = pageTools.get(name) ?? globalTools.get(name);
+    if (!tool) {
+      return JSON.stringify({ error: `Unknown client tool: ${name}` });
+    }
+    return tool.execute(argsJson);
+  },
+}));
+
+/** Read-only registry view — what the runner consumes. */
+export interface ToolRegistry {
+  isRegistered: (name: string) => boolean;
+  executeTool: (name: string, argsJson: string) => Promise<string>;
+  getActiveSchemas: () => AGUITool[];
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    include: ["src/**/*.test.{ts,tsx}"],
+  },
+});