multicorn-shield 0.8.0 → 0.10.0

package/dist/index.cjs

@@ -287,6 +287,39 @@ function hasScope(grantedScopes, requested) {
   );
 }
 
+// src/scopes/content-review-detector.ts
+function requiresContentReview(scope) {
+  if (scope.service === "web" && scope.permissionLevel === "publish") {
+    return true;
+  }
+  if (scope.service === "public_content" && scope.permissionLevel === "create") {
+    return true;
+  }
+  return false;
+}
+function isPublicContentAction(toolName, service) {
+  const lowerToolName = toolName.toLowerCase();
+  const lowerService = service.toLowerCase();
+  if (lowerService === "web" || lowerService === "public_content") {
+    return true;
+  }
+  const publicContentIndicators = [
+    "publish",
+    "public",
+    "web",
+    "blog",
+    "post",
+    "article",
+    "social",
+    "twitter",
+    "facebook",
+    "linkedin",
+    "github_pages",
+    "deploy"
+  ];
+  return publicContentIndicators.some((indicator) => lowerToolName.includes(indicator));
+}
+
 // src/consent/scope-labels.ts
 var SERVICE_DISPLAY_NAMES = {
   gmail: "Gmail",
@@ -1878,37 +1911,215 @@ function centsToDollars(cents) {
   })}`;
 }
 
-// src/scopes/content-review-detector.ts
-function requiresContentReview(scope) {
-  if (scope.service === "web" && scope.permissionLevel === "publish") {
-    return true;
+// src/openclaw/shield-client.ts
+var REQUEST_TIMEOUT_MS = 5e3;
+var AUTH_HEADER = "X-Multicorn-Key";
+var POLL_INTERVAL_MS = 3e3;
+var MAX_POLLS = 100;
+var POLL_TIMEOUT_MS = POLL_INTERVAL_MS * MAX_POLLS;
+var authErrorLogged = false;
+function isApiSuccess(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return obj["success"] === true;
+}
+function isContentReviewStatusResponse(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value;
+  return typeof obj["id"] === "string" && typeof obj["status"] === "string" && ["pending", "approved", "blocked", "timeout"].includes(obj["status"]);
+}
+function readApiErrorCode(body) {
+  if (typeof body !== "object" || body === null) return void 0;
+  const err = body["error"];
+  if (typeof err !== "object" || err === null) return void 0;
+  const code = err["code"];
+  return typeof code === "string" ? code : void 0;
+}
+function isPlanTierInsufficientError(status, body) {
+  return status === 403 && readApiErrorCode(body) === "PLAN_TIER_INSUFFICIENT";
+}
+function handleHttpError(status, logger, retryDelaySeconds) {
+  if (status === 401 || status === 403) {
+    if (!authErrorLogged) {
+      authErrorLogged = true;
+      const errorMsg = "[multicorn-shield] ERROR: Authentication failed. Your MULTICORN_API_KEY is invalid or expired. Check the key in your OpenClaw config (~/.openclaw/openclaw.json \u2192 plugins.entries.multicorn-shield.env.MULTICORN_API_KEY). Get a valid key from your Multicorn dashboard (Settings \u2192 API Keys).";
+      logger?.error(errorMsg);
+      process.stderr.write(`${errorMsg}
+`);
+    }
+    return { shouldBlock: true };
+  }
+  if (status === 429) {
+    if (retryDelaySeconds !== void 0) {
+      const rateLimitMsg = `[multicorn-shield] Rate limited by Shield API. Retrying in ${String(retryDelaySeconds)}s.`;
+      logger?.warn(rateLimitMsg);
+      process.stderr.write(`${rateLimitMsg}
+`);
+    } else {
+      const rateLimitMsg = "[multicorn-shield] Rate limited by Shield API. Action blocked: Shield cannot verify permissions.";
+      logger?.warn(rateLimitMsg);
+      process.stderr.write(`${rateLimitMsg}
+`);
+    }
+    return { shouldBlock: true };
   }
-  if (scope.service === "public_content" && scope.permissionLevel === "create") {
-    return true;
+  if (status >= 500 && status < 600) {
+    const serverErrorMsg = `[multicorn-shield] Shield API error (${String(status)}). Action blocked: Shield cannot verify permissions.`;
+    logger?.warn(serverErrorMsg);
+    process.stderr.write(`${serverErrorMsg}
+`);
+    return { shouldBlock: true };
   }
-  return false;
+  return { shouldBlock: true };
 }
-function isPublicContentAction(toolName, service) {
-  const lowerToolName = toolName.toLowerCase();
-  const lowerService = service.toLowerCase();
-  if (lowerService === "web" || lowerService === "public_content") {
-    return true;
+async function pollContentReviewStatus(reviewId, apiKey, baseUrl, logger) {
+  const startTime = Date.now();
+  const logDebug = logger?.debug?.bind(logger);
+  for (let pollCount = 0; pollCount < MAX_POLLS; pollCount++) {
+    if (Date.now() - startTime >= POLL_TIMEOUT_MS) {
+      return { status: "timeout", reason: "decision_window_exceeded", reviewId };
+    }
+    let row = null;
+    for (let retry = 0; retry < 3; retry++) {
+      try {
+        const response = await fetch(`${baseUrl}/api/v1/content-reviews/${reviewId}/status`, {
+          headers: { [AUTH_HEADER]: apiKey },
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+        });
+        if (!response.ok) {
+          if (response.status === 404) {
+            return { status: "blocked", reason: "review_not_found", reviewId };
+          }
+          const errBody = await response.json().catch(() => null);
+          if (isPlanTierInsufficientError(response.status, errBody)) {
+            return { status: "blocked", reason: "plan_tier_insufficient", reviewId };
+          }
+          if (response.status === 401 || response.status === 403) {
+            handleHttpError(response.status, logger);
+            return { status: "blocked", reason: "auth_error", reviewId };
+          }
+          if (response.status === 429 || response.status >= 500 && response.status < 600) {
+            const retryDelay = retry < 2 ? Math.pow(2, retry) : void 0;
+            handleHttpError(response.status, logger, retryDelay);
+          }
+          logDebug?.(
+            `Content review poll ${String(pollCount + 1)} failed: HTTP ${String(response.status)}. Retrying...`
+          );
+          if (retry < 2) {
+            await new Promise((resolve) => setTimeout(resolve, 1e3 * Math.pow(2, retry)));
+          }
+          continue;
+        }
+        const body = await response.json();
+        if (!isApiSuccess(body)) {
+          logDebug?.(
+            `Content review poll ${String(pollCount + 1)} failed: invalid response format. Retrying...`
+          );
+          if (retry < 2) {
+            await new Promise((resolve) => setTimeout(resolve, 1e3 * Math.pow(2, retry)));
+          }
+          continue;
+        }
+        const statusData = body.data;
+        if (!isContentReviewStatusResponse(statusData)) {
+          logDebug?.(
+            `Content review poll ${String(pollCount + 1)} failed: invalid status data. Retrying...`
+          );
+          if (retry < 2) {
+            await new Promise((resolve) => setTimeout(resolve, 1e3 * Math.pow(2, retry)));
+          }
+          continue;
+        }
+        row = statusData;
+        break;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logDebug?.(
+          `Content review poll ${String(pollCount + 1)} failed: ${errorMessage}. Retrying...`
+        );
+        if (retry < 2) {
+          await new Promise((resolve) => setTimeout(resolve, 1e3 * Math.pow(2, retry)));
+        }
+      }
+    }
+    if (row !== null) {
+      if (row.status === "approved") {
+        return { status: "approved", reviewId };
+      }
+      if (row.status === "blocked") {
+        return { status: "blocked", reason: "blocked_by_reviewer", reviewId };
+      }
+      if (row.status === "timeout") {
+        return { status: "timeout", reason: "decision_window_exceeded", reviewId };
+      }
+      if (pollCount < MAX_POLLS - 1) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      }
+    } else {
+      logDebug?.(
+        `All retries failed for content review poll ${String(pollCount + 1)}. Continuing...`
+      );
+      if (pollCount < MAX_POLLS - 1) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      }
+    }
+  }
+  return { status: "timeout", reason: "decision_window_exceeded", reviewId };
+}
+async function requestContentReview(payload, apiKey, baseUrl, logger) {
+  try {
+    const response = await fetch(`${baseUrl}/api/v1/actions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        [AUTH_HEADER]: apiKey
+      },
+      body: JSON.stringify({
+        agent: payload.agent,
+        service: payload.service,
+        actionType: payload.actionType,
+        status: "requires_approval",
+        cost: payload.cost ?? 0,
+        metadata: payload.metadata
+      }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+    const body = await response.json().catch(() => null);
+    if (isPlanTierInsufficientError(response.status, body)) {
+      return { status: "blocked", reason: "plan_tier_insufficient" };
+    }
+    if (response.status === 401 || response.status === 403) {
+      handleHttpError(response.status, logger);
+      return { status: "blocked", reason: "auth_error" };
+    }
+    if (response.status === 429 || response.status >= 500 && response.status < 600) {
+      handleHttpError(response.status, logger);
+      return { status: "blocked", reason: "service_unavailable" };
+    }
+    if (response.status === 202) {
+      if (!isApiSuccess(body)) {
+        return { status: "blocked", reason: "no_review_id" };
+      }
+      const data = body.data;
+      if (typeof data !== "object" || data === null) {
+        return { status: "blocked", reason: "no_review_id" };
+      }
+      const record = data;
+      const rid = record["content_review_id"];
+      const reviewId = typeof rid === "string" ? rid : void 0;
+      if (reviewId === void 0) {
+        return { status: "blocked", reason: "no_review_id" };
+      }
+      const polled = await pollContentReviewStatus(reviewId, apiKey, baseUrl, logger);
+      return { ...polled, reviewId };
+    }
+    if (response.status === 201) {
+      return { status: "blocked", reason: "no_review_id" };
+    }
+    return { status: "blocked", reason: "service_unavailable" };
+  } catch {
+    return { status: "blocked", reason: "network_error" };
   }
