@plasius/ai-mcp 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -18,6 +18,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - **Security**
   - (placeholder)
 
+## [0.1.4] - 2026-06-22
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.1.3] - 2026-05-20
+
+- **Added**
+  - Added MCP tool risk classes, actor-role-based allowlist resolution, and audit metadata.
+  - Added deterministic tool-allowlist result contracts with blocked/allowed reason codes.
+
+- **Changed**
+  - Updated the MCP feature flag to align with family orchestration gating.
+
+- **Fixed**
+  - Release automation now prepares version/changelog updates on a release PR before publishing from protected `main`.
+  - (placeholder)
+
+- **Security**
+  - Added restricted tool blocking and unsafe-role risk gating for safer MCP defaults.
+  - Sensitive tools are now denied for player roles unless an operator/admin context authorizes them.
+
 ## [0.1.2] - 2026-05-13
 
 - **Added**
@@ -38,5 +69,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Added initial public package scaffold with governance, legal, docs, build, test, and pack-check baselines.
 
 
-[0.1.1]: https://github.com/Plasius-LTD/ai-mcp/releases/tag/v0.1.1
 [0.1.2]: https://github.com/Plasius-LTD/ai-mcp/releases/tag/v0.1.2
+[0.1.1]: https://github.com/Plasius-LTD/ai-mcp/releases/tag/v0.1.1
+[0.1.3]: https://github.com/Plasius-LTD/ai-mcp/releases/tag/v0.1.3
+[0.1.4]: https://github.com/Plasius-LTD/ai-mcp/releases/tag/v0.1.4

package/README.md

@@ -1,10 +1,10 @@
 # @plasius/ai-mcp
 
-MCP tool registry, per-call allowlist, and tool audit contracts for Plasius agentic AI.
+MCP tool registry, per-call allowlist, and tool audit contracts for Plasius AI orchestration.
 
 ## Scope
 
-This package is part of the layered `@plasius/ai-*` package family. It is intentionally bootstrapped with a small public contract surface so implementation can evolve behind tracked Feature/Story/Task work.
+This package is part of the layered `@plasius/ai-*` package family. It defines the external contracts for MCP tool registration, per-call allowlisting, role-gated risk decisions, and audit metadata.
 
 ## Install
 
@@ -12,12 +12,43 @@ This package is part of the layered `@plasius/ai-*` package family. It is intent
 npm install @plasius/ai-mcp
 ```
 
+## Contracts
+
+- `AI_MCP_FEATURE_FLAGS` declares the feature flags that gate MCP behavior.
+- `resolveAiMcpToolAllowlist` evaluates requested tool IDs against registry descriptors, feature flags, and actor roles.
+- `isAiMcpToolAllowed` and `isAiMcpToolRiskAllowed` provide lightweight policy predicates for callers.
+- `packageDescriptor` exposes package name, primary flag, env prefix, and summary.
+
 ## Usage
 
 ```ts
-import { packageDescriptor } from "@plasius/ai-mcp";
+import {
+  AI_MCP_FEATURE_FLAGS,
+  resolveAiMcpToolAllowlist,
+} from "@plasius/ai-mcp";
+
+const result = resolveAiMcpToolAllowlist({
+  requestedTools: ["rag.search", "admin.kill-switch"],
+  actorRole: "operator",
+  featureFlags: {
+    [AI_MCP_FEATURE_FLAGS.mcp]: true,
+  },
+  toolRegistry: [
+    {
+      toolId: "rag.search",
+      toolName: "RAG Search",
+      riskClass: "safe",
+    },
+    {
+      toolId: "admin.kill-switch",
+      toolName: "Admin Kill Switch",
+      riskClass: "restricted",
+    },
+  ],
+});
 
-console.log(packageDescriptor.packageName);
+console.log(result.allowedTools);
+console.log(result.blockedTools);
 ```
 
 ## Development
@@ -30,6 +61,14 @@ npm run test:coverage
 npm run pack:check
 ```
 
+## Release Workflow
+
+Protected `main` releases use a two-step flow:
+
+1. Run `.github/workflows/cd.yml` with `bump=patch|minor|major` to open or refresh a `release/vX.Y.Z` prep PR.
+2. Merge that PR to `main`.
+3. Rerun `.github/workflows/cd.yml` on `main` with `bump=none` to tag, draft the GitHub release, and publish to npm.
+
 ## Governance
 
 - Security policy: [SECURITY.md](./SECURITY.md)

package/dist/index.cjs

@@ -21,25 +21,165 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AI_MCP_ENV_PREFIX: () => AI_MCP_ENV_PREFIX,
+  AI_MCP_FEATURE_FLAGS: () => AI_MCP_FEATURE_FLAGS,
   AI_MCP_FEATURE_FLAG_ID: () => AI_MCP_FEATURE_FLAG_ID,
   AI_MCP_PACKAGE: () => AI_MCP_PACKAGE,
-  packageDescriptor: () => packageDescriptor
+  AI_MCP_RESOLUTION_SOURCES: () => AI_MCP_RESOLUTION_SOURCES,
+  AI_MCP_TOOL_RISK_CLASSES: () => AI_MCP_TOOL_RISK_CLASSES,
+  AI_MCP_TOOL_ROLES: () => AI_MCP_TOOL_ROLES,
+  isAiMcpToolAllowed: () => isAiMcpToolAllowed,
+  isAiMcpToolRiskAllowed: () => isAiMcpToolRiskAllowed,
+  packageDescriptor: () => packageDescriptor,
+  resolveAiMcpToolAllowlist: () => resolveAiMcpToolAllowlist
 });
 module.exports = __toCommonJS(index_exports);
 var AI_MCP_PACKAGE = "@plasius/ai-mcp";
-var AI_MCP_FEATURE_FLAG_ID = "ai.mcp.enabled";
+var AI_MCP_FEATURE_FLAG_ID = "ai.mcp-rag.enabled";
 var AI_MCP_ENV_PREFIX = "AI_MCP";
