agentlang 0.10.9 → 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/interpreter.ts

@@ -128,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;
 
@@ -446,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;
@@ -532,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');
     }
   }
 
@@ -682,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');
       }
     }
   }
@@ -774,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;
   }
@@ -1000,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()) {
@@ -1097,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
@@ -1387,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> {
@@ -1397,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);
@@ -1407,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) {
@@ -1527,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();
@@ -1570,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'
     );
   }
 }
@@ -1589,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);
@@ -1602,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');
       }
     }
   }
@@ -1656,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);
@@ -1914,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');
@@ -2213,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'
+    );
   }
 }
 
@@ -2338,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');
   }
 }
 
@@ -2469,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;
@@ -2531,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();
@@ -2739,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);
@@ -2817,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(
@@ -2925,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/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') };
   }
 }
 

package/src/runtime/module.ts

@@ -1,4 +1,5 @@
 import chalk from 'chalk';
+import { createCodedError } from './errors/coded-error.js';
 import {
   AttributeDefinition,
   Expr,
@@ -2631,7 +2632,11 @@ export class Module {
 
   getEntry(entryName: string): ModuleEntry {
     const idx: number = this.getEntryIndex(entryName);
-    if (idx < 0) throw new Error(`Entry ${entryName} not found in module ${this.name}`);
+    if (idx < 0)
+      throw createCodedError(
+        `Entry ${entryName} not found in module ${this.name}`,
+        'AL_MOD_ENTRY_NOT_FOUND'
+      );
     return this.entries[idx];
   }
 
@@ -2646,7 +2651,10 @@ export class Module {
     if (e instanceof Record) {
       return e as Record;
     }
-    throw new Error(`${recordName} is not a record in module ${this.name}`);
+    throw createCodedError(
+      `${recordName} is not a record in module ${this.name}`,
+      'AL_MOD_NOT_A_RECORD'
+    );
   }
 
   removeEntry(entryName: string): boolean {
@@ -2942,7 +2950,7 @@ export function isModule(name: string): boolean {
 export function fetchModule(moduleName: string): Module {
   const module: Module | undefined = getModuleDb().get(moduleName);
   if (module === undefined) {
-    throw new Error(`Module not found - ${moduleName}`);
+    throw createCodedError(`Module not found - ${moduleName}`, 'AL_MOD_MODULE_NOT_FOUND');
   }
   return module;
 }
@@ -3481,7 +3489,7 @@ export function getEntity(name: string, moduleName: string): Entity | undefined
 export function fetchEntity(path: Path): Entity {
   const e = getEntity(path.getEntryName(), path.getModuleName());
   if (e === undefined) {
-    throw new Error(`Entity not found - ${path.asFqName()}`);
+    throw createCodedError(`Entity not found - ${path.asFqName()}`, 'AL_MOD_ENTITY_NOT_FOUND');
   }
   return e;
 }
@@ -3513,7 +3521,10 @@ export function getEvent(name: string, moduleName: string): Event {
   if (fr.module.isEvent(fr.entryName)) {
     return fr.module.getEntry(fr.entryName) as Event;
   }
-  throw new Error(`Event ${fr.entryName} not found in module ${fr.moduleName}`);
+  throw createCodedError(
+    `Event ${fr.entryName} not found in module ${fr.moduleName}`,
+    'AL_MOD_EVENT_NOT_FOUND'
+  );
 }
 
 export function maybeGetEvent(name: string, moduleName: string): Event | undefined {
@@ -3529,7 +3540,10 @@ export function getRecord(name: string, moduleName: string): Record {
   if (fr.module.isRecord(fr.entryName)) {
     return fr.module.getEntry(fr.entryName) as Record;
   }
-  throw new Error(`Record ${fr.entryName} not found in module ${fr.moduleName}`);
+  throw createCodedError(
+    `Record ${fr.entryName} not found in module ${fr.moduleName}`,
+    'AL_MOD_RECORD_NOT_FOUND'
+  );
 }
 
 export function getRelationship(name: string, moduleName: string): Relationship {
@@ -3537,7 +3551,10 @@ export function getRelationship(name: string, moduleName: string): Relationship
   if (fr.module.isRelationship(fr.entryName)) {
     return fr.module.getEntry(fr.entryName) as Relationship;
   }
-  throw new Error(`Relationship ${fr.entryName} not found in module ${fr.moduleName}`);
+  throw createCodedError(
+    `Relationship ${fr.entryName} not found in module ${fr.moduleName}`,
+    'AL_MOD_RELATIONSHIP_NOT_FOUND'
+  );
 }
 
 export function getAllBetweenRelationships(): Relationship[] {
@@ -3707,7 +3724,10 @@ function checkOneOfValue(attrSpec: AttributeSpec, attrName: string, attrValue: a
   const vals: Set<string> | undefined = getEnumValues(attrSpec);
   if (vals) {
     if (!vals.has(attrValue as string)) {
-      throw new Error(`Value of ${attrName} must be one of [${[...vals]}]`);
+      throw createCodedError(
+        `Value of ${attrName} must be one of [${[...vals]}]`,
+        'AL_MOD_TYPE_MISMATCH'
+      );
     }
     return true;
   }
@@ -3725,7 +3745,10 @@ function getCheckPredicate(attrSpec: AttributeSpec): any {
 function validateType(attrName: string, attrValue: any, attrSpec: AttributeSpec) {
   if (attrSpec.type == 'Path') {
     if (!isPath(attrValue, getRefSpec(attrSpec))) {
-      throw new Error(`Failed to validate Path ${attrValue} passed to ${attrName}`);
+      throw createCodedError(
+        `Failed to validate Path ${attrValue} passed to ${attrName}`,
+        'AL_MOD_TYPE_MISMATCH'
+      );
     }
   }
   let predic = getCheckPredicate(attrSpec);
@@ -3733,16 +3756,22 @@ function validateType(attrName: string, attrValue: any, attrSpec: AttributeSpec)
   if (predic !== undefined) {
     if (isArrayAttribute(attrSpec)) {
       if (!(attrValue instanceof Array)) {
-        throw new Error(`${attrName} expects an array of values`);
+        throw createCodedError(`${attrName} expects an array of values`, 'AL_MOD_TYPE_MISMATCH');
       } else {
         if (!attrValue.every(predic)) {
-          throw new Error(`Invalid value in the array passed to ${attrName}`);
+          throw createCodedError(
+            `Invalid value in the array passed to ${attrName}`,
+            'AL_MOD_TYPE_MISMATCH'
+          );
         }
       }
     } else {
       if (!checkOneOfValue(attrSpec, attrName, attrValue)) {
         if (!predic(attrValue)) {
-          throw new Error(`Invalid value ${attrValue} specified for ${attrName}`);
+          throw createCodedError(
+            `Invalid value ${attrValue} specified for ${attrName}`,
+            'AL_MOD_TYPE_MISMATCH'
+          );
         }
       }
     }
@@ -4307,7 +4336,10 @@ export function makeInstance(
   if (schema.size > 0) {
     attributes.forEach((value: any, key: string) => {
       if (!schema.has(key)) {
-        throw new Error(`Invalid attribute '${key}' specified for ${moduleName}/${entryName}`);
+        throw createCodedError(
+          `Invalid attribute '${key}' specified for ${moduleName}/${entryName}`,
+          'AL_MOD_INVALID_ATTR'
+        );
       }
       const spec: AttributeSpec = getAttributeSpec(schema, key);
       if (value !== null && value !== undefined) validateType(key, value, spec);

package/src/runtime/modules/ai.ts

@@ -85,6 +85,7 @@ const AgentEvalType = 'eval';
 // --- Agent cancellation infrastructure ---
 
 export class AgentCancelledException extends Error {
+  readonly agentlangCode = 'AL_AGENT_CANCELLED';
   constructor(chatId: string) {
     super(`Agent cancelled for chatId: ${chatId}`);
     this.name = 'AgentCancelledException';