@iloveagents/foundry-agent 0.3.1 → 0.4.0

package/README.md

@@ -0,0 +1,16 @@
+# @iloveagents/foundry-agent
+
+Cross-runtime AG-UI transport for Foundry UI.
+
+This package contains the non-React pieces: `AGUIRunner`, service fetch helpers,
+client-tool registry, streaming status store, citation/link stores, and the
+optional MSAL subpath.
+
+## Imports
+
+```ts
+import { AGUIRunner, createServiceFetch } from "@iloveagents/foundry-agent";
+import { authStore, tokenFetch } from "@iloveagents/foundry-agent/msal";
+```
+
+This package publishes built ESM JavaScript and `.d.ts` declarations.

package/dist/client/agui-runner.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AG-UI Runner — protocol engine for `@iloveagents/foundry-agent`.
+ *
+ * Drives the AG-UI SDK's `HttpAgent.runAgent()` with an `AgentSubscriber`,
+ * fans the subscriber callbacks out as a normalized `RunnerEvent` stream,
+ * and re-issues the run with appended assistant + tool messages whenever a
+ * client-side tool produces a result.
+ *
+ * Framework-agnostic — no React, no `@assistant-ui/*`. The assistant-ui shim
+ * in `@iloveagents/foundry-web-ui` (and future Outlook / Teams / native shells)
+ * translate `RunnerEvent`s into their own model.
+ *
+ * @see https://docs.ag-ui.com/sdk/js/client/http-agent
+ * @see https://docs.ag-ui.com/sdk/js/client/subscriber
+ */
+import type { Context, Message } from "@ag-ui/core";
+import type { ToolRegistry } from "../tools/registry.js";
+import type { RunnerEvent } from "./runner-events.js";
+export interface AGUIRunnerOptions {
+    url?: string;
+    threadId?: string;
+    /** Optional override for the underlying fetch — useful for auth-attached fetch. */
+    fetchFn?: typeof fetch;
+}
+export interface AGUIRunInput {
+    /** AG-UI messages — caller is responsible for runtime-specific message conversion. */
+    messages: Message[];
+    /** Optional state snapshot (e.g. context items) sent to the agent. */
+    state?: Record<string, unknown>;
+    /** Tool registry consulted for client-side tool dispatch + schemas. */
+    registry: ToolRegistry;
+    /** Aborts the run — generator returns cleanly when the signal fires. */
+    abortSignal?: AbortSignal;
+    /** Optional context payload forwarded with every turn (default: empty array). */
+    context?: Context[];
+}
+/**
+ * AG-UI Runner.
+ *
+ * Reusable across runs — instantiate once, call `run()` per turn batch.
+ * Maintains `threadId` and the `HttpAgent` state snapshot across calls.
+ */
+export declare class AGUIRunner {
+    private readonly httpAgent;
+    constructor(options?: AGUIRunnerOptions);
+    get threadId(): string;
+    get state(): unknown;
+    /**
+     * Run a single AG-UI exchange (with multi-turn re-issue when client-side
+     * tool results are produced) and yield normalized events.
+     */
+    run(input: AGUIRunInput): AsyncGenerator<RunnerEvent>;
+}

package/dist/client/agui-runner.js