+var AI_MCP_FEATURE_FLAGS = {
+  mcp: AI_MCP_FEATURE_FLAG_ID
+};
+var AI_MCP_TOOL_RISK_CLASSES = [
+  "safe",
+  "sensitive",
+  "privileged",
+  "restricted"
+];
+var AI_MCP_TOOL_ROLES = ["system", "admin", "operator", "player"];
+var AI_MCP_RESOLUTION_SOURCES = [
+  "policy",
+  "policy-disabled",
+  "policy-allow-empty"
+];
+function nowIsoString() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function normalizeToolIds(values) {
+  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);
+  return Array.from(new Set(normalized));
+}
+function isAiMcpFeatureEnabled(featureFlag, snapshot = {}) {
+  return snapshot[featureFlag] === true;
+}
+function isAllowedForRole(riskClass, role) {
+  if (role === "system") {
+    return true;
+  }
+  if (riskClass === "safe") {
+    return true;
+  }
+  if (riskClass === "restricted") {
+    return false;
+  }
+  if (riskClass === "privileged") {
+    return role === "admin" || role === "operator";
+  }
+  return role === "admin" || role === "operator";
+}
+function resolveAiMcpToolAllowlist(input) {
+  const featureEnabled = isAiMcpFeatureEnabled(
+    AI_MCP_FEATURE_FLAGS.mcp,
+    input.featureFlags
+  );
+  const actorRole = input.actorRole ?? "player";
+  const requestedTools = normalizeToolIds(input.requestedTools);
+  const featureFlagIds = featureEnabled ? [AI_MCP_FEATURE_FLAGS.mcp] : [];
+  const reasonCodes = [...input.reasonCodes ?? []];
+  const registryById = new Map(
+    (input.toolRegistry ?? []).map((tool) => [tool.toolId, tool])
+  );
+  if (!featureEnabled) {
+    reasonCodes.push("mcp-feature-disabled");
+    return {
+      requestedTools,
+      allowedTools: [],
+      blockedTools: requestedTools,
+      needsEscalation: true,
+      reasonCodes,
+      source: "policy-disabled",
+      enabledFeatureFlags: featureFlagIds,
+      audit: {
+        policyId: input.policyId ?? "mcp-policy-v1",
+        policyVersion: input.policyVersion ?? "2026-05-01",
+        correlationId: input.correlationId ?? crypto.randomUUID(),
+        requestId: input.requestId,
+        actorId: input.actorId,
+        actorRole,
+        evaluatedAtUtc: nowIsoString(),
+        result: "deny"
+      }
+    };
+  }
+  const allowedTools = [];
+  const blockedTools = [];
+  for (const requestedTool of requestedTools) {
+    const tool = registryById.get(requestedTool);
+    if (!tool) {
+      blockedTools.push(requestedTool);
+      reasonCodes.push(`tool-not-registered:${requestedTool}`);
+      continue;
+    }
+    if (!isAllowedForRole(tool.riskClass, actorRole)) {
+      blockedTools.push(requestedTool);
+      reasonCodes.push(`tool-risk-restricted:${requestedTool}`);
+      continue;
+    }
+    allowedTools.push(requestedTool);
+  }
+  if (allowedTools.length === 0) {
+    reasonCodes.push("mcp-allowlist-deny-all");
+  }
+  if (requestedTools.length === 0) {
+    reasonCodes.push("mcp-allowlist-empty-request");
+  }
+  return {
+    requestedTools,
+    allowedTools,
+    blockedTools,
+    needsEscalation: blockedTools.length > 0 && allowedTools.length > 0,
+    reasonCodes,
+    source: requestedTools.length > 0 ? "policy" : "policy-allow-empty",
+    enabledFeatureFlags: featureFlagIds,
+    audit: {
+      policyId: input.policyId ?? "mcp-policy-v1",
+      policyVersion: input.policyVersion ?? "2026-05-01",
+      correlationId: input.correlationId ?? crypto.randomUUID(),
+      requestId: input.requestId,
+      actorId: input.actorId,
+      actorRole,
+      evaluatedAtUtc: nowIsoString(),
+      result: blockedTools.length === requestedTools.length ? "deny" : blockedTools.length > 0 ? "escalate" : "allow"
+    }
+  };
+}
+function isAiMcpToolRiskAllowed(riskClass, actorRole) {
+  return isAllowedForRole(riskClass, actorRole);
+}
+function isAiMcpToolAllowed(toolId, actorRole, registry) {
+  const tool = registry.find((candidate) => candidate.toolId === toolId);
+  if (!tool) {
+    return false;
+  }
+  return isAllowedForRole(tool.riskClass, actorRole);
+}
 var packageDescriptor = Object.freeze({
   packageName: AI_MCP_PACKAGE,
   featureFlagId: AI_MCP_FEATURE_FLAG_ID,
   envPrefix: AI_MCP_ENV_PREFIX,
-  summary: "MCP tool registry, per-call allowlist, and tool audit contracts for Plasius agentic AI."
+  summary: "MCP tool registry, per-call allowlist, and audit contracts for Plasius AI orchestration."
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AI_MCP_ENV_PREFIX,
+  AI_MCP_FEATURE_FLAGS,
   AI_MCP_FEATURE_FLAG_ID,
   AI_MCP_PACKAGE,
-  packageDescriptor
+  AI_MCP_RESOLUTION_SOURCES,
+  AI_MCP_TOOL_RISK_CLASSES,
+  AI_MCP_TOOL_ROLES,
+  isAiMcpToolAllowed,
+  isAiMcpToolRiskAllowed,
+  packageDescriptor,
+  resolveAiMcpToolAllowlist
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n  readonly packageName: string;\n  readonly featureFlagId: string;\n  readonly envPrefix: string;\n  readonly summary: string;\n}\n\nexport const AI_MCP_PACKAGE = \"@plasius/ai-mcp\";\nexport const AI_MCP_FEATURE_FLAG_ID = \"ai.mcp.enabled\";\nexport const AI_MCP_ENV_PREFIX = \"AI_MCP\";\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n  packageName: AI_MCP_PACKAGE,\n  featureFlagId: AI_MCP_FEATURE_FLAG_ID,\n  envPrefix: AI_MCP_ENV_PREFIX,\n  summary: \"MCP tool registry, per-call allowlist, and tool audit contracts for Plasius agentic AI.\",\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOO,IAAM,iBAAiB;AACvB,IAAM,yBAAyB;AAC/B,IAAM,oBAAoB;AAE1B,IAAM,oBAAyC,OAAO,OAAO;AAAA,EAClE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SAAS;AACX,CAAC;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n  readonly packageName: string;\n  readonly featureFlagId: string;\n  readonly envPrefix: string;\n  readonly summary: string;\n}\n\nexport const AI_MCP_PACKAGE = \"@plasius/ai-mcp\";\nexport const AI_MCP_FEATURE_FLAG_ID = \"ai.mcp-rag.enabled\";\nexport const AI_MCP_ENV_PREFIX = \"AI_MCP\";\n\nexport const AI_MCP_FEATURE_FLAGS = {\n  mcp: AI_MCP_FEATURE_FLAG_ID,\n} as const;\n\nexport type AiMcpFeatureFlagKey =\n  (typeof AI_MCP_FEATURE_FLAGS)[keyof typeof AI_MCP_FEATURE_FLAGS];\n\nexport type AiMcpFeatureFlagSnapshot = Readonly<\n  Record<string, boolean | undefined>\n>;\n\nexport const AI_MCP_TOOL_RISK_CLASSES = [\n  \"safe\",\n  \"sensitive\",\n  \"privileged\",\n  \"restricted\",\n] as const;\n\nexport type AiMcpToolRiskClass = (typeof AI_MCP_TOOL_RISK_CLASSES)[number];\n\nexport const AI_MCP_TOOL_ROLES = [\"system\", \"admin\", \"operator\", \"player\"] as const;\n\nexport type AiMcpActorRole = (typeof AI_MCP_TOOL_ROLES)[number];\n\nexport const AI_MCP_RESOLUTION_SOURCES = [\n  \"policy\",\n  \"policy-disabled\",\n  \"policy-allow-empty\",\n] as const;\n\nexport type AiMcpResolutionSource = (typeof AI_MCP_RESOLUTION_SOURCES)[number];\n\nexport interface AiMcpToolDescriptor {\n  readonly toolId: string;\n  readonly toolName: string;\n  readonly riskClass: AiMcpToolRiskClass;\n  readonly description?: string;\n}\n\nexport interface AiMcpAuditMetadata {\n  readonly policyId: string;\n  readonly policyVersion: string;\n  readonly correlationId: string;\n  readonly requestId?: string;\n  readonly actorId?: string;\n  readonly actorRole: AiMcpActorRole;\n  readonly evaluatedAtUtc: string;\n  readonly result: \"allow\" | \"deny\" | \"escalate\";\n}\n\nexport interface ResolveAiMcpToolAllowlistInput {\n  readonly requestedTools: readonly string[];\n  readonly featureFlags?: AiMcpFeatureFlagSnapshot;\n  readonly toolRegistry?: readonly AiMcpToolDescriptor[];\n  readonly actorRole?: AiMcpActorRole;\n  readonly requestId?: string;\n  readonly actorId?: string;\n  readonly correlationId?: string;\n  readonly policyId?: string;\n  readonly policyVersion?: string;\n  readonly reasonCodes?: readonly string[];\n}\n\nexport interface ResolveAiMcpToolAllowlistResult {\n  readonly requestedTools: readonly string[];\n  readonly allowedTools: readonly string[];\n  readonly blockedTools: readonly string[];\n  readonly needsEscalation: boolean;\n  readonly reasonCodes: readonly string[];\n  readonly source: AiMcpResolutionSource;\n  readonly enabledFeatureFlags: readonly AiMcpFeatureFlagKey[];\n  readonly audit: AiMcpAuditMetadata;\n}\n\nfunction nowIsoString(): string {\n  return new Date().toISOString();\n}\n\nfunction normalizeToolIds(values: readonly string[]): string[] {\n  const normalized = values\n    .map((value) => value.trim())\n    .filter((value) => value.length > 0);\n\n  return Array.from(new Set(normalized));\n}\n\nfunction isAiMcpFeatureEnabled(\n  featureFlag: AiMcpFeatureFlagKey,\n  snapshot: AiMcpFeatureFlagSnapshot = {}\n): boolean {\n  return snapshot[featureFlag] === true;\n}\n\nfunction isAllowedForRole(riskClass: AiMcpToolRiskClass, role: AiMcpActorRole): boolean {\n  if (role === \"system\") {\n    return true;\n  }\n\n  if (riskClass === \"safe\") {\n    return true;\n  }\n\n  if (riskClass === \"restricted\") {\n    return false;\n  }\n\n  if (riskClass === \"privileged\") {\n    return role === \"admin\" || role === \"operator\";\n  }\n\n  return role === \"admin\" || role === \"operator\";\n}\n\nexport function resolveAiMcpToolAllowlist(\n  input: ResolveAiMcpToolAllowlistInput\n): ResolveAiMcpToolAllowlistResult {\n  const featureEnabled = isAiMcpFeatureEnabled(\n    AI_MCP_FEATURE_FLAGS.mcp,\n    input.featureFlags\n  );\n  const actorRole: AiMcpActorRole = input.actorRole ?? \"player\";\n  const requestedTools = normalizeToolIds(input.requestedTools);\n  const featureFlagIds: AiMcpFeatureFlagKey[] = featureEnabled\n    ? [AI_MCP_FEATURE_FLAGS.mcp]\n    : [];\n\n  const reasonCodes = [...(input.reasonCodes ?? [])];\n  const registryById = new Map(\n    (input.toolRegistry ?? []).map((tool) => [tool.toolId, tool])\n  );\n\n  if (!featureEnabled) {\n    reasonCodes.push(\"mcp-feature-disabled\");\n\n    return {\n      requestedTools,\n      allowedTools: [],\n      blockedTools: requestedTools,\n      needsEscalation: true,\n      reasonCodes,\n      source: \"policy-disabled\",\n      enabledFeatureFlags: featureFlagIds,\n      audit: {\n        policyId: input.policyId ?? \"mcp-policy-v1\",\n        policyVersion: input.policyVersion ?? \"2026-05-01\",\n        correlationId: input.correlationId ?? crypto.randomUUID(),\n        requestId: input.requestId,\n        actorId: input.actorId,\n        actorRole,\n        evaluatedAtUtc: nowIsoString(),\n        result: \"deny\",\n      },\n    };\n  }\n\n  const allowedTools: string[] = [];\n  const blockedTools: string[] = [];\n\n  for (const requestedTool of requestedTools) {\n    const tool = registryById.get(requestedTool);\n\n    if (!tool) {\n      blockedTools.push(requestedTool);\n      reasonCodes.push(`tool-not-registered:${requestedTool}`);\n      continue;\n    }\n\n    if (!isAllowedForRole(tool.riskClass, actorRole)) {\n      blockedTools.push(requestedTool);\n      reasonCodes.push(`tool-risk-restricted:${requestedTool}`);\n      continue;\n    }\n\n    allowedTools.push(requestedTool);\n  }\n\n  if (allowedTools.length === 0) {\n    reasonCodes.push(\"mcp-allowlist-deny-all\");\n  }\n\n  if (requestedTools.length === 0) {\n    reasonCodes.push(\"mcp-allowlist-empty-request\");\n  }\n\n  return {\n    requestedTools,\n    allowedTools,\n    blockedTools,\n    needsEscalation: blockedTools.length > 0 && allowedTools.length > 0,\n    reasonCodes,\n    source: requestedTools.length > 0 ? \"policy\" : \"policy-allow-empty\",\n    enabledFeatureFlags: featureFlagIds,\n    audit: {\n      policyId: input.policyId ?? \"mcp-policy-v1\",\n      policyVersion: input.policyVersion ?? \"2026-05-01\",\n      correlationId: input.correlationId ?? crypto.randomUUID(),\n      requestId: input.requestId,\n      actorId: input.actorId,\n      actorRole,\n      evaluatedAtUtc: nowIsoString(),\n      result:\n        blockedTools.length === requestedTools.length\n          ? \"deny\"\n          : blockedTools.length > 0\n            ? \"escalate\"\n            : \"allow\",\n    },\n  };\n}\n\nexport function isAiMcpToolRiskAllowed(\n  riskClass: AiMcpToolRiskClass,\n  actorRole: AiMcpActorRole\n): boolean {\n  return isAllowedForRole(riskClass, actorRole);\n}\n\nexport function isAiMcpToolAllowed(\n  toolId: string,\n  actorRole: AiMcpActorRole,\n  registry: readonly AiMcpToolDescriptor[]\n): boolean {\n  const tool = registry.find((candidate) => candidate.toolId === toolId);\n\n  if (!tool) {\n    return false;\n  }\n\n  return isAllowedForRole(tool.riskClass, actorRole);\n}\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n  packageName: AI_MCP_PACKAGE,\n  featureFlagId: AI_MCP_FEATURE_FLAG_ID,\n  envPrefix: AI_MCP_ENV_PREFIX,\n  summary:\n    \"MCP tool registry, per-call allowlist, and audit contracts for Plasius AI orchestration.\",\n});\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -5,8 +5,60 @@ interface AiPackageDescriptor {
     readonly summary: string;
 }
 declare const AI_MCP_PACKAGE = "@plasius/ai-mcp";
