agentlang 0.10.1 → 0.10.2

package/src/language/parser.ts

@@ -36,9 +36,16 @@ import {
   SetAttribute,
   Statement,
   WhereSpec,
+  WhereSpecClause,
   WorkflowDefinition,
 } from './generated/ast.js';
-import { firstAliasSpec, firstCatchSpec, isString, QuerySuffix } from '../runtime/util.js';
+import {
+  firstAliasSpec,
+  firstCatchSpec,
+  firstEmptySpec,
+  isString,
+  QuerySuffix,
+} from '../runtime/util.js';
 import {
   BasePattern,
   CrudPattern,
@@ -54,6 +61,7 @@ import {
   NegExpressionPattern,
   NotExpressionPattern,
   ReturnPattern,
+  WhereSpecClausePattern,
 } from './syntax.js';
 
 let nextDocumentId = 1;
@@ -262,6 +270,10 @@ function introspectStatement(stmt: Statement): BasePattern {
       r.addHandler(h.except, introspectStatement(h.stmt));
     });
   }
+  const emptySpec = firstEmptySpec(stmt);
+  if (emptySpec) {
+    r.setEmptyHandler(introspectStatement(emptySpec.stmt));
+  }
   return r;
 }
 
@@ -299,6 +311,14 @@ function introspectPattern(pat: Pattern): BasePattern {
 function introspectInto(intoSpec: SelectIntoSpec, p: CrudPattern): CrudPattern {
   intoSpec.entries.forEach((se: SelectIntoEntry) => {
     if (se.attribute) p.addInto(se.alias, se.attribute);
+    else if (se.aggregate) {
+      const args = se.aggregate.args
+        .map((s: string) => {
+          return s;
+        })
+        .join(', ');
+      p.addInto(se.alias, `@${se.aggregate?.name}(${args})`);
+    }
   });
   return p;
 }
@@ -379,6 +399,18 @@ function introspectQueryPattern(crudMap: CrudMap): CrudPattern {
       };
       cp.joins.push(jp);
     });
+    if (opts.where?.clauses) {
+      cp.where = new Array<WhereSpecClausePattern>();
+      opts.where.clauses.forEach((wc: WhereSpecClause) => {
+        cp.where?.push({ lhs: wc.lhs, op: wc.op || '=', rhs: wc.rhs.$cstNode?.text || '' });
+      });
+    }
+    if (opts.groupByClause) {
+      cp.groupBy = opts.groupByClause.colNames;
+    }
+    if (opts.orderByClause) {
+      cp.orderBy = opts.orderByClause.colNames;
+    }
     cp.isCreate = false;
     cp.isQueryUpdate = false;
     cp.isQuery = true;

package/src/language/syntax.ts

