agentlang 0.0.18 → 0.0.20

package/src/language/parser.ts

@@ -103,16 +103,37 @@ export async function parseWorkflow(workflowDef: string): Promise<WorkflowDefini
   }
 }
 
+export function maybeGetValidationErrors(document: LangiumDocument): string[] | undefined {
+  const validationErrors = (document.diagnostics ?? []).filter(e => e.severity === 1);
+
+  const sls = new Set<number>();
+  const scs = new Set<number>();
+  if (validationErrors.length > 0) {
+    const lineErrs = new Array<string>();
+    for (const validationError of validationErrors) {
+      if (
+        !sls.has(validationError.range.start.line) &&
+        !scs.has(validationError.range.start.character)
+      ) {
+        const s = document.textDocument.getText(validationError.range);
+        lineErrs.push(
+          `Error on line ${validationError.range.start.line + 1}, column ${validationError.range.start.character + 1}, unexpected token(s) '${s}'`
+        );
+        sls.add(validationError.range.start.line);
+        scs.add(validationError.range.start.character);
+      }
+    }
+
+    return lineErrs;
+  } else {
+    return undefined;
+  }
+}
+
 function maybeRaiseParserErrors(document: LangiumDocument) {
-  if (document.parseResult.lexerErrors.length > 0 || document.parseResult.parserErrors.length > 0) {
-    const errs: Array<string> = [];
-    document.parseResult.lexerErrors.forEach((v: any) => {
-      errs.push(v.message);
-    });
-    document.parseResult.parserErrors.forEach((v: any) => {
-      errs.push(v.message);
-    });
-    throw new Error(`There were parser errors: \n ${errs.join('\n')}`);
+  const errs = maybeGetValidationErrors(document);
+  if (errs) {
+    throw new Error(errs.join('\n'));
   }
 }
 

package/src/runtime/agents/common.ts

@@ -145,9 +145,12 @@ are invalid, because the alias 'employee' is not defined:
 
 A fix for the reference-error is shown below:
 
-{Employee {id? 101}} @as employee;
+{Employee {id? 101}} @as [employee];
 {SendEmail {to employee.email, body "hello"}}
 
+Note that the alias for the query is '[employee]' so that the resultset is destructured to select exactly one instance of Employee 
+selected into the reference. You must follow this pattern if your goal is to select exactly a single instance.
+
 Keep in mind that the only valid syntax for the 'if' condition is:
 
 if (<expr>) {

package/src/runtime/agents/impl/anthropic.ts

@@ -12,8 +12,64 @@ export interface AnthropicConfig {
     defaultHeaders?: Record<string, string>;
     [key: string]: any;
   };
+
+  /**
+   * Enable prompt caching to reuse context across API calls.
+   * This reduces latency and costs by caching static portions of prompts.
+   * Cache has a 5-minute lifetime by default, refreshed on each use.
+   * Minimum cacheable length: 1024 tokens for Claude 3.5+, 2048 for Haiku.
+   * Beta header: prompt-caching-2024-07-31
+   * @see https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+   */
   enablePromptCaching?: boolean;
+
+  /**
+   * Cache control type for prompt caching.
+   * Currently only 'ephemeral' is supported with 5-minute TTL.
+   * Can be extended to 1-hour with extended-cache-ttl-2025-04-11 beta.
+   */
   cacheControl?: 'ephemeral';
+
+  /**
+   * Enable extended thinking mode for Claude to show its reasoning process.
+   * When enabled, responses include thinking blocks showing Claude's thought process.
+   * Requires minimum budgetTokens of 1024 and counts towards maxTokens.
+   * Useful for complex reasoning, problem-solving, and transparency.
+   * @see https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
+   */
+  enableThinking?: boolean;
+
+  /**
+   * Token budget for thinking mode (minimum 1024).
+   * Determines how many tokens Claude can use for internal reasoning.
+   * Larger budgets enable more thorough analysis for complex problems.
+   * Must be less than maxTokens.
+   */
+  budgetTokens?: number;
+
+  /**
+   * Enable extended output to generate up to 128,000 tokens in a single response.
+   * Useful for long-form content, detailed reports, extensive code generation.
+   * Beta header: output-128k-2025-02-19
+   * Note: Use streaming to avoid timeouts with long outputs.
+   */
+  enableExtendedOutput?: boolean;
+
+  /**
+   * Enable interleaved thinking to see Claude's reasoning in real-time during streaming.
+   * When combined with extended thinking, thinking blocks are streamed alongside content.
+   * Provides transparency into Claude's problem-solving process as it happens.
+   * Beta header: interleaved-thinking-2025-05-14
+   */
+  enableInterleavedThinking?: boolean;
+
+  /**
+   * Enable fine-grained tool streaming for more responsive tool use.
+   * Streams partial JSON updates and character-by-character tool parameters.
+   * Improves UI responsiveness when Claude invokes tools.
+   * Beta header: fine-grained-tool-streaming-2025-05-14
+   */
+  enableFineGrainedToolStreaming?: boolean;
 }
 
 export class AnthropicProvider implements AgentServiceProvider {
@@ -38,16 +94,58 @@ export class AnthropicProvider implements AgentServiceProvider {
       chatConfig.clientOptions = this.config.clientOptions;
     }
 
+    // Configure beta headers based on enabled features
+    const betaFeatures: string[] = [];
+
+    // Prompt caching: Reuse static content across API calls
+    // Reduces costs by 90% for cached content, improves latency
     if (this.config.enablePromptCaching) {
+      betaFeatures.push('prompt-caching-2024-07-31');
+    }
+
+    // Extended output: Generate up to 128k tokens (vs standard 8k)
+    // Essential for long-form content generation
+    if (this.config.enableExtendedOutput) {
+      betaFeatures.push('output-128k-2025-02-19');
+    }
+
+    // Interleaved thinking: Stream thinking blocks alongside regular content
+    // Shows Claude's reasoning process in real-time during streaming
+    if (this.config.enableInterleavedThinking) {
+      betaFeatures.push('interleaved-thinking-2025-05-14');
+    }
+
+    // Fine-grained tool streaming: Stream partial tool parameters
+    // Provides character-by-character updates for better UX
+    if (this.config.enableFineGrainedToolStreaming) {
+      betaFeatures.push('fine-grained-tool-streaming-2025-05-14');
+    }
+
+    if (betaFeatures.length > 0) {
       chatConfig.clientOptions = {
         ...chatConfig.clientOptions,
         defaultHeaders: {
           ...chatConfig.clientOptions?.defaultHeaders,
-          'anthropic-beta': 'prompt-caching-2024-07-31',
+          'anthropic-beta': betaFeatures.join(','),
         },
       };
     }
 
+    // Validate thinking configuration if enabled
+    // Thinking mode requires careful token budget management
+    if (this.config.enableThinking) {
+      // Validate budget tokens (minimum 1024 required by API)
+      const budgetTokens = Math.max(1024, this.config.budgetTokens || 1024);
+
+      // Ensure budget tokens don't exceed max tokens
+      // This prevents API errors and ensures proper token allocation
+      if (budgetTokens >= (this.config.maxTokens || 8192)) {
+        throw new Error(
+          `budgetTokens (${budgetTokens}) must be less than maxTokens (${this.config.maxTokens || 8192})`
+        );
+      }
+    }
+
     this.model = new ChatAnthropic(chatConfig);
   }
 
@@ -59,6 +157,11 @@ export class AnthropicProvider implements AgentServiceProvider {
       maxRetries: 2,
       enablePromptCaching: false,
       cacheControl: 'ephemeral',
+      enableThinking: false,
+      budgetTokens: 1024, // Minimum budget tokens for thinking mode
+      enableExtendedOutput: false,
+      enableInterleavedThinking: false,
+      enableFineGrainedToolStreaming: false,
     };
 
     if (!config) {
@@ -81,6 +184,31 @@ export class AnthropicProvider implements AgentServiceProvider {
         defaultConfig.enablePromptCaching,
       cacheControl:
         config.get('cacheControl') || config.get('cache_control') || defaultConfig.cacheControl,
+      enableThinking:
+        config.get('enableThinking') ||
+        config.get('enable_thinking') ||
+        config.get('thinking') ||
+        defaultConfig.enableThinking,
+      budgetTokens:
+        config.get('budgetTokens') ||
+        config.get('budget_tokens') ||
+        config.get('thinking_budget') ||
+        defaultConfig.budgetTokens,
+      enableExtendedOutput:
+        config.get('enableExtendedOutput') ||
+        config.get('enable_extended_output') ||
+        config.get('extendedOutput') ||
+        defaultConfig.enableExtendedOutput,
+      enableInterleavedThinking:
+        config.get('enableInterleavedThinking') ||
+        config.get('enable_interleaved_thinking') ||
+        config.get('interleavedThinking') ||
+        defaultConfig.enableInterleavedThinking,
+      enableFineGrainedToolStreaming:
+        config.get('enableFineGrainedToolStreaming') ||
+        config.get('enable_fine_grained_tool_streaming') ||
+        config.get('fineGrainedToolStreaming') ||
+        defaultConfig.enableFineGrainedToolStreaming,
       apiKey,
       clientOptions: config.get('clientOptions') || config.get('client_options'),
     };
@@ -99,9 +227,25 @@ export class AnthropicProvider implements AgentServiceProvider {
       processedMessages = this.applyCacheControl(messages);
     }
 
-    return asAIResponse(await this.model.invoke(processedMessages));
+    // Add thinking configuration to the invoke options if enabled
+    // Thinking mode is passed as a parameter during invocation, not in constructor
+    const invokeOptions: any = {};
+    if (this.config.enableThinking) {
+      const budgetTokens = Math.max(1024, this.config.budgetTokens || 1024);
+      invokeOptions.thinking = {
+        type: 'enabled',
+        budget_tokens: budgetTokens,
+      };
+    }
+
+    return asAIResponse(await this.model.invoke(processedMessages, invokeOptions));
   }
 
+  /**
+   * Apply cache control to messages for prompt caching optimization.
+   * Caches system messages with substantial content (>1000 chars) to reduce costs.
+   * Cache hits cost 90% less than regular input tokens.
+   */
   private applyCacheControl(messages: BaseMessage[]): BaseMessage[] {
     // Apply cache control to the last system message if present
     // This follows Anthropic's recommendation to cache long context at the end of system messages
@@ -112,7 +256,7 @@ export class AnthropicProvider implements AgentServiceProvider {
     // Find the last system message and apply cache control
     for (let i = processedMessages.length - 1; i >= 0; i--) {
       const message = processedMessages[i];
-      if (message._getType() === 'system') {
+      if ((message as any)._getType() === 'system') {
         // Apply cache control to system message content
         const content = message.content;
         if (typeof content === 'string' && content.length > 1000) {
@@ -151,16 +295,58 @@ export class AnthropicProvider implements AgentServiceProvider {
       chatConfig.clientOptions = this.config.clientOptions;
     }
 
+    // Configure beta headers based on enabled features
+    const betaFeatures: string[] = [];
+
+    // Prompt caching: Reuse static content across API calls
+    // Reduces costs by 90% for cached content, improves latency
     if (this.config.enablePromptCaching) {
+      betaFeatures.push('prompt-caching-2024-07-31');
+    }
+
+    // Extended output: Generate up to 128k tokens (vs standard 8k)
+    // Essential for long-form content generation
+    if (this.config.enableExtendedOutput) {
+      betaFeatures.push('output-128k-2025-02-19');
+    }
+
+    // Interleaved thinking: Stream thinking blocks alongside regular content
+    // Shows Claude's reasoning process in real-time during streaming
+    if (this.config.enableInterleavedThinking) {
+      betaFeatures.push('interleaved-thinking-2025-05-14');
+    }
+
+    // Fine-grained tool streaming: Stream partial tool parameters
+    // Provides character-by-character updates for better UX
+    if (this.config.enableFineGrainedToolStreaming) {
+      betaFeatures.push('fine-grained-tool-streaming-2025-05-14');
+    }
+
+    if (betaFeatures.length > 0) {
       chatConfig.clientOptions = {
         ...chatConfig.clientOptions,
         defaultHeaders: {
           ...chatConfig.clientOptions?.defaultHeaders,
-          'anthropic-beta': 'prompt-caching-2024-07-31',
+          'anthropic-beta': betaFeatures.join(','),
         },
       };
     }
 
+    // Validate thinking configuration if enabled
+    // Thinking mode requires careful token budget management
+    if (this.config.enableThinking) {
+      // Validate budget tokens (minimum 1024 required by API)
+      const budgetTokens = Math.max(1024, this.config.budgetTokens || 1024);
+
+      // Ensure budget tokens don't exceed max tokens
+      // This prevents API errors and ensures proper token allocation
+      if (budgetTokens >= (this.config.maxTokens || 8192)) {
+        throw new Error(
+          `budgetTokens (${budgetTokens}) must be less than maxTokens (${this.config.maxTokens || 8192})`
+        );
+      }
+    }
+
     this.model = new ChatAnthropic(chatConfig);
   }
 }

package/src/runtime/auth/cognito.ts

@@ -400,7 +400,7 @@ export class CognitoAuth implements AgentlangAuth {
     }
   }
 
-  async confirmSignup(username: string, confirmationCode: string, env: Environment): Promise<void> {
+  async confirmSignup(username: string, confirmationCode: string, _: Environment): Promise<void> {
     try {
       const client = new CognitoIdentityProviderClient({
         region: process.env.AWS_REGION || 'us-west-2',

package/src/runtime/defs.ts

@@ -76,3 +76,15 @@ export class CodeMismatchError extends Error {
     super(message || 'The verification code is incorrect. Please try again.', options);
   }
 }
+
+export let FetchModuleFn: any = undefined;
+
+export function setModuleFnFetcher(f: Function) {
+  FetchModuleFn = f;
+}
+
+export let SetSubscription: any = undefined;
+
+export function setSubscriptionFn(f: Function) {
+  SetSubscription = f;
+}

package/src/runtime/interpreter.ts

@@ -54,6 +54,7 @@ import {
   DefaultModuleName,
   escapeFqName,
   escapeQueryName,
+  escapeSpecialChars,
   fqNameFromPath,
   isFqName,
   isPath,
@@ -80,6 +81,7 @@ import {
   setTimerRunning,
 } from './modules/core.js';
 import { invokeModuleFn } from './jsmodules.js';
+import { invokeOpenApiEvent, isOpenApiEventInstance } from './openapi.js';
 
 export type Result = any;
 
@@ -545,6 +547,15 @@ export async function evaluate(
         }
         await evaluateStatements(wf.statements, env, continuation);
         return env.getLastResult();
+      } else if (isOpenApiEventInstance(eventInstance)) {
+        env = new Environment(eventInstance.name + '.env', activeEnv);
+        await handleOpenApiEvent(eventInstance, env);
+        const r = env.getLastResult();
+        if (continuation) continuation(r);
+        return r;
+      } else {
+        if (continuation) continuation(null);
+        return null;
       }
     } else {
       throw new Error('Not an event - ' + eventInstance.name);
@@ -1180,6 +1191,7 @@ async function evaluateCrudMap(crud: CrudMap, env: Environment): Promise<void> {
     }
   } else if (isEventInstance(inst)) {
     if (isAgentEventInstance(inst)) await handleAgentInvocation(inst, env);
+    else if (isOpenApiEventInstance(inst)) await handleOpenApiEvent(inst, env);
     else await evaluate(inst, (result: Result) => env.setLastResult(result), env);
   } else {
     env.setLastResult(inst);
@@ -1299,46 +1311,88 @@ 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);
   await agent.invoke(agentEventInst.lookup('message'), env);
   const r: string | undefined = env.getLastResult();
   const isPlanner = agent.isPlanner();
-  const result: string | undefined = isPlanner ? cleanupAgentResponse(r) : r;
+  let result: string | undefined = isPlanner ? cleanupAgentResponse(r) : r;
   if (result) {
     if (isPlanner) {
-      logger.debug(`Agent ${agent.name} generated pattern: ${result}`);
-      try {
-        let rs = result.trim();
-        let isWf = rs.startsWith('workflow');
-        const isGrp = rs.startsWith('[');
-        if (!isWf && !isGrp && rs.indexOf(';') > 0) {
-          rs = `workflow T {${rs}}`;
-          isWf = true;
-        } else if (!isWf && isGrp) {
-          const stmts = rs.substring(1, rs.length - 1);
-          rs = `workflow T {${stmts}}`;
-          isWf = true;
-        }
-        if (isWf) {
-          const wf = await parseWorkflow(rs);
-          if (agent.runWorkflows) {
+      let retries = 0;
+      while (true) {
+        logger.debug(`Agent ${agent.name} generated pattern: ${result}`);
+        try {
+          let rs: string = result ? result.trim() : '';
+          let isWf = rs.startsWith('workflow');
+          if (isWf && !agent.runWorkflows) {
+            await parseWorkflow(rs);
+            return;
+          }
+          const isGrp = rs.startsWith('[');
+          if (!isWf && !isGrp && rs.indexOf(';') > 0) {
+            rs = `workflow T {${rs}}`;
+            isWf = true;
+          } else if (!isWf && isGrp) {
+            const stmts = rs.substring(1, rs.length - 1);
+            rs = `workflow T {${stmts}}`;
+            isWf = true;
+          }
+          if (isWf) {
+            const wf = await parseWorkflow(rs);
             await evaluateStatements(wf.statements, env);
+          } else {
+            env.setLastResult(await parseAndEvaluateStatement(rs, undefined, env));
+          }
+          break;
+        } catch (err: any) {
+          if (retries < MAX_PLANNER_RETRIES) {
+            await agent.invoke(`Please fix these errors:\n ${err}`, env);
+            const r: string | undefined = env.getLastResult();
+            result = cleanupAgentResponse(r);
+            ++retries;
+          } else {
+            logger.error(
+              `Failed to evaluate pattern generated by agent ${agent.name} - ${result}, ${err}`
+            );
+            break;
           }
-        } else {
-          env.setLastResult(await parseAndEvaluateStatement(rs, undefined, env));
         }
-      } catch (err: any) {
-        logger.error(
-          `Failed to evaluate pattern generated by agent ${agent.name} - ${result}, ${err}`
-        );
       }
     }
+    if (agent.output) {
+      await pushToAgent(agent.output, env.getLastResult(), env);
+    }
   } else {
     logger.warn(`Agent ${agent.name} failed to generate a response`);
   }
 }
 
+function agentInputAsString(result: any): string {
+  if (!isString(result)) {
+    if (result instanceof Instance) {
+      return JSON.stringify((result as Instance).asObject());
+    } else if (result instanceof Array) {
+      return `[${(result as Array<any>)
+        .map((r: any) => {
+          return agentInputAsString(r);
+        })
+        .join(',')}]`;
+    } else {
+      return JSON.stringify(result);
+    }
+  }
+  return result;
+}
+
+async function pushToAgent(agentName: string, result: any, env: Environment) {
+  const r = escapeSpecialChars(agentInputAsString(result));
+  const pat = `{${agentName} {message "\n${r}"}}`;
+  env.setLastResult(await parseAndEvaluateStatement(pat, undefined, env));
+}
+
 function cleanupAgentResponse(response: string | undefined): string | undefined {
   if (response) {
     const resp = response.trim();
@@ -1371,6 +1425,15 @@ function cleanupAgentResponse(response: string | undefined): string | undefined
   }
 }
 
+async function handleOpenApiEvent(eventInst: Instance, env: Environment): Promise<void> {
+  const r = await invokeOpenApiEvent(
+    eventInst.moduleName,
+    eventInst.name,
+    eventInst.attributesAsObject()
+  );
+  env.setLastResult(r);
+}
+
 async function evaluateUpsert(crud: CrudMap, env: Environment): Promise<void> {
   env.setInUpsertMode(true);
   try {
@@ -1634,7 +1697,7 @@ async function runPrePostEvents(
       if (env.hasHandlers()) {
         throw reason;
       } else {
-        logger.error(`${prefix}: ${reason}`);
+        throw new Error(`${prefix}: ${reason}`);
       }
     };
     if (trigInfo.async) {

package/src/runtime/jsmodules.ts

@@ -1,7 +1,7 @@
 import { logger } from './logger.js';
-import { setSubscription } from './resolvers/registry.js';
 import { now, splitRefs } from './util.js';
 import { isNodeEnv } from '../utils/runtime.js';
+import { setModuleFnFetcher } from './defs.js';
 
 let dirname: any = undefined;
 let sep: any = undefined;
@@ -26,39 +26,37 @@ const importedModules = new Map<string, any>();
 
 // Usage: importModule("./mymodels/acme.js")
 export async function importModule(path: string, name: string, moduleFileName?: string) {
-  if (importedModules.has(name)) {
-    logger.warn(`Alias '${name}' will overwrite a previously imported module`);
-  }
-  if (moduleFileName) {
-    let s: string = dirname(moduleFileName);
-    if (s.startsWith('./')) {
-      s = s.substring(2);
+  if (isNodeEnv) {
+    if (importedModules.has(name)) {
+      logger.warn(`Alias '${name}' will overwrite a previously imported module`);
     }
-    path = `${s}${sep}${path}`;
-  }
-  if ((path.startsWith(sep) || path.startsWith('.')) && moduleFileName) {
-    path = process.cwd() + sep + path;
+    if (moduleFileName) {
+      let s: string = dirname(moduleFileName);
+      if (s.startsWith('./')) {
+        s = s.substring(2);
+      } else if (s == '.') {
+        s = process.cwd();
+      }
+      path = `${s}${sep}${path}`;
+    }
+    if (!(path.startsWith(sep) || path.startsWith('.'))) {
+      path = process.cwd() + sep + path;
+    }
+    const m = await import(/* @vite-ignore */ path);
+    importedModules.set(name, m);
+    // e.g of dynamic fn-call:
+    //// let f = eval("(a, b) => m.add(a, b)");
+    //// console.log(f(10, 20))
+    return m;
+  } else {
+    return {};
   }
-  const m = await import(/* @vite-ignore */ path);
-  importedModules.set(name, m);
-  // e.g of dynamic fn-call:
-  //// let f = eval("(a, b) => m.add(a, b)");
-  //// console.log(f(10, 20))
-  return m;
 }
 
 export function moduleImported(moduleName: string): boolean {
   return importedModules.has(moduleName);
 }
 
-const ReservedImports = new Set<string>(['resolvers']);
-
-export function validateImportName(n: string) {
-  if (ReservedImports.has(n)) {
-    throw new Error(`${n} is an import reserved by the runtime`);
-  }
-}
-
 function maybeEvalFunction(fnName: string): Function | undefined {
   try {
     return eval(fnName);
@@ -68,14 +66,6 @@ function maybeEvalFunction(fnName: string): Function | undefined {
   }
 }
 
-function invokeReservedFn(moduleName: string, fnName: string, args: Array<any> | null) {
-  if (moduleName == 'resolvers' && fnName == 'setSubscription' && args != null) {
-    return setSubscription(args[0], args[1]);
-  } else {
-    throw new Error(`Failed to call ${moduleName}.${fnName} with the given arguments`);
-  }
-}
-
 async function invokeBuiltInFn(fnName: string, args: Array<any> | null, isAsync: boolean = false) {
   if (fnName == 'now') {
     return now();
@@ -112,9 +102,6 @@ export async function invokeModuleFn(
       }
     }
     const mname = refs[0];
-    if (ReservedImports.has(mname)) {
-      return invokeReservedFn(mname, refs[1], args);
-    }
     const m = importedModules.get(mname);
     if (m != undefined) {
       const f = m[refs[1]];
@@ -151,3 +138,5 @@ export function getModuleFn(fqFnName: string): Function | undefined {
     return m[refs[1]];
   } else return undefined;
 }
+
+setModuleFnFetcher(getModuleFn);