-declare const AI_MCP_FEATURE_FLAG_ID = "ai.mcp.enabled";
+declare const AI_MCP_FEATURE_FLAG_ID = "ai.mcp-rag.enabled";
 declare const AI_MCP_ENV_PREFIX = "AI_MCP";
+declare const AI_MCP_FEATURE_FLAGS: {
+    readonly mcp: "ai.mcp-rag.enabled";
+};
+type AiMcpFeatureFlagKey = (typeof AI_MCP_FEATURE_FLAGS)[keyof typeof AI_MCP_FEATURE_FLAGS];
+type AiMcpFeatureFlagSnapshot = Readonly<Record<string, boolean | undefined>>;
+declare const AI_MCP_TOOL_RISK_CLASSES: readonly ["safe", "sensitive", "privileged", "restricted"];
+type AiMcpToolRiskClass = (typeof AI_MCP_TOOL_RISK_CLASSES)[number];
+declare const AI_MCP_TOOL_ROLES: readonly ["system", "admin", "operator", "player"];
+type AiMcpActorRole = (typeof AI_MCP_TOOL_ROLES)[number];
+declare const AI_MCP_RESOLUTION_SOURCES: readonly ["policy", "policy-disabled", "policy-allow-empty"];
+type AiMcpResolutionSource = (typeof AI_MCP_RESOLUTION_SOURCES)[number];
+interface AiMcpToolDescriptor {
+    readonly toolId: string;
+    readonly toolName: string;
+    readonly riskClass: AiMcpToolRiskClass;
+    readonly description?: string;
+}
+interface AiMcpAuditMetadata {
+    readonly policyId: string;
+    readonly policyVersion: string;
+    readonly correlationId: string;
+    readonly requestId?: string;
+    readonly actorId?: string;
+    readonly actorRole: AiMcpActorRole;
+    readonly evaluatedAtUtc: string;
+    readonly result: "allow" | "deny" | "escalate";
+}
+interface ResolveAiMcpToolAllowlistInput {
+    readonly requestedTools: readonly string[];
+    readonly featureFlags?: AiMcpFeatureFlagSnapshot;
+    readonly toolRegistry?: readonly AiMcpToolDescriptor[];
+    readonly actorRole?: AiMcpActorRole;
+    readonly requestId?: string;
+    readonly actorId?: string;
+    readonly correlationId?: string;
+    readonly policyId?: string;
+    readonly policyVersion?: string;
+    readonly reasonCodes?: readonly string[];
+}
+interface ResolveAiMcpToolAllowlistResult {
+    readonly requestedTools: readonly string[];
+    readonly allowedTools: readonly string[];
+    readonly blockedTools: readonly string[];
+    readonly needsEscalation: boolean;
+    readonly reasonCodes: readonly string[];
+    readonly source: AiMcpResolutionSource;
+    readonly enabledFeatureFlags: readonly AiMcpFeatureFlagKey[];
+    readonly audit: AiMcpAuditMetadata;
+}
+declare function resolveAiMcpToolAllowlist(input: ResolveAiMcpToolAllowlistInput): ResolveAiMcpToolAllowlistResult;
+declare function isAiMcpToolRiskAllowed(riskClass: AiMcpToolRiskClass, actorRole: AiMcpActorRole): boolean;
+declare function isAiMcpToolAllowed(toolId: string, actorRole: AiMcpActorRole, registry: readonly AiMcpToolDescriptor[]): boolean;
 declare const packageDescriptor: AiPackageDescriptor;
 
