@iloveagents/foundry-agent 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# @iloveagents/foundry-agent
+
+## 0.1.2
+
+### Patch Changes
+
+- 30a4346: fix(agent): retry protected fetch with `forceRefresh` on 401
+
+  Closes the long-lived-tab 401 loop where the only recovery the user had was logging out or clearing localStorage.
+
+  The token-fetch wrapper used to ask MSAL for a cached token and never retry. If the resource server rejected that token (claims challenge, conditional-access re-eval, audience drift, or staleness MSAL's clock-offset check missed), every subsequent request kept re-sending the same token.
+
+  Fix: on 401 from a protected API, retry once with `acquireTokenSilent({ forceRefresh: true })`. If that also fails, the existing `InteractionRequiredAuthError` path bounces the user through Entra ID. Single-retry cap so we never loop. Request bodies are cloned per-attempt (ReadableStream is single-consume) so POST/PUT payloads survive the retry intact.
+
+  The `acquireToken` callback type now accepts an optional `{ forceRefresh? }` argument — non-breaking; existing callbacks continue to work, but they should forward the option to their token source so the retry path actually reaches the auth backend.
+
+  Pair: `lastspace#205` (forwards the option through `spacesFetch.acquireToken`).
+
+## 0.1.1
+
+### Patch Changes
+
+- 689d3e9: feat(sidebar): distinct file-drop affordance for nav containers
+
+  `useNavItemDnd` now exposes `isFileDragOver` separately from `isDragOver`
+  so consuming nav items can render a prominent file-drop visual (dashed
+  primary outline + soft primary background + Upload icon) when the user
+  is dragging native files over the container. Previously file drags
+  shared the same subtle ring as entity-move drags, so users couldn't
+  tell that a folder accepted external files. Applies to all five nav-
+  item shapes (action-row leaf, button leaf, `NestedFolderItem`,
+  `CollapsibleNavItem` with children/actions, `NavLink` fallthrough) and
+  updates `ContainerDropZone` for visual parity.
+
+  Also fixes a related regression: the capture-phase
+  `onDragEnterCapture` / `onDragOverCapture` handlers were calling
+  `e.stopPropagation()`, which short-circuits React's synthetic dispatch
+  and prevented the bubble-phase `onDragEnter` (where state actually
+  mutates) from running. Removed — `preventDefault()` alone is enough to
+  mark the element as droppable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iloveagents/foundry-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "types": "./src/index.ts",

package/src/__tests__/agui-runner.test.ts

@@ -6,7 +6,7 @@ import type { AgentSubscriber } from "@ag-ui/client";
 // runAgent fires them in order, synchronously yielding the loop between
 // each one so the runner's queue can drain.
 
-type ScriptedRun = (subscriber: AgentSubscriber) => Promise<void>;
+type ScriptedRun = (subscriber: AgentSubscriber, agent: { messages: unknown[] }) => Promise<void>;
 
 let nextScript: ScriptedRun[] = [];
 let runCount = 0;
@@ -38,7 +38,7 @@ vi.mock("@ag-ui/client", () => {
       const turnIdx = runCount;
       runCount++;
       const script = nextScript[turnIdx];
-      if (script) await script(subscriber);
+      if (script) await script(subscriber, this);
     }
 
     abortRun() {
@@ -52,7 +52,10 @@ import { AGUIRunner } from "../client/agui-runner.ts";
 import { clientToolRegistry } from "../tools/registry.ts";
 import type { RunnerEvent } from "../client/runner-events.ts";
 
-function makeRegistry(client: { isRegistered: (name: string) => boolean; executeTool?: (name: string, args: string) => Promise<string> }) {
+function makeRegistry(client: {
+  isRegistered: (name: string) => boolean;
+  executeTool?: (name: string, args: string) => Promise<string>;
+}) {
   return {
     isRegistered: client.isRegistered,
     executeTool: client.executeTool ?? (async () => JSON.stringify({})),
@@ -60,7 +63,10 @@ function makeRegistry(client: { isRegistered: (name: string) => boolean; execute
   };
 }
 
-async function collect(runner: AGUIRunner, registry: ReturnType<typeof makeRegistry>): Promise<RunnerEvent[]> {
+async function collect(
+  runner: AGUIRunner,
+  registry: ReturnType<typeof makeRegistry>,
+): Promise<RunnerEvent[]> {
   const out: RunnerEvent[] = [];
   for await (const evt of runner.run({ messages: [], registry })) {
     out.push(evt);
@@ -68,6 +74,18 @@ async function collect(runner: AGUIRunner, registry: ReturnType<typeof makeRegis
   return out;
 }
 
+async function collectWithMessages(
+  runner: AGUIRunner,
+  messages: Parameters<AGUIRunner["run"]>[0]["messages"],
+  registry: ReturnType<typeof makeRegistry>,
+): Promise<RunnerEvent[]> {
+  const out: RunnerEvent[] = [];
+  for await (const evt of runner.run({ messages, registry })) {
+    out.push(evt);
+  }
+  return out;
+}
+
 describe("AGUIRunner", () => {
   beforeEach(() => {
     nextScript = [];
@@ -103,8 +121,8 @@ describe("AGUIRunner", () => {
     expect(types).toContain("text-message-end");
     expect(types).toContain("run-finished");
 
-    const deltas = events.filter((e): e is Extract<RunnerEvent, { type: "text-delta" }> =>
-      e.type === "text-delta",
+    const deltas = events.filter(
+      (e): e is Extract<RunnerEvent, { type: "text-delta" }> => e.type === "text-delta",
     );
     expect(deltas.map((d) => d.delta).join("")).toBe("Hello world");
   });
@@ -121,7 +139,7 @@ describe("AGUIRunner", () => {
           } as never,
         } as never);
         await s.onToolCallArgsEvent?.({
-          event: { type: "TOOL_CALL_ARGS", toolCallId: "tc-1", delta: "{\"q\":\"x\"}" } as never,
+          event: { type: "TOOL_CALL_ARGS", toolCallId: "tc-1", delta: '{"q":"x"}' } as never,
         } as never);
         await s.onToolCallEndEvent?.({
           event: { type: "TOOL_CALL_END", toolCallId: "tc-1" } as never,
@@ -140,8 +158,8 @@ describe("AGUIRunner", () => {
     const runner = new AGUIRunner();
     const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
 
-    const start = events.find((e): e is Extract<RunnerEvent, { type: "tool-call-start" }> =>
-      e.type === "tool-call-start",
+    const start = events.find(
+      (e): e is Extract<RunnerEvent, { type: "tool-call-start" }> => e.type === "tool-call-start",
     );
     expect(start).toBeDefined();
     expect(start!.isClientSide).toBe(false);
@@ -212,8 +230,8 @@ describe("AGUIRunner", () => {
     expect(lastAssistantMsg?.toolCalls?.[0]?.id).toBe("tc-1");
 
     // tool-call-start should have isClientSide=true
-    const start = events.find((e): e is Extract<RunnerEvent, { type: "tool-call-start" }> =>
-      e.type === "tool-call-start",
+    const start = events.find(
+      (e): e is Extract<RunnerEvent, { type: "tool-call-start" }> => e.type === "tool-call-start",
     );
     expect(start!.isClientSide).toBe(true);
   });
@@ -276,6 +294,63 @@ describe("AGUIRunner", () => {
     expect(lastAssistant?.content).toBe("Navigating...");
   });
 
+  it("preserves hidden protocol messages from AG-UI snapshots across visible UI turns", async () => {
+    const registry = makeRegistry({ isRegistered: () => false });
+    const runner = new AGUIRunner();
+
+    nextScript = [
+      async (s, agent) => {
+        agent.messages = [
+          {
+            id: "spaces-global-guidance:abc",
+            role: "system",
+            content: "Tenant guidance",
+          },
+          { id: "u-1", role: "user", content: "What is your name?" },
+          { id: "a-1", role: "assistant", content: "Magic Luna." },
+        ];
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    await collectWithMessages(
+      runner,
+      [{ id: "u-1", role: "user", content: "What is your name?" }],
+      registry,
+    );
+
+    nextScript = [
+      async (s) => {
+        await s.onRunFinishedEvent?.({ event: { type: "RUN_FINISHED" } } as never);
+      },
+    ];
+
+    const events = await collectWithMessages(
+      runner,
+      [
+        { id: "u-1", role: "user", content: "What is your name?" },
+        { id: "a-1", role: "assistant", content: "Magic Luna." },
+        { id: "u-2", role: "user", content: "Say your name again." },
+      ],
+      registry,
+    );
+
+    const request = events.find(
+      (event): event is Extract<RunnerEvent, { type: "request-sent" }> =>
+        event.type === "request-sent",
+    );
+    expect(request?.input.messages).toEqual([
+      {
+        id: "spaces-global-guidance:abc",
+        role: "system",
+        content: "Tenant guidance",
+      },
+      { id: "u-1", role: "user", content: "What is your name?" },
+      { id: "a-1", role: "assistant", content: "Magic Luna." },
+      { id: "u-2", role: "user", content: "Say your name again." },
+    ]);
+  });
+
   it("yields turn-started exactly once per run iteration", async () => {
     nextScript = [
       async (s) => {
@@ -320,8 +395,8 @@ describe("AGUIRunner", () => {
     const runner = new AGUIRunner();
     const events = await collect(runner, makeRegistry({ isRegistered: () => false }));
 
-    const err = events.find((e): e is Extract<RunnerEvent, { type: "run-error" }> =>
-      e.type === "run-error",
+    const err = events.find(
+      (e): e is Extract<RunnerEvent, { type: "run-error" }> => e.type === "run-error",
     );
     expect(err).toBeDefined();
     expect(err!.message).toBe("boom");

package/src/__tests__/auth-store.test.ts

@@ -1,5 +1,6 @@
-import { beforeEach, describe, expect, it } from "vitest";
-import { authStore } from "../msal/auth-store.ts";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AuthInteractionRequiredError, authStore } from "../msal/auth-store.ts";
+import * as authConfig from "../msal/auth-config.ts";
 
 const store = () => authStore.getState();
 
@@ -35,3 +36,231 @@ describe("authStore", () => {
     expect(store().user?.avatar).toBe("https://example.com/bob.png");
   });
 });
+
+describe("authStore.getAccessToken — canonical MSAL.js fallback", () => {
+  // Reference: https://learn.microsoft.com/entra/msal/javascript/browser/errors
+  const config = {
+    clientId: "test-client",
+    authority: "https://login.microsoftonline.com/test-tenant",
+    redirectUri: "http://localhost:8010",
+    apiScope: "api://test-api/access_as_user",
+  };
+
+  function mockMsal(overrides: Record<string, unknown> = {}) {
+    const account = { username: "alice@example.com", localAccountId: "alice-oid" };
+    const mock = {
+      initialize: vi.fn().mockResolvedValue(undefined),
+      handleRedirectPromise: vi.fn().mockResolvedValue(null),
+      clearCache: vi.fn().mockResolvedValue(undefined),
+      getAllAccounts: vi.fn().mockReturnValue([account]),
+      loginRedirect: vi.fn().mockResolvedValue(undefined),
+      logoutRedirect: vi.fn().mockResolvedValue(undefined),
+      setActiveAccount: vi.fn(),
+      acquireTokenSilent: vi.fn().mockResolvedValue({ accessToken: "fresh-token" }),
+      acquireTokenRedirect: vi.fn().mockResolvedValue(undefined),
+      acquireTokenPopup: vi.fn().mockResolvedValue({ accessToken: "popup-token" }),
+      ...overrides,
+    };
+    vi.spyOn(authConfig, "getMsalInstance").mockReturnValue(mock);
+    vi.spyOn(authConfig, "getMsalConfig").mockReturnValue(config);
+    return mock;
+  }
+
+  async function expectInteractiveRecoveryError(
+    promise: Promise<unknown>,
+    expected: {
+      code?: string;
+      cause: unknown;
+      messageIncludes: string[];
+    },
+  ) {
+    let thrown: unknown;
+    try {
+      await promise;
+    } catch (err) {
+      thrown = err;
+    }
+
+    expect(thrown).toBeInstanceOf(AuthInteractionRequiredError);
+    const authError = thrown as AuthInteractionRequiredError;
+    expect(authError.code).toBe(expected.code);
+    expect(authError.cause).toBe(expected.cause);
+    for (const value of expected.messageIncludes) {
+      expect(authError.message).toContain(value);
+    }
+  }
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns null without navigating when MSAL isn't configured", async () => {
+    vi.spyOn(authConfig, "getMsalInstance").mockReturnValue(null);
+    vi.spyOn(authConfig, "getMsalConfig").mockReturnValue(null);
+    expect(await store().getAccessToken()).toBeNull();
+  });
+
+  it("returns the access token on a normal silent acquire", async () => {
+    const msal = mockMsal();
+    expect(await store().getAccessToken()).toBe("fresh-token");
+    expect(msal.acquireTokenSilent).toHaveBeenCalledOnce();
+    expect(msal.acquireTokenSilent).toHaveBeenCalledWith(
+      expect.objectContaining({ forceRefresh: false }),
+    );
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    expect(msal.loginRedirect).not.toHaveBeenCalled();
+  });
+
+  it("forwards forceRefresh to acquireTokenSilent on the 401-retry path", async () => {
+    // The fetch interceptor passes ``{ forceRefresh: true }`` after a
+    // protected API returns 401. MSAL must skip its local cache and round-
+    // trip the token endpoint so we stop sending the same stale-but-cached
+    // access token.
+    const msal = mockMsal();
+    expect(await store().getAccessToken("api", { forceRefresh: true })).toBe(
+      "fresh-token",
+    );
+    expect(msal.acquireTokenSilent).toHaveBeenCalledWith(
+      expect.objectContaining({ forceRefresh: true }),
+    );
+  });
+
+  it("returns null without redirecting when no account is cached", async () => {
+    // AuthGuard calls loginRedirect when accounts.length === 0; double-
+    // redirecting from getAccessToken would race with AuthGuard.
+    const msal = mockMsal({ getAllAccounts: vi.fn().mockReturnValue([]) });
+    expect(await store().getAccessToken()).toBeNull();
+    expect(msal.acquireTokenSilent).not.toHaveBeenCalled();
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    expect(msal.loginRedirect).not.toHaveBeenCalled();
+  });
+
+  it("clears stale cache and redirects on InteractionRequiredAuthError", async () => {
+    const err = Object.assign(new Error("MFA required"), {
+      name: "InteractionRequiredAuthError",
+      errorCode: "interaction_required",
+    });
+    const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "interaction_required",
+      cause: err,
+      messageIncludes: [
+        "Authentication interaction required",
+        "InteractionRequiredAuthError",
+        "interaction_required",
+        "MFA required",
+      ],
+    });
+    expect(msal.clearCache).toHaveBeenCalledWith({
+      account: { username: "alice@example.com", localAccountId: "alice-oid" },
+    });
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledWith({
+      scopes: [config.apiScope],
+    });
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+  });
+
+  it("clears stale cache and redirects on consent_required", async () => {
+    const err = Object.assign(new Error("consent required"), {
+      name: "InteractionRequiredAuthError",
+      errorCode: "consent_required",
+    });
+    const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "consent_required",
+      cause: err,
+      messageIncludes: ["Authentication interaction required", "consent_required"],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+
+  it("clears stale cache and redirects on monitor_window_timeout", async () => {
+    // Microsoft Learn → "Common errors in MSAL JS" → monitor_window_timeout
+    // → documented remedy includes "Invoke an interactive API".
+    const err = Object.assign(new Error("monitor_window_timeout"), {
+      name: "BrowserAuthError",
+      errorCode: "monitor_window_timeout",
+    });
+    const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "monitor_window_timeout",
+      cause: err,
+      messageIncludes: ["Authentication interaction required", "monitor_window_timeout"],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+
+  it("does NOT redirect on interaction_in_progress (would race with another flow)", async () => {
+    const err = Object.assign(new Error("interaction_in_progress"), {
+      name: "BrowserAuthError",
+      errorCode: "interaction_in_progress",
+    });
+    const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
+    expect(await store().getAccessToken()).toBeNull();
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+  });
+
+  it("does NOT redirect on hash_empty_error (config bug, redirect won't fix)", async () => {
+    const err = Object.assign(new Error("hash_empty_error"), {
+      name: "BrowserAuthError",
+      errorCode: "hash_empty_error",
+    });
+    const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
+    expect(await store().getAccessToken()).toBeNull();
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+  });
+
+  it("does NOT redirect on a transient/unknown error", async () => {
+    // A network blip shouldn't bounce the user through a login flow.
+    const err = new Error("connection reset");
+    const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
+    expect(await store().getAccessToken()).toBeNull();
+    expect(msal.acquireTokenRedirect).not.toHaveBeenCalled();
+    expect(msal.loginRedirect).not.toHaveBeenCalled();
+  });
+
+  it("matches InteractionRequiredAuthError by class name when no errorCode is set", async () => {
+    const err = Object.assign(new Error("interaction"), {
+      name: "InteractionRequiredAuthError",
+    });
+    const msal = mockMsal({ acquireTokenSilent: vi.fn().mockRejectedValue(err) });
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      cause: err,
+      messageIncludes: ["Authentication interaction required", "InteractionRequiredAuthError"],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+
+  it("preserves redirect failure details when interactive recovery cannot start", async () => {
+    const tokenErr = Object.assign(new Error("MFA required"), {
+      name: "InteractionRequiredAuthError",
+      errorCode: "interaction_required",
+    });
+    const redirectErr = Object.assign(new Error("redirect blocked"), {
+      name: "BrowserAuthError",
+      errorCode: "redirect_failed",
+    });
+    const msal = mockMsal({
+      acquireTokenSilent: vi.fn().mockRejectedValue(tokenErr),
+      loginRedirect: vi.fn().mockRejectedValue(redirectErr),
+    });
+
+    await expectInteractiveRecoveryError(store().getAccessToken(), {
+      code: "redirect_failed",
+      cause: redirectErr,
+      messageIncludes: [
+        "Authentication interaction required",
+        "login redirect failed",
+        "redirect_failed",
+        "Original token error",
+        "interaction_required",
+      ],
+    });
+    expect(msal.clearCache).toHaveBeenCalledOnce();
+    expect(msal.loginRedirect).toHaveBeenCalledOnce();
+  });
+});

package/src/__tests__/link-store.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, beforeEach, vi } from "vitest";
+import { linkStore, resolveLinkHandler, type LinkHandler } from "../store/link-store.ts";
+
+describe("linkStore", () => {
+  beforeEach(() => {
+    linkStore.getState().clear();
+  });
+
+  it("registers and clears a markdown link handler", () => {
+    const handler: LinkHandler = {
+      canHandle: (href) => href.startsWith("/spaces/"),
+      openLink: vi.fn(),
+    };
+
+    linkStore.getState().setHandler(handler);
+    expect(linkStore.getState().handler).toBe(handler);
+    expect(linkStore.getState().handlers).toEqual([handler]);
+
+    linkStore.getState().clear();
+    expect(linkStore.getState().handler).toBeNull();
+    expect(linkStore.getState().handlers).toEqual([]);
+  });
+
+  it("keeps multiple handlers and resolves the matching namespace", () => {
+    const spacesHandler: LinkHandler = {
+      canHandle: (href) => href.startsWith("/spaces/"),
+      openLink: vi.fn(),
+    };
+    const docsHandler: LinkHandler = {
+      normalizeHref: (href) => (href.startsWith("docs:") ? `/docs/${href.slice(5)}` : href),
+      canHandle: (href) => href.startsWith("/docs/"),
+      openLink: vi.fn(),
+    };
+
+    linkStore.getState().setHandler(spacesHandler);
+    linkStore.getState().setHandler(docsHandler);
+
+    expect(resolveLinkHandler("/spaces/page-1")).toEqual({
+      handler: spacesHandler,
+      href: "/spaces/page-1",
+    });
+    expect(resolveLinkHandler("docs:setup")).toEqual({
+      handler: docsHandler,
+      href: "/docs/setup",
+    });
+    expect(resolveLinkHandler("/unknown")).toBeNull();
+  });
+});

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

@@ -172,15 +172,133 @@ describe("createServiceFetch", () => {
     expect(merged.get("X-Init-Only")).toBe("init");
   });
 
-  it("recovers when acquireToken throws", async () => {
+  it("does not downgrade token failures to anonymous protected calls", async () => {
     const acquireToken = vi.fn().mockRejectedValue(new Error("token boom"));
     const serviceFetch = createServiceFetch({ acquireToken });
 
-    await serviceFetch("/api/spaces/entities");
+    await expect(serviceFetch("/api/spaces/entities")).rejects.toThrow("token boom");
 
-    expect(fetchSpy).toHaveBeenCalledTimes(1);
-    const [, init] = fetchSpy.mock.calls[0]!;
-    const headers = new Headers(init?.headers);
-    expect(headers.get("Authorization")).toBeNull();
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  describe("401 retry with forceRefresh", () => {
+    it("retries once with forceRefresh when first attempt returns 401", async () => {
+      // Resource server rejects the first (stale-cached) token, then accepts
+      // the freshly-acquired one. This is the long-lived-tab recovery path.
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale-token")
+        .mockResolvedValueOnce("fresh-token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities");
+
+      expect(res.status).toBe(200);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(acquireToken).toHaveBeenCalledTimes(2);
+      // First call: no forceRefresh (use cached token)
+      expect(acquireToken).toHaveBeenNthCalledWith(1, undefined);
+      // Second call: forceRefresh: true (skip MSAL cache, hit token endpoint)
+      expect(acquireToken).toHaveBeenNthCalledWith(2, { forceRefresh: true });
+
+      const firstAuth = new Headers(fetchSpy.mock.calls[0]![1]?.headers).get(
+        "Authorization",
+      );
+      const secondAuth = new Headers(fetchSpy.mock.calls[1]![1]?.headers).get(
+        "Authorization",
+      );
+      expect(firstAuth).toBe("Bearer stale-token");
+      expect(secondAuth).toBe("Bearer fresh-token");
+    });
+
+    it("does not retry on non-401 responses", async () => {
+      fetchSpy.mockReset();
+      fetchSpy.mockResolvedValueOnce(new Response(null, { status: 500 }));
+      const acquireToken = vi.fn().mockResolvedValue("token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities");
+
+      expect(res.status).toBe(500);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(acquireToken).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not retry when caller supplied their own Authorization header", async () => {
+      // The caller owns the token in this case; retrying would let our auth
+      // layer overwrite their explicit header on the second attempt.
+      fetchSpy.mockReset();
+      fetchSpy.mockResolvedValueOnce(new Response(null, { status: 401 }));
+      const acquireToken = vi.fn();
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities", {
+        headers: { Authorization: "Bearer caller-supplied" },
+      });
+
+      expect(res.status).toBe(401);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      expect(acquireToken).not.toHaveBeenCalled();
+    });
+
+    it("preserves a POST body across the 401 retry", async () => {
+      // Regression for the body-stream-consumed bug: ReadableStream bodies
+      // are single-consume, so the retry would otherwise see an empty body
+      // and a server-side validation failure that masks the real auth
+      // recovery. We assert the second attempt receives the same body.
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 200 }));
+      const acquireToken = vi
+        .fn()
+        .mockResolvedValueOnce("stale-token")
+        .mockResolvedValueOnce("fresh-token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const payload = JSON.stringify({ name: "create-this", id: 42 });
+      const request = new Request("https://example.com/api/items", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: payload,
+      });
+
+      const res = await serviceFetch(request);
+
+      expect(res.status).toBe(200);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+      // Each fetch call's body must be readable and equal to the original.
+      // Awaiting both confirms neither call's body stream was already
+      // drained by the time fetch received it.
+      const firstAttempt = fetchSpy.mock.calls[0]![1];
+      const secondAttempt = fetchSpy.mock.calls[1]![1];
+      const firstBody = await new Response(firstAttempt?.body as BodyInit).text();
+      const secondBody = await new Response(secondAttempt?.body as BodyInit).text();
+      expect(firstBody).toBe(payload);
+      expect(secondBody).toBe(payload);
+    });
+
+    it("only retries once even if the second attempt also returns 401", async () => {
+      // Hard auth failure (refresh token expired). The second 401 propagates
+      // to the caller; the auth layer's interaction-required path is what
+      // kicks the user to loginRedirect, not an infinite retry loop here.
+      fetchSpy.mockReset();
+      fetchSpy
+        .mockResolvedValueOnce(new Response(null, { status: 401 }))
+        .mockResolvedValueOnce(new Response(null, { status: 401 }));
+      const acquireToken = vi.fn().mockResolvedValue("token");
+      const serviceFetch = createServiceFetch({ acquireToken });
+
+      const res = await serviceFetch("/api/spaces/entities");
+
+      expect(res.status).toBe(401);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(acquireToken).toHaveBeenCalledTimes(2);
+    });
   });
 });