@bothat-io/molenkopf 0.1.2

package/.env.example

@@ -0,0 +1,2 @@
+# Required for stable signed browser sessions. Change before starting Molenkopf.
+MOLENKOPF_SESSION_SECRET=replace-with-at-least-32-random-characters

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bothat.io and Molenkopf contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+<p align="center">
+  <img src="packages/dashboard/public/molenkopf-logo.png" alt="Molenkopf logo" width="72">
+</p>
+
+# Molenkopf
+
+Molenkopf is a local gateway for API and CLI based coding agents. It is not
+only an OpenAI-compatible API proxy: it also supports Anthropic/Claude API
+traffic and local CLI runtimes such as Claude CLI and Codex CLI. It should
+reduce real transferred context, redact secrets, build local derived memory,
+and write audit manifests without full prompts or responses.
+
+Molenkopf has a fixed core safety pipeline for secret redaction, content classification, safe compression for logs, JSON and stacktraces, local retrieval storage, audit manifests, and redacted SSE events. Optional plugins extend this pipeline; core safety behavior is not toggleable.
+
+Product intent and non-negotiable plugin semantics live in
+`docs/PRODUCT_INTENT.md` and `docs/MOLENKOPF_PLUGIN_API.md`.
+
+## Safety Notice
+
+Do not run Molenkopf blindly with real provider accounts, private repositories,
+browser sessions, or imported runtime credentials. Review `SECURITY.md` first,
+keep source runs on the default loopback bind, and treat `.molenkopf/`, audit
+files, retrieval stores, databases, env files, and runtime-auth profiles as
+sensitive local state.
+
+## Implemented Baseline
+
+Built now:
+
+- Local HTTP proxy bound to `127.0.0.1` by default.
+- Transparent streaming gateway for OpenAI- and Anthropic-compatible traffic via
+  base-URL interception (`OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL`). Responses
+  are streamed through byte-for-byte where possible (SSE, gzip, headers
+  preserved); the agent runs normally and its context stream flows through
+  Molenkopf.
+- Transparent by default: the request body is never altered unless a transform plugin is explicitly enabled. Compression is opt-in and only reduces structured/operational content (json/log/stacktrace/shell); prose, markdown, source code, and diffs pass through untouched.
+- Per-agent multi-account routing: each agent (`x-molenkopf-agent`) routes to its bound provider/account; config `profiles`/`agents` resolve to providers.
+- Real token accounting: upstream `usage` is read from the provider response and recorded as
+  real input/output tokens (not only a chars/4 estimate).
+- Text-derived memory graph: concepts (files, symbols, error types) are extracted from the
+  real redacted transferred text into a bounded co-occurrence graph.
+- Static pipeline with request IDs, redaction, classification, compression, retrieval, audit, SSE events, and upstream routing.
+- Local API under `/__molenkopf/*`: bootstrap endpoints for health, session
+  status, and first-run admin creation, user-scoped usage/key endpoints, and admin-only
+  provider/plugin/agent/stats/events/config metadata plus retention purge.
+- Dashboard shell served at `/__molenkopf/dashboard` with Overview and Admin
+  views backed by an isolated React/Vite dashboard package. Dedicated Providers,
+  Plugins, Requests, Audit, Agents, and Settings views are planned.
+- Plugin pages are local HTML surfaces under `/__molenkopf/plugins/:id/page`; context compression and memory graph pages read scoped plugin data endpoints and show explicit load errors instead of fake empty workspaces.
+- The context compression plugin must expose safe token accounting for real transferred context only. Empty states must not show placeholder pressure or fake savings. Usage notes: `docs/CONTEXT_COMPRESSION_PLUGIN_README.md`.
+- Practical dashboard and proxy connection guide: `docs/MOLENKOPF_USAGE.md`.
+- JSON config startup target for providers, agents, and plugin policies:
+  `docs/MOLENKOPF_JSON_CONFIG_PLAN.md`.
+- Multi-provider env setup: `docs/MOLENKOPF_PROVIDER_ENV.md`.
+- Root `/` redirects to the local dashboard; upstream API traffic stays on `/v1/...`.
+- Claude/Anthropic-compatible target resolution through `ANTHROPIC_BASE_URL`; Molenkopf-owned CLI runtime bridging exists for local `claude` and `codex` child processes.
+- Profile routing primitives for fixed, manual, and failover routing with env credentials, budgets, and health summaries.
+- Local plugin SDK with explicit permissions and remote plugin loading disabled.
+- CI mode primitives for PR context packing and audit artifacts.
+
+Explicitly not connected:
+
+- Remote issue-tracker integration.
+- Remote plugin installation.
+- Credential-file scanning or config-file credential storage. Runtime auth import
+  stores credentials only when the operator explicitly imports a local profile.
+
+## Security Model
+
+Core and proxy use Node.js built-ins only. Molenkopf API keys are stored as hashes, imported runtime auth is kept in isolated local profile directories, and Local API responses hide provider credentials. Proxy traffic on `/v1/...` requires a valid Molenkopf API key. The default upstream route can forward incoming auth headers only when the selected profile requires it; configured provider profiles strip incoming client auth and inject the server-side credential at the forwarding boundary. Prompts and responses are not logged in full. Source code and diffs pass through in safe mode.
+
+Before the first admin exists, only health, session status, and browser first-run
+admin creation are usable. After setup, Local API metadata is role-gated: normal
+users get scoped usage and key data, while provider, plugin, agent, routing,
+stats, events, and retention endpoints are admin-only.
+
+Use `--allow-public-bind` only when you intentionally want to bind outside
+localhost. If Docker is published publicly before an admin exists, the first-run
+screen is reachable there until the first admin is created.
+
+## Control Plane Usage
+
+Open `http://127.0.0.1:8787/__molenkopf/dashboard` after starting Molenkopf.
+Root `/` redirects there, while upstream agent traffic still uses `/v1/...`.
+
+Every `/v1/...` proxy request must present a valid Molenkopf API key. Use
+`Authorization: Bearer mk_...` when Molenkopf supplies provider credentials. If
+the client must also forward an upstream `Authorization` header, put the
+Molenkopf key in `x-molenkopf-token: mk_...`; Molenkopf strips that header
+before forwarding upstream.
+
+```text
+Authorization: Bearer mk_...
+```
+
+`x-molenkopf-agent` is optional local request metadata. It may select an
+explicit agent binding only when that binding is already allowed for the
+authenticated key, team, and provider policy; otherwise the request fails
+closed.
+
+Manual provider switching happens in the Admin provider section or by posting `{ "id": "openai-env" }` to `/__molenkopf/providers/select`. Explicit provider profiles, API-key scopes, team allowlists, and routing mode are enforced before forwarding; manual selection remains the default route when no explicit profile is attached.
+
+Multiple provider profiles can be declared with `molenkopf.config.json` or
+`MOLENKOPF_PROVIDER_IDS`. JSON profiles must reference credentials with
+`auth.credentialRef` such as `env:OPENAI_API_KEY`; inline credentials are
+rejected in file config. Local API responses hide credential values and show
+only `credentialRef` plus configured state. Selected configured profiles inject
+their credential at the forwarding boundary.
+
+Users, teams, projects, and Molenkopf API keys are managed in the Dashboard.
+Overview is the signed-in user's status, usage, teams, members, and project-key
+surface. Admin contains provider, plugin, user, team, and system controls.
+Projects are required key/workload labels; teams carry provider policy and usage
+scope. See `docs/MOLENKOPF_USAGE.md` for the workflow and Local API endpoints.
+
+Plugin toggles happen in the Admin plugin section or by posting `{ "id": "context-compressor-plugin", "enabled": false }` to `/__molenkopf/plugins/toggle`. Plugins are optional extensions; core safety, storage, audit, event, and routing code is not exposed as plugins and cannot be disabled through plugin controls. Remote plugin loading is disabled.
+
+Agent drafts are stored as local proxy metadata through `/__molenkopf/agents/draft`; raw token fields are rejected and only `tokenHash` is accepted. The dashboard keeps a `localStorage` fallback if the local API is unavailable. These drafts are routing metadata, not provider credentials.
+
+For a step-by-step local setup and test flow, read `docs/MOLENKOPF_USAGE.md`.
+
+Plugin pages open in standalone windows from `/__molenkopf/plugins/context-compressor-plugin/page` and `/__molenkopf/plugins/obsidian-graph-plugin/page`. The graph workspace is derived from safe request metadata and redacted transferred text. Context and graph pages group by project/key where available and surface plugin-data failures explicitly.
+
+## Commands
+Install from npm with Node.js 24 or newer:
+
+```bash
+npm install -g @bothat-io/molenkopf
+node -e "require('node:fs').writeFileSync('.env','MOLENKOPF_SESSION_SECRET='+require('node:crypto').randomBytes(32).toString('hex')+'\n')"
+molenkopf proxy
+```
+
+Quick Docker start on the Docker host:
+
+```bash
+cp .env.example .env
+# Edit .env and set a unique MOLENKOPF_SESSION_SECRET.
+docker pull ghcr.io/bothat-io/molenkopf:latest
+docker run --rm \
+  --env-file .env \
+  -p 127.0.0.1:8787:8787 \
+  -v molenkopf-data:/data \
+  ghcr.io/bothat-io/molenkopf:latest
+```
+
+Open `http://127.0.0.1:8787/` and create the first admin user. The Docker
+quickstart binds Molenkopf to `127.0.0.1` on the host for local use; do not
+publish the port publicly before admin setup and deployment security are done.
+Docker requires `--env-file .env`; admin users are created only in the browser.
+
+Use `docs/DEPLOYMENT.md` when you need a different port or non-loopback access.
+
+For local development, use a source checkout:
+
+```bash
+npm run bootstrap
+cp .env.example .env
+# Edit .env and set a unique MOLENKOPF_SESSION_SECRET.
+npm run dev
+```
+
+## Connect A Client
+
+Use Molenkopf as the OpenAI-compatible base URL:
+
+```text
+http://127.0.0.1:8787/v1
+```
+
+Authenticate proxy traffic with a Molenkopf API key:
+
+```text
+Authorization: Bearer mk_...
+```
+
+If your client also sends an upstream provider credential in `Authorization`,
+send the Molenkopf key separately:
+
+```text
+x-molenkopf-token: mk_...
+x-molenkopf-agent: codex-local
+```
+
+These local headers are stripped before upstream forwarding. See
+`docs/MOLENKOPF_USAGE.md` for a concrete `curl` request, provider setup, and
+dashboard checks.
+
+## Limitations
+
+Provider token accounting uses upstream `usage` when present and falls back to bounded estimates for local compression pressure. JSON summaries are readable summaries, not guaranteed valid JSON. v0.1 does not retry provider failures automatically and request-side safe compression remains opt-in.
+
+Be careful with secrets and private repositories. Molenkopf reduces accidental
+exposure, but local retrieval stores still contain bounded redacted excerpts.
+They do not support full-original recovery and should be treated as sensitive
+local artifacts.
+
+## License
+
+MIT License. Copyright (c) 2026 bothat.io and Molenkopf contributors.

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security
+
+Molenkopf is a local gateway for coding-agent traffic. Do not run it blindly on
+a workstation with real provider accounts, private repositories, browser
+sessions, or imported runtime credentials. Review the configuration and runtime
+flags first.
+
+## Safe Use
+
+- Start on loopback only unless you intentionally need network access.
+- Set a unique `MOLENKOPF_SESSION_SECRET` before starting Molenkopf. Do not
+  commit `.env` files or bake secrets into Docker images.
+- Do not use `--allow-public-bind` unless you intentionally need network access.
+- First-run bootstrap is intentionally narrow. Before an admin exists, only
+  health, session status, and first-run admin creation are usable.
+- After setup, provider, plugin, routing, agent, stats, event, config metadata,
+  and retention purge endpoints are admin-only. Normal users receive scoped
+  usage and key data.
+- Treat `.molenkopf/`, audit manifests, retrieval stores, SQLite
+  files, runtime-auth profiles, and env files as sensitive local state.
+- Do not commit provider keys, imported `auth.json`, Claude credentials,
+  cookies, database files, audit files, retrieval stores, or screenshots with
+  secrets.
+- Prefer environment credential references or a private local config file over
+  UI-entered provider credentials. File config rejects inline raw credentials.
+- Read Docker and deployment settings before exposing a container port.
+
+## Reports
+
+When the repository is hosted on GitHub, prefer GitHub private vulnerability
+reporting if it is enabled. If only public issues are available, post a
+sanitized reproduction only and keep sensitive material private.
+
+Do not open a public issue that contains tokens, prompts, responses, auth files,
+provider credentials, cookies, or private repository content. Redact the
+material first and include only the minimal reproduction details.

