@bothat-io/molenkopf 0.1.2

package/packages/proxy/src/http/plugin-host.ts

@@ -0,0 +1,87 @@
+import type { AuditManifest } from "../../../core/src/manifest/audit-store.ts";
+import type { EventBus, MolenkopfEvent } from "../../../core/src/events/event-bus.ts";
+import { builtinPluginModules } from "../../../core/src/plugins/builtin-plugin-modules.ts";
+import type { MolenkopfPluginModule, PluginDataContext, PluginJson, PluginLifecycleContext, PluginRuntimeContext } from "../../../core/src/plugins/plugin-api.ts";
+import type { RetrievalStore } from "../../../core/src/store/retrieval-store.ts";
+import { isPluginEnabled, type RuntimeState } from "./runtime-state.ts";
+
+type Modules = Record<string, MolenkopfPluginModule>;
+type HookName = "onBoot" | "onStart" | "onEnable" | "onDisable" | "onStop";
+type DataResult = { ok: true; payload: PluginJson } | { ok: false; status: number; error: string };
+
+export type PluginHost = {
+  boot: () => Promise<void>;
+  start: (port?: number) => Promise<void>;
+  enable: (id: string) => Promise<void>;
+  disable: (id: string) => Promise<void>;
+  stop: (reason?: string) => Promise<void>;
+  audit: (manifest: AuditManifest) => Promise<void>;
+  data: (id: string, ctx: PluginDataContext) => Promise<DataResult>;
+};
+
+export function createPluginHost(state: RuntimeState, deps: { store: RetrievalStore; events: EventBus }, modules: Modules = builtinPluginModules): PluginHost {
+  const booted = new Set<string>(), started = new Set<string>();
+  let unsubscribe: (() => void) | undefined;
+  let eventQueue = Promise.resolve();
+  const runtime = (id: string): PluginRuntimeContext => ({ pluginId: id, dataDir: state.dataDir, storage: deps.store, now: () => new Date() });
+  const lifecycle = (id: string, hook: HookName, port?: number, reason?: string): PluginLifecycleContext => ({
+    pluginId: id, dataDir: state.dataDir, port, reason, now: () => new Date(),
+    note: (message) => deps.events.emit("plugin_event", { data: { pluginId: id, hook, message } })
+  });
+  async function run(id: string, hook: HookName, port?: number, reason?: string): Promise<boolean> {
+    const fn = modules[id]?.[hook];
+    if (!fn) { setLifecycle(id, hook); return true; }
+    try { await fn(lifecycle(id, hook, port, reason), runtime(id)); setLifecycle(id, hook); return true; } catch (error) { failLifecycle(id, hook, error); warn(deps.events, id, hook); return false; }
+  }
+  async function eachEnabled(task: (id: string) => Promise<void>): Promise<void> {
+    for (const id of Object.keys(modules)) if (isPluginEnabled(state, id)) await task(id);
+  }
+  return {
+    async boot() {
+      for (const id of Object.keys(modules)) if (await run(id, "onBoot")) booted.add(id);
+    },
+    async start(port) {
+      unsubscribe = deps.events.subscribe((event) => { if (event.type !== "plugin_event") eventQueue = eventQueue.then(() => notifyEvent(event)).catch(() => {}); });
+      await eachEnabled(async (id) => { if (await run(id, "onStart", port)) started.add(id); });
+    },
+    async enable(id) {
+      if (await run(id, "onEnable", state.port)) started.add(id);
+    },
+    async disable(id) {
+      await run(id, "onDisable", state.port);
+      started.delete(id);
+    },
+    async stop(reason = "server_close") {
+      unsubscribe?.();
+      for (const id of new Set([...booted, ...started])) await run(id, "onStop", state.port, reason);
+    },
+    async audit(manifest) {
+      await eachEnabled(async (id) => {
+        const fn = modules[id]?.onAudit;
+        if (fn) try { await fn({ requestId: manifest.requestId, providerId: manifest.providerId ?? "", statusCode: manifest.statusCode ?? 0, manifest: manifest as unknown as PluginJson, note: (message) => deps.events.emit("plugin_event", { data: { pluginId: id, hook: "onAudit", message } }) }, runtime(id)); } catch { warn(deps.events, id, "onAudit"); }
+      });
+    },
+    async data(id, ctx) {
+      const fn = modules[id]?.getData;
+      if (!fn) return { ok: false, status: 404, error: "plugin_data_not_found" };
+      try { return { ok: true, payload: await fn(ctx, runtime(id)) }; } catch { warn(deps.events, id, "getData"); return { ok: false, status: 500, error: "plugin_data_failed" }; }
+    }
+  };
+  async function notifyEvent(event: MolenkopfEvent): Promise<void> {
+    await eachEnabled(async (id) => {
+      const fn = modules[id]?.onEvent;
+      if (fn) try { await fn({ event: event.type, data: (event.data ?? {}) as PluginJson, emit: (name, data) => deps.events.emit("plugin_event", { data: { pluginId: id, event: name, ...data } }) }, runtime(id)); } catch { warn(deps.events, id, "onEvent"); }
+    });
+  }
+  function setLifecycle(id: string, hook: HookName): void {
+    const status = hook === "onDisable" ? "disabled" : hook === "onStop" ? "stopped" : hook === "onBoot" ? "booted" : "enabled";
+    state.pluginLifecycle[id] = { status, hook };
+  }
+  function failLifecycle(id: string, hook: string, _error: unknown): void {
+    state.pluginLifecycle[id] = { status: "error", hook, error: "plugin_hook_failed" };
+  }
+}
+
+function warn(events: EventBus, pluginId: string, hook: string): void {
+  events.emit("warning", { data: { warning: "plugin_hook_failed", pluginId, hook, error: "plugin_hook_failed" } });
+}

