@bothat-io/molenkopf 0.1.2

package/packages/proxy/src/http/proxy-identity.ts

@@ -0,0 +1,78 @@
+import { authenticateKey, touchKey } from "../../../core/src/identity/api-keys.ts";
+import type { IdentityStore } from "../../../core/src/identity/identity-store.ts";
+import { agentIdFromHeaders, deriveClientIdentity, safeSubjectId, type ClientIdentity } from "./client-identity.ts";
+import { effectiveProviderAllowlist } from "./provider-access.ts";
+
+// Resolves a proxy request to a client identity. A Molenkopf-issued API key
+// maps to its owner user and teams for internal budgets while audit-facing
+// labels stay key based.
+
+export type ResolvedIdentity = { client: ClientIdentity; presentedKey: boolean; keyOk: boolean };
+
+export function presentedSecret(headers: Headers): string | undefined {
+  const local = headers.get("x-molenkopf-token")?.trim();
+  if (local?.startsWith("mk_")) return local;
+  const auth = headers.get("authorization");
+  if (auth) {
+    const token = auth.toLowerCase().startsWith("bearer ") ? auth.slice(7).trim() : auth.trim();
+    if (token.startsWith("mk_")) return token;
+  }
+  const xkey = headers.get("x-api-key")?.trim();
+  if (xkey?.startsWith("mk_")) return xkey;
+  return undefined;
+}
+
+export function stripMolenkopfAuthHeaders(headers: Headers): void {
+  headers.delete("x-molenkopf-token");
+  if (presentedAuthHeader(headers.get("authorization"))) headers.delete("authorization");
+  if (headers.get("x-api-key")?.trim().startsWith("mk_")) headers.delete("x-api-key");
+}
+
+function presentedAuthHeader(value: string | null): boolean {
+  if (!value) return false;
+  const token = value.toLowerCase().startsWith("bearer ") ? value.slice(7).trim() : value.trim();
+  return token.startsWith("mk_");
+}
+
+export function resolveClientIdentity(identity: IdentityStore | undefined, headers: Headers): ResolvedIdentity {
+  const secret = presentedSecret(headers);
+  if (identity && secret) {
+    const key = authenticateKey(identity, secret);
+    if (key) {
+      const owner = identity.getUser(key.ownerUserId);
+      const teamIds = owner ? scopedTeamIds(owner.teamIds, key.teamId) : [];
+      const agentId = agentIdFromHeaders(headers);
+      const client: ClientIdentity = {
+        id: `user:${safeSubjectId(key.ownerUserId)}`,
+        label: key.agentLabel ? `key:${key.id} agent:${safeSubjectId(key.agentLabel)}` : `key:${key.id}`,
+        source: "api_key",
+        userId: key.ownerUserId,
+        agentId,
+        keyAgentLabel: key.agentLabel,
+        teamIds,
+        keyId: key.id,
+        project: key.project,
+        allowedProviderIds: effectiveProviderAllowlist(identity, owner, teamIds, key.scopes)
+      };
+      maybeTouch(identity, key);
+      return { client, presentedKey: true, keyOk: true };
+    }
+    return { client: deriveClientIdentity(headers), presentedKey: true, keyOk: false };
+  }
+  return { client: deriveClientIdentity(headers), presentedKey: Boolean(secret), keyOk: false };
+}
+
+function maybeTouch(store: IdentityStore, key: { lastUsedAt?: string }): void {
+  const last = key.lastUsedAt ? Date.parse(key.lastUsedAt) : 0;
+  if (Date.now() - last > 60_000) {
+    touchKey(store, key as any);
+    void store.save().catch(() => { /* last-used persistence must not crash auth */ });
+  }
+}
+
+function scopedTeamIds(ownerTeamIds: string[], keyTeamId: string | undefined): string[] {
+  const explicitTeams = ownerTeamIds.filter((id) => id !== "everyone");
+  if (!keyTeamId) return explicitTeams.length ? explicitTeams : ownerTeamIds;
+  if (keyTeamId === "everyone" && explicitTeams.length) return explicitTeams;
+  return ownerTeamIds.includes(keyTeamId) ? [keyTeamId] : [];
+}

package/packages/proxy/src/http/public-bind.ts