-export { AI_MCP_ENV_PREFIX, AI_MCP_FEATURE_FLAG_ID, AI_MCP_PACKAGE, type AiPackageDescriptor, packageDescriptor };
+export { AI_MCP_ENV_PREFIX, AI_MCP_FEATURE_FLAGS, AI_MCP_FEATURE_FLAG_ID, AI_MCP_PACKAGE, AI_MCP_RESOLUTION_SOURCES, AI_MCP_TOOL_RISK_CLASSES, AI_MCP_TOOL_ROLES, type AiMcpActorRole, type AiMcpAuditMetadata, type AiMcpFeatureFlagKey, type AiMcpFeatureFlagSnapshot, type AiMcpResolutionSource, type AiMcpToolDescriptor, type AiMcpToolRiskClass, type AiPackageDescriptor, type ResolveAiMcpToolAllowlistInput, type ResolveAiMcpToolAllowlistResult, isAiMcpToolAllowed, isAiMcpToolRiskAllowed, packageDescriptor, resolveAiMcpToolAllowlist };

package/dist/index.d.ts

@@ -5,8 +5,60 @@ interface AiPackageDescriptor {
     readonly summary: string;
 }
 declare const AI_MCP_PACKAGE = "@plasius/ai-mcp";
-declare const AI_MCP_FEATURE_FLAG_ID = "ai.mcp.enabled";
+declare const AI_MCP_FEATURE_FLAG_ID = "ai.mcp-rag.enabled";
 declare const AI_MCP_ENV_PREFIX = "AI_MCP";
