agentlang 0.10.2 → 0.10.4

package/src/runtime/modules/ai.ts

@@ -26,6 +26,7 @@ import {
   asJSONSchema,
   Decision,
   fetchModule,
+  getAllDocumentsForTopics,
   getDecision,
   getGlobalRetry,
   Instance,
@@ -37,7 +38,9 @@ import {
   newInstanceAttributes,
   objectToInstanceAttributes,
   Record,
+  registerTopic as registerTopicInRegistry,
   resolveDocumentAliases,
+  resolveTopicNames,
   Retry,
 } from '../module.js';
 import { provider } from '../agents/registry.js';
@@ -71,9 +74,10 @@ import {
 import { logger } from '../logger.js';
 import { FlowStep } from '../agents/flows.js';
 import { Statement } from '../../language/generated/ast.js';
-import { isMonitoringEnabled, TtlCache } from '../state.js';
+import { getKnowledgeGraphConfig, isMonitoringEnabled, TtlCache } from '../state.js';
 import { isNodeEnv } from '../../utils/runtime.js';
 import { getFileSystem } from '../../utils/fs-utils.js';
+import { getDocumentRetriever } from '../document-retriever.js';
 
 export const CoreAIModuleName = makeCoreModuleName('ai');
 export const AgentEntityName = 'Agent';
@@ -82,6 +86,50 @@ export const AgentLearnerType = 'learner';
 
 const AgentEvalType = 'eval';
 
+// --- Agent cancellation infrastructure ---
+
+export class AgentCancelledException extends Error {
+  constructor(chatId: string) {
+    super(`Agent cancelled for chatId: ${chatId}`);
+    this.name = 'AgentCancelledException';
+  }
+}
+
+export async function cancelAgent(chatId: string): Promise<string> {
+  const t = `${CoreAIModuleName}/${CancelledAgentEntity}`;
+  await parseAndEvaluateStatement(`{${t} {chatId "${chatId}"}, @upsert}`);
+  return `Cancellation requested for chatId: ${chatId}`;
+}
+
+export async function checkCancelled(chatId: string): Promise<void> {
+  if (!chatId) return;
+  try {
+    const results: Instance[] = await parseAndEvaluateStatement(
+      `{${CoreAIModuleName}/${CancelledAgentEntity} {chatId? "${chatId}"}}`
+    );
+    if (results && results.length > 0) {
+      await parseAndEvaluateStatement(
+        `purge {${CoreAIModuleName}/${CancelledAgentEntity} {chatId? "${chatId}"}}`
+      );
+      throw new AgentCancelledException(chatId);
+    }
+  } catch (err: any) {
+    if (err instanceof AgentCancelledException) throw err;
+    logger.debug(`checkCancelled DB error for ${chatId}: ${err}`);
+  }
+}
+
+export async function clearCancellation(chatId: string): Promise<void> {
+  if (!chatId) return;
+  try {
+    await parseAndEvaluateStatement(
+      `purge {${CoreAIModuleName}/${CancelledAgentEntity} {chatId? "${chatId}"}}`
+    );
+  } catch (err: any) {
+    logger.debug(`clearCancellation DB error for ${chatId}: ${err}`);
+  }
+}
+
 export default `module ${CoreAIModuleName}
 
 import "./modules/ai.js" @as ai
@@ -100,7 +148,8 @@ entity ${AgentEntityName} {
     stateless Boolean @default(false),
     instruction String @optional,
     tools String @optional, // comma-separated list of tool names
-    documents String @optional, // comma-separated list of document names
+    documents String @optional, // list of document names
+    topics String @optional, // list of topic names
     channels String @optional, // comma-separated list of channel names
     role String @optional,
     flows String @optional,
@@ -147,6 +196,15 @@ workflow processDoc {
   await ai.fetchAndCreateDocument(doc.title, doc.url, doc.retrievalConfig, doc.embeddingConfig)
 }
 
+event topic {
+  name String,
+  documents String @optional // comma-separated or array of document titles
+}
+
+workflow processTopic {
+  await ai.registerTopic(topic.name, topic.documents)
+}
+
 entity Directive {
   id UUID @id @default(uuid()),
   agentFqName String @indexed,
@@ -202,6 +260,10 @@ entity AgentFlowStep {
     suspensionId String
 }
 
+entity CancelledAgent {
+    chatId String @id
+}
+
 @public event restartFlow {
   chatId String,
   step String,
@@ -214,6 +276,14 @@ workflow restartFlow {
     {${DefaultModuleName}/restartSuspension {id fs.suspensionId, data restartFlow.userInput}}
   }
 }
+
+@public event cancelAgent {
+  chatId String
+}
+
+workflow cancelAgent {
+  await ai.cancelAgent(cancelAgent.chatId)
+}
 `;
 
 enum AgentCacheType {
@@ -317,6 +387,7 @@ export class AgentInstance {
   type: string = 'chat';
   tools: string | undefined;
   documents: string | undefined;
+  topics: string | undefined;
   channels: string | undefined;
   runWorkflows: boolean = true;
   role: string | undefined;
@@ -822,6 +893,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     const p = await findProviderForLLM(this.llm, env);
     const agentName = this.name;
     const chatId = env.getAgentChatId() || agentName;
+    await checkCancelled(chatId);
     let isplnr = this.isPlanner();
     const isflow = !isplnr && this.isFlowExecutor();
     const iseval = !isplnr && !isflow && this.isEvaluator();
@@ -920,7 +992,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
         let response: AIResponse = await p.invoke(msgs, externalToolSpecs);
         const v = this.getValidationEvent();
         if (v) {
-          response = await this.handleValidation(response, v, msgs, p);
+          response = await this.handleValidation(response, v, msgs, p, chatId);
         }
         if (!iseval)
           await AgentInstance.maybeEvaluateResponse(
@@ -1005,7 +1077,8 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     response: AIResponse,
     validationEventName: string,
     msgs: BaseMessage[],
-    provider: AgentServiceProvider
+    provider: AgentServiceProvider,
+    chatId?: string
   ): Promise<AIResponse> {
     let r: Instance = await this.invokeValidator(response, validationEventName);
     const status = r.lookup('status');
@@ -1017,6 +1090,7 @@ Only return a pure JSON object with no extra text, annotations etc.`;
         let attempt = 0;
         let delay = this.retryObj.getNextDelayMs(attempt);
         while (delay) {
+          if (chatId) await checkCancelled(chatId);
           msgs.push(assistantMessage(resp.content));
           const vs = JSON.stringify(r.asSerializableObject());
           msgs.push(
@@ -1068,93 +1142,139 @@ Only return a pure JSON object with no extra text, annotations etc.`;
     return result;
   }
 
-  private async maybeAddRelevantDocuments(message: string, env: Environment): Promise<string> {
-    if (this.documents && this.documents.length > 0) {
-      try {
-        const docNames = this.documents.split(',').map(d => d.trim());
-        const docTitles = resolveDocumentAliases(docNames);
+  private async maybeAddRelevantDocuments(message: string, _env: Environment): Promise<string> {
+    const hasDocuments = this.documents && this.documents.length > 0;
+    const hasTopics = this.topics && this.topics.length > 0;
 
-        const searchQuery = message;
+    if (!hasDocuments && !hasTopics) {
+      return message;
+    }
 
-        try {
-          const semanticResult: any[] = await parseHelper(
-            `{${CoreAIModuleName}/Document {content? "${searchQuery.replace(/"/g, '\\"')}"}}`,
-            env
-          );
+    try {
+      let containerTags: string[] = [];
+      let topicDocumentTitles: string[] = [];
 
-          if (semanticResult && semanticResult.length > 0) {
-            const docs: Instance[] = [];
-            for (const doc of semanticResult) {
-              const docTitle = doc.lookup ? doc.lookup('title') : doc.title;
-              if (AgentInstance.docTitlesMatch(docTitle, docTitles)) {
-                docs.push(
-                  doc instanceof Instance
-                    ? doc
-                    : Instance.newWithAttributes(doc, new Map(Object.entries(doc)))
-                );
-              }
-            }
+      if (hasTopics) {
+        const topicNames = resolveTopicNames(this.topics!);
+        containerTags = topicNames;
+        topicDocumentTitles = getAllDocumentsForTopics(topicNames);
+      }
 
-            if (docs.length > 0) {
-              return message.concat('\n\nRelevant context from documents:\n').concat(
-                docs
-                  .map((v: Instance) => {
-                    return `Document: ${v.lookup('title')}\n${v.lookup('content') as string}`;
-                  })
-                  .join('\n\n---\n\n')
-              );
-            }
-          }
-        } catch (semanticErr) {
-          logger.debug(
-            `Semantic search is not available, falling back to title-based filtering: ${semanticErr}`
-          );
-        }
+      if (containerTags.length === 0) {
+        containerTags = [this.getFqName()];
+      }
 
-        const result: any[] = await parseHelper(`{${CoreAIModuleName}/Document? {}}`, env);
-        if (result && result.length > 0) {
-          const docs: Instance[] = [];
-          for (let i = 0; i < result.length; ++i) {
-            const v: any = result[i];
-            const docTitle: string | undefined = AgentInstance.getDocumentTitle(v);
-
-            if (docTitle && docTitles.includes(docTitle)) {
-              if (v instanceof Instance) {
-                docs.push(v);
-              }
-            }
-          }
+      let documentTitles: string[] = [];
+      let documentRefs: string[] = [];
 
-          if (docs.length > 0) {
-            return message.concat('\n\nRelevant context from documents:\n').concat(
-              docs
-                .map((v: Instance) => {
-                  return v.lookup('content') as string;
-                })
-                .join('\n\n')
-            );
+      if (hasDocuments) {
+        const documentEntries = this.documents!.split(',')
+          .map(d => d.trim())
+          .filter(Boolean);
+        documentTitles = resolveDocumentAliases(documentEntries);
+        documentRefs = documentEntries.filter(d => d.startsWith('document-service://'));
+      }
+
+      const allDocumentTitles = [...new Set([...topicDocumentTitles, ...documentTitles])];
+
+      const kgConfig = getKnowledgeGraphConfig();
+      const serviceUrl = kgConfig?.serviceUrl?.trim() || process.env.KNOWLEDGE_SERVICE_URL || null;
+
+      if (serviceUrl) {
+        return await this.queryRemoteKnowledgeService(
+          message,
+          serviceUrl,
+          containerTags,
+          allDocumentTitles,
+          documentRefs
+        );
+      }
+
+      // Local mode: embed documents into pgvector/lancedb and query
+      const retriever = getDocumentRetriever();
+      const aiModule = isModule(DefaultModuleName + '.ai')
+        ? fetchModule(DefaultModuleName + '.ai')
+        : null;
+      if (aiModule) {
+        for (const title of allDocumentTitles) {
+          const url = aiModule.getDocument(title);
+          if (url) {
+            await retriever.processDocument(title, url);
           }
         }
-      } catch (err) {
-        logger.debug(`Error retrieving documents: ${err}`);
       }
+
+      const contextString = await retriever.query(
+        message,
+        allDocumentTitles.length > 0 ? allDocumentTitles : undefined,
+        10
+      );
+
+      if (contextString.trim().length > 0) {
+        return message.concat('\n\nRelevant context from documents:\n').concat(contextString);
+      }
+    } catch (err) {
+      logger.debug(`[KNOWLEDGE] Knowledge retrieval failed: ${err}`);
     }
+
     return message;
   }
 
-  private static docTitlesMatch(title: string | undefined, docNames: string[]): boolean {
-    return title !== undefined && docNames.includes(title);
-  }
+  private async queryRemoteKnowledgeService(
+    message: string,
+    serviceUrl: string,
+    containerTags: string[],
+    documentTitles: string[],
+    documentRefs: string[]
+  ): Promise<string> {
+    const options = {
+      chunkLimit: 10,
+      entityLimit: 20,
+      includeChunks: true,
+      includeEntities: true,
+      includeEdges: true,
+      documentTitles: documentTitles.length > 0 ? documentTitles : undefined,
+      documentRefs: documentRefs.length > 0 ? documentRefs : undefined,
+    };
 
-  private static getDocumentTitle(doc: any): string | undefined {
-    if (typeof doc.lookup === 'function') {
-      return doc.lookup('title') as string | undefined;
-    } else if (doc.attributes) {
-      return doc.attributes.get('title') as string | undefined;
-    } else if (doc.title) {
-      return doc.title;
+    let response = await fetch(`${serviceUrl}/api/knowledge/query`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query: message, containerTags, ...options }),
+    });
+
+    if (!response.ok) {
+      response = await fetch(`${serviceUrl}/knowledge.core/ApiKnowledgeQuery`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          queryText: message,
+          containerTagsJson: JSON.stringify(containerTags),
+          documentTitlesJson: JSON.stringify(options.documentTitles || []),
+          documentRefsJson: JSON.stringify(options.documentRefs || []),
+          optionsJson: JSON.stringify({
+            includeChunks: options.includeChunks,
+            includeEntities: options.includeEntities,
+            includeEdges: options.includeEdges,
+            chunkLimit: options.chunkLimit,
+            entityLimit: options.entityLimit,
+          }),
+        }),
+      });
     }
-    return undefined;
+
+    if (response.ok) {
+      const rawPayload: any = await response.json();
+      const first = Array.isArray(rawPayload) ? rawPayload[0] : rawPayload;
+      const payload =
+        first && typeof first === 'object' && first.KnowledgeQuery ? first.KnowledgeQuery : first;
+      const contextString = payload?.contextString || '';
+      if (contextString.trim().length > 0) {
+        return message.concat('\n\nRelevant context from documents:\n').concat(contextString);
+      }
+    }
+
+    return message;
   }
 
   private static ToolsCache = new Map<string, string>();
@@ -1461,6 +1581,7 @@ export async function processAgentLearning(
 const LocalAgentgFlow = true;
 const LocalFlowStepsRootDirName = 'flows';
 const AgentFlowStep = 'AgentFlowStep';
+const CancelledAgentEntity = 'CancelledAgent';
 
 export async function saveFlowStepResultLocally(
   chatId: string,
@@ -1613,6 +1734,72 @@ export async function loadFlowStep(chatId: string, step: string): Promise<Instan
   }
 }
 
+export async function registerTopic(
+  name: string,
+  documents: string | undefined,
+  _env: Environment
+): Promise<any> {
+  // Register in local registry
+  registerTopicInRegistry(name, documents ?? undefined);
+
+  // Sync to knowledge service if configured
+  const kgConfig = getKnowledgeGraphConfig();
+  const serviceUrl = kgConfig?.serviceUrl?.trim() || process.env.KNOWLEDGE_SERVICE_URL || null;
+
+  if (serviceUrl) {
+    try {
+      // Parse document list
+      const docList = documents
+        ? documents
+            .split(',')
+            .map(d => d.trim())
+            .filter(Boolean)
+        : [];
+
+      // Create or update topic in knowledge service
+      let response = await fetch(`${serviceUrl}/api/knowledge/topics`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          name,
+          description: `Topic ${name} with ${docList.length} documents`,
+          documentTitles: docList,
+        }),
+      });
+
+      if (!response.ok) {
+        // Fallback to Agentlang entity path for deployed knowledge-service
+        response = await fetch(`${serviceUrl}/knowledge.core/Topic`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            name,
+            description: `Topic ${name} with ${docList.length} documents`,
+            type: 'manual',
+            documentCount: docList.length,
+          }),
+        });
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        logger.debug(`[KNOWLEDGE] Failed to sync topic to service: ${errorText}`);
+      } else {
+        logger.debug(`[KNOWLEDGE] Synced topic "${name}" to knowledge service`);
+      }
+    } catch (err) {
+      // Don't fail topic registration if service sync fails
+      logger.debug(`[KNOWLEDGE] Error syncing topic to service: ${err}`);
+    }
+  }
+
+  return { topic: { name, documents: documents ?? '' } };
+}
+
 export async function fetchAndCreateDocument(
   title: string,
   url: string,

package/src/runtime/modules/core.ts

@@ -2,6 +2,7 @@ import { default as ai, normalizeGeneratedCode } from './ai.js';
 import { default as auth } from './auth.js';
 import { default as files } from './files.js';
 import { default as mcp } from './mcp.js';
+import messaging, { initMessagingModule } from './messaging.js';
 import {
   DefaultModuleName,
   DefaultModules,
@@ -188,6 +189,7 @@ export function registerCoreModules() {
     { def: ai, name: makeCoreModuleName('ai') },
     { def: files, name: makeCoreModuleName('files') },
     { def: mcp, name: mcpn },
+    { def: messaging, name: makeCoreModuleName('messaging') },
   ];
 
   coreModuleInfo.forEach(({ def, name }) => {
@@ -639,6 +641,8 @@ async function internPersistentModules() {
 }
 
 export function initCoreModuleManager() {
+  initMessagingModule();
+
   const ModuleResolverName = 'agentlang/moduleResolver';
   const ModuleResolver = new GenericResolver(ModuleResolverName, {
     create: createModule,