@@ -0,0 +1,8 @@
+export function isLoopbackBindHost(host: string): boolean {
+  const value = host.toLowerCase();
+  return value === "localhost" || value === "::1" || value === "[::1]" || /^127(?:\.|$)/.test(value);
+}
+
+export function requirePublicBindFlag(host: string, allowPublicBind?: boolean): void {
+  if (!isLoopbackBindHost(host) && !allowPublicBind) throw new Error("public bind requires --allow-public-bind");
+}

package/packages/proxy/src/http/request-finish.ts

@@ -0,0 +1,62 @@
+import type { AuditManifest, AuditStore } from "../../../core/src/manifest/audit-store.ts";
+import type { EventBus } from "../../../core/src/events/event-bus.ts";
+import type { RewriteAudit } from "../../../core/src/pipeline/openai-request-rewriter.ts";
+import type { UsageTotals } from "../../../core/src/manifest/usage-meter.ts";
+import { isPluginEnabled, recordUsage, type RuntimeState } from "./runtime-state.ts";
+import { recordCommunicationGraph } from "./communication-graph.ts";
+import { safeSubjectId, type ClientIdentity } from "./client-identity.ts";
+import type { PluginHost } from "./plugin-host.ts";
+
+export async function finishRequest(manifest: AuditManifest, auditStore: AuditStore, events: EventBus, state: RuntimeState, pluginHost?: PluginHost): Promise<void> {
+  const stored = auditSafeManifest(manifest);
+  await auditStore.write(stored);
+  state.requests++;
+  state.compressedItems += manifest.compressedItems;
+  recordUsage(state, manifest);
+  state.latest = stored;
+  if (isPluginEnabled(state, "obsidian-graph-plugin")) recordCommunicationGraph(state.communicationGraph, stored);
+  await pluginHost?.audit(stored);
+  events.emit("request_finished", { requestId: manifest.requestId, data: { statusCode: manifest.statusCode, durationMs: manifest.durationMs } });
+}
+
+export function buildManifest(requestId: string, method: string, path: string, target: string, providerId: string, statusCode: number, durationMs: number, client: ClientIdentity, audit?: RewriteAudit, usage?: UsageTotals): AuditManifest {
+  return {
+    requestId, timestamp: new Date().toISOString(), method, path, targetHost: new URL(target).host, providerId,
+    client,
+    compressedItems: audit?.compressedItems ?? 0,
+    estimatedOriginalTokens: audit?.estimatedOriginalTokens ?? 0,
+    estimatedCompressedTokens: audit?.estimatedCompressedTokens ?? 0,
+    estimatedSavedTokens: audit?.estimatedSavedTokens ?? 0,
+    redactedSecrets: audit?.redactedSecrets ?? 0,
+    retrievalIds: audit?.retrievalIds ?? [],
+    compressorsUsed: [...new Set(audit?.compressorsUsed ?? [])],
+    warnings: audit?.warnings ?? [], statusCode, durationMs,
+    upstreamInputTokens: usage?.inputTokens,
+    upstreamOutputTokens: usage?.outputTokens
+  };
+}
+
+function auditSafeManifest(manifest: AuditManifest): AuditManifest {
+  return { ...manifest, client: manifest.client ? auditSafeClient(manifest.client) : undefined };
+}
+
+function auditSafeClient(client: NonNullable<AuditManifest["client"]>): AuditManifest["client"] {
+  return {
+    ...client,
+    id: safeClientId(client.id),
+    label: safeClientLabel(client),
+    userId: client.userId ? safeSubjectId(client.userId) : undefined,
+    agentId: client.agentId ? safeSubjectId(client.agentId) : undefined
+  };
+}
+
+function safeClientId(id: string): string {
+  const [prefix, ...rest] = id.split(":");
+  const value = rest.join(":");
+  return value ? `${prefix}:${safeSubjectId(value)}` : safeSubjectId(id);
+}
+
+function safeClientLabel(client: NonNullable<AuditManifest["client"]>): string {
+  if (client.source === "api_key" && client.keyId) return `key:${client.keyId}`;
+  return client.label.includes(":") ? safeClientId(client.label) : safeSubjectId(client.label);
+}

