@iloveagents/foundry-agent 0.1.0

package/src/__tests__/service-fetch.test.ts

@@ -0,0 +1,186 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createServiceFetch } from "../client/service-fetch.ts";
+
+describe("createServiceFetch", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(null, { status: 200 }));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("attaches Bearer token from acquireToken", async () => {
+    const acquireToken = vi.fn().mockResolvedValue("test-token");
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    await serviceFetch("/api/spaces/entities");
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe("/api/spaces/entities");
+    const headers = new Headers(init?.headers);
+    expect(headers.get("Authorization")).toBe("Bearer test-token");
+  });
+
+  it("skips token attachment when acquireToken returns null", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    await serviceFetch("/api/spaces/entities");
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [, init] = fetchSpy.mock.calls[0]!;
+    const headers = new Headers(init?.headers);
+    expect(headers.get("Authorization")).toBeNull();
+  });
+
+  it("skips token attachment when Authorization header already present", async () => {
+    const acquireToken = vi.fn().mockResolvedValue("test-token");
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    await serviceFetch("/api/spaces/entities", {
+      headers: { Authorization: "Bearer pre-existing" },
+    });
+
+    expect(acquireToken).not.toHaveBeenCalled();
+    const [, init] = fetchSpy.mock.calls[0]!;
+    const headers = new Headers(init?.headers);
+    expect(headers.get("Authorization")).toBe("Bearer pre-existing");
+  });
+
+  it("rewrites local-relative URLs to baseUrl when configured", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({
+      acquireToken,
+      baseUrl: "https://api.example.com",
+    });
+
+    await serviceFetch("/api/spaces/entities");
+
+    const [url] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe("https://api.example.com/api/spaces/entities");
+  });
+
+  it("strips origin prefix before applying baseUrl", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({
+      acquireToken,
+      baseUrl: "https://api.example.com",
+      originResolver: () => "https://app.example.com",
+    });
+
+    await serviceFetch("https://app.example.com/api/spaces/entities");
+
+    const [url] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe("https://api.example.com/api/spaces/entities");
+  });
+
+  it("leaves URL untouched when baseUrl is empty (dev mode)", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    await serviceFetch("/api/spaces/entities");
+
+    const [url] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe("/api/spaces/entities");
+  });
+
+  it("strips trailing slashes from baseUrl", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({
+      acquireToken,
+      baseUrl: "https://api.example.com//",
+    });
+
+    await serviceFetch("/api/spaces/entities");
+
+    const [url] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe("https://api.example.com/api/spaces/entities");
+  });
+
+  it("passes URL objects through correctly", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    await serviceFetch(new URL("https://example.com/api/items"));
+
+    const [url] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe("https://example.com/api/items");
+  });
+
+  it("preserves Request method/body/headers when input is a Request", async () => {
+    const acquireToken = vi.fn().mockResolvedValue("test-token");
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    const req = new Request("https://example.com/api/items", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Custom": "from-request" },
+      body: JSON.stringify({ ok: true }),
+    });
+
+    await serviceFetch(req);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe("https://example.com/api/items");
+    expect(init?.method).toBe("POST");
+
+    // Body is preserved (as a stream or buffer in the runtime).
+    expect(init?.body).toBeDefined();
+
+    const merged = new Headers(init?.headers);
+    expect(merged.get("Authorization")).toBe("Bearer test-token");
+    expect(merged.get("X-Custom")).toBe("from-request");
+    expect(merged.get("Content-Type")).toBe("application/json");
+  });
+
+  it("does not attach a body for GET Requests", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    const req = new Request("https://example.com/api/items", {
+      method: "GET",
+      headers: { "X-Custom": "from-request" },
+    });
+
+    await serviceFetch(req);
+
+    const [, init] = fetchSpy.mock.calls[0]!;
+    expect(init?.method).toBe("GET");
+    expect(init?.body).toBeUndefined();
+  });
+
+  it("init headers override Request headers when both supplied", async () => {
+    const acquireToken = vi.fn().mockResolvedValue(null);
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    const req = new Request("https://example.com/api/items", {
+      headers: { "X-Override": "from-request", "X-Request-Only": "req" },
+    });
+
+    await serviceFetch(req, { headers: { "X-Override": "from-init", "X-Init-Only": "init" } });
+
+    const [, init] = fetchSpy.mock.calls[0]!;
+    const merged = new Headers(init?.headers);
+    expect(merged.get("X-Override")).toBe("from-init");
+    expect(merged.get("X-Request-Only")).toBe("req");
+    expect(merged.get("X-Init-Only")).toBe("init");
+  });
+
+  it("recovers when acquireToken throws", async () => {
+    const acquireToken = vi.fn().mockRejectedValue(new Error("token boom"));
+    const serviceFetch = createServiceFetch({ acquireToken });
+
+    await serviceFetch("/api/spaces/entities");
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [, init] = fetchSpy.mock.calls[0]!;
+    const headers = new Headers(init?.headers);
+    expect(headers.get("Authorization")).toBeNull();
+  });
+});

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

@@ -0,0 +1,22 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { streamingStatusStore } from "../store/streaming-status-store.ts";
+
+const store = () => streamingStatusStore.getState();
+
+describe("streamingStatusStore", () => {
+  beforeEach(() => {
+    streamingStatusStore.setState({ streamingStatus: { status: "idle" } });
+  });
+
+  it("starts with idle status", () => {
+    expect(store().streamingStatus).toEqual({ status: "idle" });
+  });
+
+  it("updates streaming status", () => {
+    store().setStreamingStatus({ status: "calling", toolName: "get_weather" });
+    expect(store().streamingStatus).toEqual({
+      status: "calling",
+      toolName: "get_weather",
+    });
+  });
+});