package/packages/proxy/src/http/plugin-modules.ts

@@ -0,0 +1 @@
+export { builtinPluginModules } from "../../../core/src/plugins/builtin-plugin-modules.ts";

package/packages/proxy/src/http/plugin-page-loader.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Plugins own their pages: a plugin ships packages/plugins/<id>/page.html and the
+// proxy serves it at /__molenkopf/plugins/<id>/page. The page fetches its own data
+// endpoint (/__molenkopf/plugins/<id>/data) client-side, so a plugin is a real
+// self-contained workspace, not a hardcoded branch in the host.
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pluginsDir = join(here, "..", "..", "..", "plugins");
+const cache = new Map<string, string | null>();
+
+export function loadPluginPage(id: string): string | undefined {
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(id)) return undefined;
+  if (!cache.has(id)) {
+    try {
+      cache.set(id, readFileSync(join(pluginsDir, id, "page.html"), "utf8"));
+    } catch {
+      cache.set(id, null);
+    }
+  }
+  return cache.get(id) ?? undefined;
+}

package/packages/proxy/src/http/plugin-pipeline.ts

@@ -0,0 +1,125 @@
+import { redactSecrets } from "../../../core/src/security/secret-redactor.ts";
+import { findPlugin } from "../../../core/src/plugins/plugin-catalog.ts";
+import type { MolenkopfPluginModule, PluginRequestResult } from "../../../core/src/plugins/plugin-api.ts";
+import type { PluginTrafficMutation } from "../../../core/src/plugins/plugin-descriptor.ts";
+import type { RetrievalStore } from "../../../core/src/store/retrieval-store.ts";
+import { builtinPluginModules } from "./plugin-modules.ts";
+
+// Plugins are middleware, but not all middleware can mutate traffic. The plugin
+// descriptor is the source of truth for reads, mutations, and toggle state.
+
+export type ConsumerUsage = { requests: number; inputTokens: number; outputTokens: number };
+
+export type PluginContext = {
+  readonly requestId: string;
+  readonly method: string;
+  readonly path: string;
+  readonly consumerId: string;
+  providerId: string;
+  body: string;
+  redactedSecrets: number;
+  compressedItems: number;
+  savedTokens: number;
+  retrievalIds: string[];
+  compressorsUsed: string[];
+  notes: string[];
+  block?: { status: number; error: string };
+  usageOf: (consumerId: string) => ConsumerUsage;
+  note: (message: string) => void;
+};
+
+export type PluginMiddleware = { id: string; mutates?: PluginTrafficMutation[]; run: (ctx: PluginContext, deps: { store: RetrievalStore }) => Promise<void> | void };
+
+export const builtinMiddlewares: PluginMiddleware[] = Object.entries(builtinPluginModules)
+  .filter(([id]) => findPlugin(id)?.hooks.includes("request:body:rewrite"))
+  .map(([id, module]) => middlewareFromModule(id, module));
+
+// Runs the enabled middlewares in order. Stops early if one blocks the request.
+export async function runRequestPipeline(ctx: PluginContext, enabled: (id: string) => boolean, deps: { store: RetrievalStore }, middlewares: PluginMiddleware[] = builtinMiddlewares): Promise<PluginContext> {
+  runCoreRedaction(ctx);
+  for (const middleware of middlewares) {
+    if (!enabled(middleware.id)) continue;
+    const before = snapshot(ctx);
+    try { await middleware.run(ctx, deps); } catch { restore(before, ctx); ctx.note(`plugin_hook_failed:${middleware.id}`); continue; }
+    enforceCapabilities(middleware, before, ctx);
+    if (ctx.block) break;
+  }
+  return ctx;
+}
+
+export function middlewareFromModule(id: string, module: MolenkopfPluginModule): PluginMiddleware {
+  return {
+    id,
+    async run(ctx, deps) {
+      if (!module.onRequest) return;
+      const result = await module.onRequest({
+        requestId: ctx.requestId,
+        method: ctx.method,
+        path: ctx.path,
+        consumerId: ctx.consumerId,
+        providerId: ctx.providerId,
+        body: ctx.body,
+        usageOf: ctx.usageOf,
+        note: ctx.note
+      }, { pluginId: id, storage: deps.store, now: () => new Date() });
+      if (result) applyModuleResult(ctx, result);
+    }
+  };
+}
+
+function applyModuleResult(ctx: PluginContext, result: PluginRequestResult): void {
+  if (result.body !== undefined) ctx.body = result.body;
+  if (result.providerId !== undefined) ctx.providerId = result.providerId;
+  if (result.block !== undefined) ctx.block = result.block;
+  if (result.redactedSecrets !== undefined) ctx.redactedSecrets += result.redactedSecrets;
+  if (result.compressedItems !== undefined) ctx.compressedItems += result.compressedItems;
+  if (result.savedTokens !== undefined) ctx.savedTokens += result.savedTokens;
+  if (result.retrievalIds) ctx.retrievalIds.push(...result.retrievalIds);
+  if (result.compressorsUsed) ctx.compressorsUsed.push(...result.compressorsUsed);
+  if (result.notes) result.notes.forEach(ctx.note);
+}
+
+function runCoreRedaction(ctx: PluginContext): void {
+  const redacted = redactSecrets(ctx.body);
+  ctx.body = redacted.text;
+  ctx.redactedSecrets += redacted.redactions.length;
+}
+
+type PipelineSnapshot = Omit<PluginContext, "usageOf" | "note">;
+
+function snapshot(ctx: PluginContext): PipelineSnapshot {
+  return { ...ctx, retrievalIds: [...ctx.retrievalIds], compressorsUsed: [...ctx.compressorsUsed], notes: [...ctx.notes], block: ctx.block ? { ...ctx.block } : undefined };
+}
+
+function enforceCapabilities(middleware: PluginMiddleware, before: PipelineSnapshot, ctx: PluginContext): void {
+  const allowed = middleware.mutates ?? findPlugin(middleware.id)?.traffic.mutates ?? ["none"];
+  if (ctx.body !== before.body && !canMutateBody(allowed)) return failCapability(middleware.id, "body", before, ctx);
+  if (ctx.providerId !== before.providerId && !allowed.includes("route")) return failCapability(middleware.id, "route", before, ctx);
+  if (blockChanged(before.block, ctx.block) && !allowed.includes("block")) return failCapability(middleware.id, "block", before, ctx);
+}
+
+function canMutateBody(allowed: PluginTrafficMutation[]): boolean {
+  return allowed.includes("mask") || allowed.includes("transform") || allowed.includes("augment-context");
+}
+
+function blockChanged(before: PluginContext["block"], after: PluginContext["block"]): boolean {
+  return (before?.status ?? 0) !== (after?.status ?? 0) || (before?.error ?? "") !== (after?.error ?? "");
+}
+
+function failCapability(id: string, mutation: string, before: PipelineSnapshot, ctx: PluginContext): void {
+  restore(before, ctx);
+  ctx.block = { status: 500, error: "plugin_capability_violation" };
+  ctx.note(`plugin_capability_violation:${id}:${mutation}`);
+}
+
+function restore(before: PipelineSnapshot, ctx: PluginContext): void {
+  ctx.body = before.body;
+  ctx.providerId = before.providerId;
+  ctx.redactedSecrets = before.redactedSecrets;
+  ctx.compressedItems = before.compressedItems;
+  ctx.savedTokens = before.savedTokens;
+  ctx.retrievalIds = [...before.retrievalIds];
+  ctx.compressorsUsed = [...before.compressorsUsed];
+  ctx.notes = [...before.notes];
+  ctx.block = before.block ? { ...before.block } : undefined;
+}