@@ -15,6 +15,7 @@ export class BasePattern {
   alias: string | undefined;
   aliases: string[] | undefined;
   handlers: Map<string, BasePattern> | undefined;
+  emptyHandler: BasePattern | undefined;
 
   setAlias(alias: string) {
     this.alias = alias;
@@ -44,6 +45,11 @@ export class BasePattern {
     this.handlers.set(k, handler);
   }
 
+  setEmptyHandler(handler: BasePattern) {
+    this.emptyHandler = handler;
+    return this;
+  }
+
   private aliasesAsString(): string | undefined {
     if (this.alias) {
       return ` @as ${this.alias}`;
@@ -54,24 +60,30 @@ export class BasePattern {
     }
   }
 
+  private emptyHandlerAsString(): string | undefined {
+    if (this.emptyHandler) {
+      return ` @empty ${this.emptyHandler.toString()}`;
+    }
+    return undefined;
+  }
+
   private handlersAsString(): string | undefined {
-    if (this.handlers) {
-      let s = '{';
+    if (this.handlers && this.handlers.size > 0) {
+      let s = ' @catch {';
       this.handlers.forEach((handler: BasePattern, k: string) => {
-        s = `${s} ${k} ${handler.toString()}\n`;
+        s = `${s}${k} ${handler.toString()} `;
       });
-      return s + '}';
-    } else {
-      return undefined;
+      return s.trimEnd() + '}';
     }
+    return undefined;
   }
+
   hintsAsString(): string {
-    const a = this.aliasesAsString();
-    const h = this.handlersAsString();
-    if (!a && !h) return '';
-    if (a && !h) return a;
-    if (!a && h) return h;
-    return `${a}\n${h}`;
+    // Order matters: @as, then @catch, then @empty (must be last because it's greedy in the grammar)
+    const a = this.aliasesAsString() ?? '';
+    const h = this.handlersAsString() ?? '';
+    const e = this.emptyHandlerAsString() ?? '';
+    return `${a}${h}${e}`;
   }
 
   toString(): string {
@@ -386,12 +398,21 @@ function joinPatternToString(jp: JoinPattern): string {
   return `${jp.type} ${jp.targetEntity} {${jp.conditionLhs}${opr} ${jp.conditionRhs}}`;
 }
 
+export type WhereSpecClausePattern = {
+  lhs: string;
+  op: string;
+  rhs: string;
+};
+
 export class CrudPattern extends BasePattern {
   recordName: string;
   attributes: Array<AttributePattern>;
   relationships: Map<string, CrudPattern[] | CrudPattern> | undefined;
   joins: JoinPattern[];
   into: Map<string, string> | undefined;
+  where: WhereSpecClausePattern[] | undefined;
+  groupBy: string[] | undefined;
+  orderBy: string[] | undefined;
   isQuery: boolean = false;
   isQueryUpdate: boolean = false;
   isCreate: boolean = false;
@@ -521,15 +542,29 @@ export class CrudPattern extends BasePattern {
     return escapeQueryName(this.recordName);
   }
 
-  private intoAsString(): string | undefined {
-    if (this.into) {
-      const ss = new Array<string>();
-      this.into.forEach((attr: string, alias: string) => {
-        ss.push(`${alias} ${attr}`);
-      });
-      return `@into { ${ss.join(',\n')} }`;
-    }
-    return undefined;
+  private intoAsString(): string {
+    const ss = new Array<string>();
+    this.into?.forEach((attr: string, alias: string) => {
+      ss.push(`${alias} ${attr}`);
+    });
+    return `@into { ${ss.join(',\n')} }`;
+  }
+
+  private whereAsString(): string {
+    const ss = new Array<string>();
+    this.where?.forEach((wc: WhereSpecClausePattern) => {
+      if (wc.op == '=') ss.push(`${wc.lhs} ${wc.rhs}`);
+      else ss.push(`${wc.lhs} ${wc.op} ${wc.rhs}`);
+    });
+    return `@where {${ss.join(`,\n`)}}`;
+  }
+
+  private groupByAsString(): string {
+    return `@groupBy(${this.groupBy?.join(', ')})`;
+  }
+
+  private orderByAsString(): string {
+    return `@orderBy(${this.orderBy?.join(', ')})`;
   }
 
   override toString(): string {
@@ -542,10 +577,22 @@ export class CrudPattern extends BasePattern {
       const js = this.joins.map(joinPatternToString);
       s = s.concat(`,\n${js.join(',\n')}`);
     }
-    const ins = this.intoAsString();
-    if (ins) {
-      s = s.concat(`,\n${ins}`);
+    if (this.into) {
+      const ins = this.intoAsString();
+      if (ins) {
+        s = s.concat(`,\n${ins}`);
+      }
+    }
+    if (this.where) {
+      s = s.concat(`,\n${this.whereAsString()}`);
     }
+    if (this.groupBy) {
+      s = s.concat(`,\n${this.groupByAsString()}`);
+    }
+    if (this.orderBy) {
+      s = s.concat(`,\n${this.orderByAsString()}`);
+    }
+
     return s.concat('}', this.hintsAsString());
   }
 }

package/src/runtime/api.ts

@@ -5,9 +5,11 @@ import {
 } from './module.js';
 import { getLocalEnv as al_getLocalEnv, setLocalEnv as al_setLocalEnv } from './auth/defs.js';
 import { now } from './util.js';
+import { initDateFns } from './datefns.js';
 
 declare global {
   var agentlang: any | undefined;
+  var dateFns: ReturnType<typeof initDateFns> | undefined;
   function getLocalEnv(k: string, defaultValue?: string): string | undefined;
   function setLocalEnv(k: string, v: string): string;
   function uuid(): string;
@@ -32,6 +34,9 @@ export function initGlobalApi() {
     globalThis.getLocalEnv = al_getLocalEnv;
     globalThis.setLocalEnv = al_setLocalEnv;
 
+    // Expose date-fns functions globally as dateFns.*
+    globalThis.dateFns = initDateFns();
+
     ApiInited = true;
   }
 }

package/src/runtime/datefns.ts

@@ -0,0 +1,112 @@
+import {
+  addDays as _addDays,
+  addWeeks as _addWeeks,
+  addMonths as _addMonths,
+  startOfWeek as _startOfWeek,
+  endOfWeek as _endOfWeek,
+  startOfMonth as _startOfMonth,
+  endOfMonth as _endOfMonth,
+  getISOWeek,
+  format,
+  parse,
+  differenceInDays,
+  differenceInWeeks,
+} from 'date-fns';
+import { formatInTimeZone } from 'date-fns-tz';
+
+/**
+ * Parse a date string as local midnight to avoid timezone day-shift issues.
+ * date-fns operates in local time, so we must parse date-only strings
+ * (YYYY-MM-DD) as local midnight rather than UTC midnight.
+ */
+function toDate(dateStr: string): Date {
+  if (!dateStr.includes('T')) {
+    const [y, m, d] = dateStr.split('-').map(Number);
+    return new Date(y, m - 1, d);
+  }
+  return new Date(dateStr);
+}
+
+function toDateStr(d: Date): string {
+  return format(d, 'yyyy-MM-dd');
+}
+
+function addDays(dateStr: string, days: number): string {
+  return toDateStr(_addDays(toDate(dateStr), days));
+}
+
+function addWeeks(dateStr: string, weeks: number): string {
+  return toDateStr(_addWeeks(toDate(dateStr), weeks));
+}
+
+function addMonths(dateStr: string, months: number): string {
+  return toDateStr(_addMonths(toDate(dateStr), months));
+}
+
+function startOfWeek(dateStr: string): string {
+  return toDateStr(_startOfWeek(toDate(dateStr), { weekStartsOn: 1 }));
+}
+
+function endOfWeek(dateStr: string): string {
+  return toDateStr(_endOfWeek(toDate(dateStr), { weekStartsOn: 1 }));
+}
+
+function startOfMonth(dateStr: string): string {
+  return toDateStr(_startOfMonth(toDate(dateStr)));
+}
+
+function endOfMonth(dateStr: string): string {
+  return toDateStr(_endOfMonth(toDate(dateStr)));
+}
+
+function getWeek(dateStr: string): number {
+  return getISOWeek(toDate(dateStr));
+}
+
+function dayName(dateStr: string): string {
+  return format(toDate(dateStr), 'EEEE');
+}
+
+function formatDate(dateStr: string, fmt: string): string {
+  return format(toDate(dateStr), fmt);
+}
+
+function parseDate(str: string, fmt: string): string {
+  return toDateStr(parse(str, fmt, new Date()));
+}
+
+function diffInDays(dateStr1: string, dateStr2: string): number {
+  return differenceInDays(toDate(dateStr1), toDate(dateStr2));
+}
+
+function diffInWeeks(dateStr1: string, dateStr2: string): number {
+  return differenceInWeeks(toDate(dateStr1), toDate(dateStr2));
+}
+
+function today(): string {
+  return toDateStr(new Date());
+}
+
+function toTimezone(dateStr: string, tz: string): string {
+  return formatInTimeZone(new Date(dateStr), tz, 'yyyy-MM-dd HH:mm:ssXXX');
+}
+
+export function initDateFns() {
+  return {
+    addDays,
+    addWeeks,
+    addMonths,
+    startOfWeek,
+    endOfWeek,
+    startOfMonth,
+    endOfMonth,
+    getWeek,
+    dayName,
+    formatDate,
+    parseDate,
+    diffInDays,
+    diffInWeeks,
+    today,
+    toTimezone,
+  };
+}

package/src/runtime/exec-graph.ts

@@ -304,8 +304,8 @@ export async function executeGraph(execGraph: ExecGraph, env: Environment): Prom
         throw reason;
       } finally {
         if (monitoringEnabled) {
-          if (monitorIncr) env.decrementMonitor();
           env.setMonitorEntryResult(env.getLastResult());
+          if (monitorIncr) env.decrementMonitor();
         }
       }
     }
@@ -425,10 +425,28 @@ export async function executeEvent(
       env.setActiveEvent(eventInstance);
       await executeEventHelper(eventInstance, env);
     } else if (isAgentEventInstance(eventInstance)) {
+      env.setActiveEvent(eventInstance);
+      if (isMonitoringEnabled()) {
+        env.appendEntryToMonitor(
+          `{${eventInstance.getFqName()} {message "${eventInstance.lookup('message')}"}}`
+        );
+      }
       await handleAgentInvocation(eventInstance, env);
+      if (isMonitoringEnabled()) {
+        env.setMonitorEntryResult(env.getLastResult());
+      }
     }
     const r = env.getLastResult();
-    if (continuation) continuation(r);
+    if (continuation) {
+      if (env.getLastPattern() && isAgentEventInstance(eventInstance)) {
+        continuation({
+          result: r.map((res: any) => (res.attributes ? Object.fromEntries(res.attributes) : res)),
+          pattern: env.getLastPattern(),
+        });
+      } else {
+        continuation(r);
+      }
+    }
     return r;
   } catch (err) {
     if (env && env.hasHandlers()) {
@@ -490,6 +508,9 @@ export async function executeEventHelper(eventInstance: Instance, env?: Environm
         );
       }
       await handleAgentInvocation(eventInstance, env);
+      if (isMonitoringEnabled()) {
+        env.setMonitorEntryResult(env.getLastResult());
+      }
     }
     if (isLocalEnv) {
       await env.commitAllTransactions();

package/src/runtime/interpreter.ts

@@ -119,6 +119,7 @@ import { Monitor, MonitorEntry } from './monitor.js';
 import { detailedDiff } from 'deep-object-diff';
 import { callMcpTool, mcpClientNameFromToolEvent } from './mcpclient.js';
 import { isNodeEnv } from '../utils/runtime.js';
+import Handlebars from 'handlebars';
 
 export type Result = any;
 
@@ -131,6 +132,7 @@ export function isEmptyResult(r: Result): boolean {
 type BetweenRelInfo = {
   relationship: Relationship;
   connectedInstance: Instance;
+  connectedAlias?: string;
 };
 
 function mkEnvName(name: string | undefined, parent: Environment | undefined): string {
@@ -155,6 +157,7 @@ export class Environment extends Instance {
   private activeUserSet: boolean = false;
   private lastResult: Result;
   private trashedResult: Result = undefined;
+  private lastPattern: string | undefined;
   private returnFlag: boolean = false;
   private parentPath: string | undefined;
   private normalizedParentPath: string | undefined;
@@ -174,6 +177,7 @@ export class Environment extends Instance {
   private agentChatId: string | undefined = undefined;
   private monitor: Monitor | undefined = undefined;
   private escalatedRole: string | undefined;
+  private activeChatId: string | undefined;
 
   private activeUserData: any = undefined;
 
@@ -201,6 +205,7 @@ export class Environment extends Instance {
       this.agentChatId = parent.agentChatId;
       this.monitor = parent.monitor;
       this.escalatedRole = parent.escalatedRole;
+      this.activeChatId = parent.activeChatId;
     } else {
       this.activeModule = DefaultModuleName;
       this.activeResolvers = new Map<string, Resolver>();
@@ -327,6 +332,15 @@ export class Environment extends Instance {
     return this.attributes.get(Environment.FlowContextTag);
   }
 
+  setActiveChatId(chatId: string): Environment {
+    this.activeChatId = chatId;
+    return this;
+  }
+
+  getActiveChatId(): string | undefined {
+    return this.activeChatId;
+  }
+
   addToScratchPad(k: string, data: any): Environment {
     if (this.scratchPad === undefined) {
       this.scratchPad = {};
@@ -397,6 +411,11 @@ export class Environment extends Instance {
     return this;
   }
 
+  maybeRewriteTemplatePatterns(instruction: string, scratchPad?: any): string {
+    const templ = Handlebars.compile(this.rewriteTemplateMappings(instruction));
+    return templ(scratchPad);
+  }
+
   static SuspensionUserData = '^';
 
   bindSuspensionUserData(userData: string): Environment {
@@ -554,6 +573,15 @@ export class Environment extends Instance {
     return this.lastResult;
   }
 
+  setLastPattern(pattern: string | undefined): Environment {
+    this.lastPattern = pattern;
+    return this;
+  }
+
+  getLastPattern(): string | undefined {
+    return this.lastPattern;
+  }
+
   getActiveModuleName(): string {
     return this.activeModule;
   }
@@ -891,6 +919,13 @@ export class Environment extends Instance {
     return this;
   }
 
+  setMonitorEntryLlmTokenUsage(input: number, output: number, total: number): Environment {
+    if (this.monitor !== undefined) {
+      this.monitor.setEntryLlmTokenUsage(input, output, total);
+    }
+    return this;
+  }
+
   incrementMonitor(): Environment {
     if (this.monitor !== undefined) {
       this.monitor = this.monitor.increment();
@@ -939,7 +974,13 @@ export let evaluate = async function (
       } else if (isAgentEventInstance(eventInstance)) {
         env = new Environment(eventInstance.name + '.env', activeEnv);
         await handleAgentInvocation(eventInstance, env);
-        if (continuation) continuation(env.getLastResult());
+        if (continuation) {
+          if (env.getLastPattern()) {
+            continuation({ result: env.getLastResult(), pattern: env.getLastPattern() });
+          } else {
+            continuation(env.getLastResult());
+          }
+        }
       } else if (isOpenApiEventInstance(eventInstance)) {
         env = new Environment(eventInstance.name + '.env', activeEnv);
         await handleOpenApiEvent(eventInstance, env);
@@ -1092,6 +1133,9 @@ export async function evaluateStatement(stmt: Statement, env: Environment): Prom
       handlersPushed = env.pushHandlers(handlers);
     }
     await evaluatePattern(stmt.pattern, env);
+    if (hasHints) {
+      await maybeHandleEmpty(hints, env);
+    }
     if (hasHints) {
       maybeBindStatementResultToAlias(hints, env);
     }
@@ -1121,6 +1165,24 @@ async function maybeHandleNotFound(handlers: CatchHandlers | undefined, env: Env
   }
 }
 
+async function maybeHandleEmpty(hints: RuntimeHint[], env: Environment) {
+  const lastResult: Result = env.getLastResult();
+  if (
+    lastResult === null ||
+    lastResult === undefined ||
+    (lastResult instanceof Array && lastResult.length == 0)
+  ) {
+    for (const rh of hints) {
+      if (rh.emptySpec) {
+        const newEnv = new Environment('empty-env', env).unsetEventExecutor();
+        await evaluateStatement(rh.emptySpec.stmt, newEnv);
+        env.setLastResult(newEnv.getLastResult());
+        break;
+      }
+    }
+  }
+}
+
 async function maybeHandleError(
   handlers: CatchHandlers | undefined,
   reason: any,
@@ -1646,7 +1708,8 @@ async function evaluateCrudMap(crud: CrudMap, env: Environment): Promise<void> {
         const insts: Instance[] = await res.queryConnectedInstances(
           betRelInfo.relationship,
           betRelInfo.connectedInstance,
-          inst
+          inst,
+          betRelInfo.connectedAlias
         );
         env.setLastResult(insts);
       } else {
@@ -1671,7 +1734,7 @@ async function evaluateCrudMap(crud: CrudMap, env: Environment): Promise<void> {
             false,
             true
           );
-          env.setLastResult(inst);
+          env.setLastResult([inst]);
         } else {
           const insts: Instance[] = await res.queryInstances(inst, isQueryAll, distinct);
           env.setLastResult(insts);
@@ -1698,7 +1761,12 @@ async function evaluateCrudMap(crud: CrudMap, env: Environment): Promise<void> {
               await evaluatePattern(rel.pattern, newEnv);
               lastRes[j].attachRelatedInstances(rel.name, newEnv.getLastResult());
             } else if (isBetweenRelationship(rel.name, moduleName)) {
-              newEnv.setBetweenRelInfo({ relationship: relEntry, connectedInstance: lastRes[j] });
+              const connAlias = relEntry.isSelfReferencing() ? relEntry.node1.alias : undefined;
+              newEnv.setBetweenRelInfo({
+                relationship: relEntry,
+                connectedInstance: lastRes[j],
+                connectedAlias: connAlias,
+              });
               await evaluatePattern(rel.pattern, newEnv);
               lastRes[j].attachRelatedInstances(rel.name, newEnv.getLastResult());
             }
@@ -1734,7 +1802,7 @@ async function evaluateCrudMap(crud: CrudMap, env: Environment): Promise<void> {
           await runPreUpdateEvents(lastRes, env);
           const finalInst: Instance = await res.updateInstance(lastRes, attrs);
           await runPostUpdateEvents(finalInst, lastRes, env);
-          env.setLastResult(finalInst);
+          env.setLastResult([finalInst]);
         }
       }
     }
@@ -2035,6 +2103,11 @@ async function agentInvoke(agent: AgentInstance, msg: string, env: Environment):
       while (true) {
         try {
           let rs: string = result ? normalizeGeneratedCode(result) : '';
+          if (agent.tools) {
+            env.setLastPattern(rs);
+          } else {
+            env.setLastPattern(undefined);
+          }
           let isWf = rs.startsWith('workflow');
           if (isWf && !agent.runWorkflows) {
             await parseWorkflow(rs);
@@ -2128,6 +2201,10 @@ export async function handleAgentInvocation(
   env: Environment
 ): Promise<void> {
   const agent: AgentInstance = await findAgentByName(agentEventInst.name, env);
+  const chatId = agentEventInst.lookup('chatId');
+  if (chatId) {
+    env.setActiveChatId(chatId);
+  }
   const origMsg: any =
     agentEventInst.lookup('message') || JSON.stringify(agentEventInst.asObject());
   const msg: string = isString(origMsg) ? origMsg : maybeInstanceAsString(origMsg);
@@ -2137,7 +2214,6 @@ export async function handleAgentInvocation(
   } else {
     const mode = agentEventInst.lookup('mode');
     let activeEnv = env;
-    const chatId = agentEventInst.lookup('chatId');
     if (chatId !== undefined) {
       activeEnv.setAgentChatId(chatId);
     }

package/src/runtime/module.ts

@@ -1409,6 +1409,10 @@ export class Relationship extends Record {
     return this.relType == RelType.BETWEEN;
   }
 
+  isSelfReferencing(): boolean {
+    return this.node1.path.asFqName() === this.node2.path.asFqName();
+  }
+
   parentNode(): RelationshipNode {
     return this.node1;
   }
@@ -1502,6 +1506,28 @@ export class Relationship extends Record {
     }
   }
 
+  /**
+   * For self-referencing relationships, resolve the alias for the connected instance
+   * based on an explicit connectedAlias. Falls back to fqName-based lookup for
+   * non-self-referencing relationships.
+   */
+  getAliasForConnected(inst: Instance, connectedAlias?: string): string {
+    if (connectedAlias && this.isSelfReferencing()) {
+      return connectedAlias;
+    }
+    return this.getAliasFor(inst);
+  }
+
+  getInverseAliasForConnected(inst: Instance, connectedAlias?: string): string {
+    if (connectedAlias && this.isSelfReferencing()) {
+      if (connectedAlias === this.node1.alias) {
+        return this.node2.alias;
+      }
+      return this.node1.alias;
+    }
+    return this.getInverseAliasFor(inst);
+  }
+
   isParent(inst: Instance): boolean {
     return inst.getFqName() == this.node1.path.asFqName();
   }