@@ -0,0 +1,320 @@
+/**
+ * AG-UI Runner — protocol engine for `@iloveagents/foundry-agent`.
+ *
+ * Drives the AG-UI SDK's `HttpAgent.runAgent()` with an `AgentSubscriber`,
+ * fans the subscriber callbacks out as a normalized `RunnerEvent` stream,
+ * and re-issues the run with appended assistant + tool messages whenever a
+ * client-side tool produces a result.
+ *
+ * Framework-agnostic — no React, no `@assistant-ui/*`. The assistant-ui shim
+ * in `@iloveagents/foundry-web-ui` (and future Outlook / Teams / native shells)
+ * translate `RunnerEvent`s into their own model.
+ *
+ * @see https://docs.ag-ui.com/sdk/js/client/http-agent
+ * @see https://docs.ag-ui.com/sdk/js/client/subscriber
+ */
+import { HttpAgent } from "@ag-ui/client";
+function shouldPreserveAcrossVisibleHistory(message) {
+    return message.role === "system" || message.role === "developer" || message.role === "reasoning";
+}
+function mergeProtocolMessagesFromSnapshot(previousMessages, visibleMessages) {
+    if (previousMessages.length === 0)
+        return [...visibleMessages];
+    const visibleById = new Map(visibleMessages.map((message) => [message.id, message]));
+    const previousVisibleIds = new Set(previousMessages
+        .filter((message) => !shouldPreserveAcrossVisibleHistory(message))
+        .map((message) => message.id));
+    const isSameVisibleThread = visibleMessages.some((message) => previousVisibleIds.has(message.id));
+    if (!isSameVisibleThread)
+        return [...visibleMessages];
+    const merged = [];
+    const emitted = new Set();
+    for (const previous of previousMessages) {
+        const currentVisible = visibleById.get(previous.id);
+        if (currentVisible) {
+            merged.push(currentVisible);
+            emitted.add(currentVisible.id);
+            continue;
+        }
+        if (shouldPreserveAcrossVisibleHistory(previous)) {
+            merged.push(previous);
+            emitted.add(previous.id);
+        }
+    }
+    for (const message of visibleMessages) {
+        if (!emitted.has(message.id)) {
+            merged.push(message);
+        }
+    }
+    return merged;
+}
+/**
+ * Bridges callback-driven `AgentSubscriber` events into an async-iterable
+ * queue the runner's generator drains. Single-producer / single-consumer.
+ */
+class EventQueue {
+    constructor() {
+        this.buffer = [];
+        this.resolve = null;
+        this.ended = false;
+        this.error = null;
+    }
+    push(value) {
+        this.buffer.push(value);
+        this.flush();
+    }
+    end(error) {
+        this.ended = true;
+        if (error !== undefined)
+            this.error = error;
+        this.flush();
+    }
+    flush() {
+        if (this.resolve) {
+            const r = this.resolve;
+            this.resolve = null;
+            r();
+        }
+    }
+    async *drain() {
+        for (;;) {
+            if (this.buffer.length > 0) {
+                yield this.buffer.shift();
+                continue;
+            }
+            if (this.ended) {
+                if (this.error)
+                    throw this.error;
+                return;
+            }
+            await new Promise((r) => {
+                this.resolve = r;
+            });
+        }
+    }
+}
+/**
+ * AG-UI Runner.
+ *
+ * Reusable across runs — instantiate once, call `run()` per turn batch.
+ * Maintains `threadId` and the `HttpAgent` state snapshot across calls.
+ */
+export class AGUIRunner {
+    constructor(options = {}) {
+        this.httpAgent = new HttpAgent({
+            url: options.url ?? "/api/agent",
+            threadId: options.threadId ?? crypto.randomUUID(),
+            ...(options.fetchFn ? { fetch: options.fetchFn } : {}),
+        });
+    }
+    get threadId() {
+        return this.httpAgent.threadId;
+    }
+    get state() {
+        return this.httpAgent.state;
+    }
+    /**
+     * Run a single AG-UI exchange (with multi-turn re-issue when client-side
+     * tool results are produced) and yield normalized events.
+     */
+    async *run(input) {
+        const { messages, state, registry, abortSignal, context } = input;
+        const toolCalls = new Map();
+        let currentMessages = mergeProtocolMessagesFromSnapshot(this.httpAgent.messages, messages);
+        // Replace once at the top with the reconciled AG-UI history. assistant-ui
+        // stores only visible chat turns, while AG-UI snapshots may contain
+        // model-visible but UI-hidden protocol messages such as system/developer
+        // guidance. Preserve those messages across turns when the visible history
+        // belongs to the same thread so the next request remains a complete AG-UI
+        // conversation without leaking system messages into the rendered chat.
+        this.httpAgent.setMessages(currentMessages);
+        if (state)
+            this.httpAgent.setState(state);
+        try {
+            for (;;) {
+                if (abortSignal?.aborted)
+                    return;
+                const tools = registry.getActiveSchemas();
+                const queue = new EventQueue();
+                const runId = crypto.randomUUID();
+                // Per-turn text accumulator. The model can emit text BEFORE a
+                // tool call in the same turn ("Looking up X..." then ui_navigate);
+                // dropping it from the follow-up replay changes the next-turn
+                // context (no server-side thread state — full history rides each
+                // request) and causes inconsistent continuations.
+                let turnAssistantText = "";
+                // Build the request input now, before runAgent fires — dev tooling
+                // consumes this snapshot via the request-sent event. `runId` is
+                // pre-generated so the snapshot matches what runAgent emits.
+                const runInputSnapshot = {
+                    threadId: this.httpAgent.threadId,
+                    runId,
+                    state: { ...(this.httpAgent.state || {}), ...(state ?? {}) },
+                    messages: currentMessages,
+                    tools,
+                    context: context ?? [],
+                };
+                queue.push({ type: "turn-started" });
+                queue.push({ type: "streaming-status", status: { status: "thinking" } });
+                queue.push({ type: "request-sent", input: runInputSnapshot });
+                const subscriber = {
+                    onRunStartedEvent: () => {
+                        queue.push({ type: "run-started" });
+                        queue.push({ type: "streaming-status", status: { status: "thinking" } });
+                    },
+                    onTextMessageStartEvent: () => {
+                        queue.push({ type: "streaming-status", status: { status: "streaming" } });
+                    },
+                    onTextMessageContentEvent: ({ event }) => {
+                        turnAssistantText += event.delta;
+                        queue.push({ type: "text-delta", delta: event.delta });
+                    },
+                    onTextMessageEndEvent: () => {
+                        queue.push({ type: "text-message-end" });
+                    },
+                    onToolCallStartEvent: ({ event }) => {
+                        const id = event.toolCallId;
+                        const name = event.toolCallName;
+                        toolCalls.set(id, { id, name, args: "" });
+                        queue.push({
+                            type: "streaming-status",
+                            status: { status: "calling", toolName: name },
+                        });
+                        queue.push({
+                            type: "tool-call-start",
+                            id,
+                            name,
+                            isClientSide: registry.isRegistered(name),
+                        });
+                    },
+                    onToolCallArgsEvent: ({ event }) => {
+                        const tc = toolCalls.get(event.toolCallId);
+                        if (tc)
+                            tc.args += event.delta;
+                        queue.push({ type: "tool-call-args", id: event.toolCallId, delta: event.delta });
+                    },
+                    onToolCallEndEvent: async ({ event }) => {
+                        const tc = toolCalls.get(event.toolCallId);
+                        if (!tc)
+                            return;
+                        // Intercept client-side tools — execute locally and stash the
+                        // result so the multi-turn loop can replay it on the next turn.
+                        if (registry.isRegistered(tc.name)) {
+                            try {
+                                const resultJson = await registry.executeTool(tc.name, tc.args);
+                                tc.result = JSON.parse(resultJson);
+                            }
+                            catch (err) {
+                                tc.result = {
+                                    error: err instanceof Error ? err.message : "Client-side tool failed",
+                                };
+                                tc.isError = true;
+                            }
+                        }
+                        queue.push({
+                            type: "tool-call-end",
+                            id: event.toolCallId,
+                            args: tc.args,
+                            result: tc.result,
+                            isError: tc.isError,
+                        });
+                    },
+                    onToolCallResultEvent: ({ event }) => {
+                        const tc = toolCalls.get(event.toolCallId);
+                        if (!tc)
+                            return;
+                        const content = event.content;
+                        let parsedResult = content;
+                        let isError = false;
+                        try {
+                            const parsed = JSON.parse(content);
+                            parsedResult = parsed;
+                            if (parsed && typeof parsed === "object" && "error" in parsed) {
+                                isError = true;
+                            }
+                        }
+                        catch {
+                            parsedResult = content;
+                        }
+                        tc.result = parsedResult;
+                        tc.isError = isError;
+                        queue.push({
+                            type: "tool-call-result",
+                            id: event.toolCallId,
+                            result: parsedResult,
+                            isError,
+                        });
+                    },
+                    onRunFinishedEvent: () => {
+                        queue.push({ type: "streaming-status", status: { status: "idle" } });
+                        queue.push({ type: "run-finished" });
+                    },
+                    onRunErrorEvent: ({ event }) => {
+                        queue.push({ type: "streaming-status", status: { status: "idle" } });
+                        queue.push({ type: "run-error", message: event.message ?? "Run error" });
+                    },
+                };
+                // Wire abort: AG-UI exposes abortRun(); call it when the caller's signal fires.
+                const onAbort = () => this.httpAgent.abortRun();
+                abortSignal?.addEventListener("abort", onAbort, { once: true });
+                // Kick off the run — completion ends the queue. Errors during the
+                // run surface via onRunErrorEvent; transport-level rejections
+                // (e.g. fetch failure) are propagated through queue.end(err).
+                const runPromise = this.httpAgent
+                    .runAgent({ runId, tools, context: context ?? [] }, subscriber)
+                    .then(() => queue.end())
+                    .catch((err) => queue.end(err));
+                try {
+                    for await (const evt of queue.drain()) {
+                        yield evt;
+                        if (abortSignal?.aborted) {
+                            this.httpAgent.abortRun();
+                            return;
+                        }
+                    }
+                }
+                finally {
+                    abortSignal?.removeEventListener("abort", onAbort);
+                    await runPromise; // ensure the run task is settled
+                }
+                // Decide whether to re-issue: any client-side tool that resolved
+                // during this turn and hasn't been replayed yet.
+                const pendingClientTools = Array.from(toolCalls.values()).filter((tc) => registry.isRegistered(tc.name) && tc.result !== undefined && !tc.followedUp);
+                if (pendingClientTools.length === 0)
+                    break;
+                for (const tc of pendingClientTools)
+                    tc.followedUp = true;
+                // Build follow-up messages with the SAME toolCallId the agent emitted.
+                // Tool results are appended to the agent's message history (AG-UI
+                // convention — append, never replace). Preserve any pre-tool text
+                // the model emitted in this turn so the next-turn context matches
+                // what the user actually saw.
+                const assistantMsg = {
+                    id: crypto.randomUUID(),
+                    role: "assistant",
+                    content: turnAssistantText,
+                    toolCalls: pendingClientTools.map((tc) => ({
+                        id: tc.id,
+                        type: "function",
+                        function: { name: tc.name, arguments: tc.args },
+                    })),
+                };
+                const toolResultMsgs = pendingClientTools.map((tc) => ({
+                    id: crypto.randomUUID(),
+                    role: "tool",
+                    toolCallId: tc.id,
+                    content: typeof tc.result === "string" ? tc.result : JSON.stringify(tc.result),
+                }));
+                currentMessages = [...currentMessages, assistantMsg, ...toolResultMsgs];
+                for (const m of [assistantMsg, ...toolResultMsgs]) {
+                    this.httpAgent.addMessage(m);
+                }
+            }
+        }
+        finally {
+            // Normalized terminal status — idempotent if onRunFinishedEvent already
+            // fired one. Consumers ignore duplicate idle transitions.
+            yield { type: "streaming-status", status: { status: "idle" } };
+        }
+    }
+}

