llmz 0.0.13 → 0.0.14

package/dist/index.js

@@ -8,11 +8,11 @@ import {
   SuccessExecutionResult,
   ThinkExit,
   getValue
-} from "./chunk-PRVFVXT4.js";
+} from "./chunk-2Z5SFF6R.js";
 import "./chunk-KH6JQYQA.js";
 import {
   Tool
-} from "./chunk-JAGB2AOU.js";
+} from "./chunk-OKTHMXRT.js";
 import {
   formatTypings,
   getTypings
@@ -26,7 +26,7 @@ import {
 import "./chunk-JQBT7UWN.js";
 import {
   Exit
-} from "./chunk-JMSZKB4T.js";
+} from "./chunk-XAN7HQP5.js";
 import {
   Component,
   assertValidComponent,
@@ -307,6 +307,62 @@ var ObjectInstance = class {
   properties;
   tools;
   metadata;
+  /**
+   * Creates a new ObjectInstance.
+   *
+   * @param props - Object configuration
+   * @param props.name - Unique object name (must be valid TypeScript identifier)
+   * @param props.description - Human-readable description of the object
+   * @param props.tools - Array of tools to group under this object namespace
+   * @param props.properties - Array of stateful properties for this object
+   * @param props.metadata - Additional metadata for the object
+   *
+   * @throws Error if name is not a valid identifier
+   * @throws Error if description is not a string
+   * @throws Error if metadata is not an object
+   * @throws Error if properties/tools are not arrays
+   * @throws Error if properties exceed 100 limit
+   * @throws Error if property names are duplicated or invalid
+   * @throws Error if property descriptions exceed 5000 characters
+   *
+   * @example
+   * ```typescript
+   * const userProfile = new ObjectInstance({
+   *   name: 'user',
+   *   description: 'User profile management',
+   *   properties: [
+   *     {
+   *       name: 'name',
+   *       value: 'John Doe',
+   *       type: z.string().min(1),
+   *       description: 'User full name',
+   *       writable: true,
+   *     },
+   *     {
+   *       name: 'email',
+   *       value: null,
+   *       type: z.string().email().nullable(),
+   *       description: 'User email address',
+   *       writable: true,
+   *     },
+   *   ],
+   *   tools: [
+   *     new Tool({
+   *       name: 'updateProfile',
+   *       input: z.object({ name: z.string(), email: z.string() }),
+   *       handler: async ({ name, email }) => {
+   *         // Update external system
+   *         await updateUserInDatabase({ name, email })
+   *       },
+   *     }),
+   *   ],
+   *   metadata: {
+   *     version: '1.0',
+   *     category: 'user-management',
+   *   },
+   * })
+   * ```
+   */
   constructor(props) {
     var _a;
     if (!isValidIdentifier(props.name)) {
@@ -368,6 +424,43 @@ var ObjectInstance = class {
     this.properties = props.properties;
     this.tools = Tool.withUniqueNames(props.tools ?? []);
   }
+  /**
+   * Generates TypeScript namespace declarations for this object.
+   *
+   * This method creates TypeScript definitions that are included in the LLM context
+   * to help it understand the available properties and tools. Properties become
+   * const declarations with appropriate Readonly/Writable types, and tools become
+   * function signatures.
+   *
+   * @returns Promise resolving to TypeScript namespace declaration
+   *
+   * @example
+   * ```typescript
+   * const obj = new ObjectInstance({
+   *   name: 'user',
+   *   properties: [
+   *     { name: 'name', value: 'John', writable: true },
+   *     { name: 'id', value: 123, writable: false },
+   *   ],
+   *   tools: [
+   *     new Tool({
+   *       name: 'save',
+   *       input: z.object({ data: z.string() }),
+   *       handler: async ({ data }) => { /* ... *\/ },
+   *     }),
+   *   ],
+   * })
+   *
+   * const typings = await obj.getTypings()
+   * console.log(typings)
+   * // Output:
+   * // export namespace user {
+   * //   const name: Writable<string> = "John"
+   * //   const id: Readonly<number> = 123
+   * //   function save(args: { data: string }): Promise<void>
+   * // }
+   * ```
+   */
   async getTypings() {
     return getObjectTypings(this).withProperties().withTools().build();
   }
@@ -866,25 +959,129 @@ var Chat = class {
   handler;
   transcript;
   components;
+  /**
+   * Creates a new Chat instance.
+   *
+   * @param props - Chat configuration
+   * @param props.handler - Function to handle agent messages (called for every agent output)
+   * @param props.components - Available UI components (static array or dynamic function)
+   * @param props.transcript - Conversation history (static array or dynamic function, defaults to empty)
+   *
+   * @example
+   * ```typescript
+   * // Basic chat with static configuration
+   * const chat = new Chat({
+   *   handler: async (input) => {
+   *     if (isComponent(input, DefaultComponents.Text)) {
+   *       console.log('Agent:', input.children.join(''))
+   *     }
+   *   },
+   *   components: [DefaultComponents.Text, DefaultComponents.Button],
+   *   transcript: [
+   *     { role: 'user', content: 'Hello', timestamp: Date.now() }
+   *   ],
+   * })
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Dynamic chat with functions for real-time updates
+   * class MyChat extends Chat {
+   *   private messages: Transcript.Message[] = []
+   *
+   *   constructor() {
+   *     super({
+   *       handler: (input) => this.handleMessage(input),
+   *
+   *       // Dynamic components - can change during execution
+   *       components: () => [
+   *         DefaultComponents.Text,
+   *         DefaultComponents.Button,
+   *         ...this.getCustomComponents()
+   *       ],
+   *
+   *       // Dynamic transcript - always reflects current state
+   *       transcript: () => this.messages,
+   *     })
+   *   }
+   * }
+   * ```
+   */
   constructor(props) {
     this.handler = props.handler;
     this.components = props.components;
     this.transcript = props.transcript || [];
   }
+  /**
+   * Called when an execution cycle completes, regardless of the outcome.
+   *
+   * Override this method to handle execution results, manage conversation flow,
+   * or perform cleanup tasks. This is called after each `execute()` call completes,
+   * whether it succeeds, fails, or is interrupted.
+   *
+   * @param result - The execution result containing status, iterations, and exit information
+   *
+   * @example
+   * ```typescript
+   * class MyChat extends Chat {
+   *   public result?: ExecutionResult
+   *
+   *   onExecutionDone(result: ExecutionResult) {
+   *     // Store result for conversation flow control
+   *     this.result = result
+   *
+   *     // Handle different result types
+   *     if (result.isSuccess()) {
+   *       console.log('✅ Execution completed successfully')
+   *       console.log('Exit:', result.output.exit_name)
+   *     } else if (result.isError()) {
+   *       console.error('❌ Execution failed:', result.output.error)
+   *     } else if (result.isInterrupted()) {
+   *       console.log('⏸️ Execution interrupted (partial result)')
+   *     }
+   *   }
+   *
+   *   // Use stored result for conversation flow
+   *   isWaitingForInput(): boolean {
+   *     return this.result?.is(ListenExit) ?? false
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // CLIChat implementation example
+   * class CLIChat extends Chat {
+   *   public status?: IterationStatus
+   *   public result?: ExecutionResult
+   *
+   *   onExecutionDone(result: ExecutionResult) {
+   *     this.result = result
+   *     this.status = result.iterations.at(-1)?.status
+   *   }
+   *
+   *   // Check if agent exited with specific exit type
+   *   hasExitedWith<R>(exit: Exit<R>): boolean {
+   *     return this.status?.type === 'exit_success' &&
+   *            this.status.exit_success.exit_name === exit.name
+   *   }
+   * }
+   * ```
+   */
   onExecutionDone(_result) {
   }
 };
 
 // src/index.ts
 var execute = async (props) => {
-  const { executeContext } = await import("./llmz-ROOX7RYI.js");
+  const { executeContext } = await import("./llmz-MCHRHRTD.js");
   return executeContext(props);
 };
 var init = async () => {
-  await import("./llmz-ROOX7RYI.js");
+  await import("./llmz-MCHRHRTD.js");
   await import("./component-WFVDVSDK.js");
-  await import("./tool-N6ODRRGH.js");
-  await import("./exit-YORW76T3.js");
+  await import("./tool-4AJIJ3QB.js");
+  await import("./exit-7HDRH27N.js");
   await import("./jsx-AEHVFB3L.js");
   await import("./vm-FLBMZUA2.js");
   await import("./utils-N24IHDFA.js");

package/dist/{llmz-ROOX7RYI.js → llmz-MCHRHRTD.js}

@@ -7,9 +7,9 @@ import {
   PartialExecutionResult,
   Snapshot,
   SuccessExecutionResult
-} from "./chunk-PRVFVXT4.js";
+} from "./chunk-2Z5SFF6R.js";
 import "./chunk-KH6JQYQA.js";
-import "./chunk-JAGB2AOU.js";
+import "./chunk-OKTHMXRT.js";
 import "./chunk-IH2WQFO5.js";
 import {
   AssignmentError,
@@ -24,7 +24,7 @@ import {
 import {
   cleanStackTrace
 } from "./chunk-JQBT7UWN.js";
-import "./chunk-JMSZKB4T.js";
+import "./chunk-XAN7HQP5.js";
 import "./chunk-GGWM6X2K.js";
 import "./chunk-ORQP26SZ.js";
 import {
@@ -46,6 +46,37 @@ import { Cognitive } from "@botpress/cognitive";
 import { z } from "@bpinternal/zui";
 import ms from "ms";
 import { ulid } from "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 = ms("15s");
 var RESPONSE_LENGTH_BUFFER = {
@@ -70,7 +101,8 @@ 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.isCognitiveClient(props.client) ? props.client : new Cognitive({ client: props.client });
   const cleanups = [];
   const ctx = new Context({
@@ -91,14 +123,14 @@ var _executeContext = async (props) => {
         return new ErrorExecutionResult(ctx, new LoopExceededError());
       }
       const iteration = await ctx.nextIteration();
-      if (signal == null ? void 0 : signal.aborted) {
+      if (controller.signal.aborted) {
         iteration.end({
           type: "aborted",
           aborted: {
-            reason: signal.reason ?? "The operation was aborted"
+            reason: controller.signal.reason ?? "The operation was aborted"
           }
         });
-        return new ErrorExecutionResult(ctx, signal.reason ?? "The operation was aborted");
+        return new ErrorExecutionResult(ctx, 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,7 +160,7 @@ 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);
       }
@@ -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();
@@ -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 ThinkSignal) {
         return iteration.end({
@@ -288,19 +327,27 @@ var executeIteration = async ({
       });
     }
     for (const tool of 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, ...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: (abortSignal == null ? void 0 : abortSignal.reason) ?? "The operation was aborted"
+        reason: controller.signal.reason ?? "The operation was aborted"
       }
     });
   }
   startedAt = Date.now();
-  const result = await runAsyncFunction(vmContext, iteration.code, traces, abortSignal, ctx.timeout).catch(
-    (err) => {
-      return {
-        success: false,
-        error: err,
-        lines_executed: [],
-        traces: [],
-        variables: {}
-      };
-    }
-  );
+  const result = await runAsyncFunction(
+    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 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: (abortSignal == null ? void 0 : abortSignal.reason) ?? "The operation was aborted"
+        reason: 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) => tool.zInput.safeParse(input).data ?? input;
   return function(input) {
     const toolCallId = `tcall_${ulid()}`;
@@ -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;