agentlang 0.10.8 → 0.11.0

package/src/runtime/errors/coded-error.ts

@@ -0,0 +1,18 @@
+/** Stable bucket for errors without an explicit code. */
+export const AL_RUNTIME_UNHANDLED = 'AL_RUNTIME_UNHANDLED';
+
+export type CodedError = Error & { agentlangCode: string };
+
+export function createCodedError(message: string, code: string): CodedError {
+  const e = new Error(message) as CodedError;
+  e.agentlangCode = code;
+  return e;
+}
+
+export function isCodedError(err: unknown): err is CodedError {
+  return (
+    err instanceof Error &&
+    typeof (err as CodedError).agentlangCode === 'string' &&
+    (err as CodedError).agentlangCode.length > 0
+  );
+}

package/src/runtime/errors/http-error.ts

@@ -0,0 +1,197 @@
+import { AgentCancelledException } from '../modules/ai.js';
+import { lookupCustomErrorMessage } from '../modules/core.js';
+import {
+  BadRequestError,
+  CodeMismatchError,
+  ExpiredCodeError,
+  InvalidParameterError,
+  PasswordResetRequiredError,
+  TooManyRequestsError,
+  UnauthorisedError,
+  UserNotConfirmedError,
+  UserNotFoundError,
+} from '../defs.js';
+import { errorFileLogger, logger } from '../logger.js';
+import { AppConfig } from '../state.js';
+import { AL_RUNTIME_UNHANDLED, isCodedError } from './coded-error.js';
+
+/** Registry of Tier-1 HTTP-facing error codes (documentation / consistency). */
+export const AgentlangErrorCodes = {
+  AL_RUNTIME_UNHANDLED,
+  AL_HTTP_AUTH_REQUIRED: 'AL_HTTP_AUTH_REQUIRED',
+  AL_HTTP_HANDLER_EXCEPTION: 'AL_HTTP_HANDLER_EXCEPTION',
+} as const;
+
+/** `target` value of an override that applies to any entity for a given code. */
+const UNIVERSAL_TARGET = '*';
+
+/** Replace `{{code}}` and `{{message}}` with runtime values (iterates until stable). */
+export function applyErrorMessageTemplate(
+  template: string,
+  code: string,
+  originalMessage: string
+): string {
+  let out = template;
+  const maxPasses = 10;
+  for (let i = 0; i < maxPasses; i++) {
+    const next = out.replace(/\{\{code\}\}/g, code).replace(/\{\{message\}\}/g, originalMessage);
+    if (next === out) break;
+    out = next;
+  }
+  return out;
+}
+
+function customMessagesEnabled(): boolean {
+  return AppConfig?.customErrorMessages?.enabled === true;
+}
+
+/**
+ * When custom error messages are enabled, append the error to a dedicated
+ * `logs/errors-<DATE>.log` file as a single line: timestamp (added by the logger),
+ * error code, and error message. No-op when custom messages are disabled.
+ */
+export function recordCustomError(code: string, message: string): void {
+  if (!customMessagesEnabled()) {
+    return;
+  }
+  try {
+    errorFileLogger?.error(`${code} ${message}`);
+  } catch (e) {
+    logger.warn(`Failed to write error to errors log file: ${e}`);
+  }
+}
+
+export function getErrorCode(err: unknown): string {
+  if (isCodedError(err)) {
+    return err.agentlangCode;
+  }
+  if (err instanceof UnauthorisedError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof BadRequestError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof UserNotFoundError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof UserNotConfirmedError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof PasswordResetRequiredError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof TooManyRequestsError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof InvalidParameterError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof ExpiredCodeError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof CodeMismatchError) {
+    return err.agentlangCode;
+  }
+  if (err instanceof AgentCancelledException) {
+    return err.agentlangCode;
+  }
+  return AL_RUNTIME_UNHANDLED;
+}
+
+/**
+ * Resolve the message for an entity-route error from the `agentlang/errorMessage`
+ * system entity. An entity-specific override (`module/Entry`) wins over a universal
+ * (`*`) one for the same code; falls back to `defaultMessage` when neither exists or
+ * when custom messages are disabled.
+ */
+export async function resolveEntityErrorMessage(
+  moduleName: string,
+  entryName: string,
+  code: string,
+  defaultMessage: string
+): Promise<string> {
+  if (!customMessagesEnabled()) {
+    return defaultMessage;
+  }
+  let template: string | undefined;
+  try {
+    const entityKey = `${moduleName}/${entryName}`;
+    template =
+      (await lookupCustomErrorMessage(entityKey, code)) ??
+      (await lookupCustomErrorMessage(UNIVERSAL_TARGET, code));
+  } catch (e) {
+    logger.warn(`Failed to resolve custom error message for code ${code}: ${e}`);
+    return defaultMessage;
+  }
+  if (template === undefined) {
+    return defaultMessage;
+  }
+  return applyErrorMessageTemplate(template, code, defaultMessage);
+}
+
+export function httpStatusFromError(err: unknown): number {
+  const ec = getErrorCode(err);
+  if (ec === 'AL_DB_UNIQUE_VIOLATION') {
+    return 409;
+  }
+  if (
+    ec === 'AL_DB_FOREIGN_KEY_VIOLATION' ||
+    ec === 'AL_DB_NOT_NULL_VIOLATION' ||
+    ec === 'AL_DB_CHECK_VIOLATION' ||
+    ec === 'AL_DB_INVALID_TYPE' ||
+    ec === 'AL_MOD_TYPE_MISMATCH' ||
+    ec === 'AL_MOD_INVALID_ATTR'
+  ) {
+    return 400;
+  }
+  if (
+    ec === 'AL_DB_DEADLOCK' ||
+    ec === 'AL_DB_LOCK_WAIT_TIMEOUT' ||
+    ec === 'AL_DB_SERIALIZATION_FAILURE'
+  ) {
+    return 503;
+  }
+  if (ec === 'AL_DB_SYNTAX_ERROR' || ec === 'AL_DB_QUERY_FAILED') {
+    return 500;
+  }
+  if (err instanceof UserNotFoundError) {
+    return 404;
+  }
+  if (err instanceof UnauthorisedError) {
+    return 401;
+  }
+  if (err instanceof TooManyRequestsError) {
+    return 429;
+  }
+  if (err instanceof BadRequestError || err instanceof InvalidParameterError) {
+    return 400;
+  }
+  if (err instanceof ExpiredCodeError || err instanceof CodeMismatchError) {
+    return 400;
+  }
+  if (err instanceof UserNotConfirmedError || err instanceof PasswordResetRequiredError) {
+    return 403;
+  }
+  if (err instanceof Error && err.message) {
+    if (
+      err.message.includes('temporarily unavailable') ||
+      err.message.includes('service error') ||
+      err.message.includes('configuration error')
+    ) {
+      return 503;
+    }
+    if (err.message.includes('contact support')) {
+      return 500;
+    }
+  }
+  return 500;
+}
+
+export function logEntityRouteError(reason: unknown, agentlangCode: string): void {
+  if (reason instanceof Error) {
+    const stack = reason.stack ? `\n${reason.stack}` : '';
+    logger.error(`[${agentlangCode}] ${reason.name}: ${reason.message}${stack}`);
+  } else {
+    logger.error(`[${agentlangCode}] ${String(reason)}`);
+  }
+}