+declare const AI_MCP_FEATURE_FLAGS: {
+    readonly mcp: "ai.mcp-rag.enabled";
+};
+type AiMcpFeatureFlagKey = (typeof AI_MCP_FEATURE_FLAGS)[keyof typeof AI_MCP_FEATURE_FLAGS];
+type AiMcpFeatureFlagSnapshot = Readonly<Record<string, boolean | undefined>>;
+declare const AI_MCP_TOOL_RISK_CLASSES: readonly ["safe", "sensitive", "privileged", "restricted"];
+type AiMcpToolRiskClass = (typeof AI_MCP_TOOL_RISK_CLASSES)[number];
+declare const AI_MCP_TOOL_ROLES: readonly ["system", "admin", "operator", "player"];
+type AiMcpActorRole = (typeof AI_MCP_TOOL_ROLES)[number];
+declare const AI_MCP_RESOLUTION_SOURCES: readonly ["policy", "policy-disabled", "policy-allow-empty"];
+type AiMcpResolutionSource = (typeof AI_MCP_RESOLUTION_SOURCES)[number];
+interface AiMcpToolDescriptor {
+    readonly toolId: string;
+    readonly toolName: string;
+    readonly riskClass: AiMcpToolRiskClass;
+    readonly description?: string;
+}
+interface AiMcpAuditMetadata {
+    readonly policyId: string;
+    readonly policyVersion: string;
+    readonly correlationId: string;
+    readonly requestId?: string;
+    readonly actorId?: string;
+    readonly actorRole: AiMcpActorRole;
+    readonly evaluatedAtUtc: string;
+    readonly result: "allow" | "deny" | "escalate";
+}
+interface ResolveAiMcpToolAllowlistInput {
+    readonly requestedTools: readonly string[];
+    readonly featureFlags?: AiMcpFeatureFlagSnapshot;
+    readonly toolRegistry?: readonly AiMcpToolDescriptor[];
+    readonly actorRole?: AiMcpActorRole;
+    readonly requestId?: string;
+    readonly actorId?: string;
+    readonly correlationId?: string;
+    readonly policyId?: string;
+    readonly policyVersion?: string;
+    readonly reasonCodes?: readonly string[];
+}
+interface ResolveAiMcpToolAllowlistResult {
+    readonly requestedTools: readonly string[];
+    readonly allowedTools: readonly string[];
+    readonly blockedTools: readonly string[];
+    readonly needsEscalation: boolean;
+    readonly reasonCodes: readonly string[];
+    readonly source: AiMcpResolutionSource;
+    readonly enabledFeatureFlags: readonly AiMcpFeatureFlagKey[];
+    readonly audit: AiMcpAuditMetadata;
+}
+declare function resolveAiMcpToolAllowlist(input: ResolveAiMcpToolAllowlistInput): ResolveAiMcpToolAllowlistResult;
+declare function isAiMcpToolRiskAllowed(riskClass: AiMcpToolRiskClass, actorRole: AiMcpActorRole): boolean;
+declare function isAiMcpToolAllowed(toolId: string, actorRole: AiMcpActorRole, registry: readonly AiMcpToolDescriptor[]): boolean;
 declare const packageDescriptor: AiPackageDescriptor;
 