package/bin/launcher.js

@@ -0,0 +1,76 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, cpSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const sourceRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const signals = ["SIGINT", "SIGTERM"];
+
+export function runLauncher(args = process.argv.slice(2), options = {}) {
+  const root = options.sourceRoot ?? sourceRoot;
+  const exit = options.exit ?? process.exit;
+  const signalSelf = options.signalSelf ?? ((name) => process.kill(process.pid, name));
+  const runtimeRoot = runtimeRootFor(root);
+  const entry = join(runtimeRoot, "packages", "proxy", "src", "cli", "main.ts");
+  if (!existsSync(entry)) throw new Error(`missing CLI entrypoint: ${entry}`);
+  const child = spawn(process.execPath, ["--experimental-strip-types", "--experimental-sqlite", "--disable-warning=ExperimentalWarning", entry, ...args], { stdio: options.stdio ?? "inherit" });
+  let closeRequested = false;
+  let finished = false;
+  let forced = false;
+  let requestedSignal = "";
+  let graceTimer;
+
+  const cleanup = () => cleanupRuntime(runtimeRoot, root);
+  const finish = (code, signal) => {
+    if (finished) return;
+    finished = true;
+    if (graceTimer) clearTimeout(graceTimer);
+    for (const name of signals) process.removeListener(name, handlers[name]);
+    cleanup();
+    const finalSignal = requestedSignal || signal;
+    if (finalSignal && process.platform !== "win32") signalSelf(finalSignal);
+    exit(code ?? (forced ? 1 : 1));
+  };
+  const handlers = Object.fromEntries(signals.map((name) => [name, () => {
+    if (closeRequested) return;
+    closeRequested = true;
+    requestedSignal = name;
+    child.kill(name);
+    graceTimer = setTimeout(() => {
+      forced = true;
+      child.kill("SIGKILL");
+    }, Number(process.env.MOLENKOPF_LAUNCHER_GRACE_MS ?? 5000)).unref();
+  }]));
+
+  child.on("close", finish);
+  child.on("error", (error) => {
+    console.error(error.message);
+    finish(1, null);
+  });
+  for (const name of signals) process.once(name, handlers[name]);
+}
+
+export function runtimeRootFor(root) {
+  if (!root.split(/[\\/]/).includes("node_modules")) return root;
+  const prefix = `molenkopf-cli-${createHash("sha256").update(root).digest("hex").slice(0, 12)}-`;
+  const runtimeRoot = mkdtempSync(join(tmpdir(), prefix));
+  try {
+    try { chmodSync(runtimeRoot, 0o700); } catch { /* Windows ACLs are inherited. */ }
+    for (const name of ["package.json", "packages", "bin"]) cpSync(join(root, name), join(runtimeRoot, name), { recursive: true });
+    return runtimeRoot;
+  } catch (error) {
+    cleanupRuntime(runtimeRoot, root);
+    throw error;
+  }
+}
+
+export function cleanupRuntime(path, root = sourceRoot) {
+  if (path === root) return;
+  try {
+    rmSync(path, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+  } catch (error) {
+    console.error(`cleanup warning: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

package/bin/molenkopf.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runLauncher } from "./launcher.js";
+
+runLauncher();

package/docs/DEPLOYMENT.md

@@ -0,0 +1,104 @@
+# Deployment
+
+This document defines the current production deployment target for Molenkopf.
+Routes, flags, and environment variables use Molenkopf names.
+
+## Local Modes
+
+- Development: `npm run dev`
+  - Binds `127.0.0.1:8787`
+  - Uses `.molenkopf/dev`
+  - Starts the Vite dashboard unless `MOLENKOPF_DASHBOARD_DEV=0`
+- Test server: `npm run serve:test`
+  - Binds `127.0.0.1:8798`
+  - Uses `.molenkopf/test`
+- Local prod smoke: `npm run prod`
+  - Builds the dashboard
+  - Binds `127.0.0.1:8787`
+  - Uses `.molenkopf/prod`
+
+`npm run prod` is a local production profile with durable local state. Override
+it with `MOLENKOPF_PROD_PORT`, `MOLENKOPF_PROD_HOST`, `MOLENKOPF_PROD_TARGET`,
+and `MOLENKOPF_PROD_DATA_DIR` when needed.
+
+## Docker Build
+
+Build after the release source tree is clean:
+
+```powershell
+docker build --pull -t molenkopf:local .
+```
+
+The Docker image builds dashboard assets in a separate stage and copies only the
+runtime source, plugin pages, root manifests, and built dashboard assets into the
+final image. The final image also carries the MIT license notice. Core and Proxy
+keep Node built-ins only.
+
+## Docker Run
+
+The published image listens on `0.0.0.0:8787` inside the container so Docker port
+publishing works. For local use, publish it only to host loopback:
+
+```powershell
+Copy-Item .env.example .env
+# Edit .env and set a unique MOLENKOPF_SESSION_SECRET.
+
+docker run --rm `
+  --env-file .env `
+  -p 127.0.0.1:8787:8787 `
+  -v molenkopf-data:/data `
+  molenkopf:local
+```
+
+Open `http://127.0.0.1:8787/` and create the first admin in the browser. Do not
+seed admin usernames or passwords through environment variables. Docker starts
+require a valid `MOLENKOPF_SESSION_SECRET`; copy `.env.example` to `.env`,
+change the value, and pass it with `--env-file .env`. Docker does not
+automatically read a host `.env` file. Configure provider credentials through
+environment variables or a mounted config file that uses credential references.
+Do not bake provider keys, imported runtime auth, `.env`, or local data into the
+image.
+
+## Data Volume
+
+Mount one durable volume at `/data`. It contains SQLite files, audit manifests,
+retrieval store files, runtime settings, and imported runtime profiles. Treat the
+volume as sensitive local state.
+
+On POSIX filesystems Molenkopf creates and repairs sensitive state directories as
+`0700` and sensitive files as `0600`, including SQLite, audit, retrieval, runtime
+settings, and imported runtime auth/profile files. Windows does not expose full
+POSIX permission bits through Node, so protect the data directory with Windows
+ACLs or a private user profile.
+
+Admins can manually purge audit and retrieval data with
+`POST /__molenkopf/retention/purge` and an explicit `scope` of `audit`,
+`retrieval`, or `all`. TTLs, quotas, pagination, and project-scoped retention
+policies are still future work.
+
+Current constraint: one writer only. Do not run multiple containers against the
+same SQLite volume.
+
+## Security Gates
+
+- Non-loopback source binds require `--allow-public-bind`.
+- `MOLENKOPF_SESSION_SECRET` is required for every server start.
+- `/v1/...` proxy APIs require a valid Molenkopf API key.
+- `x-molenkopf-token` carries Molenkopf auth when a client must keep
+  `Authorization` for the upstream provider; it is stripped before forwarding.
+- `/__molenkopf/health` is public.
+- Before first admin setup, only health, session status, and first-run admin
+  creation are usable.
+- Control-plane APIs require auth after an admin exists; provider, plugin,
+  routing, agent, stats, event, config metadata, and retention endpoints are
+  admin-only.
+- Full prompts, full responses, provider credentials, cookies, auth headers, and
+  imported auth JSON must never appear in local API responses, plugin data, logs,
+  audit files, or docs.
+
+## Not Supported Yet
+
+- Dockerized host Claude/Codex CLI runtimes by default.
+- Multi-replica deployment with one SQLite volume.
+- Remote plugin installation.
+- Obsidian vault writes without dry-run and path guards.

package/docs/MOLENKOPF_PLUGIN_API.md

@@ -0,0 +1,113 @@
+# Molenkopf Plugin API
+
+Molenkopf plugins are optional local extensions. Core safety, credential
+handling, routing enforcement, audit invariants, and request redaction are core
+responsibilities and are not exposed as plugins.
+
+Each plugin is a TypeScript module at
+`packages/plugins/<plugin-id>/plugin.ts`. It exports a static `descriptor` and
+an executable `plugin` module.
+
+The TypeScript descriptor remains the source of truth for permissions,
+readable scopes, traffic mutations, workspace data, and default enabled state.
+Runtime hook results are accepted only when the descriptor allows the matching
+mutation.
+Built-in local plugin modules are imported by the proxy from a static module
+registry. Remote or downloaded plugin code is disabled.
+
+## Descriptor
+
+```ts
+import type { PluginDescriptor } from "../../core/src/plugins/plugin-descriptor.ts";
+
+export const descriptor: PluginDescriptor = {
+  id: "context-compressor-plugin",
+  name: "context-compressor-plugin",
+  type: "transformer",
+  category: "compression",
+  description: "Compresses large safe context and keeps bounded redacted excerpts locally.",
+  traffic: { reads: ["redacted-body", "audit"], mutates: ["transform"] },
+  permissions: ["body:read", "body:write", "audit:read", "audit:write"],
+  hooks: ["request:body:rewrite", "audit:manifest", "workspace:local-page"],
+  toggle: { defaultEnabled: false, canDisable: true },
+  modulePath: "plugin.ts"
+};
+```
+
+`canDisable` is always `true` for visible plugins. If a feature is required for
+Molenkopf to run safely, it belongs in Core instead of the plugin catalog.
+
+## TypeScript Module
+
+The public hook shape lives in `packages/core/src/plugins/plugin-api.ts`.
+
+```ts
+import type { MolenkopfPluginModule } from "../../core/src/plugins/plugin-api.ts";
+
+export const plugin: MolenkopfPluginModule = {
+  onBoot(ctx) {
+    ctx.note("plugin booted");
+  },
+  onStart(ctx) {
+    ctx.note("plugin started");
+  },
+  onRequest(ctx) {
+    return { body: ctx.body.toUpperCase(), notes: ["rewrote request"] };
+  },
+  getData(ctx) {
+    return { plugin: ctx.plugin, requests: ctx.manifests.length };
+  }
+};
+```
+
+Available hooks:
+
+| Hook | Purpose |
+| --- | --- |
+| `onBoot` | Prepare local plugin state before the proxy listens. |
+| `onStart` | Initialize enabled plugin work after the proxy listens. |
+| `onEnable` | React to an admin enabling the plugin. |
+| `onDisable` | React to an admin disabling the plugin. |
+| `onRequest` | Inspect or transform a redacted request. |
+| `onAudit` | Observe redacted audit manifests. |
+| `onEvent` | Observe or emit local lifecycle events. |
+| `getData` | Serve scoped workspace data. |
+| `onStop` | Flush local state before shutdown. |
+
+`getData` receives already-scoped, already-redacted audit manifests plus safe
+workspace context such as the plugin view, declared scopes, and the memory graph
+when available. The central proxy does not contain plugin-specific metrics.
+
+## Request Results
+
+`onRequest` returns a result object instead of mutating global state directly.
+The runner applies only the allowed fields:
+
+```ts
+type PluginRequestResult = {
+  body?: string;
+  providerId?: string;
+  block?: { status: number; error: string };
+  notes?: string[];
+  redactedSecrets?: number;
+  compressedItems?: number;
+  savedTokens?: number;
+  retrievalIds?: string[];
+  compressorsUsed?: string[];
+};
+```
+
+If a plugin returns a body rewrite without `traffic.mutates` containing
+`transform`, `mask`, or `augment-context`, the runner restores the previous
+body and blocks with `plugin_capability_violation`.
+
+## Invariants
+
+- Remote plugin loading is disabled.
+- Core redaction runs before optional request plugins.
+- Full prompts, full responses, credential values, cookies, and authorization
+  headers must not appear in plugin data, audit data, dashboard data, events, or
+  logs.
+- Provider reroutes still pass provider, team, and key policy checks. Project is
+  key-level attribution, not a provider access layer.
+- A disabled plugin must leave Molenkopf usable.