@botpress/runtime 1.13.9 → 1.13.11

package/dist/internal.js

@@ -48,7 +48,7 @@ var init_define_BUILD = __esm({
 var define_PACKAGE_VERSIONS_default;
 var init_define_PACKAGE_VERSIONS = __esm({
   "<define:__PACKAGE_VERSIONS__>"() {
-    define_PACKAGE_VERSIONS_default = { runtime: "1.13.9", adk: "1.13.9", sdk: "5.0.2", llmz: "0.0.35", zai: "2.5.6", cognitive: "0.3.3" };
+    define_PACKAGE_VERSIONS_default = { runtime: "1.13.11", adk: "1.13.11", sdk: "5.0.2", llmz: "0.0.37", zai: "2.5.6", cognitive: "0.3.3" };
   }
 });
 
@@ -61,6 +61,124 @@ var init_asset = __esm({
   }
 });
 
+// ../../node_modules/ms/index.js
+var require_ms = __commonJS({
+  "../../node_modules/ms/index.js"(exports2, module) {
+    init_define_BUILD();
+    init_define_PACKAGE_VERSIONS();
+    var s = 1e3;
+    var m = s * 60;
+    var h = m * 60;
+    var d = h * 24;
+    var w = d * 7;
+    var y = d * 365.25;
+    module.exports = function(val, options) {
+      options = options || {};
+      var type = typeof val;
+      if (type === "string" && val.length > 0) {
+        return parse(val);
+      } else if (type === "number" && isFinite(val)) {
+        return options.long ? fmtLong(val) : fmtShort(val);
+      }
+      throw new Error(
+        "val is not a non-empty string or a valid number. val=" + JSON.stringify(val)
+      );
+    };
+    function parse(str) {
+      str = String(str);
+      if (str.length > 100) {
+        return;
+      }
+      var match2 = /^(-?(?:\d+)?\.?\d+) *(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)?$/i.exec(
+        str
+      );
+      if (!match2) {
+        return;
+      }
+      var n = parseFloat(match2[1]);
+      var type = (match2[2] || "ms").toLowerCase();
+      switch (type) {
+        case "years":
+        case "year":
+        case "yrs":
+        case "yr":
+        case "y":
+          return n * y;
+        case "weeks":
+        case "week":
+        case "w":
+          return n * w;
+        case "days":
+        case "day":
+        case "d":
+          return n * d;
+        case "hours":
+        case "hour":
+        case "hrs":
+        case "hr":
+        case "h":
+          return n * h;
+        case "minutes":
+        case "minute":
+        case "mins":
+        case "min":
+        case "m":
+          return n * m;
+        case "seconds":
+        case "second":
+        case "secs":
+        case "sec":
+        case "s":
+          return n * s;
+        case "milliseconds":
+        case "millisecond":
+        case "msecs":
+        case "msec":
+        case "ms":
+          return n;
+        default:
+          return void 0;
+      }
+    }
+    function fmtShort(ms4) {
+      var msAbs = Math.abs(ms4);
+      if (msAbs >= d) {
+        return Math.round(ms4 / d) + "d";
+      }
+      if (msAbs >= h) {
+        return Math.round(ms4 / h) + "h";
+      }
+      if (msAbs >= m) {
+        return Math.round(ms4 / m) + "m";
+      }
+      if (msAbs >= s) {
+        return Math.round(ms4 / s) + "s";
+      }
+      return ms4 + "ms";
+    }
+    function fmtLong(ms4) {
+      var msAbs = Math.abs(ms4);
+      if (msAbs >= d) {
+        return plural(ms4, msAbs, d, "day");
+      }
+      if (msAbs >= h) {
+        return plural(ms4, msAbs, h, "hour");
+      }
+      if (msAbs >= m) {
+        return plural(ms4, msAbs, m, "minute");
+      }
+      if (msAbs >= s) {
+        return plural(ms4, msAbs, s, "second");
+      }
+      return ms4 + " ms";
+    }
+    function plural(ms4, msAbs, n, name) {
+      var isPlural = msAbs >= n * 1.5;
+      return Math.round(ms4 / n) + " " + name + (isPlural ? "s" : "");
+    }
+  }
+});
+
 // src/errors.ts
 import { z } from "@botpress/sdk";
 var Errors;
@@ -262,7 +380,7 @@ var init_singletons = __esm({
 
 // src/runtime/context/context.ts
 import { AsyncLocalStorage } from "async_hooks";
-var storage, context;
+var storage, defaultContext, context;
 var init_context = __esm({
   "src/runtime/context/context.ts"() {
     "use strict";
@@ -270,6 +388,7 @@ var init_context = __esm({
     init_define_PACKAGE_VERSIONS();
     init_singletons();
     storage = getSingleton("__ADK_GLOBAL_CTX_STORAGE", () => new AsyncLocalStorage());
+    defaultContext = getSingleton("__ADK_GLOBAL_DEFAULT_CTX", () => ({ value: null }));
     context = {
       enterWith: (data) => {
         storage.enterWith(data);
@@ -288,7 +407,10 @@ var init_context = __esm({
         return store;
       },
       get: (key, opts) => {
-        const store = storage.getStore();
+        let store = storage.getStore();
+        if (!store && defaultContext.value) {
+          store = defaultContext.value;
+        }
         if (store) {
           store.states ??= [];
           store.tags ??= [];
@@ -304,6 +426,28 @@ var init_context = __esm({
         const store = storage.getStore();
         if (!store) throw new Error("Cannot set context outside of `run`");
         store[key] = value;
+      },
+      /**
+       * Set a default context that will be used as a fallback when no AsyncLocalStorage context is active.
+       * This is useful for testing and script execution where code runs outside of request handlers.
+       *
+       * @example
+       * ```typescript
+       * context.setDefaultContext({
+       *   botId: 'my-bot',
+       *   integrations: agentRegistry.integrations,
+       *   interfaces: agentRegistry.interfaces,
+       * })
+       * ```
+       */
+      setDefaultContext: (data) => {
+        defaultContext.value = data;
+      },
+      /**
+       * Clear the default context.
+       */
+      clearDefaultContext: () => {
+        defaultContext.value = null;
       }
     };
   }
@@ -27909,124 +28053,6 @@ var require_proxy_from_env = __commonJS({
   }
 });
 
-// ../../node_modules/ms/index.js
-var require_ms = __commonJS({
-  "../../node_modules/ms/index.js"(exports2, module) {
-    init_define_BUILD();
-    init_define_PACKAGE_VERSIONS();
-    var s = 1e3;
-    var m = s * 60;
-    var h = m * 60;
-    var d = h * 24;
-    var w = d * 7;
-    var y = d * 365.25;
-    module.exports = function(val, options) {
-      options = options || {};
-      var type = typeof val;
-      if (type === "string" && val.length > 0) {
-        return parse(val);
-      } else if (type === "number" && isFinite(val)) {
-        return options.long ? fmtLong(val) : fmtShort(val);
-      }
-      throw new Error(
-        "val is not a non-empty string or a valid number. val=" + JSON.stringify(val)
-      );
-    };
-    function parse(str) {
-      str = String(str);
-      if (str.length > 100) {
-        return;
-      }
-      var match2 = /^(-?(?:\d+)?\.?\d+) *(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)?$/i.exec(
-        str
-      );
-      if (!match2) {
-        return;
-      }
-      var n = parseFloat(match2[1]);
-      var type = (match2[2] || "ms").toLowerCase();
-      switch (type) {
-        case "years":
-        case "year":
-        case "yrs":
-        case "yr":
-        case "y":
-          return n * y;
-        case "weeks":
-        case "week":
-        case "w":
-          return n * w;
-        case "days":
-        case "day":
-        case "d":
-          return n * d;
-        case "hours":
-        case "hour":
-        case "hrs":
-        case "hr":
-        case "h":
-          return n * h;
-        case "minutes":
-        case "minute":
-        case "mins":
-        case "min":
-        case "m":
-          return n * m;
-        case "seconds":
-        case "second":
-        case "secs":
-        case "sec":
-        case "s":
-          return n * s;
-        case "milliseconds":
-        case "millisecond":
-        case "msecs":
-        case "msec":
-        case "ms":
-          return n;
-        default:
-          return void 0;
-      }
-    }
-    function fmtShort(ms3) {
-      var msAbs = Math.abs(ms3);
-      if (msAbs >= d) {
-        return Math.round(ms3 / d) + "d";
-      }
-      if (msAbs >= h) {
-        return Math.round(ms3 / h) + "h";
-      }
-      if (msAbs >= m) {
-        return Math.round(ms3 / m) + "m";
-      }
-      if (msAbs >= s) {
-        return Math.round(ms3 / s) + "s";
-      }
-      return ms3 + "ms";
-    }
-    function fmtLong(ms3) {
-      var msAbs = Math.abs(ms3);
-      if (msAbs >= d) {
-        return plural(ms3, msAbs, d, "day");
-      }
-      if (msAbs >= h) {
-        return plural(ms3, msAbs, h, "hour");
-      }
-      if (msAbs >= m) {
-        return plural(ms3, msAbs, m, "minute");
-      }
-      if (msAbs >= s) {
-        return plural(ms3, msAbs, s, "second");
-      }
-      return ms3 + " ms";
-    }
-    function plural(ms3, msAbs, n, name) {
-      var isPlural = msAbs >= n * 1.5;
-      return Math.round(ms3 / n) + " " + name + (isPlural ? "s" : "");
-    }
-  }
-});
-
 // ../../node_modules/debug/src/common.js
 var require_common = __commonJS({
   "../../node_modules/debug/src/common.js"(exports2, module) {
@@ -28067,8 +28093,8 @@ var require_common = __commonJS({
           }
           const self2 = debug;
           const curr = Number(/* @__PURE__ */ new Date());
-          const ms3 = curr - (prevTime || curr);
-          self2.diff = ms3;
+          const ms4 = curr - (prevTime || curr);
+          self2.diff = ms4;
           self2.prev = prevTime;
           self2.curr = curr;
           prevTime = curr;
@@ -34676,6 +34702,9 @@ Always prefer information from the knowledge bases over general knowledge when a
                 ...props.hooks?.onBeforeTool && {
                   onBeforeTool: asyncResource.bind(props.hooks.onBeforeTool)
                 },
+                ...props.hooks?.onIterationStart && {
+                  onIterationStart: asyncResource.bind(props.hooks.onIterationStart)
+                },
                 ...props.hooks?.onAfterTool && {
                   onAfterTool: asyncResource.bind(props.hooks.onAfterTool)
                 },
@@ -34805,7 +34834,7 @@ var init_actions = __esm({
               }
               integrations ??= context.get("integrations", { optional: true });
               client2 ??= context.get("client", { optional: true });
-              const integration = integrations.find((i) => i.alias === integrationName);
+              const integration = integrations?.find((i) => i.alias === integrationName);
               const actionDef = integration?.definition.actions?.[actionName];
               const handler = async (params) => {
                 integrations ??= context.get("integrations", { optional: true });
@@ -35120,15 +35149,25 @@ var init_validate_tag_name = __esm({
   }
 });
 
+// src/utilities/validate-event-name.ts
+var init_validate_event_name = __esm({
+  "src/utilities/validate-event-name.ts"() {
+    "use strict";
+    init_define_BUILD();
+    init_define_PACKAGE_VERSIONS();
+  }
+});
+
 // src/define-config.ts
 import { z as z4 } from "@botpress/sdk";
-var zuiSchema, modelSchema, tagDefinitionSchema, configSchema, AGENT_CONFIG_BRAND, isAgentConfig;
+var zuiSchema, modelSchema, tagDefinitionSchema, eventDefinitionSchema, configSchema, AGENT_CONFIG_BRAND, isAgentConfig;
 var init_define_config = __esm({
   "src/define-config.ts"() {
     "use strict";
     init_define_BUILD();
     init_define_PACKAGE_VERSIONS();
     init_validate_tag_name();
+    init_validate_event_name();
     zuiSchema = z4.custom(
       (val) => {
         if (typeof val === "object" && val !== null && "parse" in val) {
@@ -35153,6 +35192,13 @@ var init_define_config = __esm({
         description: z4.string().optional()
       })
     );
+    eventDefinitionSchema = z4.record(
+      z4.string(),
+      z4.object({
+        schema: zuiSchema.optional(),
+        description: z4.string().optional()
+      })
+    );
     configSchema = z4.object({
       name: z4.string().optional(),
       description: z4.string().optional(),
@@ -35193,7 +35239,8 @@ var init_define_config = __esm({
         zai: val?.zai ?? "openai:gpt-4.1-2025-04-14",
         autonomous: val?.autonomous ?? "openai:gpt-4.1-mini-2025-04-14"
       })),
-      dependencies: z4.custom()
+      dependencies: z4.custom(),
+      events: eventDefinitionSchema.optional()
     });
     AGENT_CONFIG_BRAND = Symbol.for("@botpress/runtime/AgentConfig");
     isAgentConfig = (value) => {
@@ -36335,6 +36382,268 @@ var init_tracked_state = __esm({
   }
 });
 
+// src/runtime/tracked-tags.ts
+function isSystemTag(key) {
+  return key.includes(":");
+}
+var TrackedTags;
+var init_tracked_tags = __esm({
+  "src/runtime/tracked-tags.ts"() {
+    "use strict";
+    init_define_BUILD();
+    init_define_PACKAGE_VERSIONS();
+    init_context();
+    init_tracing();
+    TrackedTags = class _TrackedTags {
+      type;
+      id;
+      client;
+      _tags = {};
+      _initialTags = {};
+      _loaded = false;
+      _saving = false;
+      _saveAgain = false;
+      _saveAgainCount = 0;
+      static _savingAll = false;
+      static _saveAllAgain = false;
+      static _saveAllCount = 0;
+      constructor(props) {
+        this.type = props.type;
+        this.id = props.id;
+        this.client = props.client;
+      }
+      static create(props) {
+        const tags = context.get("tags", { optional: true });
+        const executionFinished = context.get("executionFinished", { optional: true });
+        if (executionFinished) {
+          throw new Error(`Cannot create new TrackedTags "${props.type}/${props.id}" after execution has finished.`);
+        }
+        const match2 = tags?.find((x) => x.id === props.id && x.type === props.type);
+        if (match2) {
+          return match2;
+        }
+        const instance = new _TrackedTags(props);
+        if (props.initialTags) {
+          instance._tags = { ...props.initialTags };
+          instance._initialTags = { ...props.initialTags };
+          instance._loaded = true;
+        }
+        tags?.push(instance);
+        return instance;
+      }
+      static async saveAllDirty() {
+        if (this._savingAll) {
+          this._saveAllAgain = true;
+          return;
+        }
+        try {
+          this._savingAll = true;
+          const tags = context.get("tags", { optional: true });
+          const dirtyTags = tags?.filter((t) => t.isDirty()) || [];
+          if (!dirtyTags.length) {
+            return;
+          }
+          await span(
+            "tags.saveAllDirty",
+            {
+              tags_count: tags?.length || 0,
+              tags: tags.map((t) => `${t.type}/${t.id}`)
+            },
+            () => Promise.allSettled(dirtyTags.map((t) => t.save()))
+          );
+        } finally {
+          this._savingAll = false;
+          if (this._saveAllAgain && this._saveAllCount++ <= 5) {
+            this._saveAllAgain = false;
+            await this.saveAllDirty();
+          } else {
+            this._saveAllCount = 0;
+          }
+        }
+      }
+      static async loadAll() {
+        await span("tags.loadAll", {}, async () => {
+          const client2 = context.get("client")._inner;
+          const bot2 = context.get("bot", { optional: true });
+          const user2 = context.get("user", { optional: true });
+          const conversation = context.get("conversation", { optional: true });
+          const workflow = context.get("workflow", { optional: true });
+          if (bot2) {
+            const botTags = bot2.tags;
+            _TrackedTags.create({
+              client: client2,
+              type: "bot",
+              id: bot2.id,
+              ...botTags && { initialTags: botTags }
+            });
+          }
+          if (user2) {
+            const userTags = user2.tags;
+            _TrackedTags.create({
+              client: client2,
+              type: "user",
+              id: user2.id,
+              ...userTags && { initialTags: userTags }
+            });
+          }
+          if (conversation) {
+            const conversationTags = conversation.tags;
+            _TrackedTags.create({
+              client: client2,
+              type: "conversation",
+              id: conversation.id,
+              ...conversationTags && { initialTags: conversationTags }
+            });
+          }
+          if (workflow) {
+            const workflowTags = workflow.tags;
+            _TrackedTags.create({
+              client: client2,
+              type: "workflow",
+              id: workflow.id,
+              ...workflowTags && { initialTags: workflowTags }
+            });
+          }
+          const tags = context.get("tags", { optional: true });
+          const unloadedTags = tags?.filter((tag) => !tag._loaded) ?? [];
+          if (unloadedTags.length > 0) {
+            await Promise.allSettled(unloadedTags.map((tag) => tag.load()));
+          }
+        });
+      }
+      static unloadAll() {
+        context.get("tags", { optional: true })?.splice(0);
+      }
+      async load(force = false) {
+        if (this._loaded && !force) {
+          return;
+        }
+        await span(
+          "tags.load",
+          {
+            type: this.type,
+            id: this.id
+          },
+          async () => {
+            const tags = await this.fetchTags();
+            this._tags = { ...tags };
+            this._initialTags = { ...tags };
+            this._loaded = true;
+          }
+        );
+      }
+      async save() {
+        if (this._saving) {
+          this._saveAgain = true;
+          return;
+        }
+        const executionFinished = context.get("executionFinished", { optional: true });
+        if (executionFinished) {
+          throw new Error(`Cannot save TrackedTags "${this.type}/${this.id}" after execution has finished.`);
+        }
+        try {
+          this._saving = true;
+          await span(
+            "tags.save",
+            {
+              type: this.type,
+              id: this.id
+            },
+            async () => {
+              await this.persistTags(this._tags);
+              this._initialTags = { ...this._tags };
+            }
+          );
+        } finally {
+          this._saving = false;
+          if (this._saveAgain && this._saveAgainCount++ <= 5) {
+            this._saveAgain = false;
+            await this.save();
+          } else {
+            this._saveAgainCount = 0;
+          }
+        }
+      }
+      isDirty() {
+        const currentKeys = Object.keys(this._tags).filter((k) => !isSystemTag(k)).sort();
+        const initialKeys = Object.keys(this._initialTags).filter((k) => !isSystemTag(k)).sort();
+        if (currentKeys.length !== initialKeys.length) {
+          return true;
+        }
+        for (const key of currentKeys) {
+          if (this._tags[key] !== this._initialTags[key]) {
+            return true;
+          }
+        }
+        return false;
+      }
+      get tags() {
+        return new Proxy(this._tags, {
+          set: (target, prop, value) => {
+            if (isSystemTag(prop)) {
+              return true;
+            }
+            target[prop] = value;
+            return true;
+          },
+          deleteProperty: (target, prop) => {
+            if (isSystemTag(prop)) {
+              return true;
+            }
+            target[prop] = void 0;
+            return true;
+          }
+        });
+      }
+      set tags(value) {
+        this._tags = { ...value };
+      }
+      async fetchTags() {
+        try {
+          if (this.type === "bot") {
+            const { bot: bot2 } = await this.client.getBot({ id: this.id });
+            return bot2.tags || {};
+          } else if (this.type === "user") {
+            const { user: user2 } = await this.client.getUser({ id: this.id });
+            return user2.tags || {};
+          } else if (this.type === "conversation") {
+            const { conversation } = await this.client.getConversation({ id: this.id });
+            return conversation.tags || {};
+          } else if (this.type === "workflow") {
+            const { workflow } = await this.client.getWorkflow({ id: this.id });
+            return workflow.tags || {};
+          }
+        } catch (err) {
+          console.error(`Failed to fetch tags for ${this.type}/${this.id}:`, err);
+        }
+        return {};
+      }
+      async persistTags(tags) {
+        const tagsForApi = {};
+        for (const [key, value] of Object.entries(tags)) {
+          if (value !== void 0 && !isSystemTag(key)) {
+            tagsForApi[key] = value;
+          }
+        }
+        try {
+          if (this.type === "bot") {
+            await this.client.updateBot({ id: this.id, tags: tagsForApi });
+          } else if (this.type === "user") {
+            await this.client.updateUser({ id: this.id, tags: tagsForApi });
+          } else if (this.type === "conversation") {
+            await this.client.updateConversation({ id: this.id, tags: tagsForApi });
+          } else if (this.type === "workflow") {
+            await this.client.updateWorkflow({ id: this.id, tags: tagsForApi });
+          }
+        } catch (err) {
+          console.error(`Failed to persist tags for ${this.type}/${this.id}:`, err);
+          throw err;
+        }
+      }
+    };
+  }
+});
+
 // src/runtime/context/inspector-handler.ts
 var init_inspector_handler = __esm({
   "src/runtime/context/inspector-handler.ts"() {
@@ -36416,6 +36725,7 @@ var init_handlers = __esm({
     init_http();
     init_agent_registry();
     init_tracked_state();
+    init_tracked_tags();
     init_tracing();
     init_heavy_imports();
     init_environment();
@@ -37588,259 +37898,6 @@ var init_handlers2 = __esm({
   }
 });
 
-// src/runtime/tracked-tags.ts
-var TrackedTags;
-var init_tracked_tags = __esm({
-  "src/runtime/tracked-tags.ts"() {
-    "use strict";
-    init_define_BUILD();
-    init_define_PACKAGE_VERSIONS();
-    init_context();
-    init_tracing();
-    TrackedTags = class _TrackedTags {
-      type;
-      id;
-      client;
-      _tags = {};
-      _initialTags = {};
-      _loaded = false;
-      _saving = false;
-      _saveAgain = false;
-      _saveAgainCount = 0;
-      static _savingAll = false;
-      static _saveAllAgain = false;
-      static _saveAllCount = 0;
-      constructor(props) {
-        this.type = props.type;
-        this.id = props.id;
-        this.client = props.client;
-      }
-      static create(props) {
-        const tags = context.get("tags", { optional: true });
-        const executionFinished = context.get("executionFinished", { optional: true });
-        if (executionFinished) {
-          throw new Error(`Cannot create new TrackedTags "${props.type}/${props.id}" after execution has finished.`);
-        }
-        const match2 = tags?.find((x) => x.id === props.id && x.type === props.type);
-        if (match2) {
-          return match2;
-        }
-        const instance = new _TrackedTags(props);
-        if (props.initialTags) {
-          instance._tags = { ...props.initialTags };
-          instance._initialTags = { ...props.initialTags };
-          instance._loaded = true;
-        }
-        tags?.push(instance);
-        return instance;
-      }
-      static async saveAllDirty() {
-        if (this._savingAll) {
-          this._saveAllAgain = true;
-          return;
-        }
-        try {
-          this._savingAll = true;
-          const tags = context.get("tags", { optional: true });
-          const dirtyTags = tags?.filter((t) => t.isDirty()) || [];
-          if (!dirtyTags.length) {
-            return;
-          }
-          await span(
-            "tags.saveAllDirty",
-            {
-              tags_count: tags?.length || 0,
-              tags: tags.map((t) => `${t.type}/${t.id}`)
-            },
-            () => Promise.allSettled(dirtyTags.map((t) => t.save()))
-          );
-        } finally {
-          this._savingAll = false;
-          if (this._saveAllAgain && this._saveAllCount++ <= 5) {
-            this._saveAllAgain = false;
-            await this.saveAllDirty();
-          } else {
-            this._saveAllCount = 0;
-          }
-        }
-      }
-      static async loadAll() {
-        await span("tags.loadAll", {}, async () => {
-          const client2 = context.get("client")._inner;
-          const bot2 = context.get("bot", { optional: true });
-          const user2 = context.get("user", { optional: true });
-          const conversation = context.get("conversation", { optional: true });
-          const workflow = context.get("workflow", { optional: true });
-          if (bot2) {
-            const botTags = bot2.tags;
-            _TrackedTags.create({
-              client: client2,
-              type: "bot",
-              id: bot2.id,
-              ...botTags && { initialTags: botTags }
-            });
-          }
-          if (user2) {
-            const userTags = user2.tags;
-            _TrackedTags.create({
-              client: client2,
-              type: "user",
-              id: user2.id,
-              ...userTags && { initialTags: userTags }
-            });
-          }
-          if (conversation) {
-            const conversationTags = conversation.tags;
-            _TrackedTags.create({
-              client: client2,
-              type: "conversation",
-              id: conversation.id,
-              ...conversationTags && { initialTags: conversationTags }
-            });
-          }
-          if (workflow) {
-            const workflowTags = workflow.tags;
-            _TrackedTags.create({
-              client: client2,
-              type: "workflow",
-              id: workflow.id,
-              ...workflowTags && { initialTags: workflowTags }
-            });
-          }
-          const tags = context.get("tags", { optional: true });
-          const unloadedTags = tags?.filter((tag) => !tag._loaded) ?? [];
-          if (unloadedTags.length > 0) {
-            await Promise.allSettled(unloadedTags.map((tag) => tag.load()));
-          }
-        });
-      }
-      static unloadAll() {
-        context.get("tags", { optional: true })?.splice(0);
-      }
-      async load(force = false) {
-        if (this._loaded && !force) {
-          return;
-        }
-        await span(
-          "tags.load",
-          {
-            type: this.type,
-            id: this.id
-          },
-          async () => {
-            const tags = await this.fetchTags();
-            this._tags = { ...tags };
-            this._initialTags = { ...tags };
-            this._loaded = true;
-          }
-        );
-      }
-      async save() {
-        if (this._saving) {
-          this._saveAgain = true;
-          return;
-        }
-        const executionFinished = context.get("executionFinished", { optional: true });
-        if (executionFinished) {
-          throw new Error(`Cannot save TrackedTags "${this.type}/${this.id}" after execution has finished.`);
-        }
-        try {
-          this._saving = true;
-          await span(
-            "tags.save",
-            {
-              type: this.type,
-              id: this.id
-            },
-            async () => {
-              await this.persistTags(this._tags);
-              this._initialTags = { ...this._tags };
-            }
-          );
-        } finally {
-          this._saving = false;
-          if (this._saveAgain && this._saveAgainCount++ <= 5) {
-            this._saveAgain = false;
-            await this.save();
-          } else {
-            this._saveAgainCount = 0;
-          }
-        }
-      }
-      isDirty() {
-        const currentKeys = Object.keys(this._tags).sort();
-        const initialKeys = Object.keys(this._initialTags).sort();
-        if (currentKeys.length !== initialKeys.length) {
-          return true;
-        }
-        for (const key of currentKeys) {
-          if (this._tags[key] !== this._initialTags[key]) {
-            return true;
-          }
-        }
-        return false;
-      }
-      get tags() {
-        return new Proxy(this._tags, {
-          set: (target, prop, value) => {
-            target[prop] = value;
-            return true;
-          },
-          deleteProperty: (target, prop) => {
-            target[prop] = void 0;
-            return true;
-          }
-        });
-      }
-      set tags(value) {
-        this._tags = { ...value };
-      }
-      async fetchTags() {
-        try {
-          if (this.type === "bot") {
-            const { bot: bot2 } = await this.client.getBot({ id: this.id });
-            return bot2.tags || {};
-          } else if (this.type === "user") {
-            const { user: user2 } = await this.client.getUser({ id: this.id });
-            return user2.tags || {};
-          } else if (this.type === "conversation") {
-            const { conversation } = await this.client.getConversation({ id: this.id });
-            return conversation.tags || {};
-          } else if (this.type === "workflow") {
-            const { workflow } = await this.client.getWorkflow({ id: this.id });
-            return workflow.tags || {};
-          }
-        } catch (err) {
-          console.error(`Failed to fetch tags for ${this.type}/${this.id}:`, err);
-        }
-        return {};
-      }
-      async persistTags(tags) {
-        const tagsForApi = {};
-        for (const [key, value] of Object.entries(tags)) {
-          if (value !== void 0) {
-            tagsForApi[key] = value;
-          }
-        }
-        try {
-          if (this.type === "bot") {
-            await this.client.updateBot({ id: this.id, tags: tagsForApi });
-          } else if (this.type === "user") {
-            await this.client.updateUser({ id: this.id, tags: tagsForApi });
-          } else if (this.type === "conversation") {
-            await this.client.updateConversation({ id: this.id, tags: tagsForApi });
-          } else if (this.type === "workflow") {
-            await this.client.updateWorkflow({ id: this.id, tags: tagsForApi });
-          }
-        } catch (err) {
-          console.error(`Failed to persist tags for ${this.type}/${this.id}:`, err);
-          throw err;
-        }
-      }
-    };
-  }
-});
-
 // src/runtime/client.ts
 import { Client as Client3 } from "@botpress/client";
 function getStandaloneClient() {
@@ -38157,12 +38214,12 @@ var init_workflow_step = __esm({
       workflowControlContext.abort();
       throw createStepSignal();
     };
-    step.sleep = async (name, ms3) => {
+    step.sleep = async (name, ms4) => {
       await _step(
         name,
         async () => {
           const remainingTime = context.get("runtime").getRemainingExecutionTimeInMs();
-          if (remainingTime - MIN_STEP_REMAINING_TIME_MS <= ms3 || ms3 >= 1e4) {
+          if (remainingTime - MIN_STEP_REMAINING_TIME_MS <= ms4 || ms4 >= 1e4) {
             const client2 = context.get("client");
             const workflowControlContext = context.get("workflowControlContext");
             await client2.createEvent({
@@ -38170,7 +38227,7 @@ var init_workflow_step = __esm({
               payload: {},
               workflowId: workflowControlContext.workflow.id,
               schedule: {
-                delay: ms3
+                delay: ms4
               }
             });
             await updateWorkflow({
@@ -38179,7 +38236,7 @@ var init_workflow_step = __esm({
             });
             workflowControlContext.abort();
           } else {
-            await new Promise((resolve) => void setTimeout(resolve, ms3));
+            await new Promise((resolve) => void setTimeout(resolve, ms4));
             context.get("workflowControlContext").signal.throwIfAborted();
           }
         },
@@ -38190,8 +38247,8 @@ var init_workflow_step = __esm({
       );
     };
     step.sleepUntil = async (name, date) => {
-      const ms3 = Math.max(0, new Date(date).getTime() - Date.now() - MIN_STEP_REMAINING_TIME_MS);
-      await step.sleep(name, ms3);
+      const ms4 = Math.max(0, new Date(date).getTime() - Date.now() - MIN_STEP_REMAINING_TIME_MS);
+      await step.sleep(name, ms4);
     };
     step.waitForWorkflow = async (name, workflowId) => {
       const workflowControlContext = context.get("workflowControlContext");
@@ -38410,12 +38467,13 @@ function createWorkflowExecutionState(client2, workflowId) {
     name: BUILT_IN_STATES.workflowSteps
   });
 }
-var workflowStepContextSchema, workflowExecutionContextSchema, StepSymbol, BaseWorkflowInstance;
+var import_ms3, workflowStepContextSchema, workflowExecutionContextSchema, StepSymbol, BaseWorkflowInstance;
 var init_workflow_instance = __esm({
   "src/primitives/workflow-instance.ts"() {
     "use strict";
     init_define_BUILD();
     init_define_PACKAGE_VERSIONS();
+    import_ms3 = __toESM(require_ms(), 1);
     init_errors();
     init_library();
     init_autonomous();
@@ -38542,6 +38600,81 @@ var init_workflow_instance = __esm({
         });
         Object.assign(this.workflow, workflow);
       }
+      /**
+       * Extend the workflow timeout by setting a new timeout.
+       * This is useful for long-running workflows that need more time to complete.
+       *
+       * @param options - Either `{ in: string }` for relative duration or `{ at: string }` for absolute ISO timestamp
+       * @returns A promise that resolves when the timeout is updated (can be awaited or not)
+       * @example
+       * // Relative timeout (duration from now):
+       * workflow.setTimeout({ in: '30m' })  // Timeout in 30 minutes
+       * workflow.setTimeout({ in: '6 hours' })  // Timeout in 6 hours
+       *
+       * // Absolute timeout (ISO timestamp):
+       * workflow.setTimeout({ at: '2024-12-25T00:00:00Z' })
+       *
+       * // Optionally await if you need to ensure the update completes:
+       * await workflow.setTimeout({ in: '1h' })
+       */
+      setTimeout(options) {
+        let newTimeoutAt;
+        if ("in" in options) {
+          const durationMs = (0, import_ms3.default)(options.in);
+          if (!durationMs) {
+            throw new Error(`Invalid duration format: "${options.in}". Use formats like "30m", "1h", "6 hours".`);
+          }
+          newTimeoutAt = new Date(Date.now() + durationMs).toISOString();
+        } else {
+          const date = new Date(options.at);
+          if (isNaN(date.getTime())) {
+            throw new Error(`Invalid ISO date format: "${options.at}".`);
+          }
+          newTimeoutAt = date.toISOString();
+        }
+        return updateWorkflow({
+          id: this.id,
+          timeoutAt: newTimeoutAt
+        }).then(({ workflow }) => {
+          Object.assign(this.workflow, workflow);
+        });
+      }
+      /**
+       * Fail the workflow with an error reason.
+       * This immediately interrupts the workflow handler and marks the workflow as failed.
+       * Can only be called from within a workflow handler.
+       *
+       * @param reason - The error reason for the failure
+       * @throws Never returns - always throws to interrupt the handler
+       * @example
+       * workflow.fail('Invalid input data')
+       */
+      fail(reason) {
+        const controlContext = context.get("workflowControlContext", { optional: true });
+        if (!controlContext || controlContext.workflow.id !== this.id) {
+          throw new Error("workflow.fail() can only be called from within the workflow handler");
+        }
+        controlContext.fail(reason);
+        throw createStepSignal();
+      }
+      /**
+       * Complete the workflow early with the given output.
+       * This immediately interrupts the workflow handler and marks the workflow as completed.
+       * Can only be called from within a workflow handler.
+       *
+       * @param output - The workflow output (typed according to workflow definition)
+       * @throws Never returns - always throws to interrupt the handler
+       * @example
+       * workflow.complete({ result: 'success', data: processedData })
+       */
+      complete(output2) {
+        const controlContext = context.get("workflowControlContext", { optional: true });
+        if (!controlContext || controlContext.workflow.id !== this.id) {
+          throw new Error("workflow.complete() can only be called from within the workflow handler");
+        }
+        controlContext.complete(output2);
+        throw createStepSignal();
+      }
       /**
        * Provide data in response to a workflow data request (instance method).
        * Call this method from a conversation handler when you receive a WorkflowDataRequestEvent.
@@ -38592,6 +38725,7 @@ var init_workflow_instance = __esm({
           workflow: this.workflow,
           aborted: false,
           failed: false,
+          completed: false,
           acked: false,
           restarted: false,
           signal: abortSignal,
@@ -38606,6 +38740,10 @@ var init_workflow_instance = __esm({
             workflowControlContext.failed = true;
             workflowControlContext.failedReason = reason;
           },
+          complete: (result) => {
+            workflowControlContext.completed = true;
+            workflowControlContext.completedResult = result;
+          },
           ack: async () => {
             if (workflowControlContext.acked) {
               return;
@@ -38659,7 +38797,8 @@ var init_workflow_instance = __esm({
               step,
               client: this.client,
               execute: this.execute.bind(this),
-              signal: abortSignal
+              signal: abortSignal,
+              workflow: this
             });
             return {
               status: "done",
@@ -38670,6 +38809,12 @@ var init_workflow_instance = __esm({
           }
         } catch (err) {
           if (isStepSignal(err)) {
+            if (workflowControlContext.completed) {
+              return {
+                status: "done",
+                result: workflowControlContext.completedResult
+              };
+            }
             if (workflowControlContext.failed) {
               return {
                 status: "error",