multicorn-shield 0.1.13 → 0.1.16

package/README.md

@@ -155,6 +155,42 @@ await shield.logAction({
 
 That gives you a consent screen, scoped permissions, and an audit trail.
 
+## Dashboard
+
+Every action, approval, and permission is visible in real time at [app.multicorn.ai](https://app.multicorn.ai).
+
+**Sign up:** [https://app.multicorn.ai](https://app.multicorn.ai)
+
+With the dashboard you can:
+
+- See all agents and their activity
+- Approve or reject pending actions
+- Configure per-agent permissions (read/write/execute per service)
+- Set spending limits
+- View the full audit trail with hash-chain integrity
+
+The dashboard works with both the SDK integration and the MCP proxy. No extra setup needed.
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/overview-page.png" alt="Dashboard overview showing total actions, blocked count, spend, and live activity feed" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/approvals-card.png" alt="Approval card with one-tap approve/reject and permission duration options" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/activity-log-list.png" alt="Filterable activity log showing every agent action with status" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/consent-screen.png" alt="Consent screen where users grant agent permissions" width="800" />
+</p>
+
+<p align="center">
+  <img src="https://multicorn.ai/images/screenshots/agent-page-with-stats.png" alt="Agent detail page with action stats and budget tracking" width="800" />
+</p>
+
 ## Built with Shield
 
 Multicorn is developed using AI coding agents. Primarily Cursor for code generation and GitHub Actions as the deployment agent. Every one of those agents runs under Shield.

package/dist/multicorn-proxy.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { readFile, mkdir, writeFile } from 'fs/promises';
+import { readFile, mkdir, writeFile, unlink } from 'fs/promises';
 import { join } from 'path';
 import { homedir } from 'os';
 import { createInterface } from 'readline';
 import { spawn } from 'child_process';
+import { createHash } from 'crypto';
 import 'stream';
 
 var CONFIG_DIR = join(homedir(), ".multicorn");
@@ -506,6 +507,9 @@ function dollarsToCents(dollars) {
 // src/proxy/interceptor.ts
 var BLOCKED_ERROR_CODE = -32e3;
 var SPENDING_BLOCKED_ERROR_CODE = -32001;
+var INTERNAL_ERROR_CODE = -32002;
+var SERVICE_UNREACHABLE_ERROR_CODE = -32003;
+var AUTH_ERROR_CODE = -32004;
 function parseJsonRpcLine(line) {
   const trimmed = line.trim();
   if (trimmed.length === 0) return null;
@@ -550,6 +554,39 @@ function buildSpendingBlockedResponse(id, reason, dashboardUrl) {
     }
   };
 }
+function buildInternalErrorResponse(id) {
+  const message = "Action blocked: Shield encountered an internal error and cannot verify permissions. Check proxy logs for details.";
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: INTERNAL_ERROR_CODE,
+      message
+    }
+  };
+}
+function buildServiceUnreachableResponse(id, dashboardUrl) {
+  const message = `Action blocked: Shield cannot verify permissions (service unreachable). Configure offline behaviour at ${dashboardUrl}`;
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: SERVICE_UNREACHABLE_ERROR_CODE,
+      message
+    }
+  };
+}
+function buildAuthErrorResponse(id) {
+  const message = "Action blocked: Shield API key is invalid or has been revoked. Run npx multicorn-proxy init to reconfigure.";
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: AUTH_ERROR_CODE,
+      message
+    }
+  };
+}
 function extractServiceFromToolName(toolName) {
   const idx = toolName.indexOf("_");
   return idx === -1 ? toolName : toolName.slice(0, idx);
@@ -574,44 +611,53 @@ function capitalize(str) {
 }
 var MULTICORN_DIR = join(homedir(), ".multicorn");
 var SCOPES_PATH = join(MULTICORN_DIR, "scopes.json");
-var CONSENT_POLL_INTERVAL_MS = 3e3;
-var CONSENT_POLL_TIMEOUT_MS = 5 * 60 * 1e3;
-function deriveDashboardUrl(baseUrl) {
+var CACHE_META_PATH = join(MULTICORN_DIR, "cache-meta.json");
+function cacheKey(agentName, apiKey) {
+  return createHash("sha256").update(`${agentName}:${apiKey}`).digest("hex").slice(0, 16);
+}
+async function ensureCacheIdentity(apiKey) {
+  const currentHash = createHash("sha256").update(apiKey).digest("hex");
+  let storedHash = null;
   try {
-    const url = new URL(baseUrl);
-    if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
-      url.port = "5173";
-      url.protocol = "http:";
-      return url.toString();
-    }
-    if (url.hostname === "api.multicorn.ai") {
-      url.hostname = "app.multicorn.ai";
-      return url.toString();
-    }
-    if (url.hostname.includes("api")) {
-      url.hostname = url.hostname.replace("api", "app");
-      return url.toString();
-    }
-    if (url.protocol === "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
-      return "https://app.multicorn.ai";
+    const raw = await readFile(CACHE_META_PATH, "utf8");
+    const meta = JSON.parse(raw);
+    if (typeof meta === "object" && meta !== null && "apiKeyHash" in meta) {
+      storedHash = meta.apiKeyHash;
     }
-    return "https://app.multicorn.ai";
   } catch {
-    return "https://app.multicorn.ai";
+  }
+  if (storedHash === null || storedHash !== currentHash) {
+    try {
+      await unlink(SCOPES_PATH);
+    } catch {
+    }
+  }
+  if (storedHash !== currentHash) {
+    await mkdir(MULTICORN_DIR, { recursive: true, mode: 448 });
+    await writeFile(CACHE_META_PATH, JSON.stringify({ apiKeyHash: currentHash }, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 384
+    });
   }
 }
-async function loadCachedScopes(agentName) {
+async function loadCachedScopes(agentName, apiKey) {
+  if (apiKey.length === 0) return null;
+  await ensureCacheIdentity(apiKey);
+  const key = cacheKey(agentName, apiKey);
   try {
     const raw = await readFile(SCOPES_PATH, "utf8");
     const parsed = JSON.parse(raw);
     if (!isScopesCacheFile(parsed)) return null;
-    const entry = parsed[agentName];
+    const entry = parsed[key];
     return entry?.scopes ?? null;
   } catch {
     return null;
   }
 }
-async function saveCachedScopes(agentName, agentId, scopes) {
+async function saveCachedScopes(agentName, agentId, scopes, apiKey) {
+  if (apiKey.length === 0) return;
+  await ensureCacheIdentity(apiKey);
+  const key = cacheKey(agentName, apiKey);
   await mkdir(MULTICORN_DIR, { recursive: true, mode: 448 });
   let existing = {};
   try {
@@ -622,7 +668,7 @@ async function saveCachedScopes(agentName, agentId, scopes) {
   }
   const updated = {
     ...existing,
-    [agentName]: {
+    [key]: {
       agentId,
       scopes,
       fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -633,6 +679,44 @@ async function saveCachedScopes(agentName, agentId, scopes) {
     mode: 384
   });
 }
+function isScopesCacheFile(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/proxy/consent.ts
+var CONSENT_POLL_INTERVAL_MS = 3e3;
+var CONSENT_POLL_TIMEOUT_MS = 5 * 60 * 1e3;
+function deriveDashboardUrl(baseUrl) {
+  try {
+    const url = new URL(baseUrl);
+    if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
+      url.port = "5173";
+      url.protocol = "http:";
+      return url.toString();
+    }
+    if (url.hostname === "api.multicorn.ai") {
+      url.hostname = "app.multicorn.ai";
+      return url.toString();
+    }
+    if (url.hostname.includes("api")) {
+      url.hostname = url.hostname.replace("api", "app");
+      return url.toString();
+    }
+    if (url.protocol === "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+      return "https://app.multicorn.ai";
+    }
+    return "https://app.multicorn.ai";
+  } catch {
+    return "https://app.multicorn.ai";
+  }
+}
+var ShieldAuthError = class _ShieldAuthError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ShieldAuthError";
+    Object.setPrototypeOf(this, _ShieldAuthError.prototype);
+  }
+};
 async function findAgentByName(agentName, apiKey, baseUrl) {
   let response;
   try {
@@ -643,8 +727,18 @@ async function findAgentByName(agentName, apiKey, baseUrl) {
   } catch {
     return null;
   }
-  if (!response.ok) return null;
-  const body = await response.json();
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      return { id: "", name: agentName, scopes: [], authInvalid: true };
+    }
+    return null;
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return null;
+  }
   if (!isApiSuccessResponse(body)) return null;
   const agents = body.data;
   if (!Array.isArray(agents)) return null;
@@ -665,6 +759,11 @@ async function registerAgent(agentName, apiKey, baseUrl) {
     signal: AbortSignal.timeout(8e3)
   });
   if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      throw new ShieldAuthError(
+        `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
+      );
+    }
     throw new Error(
       `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
     );
@@ -738,12 +837,15 @@ Waiting for you to grant access in the Multicorn dashboard...
   );
 }
 async function resolveAgentRecord(agentName, apiKey, baseUrl, logger) {
-  const cachedScopes = await loadCachedScopes(agentName);
+  const cachedScopes = await loadCachedScopes(agentName, apiKey);
   if (cachedScopes !== null && cachedScopes.length > 0) {
     logger.debug("Loaded scopes from cache.", { agent: agentName, count: cachedScopes.length });
     return { id: "", name: agentName, scopes: cachedScopes };
   }
   let agent = await findAgentByName(agentName, apiKey, baseUrl);
+  if (agent?.authInvalid) {
+    return agent;
+  }
   if (agent === null) {
     try {
       logger.info("Agent not found. Registering.", { agent: agentName });
@@ -751,6 +853,9 @@ async function resolveAgentRecord(agentName, apiKey, baseUrl, logger) {
       agent = { id, name: agentName, scopes: [] };
       logger.info("Agent registered.", { agent: agentName, id });
     } catch (error) {
+      if (error instanceof ShieldAuthError) {
+        return { id: "", name: agentName, scopes: [], authInvalid: true };
+      }
       const detail = error instanceof Error ? error.message : String(error);
       logger.warn("Could not reach Multicorn service. Running with empty permissions.", {
         error: detail
@@ -760,7 +865,7 @@ async function resolveAgentRecord(agentName, apiKey, baseUrl, logger) {
   }
   const scopes = await fetchGrantedScopes(agent.id, apiKey, baseUrl);
   if (scopes.length > 0) {
-    await saveCachedScopes(agentName, agent.id, scopes);
+    await saveCachedScopes(agentName, agent.id, scopes, apiKey);
   }
   return { ...agent, scopes };
 }
@@ -798,9 +903,6 @@ function isPermissionShape(value) {
   const obj = value;
   return typeof obj["service"] === "string" && typeof obj["read"] === "boolean" && typeof obj["write"] === "boolean" && typeof obj["execute"] === "boolean" && (obj["revoked_at"] === null || typeof obj["revoked_at"] === "string");
 }
-function isScopesCacheFile(value) {
-  return typeof value === "object" && value !== null;
-}
 
 // src/proxy/index.ts
 var DEFAULT_SCOPE_REFRESH_INTERVAL_MS = 6e4;
@@ -815,6 +917,7 @@ function createProxyServer(config) {
   let spendingChecker = null;
   let grantedScopes = [];
   let agentId = "";
+  let authInvalid = false;
   let refreshTimer = null;
   let consentInProgress = false;
   const pendingLines = [];
@@ -827,7 +930,7 @@ function createProxyServer(config) {
       const scopes = await fetchGrantedScopes(agentId, config.apiKey, config.baseUrl);
       grantedScopes = scopes;
       if (scopes.length > 0) {
-        await saveCachedScopes(config.agentName, agentId, scopes);
+        await saveCachedScopes(config.agentName, agentId, scopes, config.apiKey);
       }
       config.logger.debug("Scopes refreshed.", { count: scopes.length });
     } catch (error) {
@@ -856,7 +959,7 @@ function createProxyServer(config) {
         scopeParam
       );
       grantedScopes = scopes;
-      await saveCachedScopes(config.agentName, agentId, scopes);
+      await saveCachedScopes(config.agentName, agentId, scopes, config.apiKey);
     } finally {
       consentInProgress = false;
     }
@@ -867,40 +970,28 @@ function createProxyServer(config) {
     if (request.method !== "tools/call") return null;
     const toolParams = extractToolCallParams(request);
     if (toolParams === null) return null;
-    const service = extractServiceFromToolName(toolParams.name);
-    const action = extractActionFromToolName(toolParams.name);
-    const requestedScope = { service, permissionLevel: "execute" };
-    const validation = validateScopeAccess(grantedScopes, requestedScope);
-    config.logger.debug("Tool call intercepted.", {
-      tool: toolParams.name,
-      service,
-      allowed: validation.allowed
-    });
-    if (!validation.allowed) {
-      await ensureConsent(requestedScope);
-      const revalidation = validateScopeAccess(grantedScopes, requestedScope);
-      if (!revalidation.allowed) {
-        if (actionLogger !== null) {
-          if (!config.agentName || config.agentName.trim().length === 0) {
-            process.stderr.write("[multicorn-proxy] Cannot log action: agent name not resolved\n");
-          } else {
-            await actionLogger.logAction({
-              agent: config.agentName,
-              service,
-              actionType: action,
-              status: "blocked"
-            });
-          }
-        }
-        const blocked = buildBlockedResponse(request.id, service, "execute", config.dashboardUrl);
+    try {
+      if (authInvalid) {
+        const blocked = buildAuthErrorResponse(request.id);
         return JSON.stringify(blocked);
       }
-    }
-    if (spendingChecker !== null) {
-      const costCents = extractCostCents(toolParams.arguments);
-      if (costCents > 0) {
-        const spendResult = spendingChecker.checkSpend(costCents);
-        if (!spendResult.allowed) {
+      if (agentId.length === 0) {
+        const blocked = buildServiceUnreachableResponse(request.id, config.dashboardUrl);
+        return JSON.stringify(blocked);
+      }
+      const service = extractServiceFromToolName(toolParams.name);
+      const action = extractActionFromToolName(toolParams.name);
+      const requestedScope = { service, permissionLevel: "execute" };
+      const validation = validateScopeAccess(grantedScopes, requestedScope);
+      config.logger.debug("Tool call intercepted.", {
+        tool: toolParams.name,
+        service,
+        allowed: validation.allowed
+      });
+      if (!validation.allowed) {
+        await ensureConsent(requestedScope);
+        const revalidation = validateScopeAccess(grantedScopes, requestedScope);
+        if (!revalidation.allowed) {
           if (actionLogger !== null) {
             if (!config.agentName || config.agentName.trim().length === 0) {
               process.stderr.write(
@@ -915,29 +1006,60 @@ function createProxyServer(config) {
               });
             }
           }
-          const blocked = buildSpendingBlockedResponse(
-            request.id,
-            spendResult.reason ?? "spending limit exceeded",
-            config.dashboardUrl
+          return JSON.stringify(
+            buildBlockedResponse(request.id, service, "execute", config.dashboardUrl)
           );
-          return JSON.stringify(blocked);
         }
-        spendingChecker.recordSpend(costCents);
       }
-    }
-    if (actionLogger !== null) {
-      if (!config.agentName || config.agentName.trim().length === 0) {
-        process.stderr.write("[multicorn-proxy] Cannot log action: agent name not resolved\n");
-      } else {
-        await actionLogger.logAction({
-          agent: config.agentName,
-          service,
-          actionType: action,
-          status: "approved"
-        });
+      if (spendingChecker !== null) {
+        const costCents = extractCostCents(toolParams.arguments);
+        if (costCents > 0) {
+          const spendResult = spendingChecker.checkSpend(costCents);
+          if (!spendResult.allowed) {
+            if (actionLogger !== null) {
+              if (!config.agentName || config.agentName.trim().length === 0) {
+                process.stderr.write(
+                  "[multicorn-proxy] Cannot log action: agent name not resolved\n"
+                );
+              } else {
+                await actionLogger.logAction({
+                  agent: config.agentName,
+                  service,
+                  actionType: action,
+                  status: "blocked"
+                });
+              }
+            }
+            const blocked = buildSpendingBlockedResponse(
+              request.id,
+              spendResult.reason ?? "spending limit exceeded",
+              config.dashboardUrl
+            );
+            return JSON.stringify(blocked);
+          }
+          spendingChecker.recordSpend(costCents);
+        }
       }
+      if (actionLogger !== null) {
+        if (!config.agentName || config.agentName.trim().length === 0) {
+          process.stderr.write("[multicorn-proxy] Cannot log action: agent name not resolved\n");
+        } else {
+          await actionLogger.logAction({
+            agent: config.agentName,
+            service,
+            actionType: action,
+            status: "approved"
+          });
+        }
+      }
+      return null;
+    } catch (error) {
+      config.logger.error("Tool call handler error.", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      const blocked = buildInternalErrorResponse(request.id);
+      return JSON.stringify(blocked);
     }
-    return null;
   }
   async function processLine(line) {
     const childProcess = child;
@@ -989,6 +1111,7 @@ function createProxyServer(config) {
     );
     agentId = agentRecord.id;
     grantedScopes = agentRecord.scopes;
+    authInvalid = agentRecord.authInvalid === true;
     config.logger.info("Agent resolved.", {
       agent: config.agentName,
       id: agentId,

package/dist/openclaw-hook/handler.js

@@ -1,4 +1,5 @@
-import { readFile, mkdir, writeFile } from 'fs/promises';
+import { createHash } from 'crypto';
+import { readFile, mkdir, writeFile, unlink } from 'fs/promises';
 import { join } from 'path';
 import { homedir } from 'os';
 import { spawn } from 'child_process';
@@ -83,18 +84,53 @@ function mapToolToScope(toolName, command) {
 }
 var MULTICORN_DIR = join(homedir(), ".multicorn");
 var SCOPES_PATH = join(MULTICORN_DIR, "scopes.json");
-async function loadCachedScopes(agentName) {
+var CACHE_META_PATH = join(MULTICORN_DIR, "cache-meta.json");
+function cacheKey(agentName, apiKey) {
+  return createHash("sha256").update(`${agentName}:${apiKey}`).digest("hex").slice(0, 16);
+}
+async function ensureCacheIdentity(apiKey) {
+  const currentHash = createHash("sha256").update(apiKey).digest("hex");
+  let storedHash = null;
+  try {
+    const raw = await readFile(CACHE_META_PATH, "utf8");
+    const meta = JSON.parse(raw);
+    if (typeof meta === "object" && meta !== null && "apiKeyHash" in meta) {
+      storedHash = meta.apiKeyHash;
+    }
+  } catch {
+  }
+  if (storedHash === null || storedHash !== currentHash) {
+    try {
+      await unlink(SCOPES_PATH);
+    } catch {
+    }
+  }
+  if (storedHash !== currentHash) {
+    await mkdir(MULTICORN_DIR, { recursive: true, mode: 448 });
+    await writeFile(CACHE_META_PATH, JSON.stringify({ apiKeyHash: currentHash }, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 384
+    });
+  }
+}
+async function loadCachedScopes(agentName, apiKey) {
+  if (apiKey.length === 0) return null;
+  await ensureCacheIdentity(apiKey);
+  const key = cacheKey(agentName, apiKey);
   try {
     const raw = await readFile(SCOPES_PATH, "utf8");
     const parsed = JSON.parse(raw);
     if (!isScopesCacheFile(parsed)) return null;
-    const entry = parsed[agentName];
+    const entry = parsed[key];
     return entry?.scopes ?? null;
   } catch {
     return null;
   }
 }
-async function saveCachedScopes(agentName, agentId, scopes) {
+async function saveCachedScopes(agentName, agentId, scopes, apiKey) {
+  if (apiKey.length === 0) return;
+  await ensureCacheIdentity(apiKey);
+  const key = cacheKey(agentName, apiKey);
   await mkdir(MULTICORN_DIR, { recursive: true, mode: 448 });
   let existing = {};
   try {
@@ -105,7 +141,7 @@ async function saveCachedScopes(agentName, agentId, scopes) {
   }
   const updated = {
     ...existing,
-    [agentName]: {
+    [key]: {
       agentId,
       scopes,
       fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -156,19 +192,19 @@ function handleHttpError(status, logger, retryDelaySeconds) {
   }
   if (status === 429) {
     {
-      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action was not checked \u2014 proceeding with fail-open.";
+      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action blocked: Shield cannot verify permissions.";
       process.stderr.write(`${rateLimitMsg}
 `);
     }
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
   if (status >= 500 && status < 600) {
-    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action was not checked \u2014 proceeding with fail-open.`;
+    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action blocked: Shield cannot verify permissions.`;
     process.stderr.write(`${serverErrorMsg}
 `);
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
-  return { shouldBlock: false };
+  return { shouldBlock: true };
 }
 async function findAgentByName(agentName, apiKey, baseUrl, logger) {
   try {
@@ -201,6 +237,13 @@ async function registerAgent(agentName, apiKey, baseUrl, logger) {
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
   });
   if (!response.ok) {
+    const body2 = await response.json().catch(() => null);
+    if (response.status === 403) {
+      const msg = (body2?.error?.message ?? "").toLowerCase();
+      if (msg.includes("agent limit") || msg.includes("maximum")) {
+        throw new Error("Agent limit reached. Upgrade your plan at app.multicorn.ai/settings.");
+      }
+    }
     handleHttpError(response.status);
     throw new Error(
       `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
@@ -212,15 +255,28 @@ async function registerAgent(agentName, apiKey, baseUrl, logger) {
   }
   return body.data.id;
 }
+var findOrRegisterInflight = /* @__PURE__ */ new Map();
 async function findOrRegisterAgent(agentName, apiKey, baseUrl, logger) {
-  const existing = await findAgentByName(agentName, apiKey, baseUrl, logger);
-  if (existing !== null) return existing;
-  try {
-    const id = await registerAgent(agentName, apiKey, baseUrl, logger);
-    return { id, name: agentName };
-  } catch {
-    return null;
-  }
+  const key = `${agentName}:${apiKey}:${baseUrl}`;
+  const existing = findOrRegisterInflight.get(key);
+  if (existing !== void 0) return existing;
+  const promise = (async () => {
+    const found = await findAgentByName(agentName, apiKey, baseUrl, logger);
+    if (found !== null) return found;
+    try {
+      const id = await registerAgent(agentName, apiKey, baseUrl, logger);
+      return { id, name: agentName };
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("Agent limit reached")) {
+        throw err;
+      }
+      return null;
+    }
+  })().finally(() => {
+    findOrRegisterInflight.delete(key);
+  });
+  findOrRegisterInflight.set(key, promise);
+  return promise;
 }
 async function fetchGrantedScopes(agentId, apiKey, baseUrl, logger) {
   try {
@@ -366,6 +422,7 @@ var agentRecord = null;
 var grantedScopes = [];
 var consentInProgress = false;
 var lastScopeRefresh = 0;
+var pinnedAgentName = null;
 var SCOPE_REFRESH_INTERVAL_MS = 6e4;
 function readConfig() {
   const apiKey = process.env["MULTICORN_API_KEY"] ?? "";
@@ -386,12 +443,20 @@ function resolveAgentName(sessionKey, envOverride) {
   }
   return "openclaw";
 }
+function getAgentName(sessionKey, envOverride) {
+  if (pinnedAgentName !== null) return pinnedAgentName;
+  const resolved = resolveAgentName(sessionKey, envOverride);
+  if (resolved !== "openclaw") {
+    pinnedAgentName = resolved;
+  }
+  return resolved;
+}
 async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
   if (agentRecord !== null && Date.now() - lastScopeRefresh < SCOPE_REFRESH_INTERVAL_MS) {
     return "ready";
   }
   if (agentRecord === null) {
-    const cached = await loadCachedScopes(agentName);
+    const cached = await loadCachedScopes(agentName, apiKey);
     if (cached !== null && cached.length > 0) {
       grantedScopes = cached;
       void findOrRegisterAgent(agentName, apiKey, baseUrl).then((record) => {
@@ -418,7 +483,7 @@ async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
   grantedScopes = scopes;
   lastScopeRefresh = Date.now();
   if (scopes.length > 0) {
-    await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+    await saveCachedScopes(agentName, agentRecord.id, scopes, apiKey).catch(() => {
     });
   }
   return "ready";
@@ -444,7 +509,7 @@ async function ensureConsent(agentName, apiKey, baseUrl, scope) {
   try {
     const scopes = await waitForConsent(agentRecord.id, agentName, apiKey, baseUrl, scope);
     grantedScopes = scopes;
-    await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+    await saveCachedScopes(agentName, agentRecord.id, scopes, apiKey).catch(() => {
     });
   } finally {
     consentInProgress = false;
@@ -466,7 +531,10 @@ var handler = async (event) => {
     );
     return;
   }
-  const agentName = resolveAgentName(event.sessionKey, config.agentName);
+  if (config.agentName !== null) {
+    pinnedAgentName = config.agentName;
+  }
+  const agentName = getAgentName(event.sessionKey, config.agentName);
   const readiness = await ensureAgent(agentName, config.apiKey, config.baseUrl, config.failMode);
   if (readiness === "block") {
     event.messages.push(
@@ -488,9 +556,10 @@ var handler = async (event) => {
   const permitted = isPermitted(event);
   if (!permitted) {
     const capitalizedService = mapping.service.charAt(0).toUpperCase() + mapping.service.slice(1);
-    const dashboardUrl = deriveDashboardUrl(config.baseUrl);
+    const base = deriveDashboardUrl(config.baseUrl).replace(/\/+$/, "");
     event.messages.push(
-      `Permission denied: ${capitalizedService} ${mapping.permissionLevel} access is not allowed. Check pending approvals at ${dashboardUrl}/approvals `
+      `Permission denied: ${capitalizedService} ${mapping.permissionLevel} access is not allowed. Check pending approvals at:
+${base}/approvals`
     );
     void logAction(
       {
@@ -520,6 +589,7 @@ function resetState() {
   grantedScopes = [];
   consentInProgress = false;
   lastScopeRefresh = 0;
+  pinnedAgentName = null;
 }
 
 export { handler, readConfig, resetState, resolveAgentName };

package/dist/openclaw-plugin/{index.js → multicorn-shield.js}

@@ -3,7 +3,8 @@ import * as path from 'path';
 import { join } from 'path';
 import * as os from 'os';
 import { homedir } from 'os';
-import { mkdir, readFile, writeFile } from 'fs/promises';
+import { createHash } from 'crypto';
+import { mkdir, readFile, writeFile, unlink } from 'fs/promises';
 import { spawn } from 'child_process';
 
 // Multicorn Shield plugin for OpenClaw - https://multicorn.ai
@@ -88,18 +89,53 @@ function mapToolToScope(toolName, command) {
 }
 var MULTICORN_DIR = join(homedir(), ".multicorn");
 var SCOPES_PATH = join(MULTICORN_DIR, "scopes.json");
-async function loadCachedScopes(agentName) {
+var CACHE_META_PATH = join(MULTICORN_DIR, "cache-meta.json");
+function cacheKey(agentName, apiKey) {
+  return createHash("sha256").update(`${agentName}:${apiKey}`).digest("hex").slice(0, 16);
+}
+async function ensureCacheIdentity(apiKey) {
+  const currentHash = createHash("sha256").update(apiKey).digest("hex");
+  let storedHash = null;
+  try {
+    const raw = await readFile(CACHE_META_PATH, "utf8");
+    const meta = JSON.parse(raw);
+    if (typeof meta === "object" && meta !== null && "apiKeyHash" in meta) {
+      storedHash = meta.apiKeyHash;
+    }
+  } catch {
+  }
+  if (storedHash === null || storedHash !== currentHash) {
+    try {
+      await unlink(SCOPES_PATH);
+    } catch {
+    }
+  }
+  if (storedHash !== currentHash) {
+    await mkdir(MULTICORN_DIR, { recursive: true, mode: 448 });
+    await writeFile(CACHE_META_PATH, JSON.stringify({ apiKeyHash: currentHash }, null, 2) + "\n", {
+      encoding: "utf8",
+      mode: 384
+    });
+  }
+}
+async function loadCachedScopes(agentName, apiKey) {
+  if (apiKey.length === 0) return null;
+  await ensureCacheIdentity(apiKey);
+  const key = cacheKey(agentName, apiKey);
   try {
     const raw = await readFile(SCOPES_PATH, "utf8");
     const parsed = JSON.parse(raw);
     if (!isScopesCacheFile(parsed)) return null;
-    const entry = parsed[agentName];
+    const entry = parsed[key];
     return entry?.scopes ?? null;
   } catch {
     return null;
   }
 }
-async function saveCachedScopes(agentName, agentId, scopes) {
+async function saveCachedScopes(agentName, agentId, scopes, apiKey) {
+  if (apiKey.length === 0) return;
+  await ensureCacheIdentity(apiKey);
+  const key = cacheKey(agentName, apiKey);
   await mkdir(MULTICORN_DIR, { recursive: true, mode: 448 });
   let existing = {};
   try {
@@ -110,7 +146,7 @@ async function saveCachedScopes(agentName, agentId, scopes) {
   }
   const updated = {
     ...existing,
-    [agentName]: {
+    [key]: {
       agentId,
       scopes,
       fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -162,21 +198,21 @@ function handleHttpError(status, logger, retryDelaySeconds) {
   }
   if (status === 429) {
     {
-      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action was not checked \u2014 proceeding with fail-open.";
+      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action blocked: Shield cannot verify permissions.";
       logger?.warn(rateLimitMsg);
       process.stderr.write(`${rateLimitMsg}
 `);
     }
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
   if (status >= 500 && status < 600) {
-    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action was not checked \u2014 proceeding with fail-open.`;
+    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action blocked: Shield cannot verify permissions.`;
     logger?.warn(serverErrorMsg);
     process.stderr.write(`${serverErrorMsg}
 `);
-    return { shouldBlock: false };
+    return { shouldBlock: true };
   }
-  return { shouldBlock: false };
+  return { shouldBlock: true };
 }
 async function findAgentByName(agentName, apiKey, baseUrl, logger) {
   try {
@@ -209,6 +245,13 @@ async function registerAgent(agentName, apiKey, baseUrl, logger) {
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
   });
   if (!response.ok) {
+    const body2 = await response.json().catch(() => null);
+    if (response.status === 403) {
+      const msg = (body2?.error?.message ?? "").toLowerCase();
+      if (msg.includes("agent limit") || msg.includes("maximum")) {
+        throw new Error("Agent limit reached. Upgrade your plan at app.multicorn.ai/settings.");
+      }
+    }
     handleHttpError(response.status, logger);
     throw new Error(
       `Failed to register agent "${agentName}": service returned ${String(response.status)}.`
@@ -220,15 +263,28 @@ async function registerAgent(agentName, apiKey, baseUrl, logger) {
   }
   return body.data.id;
 }
+var findOrRegisterInflight = /* @__PURE__ */ new Map();
 async function findOrRegisterAgent(agentName, apiKey, baseUrl, logger) {
-  const existing = await findAgentByName(agentName, apiKey, baseUrl, logger);
-  if (existing !== null) return existing;
-  try {
-    const id = await registerAgent(agentName, apiKey, baseUrl, logger);
-    return { id, name: agentName };
-  } catch {
-    return null;
-  }
+  const key = `${agentName}:${apiKey}:${baseUrl}`;
+  const existing = findOrRegisterInflight.get(key);
+  if (existing !== void 0) return existing;
+  const promise = (async () => {
+    const found = await findAgentByName(agentName, apiKey, baseUrl, logger);
+    if (found !== null) return found;
+    try {
+      const id = await registerAgent(agentName, apiKey, baseUrl, logger);
+      return { id, name: agentName };
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("Agent limit reached")) {
+        throw err;
+      }
+      return null;
+    }
+  })().finally(() => {
+    findOrRegisterInflight.delete(key);
+  });
+  findOrRegisterInflight.set(key, promise);
+  return promise;
 }
 async function fetchGrantedScopes(agentId, apiKey, baseUrl, logger) {
   try {
@@ -431,6 +487,7 @@ var lastScopeRefresh = 0;
 var pluginLogger = null;
 var pluginConfig;
 var connectionLogged = false;
+var pinnedAgentName = null;
 var SCOPE_REFRESH_INTERVAL_MS = 6e4;
 var cachedMulticornConfig = null;
 function loadMulticornConfig() {
@@ -453,9 +510,12 @@ function readConfig() {
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
-function resolveAgentName(sessionKey, envOverride) {
-  if (envOverride !== null && envOverride.trim().length > 0) {
-    return envOverride.trim();
+function resolveAgentName(sessionKey, configOverride, ctxAgentId) {
+  if (configOverride !== null && configOverride.trim().length > 0) {
+    return configOverride.trim();
+  }
+  if (ctxAgentId !== void 0 && ctxAgentId.trim().length > 0) {
+    return ctxAgentId.trim();
   }
   const parts = sessionKey.split(":");
   const name = parts[1];
@@ -464,12 +524,23 @@ function resolveAgentName(sessionKey, envOverride) {
   }
   return "openclaw";
 }
+function getAgentName(sessionKey, configOverride, ctxAgentId) {
+  if (pinnedAgentName !== null) return pinnedAgentName;
+  const resolved = resolveAgentName(sessionKey, configOverride, ctxAgentId);
+  if (resolved !== "openclaw") {
+    pinnedAgentName = resolved;
+  }
+  return resolved;
+}
 async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
-  if (agentRecord !== null && Date.now() - lastScopeRefresh < SCOPE_REFRESH_INTERVAL_MS) {
+  if (agentRecord !== null && agentRecord.name === agentName && Date.now() - lastScopeRefresh < SCOPE_REFRESH_INTERVAL_MS) {
     return "ready";
   }
+  if (agentRecord !== null && agentRecord.name !== agentName) {
+    agentRecord = null;
+  }
   if (agentRecord === null) {
-    const cached = await loadCachedScopes(agentName);
+    const cached = await loadCachedScopes(agentName, apiKey);
     if (cached !== null && cached.length > 0) {
       grantedScopes = cached;
       void findOrRegisterAgent(agentName, apiKey, baseUrl, pluginLogger ?? void 0).then(
@@ -501,7 +572,7 @@ async function ensureAgent(agentName, apiKey, baseUrl, failMode) {
   grantedScopes = scopes;
   lastScopeRefresh = Date.now();
   if (scopes.length > 0) {
-    await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+    await saveCachedScopes(agentName, agentRecord.id, scopes, apiKey).catch(() => {
     });
   }
   if (!connectionLogged) {
@@ -543,7 +614,7 @@ async function ensureConsent(agentName, apiKey, baseUrl, scope) {
       pluginLogger ?? void 0
     );
     grantedScopes = scopes;
-    await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+    await saveCachedScopes(agentName, agentRecord.id, scopes, apiKey).catch(() => {
     });
   } finally {
     consentInProgress = false;
@@ -632,7 +703,7 @@ async function beforeToolCall(event, ctx) {
       console.error("[SHIELD] DECISION: allow (no API key)");
       return void 0;
     }
-    const agentName = resolveAgentName(ctx.sessionKey ?? "", config.agentName);
+    const agentName = getAgentName(ctx.sessionKey ?? "", config.agentName, ctx.agentId);
     const readiness = await ensureAgent(agentName, config.apiKey, config.baseUrl, config.failMode);
     console.error("[SHIELD] ensureAgent result: " + JSON.stringify(readiness));
     if (readiness === "block") {
@@ -694,7 +765,7 @@ async function beforeToolCall(event, ctx) {
         grantedScopes = scopes;
         lastScopeRefresh = Date.now();
         if (Array.isArray(scopes) && scopes.length > 0) {
-          await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+          await saveCachedScopes(agentName, agentRecord.id, scopes, config.apiKey).catch(() => {
           });
         }
       }
@@ -702,10 +773,11 @@ async function beforeToolCall(event, ctx) {
       return void 0;
     }
     if (permissionResult.status === "pending" && permissionResult.approvalId !== void 0) {
-      const dashboardUrl2 = deriveDashboardUrl(config.baseUrl);
+      const base2 = deriveDashboardUrl(config.baseUrl).replace(/\/+$/, "");
       const returnValue2 = {
         block: true,
-        blockReason: `Action pending approval. Visit ${dashboardUrl2}approvals to approve or reject, then try again.`
+        blockReason: `Action pending approval.
+Visit ${base2}/approvals to approve or reject, then try again.`
       };
       console.error("[SHIELD] DECISION: " + JSON.stringify(returnValue2));
       return returnValue2;
@@ -726,7 +798,7 @@ async function beforeToolCall(event, ctx) {
       grantedScopes = scopes;
       lastScopeRefresh = Date.now();
       if (Array.isArray(scopes) && scopes.length > 0) {
-        await saveCachedScopes(agentName, agentRecord.id, scopes).catch(() => {
+        await saveCachedScopes(agentName, agentRecord.id, scopes, config.apiKey).catch(() => {
         });
       }
       const recheckResult = await checkActionPermission(
@@ -751,16 +823,19 @@ async function beforeToolCall(event, ctx) {
         grantedScopes = refreshedScopes;
         lastScopeRefresh = Date.now();
         if (Array.isArray(refreshedScopes) && refreshedScopes.length > 0) {
-          await saveCachedScopes(agentName, agentRecord.id, refreshedScopes).catch(() => {
-          });
+          await saveCachedScopes(agentName, agentRecord.id, refreshedScopes, config.apiKey).catch(
+            () => {
+            }
+          );
         }
         console.error("[SHIELD] DECISION: allow (re-check after consent)");
         return void 0;
       }
     }
     const capitalizedService = mapping.service.charAt(0).toUpperCase() + mapping.service.slice(1);
-    const dashboardUrl = deriveDashboardUrl(config.baseUrl);
-    const reason = `${capitalizedService} ${mapping.permissionLevel} access is not allowed. Check pending approvals at ${dashboardUrl}/approvals `;
+    const base = deriveDashboardUrl(config.baseUrl).replace(/\/+$/, "");
+    const reason = `${capitalizedService} ${mapping.permissionLevel} access is not allowed. Check pending approvals at:
+${base}/approvals`;
     const returnValue = { block: true, blockReason: reason };
     console.error("[SHIELD] DECISION: " + JSON.stringify(returnValue));
     return returnValue;
@@ -773,7 +848,7 @@ async function beforeToolCall(event, ctx) {
 function afterToolCall(event, ctx) {
   const config = readConfig();
   if (config.apiKey.length === 0) return Promise.resolve();
-  const agentName = resolveAgentName(ctx.sessionKey ?? "", config.agentName);
+  const agentName = getAgentName(ctx.sessionKey ?? "", config.agentName, ctx.agentId);
   const mapping = mapToolToScope(event.toolName);
   void logAction(
     {
@@ -801,11 +876,14 @@ var plugin = {
     pluginLogger = api.logger;
     pluginConfig = api.pluginConfig;
     cachedMulticornConfig = loadMulticornConfig();
+    const config = readConfig();
+    if (config.agentName !== null) {
+      pinnedAgentName = config.agentName;
+    }
     console.error("[SHIELD-DIAG] cachedMulticornConfig: " + JSON.stringify(cachedMulticornConfig));
     api.on("before_tool_call", beforeToolCall, { priority: 10 });
     api.on("after_tool_call", afterToolCall);
     api.logger.info("Multicorn Shield plugin registered.");
-    const config = readConfig();
     if (config.apiKey.length === 0) {
       api.logger.error(
         "Multicorn Shield: No API key found. Run 'npx multicorn-proxy init' or set MULTICORN_API_KEY."
@@ -829,6 +907,7 @@ function resetState() {
   pluginConfig = void 0;
   cachedMulticornConfig = null;
   connectionLogged = false;
+  pinnedAgentName = null;
 }
 
 export { afterToolCall, beforeToolCall, plugin, readConfig, register, resetState, resolveAgentName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multicorn-shield",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "The control layer for AI agents: permissions, consent, spending limits, and audit logging.",
   "license": "MIT",
   "type": "module",