#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
refactor(providers): extract OpenAI transport into shared module (#371) (#462)
Rohit Ghumare06248fd199fc
diff --git a/src/providers/_openai-shared.ts b/src/providers/_openai-shared.tsnew file mode 100644index 00000000..b35cca99--- /dev/null+++ b/src/providers/_openai-shared.ts@@ -0,0 +1,138 @@+// Shared transport helpers for the OpenAI-compatible LLM + embedding+// providers. Both surfaces (chat completions, embeddings) speak the+// same wire shape on the standard OpenAI path. Azure OpenAI ships+// two URL styles and we support both:+//+// - Legacy/stable: `/openai/deployments/<deployment>/chat/completions`+// with mandatory `api-version=<date>` query param. The deployment+// name lives in the URL path. Required api-version moves with+// every Azure date-stamped revision; we keep the+// `OPENAI_API_VERSION` env knob + `DEFAULT_AZURE_API_VERSION`+// fallback so existing configs don't break on upgrade.+//+// - v1 (GA Apr-2025): `/openai/v1/chat/completions`. No+// api-version query param, no `/deployments/` segment. Deployment+// name is passed in the request body as `model`. This matches+// the OpenAI wire shape one-for-one which is the whole point of+// v1 — drop-in compatibility.+//+// Auto-detection runs off the URL shape, not a flag: if the path+// already carries `/deployments/`, we route through the legacy+// builder; otherwise v1. Users opt into v1 by stripping the+// `/openai/deployments/<deployment>` suffix from their+// OPENAI_BASE_URL (or never adding it). See azureStyleOf().++export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";++// Default api-version for the legacy Azure URL pattern. Only used+// when the configured base URL carries `/deployments/` AND+// OPENAI_API_VERSION is unset. The v1 path ignores this entirely.+export const DEFAULT_AZURE_API_VERSION = "2024-08-01-preview";++type AzureStyle = "legacy" | "v1";++// Azure resource URLs land at <resource>.openai.azure.com.+export function detectAzure(baseUrl: string): boolean {+ try {+ const u = new URL(baseUrl);+ return u.hostname.endsWith(".openai.azure.com");+ } catch {+ return false;+ }+}++// Pick the Azure URL style off the base URL's path shape. We only+// consult this when detectAzure(baseUrl) has already returned true.+function azureStyleOf(baseUrl: string): AzureStyle {+ try {+ const u = new URL(baseUrl);+ // `/openai/deployments/<deployment>` (with or without a trailing+ // segment) signals the legacy URL pattern. Anything else — a+ // bare resource host, an `/openai/v1` prefix, an empty path —+ // routes through v1.+ if (/\/openai\/deployments\//.test(u.pathname)) return "legacy";+ return "v1";+ } catch {+ return "v1";+ }+}++// Legacy Azure: append the route to the existing deployment path,+// set api-version via searchParams. URL-API composition keeps any+// pre-existing query params on the base URL intact.+function legacyAzureUrl(+ baseUrl: string,+ path: string,+ apiVersion: string,+): string {+ const url = new URL(baseUrl);+ const existing = url.pathname.replace(/\/+$/, "");+ const route = path.startsWith("/") ? path : `/${path}`;+ url.pathname = `${existing}${route}`;+ url.searchParams.set("api-version", apiVersion);+ return url.toString();+}++// v1 Azure: route through `/openai/v1/<path>`. Preserve any existing+// query params on the base URL (corporate proxy, diagnostics tokens)+// but never append api-version — v1 doesn't accept it.+function v1AzureUrl(baseUrl: string, path: string): string {+ const url = new URL(baseUrl);+ const route = path.startsWith("/") ? path.slice(1) : path;+ // Strip any trailing `/openai`, `/openai/`, or `/openai/v1` so a+ // user who configures OPENAI_BASE_URL with a partial prefix still+ // gets a single, correct path.+ const base = url.pathname.replace(/\/?openai(?:\/v1)?\/?$/, "");+ url.pathname = `${base.replace(/\/+$/, "")}/openai/v1/${route}`;+ return url.toString();+}++export function buildChatUrl(+ baseUrl: string,+ isAzure: boolean,+ azureApiVersion: string,+): string {+ if (isAzure) {+ return azureStyleOf(baseUrl) === "legacy"+ ? legacyAzureUrl(baseUrl, "/chat/completions", azureApiVersion)+ : v1AzureUrl(baseUrl, "/chat/completions");+ }+ return `${baseUrl}/v1/chat/completions`;+}++export function buildEmbeddingUrl(+ baseUrl: string,+ isAzure: boolean,+ azureApiVersion: string,+): string {+ if (isAzure) {+ return azureStyleOf(baseUrl) === "legacy"+ ? legacyAzureUrl(baseUrl, "/embeddings", azureApiVersion)+ : v1AzureUrl(baseUrl, "/embeddings");+ }+ return `${baseUrl}/v1/embeddings`;+}++// Azure key-auth uses `api-key: <KEY>`; standard OpenAI-compatible+// endpoints use `Authorization: Bearer <KEY>`. Azure also accepts+// Bearer when AAD-auth is configured upstream, but the api-key path+// is the default and what our config block documents.+export function buildAuthHeaders(+ apiKey: string,+ isAzure: boolean,+): Record<string, string> {+ if (isAzure) {+ return {+ "Content-Type": "application/json",+ "api-key": apiKey,+ };+ }+ return {+ "Content-Type": "application/json",+ Authorization: `Bearer ${apiKey}`,+ };+}++export function normalizeBaseUrl(raw: string | undefined): string {+ return (raw || DEFAULT_OPENAI_BASE_URL).replace(/\/+$/, "");+}diff --git a/src/providers/embedding/openai.ts b/src/providers/embedding/openai.tsindex bbc0f9f5..ea5a0efa 100644--- a/src/providers/embedding/openai.ts+++ b/src/providers/embedding/openai.ts@@ -1,8 +1,14 @@import type { EmbeddingProvider } from "../../types.js";import { getEnvVar } from "../../config.js";import { fetchWithTimeout } from "../_fetch.js";+import {+ DEFAULT_AZURE_API_VERSION,+ buildAuthHeaders,+ buildEmbeddingUrl,+ detectAzure,+ normalizeBaseUrl,+} from "../_openai-shared.js";-const DEFAULT_BASE_URL = "https://api.openai.com";const DEFAULT_MODEL = "text-embedding-3-small";/**@@ -34,11 +40,20 @@ function resolveDimensions(model: string, override: string | undefined): number/*** OpenAI-compatible embedding provider.*+ * Shares transport (URL builder, auth header, Azure detection) with+ * the OpenAI LLM provider via `_openai-shared` (#371). Same env knobs+ * pick up automatically: when `OPENAI_BASE_URL` points at an Azure+ * resource (`.openai.azure.com` hostname) the embedding request uses+ * Azure's `/embeddings` path with the `api-version` query param and+ * `api-key` header instead of `Authorization: Bearer`.+ ** Required env vars:* OPENAI_API_KEY — API key** Optional:- * OPENAI_BASE_URL — base URL without path (default: https://api.openai.com)+ * OPENAI_BASE_URL — base URL without path (default: https://api.openai.com).+ * Azure: https://<resource>.openai.azure.com/openai/deployments/<deployment>+ * OPENAI_API_VERSION — Azure api-version query param (default: 2024-08-01-preview)* OPENAI_EMBEDDING_MODEL — model name (default: text-embedding-3-small)* OPENAI_EMBEDDING_DIMENSIONS — override reported dimensions (required for* custom / self-hosted models not in the@@ -50,18 +65,21 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {private apiKey: string;private baseUrl: string;private model: string;+ private isAzure: boolean;+ private azureApiVersion: string;constructor(apiKey?: string) {this.apiKey = apiKey || getEnvVar("OPENAI_API_KEY") || "";if (!this.apiKey) throw new Error("OPENAI_API_KEY is required");- this.baseUrl =- getEnvVar("OPENAI_BASE_URL") || DEFAULT_BASE_URL;- this.model =- getEnvVar("OPENAI_EMBEDDING_MODEL") || DEFAULT_MODEL;+ this.baseUrl = normalizeBaseUrl(getEnvVar("OPENAI_BASE_URL"));+ this.model = getEnvVar("OPENAI_EMBEDDING_MODEL") || DEFAULT_MODEL;this.dimensions = resolveDimensions(this.model,getEnvVar("OPENAI_EMBEDDING_DIMENSIONS"),);+ this.isAzure = detectAzure(this.baseUrl);+ this.azureApiVersion =+ getEnvVar("OPENAI_API_VERSION") || DEFAULT_AZURE_API_VERSION;}async embed(text: string): Promise<Float32Array> {@@ -70,13 +88,14 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {}async embedBatch(texts: string[]): Promise<Float32Array[]> {- const url = `${this.baseUrl}/v1/embeddings`;+ const url = buildEmbeddingUrl(+ this.baseUrl,+ this.isAzure,+ this.azureApiVersion,+ );const response = await fetchWithTimeout(url, {method: "POST",- headers: {- Authorization: `Bearer ${this.apiKey}`,- "Content-Type": "application/json",- },+ headers: buildAuthHeaders(this.apiKey, this.isAzure),body: JSON.stringify({model: this.model,input: texts,diff --git a/src/providers/openai.ts b/src/providers/openai.tsindex 2bb92781..bca2370f 100644--- a/src/providers/openai.ts+++ b/src/providers/openai.ts@@ -1,11 +1,16 @@import type { MemoryProvider } from "../types.js";import { getEnvVar } from "../config.js";import { fetchWithTimeout } from "./_fetch.js";+import {+ DEFAULT_AZURE_API_VERSION,+ buildAuthHeaders,+ buildChatUrl,+ detectAzure,+ normalizeBaseUrl,+} from "./_openai-shared.js";-const DEFAULT_BASE_URL = "https://api.openai.com";const DEFAULT_MODEL = "gpt-4o-mini";const DEFAULT_TIMEOUT_MS = 60_000;-const DEFAULT_AZURE_API_VERSION = "2024-08-01-preview";/*** OpenAI-compatible LLM provider.@@ -54,11 +59,7 @@ export class OpenAIProvider implements MemoryProvider {this.apiKey = apiKey;this.model = model;this.maxTokens = maxTokens;- this.baseUrl = (- baseURL ||- getEnvVar("OPENAI_BASE_URL") ||- DEFAULT_BASE_URL- ).replace(/\/+$/, "");+ this.baseUrl = normalizeBaseUrl(baseURL || getEnvVar("OPENAI_BASE_URL"));this.reasoningEffort = getEnvVar("OPENAI_REASONING_EFFORT") || undefined;this.timeoutMs = resolveTimeout();this.azureApiVersion =@@ -74,33 +75,8 @@ export class OpenAIProvider implements MemoryProvider {return this.call(systemPrompt, userPrompt);}- private buildUrl(): string {- // Azure OpenAI carries the deployment in the path and requires- // `api-version` as a query param. Standard OpenAI-compatible- // endpoints append /v1/chat/completions to the base.- if (this.isAzure) {- const sep = this.baseUrl.includes("?") ? "&" : "?";- return `${this.baseUrl}/chat/completions${sep}api-version=${encodeURIComponent(this.azureApiVersion)}`;- }- return `${this.baseUrl}/v1/chat/completions`;- }-- private buildHeaders(): Record<string, string> {- // Azure uses `api-key: <KEY>`; everyone else uses `Authorization: Bearer <KEY>`.- if (this.isAzure) {- return {- "Content-Type": "application/json",- "api-key": this.apiKey,- };- }- return {- "Content-Type": "application/json",- Authorization: `Bearer ${this.apiKey}`,- };- }-private async call(systemPrompt: string, userPrompt: string): Promise<string> {- const url = this.buildUrl();+ const url = buildChatUrl(this.baseUrl, this.isAzure, this.azureApiVersion);const body: Record<string, unknown> = {model: this.model,max_tokens: this.maxTokens,@@ -125,7 +101,7 @@ export class OpenAIProvider implements MemoryProvider {url,{method: "POST",- headers: this.buildHeaders(),+ headers: buildAuthHeaders(this.apiKey, this.isAzure),body: JSON.stringify(body),},this.timeoutMs,@@ -193,14 +169,3 @@ function parsePositiveInt(raw: string | null | undefined): number | undefined {return Number.isFinite(n) && n > 0 ? n : undefined;}-function detectAzure(baseUrl: string): boolean {- // Azure resource URLs land at <resource>.openai.azure.com. The- // `OPENAI_BASE_URL=https://<r>.openai.azure.com/openai/deployments/<d>`- // shape is the documented opt-in path.- try {- const u = new URL(baseUrl);- return u.hostname.endsWith(".openai.azure.com");- } catch {- return false;- }-}diff --git a/test/openai-shared.test.ts b/test/openai-shared.test.tsnew file mode 100644index 00000000..7240e10c--- /dev/null+++ b/test/openai-shared.test.ts@@ -0,0 +1,261 @@+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";+import {+ buildAuthHeaders,+ buildChatUrl,+ buildEmbeddingUrl,+ detectAzure,+ normalizeBaseUrl,+} from "../src/providers/_openai-shared.js";+import { OpenAIEmbeddingProvider } from "../src/providers/embedding/openai.js";++describe("_openai-shared — detectAzure", () => {+ it("detects standard Azure resource hostname", () => {+ expect(+ detectAzure(+ "https://myresource.openai.azure.com/openai/deployments/mydeploy",+ ),+ ).toBe(true);+ });++ it("does not flag api.openai.com", () => {+ expect(detectAzure("https://api.openai.com")).toBe(false);+ });++ it("does not flag DeepSeek / SiliconFlow / Ollama / vLLM", () => {+ expect(detectAzure("https://api.deepseek.com/v1")).toBe(false);+ expect(detectAzure("https://api.siliconflow.cn")).toBe(false);+ expect(detectAzure("http://localhost:11434/v1")).toBe(false);+ expect(detectAzure("http://localhost:8000/v1")).toBe(false);+ });++ it("returns false for malformed URLs", () => {+ expect(detectAzure("not-a-url")).toBe(false);+ expect(detectAzure("")).toBe(false);+ });+});++describe("_openai-shared — buildChatUrl", () => {+ it("appends /v1/chat/completions for standard OpenAI", () => {+ expect(buildChatUrl("https://api.openai.com", false, "2024-08-01-preview")).toBe(+ "https://api.openai.com/v1/chat/completions",+ );+ });++ it("appends /chat/completions + api-version for Azure", () => {+ const url = buildChatUrl(+ "https://myresource.openai.azure.com/openai/deployments/mydeploy",+ true,+ "2024-08-01-preview",+ );+ expect(url).toBe(+ "https://myresource.openai.azure.com/openai/deployments/mydeploy/chat/completions?api-version=2024-08-01-preview",+ );+ });++ it("URL-encodes the api-version", () => {+ const url = buildChatUrl(+ "https://r.openai.azure.com/openai/deployments/d",+ true,+ "preview/with/slashes",+ );+ expect(url).toContain("api-version=preview%2Fwith%2Fslashes");+ });++ it("preserves pre-existing query params on the base URL (CodeRabbit catch)", () => {+ // A corporate proxy or diagnostics endpoint might already carry+ // query parameters on the base URL. String-concat would have+ // interpolated the route path into the query string; URL-API+ // composition keeps the query intact and adds api-version+ // alongside.+ const url = buildChatUrl(+ "https://proxy.example.com/openai/deployments/d?tenant=acme",+ true,+ "2024-08-01-preview",+ );+ const parsed = new URL(url);+ expect(parsed.pathname).toBe("/openai/deployments/d/chat/completions");+ expect(parsed.searchParams.get("tenant")).toBe("acme");+ expect(parsed.searchParams.get("api-version")).toBe("2024-08-01-preview");+ });++ it("strips trailing slashes from base path before joining route", () => {+ const url = buildChatUrl(+ "https://r.openai.azure.com/openai/deployments/d/",+ true,+ "2024-08-01-preview",+ );+ expect(new URL(url).pathname).toBe("/openai/deployments/d/chat/completions");+ });++ it("routes through /openai/v1 when the base URL has no /deployments/ segment (Azure v1 GA)", () => {+ // Azure shipped a v1 URL pattern that mirrors the OpenAI shape:+ // /openai/v1/chat/completions, deployment passed in the body as+ // `model`. No api-version query param.+ const url = buildChatUrl(+ "https://r.openai.azure.com",+ true,+ "2024-08-01-preview", // ignored on v1+ );+ const parsed = new URL(url);+ expect(parsed.pathname).toBe("/openai/v1/chat/completions");+ expect(parsed.searchParams.get("api-version")).toBeNull();+ });++ it("strips a trailing /openai or /openai/v1 prefix when composing v1 URLs", () => {+ // Users may pre-configure OPENAI_BASE_URL with the /openai/v1+ // suffix already present. We should not double it.+ const fromOpenai = buildChatUrl(+ "https://r.openai.azure.com/openai",+ true,+ "ignored",+ );+ expect(new URL(fromOpenai).pathname).toBe("/openai/v1/chat/completions");++ const fromV1 = buildChatUrl(+ "https://r.openai.azure.com/openai/v1",+ true,+ "ignored",+ );+ expect(new URL(fromV1).pathname).toBe("/openai/v1/chat/completions");+ });+});++describe("_openai-shared — buildEmbeddingUrl", () => {+ it("appends /v1/embeddings for standard OpenAI", () => {+ expect(+ buildEmbeddingUrl("https://api.openai.com", false, "2024-08-01-preview"),+ ).toBe("https://api.openai.com/v1/embeddings");+ });++ it("appends /embeddings + api-version for Azure legacy (no /v1/ prefix)", () => {+ const url = buildEmbeddingUrl(+ "https://r.openai.azure.com/openai/deployments/embed-deploy",+ true,+ "2024-08-01-preview",+ );+ expect(url).toBe(+ "https://r.openai.azure.com/openai/deployments/embed-deploy/embeddings?api-version=2024-08-01-preview",+ );+ });++ it("routes through /openai/v1/embeddings on Azure v1 (no api-version)", () => {+ const url = buildEmbeddingUrl(+ "https://r.openai.azure.com",+ true,+ "2024-08-01-preview", // ignored on v1+ );+ const parsed = new URL(url);+ expect(parsed.pathname).toBe("/openai/v1/embeddings");+ expect(parsed.searchParams.get("api-version")).toBeNull();+ });+});++describe("_openai-shared — buildAuthHeaders", () => {+ it("emits Authorization: Bearer for standard OpenAI", () => {+ expect(buildAuthHeaders("sk-test", false)).toEqual({+ "Content-Type": "application/json",+ Authorization: "Bearer sk-test",+ });+ });++ it("emits api-key header for Azure", () => {+ expect(buildAuthHeaders("azure-key", true)).toEqual({+ "Content-Type": "application/json",+ "api-key": "azure-key",+ });+ });+});++describe("_openai-shared — normalizeBaseUrl", () => {+ it("returns default when no value passed", () => {+ expect(normalizeBaseUrl(undefined)).toBe("https://api.openai.com");+ expect(normalizeBaseUrl("")).toBe("https://api.openai.com");+ });++ it("strips trailing slashes", () => {+ expect(normalizeBaseUrl("https://api.deepseek.com/v1///")).toBe(+ "https://api.deepseek.com/v1",+ );+ });++ it("returns explicit values unchanged otherwise", () => {+ expect(normalizeBaseUrl("https://api.deepseek.com/v1")).toBe(+ "https://api.deepseek.com/v1",+ );+ });+});++// ─────────────────────────────────────────────────────────────+// OpenAIEmbeddingProvider — Azure transport (#371)+// Verifies the embedding path now uses the shared Azure helpers:+// hits /embeddings (not /v1/embeddings), includes api-version, uses+// api-key header instead of Authorization: Bearer.+// ─────────────────────────────────────────────────────────────+describe("OpenAIEmbeddingProvider — Azure auto-detection (#371)", () => {+ const ORIGINAL_BASE = process.env["OPENAI_BASE_URL"];+ const ORIGINAL_VERSION = process.env["OPENAI_API_VERSION"];++ beforeEach(() => {+ vi.restoreAllMocks();+ });++ afterEach(() => {+ if (ORIGINAL_BASE === undefined) delete process.env["OPENAI_BASE_URL"];+ else process.env["OPENAI_BASE_URL"] = ORIGINAL_BASE;+ if (ORIGINAL_VERSION === undefined) delete process.env["OPENAI_API_VERSION"];+ else process.env["OPENAI_API_VERSION"] = ORIGINAL_VERSION;+ vi.restoreAllMocks();+ });++ it("uses Azure shape when OPENAI_BASE_URL points at *.openai.azure.com", async () => {+ process.env["OPENAI_BASE_URL"] =+ "https://myres.openai.azure.com/openai/deployments/embed-d";+ process.env["OPENAI_API_VERSION"] = "2024-08-01-preview";++ let capturedUrl = "";+ let capturedHeaders = new Headers();+ vi.spyOn(globalThis, "fetch").mockImplementation(+ async (url: string | URL | Request, init?: RequestInit) => {+ capturedUrl = String(url);+ capturedHeaders = new Headers(init?.headers);+ return new Response(+ JSON.stringify({ data: [{ embedding: [0.1, 0.2, 0.3] }] }),+ { status: 200 },+ );+ },+ );++ const provider = new OpenAIEmbeddingProvider("azure-key");+ await provider.embedBatch(["hello"]);++ expect(capturedUrl).toBe(+ "https://myres.openai.azure.com/openai/deployments/embed-d/embeddings?api-version=2024-08-01-preview",+ );+ expect(capturedHeaders.get("api-key")).toBe("azure-key");+ expect(capturedHeaders.get("Authorization")).toBeNull();+ });++ it("uses standard shape when OPENAI_BASE_URL points at api.openai.com", async () => {+ process.env["OPENAI_BASE_URL"] = "https://api.openai.com";++ let capturedUrl = "";+ let capturedHeaders = new Headers();+ vi.spyOn(globalThis, "fetch").mockImplementation(+ async (url: string | URL | Request, init?: RequestInit) => {+ capturedUrl = String(url);+ capturedHeaders = new Headers(init?.headers);+ return new Response(+ JSON.stringify({ data: [{ embedding: [0.4, 0.5, 0.6] }] }),+ { status: 200 },+ );+ },+ );++ const provider = new OpenAIEmbeddingProvider("sk-test");+ await provider.embedBatch(["hello"]);++ expect(capturedUrl).toBe("https://api.openai.com/v1/embeddings");+ expect(capturedHeaders.get("Authorization")).toBe("Bearer sk-test");+ expect(capturedHeaders.get("api-key")).toBeNull();+ });+});