-export { AI_MCP_ENV_PREFIX, AI_MCP_FEATURE_FLAG_ID, AI_MCP_PACKAGE, type AiPackageDescriptor, packageDescriptor };
+export { AI_MCP_ENV_PREFIX, AI_MCP_FEATURE_FLAGS, AI_MCP_FEATURE_FLAG_ID, AI_MCP_PACKAGE, AI_MCP_RESOLUTION_SOURCES, AI_MCP_TOOL_RISK_CLASSES, AI_MCP_TOOL_ROLES, type AiMcpActorRole, type AiMcpAuditMetadata, type AiMcpFeatureFlagKey, type AiMcpFeatureFlagSnapshot, type AiMcpResolutionSource, type AiMcpToolDescriptor, type AiMcpToolRiskClass, type AiPackageDescriptor, type ResolveAiMcpToolAllowlistInput, type ResolveAiMcpToolAllowlistResult, isAiMcpToolAllowed, isAiMcpToolRiskAllowed, packageDescriptor, resolveAiMcpToolAllowlist };

package/dist/index.js

@@ -1,17 +1,150 @@
 // src/index.ts
 var AI_MCP_PACKAGE = "@plasius/ai-mcp";
-var AI_MCP_FEATURE_FLAG_ID = "ai.mcp.enabled";
+var AI_MCP_FEATURE_FLAG_ID = "ai.mcp-rag.enabled";
 var AI_MCP_ENV_PREFIX = "AI_MCP";
