@full-self-developing/fsd 1.0.0

package/extensions/lmstudio/src/runtime.test.ts

@@ -0,0 +1,357 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/provider-auth";
+import { CUSTOM_LOCAL_AUTH_MARKER } from "openclaw/plugin-sdk/provider-auth";
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER } from "./defaults.js";
+import {
+  buildLmstudioAuthHeaders,
+  resolveLmstudioConfiguredApiKey,
+  resolveLmstudioProviderHeaders,
+  resolveLmstudioRuntimeApiKey,
+} from "./runtime.js";
+
+const resolveApiKeyForProviderMock = vi.hoisted(() => vi.fn());
+
+vi.mock("openclaw/plugin-sdk/provider-auth-runtime", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("openclaw/plugin-sdk/provider-auth-runtime")>();
+  return {
+    ...actual,
+    resolveApiKeyForProvider: (...args: unknown[]) => resolveApiKeyForProviderMock(...args),
+  };
+});
+
+afterAll(() => {
+  vi.doUnmock("openclaw/plugin-sdk/provider-auth-runtime");
+  vi.resetModules();
+});
+
+function buildLmstudioConfig(overrides?: {
+  apiKey?: unknown;
+  headers?: unknown;
+  auth?: "api-key";
+}): OpenClawConfig {
+  return {
+    models: {
+      providers: {
+        lmstudio: {
+          baseUrl: "http://localhost:1234/v1",
+          api: "openai-completions",
+          ...(overrides?.auth ? { auth: overrides.auth } : {}),
+          ...(overrides?.apiKey !== undefined ? { apiKey: overrides.apiKey } : {}),
+          ...(overrides?.headers !== undefined ? { headers: overrides.headers } : {}),
+          models: [],
+        },
+      },
+    },
+  } as OpenClawConfig;
+}
+
+describe("lmstudio-runtime", () => {
+  beforeEach(() => {
+    resolveApiKeyForProviderMock.mockReset();
+  });
+
+  it("throws when runtime auth resolves to blank and no configured key exists", async () => {
+    resolveApiKeyForProviderMock.mockResolvedValueOnce({
+      apiKey: "   ",
+      source: "profile:lmstudio:default",
+      mode: "api-key",
+    });
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({ auth: "api-key" }),
+      }),
+    ).rejects.toThrow(/LM Studio API key is required/i);
+  });
+
+  it("falls back to configured env marker key when profile resolution fails", async () => {
+    resolveApiKeyForProviderMock.mockRejectedValueOnce(
+      new Error('No API key found for provider "lmstudio". Auth store: /tmp/auth-profiles.json.'),
+    );
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({
+          auth: "api-key",
+          apiKey: "${LM_API_TOKEN}",
+        }),
+        env: {
+          LM_API_TOKEN: "template-lmstudio-key",
+        },
+      }),
+    ).resolves.toBe("template-lmstudio-key");
+  });
+
+  it("accepts synthesized lmstudio-local for non-explicit auth mode", async () => {
+    resolveApiKeyForProviderMock.mockResolvedValueOnce({
+      apiKey: LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER,
+      source: "models.providers.lmstudio (synthetic local key)",
+      mode: "api-key",
+    });
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig(),
+      }),
+    ).resolves.toBe(LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER);
+  });
+
+  it("accepts synthesized lmstudio-local for explicit api-key mode", async () => {
+    resolveApiKeyForProviderMock.mockResolvedValueOnce({
+      apiKey: LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER,
+      source: "models.providers.lmstudio (synthetic local key)",
+      mode: "api-key",
+    });
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({ auth: "api-key" }),
+      }),
+    ).resolves.toBe(LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER);
+  });
+
+  it("accepts shared synthetic local marker for keyless runtime auth", async () => {
+    resolveApiKeyForProviderMock.mockResolvedValueOnce({
+      apiKey: CUSTOM_LOCAL_AUTH_MARKER,
+      source: "models.providers.lmstudio (synthetic local key)",
+      mode: "api-key",
+    });
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig(),
+      }),
+    ).resolves.toBe(CUSTOM_LOCAL_AUTH_MARKER);
+  });
+
+  it("allows header-only runtime auth when Authorization is configured", async () => {
+    resolveApiKeyForProviderMock.mockRejectedValueOnce(
+      new Error('No API key found for provider "lmstudio". Auth store: /tmp/auth-profiles.json.'),
+    );
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({
+          headers: {
+            Authorization: "Bearer proxy-token",
+          },
+        }),
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("allows header-only runtime auth when an api key env template is unset", async () => {
+    resolveApiKeyForProviderMock.mockRejectedValueOnce(
+      new Error('No API key found for provider "lmstudio". Auth store: /tmp/auth-profiles.json.'),
+    );
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({
+          apiKey: "${LMSTUDIO_API_KEY}",
+          headers: {
+            Authorization: "Bearer proxy-token",
+          },
+        }),
+        env: {},
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("suppresses profile runtime auth when Authorization is configured", async () => {
+    resolveApiKeyForProviderMock.mockResolvedValueOnce({
+      apiKey: "stale-profile-key",
+      source: "profile:lmstudio:default",
+      mode: "api-key",
+    });
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({
+          headers: {
+            Authorization: "Bearer proxy-token",
+          },
+        }),
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("suppresses env runtime auth when Authorization is configured", async () => {
+    resolveApiKeyForProviderMock.mockResolvedValueOnce({
+      apiKey: "stale-env-key",
+      source: "env:LM_API_TOKEN",
+      mode: "api-key",
+    });
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({
+          headers: {
+            Authorization: "Bearer proxy-token",
+          },
+        }),
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("suppresses shell env runtime auth when Authorization is configured", async () => {
+    resolveApiKeyForProviderMock.mockResolvedValueOnce({
+      apiKey: "stale-shell-env-key",
+      source: "shell env: LM_API_TOKEN",
+      mode: "api-key",
+    });
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({
+          headers: {
+            Authorization: "Bearer proxy-token",
+          },
+        }),
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("throws when explicit api-key mode cannot resolve any key", async () => {
+    resolveApiKeyForProviderMock.mockRejectedValue(
+      new Error('No API key found for provider "lmstudio". Auth store: /tmp/auth-profiles.json.'),
+    );
+
+    await expect(
+      resolveLmstudioRuntimeApiKey({
+        config: buildLmstudioConfig({ auth: "api-key" }),
+      }),
+    ).rejects.toThrow(/LM Studio API key is required/i);
+
+    await expect(
+      resolveLmstudioConfiguredApiKey({
+        config: buildLmstudioConfig({ auth: "api-key" }),
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("resolves SecretRef api key and headers", async () => {
+    const headerRef = {
+      "X-Proxy-Auth": {
+        source: "env" as const,
+        provider: "default" as const,
+        id: "LMSTUDIO_PROXY_TOKEN",
+      },
+    };
+    await expect(
+      resolveLmstudioConfiguredApiKey({
+        config: buildLmstudioConfig({
+          apiKey: {
+            source: "env",
+            provider: "default",
+            id: "LM_API_TOKEN",
+          },
+        }),
+        env: {
+          LM_API_TOKEN: "secretref-lmstudio-key",
+        },
+      }),
+    ).resolves.toBe("secretref-lmstudio-key");
+
+    await expect(
+      resolveLmstudioProviderHeaders({
+        config: buildLmstudioConfig({ headers: headerRef }),
+        env: {
+          LMSTUDIO_PROXY_TOKEN: "proxy-token",
+        },
+        headers: headerRef,
+      }),
+    ).resolves.toEqual({
+      "X-Proxy-Auth": "proxy-token",
+    });
+  });
+
+  it("resolves env-template api keys from config", async () => {
+    await expect(
+      resolveLmstudioConfiguredApiKey({
+        config: buildLmstudioConfig({
+          apiKey: "${LM_API_TOKEN}",
+        }),
+        env: {
+          LM_API_TOKEN: "template-lmstudio-key",
+        },
+      }),
+    ).resolves.toBe("template-lmstudio-key");
+  });
+
+  it("resolves arbitrary env-template api keys from config", async () => {
+    await expect(
+      resolveLmstudioConfiguredApiKey({
+        config: buildLmstudioConfig({
+          apiKey: "${LMSTUDIO_API_KEY}",
+        }),
+        env: {
+          LMSTUDIO_API_KEY: "custom-template-lmstudio-key",
+        },
+      }),
+    ).resolves.toBe("custom-template-lmstudio-key");
+  });
+
+  it("throws a path-specific error when an env-template api key cannot be resolved", async () => {
+    await expect(
+      resolveLmstudioConfiguredApiKey({
+        config: buildLmstudioConfig({
+          apiKey: "${LMSTUDIO_API_KEY}",
+        }),
+        env: {},
+      }),
+    ).rejects.toThrow(/models\.providers\.lmstudio\.apiKey/i);
+  });
+
+  it("throws a path-specific error when a SecretRef header cannot be resolved", async () => {
+    const headerRef = {
+      "X-Proxy-Auth": {
+        source: "env" as const,
+        provider: "default" as const,
+        id: "LMSTUDIO_PROXY_TOKEN",
+      },
+    };
+    await expect(
+      resolveLmstudioProviderHeaders({
+        config: buildLmstudioConfig({ headers: headerRef }),
+        env: {},
+        headers: headerRef,
+      }),
+    ).rejects.toThrow(/models\.providers\.lmstudio\.headers\.X-Proxy-Auth/i);
+  });
+
+  it("builds auth headers with key precedence and json support", () => {
+    expect(buildLmstudioAuthHeaders({})).toBeUndefined();
+    expect(buildLmstudioAuthHeaders({ apiKey: "  sk-test  " })).toEqual({
+      Authorization: "Bearer sk-test",
+    });
+    expect(buildLmstudioAuthHeaders({ apiKey: "   " })).toBeUndefined();
+    expect(
+      buildLmstudioAuthHeaders({ apiKey: LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER }),
+    ).toBeUndefined();
+    expect(
+      buildLmstudioAuthHeaders({
+        apiKey: LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER,
+        headers: {
+          Authorization: "Bearer proxy-token",
+        },
+      }),
+    ).toEqual({
+      Authorization: "Bearer proxy-token",
+    });
+    expect(
+      buildLmstudioAuthHeaders({
+        apiKey: "sk-new",
+        json: true,
+        headers: {
+          authorization: "Bearer sk-old",
+          "X-Proxy": "proxy-token",
+        },
+      }),
+    ).toEqual({
+      "Content-Type": "application/json",
+      "X-Proxy": "proxy-token",
+      Authorization: "Bearer sk-new",
+    });
+  });
+});

package/extensions/lmstudio/src/runtime.ts

@@ -0,0 +1,276 @@
+import {
+  CUSTOM_LOCAL_AUTH_MARKER,
+  isKnownEnvApiKeyMarker,
+  isNonSecretApiKeyMarker,
+  normalizeApiKeyConfig,
+  normalizeOptionalSecretInput,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/provider-auth";
+import { resolveApiKeyForProvider } from "openclaw/plugin-sdk/provider-auth-runtime";
+import { resolveConfiguredSecretInputString } from "openclaw/plugin-sdk/secret-input-runtime";
+import {
+  LMSTUDIO_DEFAULT_API_KEY_ENV_VAR,
+  LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER,
+  LMSTUDIO_PROVIDER_ID,
+} from "./defaults.js";
+import { hasLmstudioAuthorizationHeader } from "./provider-auth.js";
+
+type LmstudioAuthHeadersParams = {
+  apiKey?: string;
+  json?: boolean;
+  headers?: Record<string, string>;
+};
+
+export function buildLmstudioAuthHeaders(
+  params: LmstudioAuthHeadersParams,
+): Record<string, string> | undefined {
+  const headers: Record<string, string> = { ...params.headers };
+  // Runtime auth resolution is strict, but guard known non-secret markers here.
+  const apiKey = params.apiKey?.trim();
+  const isSyntheticLocalKey = apiKey === LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER;
+  if (apiKey && !isSyntheticLocalKey && !isNonSecretApiKeyMarker(apiKey)) {
+    for (const headerName of Object.keys(headers)) {
+      if (headerName.toLowerCase() === "authorization") {
+        delete headers[headerName];
+      }
+    }
+    headers.Authorization = `Bearer ${apiKey}`;
+  }
+  if (params.json) {
+    headers["Content-Type"] = "application/json";
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+function sanitizeStringHeaders(headers: unknown): Record<string, string> | undefined {
+  if (!headers || typeof headers !== "object" || Array.isArray(headers)) {
+    return undefined;
+  }
+  const next: Record<string, string> = {};
+  for (const [headerName, headerValue] of Object.entries(headers)) {
+    if (typeof headerValue !== "string") {
+      continue;
+    }
+    const normalized = headerValue.trim();
+    if (!normalized) {
+      continue;
+    }
+    next[headerName] = normalized;
+  }
+  return Object.keys(next).length > 0 ? next : undefined;
+}
+
+function shouldSuppressResolvedRuntimeApiKeyForHeaderAuth(
+  source: string | undefined,
+  hasAuthorizationHeader: boolean,
+): boolean {
+  if (!hasAuthorizationHeader || !source) {
+    return false;
+  }
+  return /^profile:|^(?:shell )?env(?::|$)/.test(source);
+}
+
+export async function resolveLmstudioConfiguredApiKey(params: {
+  config?: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+  path?: string;
+  allowUnresolved?: boolean;
+}): Promise<string | undefined> {
+  const providerConfig = params.config?.models?.providers?.[LMSTUDIO_PROVIDER_ID];
+  const apiKeyInput = providerConfig?.apiKey;
+  if (apiKeyInput === undefined || apiKeyInput === null) {
+    return undefined;
+  }
+
+  const path = params.path ?? "models.providers.lmstudio.apiKey";
+  const env = params.env ?? process.env;
+  const directApiKey = normalizeOptionalSecretInput(apiKeyInput);
+  if (directApiKey !== undefined) {
+    const resolved = params.config
+      ? await resolveConfiguredSecretInputString({
+          config: params.config,
+          env,
+          value: directApiKey,
+          path,
+          unresolvedReasonStyle: "detailed",
+        })
+      : { value: directApiKey };
+    if (resolved.unresolvedRefReason) {
+      if (params.allowUnresolved) {
+        return undefined;
+      }
+      throw new Error(`${path}: ${resolved.unresolvedRefReason}`);
+    }
+    const resolvedValue = normalizeOptionalSecretInput(resolved.value);
+    const trimmed = resolvedValue ? normalizeApiKeyConfig(resolvedValue).trim() : "";
+    if (!trimmed) {
+      return undefined;
+    }
+    if (isKnownEnvApiKeyMarker(trimmed)) {
+      const envValue = normalizeOptionalSecretInput(env[trimmed]);
+      return envValue;
+    }
+    return isNonSecretApiKeyMarker(trimmed) ? undefined : trimmed;
+  }
+
+  if (!params.config) {
+    return undefined;
+  }
+  const resolved = await resolveConfiguredSecretInputString({
+    config: params.config,
+    env,
+    value: apiKeyInput,
+    path,
+    unresolvedReasonStyle: "detailed",
+  });
+  if (resolved.unresolvedRefReason) {
+    if (params.allowUnresolved) {
+      return undefined;
+    }
+    throw new Error(`${path}: ${resolved.unresolvedRefReason}`);
+  }
+  const resolvedValue = normalizeOptionalSecretInput(resolved.value);
+  const trimmedResolvedValue = resolvedValue ? normalizeApiKeyConfig(resolvedValue).trim() : "";
+  if (!trimmedResolvedValue) {
+    return undefined;
+  }
+  if (isNonSecretApiKeyMarker(trimmedResolvedValue)) {
+    return undefined;
+  }
+  return trimmedResolvedValue;
+}
+
+export async function resolveLmstudioProviderHeaders(params: {
+  config?: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+  headers?: unknown;
+  path?: string;
+}): Promise<Record<string, string> | undefined> {
+  const headerInputs = params.headers;
+  if (!headerInputs || typeof headerInputs !== "object" || Array.isArray(headerInputs)) {
+    return undefined;
+  }
+
+  if (!params.config) {
+    return sanitizeStringHeaders(headerInputs);
+  }
+
+  const pathPrefix = params.path ?? "models.providers.lmstudio.headers";
+  const resolved: Record<string, string> = {};
+  for (const [headerName, headerValue] of Object.entries(headerInputs)) {
+    const resolvedHeader = await resolveConfiguredSecretInputString({
+      config: params.config,
+      env: params.env ?? process.env,
+      value: headerValue,
+      path: `${pathPrefix}.${headerName}`,
+      unresolvedReasonStyle: "detailed",
+    });
+    if (resolvedHeader.unresolvedRefReason) {
+      throw new Error(`${pathPrefix}.${headerName}: ${resolvedHeader.unresolvedRefReason}`);
+    }
+    const resolvedValue = resolvedHeader.value;
+    if (!resolvedValue) {
+      continue;
+    }
+    resolved[headerName] = resolvedValue;
+  }
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+/**
+ * Resolves LM Studio API key and provider headers in parallel.
+ * Use this as the standard auth setup step before discovery or model load calls.
+ */
+export async function resolveLmstudioRequestContext(params: {
+  config?: OpenClawConfig;
+  agentDir?: string;
+  env?: NodeJS.ProcessEnv;
+  providerHeaders?: unknown;
+}): Promise<{ apiKey: string | undefined; headers: Record<string, string> | undefined }> {
+  const providerHeaders =
+    params.providerHeaders ?? params.config?.models?.providers?.[LMSTUDIO_PROVIDER_ID]?.headers;
+  const [apiKey, headers] = await Promise.all([
+    resolveLmstudioRuntimeApiKey({
+      config: params.config,
+      agentDir: params.agentDir,
+      env: params.env,
+      headers: providerHeaders,
+    }),
+    resolveLmstudioProviderHeaders({
+      config: params.config,
+      env: params.env,
+      headers: providerHeaders,
+    }),
+  ]);
+  return { apiKey, headers };
+}
+
+/**
+ * Resolves LM Studio runtime API key from config.
+ */
+export async function resolveLmstudioRuntimeApiKey(params: {
+  config?: OpenClawConfig;
+  agentDir?: string;
+  env?: NodeJS.ProcessEnv;
+  headers?: unknown;
+}): Promise<string | undefined> {
+  const config = params.config;
+  if (!config) {
+    return undefined;
+  }
+  const providerHeaders =
+    params.headers ?? config.models?.providers?.[LMSTUDIO_PROVIDER_ID]?.headers;
+  const hasAuthorizationHeader = hasLmstudioAuthorizationHeader(providerHeaders);
+  let configuredApiKeyPromise: Promise<string | undefined> | undefined;
+  const getConfiguredApiKey = async () => {
+    configuredApiKeyPromise ??= resolveLmstudioConfiguredApiKey({
+      config,
+      env: params.env,
+      allowUnresolved: hasAuthorizationHeader,
+    });
+    return await configuredApiKeyPromise;
+  };
+  const resolveConfiguredApiKeyOrThrow = async () => {
+    const configuredApiKey = await getConfiguredApiKey();
+    if (configuredApiKey) {
+      return configuredApiKey;
+    }
+    if (hasAuthorizationHeader) {
+      return undefined;
+    }
+    const envMarker = `\${${LMSTUDIO_DEFAULT_API_KEY_ENV_VAR}}`;
+    throw new Error(
+      [
+        "LM Studio API key is required.",
+        `Set models.providers.lmstudio.apiKey (for example "${envMarker}")`,
+        'or run "openclaw models auth lmstudio".',
+      ].join(" "),
+    );
+  };
+  let resolved: Awaited<ReturnType<typeof resolveApiKeyForProvider>>;
+  try {
+    resolved = await resolveApiKeyForProvider({
+      provider: LMSTUDIO_PROVIDER_ID,
+      cfg: config,
+      agentDir: params.agentDir,
+    });
+  } catch {
+    return await resolveConfiguredApiKeyOrThrow();
+  }
+  // Normalize empty/whitespace keys to undefined for callers.
+  const resolvedApiKey = resolved.apiKey?.trim();
+  if (!resolvedApiKey || resolvedApiKey.length === 0) {
+    return await resolveConfiguredApiKeyOrThrow();
+  }
+  if (shouldSuppressResolvedRuntimeApiKeyForHeaderAuth(resolved.source, hasAuthorizationHeader)) {
+    return await resolveConfiguredApiKeyOrThrow();
+  }
+  if (
+    isNonSecretApiKeyMarker(resolvedApiKey) &&
+    resolvedApiKey !== CUSTOM_LOCAL_AUTH_MARKER &&
+    resolvedApiKey !== LMSTUDIO_LOCAL_API_KEY_PLACEHOLDER
+  ) {
+    return await resolveConfiguredApiKeyOrThrow();
+  }
+  return resolvedApiKey;
+}