llmz 0.0.13 → 0.0.15

package/dist/{llmz-QLZBDG2Z.cjs → llmz-WVNKAMCP.cjs}

@@ -7,10 +7,10 @@ var _chunkBEPRLBPKcjs = require('./chunk-BEPRLBPK.cjs');
 
 
 
-var _chunkHJKOSEH2cjs = require('./chunk-HJKOSEH2.cjs');
-require('./chunk-SHJDRZF5.cjs');
-require('./chunk-C6WNNTEV.cjs');
-require('./chunk-4L6D2A6O.cjs');
+var _chunkTCRRSS44cjs = require('./chunk-TCRRSS44.cjs');
+require('./chunk-PIDLNYIP.cjs');
+require('./chunk-XGJOEQMW.cjs');
+require('./chunk-FZJHYLM2.cjs');
 
 
 
@@ -24,16 +24,16 @@ var _chunkJDABP4SDcjs = require('./chunk-JDABP4SD.cjs');
 
 
 var _chunkIKSIOIIPcjs = require('./chunk-IKSIOIIP.cjs');
-require('./chunk-GWFYZDUR.cjs');
+require('./chunk-3G3BS5IA.cjs');
 require('./chunk-ZRCU35UV.cjs');
 require('./chunk-KMZDFWYZ.cjs');
 
 
-var _chunkJGVAZO4Xcjs = require('./chunk-JGVAZO4X.cjs');
+var _chunkGZPN7RGHcjs = require('./chunk-GZPN7RGH.cjs');
 
 
 
-var _chunk276Q6EWPcjs = require('./chunk-276Q6EWP.cjs');
+var _chunkWHNOR4ZUcjs = require('./chunk-WHNOR4ZU.cjs');
 
 
 
@@ -46,6 +46,37 @@ var _cognitive = require('@botpress/cognitive');
 var _zui = require('@bpinternal/zui');
 var _ms = require('ms'); var _ms2 = _interopRequireDefault(_ms);
 var _ulid = require('ulid');