-  const publicContentIndicators = [
-    "publish",
-    "public",
-    "web",
-    "blog",
-    "post",
-    "article",
-    "social",
-    "twitter",
-    "facebook",
-    "linkedin",
-    "github_pages",
-    "deploy"
-  ];
-  return publicContentIndicators.some((indicator) => lowerToolName.includes(indicator));
 }
 
 // src/mcp/mcp-adapter.ts
@@ -1985,6 +2196,28 @@ function createMcpAdapter(config) {
       status
     });
   }
+  function mapContentReviewReasonToUserMessage(reason) {
+    switch (reason) {
+      case "plan_tier_insufficient":
+        return "Content review requires an Enterprise plan. Upgrade at app.multicorn.ai/settings.";
+      case "review_not_found":
+        return "Content review no longer exists. It may have been deleted or timed out.";
+      case "decision_window_exceeded":
+        return "Content review timed out before a decision was made.";
+      case "blocked_by_reviewer":
+        return "Content review was blocked by a reviewer.";
+      case "auth_error":
+        return "Content review failed: please verify your Multicorn API key.";
+      case "service_unavailable":
+        return "Content review failed: service unavailable.";
+      case "network_error":
+        return "Content review failed: network error.";
+      case "no_review_id":
+        return "Content review failed: could not start review.";
+      default:
+        return "Content review failed.";
+    }
+  }
   async function checkAutoApproveStatus() {
     if (config.checkAutoApprove !== void 0) {
       const result = config.checkAutoApprove(config.agentId);
@@ -2054,6 +2287,38 @@ function createMcpAdapter(config) {
             arguments: JSON.stringify(toolCall.arguments),
             requiresReview: true
           };
+          if (config.waitForReviewDecision === true) {
+            if (config.baseUrl === void 0 || config.apiKey === void 0) {
+              return {
+                blocked: true,
+                reason: "waitForReviewDecision requires baseUrl and apiKey to poll the content review.",
+                toolName: toolCall.toolName,
+                service: mappedService,
+                action
+              };
+            }
+            const review = await requestContentReview(
+              {
+                agent: config.agentId,
+                service: mappedService,
+                actionType: action,
+                metadata
+              },
+              config.apiKey,
+              config.baseUrl
+            );
+            if (review.status === "approved") {
+              await recordAction(mappedService, action, ACTION_STATUSES.Approved);
+              return handler(toolCall);
+            }
+            return {
+              blocked: true,
+              reason: mapContentReviewReasonToUserMessage(review.reason),
+              toolName: toolCall.toolName,
+              service: mappedService,
+              action
+            };
+          }
           if (config.logger) {
             await config.logger.logAction({
               agent: config.agentId,
@@ -2503,9 +2768,12 @@ exports.getServiceDisplayName = getServiceDisplayName;
 exports.getServiceIcon = getServiceIcon;
 exports.hasScope = hasScope;
 exports.isBlockedResult = isBlockedResult;
+exports.isPublicContentAction = isPublicContentAction;
 exports.isValidScopeString = isValidScopeString;
 exports.parseScope = parseScope;
 exports.parseScopes = parseScopes;
+exports.requestContentReview = requestContentReview;
+exports.requiresContentReview = requiresContentReview;
 exports.tryParseScope = tryParseScope;
 exports.validateAllScopesAccess = validateAllScopesAccess;
 exports.validateScopeAccess = validateScopeAccess;

package/dist/index.d.cts

@@ -652,6 +652,42 @@ declare function validateAllScopesAccess(grantedScopes: readonly Scope[], reques
  */
 declare function hasScope(grantedScopes: readonly Scope[], requested: Scope): boolean;
 
+/**
+ * Detects if a scope requires content review before execution.
+ *
+ * Public content scopes that require review:
+ * - `publish:web` - publishing content to the web
+ * - `create:public_content` - creating public-facing content
+ *
+ * @module scopes/content-review-detector
+ */
+
+/**
+ * Check if a scope requires content review.
+ *
+ * @param scope - The scope to check
+ * @returns `true` if the scope requires content review
+ *
+ * @example
+ * ```ts
+ * requiresContentReview({ service: "web", permissionLevel: "publish" }); // true
+ * requiresContentReview({ service: "public_content", permissionLevel: "create" }); // true
+ * requiresContentReview({ service: "gmail", permissionLevel: "execute" }); // false
+ * ```
+ */
+declare function requiresContentReview(scope: Scope): boolean;
+/**
+ * Check if a tool name/action indicates public content creation.
+ *
+ * This is a helper for cases where the service might not be explicitly
+ * "web" or "public_content" but the action name indicates public content.
+ *
+ * @param toolName - The tool name to check
+ * @param service - The service name
+ * @returns `true` if the tool/action indicates public content
+ */
+declare function isPublicContentAction(toolName: string, service: string): boolean;
+
 /**
  * Custom element tag name for the consent component.
  */
@@ -1775,6 +1811,11 @@ interface McpAdapterConfig {
      * Used with baseUrl to fetch auto-approval status if checkAutoApprove is not provided.
      */
     readonly apiKey?: string;
+    /**
+     * When `true`, blocks until the content review completes (or times out) and forwards the tool call if approved.
+     * Requires `baseUrl` and `apiKey`. Default `false` preserves the existing fast block with `requires_approval` logging only.
+     */
+    readonly waitForReviewDecision?: boolean;
 }
 /**
  * The MCP adapter produced by {@link createMcpAdapter}.
@@ -2179,4 +2220,67 @@ declare class MulticornShield {
     destroy(): void;
 }
 
-export { ACTION_STATUSES, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isValidScopeString, parseScope, parseScopes, tryParseScope, validateAllScopesAccess, validateScopeAccess };
+/**
+ * Local type definitions for the OpenClaw Plugin SDK.
+ *
+ * Extracted from openclaw/dist/plugin-sdk/plugins/types.d.ts (v2026.2.26).
+ * We define only the subset needed for the Shield plugin so there's no
+ * build-time dependency on the OpenClaw package itself.
+ *
+ * @module openclaw/plugin-sdk.types
+ */
+interface PluginLogger {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+
+/**
+ * HTTP client for communicating with the Multicorn Shield API.
+ *
+ * Handles agent registration, permission fetching, and action logging.
+ * Follows the same patterns as the MCP proxy client but is self-contained
+ * so the hook has no runtime dependency on proxy internals.
+ *
+ * Security: the API key is passed as a parameter and sent only via the
+ * `X-Multicorn-Key` header over HTTPS. It is never logged or written
+ * to disk.
+ *
+ * @module openclaw/shield-client
+ */
+
+/**
+ * `data` shape from GET /api/v1/content-reviews/:id/status when `success` is true.
+ */
+interface ContentReviewStatusResponse {
+    readonly id: string;
+    readonly status: "pending" | "approved" | "blocked" | "timeout";
+}
+/**
+ * Result of {@link requestContentReview} or {@link pollContentReviewStatus}.
+ */
+interface ContentReviewResult {
+    readonly status: "approved" | "blocked" | "timeout";
+    readonly reviewId?: string;
+    readonly reason?: string;
+}
+/**
+ * Payload for {@link requestContentReview}. `cost` is optional; the POST body always includes `cost`, defaulting to `0` when omitted (matches {@link LogActionRequest} in the service).
+ */
+interface ContentReviewRequestPayload {
+    readonly agent: string;
+    readonly service: string;
+    readonly actionType: string;
+    /** Defaults to `0` when omitted. Must be >= 0 if set. */
+    readonly cost?: number;
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+/**
+ * Create a content-review request via POST /api/v1/actions with `status: "requires_approval"`, then poll until decided.
+ *
+ * Wire format: response `data.content_review_id` (snake_case) per service Jackson naming.
+ */
+declare function requestContentReview(payload: ContentReviewRequestPayload, apiKey: string, baseUrl: string, logger?: PluginLogger): Promise<ContentReviewResult>;
+
+export { ACTION_STATUSES, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type ContentReviewRequestPayload, type ContentReviewResult, type ContentReviewStatusResponse, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };

package/dist/index.d.ts

@@ -652,6 +652,42 @@ declare function validateAllScopesAccess(grantedScopes: readonly Scope[], reques
  */
 declare function hasScope(grantedScopes: readonly Scope[], requested: Scope): boolean;
 
+/**
+ * Detects if a scope requires content review before execution.
+ *
+ * Public content scopes that require review:
+ * - `publish:web` - publishing content to the web
+ * - `create:public_content` - creating public-facing content
+ *
+ * @module scopes/content-review-detector
+ */
+
+/**
+ * Check if a scope requires content review.
+ *
+ * @param scope - The scope to check
+ * @returns `true` if the scope requires content review
+ *
+ * @example
+ * ```ts
+ * requiresContentReview({ service: "web", permissionLevel: "publish" }); // true
+ * requiresContentReview({ service: "public_content", permissionLevel: "create" }); // true
+ * requiresContentReview({ service: "gmail", permissionLevel: "execute" }); // false
+ * ```
+ */
+declare function requiresContentReview(scope: Scope): boolean;
+/**
+ * Check if a tool name/action indicates public content creation.
+ *
+ * This is a helper for cases where the service might not be explicitly
+ * "web" or "public_content" but the action name indicates public content.
+ *
+ * @param toolName - The tool name to check
+ * @param service - The service name
+ * @returns `true` if the tool/action indicates public content
+ */
+declare function isPublicContentAction(toolName: string, service: string): boolean;
+
 /**
  * Custom element tag name for the consent component.
  */
@@ -1775,6 +1811,11 @@ interface McpAdapterConfig {
      * Used with baseUrl to fetch auto-approval status if checkAutoApprove is not provided.
      */
     readonly apiKey?: string;
+    /**
+     * When `true`, blocks until the content review completes (or times out) and forwards the tool call if approved.
+     * Requires `baseUrl` and `apiKey`. Default `false` preserves the existing fast block with `requires_approval` logging only.
+     */
+    readonly waitForReviewDecision?: boolean;
 }
 /**
  * The MCP adapter produced by {@link createMcpAdapter}.
@@ -2179,4 +2220,67 @@ declare class MulticornShield {
     destroy(): void;
 }
 
-export { ACTION_STATUSES, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isValidScopeString, parseScope, parseScopes, tryParseScope, validateAllScopesAccess, validateScopeAccess };
+/**
+ * Local type definitions for the OpenClaw Plugin SDK.
+ *
+ * Extracted from openclaw/dist/plugin-sdk/plugins/types.d.ts (v2026.2.26).
+ * We define only the subset needed for the Shield plugin so there's no
+ * build-time dependency on the OpenClaw package itself.
+ *
+ * @module openclaw/plugin-sdk.types
+ */
+interface PluginLogger {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+
+/**
+ * HTTP client for communicating with the Multicorn Shield API.
+ *
+ * Handles agent registration, permission fetching, and action logging.
+ * Follows the same patterns as the MCP proxy client but is self-contained
+ * so the hook has no runtime dependency on proxy internals.
+ *
+ * Security: the API key is passed as a parameter and sent only via the
+ * `X-Multicorn-Key` header over HTTPS. It is never logged or written
+ * to disk.
+ *
+ * @module openclaw/shield-client
+ */
+
+/**
+ * `data` shape from GET /api/v1/content-reviews/:id/status when `success` is true.
+ */
+interface ContentReviewStatusResponse {
+    readonly id: string;
+    readonly status: "pending" | "approved" | "blocked" | "timeout";
+}
+/**
+ * Result of {@link requestContentReview} or {@link pollContentReviewStatus}.
+ */
+interface ContentReviewResult {
+    readonly status: "approved" | "blocked" | "timeout";
+    readonly reviewId?: string;
+    readonly reason?: string;
+}
+/**
+ * Payload for {@link requestContentReview}. `cost` is optional; the POST body always includes `cost`, defaulting to `0` when omitted (matches {@link LogActionRequest} in the service).
+ */
+interface ContentReviewRequestPayload {
+    readonly agent: string;
+    readonly service: string;
+    readonly actionType: string;
+    /** Defaults to `0` when omitted. Must be >= 0 if set. */
+    readonly cost?: number;
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+/**
+ * Create a content-review request via POST /api/v1/actions with `status: "requires_approval"`, then poll until decided.
+ *
+ * Wire format: response `data.content_review_id` (snake_case) per service Jackson naming.
+ */
+declare function requestContentReview(payload: ContentReviewRequestPayload, apiKey: string, baseUrl: string, logger?: PluginLogger): Promise<ContentReviewResult>;
+
+export { ACTION_STATUSES, AGENT_STATUSES, type Action, type ActionInput, type ActionLogger, type ActionLoggerConfig, type ActionPayload, type ActionStatus, type Agent, type AgentStatus, type ApiError, BUILT_IN_SERVICES, type BatchModeConfig, type BuiltInServiceName, CONSENT_ELEMENT_TAG, type ConsentDecision, type ConsentDeniedEventDetail, type ConsentEventDetail, type ConsentEventMap, type ConsentEventName, type ConsentGrantedEventDetail, type ConsentOptions, type ConsentPartialEventDetail, type ContentReviewRequestPayload, type ContentReviewResult, type ContentReviewStatusResponse, type FocusTrap, type McpAdapter, type McpAdapterConfig, type McpAdapterResult, type McpBlockedResult, type McpToolCall, type McpToolHandler, type McpToolResult, MulticornConsent, MulticornShield, type MulticornShieldConfig, PERMISSION_LEVELS, type Permission, type PermissionLevel, type RemainingBudget, SERVICE_NAME_PATTERN, type Scope, ScopeParseError, type ScopeParseResult, type ScopeRegistry, type ScopeRequest, type ServiceDefinition, type SpendCheckResult, type SpendingCheckResult, type SpendingChecker, type SpendingLimit, type SpendingLimits, type SpendingTrackerConfig, type ValidationResult, centsToDollars, createActionLogger, createFocusTrap, createMcpAdapter, createScopeRegistry, createSpendingChecker, dollarsToCents, formatScope, getPermissionLabel, getScopeLabel, getScopeShortLabel, getServiceDisplayName, getServiceIcon, hasScope, isBlockedResult, isPublicContentAction, isValidScopeString, parseScope, parseScopes, requestContentReview, requiresContentReview, tryParseScope, validateAllScopesAccess, validateScopeAccess };