Support documentation meta tag on entity/event/relationship defs

src/api/http.ts

@@ -19,6 +19,7 @@ import {
   Module,
   getAllBetweenRelationshipNames,
   linkInstancesEvent,
+  getPublicMeta,
 } from '../runtime/module.js';
 import { isNodeEnv } from '../utils/runtime.js';
 import { parseAndEvaluateStatement, Result } from '../runtime/interpreter.js';
@@ -812,6 +813,8 @@ async function handleMetaGet(req: Request, res: Response): Promise<void> {
                       : rel.isOneToMany()
                         ? 'one-to-many'
                         : 'many-to-many',
+                    documentation: rel.getDocumentation(),
+                    meta: getPublicMeta(rel),
                   });
                 } else if (
                   childNode.path.getModuleName() === moduleName &&
@@ -827,6 +830,8 @@ async function handleMetaGet(req: Request, res: Response): Promise<void> {
                       : rel.isOneToMany()
                         ? 'one-to-many'
                         : 'many-to-many',
+                    documentation: rel.getDocumentation(),
+                    meta: getPublicMeta(rel),
                   });
                 }
               });
@@ -839,7 +844,8 @@ async function handleMetaGet(req: Request, res: Response): Promise<void> {
               type: 'entity',
               attributes: attributes,
               relationships: relationships,
-              meta: entity instanceof Record && entity.meta ? Object.fromEntries(entity.meta) : {},
+              documentation: entity instanceof Record ? entity.getDocumentation() : undefined,
+              meta: entity instanceof Record ? getPublicMeta(entity) : {},
             };
             entities.push(entityInfo);
           } catch (err: any) {
@@ -906,7 +912,8 @@ async function handleMetaGet(req: Request, res: Response): Promise<void> {
               fqName: makeFqName(moduleName, eventName),
               type: 'event',
               attributes: attributes,
-              meta: event instanceof Record && event.meta ? Object.fromEntries(event.meta) : {},
+              documentation: event instanceof Record ? event.getDocumentation() : undefined,
+              meta: event instanceof Record ? getPublicMeta(event) : {},
             };
             events.push(eventInfo);
           } catch (err: any) {

src/runtime/module.ts

@@ -135,6 +135,16 @@ function normalizePropertyNames(props: Map<string, any>) {
 const SystemAttributeProperty: string = 'system-attribute';
 const SystemDefinedEvent = 'system-event';
 const McpToolEvent = 'mcp-tool';
+const IsAgentEventMeta = 'is-agent-event';
+const EventAgentName = 'event-agent-name';
+const DocumentationMetaTag = 'documentation';
+
+const InternalMetaKeys = new Set<string>([
+  IsAgentEventMeta,
+  EventAgentName,
+  SystemDefinedEvent,
+  McpToolEvent,
+]);
 
 function asSystemAttribute(attrSpec: AttributeSpec): AttributeSpec {
   const props: Map<string, any> = attrSpec.properties ? attrSpec.properties : new Map();
@@ -238,6 +248,15 @@ export function newMeta(): Meta {
   return new Map<string, any>();
 }
 
+export function getPublicMeta(record: Record): { [key: string]: any } {
+  if (!record.meta || record.meta.size === 0) return {};
+  const result: { [key: string]: any } = {};
+  record.meta.forEach((v: any, k: string) => {
+    if (!InternalMetaKeys.has(k)) result[k] = v;
+  });
+  return result;
+}
+
 export enum RecordType {
   RECORD,
   ENTITY,
@@ -513,6 +532,10 @@ export class Record extends ModuleEntry {
     }
   }
 
+  getDocumentation(): string | undefined {
+    return this.getMeta(DocumentationMetaTag) as string | undefined;
+  }
+
   getFullTextSearchAttributes(): string[] | undefined {
     let fts: string[] | string | undefined = this.getMeta('fullTextSearchAttributes');
     if (!fts) {
@@ -701,8 +724,7 @@ export class Record extends ModuleEntry {
       if (isevent && isAgentEvent(this) && toolCall) {
         const m = new Map<string, any>();
         this.meta?.forEach((v: any, k: string) => {
-          if (!(k === IsAgentEventMeta || k === EventAgentName || k === DocumentationMetaTag))
-            m.set(k, v);
+          if (!InternalMetaKeys.has(k)) m.set(k, v);
         });
         if (m.size > 0) {
           metaObj = Object.fromEntries(m);
@@ -4362,10 +4384,6 @@ export function assertInstance(obj: any) {
   }
 }
 
-const IsAgentEventMeta = 'is-agent-event';
-const EventAgentName = 'event-agent-name';
-const DocumentationMetaTag = 'documentation';
-
 function markAsAgentEvent(event: Event): Event {
   event.addMeta(IsAgentEventMeta, 'y');
   return event;
@@ -4382,7 +4400,7 @@ export function defineAgentEvent(moduleName: string, agentName: string, instruct
       .addMeta(SystemDefinedEvent, 'true');
   }
   markAsAgentEvent(event as Event).addMeta(EventAgentName, agentName);
-  if (instruction) {
+  if (instruction && !event.getMeta(DocumentationMetaTag)) {
     event.addMeta(
       DocumentationMetaTag,
       `This event will trigger an agent which has the instruction - "${instruction}".