@bothat-io/molenkopf 0.1.2

package/packages/proxy/src/cli/main.ts

@@ -0,0 +1,132 @@
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { compressContext } from "../../../core/src/compression/context-compressor.ts";
+import { AuditStore } from "../../../core/src/manifest/audit-store.ts";
+import { RetrievalStore } from "../../../core/src/store/retrieval-store.ts";
+import { startProxy } from "../http/server.ts";
+import { parseArgs, type CliArgs } from "./args.ts";
+import { loadProxyConfig } from "./config-loader.ts";
+import { loadDefaultEnvFile, loadEnvFile } from "./env-file.ts";
+import { resolveCliTarget } from "./target.ts";
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.command === "--help" || args.command === "help" || args.flags.has("help")) return usage(0);
+  if (args.command === "proxy") return proxy(args);
+  if (args.command === "compress-file") return compressFile(args);
+  if (args.command === "retrieve") return retrieve(args);
+  if (args.command === "inspect") return inspect(args);
+  if (args.command === "self-test") return selfTest();
+  usage(1);
+}
+
+async function proxy(args: CliArgs) {
+  const envFile = args.flags.get("env-file");
+  if (typeof envFile === "string") await loadEnvFile(envFile);
+  loadDefaultEnvFile();
+  const loaded = await loadProxyConfig(args.flags);
+  const config = loaded.config;
+  const explicitConfig = loaded.source === "file" && Boolean(config);
+  const target = targetValue(args.flags, config?.target);
+  const port = Number(args.flags.get("port") ?? config?.server.port ?? 8787);
+  const host = String(args.flags.get("host") ?? config?.server.bindHost ?? "127.0.0.1");
+  const allowPublicBind = args.flags.has("allow-public-bind") || config?.server.allowPublicBind === true;
+  const dataDir = stringFlag(args.flags, "data-dir") ?? config?.server.dataDir;
+  if (host !== "127.0.0.1" && allowPublicBind) console.warn("warning: public bind enabled");
+  let running: Awaited<ReturnType<typeof startProxy>>;
+  try {
+    running = await startProxy({
+      target,
+      port,
+      host,
+      allowPublicBind,
+      dataDir,
+      providers: config?.providers,
+      activeProviderId: config?.activeProviderId,
+      configAgents: config?.agents,
+      providerCatalogMode: explicitConfig ? "explicit" : "auto",
+      configSource: { kind: loaded.source, path: displayConfigPath(loaded.configPath) }
+    });
+  } catch (error) {
+    if (isAddressInUse(error) && await isMolenkopfRunning(host, port)) {
+      console.log(`Molenkopf proxy already running on http://${host}:${port}`);
+      console.log(`Dashboard: http://${host}:${port}/__molenkopf/dashboard`);
+      return;
+    }
+    if (isAddressInUse(error)) throw new Error(`port already in use: ${host}:${port}; stop that process or pass --port <free-port>`);
+    throw error;
+  }
+  console.log(`Molenkopf proxy listening on http://${host}:${running.port}`);
+}
+
+async function compressFile(args: CliArgs) {
+  const file = args.values[0];
+  if (!file) throw new Error("compress-file requires a file path");
+  const text = await readFile(file, "utf8");
+  const store = new RetrievalStore();
+  const result = await compressContext(text, store);
+  console.log(result.text);
+  if (result.retrievalId) console.log(`\nretrieve: ${result.retrievalId}`);
+}
+
+async function retrieve(args: CliArgs) {
+  const id = args.values[0];
+  if (!id) throw new Error("retrieve requires a retrieval id");
+  console.log(await new RetrievalStore().retrieve(id));
+}
+
+async function inspect(args: CliArgs) {
+  if (!args.flags.has("last")) throw new Error("inspect currently supports --last");
+  const latest = await new AuditStore().latest();
+  console.log(JSON.stringify(latest ?? {}, null, 2));
+}
+
+async function selfTest() {
+  const sample = Array.from({ length: 260 }, (_, i) => `line ${i}`).join("\n") + "\nERROR sample";
+  const result = await compressContext(sample, new RetrievalStore());
+  if (!result.compressed || !result.retrievalId) throw new Error("compression self-test failed");
+  const original = await new RetrievalStore().retrieve(result.retrievalId);
+  if (!original.includes("Context excerpt only") || !original.includes("TRUNCATED_CONTEXT")) throw new Error("retrieval self-test failed");
+  if (original.includes("ERROR sample")) throw new Error("retrieval self-test persisted a raw tail");
+  console.log("self-test ok");
+}
+
+function usage(code: number): never {
+  console.error("usage: proxy [--env-file FILE] [--config FILE]|compress-file|retrieve|inspect|self-test");
+  process.exit(code);
+}
+
+function targetValue(flags: Map<string, string | boolean>, configTarget?: string): string {
+  const explicit = stringFlag(flags, "target");
+  return explicit ?? configTarget ?? resolveCliTarget(flags);
+}
+
+function stringFlag(flags: Map<string, string | boolean>, name: string): string | undefined {
+  const value = flags.get(name);
+  return typeof value === "string" && value ? value : undefined;
+}
+
+function displayConfigPath(path: string | undefined): string | undefined {
+  if (!path) return undefined;
+  const rel = relative(process.cwd(), path);
+  return rel && !rel.startsWith("..") && !rel.includes(":") ? rel : path;
+}
+
+function isAddressInUse(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EADDRINUSE";
+}
+
+async function isMolenkopfRunning(host: string, port: number): Promise<boolean> {
+  const healthHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+  try {
+    const response = await fetch(`http://${healthHost}:${port}/__molenkopf/health`, { signal: AbortSignal.timeout(800) });
+    return response.ok && (await response.json()).ok === true;
+  } catch {
+    return false;
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/packages/proxy/src/cli/profile-server.ts

@@ -0,0 +1,176 @@
+import { spawn } from "node:child_process";
+import { watch } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ensurePrivateDirSync } from "../../../core/src/storage/private-state.ts";
+import { validateProviderTarget } from "../../../core/src/security/target-policy.ts";
+import { loadDefaultEnvFile } from "./env-file.ts";
+
+const WATCH_DIRS = ["packages/core/src", "packages/proxy/src"];
+const RESTART_DEBOUNCE_MS = 250;
+const FORCE_KILL_MS = 1500;
+const DASHBOARD_DEV_PORT = 5173;
+
+const PROFILE_DEFAULTS = {
+  dev: { port: 8787, dataDir: ".molenkopf/dev" },
+  test: { port: 8798, dataDir: ".molenkopf/test" },
+  prod: { port: 8787, dataDir: ".molenkopf/prod" }
+};
+
+type ProfileName = keyof typeof PROFILE_DEFAULTS;
+type Profile = { name: ProfileName; port: number; host: string; target: string; dataDir: string };
+
+export function resolveProfile(name: string, env: Record<string, string | undefined> = process.env): Profile {
+  if (!isProfileName(name)) throw new Error("profile must be one of: dev, test, prod");
+  const upper = name.toUpperCase();
+  const base = PROFILE_DEFAULTS[name];
+  const port = parsePort(env[`MOLENKOPF_${upper}_PORT`] || String(base.port));
+  const dataDir = env[`MOLENKOPF_${upper}_DATA_DIR`] || base.dataDir;
+  const target = env[`MOLENKOPF_${upper}_TARGET`] || env.MOLENKOPF_TARGET || "https://api.openai.com/v1";
+  const host = env[`MOLENKOPF_${upper}_HOST`] || "127.0.0.1";
+  validateHost(host);
+  validateTarget(target);
+  if (!dataDir.trim()) throw new Error("dataDir must not be empty");
+  return { name, port, host, target, dataDir: resolve(dataDir) };
+}
+
+export function proxyArgs(profile: Profile) {
+  return [
+    "--experimental-strip-types", "--experimental-sqlite", "--disable-warning=ExperimentalWarning",
+    "packages/proxy/src/cli/main.ts", "proxy",
+    "--target", profile.target, "--host", profile.host,
+    "--port", String(profile.port), "--data-dir", profile.dataDir
+  ];
+}
+
+export function devWatchEnabled(profile: Profile, env: Record<string, string | undefined> = process.env) {
+  return profile.name === "dev" && env.MOLENKOPF_DEV_WATCH !== "0";
+}
+
+function spawnProxy(profile: Profile, revision?: string) {
+  const env: NodeJS.ProcessEnv = { ...process.env, MOLENKOPF_PROFILE: profile.name };
+  if (revision) env.MOLENKOPF_DEV_REVISION = revision;
+  if (profile.name === "dev" && dashboardDevEnabled()) env.MOLENKOPF_DASHBOARD_DEV_ORIGIN = dashboardDevOrigin(env);
+  return spawnLogged(process.execPath, proxyArgs(profile), { env });
+}
+
+function run() {
+  loadDefaultEnvFile();
+  const profile = resolveProfile(process.argv[2] || "dev");
+  ensurePrivateDirSync(profile.dataDir);
+  console.log(`Molenkopf ${profile.name}: http://${profile.host}:${profile.port}`);
+  console.log(`data-dir: ${profile.dataDir}`);
+  if (devWatchEnabled(profile)) return runWatched(profile);
+  const child = spawnProxy(profile);
+  child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+}
+
+function runWatched(profile: Profile) {
+  const watchers: ReturnType<typeof watch>[] = [];
+  let child: ReturnType<typeof spawnProxy>;
+  const dashboard = dashboardDevEnabled() ? spawnDashboardDev() : undefined;
+  let revision = String(Date.now());
+  let restartTimer: ReturnType<typeof setTimeout>;
+  let restarting = false;
+
+  const startChild = () => {
+    console.log(`dev-revision: ${revision}`);
+    child = spawnProxy(profile, revision);
+    child.on("exit", (code, signal) => {
+      if (restarting) { restarting = false; startChild(); return; }
+      closeWatchers(watchers);
+      process.exit(code ?? (signal ? 1 : 0));
+    });
+  };
+
+  const scheduleRestart = (reason: string) => {
+    if (restarting) return;
+    clearTimeout(restartTimer);
+    restartTimer = setTimeout(() => {
+      revision = String(Date.now());
+      console.log(`Dev change: ${reason}; restarting Molenkopf...`);
+      restarting = true;
+      let exited = false;
+      child.once("exit", () => { exited = true; });
+      child.kill();
+      const forceKill = setTimeout(() => { if (!exited) child.kill("SIGKILL"); }, FORCE_KILL_MS);
+      forceKill.unref?.();
+    }, RESTART_DEBOUNCE_MS);
+  };
+
+  startChild();
+  for (const dir of WATCH_DIRS) {
+    try {
+      const root = resolve(dir);
+      watchers.push(watch(root, { recursive: true }, (_event, file) => scheduleRestart(file ? join(dir, String(file)) : dir)));
+    } catch (error) {
+      console.warn(`Dev watch disabled for ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  const stop = (code: number) => {
+    closeWatchers(watchers);
+    child.kill();
+    if (dashboard) dashboard.kill();
+    process.exit(code);
+  };
+  process.on("SIGINT", () => stop(130));
+  process.on("SIGTERM", () => stop(143));
+}
+
+function dashboardDevEnabled(env = process.env) {
+  return env.MOLENKOPF_DASHBOARD_DEV !== "0";
+}
+
+function dashboardDevOrigin(env = process.env) {
+  const port = Number(env.MOLENKOPF_DASHBOARD_DEV_PORT || DASHBOARD_DEV_PORT);
+  return `http://127.0.0.1:${port}`;
+}
+
+function spawnDashboardDev() {
+  const command = process.platform === "win32" ? process.env.ComSpec || "cmd.exe" : "npm";
+  const args = process.platform === "win32" ? ["/d", "/s", "/c", "npm --prefix packages/dashboard run dev"] : ["--prefix", "packages/dashboard", "run", "dev"];
+  const profile = resolveProfile(process.argv[2] || "dev");
+  return spawnLogged(command, args, {
+    env: {
+      ...process.env,
+      MOLENKOPF_DASHBOARD_DEV_PORT: String(Number(process.env.MOLENKOPF_DASHBOARD_DEV_PORT || DASHBOARD_DEV_PORT)),
+      MOLENKOPF_DASHBOARD_API_ORIGIN: `http://${profile.host}:${profile.port}`
+    }
+  });
+}
+
+function closeWatchers(watchers: ReturnType<typeof watch>[]) {
+  for (const watcher of watchers) watcher.close();
+}
+
+function spawnLogged(command: string, args: string[], options: { env: NodeJS.ProcessEnv }) {
+  const child = spawn(command, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+  child.stdout?.pipe(process.stdout);
+  child.stderr?.pipe(process.stderr);
+  return child;
+}
+
+function isProfileName(name: string): name is ProfileName {
+  return name === "dev" || name === "test" || name === "prod";
+}
+
+function parsePort(value: string): number {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("invalid profile port");
+  return port;
+}
+
+function validateHost(value: string): void {
+  if (!value.trim() || /[/:?#]/.test(value)) throw new Error("invalid profile host");
+}
+
+function validateTarget(value: string): void {
+  try {
+    validateProviderTarget(value, { path: "profile target", allowPrivate: true });
+  } catch {
+    throw new Error("invalid profile target");
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) run();

package/packages/proxy/src/cli/target.ts

@@ -0,0 +1,7 @@
+export function resolveCliTarget(flags: Map<string, string | boolean>, env: Record<string, string | undefined> = process.env): string {
+  const explicit = flags.get("target");
+  if (typeof explicit === "string" && explicit) return explicit;
+  if (env.ANTHROPIC_BASE_URL) return env.ANTHROPIC_BASE_URL;
+  if (env.OPENAI_BASE_URL) return env.OPENAI_BASE_URL;
+  return "https://api.openai.com/v1";
+}

package/packages/proxy/src/http/agent-drafts.ts

@@ -0,0 +1,103 @@
+import { pluginCatalog } from "../../../core/src/plugins/plugin-catalog.ts";
+import { clientIdForAgent } from "./client-identity.ts";
+import { CONTROL_PLANE_LIMITS, emptyUsage, enabledPluginIds, type AgentDraftMetadata, type AgentDraftView, type RuntimeState, type RuntimeStateResult } from "./runtime-state.ts";
+
+export function listAgentDrafts(state: RuntimeState): AgentDraftView[] {
+  return state.agentDrafts.slice(0, CONTROL_PLANE_LIMITS.agentDrafts).map((draft) => viewDraft(draft, state));
+}
+
+export function upsertAgentDraft(state: RuntimeState, input: Record<string, unknown>, now = new Date().toISOString()): RuntimeStateResult<AgentDraftView> {
+  const rawField = rawCredentialField(input);
+  if (rawField) return fail(400, "raw_token_rejected", `${rawField} must be sent as tokenHash`);
+
+  const id = cleanId(input.id);
+  if (!id) return fail(400, "invalid_agent_id");
+  const existingIndex = state.agentDrafts.findIndex((item) => item.id === id);
+  const existing = existingIndex >= 0 ? state.agentDrafts[existingIndex] : undefined;
+  if (!existing && state.agentDrafts.length >= CONTROL_PLANE_LIMITS.agentDrafts) return fail(409, "agent_draft_limit");
+
+  const label = cleanLabel(input.label ?? input.name ?? existing?.label ?? id);
+  if (!label) return fail(400, "invalid_agent_label");
+  const kind = cleanAgentKind(input.kind ?? existing?.kind ?? "CI agent");
+  const providerId = cleanId(input.providerId ?? existing?.providerId ?? state.activeProviderId);
+  const provider = providerId ? state.providers.find((item) => item.id === providerId) : undefined;
+  if (!provider) return fail(404, "unknown_provider");
+  if (provider.enabled === false) return fail(409, "provider_disabled");
+
+  const plugins = normalizePluginIds(input.enabledPluginIds ?? input.pluginIds, state, existing);
+  if (plugins.ok === false) return plugins;
+  const tokenHash = normalizeTokenHash(input, existing);
+  if (tokenHash.ok === false) return tokenHash;
+
+  let tokenLimit = existing?.tokenLimit;
+  if (input.tokenLimit !== undefined) {
+    if (input.tokenLimit === null || input.tokenLimit === 0) tokenLimit = undefined;
+    else if (typeof input.tokenLimit === "number" && Number.isInteger(input.tokenLimit) && input.tokenLimit > 0) tokenLimit = input.tokenLimit;
+    else return fail(400, "invalid_token_limit");
+  }
+  const disabled = typeof input.disabled === "boolean" ? input.disabled : existing?.disabled;
+
+  const draft: AgentDraftMetadata = { id, label, kind, providerId: provider.id, enabledPluginIds: plugins.value, status: "draft", createdAt: existing?.createdAt ?? now, updatedAt: now };
+  if (tokenHash.value) {
+    draft.tokenHash = tokenHash.value;
+    draft.tokenHashAlgorithm = "sha256";
+  }
+  if (disabled) draft.disabled = true;
+  if (tokenLimit) draft.tokenLimit = tokenLimit;
+  if (existingIndex >= 0) state.agentDrafts[existingIndex] = draft;
+  else state.agentDrafts.push(draft);
+  return { ok: true, value: viewDraft(draft, state) };
+}
+
+function normalizePluginIds(input: unknown, state: RuntimeState, existing?: AgentDraftMetadata): RuntimeStateResult<string[]> {
+  if (input === undefined) return { ok: true, value: existing?.enabledPluginIds ?? enabledPluginIds(state) };
+  if (!Array.isArray(input) || input.length > CONTROL_PLANE_LIMITS.pluginIds) return fail(400, "invalid_plugin_ids");
+  const known = new Set(pluginCatalog.map((plugin) => plugin.id));
+  const ids = [...new Set(input.map(cleanId))];
+  if (ids.some((id) => !id)) return fail(400, "invalid_plugin_id");
+  const unknown = ids.find((id) => !known.has(id as string));
+  if (unknown) return fail(404, "unknown_plugin", unknown);
+  return { ok: true, value: ids as string[] };
+}
+
+function normalizeTokenHash(input: Record<string, unknown>, existing?: AgentDraftMetadata): RuntimeStateResult<string | undefined> {
+  if (input.tokenHash === undefined) return { ok: true, value: existing?.tokenHash };
+  if (input.tokenHash === null || input.tokenHash === "") return { ok: true, value: undefined };
+  if (input.tokenHashAlgorithm !== undefined && input.tokenHashAlgorithm !== "sha256") return fail(400, "unsupported_token_hash");
+  if (typeof input.tokenHash !== "string" || !/^(?:sha256:)?[a-f0-9]{64}$/i.test(input.tokenHash)) return fail(400, "invalid_token_hash");
+  const hash = input.tokenHash.toLowerCase();
+  return { ok: true, value: hash.startsWith("sha256:") ? hash : `sha256:${hash}` };
+}
+
+function cleanId(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const id = value.trim();
+  return id.length <= CONTROL_PLANE_LIMITS.idLength && /^[a-z0-9][a-z0-9._:-]*$/i.test(id) ? id : undefined;
+}
+
+function cleanLabel(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const label = value.trim().replace(/\s+/g, " ");
+  return label && label.length <= CONTROL_PLANE_LIMITS.labelLength ? label : undefined;
+}
+
+function cleanAgentKind(value: unknown): AgentDraftMetadata["kind"] {
+  return value === "Local agent" || value === "External agent" ? value : "CI agent";
+}
+
+function rawCredentialField(input: Record<string, unknown>): string | undefined {
+  const forbidden = new Set(["token", "apikey", "api_key", "secret", "credential", "password", "authorization"]);
+  return Object.keys(input).find((key) => forbidden.has(key.toLowerCase()));
+}
+
+function viewDraft(draft: AgentDraftMetadata, state: RuntimeState): AgentDraftView {
+  const { tokenHash, ...rest } = draft;
+  const usage = state.usageByAgent[clientIdForAgent(draft.id)] ?? emptyUsage();
+  const view: AgentDraftView = { ...rest, enabledPluginIds: [...draft.enabledPluginIds], tokenHashPresent: Boolean(tokenHash), usage: { ...usage } };
+  if (tokenHash) view.tokenFingerprint = tokenHash.slice(0, 15);
+  return view;
+}
+
+function fail(status: number, error: string, reason?: string): RuntimeStateResult<never> {
+  return { ok: false, status, error, reason };
+}

package/packages/proxy/src/http/agent-router.ts

@@ -0,0 +1,69 @@
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import { chooseByDistribution } from "../../../core/src/routing/distribution.ts";
+import { activeProvider, agentTokensUsed, distributionEligible, providerWeight, type RuntimeState } from "./runtime-state.ts";
+import { clientIdForAgent, type ClientIdentity } from "./client-identity.ts";
+import { providerAllowedForClient } from "./provider-access.ts";
+
+export type RoutingResult = { ok: true; provider: ProviderConfig } | { ok: false; status: number; error: string };
+
+// Resolves the upstream provider for a request and enforces agent access/budget.
+// Priority: explicit agent binding -> distribution mode -> global active provider.
+export function resolveRouting(state: RuntimeState, headers: Headers, client: ClientIdentity): RoutingResult {
+  const budget = state.consumerBudgets[client.id];
+  if (budget && agentTokensUsed(state, client.id) >= budget) return { ok: false, status: 429, error: "consumer_budget" };
+  const agentId = cleanAgentId(headers.get("x-molenkopf-agent"));
+  if (agentId) {
+    const draft = state.agentDrafts.find((item) => item.id === agentId);
+    const agentUsageId = clientIdForAgent(agentId);
+    if (draft?.disabled) return { ok: false, status: 403, error: "agent_disabled" };
+    if (draft?.tokenLimit && agentTokensUsed(state, agentUsageId) >= draft.tokenLimit) {
+      return { ok: false, status: 429, error: "agent_token_limit" };
+    }
+    const configAgent = state.configAgents.find((item) => item.id === agentId);
+    if (configAgent?.enabled === false) return { ok: false, status: 403, error: "agent_disabled" };
+    if (configAgent && (client.source !== "api_key" || client.keyAgentLabel !== agentId)) return { ok: false, status: 403, error: "agent_forbidden" };
+    const pinned = draft?.providerId ?? configAgent?.providerId;
+    if (pinned) {
+      const provider = enabledProvider(state, pinned);
+      if (provider) return requireProviderAccess(client, provider);
+      return { ok: false, status: 409, error: "provider_unavailable" };
+    }
+  }
+  if (state.routingMode === "distribute") {
+    const distributed = distribute(state, client);
+    if (distributed) return { ok: true, provider: distributed };
+    return { ok: false, status: 409, error: "no_eligible_provider" };
+  }
+  return requireProviderAccess(client, activeProvider(state));
+}
+
+function distribute(state: RuntimeState, client: ClientIdentity): ProviderConfig | undefined {
+  const eligible = state.providers.filter((provider) => distributionEligible(provider) && providerAllowedForClient(client, provider.id));
+  const shares = eligible.map((provider) => ({
+    id: provider.id,
+    weight: providerWeight(state, provider.id),
+    usedTokens: tokensFor(state, provider.id)
+  }));
+  const chosen = chooseByDistribution(shares);
+  return eligible.find((provider) => provider.id === chosen);
+}
+
+function tokensFor(state: RuntimeState, id: string): number {
+  const usage = state.usageByProvider[id];
+  return usage ? usage.inputTokens + usage.outputTokens : 0;
+}
+
+function enabledProvider(state: RuntimeState, id: string): ProviderConfig | undefined {
+  return state.providers.find((item) => item.id === id && item.enabled !== false);
+}
+
+function requireProviderAccess(client: ClientIdentity, provider: ProviderConfig): RoutingResult {
+  if (!providerAllowedForClient(client, provider.id)) return { ok: false, status: 403, error: "provider_forbidden" };
+  return { ok: true, provider };
+}
+
+function cleanAgentId(value: string | null): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const id = value.trim();
+  return /^[a-z0-9][a-z0-9._:-]{0,63}$/i.test(id) ? id : undefined;
+}

package/packages/proxy/src/http/audit-view.ts

@@ -0,0 +1,15 @@
+import type { AuditManifest } from "../../../core/src/manifest/audit-store.ts";
+import { auditPath } from "./request-path.ts";
+
+export function auditView(manifest: AuditManifest): AuditManifest {
+  return {
+    ...manifest,
+    path: auditPath(manifest.path),
+    retrievalIds: manifest.retrievalIds.slice(0, 10),
+    warnings: manifest.warnings.slice(0, 10)
+  };
+}
+
+export function auditViews(manifests: AuditManifest[]): AuditManifest[] {
+  return manifests.map(auditView);
+}

package/packages/proxy/src/http/auth-state.ts

@@ -0,0 +1,44 @@
+import { verifySessionPayload } from "../../../core/src/auth/session.ts";
+import type { User } from "../../../core/src/identity/types.ts";
+import type { RuntimeState } from "./runtime-state.ts";
+
+// Auth lives on the Identity store (users/teams). With no password-bearing user,
+// Molenkopf stays in first-run mode until the browser flow creates an admin.
+
+export type AuthUser = User;
+
+export function authRequired(state: RuntimeState): boolean {
+  const users = state.identity?.data.users ?? {};
+  return Object.values(users).some((u) => Boolean(u.password?.hash));
+}
+
+export function currentUser(state: RuntimeState, cookieHeader: string | null): User | undefined {
+  const token = readCookie(cookieHeader, "molenkopf_session");
+  const session = verifySessionPayload(token, state.sessionSecret);
+  const user = session ? state.identity?.getUser(session.userId) : undefined;
+  if (user && (user.sessionVersion ?? 0) !== session?.sessionVersion) return undefined;
+  return user && !user.disabled ? user : undefined;
+}
+
+export function canManage(_state: RuntimeState, user: User | undefined): boolean {
+  return Boolean(user && user.role === "admin");
+}
+
+export function providerAllowed(state: RuntimeState, user: User | undefined, providerId: string): boolean {
+  if (!user || user.role === "admin") return true;
+  return (user.teamIds ?? []).some((id) => {
+    const allowed = state.identity?.getTeam(id)?.allowedProviders;
+    return allowed === "*" || (Array.isArray(allowed) && allowed.includes(providerId));
+  });
+}
+
+export function readCookie(header: string | null, name: string): string | undefined {
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const [k, ...v] = part.trim().split("=");
+    if (k === name) {
+      try { return decodeURIComponent(v.join("=")); } catch { return undefined; }
+    }
+  }
+  return undefined;
+}

package/packages/proxy/src/http/budget-gate.ts

@@ -0,0 +1,45 @@
+import type { Budget } from "../../../core/src/identity/types.ts";
+import { keyCostUsed, keyTokensUsed, orgCostUsed, orgTokensUsed, teamCostUsed, teamTokensUsed, userCostUsed, userTokensUsed, type RuntimeState } from "./runtime-state.ts";
+import type { ClientIdentity } from "./client-identity.ts";
+
+// Hierarchical budget enforcement: key -> user -> team(s) -> org. The first
+// exceeded tier with onExceed="block" wins (429). "warn" tiers are reported but
+// allowed. Periodic budgets read only the active UTC usage bucket.
+
+export type BudgetCheck =
+  | { ok: true; warnings: string[] }
+  | { ok: false; status: 429; error: string; tier: string; scopeId: string; metric: "tokens" | "cost" };
+
+export function checkBudgets(state: RuntimeState, client: ClientIdentity, now = new Date()): BudgetCheck {
+  const identity = state.identity;
+  if (!identity) return { ok: true, warnings: [] };
+  const warnings: string[] = [];
+
+  const tiers: { tier: string; scopeId: string; budget?: Budget; tokens: number; cost: number }[] = [];
+  const keyBudget = client.keyId ? identity.data.keys[client.keyId]?.budget : undefined;
+  if (client.keyId) tiers.push({ tier: "key", scopeId: client.keyId, budget: keyBudget, tokens: keyTokensUsed(state, client.keyId, keyBudget?.period, now), cost: keyCostUsed(state, client.keyId, keyBudget?.period, now) });
+  const userBudget = client.userId ? identity.getUser(client.userId)?.budget : undefined;
+  if (client.userId) tiers.push({ tier: "user", scopeId: client.userId, budget: userBudget, tokens: userTokensUsed(state, client.userId, userBudget?.period, now), cost: userCostUsed(state, client.userId, userBudget?.period, now) });
+  for (const teamId of client.teamIds ?? []) {
+    const budget = identity.getTeam(teamId)?.budget;
+    tiers.push({ tier: "team", scopeId: teamId, budget, tokens: teamTokensUsed(state, teamId, budget?.period, now), cost: teamCostUsed(state, teamId, budget?.period, now) });
+  }
+  const orgBudget = identity.data.orgBudget;
+  tiers.push({ tier: "org", scopeId: "org", budget: orgBudget, tokens: orgTokensUsed(state, orgBudget?.period, now), cost: orgCostUsed(state, orgBudget?.period, now) });
+
+  for (const t of tiers) {
+    const metric = exceededMetric(t);
+    if (!metric) continue;
+    if (t.budget?.onExceed === "warn") { warnings.push(`${t.tier}:${t.scopeId} over ${metric} budget`); continue; }
+    return { ok: false, status: 429, error: `budget_exceeded_${t.tier}`, tier: t.tier, scopeId: t.scopeId, metric };
+  }
+  return { ok: true, warnings };
+}
+
+function exceededMetric(t: { budget?: Budget; tokens: number; cost: number }): "tokens" | "cost" | undefined {
+  const tokenLimit = t.budget?.tokenLimit;
+  if (typeof tokenLimit === "number" && tokenLimit > 0 && t.tokens >= tokenLimit) return "tokens";
+  const costLimit = t.budget?.costLimitEur;
+  if (typeof costLimit === "number" && costLimit > 0 && t.cost >= costLimit) return "cost";
+  return undefined;
+}

package/packages/proxy/src/http/budget-warnings.ts

@@ -0,0 +1,7 @@
+import type { RewriteAudit } from "../../../core/src/pipeline/openai-request-rewriter.ts";
+
+export function withBudgetWarnings(audit: RewriteAudit | undefined, warnings: string[]): RewriteAudit | undefined {
+  if (!warnings.length) return audit;
+  const base = audit ?? { compressedItems: 0, estimatedOriginalTokens: 0, estimatedCompressedTokens: 0, estimatedSavedTokens: 0, redactedSecrets: 0, retrievalIds: [], compressorsUsed: [], warnings: [] };
+  return { ...base, warnings: [...warnings, ...(base.warnings ?? [])] };
+}

package/packages/proxy/src/http/cli-stream-response.ts

@@ -0,0 +1,51 @@
+import type { ServerResponse } from "node:http";
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import { estimateTokens } from "../../../core/src/utils/tokens.ts";
+import { executeCliProvider } from "../runtime/cli-executor.ts";
+import { cliRequest } from "../runtime/cli-request.ts";
+import {
+  isOpenAiResponses,
+  openAiResponsesStreamFailure,
+  openAiResponsesStreamOutput,
+  openAiResponsesStreamStart,
+  wantsStream
+} from "../runtime/cli-provider.ts";
+
+export type CliStreamResult = {
+  status: number;
+  usage?: { inputTokens?: number; outputTokens?: number };
+};
+
+export function canStreamOpenAiCli(path: string, body: string): boolean {
+  return isOpenAiResponses(path) && wantsStream(body);
+}
+
+export async function streamOpenAiCliProvider(
+  provider: ProviderConfig,
+  body: string,
+  requestId: string,
+  res: ServerResponse
+): Promise<CliStreamResult> {
+  const request = cliRequest(body, provider);
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    connection: "keep-alive"
+  });
+  res.write(openAiResponsesStreamStart(requestId, request.responseModel));
+  const keepAlive = setInterval(() => res.write(": keep-alive\n\n"), 10000);
+  keepAlive.unref?.();
+  try {
+    const output = await executeCliProvider(provider, request.prompt, request.runModel);
+    const usage = { inputTokens: estimateTokens(request.prompt), outputTokens: estimateTokens(output) };
+    res.write(openAiResponsesStreamOutput(requestId, request.responseModel, output, usage));
+    res.end("data: [DONE]\n\n");
+    return { status: 200, usage };
+  } catch {
+    res.write(openAiResponsesStreamFailure(requestId, request.responseModel));
+    res.end();
+    return { status: 502 };
+  } finally {
+    clearInterval(keepAlive);
+  }
+}