+var AI_MCP_FEATURE_FLAGS = {
+  mcp: AI_MCP_FEATURE_FLAG_ID
+};
+var AI_MCP_TOOL_RISK_CLASSES = [
+  "safe",
+  "sensitive",
+  "privileged",
+  "restricted"
+];
+var AI_MCP_TOOL_ROLES = ["system", "admin", "operator", "player"];
+var AI_MCP_RESOLUTION_SOURCES = [
+  "policy",
+  "policy-disabled",
+  "policy-allow-empty"
+];
+function nowIsoString() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function normalizeToolIds(values) {
+  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);
+  return Array.from(new Set(normalized));
+}
+function isAiMcpFeatureEnabled(featureFlag, snapshot = {}) {
+  return snapshot[featureFlag] === true;
+}
+function isAllowedForRole(riskClass, role) {
+  if (role === "system") {
+    return true;
+  }
+  if (riskClass === "safe") {
+    return true;
+  }
+  if (riskClass === "restricted") {
+    return false;
+  }
+  if (riskClass === "privileged") {
+    return role === "admin" || role === "operator";
+  }
+  return role === "admin" || role === "operator";
+}
+function resolveAiMcpToolAllowlist(input) {
+  const featureEnabled = isAiMcpFeatureEnabled(
+    AI_MCP_FEATURE_FLAGS.mcp,
+    input.featureFlags
+  );
+  const actorRole = input.actorRole ?? "player";
+  const requestedTools = normalizeToolIds(input.requestedTools);
+  const featureFlagIds = featureEnabled ? [AI_MCP_FEATURE_FLAGS.mcp] : [];
+  const reasonCodes = [...input.reasonCodes ?? []];
+  const registryById = new Map(
+    (input.toolRegistry ?? []).map((tool) => [tool.toolId, tool])
+  );
+  if (!featureEnabled) {
+    reasonCodes.push("mcp-feature-disabled");
+    return {
+      requestedTools,
+      allowedTools: [],
+      blockedTools: requestedTools,
+      needsEscalation: true,
+      reasonCodes,
+      source: "policy-disabled",
+      enabledFeatureFlags: featureFlagIds,
+      audit: {
+        policyId: input.policyId ?? "mcp-policy-v1",
+        policyVersion: input.policyVersion ?? "2026-05-01",
+        correlationId: input.correlationId ?? crypto.randomUUID(),
+        requestId: input.requestId,
+        actorId: input.actorId,
+        actorRole,
+        evaluatedAtUtc: nowIsoString(),
+        result: "deny"
+      }
+    };
+  }
+  const allowedTools = [];
+  const blockedTools = [];
+  for (const requestedTool of requestedTools) {
+    const tool = registryById.get(requestedTool);
+    if (!tool) {
+      blockedTools.push(requestedTool);
+      reasonCodes.push(`tool-not-registered:${requestedTool}`);
+      continue;
+    }
+    if (!isAllowedForRole(tool.riskClass, actorRole)) {
+      blockedTools.push(requestedTool);
+      reasonCodes.push(`tool-risk-restricted:${requestedTool}`);
+      continue;
+    }
+    allowedTools.push(requestedTool);
+  }
+  if (allowedTools.length === 0) {
+    reasonCodes.push("mcp-allowlist-deny-all");
+  }
+  if (requestedTools.length === 0) {
+    reasonCodes.push("mcp-allowlist-empty-request");
+  }
+  return {
+    requestedTools,
+    allowedTools,
+    blockedTools,
+    needsEscalation: blockedTools.length > 0 && allowedTools.length > 0,
+    reasonCodes,
+    source: requestedTools.length > 0 ? "policy" : "policy-allow-empty",
+    enabledFeatureFlags: featureFlagIds,
+    audit: {
+      policyId: input.policyId ?? "mcp-policy-v1",
+      policyVersion: input.policyVersion ?? "2026-05-01",
+      correlationId: input.correlationId ?? crypto.randomUUID(),
+      requestId: input.requestId,
+      actorId: input.actorId,
+      actorRole,
+      evaluatedAtUtc: nowIsoString(),
+      result: blockedTools.length === requestedTools.length ? "deny" : blockedTools.length > 0 ? "escalate" : "allow"
+    }
+  };
+}
+function isAiMcpToolRiskAllowed(riskClass, actorRole) {
+  return isAllowedForRole(riskClass, actorRole);
+}
+function isAiMcpToolAllowed(toolId, actorRole, registry) {
+  const tool = registry.find((candidate) => candidate.toolId === toolId);
+  if (!tool) {
+    return false;
+  }
+  return isAllowedForRole(tool.riskClass, actorRole);
+}
 var packageDescriptor = Object.freeze({
   packageName: AI_MCP_PACKAGE,
   featureFlagId: AI_MCP_FEATURE_FLAG_ID,
   envPrefix: AI_MCP_ENV_PREFIX,
-  summary: "MCP tool registry, per-call allowlist, and tool audit contracts for Plasius agentic AI."
+  summary: "MCP tool registry, per-call allowlist, and audit contracts for Plasius AI orchestration."
 });
 export {
   AI_MCP_ENV_PREFIX,
+  AI_MCP_FEATURE_FLAGS,
   AI_MCP_FEATURE_FLAG_ID,
   AI_MCP_PACKAGE,
-  packageDescriptor
+  AI_MCP_RESOLUTION_SOURCES,
+  AI_MCP_TOOL_RISK_CLASSES,
+  AI_MCP_TOOL_ROLES,
+  isAiMcpToolAllowed,
+  isAiMcpToolRiskAllowed,
+  packageDescriptor,
+  resolveAiMcpToolAllowlist
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n  readonly packageName: string;\n  readonly featureFlagId: string;\n  readonly envPrefix: string;\n  readonly summary: string;\n}\n\nexport const AI_MCP_PACKAGE = \"@plasius/ai-mcp\";\nexport const AI_MCP_FEATURE_FLAG_ID = \"ai.mcp.enabled\";\nexport const AI_MCP_ENV_PREFIX = \"AI_MCP\";\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n  packageName: AI_MCP_PACKAGE,\n  featureFlagId: AI_MCP_FEATURE_FLAG_ID,\n  envPrefix: AI_MCP_ENV_PREFIX,\n  summary: \"MCP tool registry, per-call allowlist, and tool audit contracts for Plasius agentic AI.\",\n});\n"],"mappings":";AAOO,IAAM,iBAAiB;AACvB,IAAM,yBAAyB;AAC/B,IAAM,oBAAoB;AAE1B,IAAM,oBAAyC,OAAO,OAAO;AAAA,EAClE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SAAS;AACX,CAAC;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n  readonly packageName: string;\n  readonly featureFlagId: string;\n  readonly envPrefix: string;\n  readonly summary: string;\n}\n\nexport const AI_MCP_PACKAGE = \"@plasius/ai-mcp\";\nexport const AI_MCP_FEATURE_FLAG_ID = \"ai.mcp-rag.enabled\";\nexport const AI_MCP_ENV_PREFIX = \"AI_MCP\";\n\nexport const AI_MCP_FEATURE_FLAGS = {\n  mcp: AI_MCP_FEATURE_FLAG_ID,\n} as const;\n\nexport type AiMcpFeatureFlagKey =\n  (typeof AI_MCP_FEATURE_FLAGS)[keyof typeof AI_MCP_FEATURE_FLAGS];\n\nexport type AiMcpFeatureFlagSnapshot = Readonly<\n  Record<string, boolean | undefined>\n>;\n\nexport const AI_MCP_TOOL_RISK_CLASSES = [\n  \"safe\",\n  \"sensitive\",\n  \"privileged\",\n  \"restricted\",\n] as const;\n\nexport type AiMcpToolRiskClass = (typeof AI_MCP_TOOL_RISK_CLASSES)[number];\n\nexport const AI_MCP_TOOL_ROLES = [\"system\", \"admin\", \"operator\", \"player\"] as const;\n\nexport type AiMcpActorRole = (typeof AI_MCP_TOOL_ROLES)[number];\n\nexport const AI_MCP_RESOLUTION_SOURCES = [\n  \"policy\",\n  \"policy-disabled\",\n  \"policy-allow-empty\",\n] as const;\n\nexport type AiMcpResolutionSource = (typeof AI_MCP_RESOLUTION_SOURCES)[number];\n\nexport interface AiMcpToolDescriptor {\n  readonly toolId: string;\n  readonly toolName: string;\n  readonly riskClass: AiMcpToolRiskClass;\n  readonly description?: string;\n}\n\nexport interface AiMcpAuditMetadata {\n  readonly policyId: string;\n  readonly policyVersion: string;\n  readonly correlationId: string;\n  readonly requestId?: string;\n  readonly actorId?: string;\n  readonly actorRole: AiMcpActorRole;\n  readonly evaluatedAtUtc: string;\n  readonly result: \"allow\" | \"deny\" | \"escalate\";\n}\n\nexport interface ResolveAiMcpToolAllowlistInput {\n  readonly requestedTools: readonly string[];\n  readonly featureFlags?: AiMcpFeatureFlagSnapshot;\n  readonly toolRegistry?: readonly AiMcpToolDescriptor[];\n  readonly actorRole?: AiMcpActorRole;\n  readonly requestId?: string;\n  readonly actorId?: string;\n  readonly correlationId?: string;\n  readonly policyId?: string;\n  readonly policyVersion?: string;\n  readonly reasonCodes?: readonly string[];\n}\n\nexport interface ResolveAiMcpToolAllowlistResult {\n  readonly requestedTools: readonly string[];\n  readonly allowedTools: readonly string[];\n  readonly blockedTools: readonly string[];\n  readonly needsEscalation: boolean;\n  readonly reasonCodes: readonly string[];\n  readonly source: AiMcpResolutionSource;\n  readonly enabledFeatureFlags: readonly AiMcpFeatureFlagKey[];\n  readonly audit: AiMcpAuditMetadata;\n}\n\nfunction nowIsoString(): string {\n  return new Date().toISOString();\n}\n\nfunction normalizeToolIds(values: readonly string[]): string[] {\n  const normalized = values\n    .map((value) => value.trim())\n    .filter((value) => value.length > 0);\n\n  return Array.from(new Set(normalized));\n}\n\nfunction isAiMcpFeatureEnabled(\n  featureFlag: AiMcpFeatureFlagKey,\n  snapshot: AiMcpFeatureFlagSnapshot = {}\n): boolean {\n  return snapshot[featureFlag] === true;\n}\n\nfunction isAllowedForRole(riskClass: AiMcpToolRiskClass, role: AiMcpActorRole): boolean {\n  if (role === \"system\") {\n    return true;\n  }\n\n  if (riskClass === \"safe\") {\n    return true;\n  }\n\n  if (riskClass === \"restricted\") {\n    return false;\n  }\n\n  if (riskClass === \"privileged\") {\n    return role === \"admin\" || role === \"operator\";\n  }\n\n  return role === \"admin\" || role === \"operator\";\n}\n\nexport function resolveAiMcpToolAllowlist(\n  input: ResolveAiMcpToolAllowlistInput\n): ResolveAiMcpToolAllowlistResult {\n  const featureEnabled = isAiMcpFeatureEnabled(\n    AI_MCP_FEATURE_FLAGS.mcp,\n    input.featureFlags\n  );\n  const actorRole: AiMcpActorRole = input.actorRole ?? \"player\";\n  const requestedTools = normalizeToolIds(input.requestedTools);\n  const featureFlagIds: AiMcpFeatureFlagKey[] = featureEnabled\n    ? [AI_MCP_FEATURE_FLAGS.mcp]\n    : [];\n\n  const reasonCodes = [...(input.reasonCodes ?? [])];\n  const registryById = new Map(\n    (input.toolRegistry ?? []).map((tool) => [tool.toolId, tool])\n  );\n\n  if (!featureEnabled) {\n    reasonCodes.push(\"mcp-feature-disabled\");\n\n    return {\n      requestedTools,\n      allowedTools: [],\n      blockedTools: requestedTools,\n      needsEscalation: true,\n      reasonCodes,\n      source: \"policy-disabled\",\n      enabledFeatureFlags: featureFlagIds,\n      audit: {\n        policyId: input.policyId ?? \"mcp-policy-v1\",\n        policyVersion: input.policyVersion ?? \"2026-05-01\",\n        correlationId: input.correlationId ?? crypto.randomUUID(),\n        requestId: input.requestId,\n        actorId: input.actorId,\n        actorRole,\n        evaluatedAtUtc: nowIsoString(),\n        result: \"deny\",\n      },\n    };\n  }\n\n  const allowedTools: string[] = [];\n  const blockedTools: string[] = [];\n\n  for (const requestedTool of requestedTools) {\n    const tool = registryById.get(requestedTool);\n\n    if (!tool) {\n      blockedTools.push(requestedTool);\n      reasonCodes.push(`tool-not-registered:${requestedTool}`);\n      continue;\n    }\n\n    if (!isAllowedForRole(tool.riskClass, actorRole)) {\n      blockedTools.push(requestedTool);\n      reasonCodes.push(`tool-risk-restricted:${requestedTool}`);\n      continue;\n    }\n\n    allowedTools.push(requestedTool);\n  }\n\n  if (allowedTools.length === 0) {\n    reasonCodes.push(\"mcp-allowlist-deny-all\");\n  }\n\n  if (requestedTools.length === 0) {\n    reasonCodes.push(\"mcp-allowlist-empty-request\");\n  }\n\n  return {\n    requestedTools,\n    allowedTools,\n    blockedTools,\n    needsEscalation: blockedTools.length > 0 && allowedTools.length > 0,\n    reasonCodes,\n    source: requestedTools.length > 0 ? \"policy\" : \"policy-allow-empty\",\n    enabledFeatureFlags: featureFlagIds,\n    audit: {\n      policyId: input.policyId ?? \"mcp-policy-v1\",\n      policyVersion: input.policyVersion ?? \"2026-05-01\",\n      correlationId: input.correlationId ?? crypto.randomUUID(),\n      requestId: input.requestId,\n      actorId: input.actorId,\n      actorRole,\n      evaluatedAtUtc: nowIsoString(),\n      result:\n        blockedTools.length === requestedTools.length\n          ? \"deny\"\n          : blockedTools.length > 0\n            ? \"escalate\"\n            : \"allow\",\n    },\n  };\n}\n\nexport function isAiMcpToolRiskAllowed(\n  riskClass: AiMcpToolRiskClass,\n  actorRole: AiMcpActorRole\n): boolean {\n  return isAllowedForRole(riskClass, actorRole);\n}\n\nexport function isAiMcpToolAllowed(\n  toolId: string,\n  actorRole: AiMcpActorRole,\n  registry: readonly AiMcpToolDescriptor[]\n): boolean {\n  const tool = registry.find((candidate) => candidate.toolId === toolId);\n\n  if (!tool) {\n    return false;\n  }\n\n  return isAllowedForRole(tool.riskClass, actorRole);\n}\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n  packageName: AI_MCP_PACKAGE,\n  featureFlagId: AI_MCP_FEATURE_FLAG_ID,\n  envPrefix: AI_MCP_ENV_PREFIX,\n  summary:\n    \"MCP tool registry, per-call allowlist, and audit contracts for Plasius AI orchestration.\",\n});\n"],"mappings":"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","names":[]}