package/packages/proxy/src/http/request-path.ts

@@ -0,0 +1,8 @@
+export function auditPath(value: string | undefined): string {
+  try {
+    const url = new URL(value || "/", "http://molenkopf.local");
+    return url.pathname || "/";
+  } catch {
+    return "/";
+  }
+}

package/packages/proxy/src/http/request-policy.ts

@@ -0,0 +1,46 @@
+import { agentIdFromHeaders, type ClientIdentity } from "./client-identity.ts";
+import type { RuntimeState } from "./runtime-state.ts";
+
+export type EffectiveRequestPolicy = {
+  agentId?: string;
+  allowedModels?: string[];
+  defaultModel?: string;
+  enabledPluginIds?: string[];
+};
+
+export type ModelPolicyResult = { ok: true } | { ok: false; status: number; error: string };
+
+export function effectiveRequestPolicy(state: RuntimeState, headers: Headers, client: ClientIdentity): EffectiveRequestPolicy {
+  const agentId = agentIdFromHeaders(headers);
+  if (!agentId || client.source !== "api_key" || client.keyAgentLabel !== agentId) return {};
+  const configAgent = state.configAgents.find((item) => item.id === agentId);
+  const draft = state.agentDrafts.find((item) => item.id === agentId);
+  return {
+    agentId,
+    allowedModels: configAgent?.allowedModels,
+    defaultModel: configAgent?.defaultModel,
+    enabledPluginIds: configAgent?.enabledPluginIds ?? draft?.enabledPluginIds
+  };
+}
+
+export function pluginAllowedByPolicy(policy: EffectiveRequestPolicy, pluginId: string): boolean {
+  return policy.enabledPluginIds === undefined || policy.enabledPluginIds.includes(pluginId);
+}
+
+export function enforceModelPolicy(policy: EffectiveRequestPolicy, body: string): ModelPolicyResult {
+  if (!policy.allowedModels?.length) return { ok: true };
+  const model = modelFromBody(body);
+  if (model === false) return { ok: false, status: 400, error: "invalid_json" };
+  if (model === undefined) return { ok: true };
+  if (!policy.allowedModels.includes(model)) return { ok: false, status: 403, error: "model_forbidden" };
+  return { ok: true };
+}
+
+function modelFromBody(body: string): string | undefined | false {
+  try {
+    const parsed = JSON.parse(body) as { model?: unknown };
+    return typeof parsed.model === "string" && parsed.model.trim() ? parsed.model.trim() : undefined;
+  } catch {
+    return false;
+  }
+}

package/packages/proxy/src/http/runtime-auth-proof.ts

@@ -0,0 +1,55 @@
+import { createHash, randomBytes } from "node:crypto";
+import type { RuntimeState } from "./runtime-state.ts";
+
+type Proof = { digest: string; expiresAt: number };
+
+const PROOF_TTL_MS = 5 * 60 * 1000;
+const PROOF_FIELDS = ["id", "name", "runtime", "authJson", "profileText", "settingsJson", "configToml", "profile", "activate"] as const;
+
+export function issueRuntimeAuthProof(state: RuntimeState, body: Record<string, unknown>, now = Date.now()): string {
+  clearExpiredProofs(state, now);
+  const token = randomBytes(24).toString("base64url");
+  state.runtimeAuthProofs[token] = { digest: runtimeAuthDigest(body), expiresAt: now + PROOF_TTL_MS };
+  return token;
+}
+
+export function consumeRuntimeAuthProof(state: RuntimeState, body: Record<string, unknown>, now = Date.now()): boolean {
+  const token = typeof body.importProof === "string" ? body.importProof : "";
+  const proof = token ? state.runtimeAuthProofs[token] : undefined;
+  if (token) delete state.runtimeAuthProofs[token];
+  clearExpiredProofs(state, now);
+  return Boolean(proof && proof.expiresAt > now && proof.digest === runtimeAuthDigest(body));
+}
+
+export function runtimeAuthDigest(body: Record<string, unknown>): string {
+  const payload: Record<string, unknown> = {};
+  for (const field of PROOF_FIELDS) if (body[field] !== undefined) payload[field] = normalize(body[field]);
+  return createHash("sha256").update(stableJson(payload)).digest("hex");
+}
+
+function clearExpiredProofs(state: RuntimeState, now: number): void {
+  for (const [token, proof] of Object.entries(state.runtimeAuthProofs)) {
+    if (proof.expiresAt <= now) delete state.runtimeAuthProofs[token];
+  }
+}
+
+function normalize(value: unknown): unknown {
+  if (typeof value === "string") return value.trim();
+  if (Array.isArray(value)) return value.map(normalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, normalize(item)]));
+  }
+  return value;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export type RuntimeAuthProofStore = Record<string, Proof>;