package/dist/client/runner-events.d.ts

@@ -0,0 +1,54 @@
+import type { StreamingStatus } from "../store/streaming-status-store.js";
+/**
+ * Normalized event stream emitted by `AGUIRunner.run()`. The runner is
+ * framework-agnostic; consumers (e.g. the assistant-ui shim in
+ * `@iloveagents/foundry-web-ui`) translate these events into their own runtime model.
+ *
+ * `request-sent` carries the exact AG-UI request payload — used by host
+ * dev-tooling to capture each turn.
+ *
+ * `turn-started` fires at the top of every iteration of the multi-turn loop
+ * (initial request + each client-tool follow-up). Consumers reset their
+ * per-turn buffers (e.g. `currentText`) here.
+ */
+export type RunnerEvent = {
+    type: "request-sent";
+    input: Record<string, unknown>;
+} | {
+    type: "turn-started";
+} | {
+    type: "run-started";
+} | {
+    type: "text-delta";
+    delta: string;
+} | {
+    type: "text-message-end";
+} | {
+    type: "tool-call-start";
+    id: string;
+    name: string;
+    isClientSide: boolean;
+} | {
+    type: "tool-call-args";
+    id: string;
+    delta: string;
+} | {
+    type: "tool-call-end";
+    id: string;
+    args: string;
+    result?: unknown;
+    isError?: boolean;
+} | {
+    type: "tool-call-result";
+    id: string;
+    result: unknown;
+    isError: boolean;
+} | {
+    type: "streaming-status";
+    status: StreamingStatus;
+} | {
+    type: "run-finished";
+} | {
+    type: "run-error";
+    message: string;
+};