package/docs/adrs/adr-0002-mcp-allowlist-risk-audit.md

@@ -0,0 +1,24 @@
+# ADR-0002: MCP allowlist and risk-based execution gates
+
+- Date: 2026-05-14
+- Status: Accepted
+
+## Context
+
+MCP execution is part of the agentic AI boundary and requires strict minimization of available tools. A request should only execute from an allowlist based on role and tool risk class to avoid accidental privileged actions.
+
+## Decision
+
+`@plasius/ai-mcp` now exposes a deterministic allowlist resolver that:
+
+- requires explicit `ai.mcp-rag.enabled` feature gate;
+- evaluates requested tool IDs against a registry of tool descriptors;
+- enforces role-based risk-class constraints;
+- returns structured outcomes including allowed/blocked tools and audit metadata.
+
+## Consequences
+
+- Tool access is explicit and inspectable per request.
+- Downstream callers can enforce telemetry and policy with reason codes.
+- Restricted or unknown tools are denied by default when policy is unavailable.
+- Audits now include decision outcome and policy references for compliance traceability.

package/docs/adrs/index.md

@@ -1,3 +1,4 @@
 # Architecture Decision Records
 
 - [ADR-0001: @plasius/ai-mcp Package Boundary](./adr-0001-package-boundary.md)
+- [ADR-0002: MCP tool allowlist and risk-based execution gates](./adr-0002-mcp-allowlist-risk-audit.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/ai-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "MCP tool registry, per-call allowlist, and tool audit contracts for Plasius agentic AI.",
   "type": "module",
   "sideEffects": false,