feat(sdk-core): implement ConfigurableAgent for multi-server routing

Add ConfigurableAgent class that extends Agent to support routing requests
to configurable service URLs, enabling proper PDS/SDS separation and
multi-SDS support.

Key features:
- ConfigurableAgent wraps session's fetch handler to route to custom URL
- Repository now uses ConfigurableAgent instead of standard Agent
- Supports multiple SDS instances with same OAuth session
- Maintains all authentication (DPoP, OAuth) from original session

Architecture:
- Agent's service URL is determined by FetchHandler, not modifiable properties
- ConfigurableAgent creates custom FetchHandler that prepends target URL
- Session's fetch handler provides authentication layer
- Enables: user@PDS accessing orgA@SDS and orgB@SDS simultaneously

Use cases:
- Route to SDS while authenticated via PDS
- Access multiple organization SDS instances
- Test against different server environments
- Switch between PDS and SDS operations dynamically

Resolves the issue where invalid agent.service and agent.api.xrpc.uri
property assignments were attempted. The proper solution is to wrap
the fetch handler at Agent construction time.

Related: #59, implements pattern from hypercerts-org/atproto sds-demo

Author: bitbeckers

packages/sdk-core/src/agent/ConfigurableAgent.ts

@@ -0,0 +1,84 @@
+/**
+ * ConfigurableAgent - Agent with configurable service URL routing.
+ *
+ * This module provides an Agent extension that allows routing requests to
+ * a specific server URL, overriding the default URL from the OAuth session.
+ *
+ * @packageDocumentation
+ */
+
+import { Agent } from "@atproto/api";
+import type { FetchHandler } from "@atproto/xrpc";
+import type { Session } from "../core/types.js";
+
+/**
+ * Agent subclass that routes requests to a configurable service URL.
+ *
+ * The standard Agent uses the service URL embedded in the OAuth session's
+ * fetch handler. This class allows overriding that URL to route requests
+ * to different servers (e.g., PDS vs SDS, or multiple SDS instances).
+ *
+ * @remarks
+ * This is particularly useful for:
+ * - Routing to a Shared Data Server (SDS) while authenticated via PDS
+ * - Supporting multiple SDS instances for different organizations
+ * - Testing against different server environments
+ *
+ * @example Basic usage
+ * ```typescript
+ * const session = await sdk.authorize("user.bsky.social");
+ *
+ * // Create agent routing to SDS instead of session's default PDS
+ * const sdsAgent = new ConfigurableAgent(session, "https://sds.hypercerts.org");
+ *
+ * // All requests will now go to the SDS
+ * await sdsAgent.com.atproto.repo.createRecord({...});
+ * ```
+ *
+ * @example Multiple SDS instances
+ * ```typescript
+ * // Route to organization A's SDS
+ * const orgAAgent = new ConfigurableAgent(session, "https://sds-org-a.example.com");
+ *
+ * // Route to organization B's SDS
+ * const orgBAgent = new ConfigurableAgent(session, "https://sds-org-b.example.com");
+ * ```
+ */
+export class ConfigurableAgent extends Agent {
+  private customServiceUrl: string;
+
+  /**
+   * Creates a ConfigurableAgent that routes to a specific service URL.
+   *
+   * @param session - OAuth session for authentication
+   * @param serviceUrl - Base URL of the server to route requests to
+   *
+   * @remarks
+   * The agent wraps the session's fetch handler to intercept requests and
+   * prepend the custom service URL instead of using the session's default.
+   */
+  constructor(session: Session, serviceUrl: string) {
+    // Create a custom fetch handler that uses our service URL
+    const customFetchHandler: FetchHandler = async (pathname: string, init: RequestInit) => {
+      // Construct the full URL with our custom service
+      const url = new URL(pathname, serviceUrl).toString();
+
+      // Use the session's fetch handler for authentication (DPoP, etc.)
+      return session.fetchHandler(url, init);
+    };
+
+    // Initialize the parent Agent with our custom fetch handler
+    super(customFetchHandler);
+
+    this.customServiceUrl = serviceUrl;
+  }
+
+  /**
+   * Gets the service URL this agent routes to.
+   *
+   * @returns The base URL of the configured service
+   */
+  getServiceUrl(): string {
+    return this.customServiceUrl;
+  }
+}

packages/sdk-core/src/index.ts

@@ -10,6 +10,9 @@ export type { AuthorizeOptions } from "./core/SDK.js";
 export type { ATProtoSDKConfig } from "./core/config.js";
 export type { Session } from "./core/types.js";
 
