agentlang 0.0.37 → 0.0.50

package/src/runtime/agents/common.ts

@@ -250,7 +250,7 @@ workflow sendEmail {
     {email {to emp.email body "please call me as soon as possible"}}
 }
 
-The point is use the immediate context to fill-in values in generated patterns, as much as possible.
+The point is, use the immediate context to fill-in values in generated patterns, as much as possible.
 
 Also generate a workflow only if required explicitly by the user or the contextual information is incomplete. Otherwise, just return an array of patterns.
 As an example, if the user request is "send an email to employee 101 with this message - 'please call me as soon as possible'", you must return:
@@ -263,3 +263,52 @@ You MUST separate each pattern in the array with a semi-colon (;)  and never use
 Now consider the following module definition and generate appropriate patterns in response to the user instructions. You must return only valid patterns or workflows,
 no other descriptive text or comments are needed.
 `;
+
+export const FlowExecInstructions = `The following is the textual representation of a flowchart. 
+
+checkOrder --> "ProductA" acceptOrder
+checkOrder --> "ProductB" acceptOrder
+checkOrder --> "ProductC" rejectOrder
+acceptOrder --> sendPaymentLinkToCustomer
+rejectOrder --> sendRejectionEmailToCustomer
+
+Along with this flowchart, you'll be passed a "context", which contain the steps in the flowchart that was executed so far, along with
+their results. Based on the context, you need to return the name of the step that needs to execute next. If you have reached the end
+of the chart, return 'DONE'. 
+
+At the beginning of the execution, the context will contain only the order information, say something like:
+
+OrderNo: 101, Item: "ProductB", customerEmail: "manager@acme.com"
+
+This means you have to return 'checkOrder' as the next step (i.e you move the root node of the flowchart).
+After the step checkOrder executes, you'll be passed the following context:
+
+orderNo: 101, Item: "ProductB", customerEmail: "manager@acme.com"
+checkOrder --> "ProductB"
+
+Now you can infer from the context that if the result of checkOrder is either "ProductA" or "ProductB", you must move to the step 'acceptOrder'.
+So you return 'acceptOrder'. After this, you'll return the updated context as:
+
+OrderNo: 101, Item: "ProductB", customerEmail: "manager@acme.com"
+checkOrder --> "ProductB"
+acceptOrder --> {orderNo: 101, customerEmail: "manager@acme.com", acceptedOn: "2025-07-01"}
+
+You see that 'acceptOrder' has produced the result '{orderNo: 101, customerEmail: "manager@acme.com", acceptedOn: "2025-07-01"}' - but from the flowchart you know that, whatever the result of 'acceptOrder',
+you have to move to the 'sendPaymentLinkToCustomer' step and so you return 'sendPaymentLinkToCustomer'.
+
+The next context you'll see will be:
+
+OrderNo: 101, Item: "ProductB", customerEmail: "manager@acme.com"
+checkOrder --> "ProductB"
+acceptOrder --> {orderNo: 101, customerEmail: "manager@acme.com", acceptedOn: "2025-07-01"}
+sendPaymentLinkToCustomer --> "manager@acme.com"
+
+The 'sendPaymentLinkToCustomer' has returned the customer email. You look at the flowchart and detect that, whatever the return value of
+'sendPaymentLinkToCustomer' there is nothing else to do. So you return 'DONE'.
+
+Generally a flowchart has the following two types of entries:
+  1. a --> b, meaning after step 'a' do step 'b'.
+  2. a --> "x" b - this means if 'a' returns the string "x", then do step 'b'.
+If you detect that you have reached the end of the chart, return 'DONE'. Otherwise, return only the name of the next step. Never return
+any additional description, direction or comments.
+`;

package/src/runtime/agents/registry.ts

@@ -18,9 +18,9 @@ export function provider(service: string) {
         p = Providers.get(availableService);
         if (p) return p;
       }
-      throw new Error(
-        `${service} provider requested but ${service.toUpperCase()}_API_KEY not found. Available providers: ${getAvailableProviders().join(', ') || 'none'}`
-      );
+      const errorMessage = `${service} provider requested but ${service.toUpperCase()}_API_KEY not found. Available providers: ${getAvailableProviders().join(', ') || 'none'}`;
+      console.error(errorMessage);
+      throw new Error(errorMessage);
     }
   } else {
     throw new Error(`No provider found for ${service}`);

package/src/runtime/auth/cognito.ts

@@ -378,9 +378,11 @@ export class CognitoAuth implements AgentlangAuth {
 
       if (response.$metadata.httpStatusCode == 200) {
         logger.info(`Signup successful for user: ${username}`);
-        const user = await ensureUser(username, '', '', env);
+        const user = await ensureUser(username, firstName, lastName, env);
         const userInfo: UserInfo = {
           username: username,
+          firstName: firstName,
+          lastName: lastName,
           id: user.id,
           systemUserInfo: response.UserSub,
         };
@@ -538,15 +540,19 @@ export class CognitoAuth implements AgentlangAuth {
       }
       if (result) {
         // After successful Cognito authentication, create/update local records
-        let localUser = await findUserByEmail(username, env);
-        if (!localUser) {
-          localUser = await ensureUser(username, '', '', env);
-        }
-        const userid = localUser.lookup('id');
         const idtok = result.getIdToken();
         const idToken = idtok.getJwtToken();
         const idTokenPayload = idtok.decodePayload();
+
+        const firstName = idTokenPayload['given_name'] || idTokenPayload['name'] || '';
+        const lastName = idTokenPayload['family_name'] || '';
         const userGroups = idTokenPayload['cognito:groups'];
+
+        let localUser = await findUserByEmail(username, env);
+        if (!localUser) {
+          localUser = await ensureUser(username, firstName, lastName, env);
+        }
+        const userid = localUser.lookup('id');
         if (userGroups) {
           await ensureUserRoles(userid, userGroups, env);
         }
@@ -802,6 +808,8 @@ export class CognitoAuth implements AgentlangAuth {
     }
 
     const userEmail = localUser.lookup('email');
+    const firstName = localUser.lookup('firstName');
+    const lastName = localUser.lookup('lastName');
 
     // Check if Cognito is configured
     const cognitoConfigured = process.env.COGNITO_USER_POOL_ID && process.env.COGNITO_CLIENT_ID;
@@ -825,6 +833,8 @@ export class CognitoAuth implements AgentlangAuth {
         return {
           id: userId,
           username: userEmail,
+          firstName: firstName,
+          lastName: lastName,
           systemUserInfo: {
             localUser: localUser,
             cognitoData: {
@@ -847,6 +857,8 @@ export class CognitoAuth implements AgentlangAuth {
         return {
           id: userId,
           username: userEmail,
+          firstName: firstName,
+          lastName: lastName,
           systemUserInfo: localUser,
         };
       }
@@ -855,6 +867,8 @@ export class CognitoAuth implements AgentlangAuth {
       return {
         id: userId,
         username: userEmail || userId,
+        firstName: firstName,
+        lastName: lastName,
         systemUserInfo: localUser,
       };
     }
@@ -867,6 +881,8 @@ export class CognitoAuth implements AgentlangAuth {
     }
 
     const userId = localUser.lookup('id');
+    const firstName = localUser.lookup('firstName');
+    const lastName = localUser.lookup('lastName');
 
     // Check if Cognito is configured
     const cognitoConfigured = process.env.COGNITO_USER_POOL_ID && process.env.COGNITO_CLIENT_ID;
@@ -876,11 +892,11 @@ export class CognitoAuth implements AgentlangAuth {
         // Get additional user details from Cognito
         const client = new CognitoIdentityProviderClient({
           region: process.env.AWS_REGION || 'us-west-2',
-          credentials: fromEnv(),
         });
 
         const command = new AdminGetUserCommand({
           UserPoolId: this.fetchUserPoolId(),
+          ClientId: this.fetchClientId(),
           Username: email,
         });
 
@@ -890,6 +906,8 @@ export class CognitoAuth implements AgentlangAuth {
         return {
           id: userId,
           username: email,
+          firstName: firstName,
+          lastName: lastName,
           systemUserInfo: {
             localUser: localUser,
             cognitoData: {
@@ -904,7 +922,7 @@ export class CognitoAuth implements AgentlangAuth {
           },
         };
       } catch (err: any) {
-        logger.warn(`Failed to get Cognito user info for email ${email}, using local data only:`, {
+        console.log(`Failed to get Cognito user info for email ${email}, using local data only:`, {
           errorName: err.name,
           errorMessage: sanitizeErrorMessage(err.message),
         });
@@ -912,6 +930,8 @@ export class CognitoAuth implements AgentlangAuth {
         return {
           id: userId,
           username: email,
+          firstName: firstName,
+          lastName: lastName,
           systemUserInfo: localUser,
         };
       }
@@ -920,6 +940,8 @@ export class CognitoAuth implements AgentlangAuth {
       return {
         id: userId,
         username: email,
+        firstName: firstName,
+        lastName: lastName,
         systemUserInfo: localUser,
       };
     }

package/src/runtime/auth/interface.ts

@@ -3,6 +3,8 @@ import { Environment } from '../interpreter.js';
 export type UserInfo = {
   id: string; // a UUID
   username: string;
+  firstName: string;
+  lastName: string;
   systemUserInfo?: any;
 };
 

package/src/runtime/defs.ts

@@ -89,3 +89,4 @@ export function setSubscriptionFn(f: Function) {
 }
 
 export const ForceReadPermFlag = 'f-r-f';
+export const FlowSuspensionTag = `--`;

package/src/runtime/interpreter.ts

@@ -70,9 +70,22 @@ import {
 import { getResolver, getResolverNameForPath } from './resolvers/registry.js';
 import { parseStatement, parseWorkflow } from '../language/parser.js';
 import { ActiveSessionInfo, AdminSession, AdminUserId } from './auth/defs.js';
-import { AgentInstance, AgentEntityName, AgentFqName, findAgentByName } from './modules/ai.js';
+import {
+  AgentInstance,
+  AgentEntityName,
+  AgentFqName,
+  findAgentByName,
+  FlowSpec,
+  getAgentFlow,
+  FlowStep,
+} from './modules/ai.js';
 import { logger } from './logger.js';
-import { ParentAttributeName, PathAttributeName, PathAttributeNameQuery } from './defs.js';
+import {
+  FlowSuspensionTag,
+  ParentAttributeName,
+  PathAttributeName,
+  PathAttributeNameQuery,
+} from './defs.js';
 import {
   addCreateAudit,
   addDeleteAudit,
@@ -238,6 +251,22 @@ export class Environment extends Instance {
     return this;
   }
 
+  private static FlowContextTag = 'flow-context';
+
+  setFlowContext(s: string): Environment {
+    this.attributes.set(Environment.FlowContextTag, s);
+    return this;
+  }
+
+  resetFlowContext(): Environment {
+    this.attributes.set(Environment.FlowContextTag, undefined);
+    return this;
+  }
+
+  getFlowContext(): string | undefined {
+    return this.attributes.get(Environment.FlowContextTag);
+  }
+
   static SuspensionUserData = '^';
 
   bindSuspensionUserData(userData: string): Environment {
@@ -1093,7 +1122,7 @@ async function evaluateCrudMap(crud: CrudMap, env: Environment): Promise<void> {
         await runPostCreateEvents(inst, env);
       }
       if (r && entryName == AgentEntityName) {
-        defineAgentEvent(env.getActiveModuleName(), r.lookup('name'));
+        defineAgentEvent(env.getActiveModuleName(), r.lookup('name'), r.lookup('instruction'));
       }
       env.setLastResult(r);
       const betRelInfo: BetweenRelInfo | undefined = env.getBetweenRelInfo();
@@ -1365,10 +1394,9 @@ async function walkJoinQueryPattern(
 
 const MAX_PLANNER_RETRIES = 3;
 
-async function handleAgentInvocation(agentEventInst: Instance, env: Environment): Promise<void> {
-  const agent: AgentInstance = await findAgentByName(agentEventInst.name, env);
-  const origMsg: any = agentEventInst.lookup('message');
-  const msg: string = isString(origMsg) ? origMsg : agentInputAsString(origMsg);
+async function agentInvoke(agent: AgentInstance, msg: string, env: Environment): Promise<void> {
+  const flowContext = env.getFlowContext();
+  msg = flowContext ? `context: ${flowContext}\n${msg}` : msg;
   await agent.invoke(msg, env);
   const r: string | undefined = env.getLastResult();
   const isPlanner = agent.isPlanner();
@@ -1420,7 +1448,93 @@ async function handleAgentInvocation(agentEventInst: Instance, env: Environment)
       await pushToAgent(agent.output, env.getLastResult(), env);
     }
   } else {
-    logger.warn(`Agent ${agent.name} failed to generate a response`);
+    throw new Error(`Agent ${agent.name} failed to generate a response`);
+  }
+}
+
+async function handleAgentInvocation(agentEventInst: Instance, env: Environment): Promise<void> {
+  const agent: AgentInstance = await findAgentByName(agentEventInst.name, env);
+  const origMsg: any = agentEventInst.lookup('message');
+  const msg: string = isString(origMsg) ? origMsg : agentInputAsString(origMsg);
+  const flow = getAgentFlow(agent.name);
+  if (flow) {
+    await handleAgentInvocationWithFlow(agent, flow, msg, env);
+  } else {
+    await agentInvoke(agent, msg, env).catch((reason: any) => {
+      logger.warn(reason);
+    });
+  }
+}
+
+async function handleAgentInvocationWithFlow(
+  rootAgent: AgentInstance,
+  flow: FlowSpec,
+  msg: string,
+  env: Environment
+): Promise<void> {
+  await iterateOnFlow(flow, rootAgent, msg, env);
+}
+
+async function saveFlowSuspension(
+  agent: AgentInstance,
+  context: string,
+  step: FlowStep,
+  env: Environment
+): Promise<void> {
+  const suspId = await createSuspension(
+    env.getSuspensionId(),
+    [FlowSuspensionTag, agent.name, step, context],
+    env
+  );
+  env.setLastResult({ suspension: suspId || 'null' });
+}
+
+export async function restartFlow(
+  flowContext: string[],
+  userData: string,
+  env: Environment
+): Promise<void> {
+  const [_, agentName, step, ctx] = flowContext;
+  const flow = getAgentFlow(agentName);
+  if (flow) {
+    const rootAgent = await findAgentByName(agentName, env);
+    const newCtx = `${ctx}\n${step} --> ${userData}\n`;
+    await iterateOnFlow(flow, rootAgent, newCtx, env);
+  }
+}
+
+const MaxFlowSteps = 25;
+
+async function iterateOnFlow(
+  flow: FlowSpec,
+  rootAgent: AgentInstance,
+  msg: string,
+  env: Environment
+): Promise<void> {
+  rootAgent.disableSession();
+  const s = `Now consider the following flowchart and context:\n${flow}\n\n${msg}`;
+  await agentInvoke(rootAgent, s, env);
+  let step = env.getLastResult();
+  let context = msg;
+  let stepc = 0;
+  while (step != 'DONE') {
+    if (stepc > MaxFlowSteps) {
+      throw new Error(`Flow execution exceeded maximum steps limit`);
+    }
+    ++stepc;
+    const agent = AgentInstance.FromFlowStep(step, rootAgent);
+    agent.disableSession();
+    env.setFlowContext(context);
+    await agentInvoke(agent, '', env);
+    env.resetFlowContext();
+    if (env.isSuspended()) {
+      await saveFlowSuspension(rootAgent, context, step, env);
+      return;
+    }
+    const r = env.getLastResult();
+    context = `${context}\n${step} --> ${agentInputAsString(r)}\n`;
+    await agentInvoke(rootAgent, `${s}\n${context}`, env);
+    step = env.getLastResult();
   }
 }
 

package/src/runtime/loader.ts

@@ -22,8 +22,13 @@ import {
   isResolverDefinition,
   ResolverDefinition,
   ResolverMethodSpec,
-  AgentPropertyDef,
+  GenericPropertyDef,
   isLiteral,
+  ArrayLiteral,
+  MapEntry,
+  Expr,
+  FlowDefinition,
+  isFlowDefinition,
 } from '../language/generated/ast.js';
 import {
   addEntity,
@@ -47,6 +52,7 @@ import {
 import {
   escapeSpecialChars,
   findRbacSchema,
+  isFqName,
   isString,
   makeFqName,
   maybeExtends,
@@ -61,7 +67,13 @@ import { maybeGetValidationErrors, parse, parseModule, parseWorkflow } from '../
 import { logger } from './logger.js';
 import { Environment, evaluateStatements, GlobalEnvironment } from './interpreter.js';
 import { createPermission, createRole } from './modules/auth.js';
-import { AgentEntityName, CoreAIModuleName, LlmEntityName } from './modules/ai.js';
+import {
+  AgentEntityName,
+  CoreAIModuleName,
+  LlmEntityName,
+  registerAgentFlow,
+  registerFlow,
+} from './modules/ai.js';
 import { GenericResolver, GenericResolverMethods } from './resolvers/interface.js';
 import { registerResolver, setResolver } from './resolvers/registry.js';
 import { Config, ConfigSchema, setAppConfig } from './state.js';
@@ -288,6 +300,7 @@ export async function loadCoreModules() {
 
 async function loadModule(fileName: string, fsOptions?: any, callback?: Function): Promise<Module> {
   // Initialize filesystem if not already done
+  console.log(`loading ${fileName}`);
   const fs = await getFileSystem(fsOptions);
 
   const fsAdapter = getFsAdapter(fs);
@@ -455,45 +468,53 @@ async function addAgentDefinition(def: AgentDefinition, moduleName: string) {
   const attrsStrs = new Array<string>();
   attrsStrs.push(`name "${name}"`);
   const attrs = newInstanceAttributes();
-  def.body?.attributes.forEach((apdef: AgentPropertyDef) => {
-    let v: any = undefined;
-    if (apdef.value.array) {
-      v = apdef.value.array.vals
-        .map((stmt: Statement) => {
-          if (stmt.pattern.expr && isLiteral(stmt.pattern.expr)) {
-            const s = stmt.pattern.expr.str || stmt.pattern.expr.id || stmt.pattern.expr.ref;
-            if (s == undefined) {
-              throw new Error(
-                `Only arrays of string-literals or identifiers should be passed to agent ${name}`
-              );
-            }
-            return s;
-          } else {
-            throw new Error(`Invalid value in array passed to agent ${name}`);
-          }
-        })
-        .join(',');
+  attrsStrs.push(`moduleName "${moduleName}"`);
+  attrs.set('moduleName', moduleName);
+  def.body?.attributes.forEach((apdef: GenericPropertyDef) => {
+    if (apdef.name == 'flows') {
+      let fnames: string | undefined = undefined;
+      if (apdef.value.array) {
+        fnames = processAgentArray(apdef.value.array, name);
+      } else {
+        fnames = apdef.value.id || apdef.value.str;
+      }
+      if (fnames) {
+        fnames.split(',').forEach((n: string) => {
+          n = n.trim();
+          const fqn = isFqName(n) ? n : `${moduleName}/${n}`;
+          registerAgentFlow(name, fqn);
+        });
+        attrsStrs.push(`type "flow-exec"`);
+        attrs.set('type', 'flow-exec');
+      } else {
+        throw new Error(`Invalid flows list in agent ${name}`);
+      }
     } else {
-      v = apdef.value.str || apdef.value.id || apdef.value.ref || apdef.value.num;
+      let v: any = undefined;
+      if (apdef.value.array) {
+        v = processAgentArray(apdef.value.array, name);
+      } else {
+        v = apdef.value.str || apdef.value.id || apdef.value.ref || apdef.value.num;
+        if (v == undefined) {
+          v = apdef.value.bool;
+        }
+      }
       if (v == undefined) {
-        v = apdef.value.bool;
+        throw new Error(`Cannot initialize agent ${name}, only literals can be set for attributes`);
       }
+      if (llmName == undefined && apdef.name == 'llm') {
+        llmName = v;
+        hasUserLlm = true;
+      }
+      const ov = v;
+      if (apdef.value.id || apdef.value.ref || apdef.value.array) {
+        v = `"${v}"`;
+      } else if (apdef.value.str) {
+        v = `"${escapeSpecialChars(v)}"`;
+      }
+      attrsStrs.push(`${apdef.name} ${v}`);
+      attrs.set(apdef.name, ov);
     }
-    if (v == undefined) {
-      throw new Error(`Cannot initialize agent ${name}, only literals can be set for attributes`);
-    }
-    if (llmName == undefined && apdef.name == 'llm') {
-      llmName = v;
-      hasUserLlm = true;
-    }
-    const ov = v;
-    if (apdef.value.id || apdef.value.ref || apdef.value.array) {
-      v = `"${v}"`;
-    } else if (apdef.value.str) {
-      v = `"${escapeSpecialChars(v)}"`;
-    }
-    attrsStrs.push(`${apdef.name} ${v}`);
-    attrs.set(apdef.name, ov);
   });
   if (!attrs.has('llm')) {
     llmName = `${name}_llm`;
@@ -513,6 +534,45 @@ async function addAgentDefinition(def: AgentDefinition, moduleName: string) {
   addAgent(def.name, attrs, moduleName);
 }
 
+function processAgentArray(array: ArrayLiteral, attrName: string): string {
+  return array.vals
+    .map((stmt: Statement) => {
+      const expr = stmt.pattern.expr;
+      return processAgentArrayValue(expr, attrName);
+    })
+    .join(',');
+}
+
+function processAgentArrayValue(expr: Expr | undefined, attrName: string): string {
+  if (expr && isLiteral(expr)) {
+    const s = expr.str || expr.id || expr.ref || expr.bool;
+    if (s != undefined) {
+      return s;
+    }
+    if (expr.array) {
+      return processAgentArray(expr.array, attrName);
+    } else if (expr.map) {
+      const m = new Array<string>();
+      expr.map.entries.forEach((me: MapEntry) => {
+        m.push(
+          `${me.key.str || me.key.num || me.key.bool || ''}: ${processAgentArrayValue(me.value, attrName)}`
+        );
+      });
+      return `{${m.join(',')}}`;
+    } else {
+      throw new Error(`Type not supprted in agent-arrays - ${attrName}`);
+    }
+  } else {
+    throw new Error(`Invalid value in array passed to agent ${attrName}`);
+  }
+}
+
+function addFlowDefinition(def: FlowDefinition, moduleName: string) {
+  if (def.body && def.$cstNode) {
+    registerFlow(`${moduleName}/${def.name}`, def.$cstNode.text);
+  }
+}
+
 function addResolverDefinition(def: ResolverDefinition, moduleName: string) {
   const resolverName = `${moduleName}/${def.name}`;
   const paths = def.paths;
@@ -571,6 +631,7 @@ export async function addFromDef(def: Definition, moduleName: string) {
   else if (isAgentDefinition(def)) await addAgentDefinition(def, moduleName);
   else if (isStandaloneStatement(def)) addStandaloneStatement(def.stmt, moduleName);
   else if (isResolverDefinition(def)) addResolverDefinition(def, moduleName);
+  else if (isFlowDefinition(def)) addFlowDefinition(def, moduleName);
 }
 
 export async function parseAndIntern(code: string, moduleName?: string) {

package/src/runtime/module.ts

@@ -850,8 +850,10 @@ export class Agent extends Record {
   override toString(): string {
     const attrs = new Array<string>();
     this.attributes.forEach((value: any, key: string) => {
-      const v = isString(value) ? `"${value}"` : value;
-      attrs.push(`    ${key} ${v}`);
+      if (key != 'moduleName') {
+        const v = isString(value) ? `"${value}"` : value;
+        attrs.push(`    ${key} ${v}`);
+      }
     });
     return `agent ${Agent.NormalizeName(this.name)}
 {
@@ -2848,14 +2850,22 @@ export function assertInstance(obj: any) {
 
 const IsAgentEventMeta = 'is-agent-event';
 const EventAgentName = 'event-agent-name';
+const DocumentationMetaTag = 'documentation';
 
-export function defineAgentEvent(moduleName: string, agentName: string) {
+export function defineAgentEvent(moduleName: string, agentName: string, instruction?: string) {
   const module = fetchModule(moduleName);
   const event: Record = new Event(agentName, moduleName);
   event.addAttribute('message', { type: 'Any' });
   event.addAttribute('chatId', { type: 'String' });
   event.addMeta(IsAgentEventMeta, 'y');
   event.addMeta(EventAgentName, agentName);
+  if (instruction) {
+    event.addMeta(
+      DocumentationMetaTag,
+      `This event will trigger an agent which has the instruction - "${instruction}".
+    So make sure to pass all relevant information in the 'message' attribute of this event.`
+    );
+  }
   module.addEntry(event);
 }