package/packages/proxy/src/http/provider-access.ts

@@ -0,0 +1,33 @@
+import type { IdentityStore } from "../../../core/src/identity/identity-store.ts";
+import type { User } from "../../../core/src/identity/types.ts";
+
+export type ProviderAllowlist = "*" | string[];
+
+export function effectiveProviderAllowlist(identity: IdentityStore, owner: User | undefined, teamIds: string[], keyScopes: string[] | undefined): ProviderAllowlist {
+  const teamAllowlist = owner?.role === "admin" ? "*" : allowlistForTeams(identity, teamIds);
+  const keyAllowlist = cleanAllowlist(keyScopes);
+  if (!keyAllowlist) return teamAllowlist;
+  if (teamAllowlist === "*") return keyAllowlist;
+  return keyAllowlist.filter((id) => teamAllowlist.includes(id));
+}
+
+export function providerAllowedForClient(client: { allowedProviderIds?: ProviderAllowlist }, providerId: string): boolean {
+  const allowed = client.allowedProviderIds;
+  if (allowed && allowed !== "*" && !allowed.includes(providerId)) return false;
+  return true;
+}
+
+function allowlistForTeams(identity: IdentityStore, teamIds: string[]): ProviderAllowlist {
+  const providers = new Set<string>();
+  for (const teamId of teamIds) {
+    const allowed = identity.getTeam(teamId)?.allowedProviders;
+    if (allowed === "*") return "*";
+    if (Array.isArray(allowed)) for (const providerId of allowed) providers.add(providerId);
+  }
+  return [...providers];
+}
+
+function cleanAllowlist(value: string[] | undefined): string[] | undefined {
+  if (!value) return undefined;
+  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];
+}

