@clawdreyhepburn/carapace 0.4.0 → 0.4.2

package/dist/policy-source.d.ts

@@ -3,8 +3,13 @@
  * so that OVID-ME can query the effective policy ceiling.
  */
 /**
- * Interface matching @clawdreyhepburn/ovid-me's PolicySource.
- * Defined locally to avoid circular dependencies.
+ * Must match @clawdreyhepburn/ovid-me PolicySource interface.
+ *
+ * Kept as a local copy because ovid-me pulls in native dependencies
+ * (better-sqlite3) that would bloat Carapace's install. A type
+ * compatibility test in test/policy-source.test.ts guards against drift.
+ *
+ * Canonical definition: ovid-me/src/config.ts
  */
 export interface PolicySource {
     getEffectivePolicy(principal: string): Promise<string | null>;

package/dist/policy-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy-source.js","sourceRoot":"","sources":["../src/policy-source.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAUlC;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACvB,SAAS,CAAS;IAE1B,YAAY,SAAkB;QAC5B,IAAI,CAAC,SAAS,GAAG,CAAC,SAAS,IAAI,2BAA2B,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,UAAkB;QACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QAE7C,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC5E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAChF,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"policy-source.js","sourceRoot":"","sources":["../src/policy-source.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAelC;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACvB,SAAS,CAAS;IAE1B,YAAY,SAAkB;QAC5B,IAAI,CAAC,SAAS,GAAG,CAAC,SAAS,IAAI,2BAA2B,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,UAAkB;QACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QAE7C,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC5E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAChF,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/openclaw.plugin.json

@@ -2,10 +2,10 @@
   "id": "carapace",
   "name": "Carapace",
   "description": "Immutable policy boundaries for MCP tool access. Your agent's exoskeleton.",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "configSchema": {
     "type": "object",
-    "additionalProperties": false,
+    "additionalProperties": true,
     "properties": {
       "guiPort": {
         "type": "number",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdreyhepburn/carapace",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Immutable policy boundaries for MCP tool access. Powered by Cedar + Cedarling WASM.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cedar-engine-cedarling.ts

@@ -150,18 +150,14 @@ export class CedarlingEngine {
       const typeMatch = request.resource.match(/^(?:\w+::)?(\w+)::/);
       if (typeMatch) resourceEntityType = typeMatch[1];
 
-      const cedarContext: Record<string, unknown> = { ...(request.context ?? {}) };
-
-      const effectivePrincipalId = principalId;
-
       const result = await this.cedarling.authorize_unsigned({
         principals: [
           {
             cedar_entity_mapping: {
               entity_type: `${this.namespace}::${this.agentEntityType}`,
-              id: effectivePrincipalId,
+              id: principalId,
             },
-            name: effectivePrincipalId,
+            name: principalId,
           },
         ],
         action: `${this.namespace}::Action::"${actionName}"`,
@@ -172,7 +168,7 @@ export class CedarlingEngine {
           },
           ...(request.context ?? {}),
         },
-        context: cedarContext,
+        context: request.context ?? {},
       });
 
       const decision = result.decision ? "allow" : "deny";
@@ -500,38 +496,6 @@ export class CedarlingEngine {
               },
             },
           },
-          Agent: {
-            shape: {
-              type: "Record",
-              attributes: {
-                role: {
-                  type: "EntityOrCommon",
-                  name: "String",
-                  required: false,
-                },
-                parentChain: {
-                  type: "Set",
-                  element: { type: "EntityOrCommon", name: "String" },
-                  required: false,
-                },
-                issuer: {
-                  type: "EntityOrCommon",
-                  name: "String",
-                  required: false,
-                },
-                depth: {
-                  type: "EntityOrCommon",
-                  name: "Long",
-                  required: false,
-                },
-                attestation_proven: {
-                  type: "EntityOrCommon",
-                  name: "Boolean",
-                  required: false,
-                },
-              },
-            },
-          },
           Tool: {
             shape: {
               type: "Record",
@@ -546,21 +510,6 @@ export class CedarlingEngine {
                   name: "String",
                   required: false,
                 },
-                project: {
-                  type: "EntityOrCommon",
-                  name: "String",
-                  required: false,
-                },
-                team: {
-                  type: "EntityOrCommon",
-                  name: "String",
-                  required: false,
-                },
-                domain: {
-                  type: "EntityOrCommon",
-                  name: "String",
-                  required: false,
-                },
               },
             },
           },
@@ -607,17 +556,9 @@ export class CedarlingEngine {
         actions: {
           call_tool: {
             appliesTo: {
-              principalTypes: [this.agentEntityType, "Agent"],
+              principalTypes: [this.agentEntityType],
               resourceTypes: ["Tool"],
-              context: {
-                type: "Record",
-                attributes: {
-                  agent_role: { type: "EntityOrCommon", name: "String", required: false },
-                  agent_issuer: { type: "EntityOrCommon", name: "String", required: false },
-                  agent_depth: { type: "EntityOrCommon", name: "Long", required: false },
-                  agent_attestation_proven: { type: "EntityOrCommon", name: "Boolean", required: false },
-                },
-              },
+              context: { type: "Record", attributes: {} },
             },
           },
           list_tools: {

package/src/gui/html.ts

@@ -339,6 +339,13 @@ export function guiHtml(): string {
     </div>
   </header>
 
+  <div id="not-enforcing-banner" style="display:none; background:#e8a735; color:#1a1a1a; padding:1rem 1.5rem; font-size:0.95rem; text-align:center; font-weight:500; line-height:1.6;">
+    ⚠️ Carapace is loaded but <strong>not enforcing</strong>. No tools are gated and the LLM proxy is disabled.
+    Your agent is running without policy protection.<br>
+    To activate, run these two commands in your terminal:<br>
+    <code style="background:rgba(0,0,0,0.1); padding:0.3em 0.6em; border-radius:3px; display:inline-block; margin-top:0.3rem;">openclaw carapace setup && openclaw gateway restart</code>
+  </div>
+
   <div class="container">
     <div id="servers-section">
       <h2>MCP Servers</h2>
@@ -533,6 +540,13 @@ export function guiHtml(): string {
     function render() {
       document.getElementById('total-count').textContent = state.toolCount ?? state.tools.length;
       document.getElementById('enabled-count').textContent = state.enabledCount ?? state.tools.filter(t => t.enabled).length;
+
+      // Show/hide not-enforcing banner
+      const banner = document.getElementById('not-enforcing-banner');
+      if (banner) {
+        banner.style.display = state.notEnforcing ? 'block' : 'none';
+      }
+
       renderServers();
       renderTools();
       renderPolicies();

package/src/gui/server.ts

@@ -15,6 +15,7 @@ interface GuiOpts {
   aggregator: McpAggregator;
   cedar: CedarEngineInterface;
   logger: Logger;
+  proxyEnabled?: boolean;
 }
 
 export class ControlGui {
@@ -23,14 +24,14 @@ export class ControlGui {
   private cedar: CedarEngineInterface;
   private logger: Logger;
   private server: Server | null = null;
-
+  private proxyEnabled: boolean;
 
   constructor(opts: GuiOpts) {
     this.port = opts.port;
     this.aggregator = opts.aggregator;
     this.cedar = opts.cedar;
     this.logger = opts.logger;
-
+    this.proxyEnabled = opts.proxyEnabled ?? false;
   }
 
   async start(): Promise<void> {
@@ -62,13 +63,16 @@ export class ControlGui {
       if (url.pathname === "/api/status" && req.method === "GET") {
         const servers = this.aggregator.getServerStatus();
         const tools = this.aggregator.listTools();
+        const enabledCount = tools.filter((t) => t.enabled).length;
         this.json(res, {
           servers,
           tools,
           policies: this.cedar.getPolicies(),
           toolCount: tools.length,
-          enabledCount: tools.filter((t) => t.enabled).length,
+          enabledCount,
           defaultPolicy: this.cedar.getDefaultPolicy?.() ?? "allow-all",
+          proxyEnabled: this.proxyEnabled,
+          notEnforcing: !this.proxyEnabled && enabledCount === 0,
         });
         return;
       }
@@ -136,21 +140,6 @@ export class ControlGui {
         return;
       }
 
-      if (url.pathname === "/api/agents" && req.method === "GET") {
-        // Agent hierarchy removed — see @clawdreyhepburn/ovid-me for per-agent mandates
-        this.json(res, []);
-        return;
-      }
-
-      if (url.pathname === "/api/policy-source" && req.method === "GET") {
-        // Return all Cedar policies (deployment-wide ceiling)
-        const policies = this.cedar.getPolicies();
-        const policyText = policies.map(p => p.raw).join("\n\n");
-        res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
-        res.end(policyText || "# No policies defined\n");
-        return;
-      }
-
       // --- GUI ---
       if (url.pathname === "/" || url.pathname === "/index.html") {
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });

package/src/index.ts

@@ -11,8 +11,6 @@ import { ControlGui } from "./gui/server.js";
 import { LlmProxy } from "./llm-proxy.js";
 import type { PluginConfig } from "./types.js";
 
-export { CarapacePolicySource } from "./policy-source.js";
-export type { PolicySource } from "./policy-source.js";
 export const id = "carapace";
 export const name = "Carapace";
 
@@ -43,6 +41,46 @@ interface OpenClawPluginApi {
   registerGatewayMethod?(name: string, handler: (ctx: { respond: (ok: boolean, data: any) => void }) => void): void;
 }
 
+/**
+ * Build upstream config from either string or object format.
+ * String format: proxy.upstream = "https://api.anthropic.com", proxy.apiKey = "sk-..."
+ * Object format: proxy.upstream = { anthropic: { url, apiKey }, openai: { url, apiKey } }
+ */
+function buildUpstreamConfig(proxyConfig: NonNullable<PluginConfig["proxy"]>): {
+  anthropic?: { url: string; apiKey: string };
+  openai?: { url: string; apiKey: string };
+} {
+  const upstream = proxyConfig.upstream;
+
+  if (!upstream) return {};
+
+  // String format: single upstream URL + flat apiKey
+  if (typeof upstream === "string") {
+    const apiKey = proxyConfig.apiKey ?? "";
+    const url = upstream;
+    // Guess provider from URL
+    if (url.includes("anthropic")) {
+      return { anthropic: { url, apiKey } };
+    } else if (url.includes("openai")) {
+      return { openai: { url, apiKey } };
+    }
+    // Default to anthropic
+    return { anthropic: { url, apiKey } };
+  }
+
+  // Object format: multi-provider
+  return {
+    anthropic: upstream.anthropic ? {
+      url: upstream.anthropic.url ?? "https://api.anthropic.com",
+      apiKey: upstream.anthropic.apiKey,
+    } : undefined,
+    openai: upstream.openai ? {
+      url: upstream.openai.url ?? "https://api.openai.com",
+      apiKey: upstream.openai.apiKey,
+    } : undefined,
+  };
+}
+
 export default function register(api: OpenClawPluginApi) {
   const config: PluginConfig = api.pluginConfig ?? {};
   const logger = api.logger;
@@ -60,27 +98,20 @@ export default function register(api: OpenClawPluginApi) {
     logger,
   });
 
+  // --- LLM Proxy: intercept tool calls at the API level ---
+  const proxyConfig = config.proxy;
+
   const gui = new ControlGui({
     port: config.guiPort ?? 19820,
     aggregator,
     cedar,
     logger,
+    proxyEnabled: !!proxyConfig?.enabled,
   });
 
-  // --- LLM Proxy: intercept tool calls at the API level ---
-  const proxyConfig = config.proxy;
-  const proxy = proxyConfig?.enabled ? new LlmProxy({
+  let proxy: LlmProxy | null = proxyConfig?.enabled ? new LlmProxy({
     port: proxyConfig.port ?? 19821,
-    upstream: {
-      anthropic: proxyConfig.upstream?.anthropic ? {
-        url: proxyConfig.upstream.anthropic.url ?? "https://api.anthropic.com",
-        apiKey: proxyConfig.upstream.anthropic.apiKey,
-      } : undefined,
-      openai: proxyConfig.upstream?.openai ? {
-        url: proxyConfig.upstream.openai.url ?? "https://api.openai.com",
-        apiKey: proxyConfig.upstream.openai.apiKey,
-      } : undefined,
-    },
+    upstream: buildUpstreamConfig(proxyConfig),
     cedar,
     logger,
   }) : null;
@@ -132,6 +163,17 @@ export default function register(api: OpenClawPluginApi) {
     return { patched: toAdd, alreadyDenied };
   }
 
+  function backupConfig(): void {
+    const { readFileSync, writeFileSync, existsSync, copyFileSync } = require("node:fs");
+    const { join } = require("node:path");
+    const { homedir } = require("node:os");
+    const configPath = join(homedir(), ".openclaw", "openclaw.json");
+    if (existsSync(configPath)) {
+      const backupPath = configPath + ".carapace-backup";
+      copyFileSync(configPath, backupPath);
+    }
+  }
+
   function patchConfigProxyBaseUrl(): { patched: string[]; alreadySet: string[] } {
     const { readFileSync, writeFileSync, existsSync } = require("node:fs");
     const { join } = require("node:path");
@@ -144,28 +186,45 @@ export default function register(api: OpenClawPluginApi) {
     const port = config.proxy?.port ?? 19821;
     const proxyUrl = `http://127.0.0.1:${port}`;
 
-    // Figure out which providers have upstream keys configured
-    const providers: string[] = [];
-    if (config.proxy?.upstream?.anthropic) providers.push("anthropic");
-    if (config.proxy?.upstream?.openai) providers.push("openai");
+    // Figure out which providers are configured
+    const upstreamConfig = proxyConfig ? buildUpstreamConfig(proxyConfig) : {};
+    const providers = Object.keys(upstreamConfig).filter(
+      (k) => upstreamConfig[k as keyof typeof upstreamConfig],
+    );
 
     const patched: string[] = [];
     const alreadySet: string[] = [];
 
     if (!cfg.models) cfg.models = {};
+    if (!cfg.models.mode) cfg.models.mode = "merge";
     if (!cfg.models.providers) cfg.models.providers = {};
 
     for (const provider of providers) {
       if (!cfg.models.providers[provider]) cfg.models.providers[provider] = {};
+      // Ensure models array exists (OpenClaw requires it)
+      if (!Array.isArray(cfg.models.providers[provider].models)) {
+        cfg.models.providers[provider].models = [];
+      }
       if (cfg.models.providers[provider].baseUrl === proxyUrl) {
         alreadySet.push(provider);
       } else {
+        // Store original baseUrl for clean revert
+        if (cfg.models.providers[provider].baseUrl && cfg.models.providers[provider].baseUrl !== proxyUrl) {
+          cfg.models.providers[provider]._originalBaseUrl = cfg.models.providers[provider].baseUrl;
+        }
         cfg.models.providers[provider].baseUrl = proxyUrl;
         patched.push(provider);
       }
     }
 
-    if (patched.length > 0) {
+    // Ensure plugin config is under plugins.entries.carapace.config
+    if (!cfg.plugins) cfg.plugins = {};
+    if (!cfg.plugins.entries) cfg.plugins.entries = {};
+    if (!cfg.plugins.entries.carapace) cfg.plugins.entries.carapace = {};
+    if (!cfg.plugins.entries.carapace.config) cfg.plugins.entries.carapace.config = {};
+
+    if (patched.length > 0 || !cfg.plugins.entries.carapace.enabled) {
+      cfg.plugins.entries.carapace.enabled = true;
       writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
     }
 
@@ -184,10 +243,27 @@ export default function register(api: OpenClawPluginApi) {
 
       if (proxy) {
         await proxy.start();
-        logger.info(
-          `🛡️  LLM Proxy active on http://127.0.0.1:${proxyConfig!.port ?? 19821} — ` +
-          `all tool calls go through Cedar`
-        );
+
+        // Health check: verify proxy is actually responding
+        const proxyPort = proxyConfig!.port ?? 19821;
+        try {
+          const controller = new AbortController();
+          const timer = setTimeout(() => controller.abort(), 3000);
+          const healthResp = await fetch(`http://127.0.0.1:${proxyPort}/health`, { signal: controller.signal });
+          clearTimeout(timer);
+          if (!healthResp.ok) throw new Error(`HTTP ${healthResp.status}`);
+        } catch (err: any) {
+          logger.error(`❌ Proxy health check failed on port ${proxyPort}: ${err.message}. Disabling proxy.`);
+          try { await proxy.stop(); } catch {}
+          proxy = null;
+        }
+
+        if (proxy) {
+          logger.info(
+            `🛡️  LLM Proxy active on http://127.0.0.1:${proxyPort} — ` +
+            `all tool calls go through Cedar`
+          );
+        }
       } else {
         // Check for bypass vulnerabilities only when proxy is disabled
         const bypasses = checkForBypasses();
@@ -199,6 +275,17 @@ export default function register(api: OpenClawPluginApi) {
           );
         }
       }
+
+      // Warn if Carapace is loaded but not actually enforcing anything
+      const tools = aggregator.listTools();
+      const enabledCount = tools.filter((t: any) => t.enabled).length;
+      if (!proxy && enabledCount === 0) {
+        logger.warn(
+          `⚠️  Carapace is loaded but NOT ENFORCING. No tools are gated and the LLM proxy is disabled. ` +
+          `Your agent is running without policy protection. ` +
+          `Run "openclaw carapace setup" to activate enforcement, or configure policies at http://localhost:${config.guiPort ?? 19820}`
+        );
+      }
     },
     async stop() {
       if (proxy) await proxy.stop();
@@ -514,6 +601,8 @@ export default function register(api: OpenClawPluginApi) {
         .description("Configure OpenClaw to route all traffic through Carapace")
         .action(async () => {
           console.log("\n🦞 Carapace Setup\n");
+          backupConfig();
+          console.log("  📦 Backed up openclaw.json → openclaw.json.carapace-backup");
           let anyChanges = false;
 
           // 1. Deny built-in bypass tools
@@ -545,7 +634,8 @@ export default function register(api: OpenClawPluginApi) {
             }
             if (patched.length === 0 && alreadySet.length === 0) {
               console.log("    ⚠️  No upstream providers configured in proxy config.");
-              console.log("       Add proxy.upstream.anthropic or proxy.upstream.openai to your plugin config.");
+              console.log('       Set proxy.upstream to a URL string (e.g., "https://api.anthropic.com") with proxy.apiKey,');
+              console.log("       or use the object format: proxy.upstream = { anthropic: { apiKey: '...' } }");
             }
           } else {
             console.log("\n  LLM proxy not enabled — skipping baseUrl setup.");
@@ -599,11 +689,18 @@ export default function register(api: OpenClawPluginApi) {
             if (cfg.models?.providers) {
               for (const [name, provCfg] of Object.entries(cfg.models.providers)) {
                 if ((provCfg as any)?.baseUrl === proxyUrl) {
-                  delete (provCfg as any).baseUrl;
+                  // Restore original baseUrl if stored
+                  if ((provCfg as any)._originalBaseUrl) {
+                    (provCfg as any).baseUrl = (provCfg as any)._originalBaseUrl;
+                    delete (provCfg as any)._originalBaseUrl;
+                    console.log(`  ✅ Restored original baseUrl for ${name}`);
+                  } else {
+                    delete (provCfg as any).baseUrl;
+                    console.log(`  ✅ Removed baseUrl proxy override for ${name}`);
+                  }
                   // Clean up empty objects
                   if (Object.keys(provCfg as any).length === 0) delete cfg.models.providers[name];
                   changed = true;
-                  console.log(`  ✅ Removed baseUrl proxy override for ${name}`);
                   console.log(`     ${name} will connect directly to its API again.`);
                 }
               }

package/src/llm-proxy.ts

@@ -63,14 +63,6 @@ export class LlmProxy {
     toolCallsDenied: 0,
   };
 
-  // Audit log for GUI display
-  private auditLog: Array<{
-    timestamp: number;
-    tool: string;
-    decision: "allow" | "deny";
-    reasons: string[];
-  }> = [];
-
   constructor(opts: LlmProxyOpts) {
     this.port = opts.port;
     this.upstream = opts.upstream;
@@ -78,10 +70,6 @@ export class LlmProxy {
     this.logger = opts.logger;
   }
 
-  getAuditLog() {
-    return this.auditLog.slice(-100); // last 100 entries
-  }
-
   async start(): Promise<void> {
     this.server = createServer(async (req, res) => {
       try {
@@ -608,15 +596,6 @@ export class LlmProxy {
       context,
     });
 
-    // Audit log entry
-    this.auditLog.push({
-      timestamp: Date.now(),
-      tool: toolName,
-      decision: decision.decision,
-      reasons: decision.reasons,
-    });
-    if (this.auditLog.length > 500) this.auditLog.splice(0, this.auditLog.length - 100);
-
     if (decision.decision === "deny") {
       this.stats.toolCallsDenied++;
     }

package/src/policy-source.ts

@@ -8,8 +8,13 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 
 /**
- * Interface matching @clawdreyhepburn/ovid-me's PolicySource.
- * Defined locally to avoid circular dependencies.
+ * Must match @clawdreyhepburn/ovid-me PolicySource interface.
+ *
+ * Kept as a local copy because ovid-me pulls in native dependencies
+ * (better-sqlite3) that would bloat Carapace's install. A type
+ * compatibility test in test/policy-source.test.ts guards against drift.
+ *
+ * Canonical definition: ovid-me/src/config.ts
  */
 export interface PolicySource {
   getEffectivePolicy(principal: string): Promise<string | null>;

package/src/types.ts

@@ -27,10 +27,13 @@ export interface PluginConfig {
   proxy?: {
     enabled?: boolean;
     port?: number;  // default: 19821
-    upstream?: {
+    /** String (simple: base URL) or object (multi-provider) */
+    upstream?: string | {
       anthropic?: { url?: string; apiKey: string };
       openai?: { url?: string; apiKey: string };
     };
+    /** API key for the upstream provider (used with string upstream) */
+    apiKey?: string;
   };
 }