+
+// src/abort-signal.ts
+function createJoinedAbortController(signals) {
+  const controller = new AbortController();
+  const validSignals = signals.filter((signal) => signal != null);
+  if (validSignals.length === 0) {
+    return controller;
+  }
+  for (const signal of validSignals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      return controller;
+    }
+  }
+  const abortListeners = [];
+  for (const signal of validSignals) {
+    const listener = () => {
+      controller.abort(signal.reason);
+      cleanup();
+    };
+    signal.addEventListener("abort", listener);
+    abortListeners.push(() => signal.removeEventListener("abort", listener));
+  }
+  const cleanup = () => {
+    abortListeners.forEach((removeListener) => removeListener());
+  };
+  controller.signal.addEventListener("abort", cleanup, { once: true });
+  return controller;
+}
+
+// src/llmz.ts
 var getErrorMessage = (err) => err instanceof Error ? err.message : JSON.stringify(err);
 var SLOW_TOOL_WARNING = _ms2.default.call(void 0, "15s");
 var RESPONSE_LENGTH_BUFFER = {
@@ -60,7 +91,7 @@ var getModelOutputLimit = (inputLength) => _chunkUQOBUJIQcjs.clamp_default.call(
 );
 var executeContext = async (props) => {
   var _a, _b;
-  await _chunk276Q6EWPcjs.init.call(void 0, );
+  await _chunkWHNOR4ZUcjs.init.call(void 0, );
   const result = await _executeContext(props);
   try {
     (_b = (_a = result.context.chat) == null ? void 0 : _a.onExecutionDone) == null ? void 0 : _b.call(_a, result);
@@ -70,10 +101,11 @@ var executeContext = async (props) => {
 };
 var _executeContext = async (props) => {
   var _a, _b, _c, _d;
-  const { signal, onIterationEnd, onTrace, onExit, onBeforeExecution } = props;
+  const controller = createJoinedAbortController([props.signal]);
+  const { onIterationEnd, onTrace, onExit, onBeforeExecution, onAfterTool, onBeforeTool } = props;
   const cognitive = _cognitive.Cognitive.isCognitiveClient(props.client) ? props.client : new (0, _cognitive.Cognitive)({ client: props.client });
   const cleanups = [];
-  const ctx = new (0, _chunkHJKOSEH2cjs.Context)({
+  const ctx = new (0, _chunkTCRRSS44cjs.Context)({
     chat: props.chat,
     instructions: props.instructions,
     objects: props.objects,
@@ -88,17 +120,17 @@ var _executeContext = async (props) => {
   try {
     while (true) {
       if (ctx.iterations.length >= ctx.loop) {
-        return new (0, _chunkHJKOSEH2cjs.ErrorExecutionResult)(ctx, new (0, _chunkJDABP4SDcjs.LoopExceededError)());
+        return new (0, _chunkTCRRSS44cjs.ErrorExecutionResult)(ctx, new (0, _chunkJDABP4SDcjs.LoopExceededError)());
       }
       const iteration = await ctx.nextIteration();
-      if (signal == null ? void 0 : signal.aborted) {
+      if (controller.signal.aborted) {
         iteration.end({
           type: "aborted",
           aborted: {
-            reason: _nullishCoalesce(signal.reason, () => ( "The operation was aborted"))
+            reason: _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted"))
           }
         });
-        return new (0, _chunkHJKOSEH2cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(signal.reason, () => ( "The operation was aborted")));
+        return new (0, _chunkTCRRSS44cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted")));
       }
       cleanups.push(
         iteration.traces.onPush((traces) => {
@@ -112,9 +144,11 @@ var _executeContext = async (props) => {
           iteration,
           ctx,
           cognitive,
-          abortSignal: signal,
+          controller,
           onExit,
-          onBeforeExecution
+          onBeforeExecution,
+          onAfterTool,
+          onBeforeTool
         });
       } catch (err) {
         iteration.end({
@@ -126,31 +160,31 @@ var _executeContext = async (props) => {
         });
       }
       try {
-        await (onIterationEnd == null ? void 0 : onIterationEnd(iteration));
+        await (onIterationEnd == null ? void 0 : onIterationEnd(iteration, controller));
       } catch (err) {
         console.error(err);
       }
       if (iteration.status.type === "exit_success") {
         const exitName = iteration.status.exit_success.exit_name;
-        return new (0, _chunkHJKOSEH2cjs.SuccessExecutionResult)(ctx, {
+        return new (0, _chunkTCRRSS44cjs.SuccessExecutionResult)(ctx, {
           exit: iteration.exits.find((x) => x.name === exitName),
           result: iteration.status.exit_success.return_value
         });
       }
       if (iteration.status.type === "callback_requested") {
-        return new (0, _chunkHJKOSEH2cjs.PartialExecutionResult)(
+        return new (0, _chunkTCRRSS44cjs.PartialExecutionResult)(
           ctx,
           iteration.status.callback_requested.signal,
-          _chunkHJKOSEH2cjs.Snapshot.fromSignal(iteration.status.callback_requested.signal)
+          _chunkTCRRSS44cjs.Snapshot.fromSignal(iteration.status.callback_requested.signal)
         );
       }
       if (iteration.status.type === "thinking_requested" || iteration.status.type === "exit_error" || iteration.status.type === "execution_error" || iteration.status.type === "invalid_code_error") {
         continue;
       }
-      return new (0, _chunkHJKOSEH2cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(iteration.error, () => ( `Unknown error. Status: ${iteration.status.type}`)));
+      return new (0, _chunkTCRRSS44cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(iteration.error, () => ( `Unknown error. Status: ${iteration.status.type}`)));
     }
   } catch (error) {
-    return new (0, _chunkHJKOSEH2cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(error, () => ( "Unknown error")));
+    return new (0, _chunkTCRRSS44cjs.ErrorExecutionResult)(ctx, _nullishCoalesce(error, () => ( "Unknown error")));
   } finally {
     for (const cleanup of cleanups) {
       try {
@@ -164,9 +198,11 @@ var executeIteration = async ({
   iteration,
   ctx,
   cognitive,
-  abortSignal,
+  controller,
   onExit,
-  onBeforeExecution
+  onBeforeExecution,
+  onBeforeTool,
+  onAfterTool
 }) => {
   var _a, _b, _c, _d, _e;
   let startedAt = Date.now();
@@ -174,7 +210,7 @@ var executeIteration = async ({
   const model = await cognitive.getModelDetails(_nullishCoalesce(ctx.model, () => ( "best")));
   const modelLimit = model.input.maxTokens;
   const responseLengthBuffer = getModelOutputLimit(modelLimit);
-  const messages = _chunkJGVAZO4Xcjs.truncateWrappedContent.call(void 0, {
+  const messages = _chunkGZPN7RGHcjs.truncateWrappedContent.call(void 0, {
     messages: iteration.messages,
     tokenLimit: modelLimit - responseLengthBuffer,
     throwOnFailure: true
@@ -192,7 +228,7 @@ var executeIteration = async ({
     model: model.ref
   });
   const output = await cognitive.generateContent({
-    signal: abortSignal,
+    signal: controller.signal,
     systemPrompt: (_a = messages.find((x) => x.role === "system")) == null ? void 0 : _a.content,
     model: model.ref,
     temperature: ctx.temperature,
@@ -208,7 +244,10 @@ var executeIteration = async ({
   iteration.code = assistantResponse.code.trim();
   if (typeof onBeforeExecution === "function") {
     try {
-      await onBeforeExecution(iteration);
+      const hookRes = await onBeforeExecution(iteration, controller);
+      if (typeof (hookRes == null ? void 0 : hookRes.code) === "string" && hookRes.code.trim().length > 0) {
+        iteration.code = hookRes.code.trim();
+      }
     } catch (err) {
       if (err instanceof _chunkJDABP4SDcjs.ThinkSignal) {
         return iteration.end({
@@ -245,7 +284,7 @@ var executeIteration = async ({
     model: model.ref,
     code: iteration.code
   });
-  const vmContext = { ..._chunk276Q6EWPcjs.stripInvalidIdentifiers.call(void 0, iteration.variables) };
+  const vmContext = { ..._chunkWHNOR4ZUcjs.stripInvalidIdentifiers.call(void 0, iteration.variables) };
   for (const obj of iteration.objects) {
     const internalValues = {};
     const instance = {};
@@ -288,19 +327,27 @@ var executeIteration = async ({
       });
     }
     for (const tool of _nullishCoalesce(obj.tools, () => ( []))) {
-      instance[tool.name] = wrapTool({ tool, traces, object: obj.name });
+      instance[tool.name] = wrapTool({
+        tool,
+        traces,
+        object: obj.name,
+        iteration,
+        beforeHook: onBeforeTool,
+        afterHook: onAfterTool,
+        controller
+      });
     }
     Object.preventExtensions(instance);
     Object.seal(instance);
     vmContext[obj.name] = instance;
   }
   for (const tool of iteration.tools) {
-    const wrapped = wrapTool({ tool, traces });
+    const wrapped = wrapTool({ tool, traces, iteration, beforeHook: onBeforeTool, afterHook: onAfterTool, controller });
     for (const key of [tool.name, ..._nullishCoalesce(tool.aliases, () => ( []))]) {
       vmContext[key] = wrapped;
     }
   }
-  if (abortSignal == null ? void 0 : abortSignal.aborted) {
+  if (controller.signal.aborted) {
     traces.push({
       type: "abort_signal",
       started_at: Date.now(),
@@ -309,22 +356,26 @@ var executeIteration = async ({
     return iteration.end({
       type: "aborted",
       aborted: {
-        reason: _nullishCoalesce((abortSignal == null ? void 0 : abortSignal.reason), () => ( "The operation was aborted"))
+        reason: _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted"))
       }
     });
   }
   startedAt = Date.now();
-  const result = await _chunkBEPRLBPKcjs.runAsyncFunction.call(void 0, vmContext, iteration.code, traces, abortSignal, ctx.timeout).catch(
-    (err) => {
-      return {
-        success: false,
-        error: err,
-        lines_executed: [],
-        traces: [],
-        variables: {}
-      };
-    }
-  );
+  const result = await _chunkBEPRLBPKcjs.runAsyncFunction.call(void 0, 
+    vmContext,
+    iteration.code,
+    traces,
+    controller.signal,
+    ctx.timeout
+  ).catch((err) => {
+    return {
+      success: false,
+      error: err,
+      lines_executed: [],
+      traces: [],
+      variables: {}
+    };
+  });
   if (result.error && result.error instanceof _chunkJDABP4SDcjs.InvalidCodeError) {
     return iteration.end({
       type: "invalid_code_error",
@@ -348,11 +399,11 @@ var executeIteration = async ({
       }
     });
   }
-  if (abortSignal == null ? void 0 : abortSignal.aborted) {
+  if (controller.signal.aborted) {
     return iteration.end({
       type: "aborted",
       aborted: {
-        reason: _nullishCoalesce((abortSignal == null ? void 0 : abortSignal.reason), () => ( "The operation was aborted"))
+        reason: _nullishCoalesce(controller.signal.reason, () => ( "The operation was aborted"))
       }
     });
   }
@@ -462,7 +513,7 @@ var executeIteration = async ({
     }
   });
 };
-function wrapTool({ tool, traces, object }) {
+function wrapTool({ tool, traces, object, iteration, beforeHook, afterHook, controller }) {
   const getToolInput = (input) => _nullishCoalesce(tool.zInput.safeParse(input).data, () => ( input));
   return function(input) {
     const toolCallId = `tcall_${_ulid.ulid.call(void 0, )}`;
@@ -510,9 +561,32 @@ function wrapTool({ tool, traces, object }) {
       return false;
     };
     try {
-      const result = tool.execute(input, {
-        callId: toolCallId
-      });
+      const withHooks = async (input2) => {
+        const beforeRes = await (beforeHook == null ? void 0 : beforeHook({
+          iteration,
+          tool,
+          input: input2,
+          controller
+        }));
+        if (typeof (beforeRes == null ? void 0 : beforeRes.input) !== "undefined") {
+          input2 = beforeRes.input;
+        }
+        let output2 = await tool.execute(input2, {
+          callId: toolCallId
+        });
+        const afterRes = await (afterHook == null ? void 0 : afterHook({
+          iteration,
+          tool,
+          input: input2,
+          output: output2,
+          controller
+        }));
+        if (typeof (afterRes == null ? void 0 : afterRes.output) !== "undefined") {
+          output2 = afterRes.output;
+        }
+        return output2;
+      };
+      const result = withHooks(input);
       if (result instanceof Promise || (result == null ? void 0 : result.then) && (result == null ? void 0 : result.catch)) {
         return result.then((res) => {
           output = res;

package/dist/llmz.d.ts

@@ -10,29 +10,166 @@ import { type Tool } from './tool.js';
 import { Trace } from './types.js';
 export type ExecutionHooks = {
     /**
-     * Called after each iteration ends
+     * NON-BLOCKING HOOK
+     *   This hook will not block the execution of the iteration.
+     * NON-MUTATION HOOK
+     *   This hook can't mutate traces.
      *
-     * **Warning**: This should not be a long task as it blocks the execution
+     * This hook is called for each trace that is generated during the iteration.
+     * It is useful for logging, debugging, or monitoring the execution of the iteration.
      */
-    onIterationEnd?: (iteration: Iteration) => Promise<void> | void;
     onTrace?: (event: {
         trace: Trace;
         iteration: number;
     }) => void;
+    /**
+     * BLOCKING HOOK
+     *   This hook will block the execution of the iteration until it resolves.
+     * NON-MUTATION HOOK
+     *   This hook can't mutate the result or status of the iteration.
+     *
+     * This hook will be called after each iteration ends, regardless of the status.
+     * This is useful for logging, cleanup or to prevent or delay the next iteration from starting.
+     */
+    onIterationEnd?: (iteration: Iteration, controller: AbortController) => Promise<void> | void;
+    /**
+     * BLOCKING HOOK
+     *   This hook will block the execution of the iteration until it resolves.
+     * NON-MUTATION HOOK
+     *   This hook can't mutate the exit result.
+     *
+     * This hook is called when an exit is reached in the iteration.
+     * It is useful for logging, sending notifications, or performing actions based on the exit.
+     * It can also be used to throw an error and preventing the exit from being successful.
+     * If this hook throws an error, the execution will keep iterating with the error as context.
+     */
     onExit?: <T = unknown>(result: ExitResult<T>) => Promise<void> | void;
-    onBeforeExecution?: (iteration: Iteration) => Promise<void> | void;
+    /**
+     * BLOCKING HOOK
+     *   This hook will block the execution of the iteration until it resolves.
+     * MUTATION HOOK
+     *   This hook can mutate the code to run in the iteration.
+     *
+     * This hook is called after the LLM generates the code for the iteration, but before it is executed.
+     * It is useful for modifying the code to run, or for guarding against certain code patterns.
+     */
+    onBeforeExecution?: (iteration: Iteration, controller: AbortController) => Promise<{
+        code?: string;
+    } | void>;
+    /**
+     * BLOCKING HOOK
+     *   This hook will block the execution of the iteration until it resolves.
+     * MUTATION HOOK
+     *   This hook can mutate the input to the tool.
+     *
+     * This hook is called before any tool is executed.
+     * It is useful for modifying the input to a tool or prevent a tool from executing.
+     */
+    onBeforeTool?: (event: {
+        iteration: Iteration;
+        tool: Tool;
+        input: any;
+        controller: AbortController;
+    }) => Promise<{
+        input?: any;
+    } | void>;
+    /**
+     * BLOCKING HOOK
+     *   This hook will block the execution of the iteration until it resolves.
+     * MUTATION HOOK
+     *   This hook can mutate the output of the tool.
+     *
+     * This hook is called after a tool is executed.
+     * It is useful for modifying the output of a tool or for logging purposes.
+     */
+    onAfterTool?: (event: {
+        iteration: Iteration;
+        tool: Tool;
+        input: any;
+        output: any;
+        controller: AbortController;
+    }) => Promise<{
+        output?: any;
+    } | void>;
 };
 type Options = Partial<Pick<Context, 'loop' | 'temperature' | 'model' | 'timeout'>>;
 export type ExecutionProps = {
+    /**
+     * If provided, the execution will be run in "Chat Mode".
+     * In this mode, the execution will be able to send messages to the chat and will also have access to a chat transcript.
+     * The execution can still end with a custom Exit, but a special ListenExit will be added to give back the chat control to the user.
+     *
+     * If `chat` is not provided, the execution will run in "Worker Mode", where it will not have access to a chat transcript.
+     * In Worker Mode, the execution will iterate until it reaches an Exit or runs out of iterations.
+     */
     chat?: Chat;
+    /**
+     * Instructions for the LLM to follow.
+     * This is a system prompt that will be used to guide the LLM's behavior.
+     * It can be a simple string or a function that returns a string based on the current context (dynamic instructions).
+     * Dynamic instructions are evaluated at the start of each iteration, allowing for context-aware instructions.
+     */
     instructions?: ValueOrGetter<string, Context>;
+    /**
+     * Objects available in the context.
+     * Objects are useful to scope related tools together and to provide data to the VM.
+     * Objects can contain "properties" that can be read and written to, as well as "tools" that can be executed.
+     * Properties are type-safe and can be defined using a Zui schema.
+     * Properties can be marked as read-only or writable.
+     * The sandbox will ensure that properties are only modified if they are writable, and will also ensure that the values are valid according to the schema.
+     *
+     * Objects can be a static array of objects or a function that returns an array based on the current context.
+     * Dynamic objects are evaluated at the start of each iteration, allowing for context-aware objects.
+     *
+     * Example:
+     * An object "user" with properties "name" (string, writable) and "age" (number, read-only) will allow the LLM to see both properties and their values,
+     * and executing the code `user.name = 'John'` will succeed, while `user.age = 30` will throw an error as the property is read-only.
+     * Similarly, `user.name = 123` will throw an error as the value is not a string.
+     */
     objects?: ValueOrGetter<ObjectInstance[], Context>;
+    /**
+     * Tools available in the context.
+     * Tools are functions that can be executed by the LLM to perform actions or retrieve data.
+     * Tools can be defined with input and output schemas using Zui, and can be scoped to an object.
+     * Tools can also have aliases, which are alternative names for the tool that can be used to call it.
+     *
+     * Tools can be a static array of tools or a function that returns an array based on the current context.
+     * Dynamic tools are evaluated at the start of each iteration, allowing for context-aware tools.
+     */
     tools?: ValueOrGetter<Tool[], Context>;
+    /**
+     * Exits available in the context.
+     * Exits define the possible endpoints for the execution. Every execution will either end with an exit, or run out of iterations.
+     *
+     * When `chat` is provided, the built-in "ListenExit" is automatically added.
+     * When `exits` is not provided, the built-in "DefaultExit" is automatically added.
+     *
+     * Each exit has a name and can have aliases, which are alternative names for the exit that can be used to call it.
+     * Exits can also have a Zui schema to validate the return value when the exit is reached.
+     *
+     * Exits can be a static array of exits or a function that returns an array based on the current context.
+     * Dynamic exits are evaluated at the start of each iteration, allowing for context-aware exits.
+     */
     exits?: ValueOrGetter<Exit[], Context>;
     options?: Options;
-    /** An instance of a Botpress Client, or an instance of Cognitive Client (@botpress/cognitive) */
+    /**
+     * An instance of a Botpress Client, or an instance of Cognitive Client (@botpress/cognitive).
+     * This is used to generate content using the LLM and to access the Botpress API.
+     */
     client: Cognitive | BotpressClientLike;
+    /**
+     * When provided, the execution will immediately stop when the signal is aborted.
+     * This will stop the LLM generation, as well as kill the VM sandbox execution.
+     * Aborted iterations will end with IterationStatuses.Aborted and the execution will be marked as failed.
+     */
     signal?: AbortSignal;
+    /**
+     * A snapshot is a saved state of the execution context.
+     * It can be used to resume the execution of a context at a later time.
+     * This is useful for long-running executions that may need to be paused and resumed later.
+     * The snapshot MUST be settled, which means it has to be resolved or rejected.
+     * Providing an unsettled snapshot will throw an error.
+     */
     snapshot?: Snapshot;
 } & ExecutionHooks;
 export declare const executeContext: (props: ExecutionProps) => Promise<ExecutionResult>;