package/src/__tests__/token-fetch.test.ts

@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const getAccessToken = vi.fn();
+
+vi.mock("../msal/auth-store.ts", () => ({
+  authStore: {
+    getState: () => ({
+      getAccessToken,
+    }),
+  },
+}));
+
+import { tokenFetch } from "../msal/token-fetch.ts";
+
+describe("tokenFetch", () => {
+  beforeEach(() => {
+    getAccessToken.mockReset();
+    vi.restoreAllMocks();
+  });
+
+  it("merges Request headers and lets init headers take precedence", async () => {
+    getAccessToken.mockResolvedValue("test-token");
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(null, { status: 200 }));
+
+    const request = new Request("https://example.com/api/items", {
+      headers: {
+        "Content-Type": "application/json",
+        "X-Request-Only": "request",
+        "X-Override": "request",
+      },
+    });
+
+    await tokenFetch(request, {
+      headers: {
+        "X-Init-Only": "init",
+        "X-Override": "init",
+      },
+    });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [, init] = fetchSpy.mock.calls[0]!;
+    const headers = new Headers(init?.headers);
+
+    expect(headers.get("Authorization")).toBe("Bearer test-token");
+    expect(headers.get("Content-Type")).toBe("application/json");
+    expect(headers.get("X-Request-Only")).toBe("request");
+    expect(headers.get("X-Init-Only")).toBe("init");
+    expect(headers.get("X-Override")).toBe("init");
+  });
+
+  it("falls through to native fetch when no token is available", async () => {
+    getAccessToken.mockResolvedValue(null);
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response(null, { status: 200 }));
+
+    await tokenFetch("https://example.com/api/items");
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [, init] = fetchSpy.mock.calls[0]!;
+    expect(init).toBeUndefined();
+  });
+});

package/src/client/agui-runner.ts

@@ -0,0 +1,330 @@
+/**
+ * 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, type AgentSubscriber } from "@ag-ui/client";
+import type { Context, Message, Tool } from "@ag-ui/core";
+import type { ToolRegistry } from "../tools/registry.ts";
+import type { RunnerEvent } from "./runner-events.ts";
+
+interface ToolCallState {
+  id: string;
+  name: string;
+  args: string;
+  result?: unknown;
+  isError?: boolean;
+  followedUp?: boolean;
+}
+
+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[];
+}
+
+/**
+ * Bridges callback-driven `AgentSubscriber` events into an async-iterable
+ * queue the runner's generator drains. Single-producer / single-consumer.
+ */
+class EventQueue<T> {
+  private buffer: T[] = [];
+  private resolve: (() => void) | null = null;
+  private ended = false;
+  private error: unknown = null;
+
+  push(value: T): void {
+    this.buffer.push(value);
+    this.flush();
+  }
+
+  end(error?: unknown): void {
+    this.ended = true;
+    if (error !== undefined) this.error = error;
+    this.flush();
+  }
+
+  private flush(): void {
+    if (this.resolve) {
+      const r = this.resolve;
+      this.resolve = null;
+      r();
+    }
+  }
+
+  async *drain(): AsyncGenerator<T> {
+    for (;;) {
+      if (this.buffer.length > 0) {
+        yield this.buffer.shift()!;
+        continue;
+      }
+      if (this.ended) {
+        if (this.error) throw this.error;
+        return;
+      }
+      await new Promise<void>((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 {
+  private readonly httpAgent: HttpAgent;
+
+  constructor(options: AGUIRunnerOptions = {}) {
+    this.httpAgent = new HttpAgent({
+      url: options.url ?? "/api/agent",
+      threadId: options.threadId ?? crypto.randomUUID(),
+      ...(options.fetchFn ? { fetch: options.fetchFn } : {}),
+    });
+  }
+
+  get threadId(): string {
+    return this.httpAgent.threadId;
+  }
+
+  get state(): unknown {
+    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: AGUIRunInput): AsyncGenerator<RunnerEvent> {
+    const { messages, state, registry, abortSignal, context } = input;
+    const toolCalls = new Map<string, ToolCallState>();
+    let currentMessages: Message[] = [...messages];
+
+    // Replace once at the top: subsequent turns append to currentMessages
+    // (per AG-UI convention — see footgun in apps/web AGENTS.md cross-link).
+    this.httpAgent.setMessages(currentMessages);
+    if (state) this.httpAgent.setState(state);
+
+    try {
+      for (;;) {
+        if (abortSignal?.aborted) return;
+
+        const tools: Tool[] = registry.getActiveSchemas();
+        const queue = new EventQueue<RunnerEvent>();
+        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: Record<string, unknown> = {
+          threadId: this.httpAgent.threadId,
+          runId,
+          state: { ...((this.httpAgent.state as Record<string, unknown>) || {}), ...(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: AgentSubscriber = {
+          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: unknown = 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: unknown) => 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: Message = {
+          id: crypto.randomUUID(),
+          role: "assistant",
+          content: turnAssistantText,
+          toolCalls: pendingClientTools.map((tc) => ({
+            id: tc.id,
+            type: "function" as const,
+            function: { name: tc.name, arguments: tc.args },
+          })),
+        };
+
+        const toolResultMsgs: Message[] = 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/src/client/runner-events.ts

@@ -0,0 +1,27 @@
+import type { StreamingStatus } from "../store/streaming-status-store.ts";
+
+/**
+ * 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 };