+// Agent
+export { ConfigurableAgent } from "./agent/ConfigurableAgent.js";
+
 // Repository (fluent API)
 export { Repository } from "./repository/Repository.js";
 export type {

packages/sdk-core/src/repository/Repository.ts

@@ -7,11 +7,12 @@
  * @packageDocumentation
  */
 
-import { Agent } from "@atproto/api";
 import { SDSRequiredError } from "../core/errors.js";
 import type { LoggerInterface } from "../core/interfaces.js";
 import type { Session } from "../core/types.js";
 import { HYPERCERT_LEXICONS } from "@hypercerts-org/lexicon";
+import { ConfigurableAgent } from "../agent/ConfigurableAgent.js";
+import type { Agent } from "@atproto/api";
 import type { LexiconRegistry } from "./LexiconRegistry.js";
 
 // Types
@@ -179,10 +180,10 @@ export class Repository {
     this._isSDS = isSDS;
     this.logger = logger;
 
-    // Create Agent with OAuth session
-    // Note: The Agent will use the session's fetch handler which contains
-    // the service URL configuration from the OAuth session
-    this.agent = new Agent(session);
+    // Create a ConfigurableAgent that routes requests to the specified server URL
+    // This allows routing to PDS, SDS, or any custom server while maintaining
+    // the OAuth session's authentication
+    this.agent = new ConfigurableAgent(session, serverUrl);
 
     this.lexiconRegistry.addToAgent(this.agent);
 

packages/sdk-core/tests/agent/ConfigurableAgent.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ConfigurableAgent } from "../../src/agent/ConfigurableAgent.js";
+import { createMockSession } from "../utils/repository-fixtures.js";
+
+describe("ConfigurableAgent", () => {
+  let mockSession: ReturnType<typeof createMockSession>;
+  let customServiceUrl: string;
+
+  beforeEach(() => {
+    mockSession = createMockSession();
+    customServiceUrl = "https://custom-sds.example.com";
+  });
+
+  describe("constructor", () => {
+    it("should create an agent with custom service URL", () => {
+      const agent = new ConfigurableAgent(mockSession, customServiceUrl);
+
+      expect(agent).toBeDefined();
+      expect(agent.getServiceUrl()).toBe(customServiceUrl);
+    });
+
+    it("should extend Agent class", () => {
+      const agent = new ConfigurableAgent(mockSession, customServiceUrl);
+
+      // Should have Agent properties and methods
+      expect(agent.com).toBeDefined();
+      expect(agent.app).toBeDefined();
+      expect(typeof agent.uploadBlob).toBe("function");
+    });
+  });
+
+  describe("fetch routing", () => {
+    it("should route requests to custom service URL", async () => {
+      const fetchSpy = vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({ uri: "at://test/record" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+
+      const sessionWithSpy = createMockSession({
+        fetchHandler: fetchSpy,
+      });
+
+      const agent = new ConfigurableAgent(sessionWithSpy, customServiceUrl);
+
+      // Attempt to make a call (will use the mocked fetch)
+      try {
+        await agent.com.atproto.repo.getRecord({
+          repo: "did:plc:test",
+          collection: "app.bsky.feed.post",
+          rkey: "test123",
+        });
+      } catch {
+        // Expected to fail due to mock, we just care about the fetch call
+      }
+
+      // Verify the fetch was called
+      expect(fetchSpy).toHaveBeenCalled();
+
+      // Check that the URL passed to fetch starts with our custom service URL
+      const callArgs = fetchSpy.mock.calls[0];
+      const calledUrl = callArgs[0] as string;
+
+      // The URL should be constructed with our custom service as base
+      expect(calledUrl).toContain(customServiceUrl);
+    });
+
+    it("should work with different service URLs", () => {
+      const pdsUrl = "https://pds.example.com";
+      const sdsUrl = "https://sds.example.com";
+      const customUrl = "https://custom.example.com";
+
+      const pdsAgent = new ConfigurableAgent(mockSession, pdsUrl);
+      const sdsAgent = new ConfigurableAgent(mockSession, sdsUrl);
+      const customAgent = new ConfigurableAgent(mockSession, customUrl);
+
+      expect(pdsAgent.getServiceUrl()).toBe(pdsUrl);
+      expect(sdsAgent.getServiceUrl()).toBe(sdsUrl);
+      expect(customAgent.getServiceUrl()).toBe(customUrl);
+    });
+  });
+
+  describe("authentication", () => {
+    it("should use session's fetch handler for authentication", async () => {
+      const authenticatedFetchSpy = vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({}), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+
+      const sessionWithAuth = createMockSession({
+        fetchHandler: authenticatedFetchSpy,
+      });
+
+      const agent = new ConfigurableAgent(sessionWithAuth, customServiceUrl);
+
+      try {
+        await agent.com.atproto.repo.createRecord({
+          repo: "did:plc:test",
+          collection: "app.bsky.feed.post",
+          record: { text: "test", createdAt: new Date().toISOString() },
+        });
+      } catch {
+        // Expected to fail, we're checking the fetch call
+      }
+
+      // Verify the session's fetch handler was used (includes auth)
+      expect(authenticatedFetchSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe("multiple instances", () => {
+    it("should allow multiple agents with different service URLs from same session", () => {
+      const orgA = new ConfigurableAgent(mockSession, "https://sds-org-a.example.com");
+      const orgB = new ConfigurableAgent(mockSession, "https://sds-org-b.example.com");
+      const pds = new ConfigurableAgent(mockSession, "https://pds.example.com");
+
+      expect(orgA.getServiceUrl()).toBe("https://sds-org-a.example.com");
+      expect(orgB.getServiceUrl()).toBe("https://sds-org-b.example.com");
+      expect(pds.getServiceUrl()).toBe("https://pds.example.com");
+
+      // Each agent should be independently configured
+      expect(orgA).not.toBe(orgB);
+      expect(orgB).not.toBe(pds);
+      expect(orgA).not.toBe(pds);
+    });
+  });
+
+  describe("integration with Repository pattern", () => {
+    it("should work as drop-in replacement for standard Agent", () => {
+      const agent = new ConfigurableAgent(mockSession, customServiceUrl);
+
+      // Should have all the standard Agent namespaces
+      expect(agent.com).toBeDefined();
+      expect(agent.com.atproto).toBeDefined();
+      expect(agent.com.atproto.repo).toBeDefined();
+      expect(agent.app).toBeDefined();
+
+      // Should have utility methods
+      expect(typeof agent.uploadBlob).toBe("function");
+      expect(typeof agent.resolveHandle).toBe("function");
+    });
+  });
+});