package/packages/proxy/src/http/runtime-auth-registry.ts

@@ -0,0 +1,105 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import { defaultDataDir } from "../../../core/src/storage/local-paths.ts";
+import { ensurePrivateDir, writePrivateFile } from "../../../core/src/storage/private-state.ts";
+import type { RoutingMode } from "./runtime-state.ts";
+import { runtimeCliArgs } from "../runtime/runtime-profile.ts";
+
+type RuntimeAuthMeta = Pick<ProviderConfig, "id" | "name" | "runtime" | "runtimeProfile" | "allowDistribution"> & { authRef: string };
+type RuntimeAuthState = { activeProviderId?: string; routingMode?: RoutingMode };
+
+const ID_RE = /^[a-z0-9][a-z0-9._:-]{0,63}$/i;
+const META_FILE = "provider.json";
+const STATE_FILE = "state.json";
+
+export function restoreRuntimeAuthProviders(dataDir: string | undefined): { providers: ProviderConfig[]; activeProviderId?: string; routingMode?: RoutingMode } {
+  const root = runtimeAuthRoot(dataDir);
+  if (!root || !existsSync(root)) return { providers: [] };
+  const providers = readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => providerFromDir(root, entry.name))
+    .filter((provider): provider is ProviderConfig => Boolean(provider));
+  const persisted = readJson<RuntimeAuthState>(join(root, STATE_FILE));
+  const activeProviderId = providers.some((item) => item.id === persisted?.activeProviderId) ? persisted?.activeProviderId : undefined;
+  return { providers, activeProviderId, routingMode: persisted?.routingMode };
+}
+
+export async function writeRuntimeAuthFiles(authDir: string, runtime: "claude" | "codex", content: string): Promise<void> {
+  await ensurePrivateDir(authDir);
+  await writePrivateFile(join(authDir, "auth.json"), content);
+  if (runtime === "claude") await writePrivateFile(join(authDir, ".credentials.json"), content);
+}
+
+export async function persistRuntimeAuthProvider(dataDir: string | undefined, provider: ProviderConfig, active: boolean, routingMode: RoutingMode): Promise<void> {
+  if (!provider.runtimeAuthDir || !provider.runtime) return;
+  await ensurePrivateDir(provider.runtimeAuthDir);
+  const meta: RuntimeAuthMeta = {
+    id: provider.id,
+    name: provider.name,
+    runtime: provider.runtime,
+    authRef: provider.authRef ?? `runtime-auth:${provider.id}`,
+    runtimeProfile: provider.runtimeProfile,
+    allowDistribution: provider.allowDistribution
+  };
+  await writePrivateFile(join(provider.runtimeAuthDir, META_FILE), `${JSON.stringify(meta, null, 2)}\n`);
+  if (active) await persistRuntimeAuthSelection(dataDir, provider.id, routingMode);
+}
+
+export async function persistRuntimeAuthSelection(dataDir: string | undefined, activeProviderId: string, routingMode: RoutingMode): Promise<void> {
+  const root = runtimeAuthRoot(dataDir);
+  if (!root) return;
+  await ensurePrivateDir(root);
+  await writePrivateFile(join(root, STATE_FILE), `${JSON.stringify({ activeProviderId, routingMode }, null, 2)}\n`);
+}
+
+export async function removeRuntimeAuthProvider(provider: ProviderConfig): Promise<void> {
+  if (!provider.runtimeAuthDir) return;
+  await rm(provider.runtimeAuthDir, { recursive: true, force: true });
+}
+
+export function runtimeAuthProvider(id: string, name: string, runtime: "claude" | "codex", authDir: string, authRef: string, profile?: ProviderConfig["runtimeProfile"]): ProviderConfig {
+  return {
+    id,
+    name,
+    kind: "cli",
+    target: `cli://${id}`,
+    runtime,
+    cliCommand: runtime,
+    cliArgs: runtimeCliArgs(runtime, authDir, profile),
+    cliInputMode: "stdin",
+    cliTimeoutMs: 120000,
+    authScheme: "none",
+    credentialRef: "none",
+    runtimeAuthDir: authDir,
+    authRef,
+    runtimeProfile: profile,
+    allowDistribution: true,
+    enabled: true
+  };
+}
+
+function providerFromDir(root: string, id: string): ProviderConfig | undefined {
+  if (!ID_RE.test(id)) return undefined;
+  const authDir = join(root, id);
+  const meta = readJson<RuntimeAuthMeta>(join(authDir, META_FILE));
+  if (meta && meta.id === id && (meta.runtime === "claude" || meta.runtime === "codex") && typeof meta.authRef === "string" && meta.authRef.trim()) {
+    const provider = runtimeAuthProvider(id, meta.name || id, meta.runtime, authDir, meta.authRef.trim(), meta.runtimeProfile);
+    if (typeof meta.allowDistribution === "boolean") provider.allowDistribution = meta.allowDistribution;
+    return provider;
+  }
+  return undefined;
+}
+
+function runtimeAuthRoot(dataDir: string | undefined): string | undefined {
+  return join(dataDir ?? defaultDataDir(), "runtime-auth");
+}
+
+function readJson<T>(path: string): T | undefined {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return undefined;
+  }
+}