package/packages/proxy/src/http/provider-http-test.ts

@@ -0,0 +1,133 @@
+import { request as httpRequest, type IncomingHttpHeaders, type OutgoingHttpHeaders } from "node:http";
+import { request as httpsRequest } from "node:https";
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import { resolveConnectTarget, type ConnectTarget } from "../../../core/src/security/target-policy.ts";
+import { buildForwardHeaders, missingProviderCredential } from "./header-utils.ts";
+
+type Check = { status: "ok" | "failed" | "missing" | "unknown" | "blocked"; message: string };
+type SmokeSpec = { method: "GET" | "POST"; path: string; protocol: string; body?: Record<string, unknown> };
+
+export async function providerHttpTest(provider: ProviderConfig) {
+  const base = {
+    providerId: provider.id,
+    kind: provider.kind,
+    runtime: provider.runtime ?? provider.kind,
+    protocol: protocolOf(provider),
+    auth: authCheck(provider),
+    model: { status: "unknown", message: "Not tested yet" } as Check,
+    permission: { status: "unknown", message: "HTTP providers do not use host CLI permissions" } as Check,
+    http: { statusCode: 0, path: "", method: "" }
+  };
+  if (base.auth.status === "missing") return base;
+  const spec = smokeSpec(provider);
+  const headers = buildForwardHeaders(new Headers({ "content-type": "application/json" }), provider);
+  if (spec.protocol === "anthropic-messages") headers.set("anthropic-version", "2023-06-01");
+  const url = smokeUrl(provider.target, spec);
+  try {
+    const checked = await resolveConnectTarget(url, { path: "provider test target", allowPrivate: provider.kind === "local" });
+    const response = await pinnedRequest(checked, {
+      method: spec.method,
+      headers,
+      body: spec.body ? JSON.stringify(spec.body) : undefined
+    });
+    const redirect = await blockedRedirect(response, url, provider.kind === "local");
+    if (redirect) return { ...base, model: redirect, http: { statusCode: response.status, path: spec.path, method: spec.method } };
+    return {
+      ...base,
+      auth: authFromStatus(response.status, base.auth),
+      model: statusCheck(response.status, spec),
+      http: { statusCode: response.status, path: spec.path, method: spec.method }
+    };
+  } catch (error) {
+    return { ...base, model: { status: "failed", message: safeError(error) } as Check, http: { statusCode: 0, path: spec.path, method: spec.method } };
+  }
+}
+
+type ProviderHttpResponse = { status: number; headers: Headers };
+
+async function pinnedRequest(checked: ConnectTarget, init: { method: string; headers: Headers; body?: string }): Promise<ProviderHttpResponse> {
+  const transport = checked.url.protocol === "https:" ? httpsRequest : httpRequest;
+  return new Promise((resolve, reject) => {
+    const request = transport(checked.url, { method: init.method, headers: outgoingHeaders(init.headers, checked.url.host), lookup: pinnedLookup(checked.address, checked.family) }, (response) => {
+      response.resume();
+      response.on("end", () => resolve({ status: response.statusCode ?? 0, headers: responseHeaders(response.headers) }));
+      response.on("error", reject);
+    });
+    request.setTimeout(15000, () => request.destroy(new Error("provider test timed out after 15000ms")));
+    request.on("error", reject);
+    request.end(init.body);
+  });
+}
+
+async function blockedRedirect(response: ProviderHttpResponse, url: string, allowPrivate: boolean): Promise<Check | undefined> {
+  if (response.status < 300 || response.status > 399) return undefined;
+  const location = response.headers.get("location");
+  if (!location) return undefined;
+  try { await resolveConnectTarget(new URL(location, url).toString(), { path: "provider redirect", allowPrivate }); return undefined; }
+  catch { return { status: "blocked", message: "Provider redirect target is not allowed" }; }
+}
+
+function authCheck(provider: ProviderConfig): Check {
+  if (missingProviderCredential(provider)) return { status: "missing", message: "Provider credential is missing" };
+  return { status: "ok", message: provider.authScheme === "none" ? "No credential required" : "Provider credential policy is configured" };
+}
+
+function authFromStatus(status: number, current: Check): Check {
+  if (status === 401 || status === 403) return { status: "failed", message: `Upstream rejected credentials with HTTP ${status}` };
+  return current;
+}
+
+function statusCheck(status: number, spec: SmokeSpec): Check {
+  const message = `${spec.protocol} smoke ${spec.method} ${spec.path} returned HTTP ${status}`;
+  return status >= 200 && status < 300 ? { status: "ok", message } : { status: "failed", message };
+}
+
+function smokeSpec(provider: ProviderConfig): SmokeSpec {
+  const protocol = protocolOf(provider);
+  if (protocol === "ollama-tags") return { method: "GET", path: "/api/tags", protocol };
+  if (protocol === "anthropic-messages") return {
+    method: "POST", path: "/messages", protocol,
+    body: { model: "claude-3-5-haiku-latest", max_tokens: 1, messages: [{ role: "user", content: "Reply OK" }] }
+  };
+  if (protocol === "openai-chat") return { method: "GET", path: "/models", protocol };
+  return { method: "POST", path: "/responses", protocol, body: { model: "gpt-4.1-mini", input: "Reply OK", max_output_tokens: 1 } };
+}
+
+function protocolOf(provider: ProviderConfig): NonNullable<ProviderConfig["protocol"]> {
+  if (provider.protocol) return provider.protocol;
+  if (provider.kind === "local" && provider.target.includes("11434")) return "ollama-tags";
+  if (provider.kind === "local") return "openai-chat";
+  return provider.authScheme === "x-api-key" || provider.target.includes("anthropic") ? "anthropic-messages" : "openai-responses";
+}
+
+function smokeUrl(target: string, spec: SmokeSpec): string {
+  if (spec.protocol === "ollama-tags") return new URL(spec.path, new URL(target).origin).toString();
+  const base = target.endsWith("/") ? target : `${target}/`;
+  return new URL(spec.path.replace(/^\//, ""), base).toString();
+}
+
+function safeError(error: unknown): string {
+  return error instanceof Error ? error.message.slice(0, 180) : String(error).slice(0, 180);
+}
+
+function outgoingHeaders(headers: Headers, host: string): OutgoingHttpHeaders {
+  const out: OutgoingHttpHeaders = {};
+  headers.forEach((value, key) => { out[key] = value; });
+  out.host = host;
+  return out;
+}
+
+function responseHeaders(headers: IncomingHttpHeaders): Headers {
+  const out = new Headers();
+  for (const [key, value] of Object.entries(headers)) {
+    if (Array.isArray(value)) for (const item of value) out.append(key, item);
+    else if (value !== undefined) out.set(key, String(value));
+  }
+  return out;
+}
+
+function pinnedLookup(address: string, family: 4 | 6) {
+  return (_hostname: string, _options: unknown, callback: (error: NodeJS.ErrnoException | null, address: string, family: number) => void) => {
+    callback(null, address, family);
+  };
+}

package/packages/proxy/src/http/provider-input.ts

@@ -0,0 +1,39 @@
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import { validateProviderTarget } from "../../../core/src/security/target-policy.ts";
+
+export function buildProviderFromInput(id: string, name: string, body: Record<string, unknown>): { provider: ProviderConfig } | { error: string } {
+  const kind = String(body.kind ?? "openai");
+  if (!knownKind(kind)) return { error: "invalid_kind" };
+  const credential = typeof body.credential === "string" && body.credential.trim() ? body.credential.trim() : undefined;
+  const credentialEnv = typeof body.credentialEnv === "string" && body.credentialEnv.trim() ? body.credentialEnv.trim() : undefined;
+  if (credentialEnv && !validEnv(credentialEnv)) return { error: "invalid_credential_env" };
+  if (kind === "cli-claude" || kind === "cli-codex") {
+    const runtime = kind === "cli-codex" ? "codex" : "claude";
+    return { provider: { id, name, kind: "cli", target: `cli://${id}`, runtime, cliCommand: runtime, cliArgs: runtime === "codex" ? ["exec"] : ["--print"], cliInputMode: "stdin", authScheme: "none", credentialRef: "none", enabled: true } };
+  }
+  const target = providerTarget(kind, body);
+  const providerKind = kind === "local" || kind === "ollama" ? "local" : "api";
+  try { validateProviderTarget(target, { path: "provider target", allowPrivate: providerKind === "local" }); } catch { return { error: "invalid_target" }; }
+  const authScheme = kind === "anthropic" ? "x-api-key" : providerKind === "local" ? "none" : credential || credentialEnv ? "bearer" : "none";
+  return { provider: { id, name, kind: providerKind, target, authScheme, protocol: providerProtocol(kind), credentialValue: credential, credentialEnv, credentialRef: credential ? "inline" : credentialEnv ? `env:${credentialEnv}` : "none", enabled: true } };
+}
+
+export function validEnv(value: string): boolean {
+  return /^[A-Z_][A-Z0-9_]*$/i.test(value);
+}
+
+function providerTarget(kind: string, body: Record<string, unknown>): string {
+  const target = typeof body.target === "string" ? body.target.trim() : "";
+  return target || (kind === "ollama" ? "http://127.0.0.1:11434/v1" : "");
+}
+
+function providerProtocol(kind: string): ProviderConfig["protocol"] {
+  if (kind === "anthropic") return "anthropic-messages";
+  if (kind === "ollama") return "ollama-tags";
+  if (kind === "local") return "openai-chat";
+  return "openai-responses";
+}
+
+function knownKind(kind: string): boolean {
+  return ["openai", "openai-compatible", "anthropic", "local", "ollama", "cli-claude", "cli-codex"].includes(kind);
+}

package/packages/proxy/src/http/provider-routing-snapshot.ts

@@ -0,0 +1,28 @@
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import type { RoutingMode, RuntimeState } from "./runtime-state.ts";
+
+type Snapshot = {
+  providers: ProviderConfig[];
+  providerWeights: Record<string, number>;
+  activeProviderId: string;
+  providerSelectedAt?: string;
+  routingMode: RoutingMode;
+};
+
+export function snapshotProviderRouting(state: RuntimeState): Snapshot {
+  return {
+    providers: state.providers.slice(),
+    providerWeights: { ...state.providerWeights },
+    activeProviderId: state.activeProviderId,
+    providerSelectedAt: state.providerSelectedAt,
+    routingMode: state.routingMode
+  };
+}
+
+export function restoreProviderRouting(state: RuntimeState, snapshot: Snapshot): void {
+  state.providers = snapshot.providers;
+  state.providerWeights = snapshot.providerWeights;
+  state.activeProviderId = snapshot.activeProviderId;
+  state.providerSelectedAt = snapshot.providerSelectedAt;
+  state.routingMode = snapshot.routingMode;
+}

package/packages/proxy/src/http/provider-test.ts

@@ -0,0 +1,149 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import { isCliProvider, runCliProvider } from "../runtime/cli-provider.ts";
+import { cliErrorDiagnostics, safeCliMessage, successfulCliLifecycle } from "../runtime/cli-diagnostics.ts";
+import { runtimeProfileFromImport, writeRuntimeProfileFiles } from "../runtime/runtime-profile.ts";
+import type { RuntimeState } from "./runtime-state.ts";
+import { missingProviderCredential } from "./header-utils.ts";
+import { readJson, writeJson } from "./local-api-io.ts";
+import { providerHttpTest } from "./provider-http-test.ts";
+import { runtimeAuthProvider, writeRuntimeAuthFiles } from "./runtime-auth-registry.ts";
+import { issueRuntimeAuthProof } from "./runtime-auth-proof.ts";
+
+type Check = { status: "ok" | "failed" | "missing" | "unknown" | "blocked"; message: string };
+const RUNTIME_TEST_BYTES = 256 * 1024;
+
+export async function testRuntimeProvider(req: IncomingMessage, res: ServerResponse, state: RuntimeState) {
+  const result = await selectedProviderTest(req, state, "runtime");
+  writeJson(res, statusOfTestResult(result), result);
+}
+
+export async function testProvider(req: IncomingMessage, res: ServerResponse, state: RuntimeState) {
+  const result = await selectedProviderTest(req, state, "auto");
+  writeJson(res, statusOfTestResult(result), result);
+}
+
+async function selectedProviderTest(req: IncomingMessage, state: RuntimeState, mode: "auto" | "runtime") {
+  const body = await readJson(req, mode === "runtime" ? RUNTIME_TEST_BYTES : undefined);
+  if (mode === "runtime" && hasDraftRuntimeAuth(body)) {
+    const result = await draftRuntimeProviderTest(body);
+    return statusOfTestResult(result) === 200 ? { ...result, importProof: issueRuntimeAuthProof(state, body) } : result;
+  }
+  const id = typeof body.id === "string" && body.id.trim() ? body.id.trim() : state.activeProviderId;
+  const provider = state.providers.find((item) => item.id === id);
+  if (!provider) return { error: "unknown_provider" };
+  if (provider.enabled === false) return { error: "provider_disabled" };
+  if (mode === "auto" && !isCliProvider(provider)) return providerHttpTest(provider);
+  return providerRuntimeTest(provider);
+}
+
+function statusOfTestResult(result: any): number {
+  if (result.error === "invalid_runtime" || result.error === "missing_auth_json" || result.error === "invalid_auth_json" || result.error === "invalid_runtime_profile") return 400;
+  if (result.error === "unknown_provider") return 404;
+  if (result.error === "provider_disabled") return 409;
+  if (result.permission?.status === "blocked" || result.model?.status === "failed" || result.auth?.status === "failed") return 502;
+  return 200;
+}
+
+async function draftRuntimeProviderTest(body: Record<string, unknown>) {
+  const runtime = runtimeValue(body.runtime);
+  if (!runtime) return { error: "invalid_runtime" };
+  const authJson = authJsonText(body);
+  if (!authJson) return { error: "missing_auth_json" };
+  if (!parseJsonObject(authJson)) return { error: "invalid_auth_json" };
+  let runtimeProfile;
+  try {
+    runtimeProfile = runtimeProfileFromImport(body, runtime);
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : "invalid_runtime_profile" };
+  }
+  const root = await mkdtemp(join(tmpdir(), "molenkopf-runtime-test-"));
+  try {
+    const authDir = join(root, "runtime-auth", "draft");
+    await writeRuntimeAuthFiles(authDir, runtime, authJson.endsWith("\n") ? authJson : `${authJson}\n`);
+    await writeRuntimeProfileFiles(authDir, runtimeProfile);
+    const provider = runtimeAuthProvider("draft", "Draft runtime provider", runtime, authDir, "runtime-auth:draft", runtimeProfile.profile);
+    return { ...(await providerRuntimeTest(provider)), draft: true };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+function hasDraftRuntimeAuth(body: Record<string, unknown>): boolean {
+  return typeof body.runtime === "string" && "authJson" in body;
+}
+
+function runtimeValue(value: unknown): "claude" | "codex" | undefined {
+  return value === "claude" || value === "codex" ? value : undefined;
+}
+
+function authJsonText(body: Record<string, unknown>): string {
+  if (typeof body.authJson === "string" && body.authJson.trim()) return body.authJson.trim();
+  return "";
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function providerRuntimeTest(provider: ProviderConfig) {
+  const base = {
+    providerId: provider.id,
+    runtime: provider.runtime ?? provider.kind,
+    auth: authCheck(provider),
+    model: { status: "unknown", message: "Not tested yet" } as Check,
+    permission: permissionCheck(provider),
+    lifecycle: { state: "unknown", events: [] as string[] }
+  };
+  if (base.auth.status === "missing") return base;
+  if (!isCliProvider(provider)) return { ...base, model: { status: "unknown", message: "Only local CLI providers are tested here" } as Check };
+  try {
+    const checkedProvider = { ...provider, cliTimeoutMs: Math.min(provider.cliTimeoutMs ?? 30000, 30000) };
+    const result = await runCliProvider(checkedProvider, JSON.stringify({ input: "Reply with OK only. Molenkopf provider test." }), `test-${Date.now()}`);
+    return { ...base, model: modelCheck(result.body), permission: { ...base.permission, message: "No host permission block was observed during this read-only test" }, lifecycle: successfulCliLifecycle() };
+  } catch (error) {
+    const message = safeCliMessage(error);
+    const cli = cliErrorDiagnostics(error);
+    if (cli.permissionBlocked) return { ...base, model: { status: "failed", message: "CLI did not complete" } as Check, permission: { status: "blocked", message: "Local CLI reported a permission prompt" } as Check, lifecycle: cli.lifecycle };
+    if (cli.class === "auth_failure") return { ...base, auth: { status: "failed", message } as Check, model: { status: "failed", message: "CLI did not complete" } as Check, lifecycle: cli.lifecycle };
+    return { ...base, auth: authFromError(message, base.auth), model: { status: "failed", message } as Check, lifecycle: cli.lifecycle };
+  }
+}
+
+function authCheck(provider: ProviderConfig): Check {
+  if (missingProviderCredential(provider)) return { status: "missing", message: "Provider credential is missing" };
+  if (provider.runtimeAuthDir) return { status: "ok", message: "Imported auth directory is configured" };
+  if (provider.kind === "cli") return { status: "unknown", message: "Local CLI auth is managed by the installed client" };
+  return { status: "ok", message: "Provider credential policy is configured" };
+}
+
+function permissionCheck(provider: ProviderConfig): Check {
+  if (provider.runtime === "claude") return { status: "unknown", message: "Outer Claude harness permissions are separate from imported auth" };
+  if (provider.runtime === "codex") return { status: "unknown", message: "Outer Codex harness permissions are separate from imported auth" };
+  return { status: "unknown", message: "No imported runtime permission profile" };
+}
+
+function modelCheck(body: Buffer): Check {
+  const text = body.toString("utf8");
+  try {
+    const json = JSON.parse(text) as { output_text?: string; content?: { text?: string }[] };
+    const output = json.output_text ?? json.content?.map((item) => item.text).filter(Boolean).join(" ");
+    return output ? { status: "ok", message: "Model produced a non-empty response" } : { status: "failed", message: "Model response had no text" };
+  } catch {
+    return text.trim() ? { status: "ok", message: "Model produced a non-empty response" } : { status: "failed", message: "Model response was empty" };
+  }
+}
+
+function authFromError(message: string, current: Check): Check {
+  return /output_class:auth_failure|not logged in|please run \/login|auth|authentication|credentials/i.test(message)
+    ? { status: "failed", message }
+    : current;
+}