agentlang 0.0.40 → 0.0.51

package/src/language/syntax.ts

@@ -715,3 +715,24 @@ function patternsToString(body: BasePattern[], sep = ';\n'): string {
     })
     .join(sep);
 }
+
+export class FlowStepPattern extends BasePattern {
+  first: string;
+  next: string;
+  condition?: string;
+
+  constructor(first: string, next: string, condition?: string) {
+    super();
+    this.first = first;
+    this.next = next;
+    this.condition = condition;
+  }
+
+  override toString(): string {
+    if (this.condition) {
+      return `${this.first} --> ${this.condition} ${this.next}`;
+    } else {
+      return `${this.first} --> ${this.next}`;
+    }
+  }
+}

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,93 @@ 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.
+`;
+
+export type FlowSpec = string;
+export type FlowStep = string;
+
+const AgentFlows = new Map<string, string[]>();
+const FlowRegistry = new Map<string, FlowSpec>();
+
+export function registerFlow(name: string, flow: FlowSpec): string {
+  FlowRegistry.set(name, flow);
+  return name;
+}
+
+export function getFlow(name: string): FlowSpec | undefined {
+  return FlowRegistry.get(name);
+}
+
+export function registerAgentFlow(agentName: string, flowSpecName: string): string {
+  let currentFlows = AgentFlows.get(agentName);
+  if (currentFlows) {
+    currentFlows.push(flowSpecName);
+  } else {
+    currentFlows = new Array<string>();
+    currentFlows.push(flowSpecName);
+  }
+  AgentFlows.set(agentName, currentFlows);
+  return agentName;
+}
+
+// Return the first flow registered with the agent.
+export function getAgentFlow(agentName: string): FlowSpec | undefined {
+  const currentFlows = AgentFlows.get(agentName);
+  if (currentFlows) {
+    return getFlow(currentFlows[0]);
+  } else {
+    return undefined;
+  }
+}
+
+export function getAllAgentFlows(agentName: string): FlowSpec[] | undefined {
+  return AgentFlows.get(agentName);
+}

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

@@ -543,11 +543,11 @@ export class CognitoAuth implements AgentlangAuth {
         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);
@@ -891,7 +891,7 @@ export class CognitoAuth implements AgentlangAuth {
       try {
         // Get additional user details from Cognito
         const client = new CognitoIdentityProviderClient({
-          region: process.env.AWS_REGION || 'us-west-2'
+          region: process.env.AWS_REGION || 'us-west-2',
         });
 
         const command = new AdminGetUserCommand({

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

@@ -47,7 +47,8 @@ import {
   Relationship,
   Workflow,
 } from './module.js';
-import { JoinInfo, Resolver, ResolverAuthInfo } from './resolvers/interface.js';
+import { JoinInfo, Resolver } from './resolvers/interface.js';
+import { ResolverAuthInfo } from './resolvers/authinfo.js';
 import { SqlDbResolver } from './resolvers/sqldb/impl.js';
 import {
   CrudType,
@@ -72,7 +73,12 @@ 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 { logger } from './logger.js';
-import { ParentAttributeName, PathAttributeName, PathAttributeNameQuery } from './defs.js';
+import {
+  FlowSuspensionTag,
+  ParentAttributeName,
+  PathAttributeName,
+  PathAttributeNameQuery,
+} from './defs.js';
 import {
   addCreateAudit,
   addDeleteAudit,
@@ -84,6 +90,7 @@ import {
 import { invokeModuleFn } from './jsmodules.js';
 import { invokeOpenApiEvent, isOpenApiEventInstance } from './openapi.js';
 import { fetchDoc } from './docs.js';
+import { FlowSpec, FlowStep, getAgentFlow } from './agents/common.js';
 
 export type Result = any;
 
@@ -156,6 +163,7 @@ export class Environment extends Instance {
       this.activeResolvers = new Map<string, Resolver>();
       this.activeTransactions = new Map<string, string>();
       this.activeCatchHandlers = new Array<CatchHandlers>();
+      this.attributes.set('process', process);
     }
   }
 
@@ -238,6 +246,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 +1117,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 +1389,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 +1443,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,
@@ -43,10 +48,12 @@ import {
   removeModule,
   newInstanceAttributes,
   addAgent,
+  fetchModule,
 } from './module.js';
 import {
   escapeSpecialChars,
   findRbacSchema,
+  isFqName,
   isString,
   makeFqName,
   maybeExtends,
@@ -69,6 +76,7 @@ import { getModuleFn, importModule } from './jsmodules.js';
 import { SetSubscription } from './defs.js';
 import { ExtendedFileSystem } from '../utils/fs/interfaces.js';
 import z from 'zod';
+import { registerAgentFlow, registerFlow } from './agents/common.js';
 
 export async function extractDocument(
   fileName: string,
@@ -288,6 +296,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);
@@ -418,7 +427,7 @@ export function addWorkflowFromDef(def: WorkflowDefinition, moduleName: string):
 
 const StandaloneStatements = new Map<string, Statement[]>();
 
-function addStandaloneStatement(stmt: Statement, moduleName: string) {
+function addStandaloneStatement(stmt: Statement, moduleName: string, userDefined = true) {
   let stmts: Array<Statement> | undefined = StandaloneStatements.get(moduleName);
   if (stmts == undefined) {
     stmts = new Array<Statement>();
@@ -427,6 +436,10 @@ function addStandaloneStatement(stmt: Statement, moduleName: string) {
   if (!StandaloneStatements.has(moduleName)) {
     StandaloneStatements.set(moduleName, stmts);
   }
+  if (userDefined) {
+    const m = fetchModule(moduleName);
+    m.addStandaloneStatement(stmt);
+  }
 }
 
 export async function runStandaloneStatements() {
@@ -455,45 +468,55 @@ 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');
+        attrsStrs.push(`flows "${fnames}"`);
+        attrs.set('flows', fnames);
+      } 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`;
@@ -505,14 +528,64 @@ async function addAgentDefinition(def: AgentDefinition, moduleName: string) {
   }, @upsert}`;
   let wf = createAgent;
   if (llmName) {
-    wf = `{${CoreAIModuleName}/${LlmEntityName} {name "${llmName}"}, @upsert}; ${wf}`;
+    const service = process.env.ANTHROPIC_API_KEY ? 'anthropic' : 'openai';
+    wf = `{${CoreAIModuleName}/${LlmEntityName} {name "${llmName}", service "${service}"}, @upsert}; ${wf}`;
   }
   (await parseWorkflow(`workflow A {${wf}}`)).statements.forEach((stmt: Statement) => {
-    addStandaloneStatement(stmt, moduleName);
+    addStandaloneStatement(stmt, moduleName, false);
   });
   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) {
+    const m = fetchModule(moduleName);
+    const sdef = def.$cstNode.text;
+    const idx = sdef.indexOf('{');
+    let f = '';
+    if (idx > 0) {
+      f = sdef.substring(idx + 1, sdef.lastIndexOf('}')).trim();
+    } else {
+      f = sdef;
+    }
+    m.addFlow(def.name, f);
+    registerFlow(`${moduleName}/${def.name}`, f);
+  }
+}
+
 function addResolverDefinition(def: ResolverDefinition, moduleName: string) {
   const resolverName = `${moduleName}/${def.name}`;
   const paths = def.paths;
@@ -571,6 +644,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) {