package/packages/proxy/src/http/runtime-settings.ts

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync, renameSync } from "node:fs";
+import { rename } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import { validateProviderTarget } from "../../../core/src/security/target-policy.ts";
+import { defaultDataDir } from "../../../core/src/storage/local-paths.ts";
+import { ensurePrivateDir, writePrivateFile } from "../../../core/src/storage/private-state.ts";
+import { CONTROL_PLANE_LIMITS, type AgentDraftMetadata, type RoutingMode, type RuntimeState } from "./runtime-state.ts";
+
+export type RuntimeSettings = {
+  activeProviderId?: string;
+  routingMode?: RoutingMode;
+  pluginEnabled?: Record<string, boolean>;
+  pluginOrder?: string[];
+  providerWeights?: Record<string, number>;
+  providers?: PersistedProvider[];
+  consumerBudgets?: Record<string, number>;
+  agentDrafts?: AgentDraftMetadata[];
+};
+export type RuntimeSettingsLoad = { settings: RuntimeSettings; warning?: string };
+type PersistedProvider = Pick<ProviderConfig, "id" | "name" | "kind" | "target" | "credentialEnv" | "credentialRef" | "authScheme" | "protocol" | "enabled" | "allowDistribution" | "runtime" | "cliCommand" | "cliArgs" | "cliInputMode" | "cliTimeoutMs">;
+const BUILT_IN_IDS = new Set(["default", "openai-env", "anthropic-env", "ollama-local", "lmstudio-local"]);
+
+const FILE = "runtime-settings.json";
+
+export function loadRuntimeSettings(dataDir: string | undefined): RuntimeSettingsLoad {
+  const file = settingsFile(dataDir);
+  if (!existsSync(file)) return { settings: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    const settings = cleanSettings(parsed);
+    return { settings, warning: cleanWarning(parsed, settings) };
+  } catch {
+    const corrupt = `${file}.corrupt.${Date.now()}`;
+    try { renameSync(file, corrupt); } catch { /* best effort */ }
+    return { settings: {}, warning: `runtime settings were corrupt and quarantined as ${corrupt}` };
+  }
+}
+
+export async function persistRuntimeSettings(state: RuntimeState): Promise<void> {
+  const file = settingsFile(state.dataDir);
+  await ensurePrivateDir(dirname(file));
+  const data: RuntimeSettings = {
+    activeProviderId: state.activeProviderId,
+    routingMode: state.routingMode,
+    pluginEnabled: state.pluginEnabled,
+    pluginOrder: state.pluginOrder,
+    providerWeights: state.providerWeights,
+    providers: state.providers.filter(persistableProvider).map(persistedProvider),
+    consumerBudgets: state.consumerBudgets,
+    agentDrafts: state.agentDrafts.map(persistedDraft)
+  };
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  await writePrivateFile(tmp, `${JSON.stringify(data, null, 2)}\n`);
+  await rename(tmp, file);
+}
+
+function settingsFile(dataDir: string | undefined): string {
+  return join(dataDir ?? defaultDataDir(), FILE);
+}
+
+function persistableProvider(provider: ProviderConfig): boolean {
+  return !BUILT_IN_IDS.has(provider.id) && !provider.runtimeAuthDir && !provider.credentialValue;
+}
+
+function persistedProvider(provider: ProviderConfig): PersistedProvider {
+  const { id, name, kind, target, credentialEnv, credentialRef, authScheme, protocol, enabled, allowDistribution, runtime, cliCommand, cliArgs, cliInputMode, cliTimeoutMs } = provider;
+  return { id, name, kind, target, credentialEnv, credentialRef, authScheme, protocol, enabled, allowDistribution, runtime, cliCommand, cliArgs, cliInputMode, cliTimeoutMs };
+}
+
+function cleanSettings(value: unknown): RuntimeSettings {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const input = value as RuntimeSettings;
+  return {
+    activeProviderId: idOk(input.activeProviderId) ? input.activeProviderId : undefined,
+    routingMode: input.routingMode === "manual" || input.routingMode === "distribute" ? input.routingMode : undefined,
+    pluginEnabled: cleanBooleanMap(input.pluginEnabled),
+    pluginOrder: cleanIdArray(input.pluginOrder),
+    providerWeights: cleanWeights(input.providerWeights),
+    providers: cleanProviders(input.providers),
+    consumerBudgets: cleanBudgets(input.consumerBudgets),
+    agentDrafts: cleanDrafts(input.agentDrafts)
+  };
+}
+
+function cleanWarning(value: unknown, settings: RuntimeSettings): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const providers = (value as RuntimeSettings).providers;
+  return Array.isArray(providers) && providers.length !== (settings.providers?.length ?? 0) ? "runtime settings contained invalid provider records that were ignored" : undefined;
+}
+
+function cleanBudgets(value: unknown): Record<string, number> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const out: Record<string, number> = {};
+  for (const [id, limit] of Object.entries(value)) {
+    if (/^[a-z0-9][a-z0-9._:-]{0,63}$/i.test(id) && typeof limit === "number" && Number.isInteger(limit) && limit > 0) out[id] = limit;
+  }
+  return out;
+}
+
+function cleanDrafts(value: unknown): AgentDraftMetadata[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  return value.slice(0, CONTROL_PLANE_LIMITS.agentDrafts).filter(isDraft).map(persistedDraft);
+}
+
+function cleanProviders(value: unknown): PersistedProvider[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const seen = new Set<string>(), out: PersistedProvider[] = [];
+  for (const item of value) {
+    const provider = cleanProvider(item);
+    if (provider && !seen.has(provider.id)) { seen.add(provider.id); out.push(provider); }
+  }
+  return out.length ? out : undefined;
+}
+
+function cleanProvider(value: unknown): PersistedProvider | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const item = value as Record<string, unknown>;
+  const id = typeof item.id === "string" && idOk(item.id) && !BUILT_IN_IDS.has(item.id) ? item.id : "";
+  const kind = item.kind === "api" || item.kind === "local" || item.kind === "cli" ? item.kind : undefined;
+  const target = typeof item.target === "string" ? item.target : "";
+  if (!id || !kind || item.credentialValue !== undefined || item.credential !== undefined) return undefined;
+  if (kind === "cli") return cleanCliProvider(id, item);
+  try { validateProviderTarget(target, { path: "runtime provider target", allowPrivate: kind === "local" }); } catch { return undefined; }
+  const credentialEnv = cleanEnv(item.credentialEnv);
+  const credentialRef = credentialEnv ? `env:${credentialEnv}` : "none";
+  return cleanBaseProvider(id, item, kind, target, { credentialEnv, credentialRef, authScheme: cleanAuth(item.authScheme, target, credentialEnv), protocol: cleanProtocol(item.protocol) });
+}
+
+function cleanCliProvider(id: string, item: Record<string, unknown>): PersistedProvider | undefined {
+  const runtime = item.runtime === "claude" || item.runtime === "codex" ? item.runtime : undefined;
+  const target = typeof item.target === "string" && item.target === `cli://${id}` ? item.target : "";
+  if (!runtime || !target) return undefined;
+  const cliArgs = Array.isArray(item.cliArgs) && item.cliArgs.every((arg) => typeof arg === "string") ? item.cliArgs.slice(0, 20) as string[] : undefined;
+  const cliTimeoutMs = typeof item.cliTimeoutMs === "number" && Number.isInteger(item.cliTimeoutMs) && item.cliTimeoutMs > 0 && item.cliTimeoutMs <= 600000 ? item.cliTimeoutMs : undefined;
+  return cleanBaseProvider(id, item, "cli", target, {
+    runtime,
+    cliCommand: typeof item.cliCommand === "string" && item.cliCommand.trim() ? item.cliCommand.trim().slice(0, 80) : runtime,
+    cliArgs,
+    cliInputMode: item.cliInputMode === "argument" ? "argument" : "stdin",
+    cliTimeoutMs,
+    authScheme: "none",
+    credentialRef: "none"
+  });
+}
+
+function cleanBaseProvider(id: string, item: Record<string, unknown>, kind: ProviderConfig["kind"], target: string, extra: Partial<PersistedProvider>): PersistedProvider {
+  return { id, name: typeof item.name === "string" && item.name.trim() ? item.name.trim().slice(0, 80) : id, kind, target, enabled: item.enabled !== false, allowDistribution: typeof item.allowDistribution === "boolean" ? item.allowDistribution : undefined, ...extra };
+}
+
+function cleanBooleanMap(value: unknown): Record<string, boolean> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const out: Record<string, boolean> = {};
+  for (const [id, enabled] of Object.entries(value)) if (idOk(id) && typeof enabled === "boolean") out[id] = enabled;
+  return Object.keys(out).length ? out : undefined;
+}
+
+function cleanWeights(value: unknown): Record<string, number> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const out: Record<string, number> = {};
+  for (const [id, weight] of Object.entries(value)) if (idOk(id) && typeof weight === "number" && Number.isFinite(weight) && weight >= 0 && weight <= 1000) out[id] = weight;
+  return Object.keys(out).length ? out : undefined;
+}
+
+function cleanIdArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value.filter((id): id is string => idOk(id)).slice(0, 100);
+  return out.length ? [...new Set(out)] : undefined;
+}
+
+function cleanEnv(value: unknown): string | undefined {
+  return typeof value === "string" && /^[A-Z_][A-Z0-9_]*$/i.test(value) ? value : undefined;
+}
+
+function cleanAuth(value: unknown, target: string, credentialEnv?: string): ProviderConfig["authScheme"] {
+  if (value === "bearer" || value === "x-api-key" || value === "none") return value;
+  if (!credentialEnv) return "none";
+  return target.includes("anthropic") ? "x-api-key" : "bearer";
+}
+
+function cleanProtocol(value: unknown): ProviderConfig["protocol"] | undefined {
+  return value === "openai-responses" || value === "anthropic-messages" || value === "openai-chat" || value === "ollama-tags" ? value : undefined;
+}
+
+function isDraft(value: unknown): value is AgentDraftMetadata {
+  if (!value || typeof value !== "object") return false;
+  const item = value as AgentDraftMetadata;
+  return idOk(item.id) && idOk(item.providerId) && typeof item.label === "string" && Array.isArray(item.enabledPluginIds) && item.status === "draft";
+}
+
+function persistedDraft(draft: AgentDraftMetadata): AgentDraftMetadata {
+  const copy: AgentDraftMetadata = { ...draft, enabledPluginIds: [...draft.enabledPluginIds] };
+  if (!copy.tokenHash) delete copy.tokenHashAlgorithm;
+  return copy;
+}
+
+function idOk(value: unknown): value is string {
+  return typeof value === "string" && /^[a-z0-9][a-z0-9._:-]{0,63}$/i.test(value);
+}