package/src/runtime/exec-graph-cache.ts

@@ -0,0 +1,12 @@
+import type { ExecGraph } from './defs.js';
+
+const graphCache = new Map<string, ExecGraph>();
+
+/** Drop cached graphs so workflow/agent structure changes after module reload are picked up. */
+export function clearExecutionGraphCache(): void {
+  graphCache.clear();
+}
+
+export function getExecutionGraphCache(): Map<string, ExecGraph> {
+  return graphCache;
+}

package/src/runtime/exec-graph.ts

@@ -56,10 +56,10 @@ import {
   makeFqName,
   nameToPath,
 } from './util.js';
-
-const GraphCache = new Map<string, ExecGraph>();
+import { getExecutionGraphCache } from './exec-graph-cache.js';
 
 export async function generateExecutionGraph(eventName: string): Promise<ExecGraph | undefined> {
+  const GraphCache = getExecutionGraphCache();
   const cg = GraphCache.get(eventName);
   if (cg) return cg;
   const wf = getWorkflowForEvent(eventName);

package/src/runtime/interpreter.ts

@@ -34,6 +34,7 @@ import {
 import {
   Agent,
   defineAgentEvent,
+  eventAgentName,
   Event,
   getOneOfRef,
   getRelationship,
@@ -127,6 +128,7 @@ import { detailedDiff } from 'deep-object-diff';
 import { callMcpTool, mcpClientNameFromToolEvent } from './mcpclient.js';
 import { isNodeEnv } from '../utils/runtime.js';
 import Handlebars from 'handlebars';
+import { createCodedError } from './errors/coded-error.js';
 
 export type Result = any;
 
@@ -445,7 +447,11 @@ export class Environment extends Instance {
 
   setActiveEvent(eventInst: Instance | undefined): Environment {
     if (eventInst) {
-      if (!isEventInstance(eventInst)) throw new Error(`Not an event instance - ${eventInst.name}`);
+      if (!isEventInstance(eventInst))
+        throw createCodedError(
+          `Not an event instance - ${eventInst.name}`,
+          'AL_INT_NOT_EVENT_INSTANCE'
+        );
       this.bindInstance(eventInst);
       this.activeModule = eventInst.moduleName;
       this.activeEventInstance = eventInst;
@@ -531,7 +537,7 @@ export class Environment extends Instance {
     if (this.suspensionId) {
       return this.suspensionId;
     } else {
-      throw new Error('SuspensionId is not set');
+      throw createCodedError('SuspensionId is not set', 'AL_INT_SUSPENSION_ID_NOT_SET');
     }
   }
 
@@ -681,7 +687,7 @@ export class Environment extends Instance {
         this.activeTransactions.set(n, txnId);
         return txnId;
       } else {
-        throw new Error(`Failed to start transaction for ${n}`);
+        throw createCodedError(`Failed to start transaction for ${n}`, 'AL_INT_TXN_START_FAILED');
       }
     }
   }
@@ -773,7 +779,7 @@ export class Environment extends Instance {
   popHandlers(): CatchHandlers {
     const r = this.activeCatchHandlers.pop();
     if (r === undefined) {
-      throw new Error(`No more handlers to pop`);
+      throw createCodedError(`No more handlers to pop`, 'AL_INT_NO_HANDLERS_TO_POP');
     }
     return r;
   }
@@ -999,7 +1005,7 @@ export let evaluate = async function (
         return null;
       }
     } else {
-      throw new Error('Not an event - ' + eventInstance.name);
+      throw createCodedError('Not an event - ' + eventInstance.name, 'AL_INT_NOT_AN_EVENT');
     }
   } catch (err) {
     if (env && env.hasHandlers()) {
@@ -1096,7 +1102,10 @@ async function evaluateAsyncPattern(
           if (s.$cstNode) {
             return s.$cstNode.text;
           } else {
-            throw new Error('failed to extract code for suspension statement');
+            throw createCodedError(
+              'failed to extract code for suspension statement',
+              'AL_INT_SUSPENSION_CODE_EXTRACT'
+            );
           }
         }),
         env
@@ -1386,7 +1395,7 @@ export async function evaluatePattern(
 
 async function evaluateThrowError(throwErr: ThrowError, env: Environment) {
   await evaluateExpression(throwErr.reason, env);
-  throw new Error(env.getLastResult());
+  throw createCodedError(String(env.getLastResult()), 'AL_INT_USER_THROW');
 }
 
 async function evaluateFullTextSearch(fts: FullTextSearch, env: Environment): Promise<void> {
@@ -1396,7 +1405,10 @@ async function evaluateFullTextSearch(fts: FullTextSearch, env: Environment): Pr
     if (inst) {
       n = makeFqName(inst.moduleName, n);
     } else {
-      throw new Error(`Fully qualified name required for full-text-search in ${n}`);
+      throw createCodedError(
+        `Fully qualified name required for full-text-search in ${n}`,
+        'AL_INT_FTS_FQN_REQUIRED'
+      );
     }
   }
   const path = nameToPath(n);
@@ -1406,7 +1418,10 @@ async function evaluateFullTextSearch(fts: FullTextSearch, env: Environment): Pr
   await evaluateLiteral(fts.query, env);
   const q = env.getLastResult();
   if (!isString(q)) {
-    throw new Error(`Full text search query must be a string - ${q}`);
+    throw createCodedError(
+      `Full text search query must be a string - ${q}`,
+      'AL_INT_FTS_QUERY_STRING'
+    );
   }
   let options: Map<string, any> | undefined;
   if (fts.options) {
@@ -1526,7 +1541,10 @@ async function patternToInstance(
         let aname: string = a.name;
         if (aname.endsWith(QuerySuffix)) {
           if (isQueryAll) {
-            throw new Error(`Cannot specifiy query attribute ${aname} here`);
+            throw createCodedError(
+              `Cannot specifiy query attribute ${aname} here`,
+              'AL_INT_QUERY_ATTR_FORBIDDEN'
+            );
           }
           if (qattrs === undefined) qattrs = newInstanceAttributes();
           if (qattrVals === undefined) qattrVals = newInstanceAttributes();
@@ -1569,11 +1587,15 @@ async function instanceFromSource(crud: CrudMap, env: Environment): Promise<Inst
       const m = nparts.hasModule() ? nparts.getModuleName() : env.getActiveModuleName();
       return makeInstance(m, n, attrs);
     } else {
-      throw new Error(`Failed to initialize instance of ${crud.name}, expected a map after @from.`);
+      throw createCodedError(
+        `Failed to initialize instance of ${crud.name}, expected a map after @from.`,
+        'AL_INT_CRUD_INIT_MAP_EXPECTED'
+      );
     }
   } else {
-    throw new Error(
-      `Cannot create instance of ${crud.name}, CRUD pattern does not specify a source map.`
+    throw createCodedError(
+      `Cannot create instance of ${crud.name}, CRUD pattern does not specify a source map.`,
+      'AL_INT_CRUD_NO_SOURCE_MAP'
     );
   }
 }
@@ -1588,7 +1610,7 @@ async function maybeValidateOneOfRefs(inst: Instance, env: Environment) {
     const attrSpec = inst.record.schema.get(n);
     if (!attrSpec) continue;
     const r = getOneOfRef(attrSpec);
-    if (!r) throw new Error(`Failed to fetch one-of-ref for ${n}`);
+    if (!r) throw createCodedError(`Failed to fetch one-of-ref for ${n}`, 'AL_INT_ONEOF_REF_FETCH');
     if (r) {
       const parts = r.split('.');
       const insts = await lookupOneOfVals(parts[0], env);
@@ -1601,7 +1623,7 @@ async function maybeValidateOneOfRefs(inst: Instance, env: Environment) {
           return i.lookup(parts[1]) == v;
         })
       ) {
-        throw new Error(`Invalid enum-value ${v} for ${n}`);
+        throw createCodedError(`Invalid enum-value ${v} for ${n}`, 'AL_INT_INVALID_ENUM');
       }
     }
   }
@@ -1655,12 +1677,16 @@ async function evaluateCrudMap(crud: CrudMap, env: Environment): Promise<void> {
   }
   if (qopts.into) {
     if (attrs.size > 0) {
-      throw new Error(
-        `Query pattern for ${entryName} with 'into' clause cannot be used to update attributes`
+      throw createCodedError(
+        `Query pattern for ${entryName} with 'into' clause cannot be used to update attributes`,
+        'AL_INT_INTO_WITH_ATTRS'
       );
     }
     if (qattrs === undefined && !isQueryAll) {
-      throw new Error(`Pattern for ${entryName} with 'into' clause must be a query`);
+      throw createCodedError(
+        `Pattern for ${entryName} with 'into' clause must be a query`,
+        'AL_INT_INTO_MUST_BE_QUERY'
+      );
     }
     if (qopts.joins && qopts.joins.length > 0) {
       await evaluateJoinQuery(qopts.joins, qopts.into, qopts.where, inst, distinct, env);
@@ -1913,7 +1939,10 @@ async function handleDocEvent(inst: Instance, env: Environment): Promise<void> {
   const url = inst.lookup('url');
   if (typeof url === 'string' && url.startsWith('s3://')) {
     if (!isNodeEnv) {
-      throw new Error('Document fetching is only available in Node.js environment');
+      throw createCodedError(
+        'Document fetching is only available in Node.js environment',
+        'AL_INT_DOC_FETCH_NODE_ONLY'
+      );
     }
     const title = inst.lookup('title');
     const retrievalConfig = inst.lookup('retrievalConfig');
@@ -2212,7 +2241,10 @@ async function walkJoinQueryPattern(
     });
     return joinsSpec;
   } else {
-    throw new Error(`Expected a query for relationship ${rp.name}`);
+    throw createCodedError(
+      `Expected a query for relationship ${rp.name}`,
+      'AL_INT_RELATIONSHIP_QUERY_EXPECTED'
+    );
   }
 }
 
@@ -2337,10 +2369,13 @@ async function agentInvoke(agent: AgentInstance, msg: string, env: Environment):
       }
     }
   } else {
-    throw new Error(`Agent ${agent.name} failed to generate a response`);
+    throw createCodedError(
+      `Agent ${agent.name} failed to generate a response`,
+      'AL_INT_AGENT_NO_RESPONSE'
+    );
   }
   if (agentInternalError !== undefined) {
-    throw new Error(agentInternalError);
+    throw createCodedError(agentInternalError, 'AL_INT_AGENT_INTERNAL');
   }
 }
 
@@ -2348,7 +2383,8 @@ export async function handleAgentInvocation(
   agentEventInst: Instance,
   env: Environment
 ): Promise<void> {
-  const agent: AgentInstance = await findAgentByName(agentEventInst.name, env);
+  const agentLookupName = eventAgentName(agentEventInst) ?? agentEventInst.name;
+  const agent: AgentInstance = await findAgentByName(agentLookupName, env);
   if (agent.role) {
     env.setAssumedRole(agent.role);
   }
@@ -2467,7 +2503,10 @@ async function iterateOnFlow(
       while (step != 'DONE' && !executedSteps.has(step)) {
         await checkCancelled(iterId);
         if (stepc > MaxFlowSteps) {
-          throw new Error(`Flow execution exceeded maximum steps limit`);
+          throw createCodedError(
+            `Flow execution exceeded maximum steps limit`,
+            'AL_INT_FLOW_MAX_STEPS'
+          );
         }
         executedSteps.add(step);
         ++stepc;
@@ -2529,7 +2568,10 @@ async function iterateOnFlow(
         ++fullFlowRetries;
         continue;
       } else {
-        throw new Error(reason);
+        throw createCodedError(
+          typeof reason === 'string' ? reason : String(reason),
+          'AL_INT_FLOW_FATAL'
+        );
       }
     } finally {
       env.decrementMonitor().revokeLastResult().setMonitorFlowResult();
@@ -2737,7 +2779,7 @@ export async function evaluateExpression(expr: Expr, env: Environment): Promise<
         });
         break;
       default:
-        throw new Error(`Unrecognized binary operator: ${expr.op}`);
+        throw createCodedError(`Unrecognized binary operator: ${expr.op}`, 'AL_INT_BAD_BINARY_OP');
     }
   } else if (isNegExpr(expr)) {
     await evaluateExpression(expr.ne, env);
@@ -2815,7 +2857,10 @@ async function followReference(env: Environment, s: string): Promise<Result> {
 async function dereferencePath(path: string, env: Environment): Promise<Result> {
   const fqName = fqNameFromPath(path);
   if (fqName === undefined) {
-    throw new Error(`Failed to deduce entry-name from path - ${path}`);
+    throw createCodedError(
+      `Failed to deduce entry-name from path - ${path}`,
+      'AL_INT_DEDUCE_ENTRY_NAME'
+    );
   }
   const newEnv = new Environment('path-deref', env);
   await parseAndEvaluateStatement(
@@ -2923,7 +2968,7 @@ async function runPrePostEvents(
       if (env.hasHandlers()) {
         throw reason;
       } else {
-        throw new Error(`${prefix}: ${reason}`);
+        throw createCodedError(`${prefix}: ${reason}`, 'AL_INT_PREPOST_EVENT_FAILED');
       }
     };
     if (trigInfo.async) {

package/src/runtime/loader.ts

@@ -80,6 +80,7 @@ import {
   asStringLiteralsMap,
   escapeSpecialChars,
   findRbacSchema,
+  isCoreModule,
   isFqName,
   makeFqName,
   maybeExtends,
@@ -105,6 +106,7 @@ import {
   parseStatement,
   parseWorkflow,
 } from '../language/parser.js';
+import { clearExecutionGraphCache } from './exec-graph-cache.js';
 import { logger } from './logger.js';
 import {
   Environment,
@@ -1305,6 +1307,9 @@ export async function internModule(
   moduleFileName?: string
 ): Promise<Module> {
   const mn = module.name;
+  if (!isCoreModule(mn)) {
+    clearExecutionGraphCache();
+  }
   const r = addModule(mn);
   // Process imports sequentially to ensure all JS modules are loaded before definitions
   for (const imp of module.imports as Import[]) {

package/src/runtime/logger.ts

@@ -17,6 +17,13 @@ if (isNodeEnv) {
 
 export let logger: any;
 
+/**
+ * Dedicated logger that records each error to `logs/errors-<DATE>.log`, one line
+ * per error. Used when custom error messages are enabled (see `recordCustomError`
+ * in errors/http-error.ts).
+ */
+export let errorFileLogger: any;
+
 function getLogLevel(): string {
   if (isNodeEnv && process.env && process.env.DEBUG) {
     return 'debug';
@@ -46,6 +53,25 @@ export function initializeLogger() {
       ),
       transports: [fileTransport],
     });
+
+    const errorFileTransport = new DailyRotateFile({
+      level: 'error',
+      filename: 'logs/errors-%DATE%.log',
+      datePattern: 'YYYY-MM-DD',
+      maxSize: '20m',
+      maxFiles: '30d',
+    });
+
+    errorFileLogger = winston.createLogger({
+      level: 'error',
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.printf(({ timestamp, message }: any) => {
+          return `[${timestamp}] ${message}`;
+        })
+      ),
+      transports: [errorFileTransport],
+    });
   } else {
     function mkLogger(tag: string): Function {
       return (msg: string) => {
@@ -58,6 +84,7 @@ export function initializeLogger() {
       warn: mkLogger('WARN'),
       error: mkLogger('ERROR'),
     };
+    errorFileLogger = { error: mkLogger('ERROR') };
   }
 }