From eecec7495f2672f6244b46c1ab56aa039800bb68 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 01:32:51 -0400 Subject: [PATCH] docs: document memory remote helpers --- .../src/host/embedding-provider-adapter-utils.ts | 5 +++++ packages/memory-host-sdk/src/host/embeddings-debug.ts | 4 ++++ .../memory-host-sdk/src/host/embeddings-remote-client.ts | 6 ++++++ .../memory-host-sdk/src/host/embeddings-remote-fetch.ts | 7 +++++++ .../memory-host-sdk/src/host/embeddings-remote-provider.ts | 5 +++++ packages/memory-host-sdk/src/host/post-json.ts | 3 +++ packages/memory-host-sdk/src/host/remote-http.ts | 5 +++++ packages/memory-host-sdk/src/host/ssrf-policy.ts | 3 +++ 8 files changed, 38 insertions(+) diff --git a/packages/memory-host-sdk/src/host/embedding-provider-adapter-utils.ts b/packages/memory-host-sdk/src/host/embedding-provider-adapter-utils.ts index dc2e03e22b66..a624a05bb759 100644 --- a/packages/memory-host-sdk/src/host/embedding-provider-adapter-utils.ts +++ b/packages/memory-host-sdk/src/host/embedding-provider-adapter-utils.ts @@ -1,9 +1,13 @@ import { normalizeLowercaseStringOrEmpty } from "./string-utils.js"; +// Adapter helpers shared by remote embedding provider implementations. + +/** Detect missing API key errors from provider auth resolution. */ export function isMissingEmbeddingApiKeyError(err: unknown): boolean { return err instanceof Error && err.message.includes("No API key found for provider"); } +/** Return stable cache headers after removing provider-specific secret headers. */ export function sanitizeEmbeddingCacheHeaders( headers: Record, excludedHeaderNames: string[], @@ -17,6 +21,7 @@ export function sanitizeEmbeddingCacheHeaders( .map(([key, value]) => [key, value]); } +/** Convert custom-id keyed batch embeddings back to request-index order. */ export function mapBatchEmbeddingsByIndex( byCustomId: Map, count: number, diff --git a/packages/memory-host-sdk/src/host/embeddings-debug.ts b/packages/memory-host-sdk/src/host/embeddings-debug.ts index 2109aad70ae8..1be644b05884 100644 --- a/packages/memory-host-sdk/src/host/embeddings-debug.ts +++ b/packages/memory-host-sdk/src/host/embeddings-debug.ts @@ -1,7 +1,10 @@ import { normalizeLowercaseStringOrEmpty } from "./string-utils.js"; +// Lightweight stderr debug logging for memory embedding internals. + const debugEmbeddings = isTruthyEnvValue(process.env.OPENCLAW_DEBUG_MEMORY_EMBEDDINGS); +/** Write embedding debug metadata when OPENCLAW_DEBUG_MEMORY_EMBEDDINGS is enabled. */ export function debugEmbeddingsLog(message: string, meta?: Record): void { if (!debugEmbeddings) { return; @@ -10,6 +13,7 @@ export function debugEmbeddingsLog(message: string, meta?: Record { const version = typeof process !== "undefined" ? process.env.OPENCLAW_VERSION?.trim() : undefined; return { @@ -16,6 +20,7 @@ function resolveOpenClawAttributionHeaders(): Record { }; } +/** Detect the native OpenAI embeddings API route that accepts attribution headers. */ function isNativeOpenAIEmbeddingRoute(provider: string, baseUrl: string): boolean { if (provider !== "openai") { return false; @@ -27,6 +32,7 @@ function isNativeOpenAIEmbeddingRoute(provider: string, baseUrl: string): boolea } } +/** Resolve base URL, bearer headers, header overrides, and SSRF policy for remote embeddings. */ export async function resolveRemoteEmbeddingBearerClient(params: { provider: RemoteEmbeddingProviderId; options: EmbeddingProviderOptions; diff --git a/packages/memory-host-sdk/src/host/embeddings-remote-fetch.ts b/packages/memory-host-sdk/src/host/embeddings-remote-fetch.ts index 2b57f97e901e..57ce6d98467d 100644 --- a/packages/memory-host-sdk/src/host/embeddings-remote-fetch.ts +++ b/packages/memory-host-sdk/src/host/embeddings-remote-fetch.ts @@ -1,16 +1,21 @@ import { postJson } from "./post-json.js"; import type { SsrFPolicy } from "./ssrf-policy.js"; +// Fetches and validates OpenAI-compatible embedding responses. + +/** Narrow unknown JSON payloads to plain objects. */ function asRecord(value: unknown): Record | undefined { return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record) : undefined; } +/** Build the common malformed embedding response error. */ function malformedEmbeddingResponse(errorPrefix: string): Error { return new Error(`${errorPrefix}: malformed JSON response`); } +/** Validate and return one finite embedding vector. */ function readEmbeddingVector(value: unknown, errorPrefix: string): number[] { if (!Array.isArray(value)) { throw malformedEmbeddingResponse(errorPrefix); @@ -23,11 +28,13 @@ function readEmbeddingVector(value: unknown, errorPrefix: string): number[] { return value; } +/** Resolve expected response count from the request body when input is an array. */ function resolveExpectedEmbeddingCount(body: unknown): number | undefined { const input = asRecord(body)?.input; return Array.isArray(input) ? input.length : undefined; } +/** POST an embedding request and return validated vectors in provider response order. */ export async function fetchRemoteEmbeddingVectors(params: { url: string; headers: Record; diff --git a/packages/memory-host-sdk/src/host/embeddings-remote-provider.ts b/packages/memory-host-sdk/src/host/embeddings-remote-provider.ts index 3185ba252c73..08697d01960e 100644 --- a/packages/memory-host-sdk/src/host/embeddings-remote-provider.ts +++ b/packages/memory-host-sdk/src/host/embeddings-remote-provider.ts @@ -6,6 +6,9 @@ import { fetchRemoteEmbeddingVectors } from "./embeddings-remote-fetch.js"; import type { EmbeddingProvider, EmbeddingProviderOptions } from "./embeddings.types.js"; import type { SsrFPolicy } from "./ssrf-policy.js"; +// Remote embedding provider factory for OpenAI-compatible embeddings APIs. + +/** HTTP client details required by a remote embedding provider. */ export type RemoteEmbeddingClient = { baseUrl: string; headers: Record; @@ -14,6 +17,7 @@ export type RemoteEmbeddingClient = { model: string; }; +/** Create an EmbeddingProvider backed by a remote embeddings endpoint. */ export function createRemoteEmbeddingProvider(params: { id: string; client: RemoteEmbeddingClient; @@ -50,6 +54,7 @@ export function createRemoteEmbeddingProvider(params: { }; } +/** Resolve a normalized remote embedding client from provider config and model options. */ export async function resolveRemoteEmbeddingClient(params: { provider: RemoteEmbeddingProviderId; options: EmbeddingProviderOptions; diff --git a/packages/memory-host-sdk/src/host/post-json.ts b/packages/memory-host-sdk/src/host/post-json.ts index 1f0d34470e56..be0c9f2748f6 100644 --- a/packages/memory-host-sdk/src/host/post-json.ts +++ b/packages/memory-host-sdk/src/host/post-json.ts @@ -2,6 +2,9 @@ import { withRemoteHttpResponse } from "./remote-http.js"; import { readResponseJsonWithLimit, readResponseTextSnippet } from "./response-snippet.js"; import type { SsrFPolicy } from "./ssrf-policy.js"; +// Shared JSON POST helper for guarded remote memory provider calls. + +/** POST JSON, parse bounded response JSON, and attach status metadata when requested. */ export async function postJson(params: { url: string; headers: Record; diff --git a/packages/memory-host-sdk/src/host/remote-http.ts b/packages/memory-host-sdk/src/host/remote-http.ts index 702b77413b9e..44b9a0f6c666 100644 --- a/packages/memory-host-sdk/src/host/remote-http.ts +++ b/packages/memory-host-sdk/src/host/remote-http.ts @@ -5,11 +5,16 @@ import { } from "./openclaw-runtime-network.js"; import type { SsrFPolicy } from "./ssrf-policy.js"; +// Remote memory HTTP wrapper that applies SSRF policy and releases guarded sockets. + +/** Proxy mode used only for URLs that the runtime classified as env-proxy safe. */ export const MEMORY_REMOTE_TRUSTED_ENV_PROXY_MODE = "trusted_env_proxy"; +/** Build an SSRF allow policy from a configured remote base URL. */ export const buildRemoteBaseUrlPolicy: (baseUrl: string) => SsrFPolicy | undefined = ssrfPolicyFromHttpBaseUrlAllowedHostname; +/** Execute a remote HTTP request under SSRF guard and always release the response handle. */ export async function withRemoteHttpResponse(params: { url: string; init?: RequestInit; diff --git a/packages/memory-host-sdk/src/host/ssrf-policy.ts b/packages/memory-host-sdk/src/host/ssrf-policy.ts index aefa20ebb3bb..56de4c341d7f 100644 --- a/packages/memory-host-sdk/src/host/ssrf-policy.ts +++ b/packages/memory-host-sdk/src/host/ssrf-policy.ts @@ -1,3 +1,6 @@ +// Public SSRF policy shape accepted by memory host remote HTTP helpers. + +/** Host/network allowlist policy forwarded to the runtime SSRF guard. */ export type SsrFPolicy = { allowPrivateNetwork?: boolean; dangerouslyAllowPrivateNetwork?: boolean;