package/dist/client/runner-events.js

@@ -0,0 +1 @@
+export {};

package/dist/client/service-fetch.d.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).
+     *
+     * The optional ``{ forceRefresh: true }`` argument is passed by the
+     * fetch interceptor on a 401 retry — the auth layer should bypass
+     * its local token cache and round-trip the token endpoint so we
+     * stop re-sending an access token the resource server has already
+     * rejected (canonical MSAL.js fix for tab-open-overnight 401 loops).
+     */
+    acquireToken: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+    /**
+     * Force interactive recovery (e.g. ``loginRedirect``) when even a
+     * force-refreshed access token gets rejected by the resource server.
+     * The fetch interceptor calls this after a SECOND consecutive 401 —
+     * at that point we know the silent refresh produced a token the
+     * server still won't accept (audience drift, conditional-access
+     * re-eval, tenant-policy change), and the only correct UX is to
+     * mint a fresh session.
+     *
+     * Implementations should clear cached auth state and start a redirect
+     * to the IdP. They MUST throw rather than return so the fetch caller
+     * can stop processing the in-flight request — when this resolves
+     * normally the redirect is in flight and the page is about to
+     * navigate away.
+     *
+     * Optional: when omitted, the fetch interceptor lets the second 401
+     * propagate as-is. Hosts without an interactive recovery path (e.g.
+     * tests, embedded apps) should leave it unset.
+     */
+    recoverFromHardAuthFailure?: (reason: unknown) => Promise<never>;
+    /**
+     * 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>;
+/**
+ * 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 declare class TokenAcquisitionError extends Error {
+    readonly name = "TokenAcquisitionError";
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/**
+ * Build a service-fetch function. Returns a function with the same shape as
+ * `fetch` that rewrites URLs + attaches the Bearer token from `acquireToken`.
+ */
+export declare function createServiceFetch(options: ServiceFetchOptions): ServiceFetch;
+/**
+ * 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 declare class AuthInteractionRequiredError extends Error {
+    readonly name = "AuthInteractionRequiredError";
+    readonly claims?: string;
+    constructor(message: string, options?: {
+        claims?: string;
+    });
+}
+/**
+ * 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 declare function parseClaimsChallengeFromWwwAuthenticate(header: string | null | undefined): string | undefined;