feat(sdk): add injectable fetch transport seam and route all provider requests through it

Author: chenanran555

packages/sdk/src/index.ts

@@ -3,6 +3,15 @@
 // ./internal and are deliberately not exported — do not add internal-only symbols here.
 
 export { UserError } from "./internal/errors.ts";
+// Server-side HTTP errors thrown by provider clients. Exported so hosts (CLIs,
+// servers) can branch on them and surface statusCode/responseBody structurally
+// instead of parsing the message string.
+export { ApiError, ConflictError } from "./internal/providers/base-client.ts";
+
+// Transport seam: hosts install a fetch-compatible implementation to add
+// cross-cutting request concerns (tracking headers, logging) without touching
+// globalThis.fetch. Unset → provider clients use the global fetch as before.
+export { setDefaultFetch, type FetchLike } from "./internal/transport.ts";
 
 export type {
 	BackendRuntimeInput,

packages/sdk/src/internal/executor/skill-resolver.ts

@@ -1,5 +1,6 @@
 import { readFileSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import { resolveFetch } from "../transport.ts";
 import type { SkillDecl } from "../types/config.ts";
 import type { SkillFile } from "../types/skill-file.ts";
 import { collectFiles } from "../utils/collect-files.ts";
@@ -10,7 +11,7 @@ import type { ExecContext } from "./context.ts";
 // is read relative to configPath (zip, directory, or a single SKILL.md).
 export async function resolveSkillFiles(decl: SkillDecl, ctx: ExecContext): Promise<SkillFile[]> {
 	if (/^https?:\/\//i.test(decl.source)) {
-		const res = await fetch(decl.source);
+		const res = await resolveFetch()(decl.source);
 		if (!res.ok) throw new Error(`skill source 下载失败：${res.status} ${decl.source}`);
 		return extractSkillZipFiles(Buffer.from(await res.arrayBuffer()));
 	}

packages/sdk/src/internal/providers/base-client.ts

@@ -1,3 +1,4 @@
+import { resolveFetch } from "../transport.ts";
 import type { RemoteResource } from "./interface.ts";
 
 export class ApiError extends Error {
@@ -34,7 +35,7 @@ export abstract class BaseApiClient {
 	}
 
 	async post(path: string, body: unknown): Promise<unknown> {
-		const res = await fetch(`${this.baseUrl}${path}`, {
+		const res = await resolveFetch()(`${this.baseUrl}${path}`, {
 			method: "POST",
 			headers: this.headers(),
 			body: JSON.stringify(body),
@@ -44,7 +45,7 @@ export abstract class BaseApiClient {
 	}
 
 	async put(path: string, body: unknown): Promise<unknown> {
-		const res = await fetch(`${this.baseUrl}${path}`, {
+		const res = await resolveFetch()(`${this.baseUrl}${path}`, {
 			method: "PUT",
 			headers: this.headers(),
 			body: JSON.stringify(body),
@@ -54,15 +55,15 @@ export abstract class BaseApiClient {
 	}
 
 	async delete(path: string): Promise<void> {
-		const res = await fetch(`${this.baseUrl}${path}`, {
+		const res = await resolveFetch()(`${this.baseUrl}${path}`, {
 			method: "DELETE",
 			headers: this.headers(),
 		});
 		await this.throwIfError(res);
 	}
 
 	async get(path: string): Promise<unknown> {
-		const res = await fetch(`${this.baseUrl}${path}`, {
+		const res = await resolveFetch()(`${this.baseUrl}${path}`, {
 			method: "GET",
 			headers: this.headers(),
 		});
@@ -71,7 +72,7 @@ export abstract class BaseApiClient {
 	}
 
 	async getBuffer(path: string): Promise<Buffer> {
-		const res = await fetch(`${this.baseUrl}${path}`, {
+		const res = await resolveFetch()(`${this.baseUrl}${path}`, {
 			method: "GET",
 			headers: this.headers(),
 		});
@@ -81,7 +82,7 @@ export abstract class BaseApiClient {
 
 	async *sse(path: string, options?: { headers?: Record<string, string> }): AsyncGenerator<Record<string, unknown>> {
 		const controller = new AbortController();
-		const res = await fetch(`${this.baseUrl}${path}`, {
+		const res = await resolveFetch()(`${this.baseUrl}${path}`, {
 			method: "GET",
 			headers: { ...this.headers(), Accept: "text/event-stream", ...options?.headers },
 			signal: controller.signal,
@@ -140,7 +141,7 @@ export abstract class BaseApiClient {
 		// boundary itself. Every provider's multipart headers are exactly its JSON
 		// headers minus Content-Type, so derive them here.
 		const { "Content-Type": _contentType, ...headers } = this.headers();
-		const res = await fetch(`${this.baseUrl}${path}`, {
+		const res = await resolveFetch()(`${this.baseUrl}${path}`, {
 			method: "POST",
 			headers,
 			body: formData,

packages/sdk/src/internal/transport.ts

@@ -0,0 +1,22 @@
+// Host-injectable transport seam. A host embedding the SDK (a CLI, a server)
+// can install a fetch-compatible implementation — e.g. to add tracking headers
+// or request logging — without monkey-patching globalThis.fetch. Response
+// semantics (ApiError classification, SSE parsing, pagination) stay in the
+// provider clients regardless of the installed implementation.
+
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+let defaultFetch: FetchLike | undefined;
+
+/** Install the fetch implementation used by all provider clients; pass undefined to reset. */
+export function setDefaultFetch(fetchImpl: FetchLike | undefined): void {
+	defaultFetch = fetchImpl;
+}
+
+/**
+ * Resolve the active fetch implementation. Falls back to the *current*
+ * globalThis.fetch (resolved per call, so test-time fetch mocks keep working).
+ */
+export function resolveFetch(): FetchLike {
+	return defaultFetch ?? ((input, init) => fetch(input, init));
+}

packages/sdk/tests/unit/transport.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, expect, test } from "bun:test";
+import { BaseApiClient } from "../../src/internal/providers/base-client.ts";
+import { type FetchLike, resolveFetch, setDefaultFetch } from "../../src/internal/transport.ts";
+
+class TestClient extends BaseApiClient {
+	protected baseUrl = "https://example.test";
+	protected errorPrefix = "test";
+	protected paginationStrategy = "page" as const;
+
+	protected headers(): Record<string, string> {
+		return { "Content-Type": "application/json", Authorization: "Bearer k" };
+	}
+}
+
+afterEach(() => {
+	setDefaultFetch(undefined);
+});
+
+test("resolveFetch falls back to the current globalThis.fetch when nothing is installed", async () => {
+	const originalFetch = globalThis.fetch;
+	globalThis.fetch = (async () =>
+		new Response(JSON.stringify({ id: "from-global" }), {
+			status: 200,
+		})) as unknown as typeof fetch;
+
+	try {
+		const res = await new TestClient().get("/x");
+		expect(res).toEqual({ id: "from-global" });
+	} finally {
+		globalThis.fetch = originalFetch;
+	}
+});
+
+test("setDefaultFetch routes provider client requests through the installed implementation", async () => {
+	const captured: Array<{
+		url: string;
+		method?: string;
+		headers: Record<string, string>;
+	}> = [];
+	const installed: FetchLike = async (input, init) => {
+		captured.push({
+			url: typeof input === "string" ? input : input instanceof URL ? input.href : input.url,
+			method: init?.method,
+			headers: (init?.headers ?? {}) as Record<string, string>,
+		});
+		return new Response(JSON.stringify({ id: "from-installed" }), {
+			status: 200,
+		});
+	};
+	setDefaultFetch(installed);
+
+	const res = await new TestClient().post("/agents", { name: "a" });
+	expect(res).toEqual({ id: "from-installed" });
+	expect(captured).toEqual([
+		{
+			url: "https://example.test/agents",
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: "Bearer k",
+			},
+		},
+	]);
+});
+
+test("installed implementation still gets ApiError semantics from the client (non-ok response)", async () => {
+	setDefaultFetch(async () => new Response("missing", { status: 404 }));
+
+	const err = (await new TestClient().get("/missing").catch((error: unknown) => error)) as Error & {
+		statusCode?: number;
+	};
+	expect(err.statusCode).toBe(404);
+});
+
+test("setDefaultFetch(undefined) resets back to the global fetch", async () => {
+	setDefaultFetch(async () => new Response("{}", { status: 200 }));
+	setDefaultFetch(undefined);
+
+	const originalFetch = globalThis.fetch;
+	let globalHit = false;
+	globalThis.fetch = (async () => {
+		globalHit = true;
+		return new Response("{}", { status: 200 });
+	}) as unknown as typeof fetch;
+
+	try {
+		await resolveFetch()("https://example.test/ping");
+		expect(globalHit).toBe(true);
+	} finally {
+		globalThis.fetch = originalFetch;
+	}
+});