llmz 0.6.0 → 0.6.2

package/dist/index.js

@@ -1,1555 +1,1797 @@
-import {
-  DefaultExit,
-  ErrorExecutionResult,
-  ExecutionResult,
-  ListenExit,
-  PartialExecutionResult,
-  Snapshot,
-  SuccessExecutionResult,
-  ThinkExit,
-  _CustomModelClient,
-  getValue,
-  parseExit
-} from "./chunk-4POZJQXN.js";
-import {
-  MARKER,
-  NAME_REGEX,
-  StreamingMessageParser,
-  generateInstructions,
-  tryParseJson
-} from "./chunk-LOX7GOR6.js";
-import {
-  configureQuickJS
-} from "./chunk-UGHFNCPD.js";
-import {
-  Tool
-} from "./chunk-TDALRNGL.js";
-import {
-  formatTypings,
-  getTypings,
-  isGroup,
-  isPunct,
-  parse,
-  tokenize
-} from "./chunk-GDJTKI7J.js";
-import {
-  CodeFormattingError,
-  LoopExceededError,
-  SnapshotSignal,
-  ThinkSignal
-} from "./chunk-WSVDMGMR.js";
-import "./chunk-YEAWWJSJ.js";
-import {
-  Exit
-} from "./chunk-HB2G32AK.js";
-import {
-  Component,
-  assertValidComponent,
-  isAnyComponent,
-  isComponent
-} from "./chunk-KWQTYXAT.js";
-import "./chunk-XTEHT2TK.js";
-import {
-  stripTruncationTags,
-  truncateWrappedContent,
-  wrapContent
-} from "./chunk-72ZWBNZV.js";
-import {
-  configureTokenizer,
-  escapeString,
-  getMultilineComment,
-  isJsonSchema,
-  isValidIdentifier,
-  isZuiSchema,
-  toValidFunctionName,
-  toValidObjectName
-} from "./chunk-GLXADNTR.js";
-import {
-  upperFirst_default
-} from "./chunk-34GJUS6U.js";
-
-// package.json
-var version = "0.6.0";
-
-// src/objects.ts
-import { z } from "@bpinternal/zui";
-
-// src/hoist.ts
+import { a as StreamingMessageParser, c as NAME_REGEX, o as tryParseJson, r as generateInstructions, s as MARKER } from "./dual-modes-D_p-jedw.js";
+import { a as ThinkExit, c as ExecutionResult, d as Snapshot, f as parseExit, i as ListenExit, l as PartialExecutionResult, o as getValue, r as DefaultExit, s as ErrorExecutionResult, t as _CustomModelClient, u as SuccessExecutionResult } from "./custom-client-NUoxrFQh.js";
+import { a as getMultilineComment, c as isJsonSchema, l as isValidIdentifier, m as toValidObjectName, n as escapeString, p as toValidFunctionName, t as configureTokenizer, u as isZuiSchema, v as upperFirst } from "./utils-UBeAFeEI.js";
+import { t as Tool } from "./tool-CAo-BQHs.js";
+import { c as SnapshotSignal, l as ThinkSignal, o as LoopExceededError, r as CodeFormattingError } from "./errors-Cg1G0Awu.js";
+import { a as isPunct, i as isGroup, o as parse, r as formatTypings, s as tokenize, t as getTypings } from "./typings-CrBa7Tyy.js";
+import { t as Exit } from "./exit-CDdxDBRT.js";
+import { a as isComponent, i as isAnyComponent, n as assertValidComponent, t as Component } from "./component-DGG7d_Mz.js";
+import { i as wrapContent, n as truncateWrappedContent, t as stripTruncationTags } from "./truncator-DZqEqnpD.js";
+import { t as configureQuickJS } from "./quickjs-variant-BYhMBpwU.js";
+import { transforms, z } from "@bpinternal/zui";
+//#region package.json
+var version = "0.6.2";
+//#endregion
+//#region src/hoist.ts
+/**
+* Hoists object types (`{ ... }`) that appear more than once in a block of
+* typings into named `type` aliases, replacing every occurrence with a
+* reference. Runs repeatedly until a fixpoint so nested duplicates converge.
+*/
+/** Prints a node tree back to text, preserving line structure (formatTypings normalizes later) */
 function printNodes(nodes) {
-  let out = "";
-  let afterLineComment = false;
-  const emit = (n) => {
-    const newlines = Math.min(n.nl ?? 0, 2);
-    if (newlines > 0) {
-      out += "\n".repeat(newlines);
-    } else if (afterLineComment) {
-      out += "\n";
-    } else if (out.length && !out.endsWith("\n")) {
-      out += " ";
-    }
-    afterLineComment = false;
-    if (isGroup(n)) {
-      out += n.open;
-      for (const child of n.children) {
-        emit(child);
-      }
-      if (afterLineComment) {
-        out += "\n";
-        afterLineComment = false;
-      }
-      out += n.close;
-    } else {
-      out += n.text;
-      afterLineComment = n.kind === "line-comment";
-    }
-  };
-  for (const n of nodes) {
-    emit(n);
-  }
-  return out;
+	let out = "";
+	let afterLineComment = false;
+	const emit = (n) => {
+		const newlines = Math.min(n.nl ?? 0, 2);
+		if (newlines > 0) out += "\n".repeat(newlines);
+		else if (afterLineComment) out += "\n";
+		else if (out.length && !out.endsWith("\n")) out += " ";
+		afterLineComment = false;
+		if (isGroup(n)) {
+			out += n.open;
+			for (const child of n.children) emit(child);
+			if (afterLineComment) {
+				out += "\n";
+				afterLineComment = false;
+			}
+			out += n.close;
+		} else {
+			out += n.text;
+			afterLineComment = n.kind === "line-comment";
+		}
+	};
+	for (const n of nodes) emit(n);
+	return out;
 }
+/** Canonical structural key of a type literal: comments and separators ignored */
 function keyOf(group) {
-  const parts = [];
-  const visit = (n) => {
-    if (isGroup(n)) {
-      parts.push(n.open);
-      n.children.forEach(visit);
-      parts.push(n.close);
-    } else if (n.kind === "word" || n.kind === "string" || n.kind === "punct" && n.text !== ";" && n.text !== ",") {
-      parts.push(n.text);
-    }
-  };
-  visit(group);
-  return parts.join(" ");
+	const parts = [];
+	const visit = (n) => {
+		if (isGroup(n)) {
+			parts.push(n.open);
+			n.children.forEach(visit);
+			parts.push(n.close);
+		} else if (n.kind === "word" || n.kind === "string" || n.kind === "punct" && n.text !== ";" && n.text !== ",") parts.push(n.text);
+	};
+	visit(group);
+	return parts.join(" ");
 }
-var prevMeaningful = (siblings, index) => {
-  for (let i = index - 1; i >= 0; i--) {
-    const n = siblings[i];
-    if (isGroup(n) || n.kind !== "block-comment" && n.kind !== "line-comment") {
-      return n;
-    }
-  }
-  return void 0;
+const prevMeaningful = (siblings, index) => {
+	for (let i = index - 1; i >= 0; i--) {
+		const n = siblings[i];
+		if (isGroup(n) || n.kind !== "block-comment" && n.kind !== "line-comment") return n;
+	}
 };
-var asName = (text) => upperFirst_default(text.replace(/['"]/g, "").replace(/[^A-Za-z0-9_$]/g, ""));
+const asName = (text) => upperFirst(text.replace(/['"]/g, "").replace(/[^A-Za-z0-9_$]/g, ""));
+/** The naming segment for a `{`/`<` group from its surrounding tokens (`key:`, `fn(...)`, `): `, `=>`) */
 function segmentsAt(siblings, index) {
-  var _a;
-  const prev = prevMeaningful(siblings, index);
-  if (!prev || isGroup(prev)) {
-    return [];
-  }
-  if (isPunct(prev, "=>")) {
-    return ["Output"];
-  }
-  if (isPunct(prev, ":") || isPunct(prev, "<")) {
-    let i = siblings.indexOf(prev) - 1;
-    while (i >= 0 && !isGroup(siblings[i]) && ((_a = siblings[i].kind) == null ? void 0 : _a.includes("comment"))) {
-      i--;
-    }
-    let q = siblings[i];
-    if (q && !isGroup(q) && q.kind === "punct" && q.text === "?") {
-      q = siblings[--i];
-    }
-    if (q && isGroup(q) && q.open === "(") {
-      const fnWord = prevMeaningful(siblings, i);
-      return fnWord && !isGroup(fnWord) && fnWord.kind === "word" ? [asName(fnWord.text), "Output"] : ["Output"];
-    }
-    if (q && !isGroup(q) && (q.kind === "word" || q.kind === "string")) {
-      return [asName(q.text)];
-    }
-  }
-  return [];
+	const prev = prevMeaningful(siblings, index);
+	if (!prev || isGroup(prev)) return [];
+	if (isPunct(prev, "=>")) return ["Output"];
+	if (isPunct(prev, ":") || isPunct(prev, "<")) {
+		var _kind;
+		let i = siblings.indexOf(prev) - 1;
+		while (i >= 0 && !isGroup(siblings[i]) && ((_kind = siblings[i].kind) === null || _kind === void 0 ? void 0 : _kind.includes("comment"))) i--;
+		let q = siblings[i];
+		if (q && !isGroup(q) && q.kind === "punct" && q.text === "?") q = siblings[--i];
+		if (q && isGroup(q) && q.open === "(") {
+			const fnWord = prevMeaningful(siblings, i);
+			return fnWord && !isGroup(fnWord) && fnWord.kind === "word" ? [asName(fnWord.text), "Output"] : ["Output"];
+		}
+		if (q && !isGroup(q) && (q.kind === "word" || q.kind === "string")) return [asName(q.text)];
+	}
+	return [];
 }
+/**
+* Visits every hoistable `{ ... }` type literal with its naming path. Value
+* objects (after `=`) are skipped — except `type X = { ... }` alias bodies,
+* which are visited with their alias name so they can act as the canonical
+* definition.
+*/
 function walkLiterals(siblings, path, visit) {
-  var _a;
-  for (let i = 0; i < siblings.length; i++) {
-    const node = siblings[i];
-    if (!isGroup(node)) {
-      continue;
-    }
-    if (node.open === "(") {
-      const fnWord = prevMeaningful(siblings, i);
-      const fnName = fnWord && !isGroup(fnWord) && fnWord.kind === "word" ? [asName(fnWord.text)] : [];
-      walkLiterals(node.children, [...path, ...fnName], visit);
-      continue;
-    }
-    if (node.open === "<" || node.open === "[") {
-      walkLiterals(node.children, [...path, ...segmentsAt(siblings, i)], visit);
-      continue;
-    }
-    const prev = prevMeaningful(siblings, i);
-    if (prev && isPunct(prev, "=")) {
-      const eqIdx = siblings.indexOf(prev);
-      const nameTok = siblings[eqIdx - 1];
-      const typeTok = siblings[eqIdx - 2];
-      const isAlias = nameTok && typeTok && !isGroup(nameTok) && !isGroup(typeTok) && nameTok.kind === "word" && typeTok.kind === "word" && typeTok.text === "type";
-      if (!isAlias) {
-        continue;
-      }
-      const aliasName = nameTok.text;
-      visit({ siblings, index: i, group: node, path: [aliasName], aliasName });
-      if (siblings[i] === node) {
-        walkLiterals(node.children, [aliasName], visit);
-      }
-      continue;
-    }
-    const prevIsNamespace = prev && !isGroup(prev) && prev.kind === "word" && ((_a = prevMeaningful(siblings, siblings.indexOf(prev))) == null ? void 0 : _a.kind) === "word";
-    const namespaceLike = prevIsNamespace && ["namespace", "module"].includes(prevMeaningful(siblings, siblings.indexOf(prev)).text);
-    const segments = segmentsAt(siblings, i);
-    const newPath = [...path, ...segments];
-    if (!namespaceLike) {
-      visit({ siblings, index: i, group: node, path: newPath });
-    }
-    if (siblings[i] === node) {
-      walkLiterals(node.children, namespaceLike ? [...path, asName(prev.text)] : newPath, visit);
-    }
-  }
+	for (let i = 0; i < siblings.length; i++) {
+		var _prevMeaningful;
+		const node = siblings[i];
+		if (!isGroup(node)) continue;
+		if (node.open === "(") {
+			const fnWord = prevMeaningful(siblings, i);
+			const fnName = fnWord && !isGroup(fnWord) && fnWord.kind === "word" ? [asName(fnWord.text)] : [];
+			walkLiterals(node.children, [...path, ...fnName], visit);
+			continue;
+		}
+		if (node.open === "<" || node.open === "[") {
+			walkLiterals(node.children, [...path, ...segmentsAt(siblings, i)], visit);
+			continue;
+		}
+		const prev = prevMeaningful(siblings, i);
+		if (prev && isPunct(prev, "=")) {
+			const eqIdx = siblings.indexOf(prev);
+			const nameTok = siblings[eqIdx - 1];
+			const typeTok = siblings[eqIdx - 2];
+			if (!(nameTok && typeTok && !isGroup(nameTok) && !isGroup(typeTok) && nameTok.kind === "word" && typeTok.kind === "word" && typeTok.text === "type")) continue;
+			const aliasName = nameTok.text;
+			visit({
+				siblings,
+				index: i,
+				group: node,
+				path: [aliasName],
+				aliasName
+			});
+			if (siblings[i] === node) walkLiterals(node.children, [aliasName], visit);
+			continue;
+		}
+		const namespaceLike = prev && !isGroup(prev) && prev.kind === "word" && ((_prevMeaningful = prevMeaningful(siblings, siblings.indexOf(prev))) === null || _prevMeaningful === void 0 ? void 0 : _prevMeaningful.kind) === "word" && ["namespace", "module"].includes(prevMeaningful(siblings, siblings.indexOf(prev)).text);
+		const segments = segmentsAt(siblings, i);
+		const newPath = [...path, ...segments];
+		if (!namespaceLike) visit({
+			siblings,
+			index: i,
+			group: node,
+			path: newPath
+		});
+		if (siblings[i] === node) walkLiterals(node.children, namespaceLike ? [...path, asName(prev.text)] : newPath, visit);
+	}
 }
 function extractAndHoistTypes(code) {
-  const top = parse(tokenize(code));
-  const counts = /* @__PURE__ */ new Map();
-  const aliasByKey = /* @__PURE__ */ new Map();
-  const usedNames = /* @__PURE__ */ new Set();
-  walkLiterals(top, [], ({ group, path, aliasName }) => {
-    const key = keyOf(group);
-    counts.set(key, (counts.get(key) ?? 0) + 1);
-    if (aliasName && !aliasByKey.has(key)) {
-      aliasByKey.set(key, aliasName);
-    }
-    for (const segment of path) {
-      usedNames.add(segment);
-    }
-    if (aliasName) {
-      usedNames.add(aliasName);
-    }
-  });
-  const uniqueName = (base) => {
-    let name = base;
-    let counter = 1;
-    while (usedNames.has(name)) {
-      name = `${base}${counter++}`;
-    }
-    usedNames.add(name);
-    return name;
-  };
-  const newAliases = [];
-  walkLiterals(top, [], ({ siblings, index, group, aliasName, path }) => {
-    const key = keyOf(group);
-    if ((counts.get(key) ?? 0) < 2 || aliasName) {
-      return;
-    }
-    let name = aliasByKey.get(key);
-    if (!name) {
-      const deduped = [...new Set(path)];
-      name = uniqueName(deduped.length ? deduped.join("") : "UnnamedType");
-      aliasByKey.set(key, name);
-      newAliases.push(`type ${name} = ${printNodes([{ ...group, nl: 0 }])}`);
-    }
-    siblings[index] = { kind: "word", text: name, nl: group.nl };
-  });
-  const body = printNodes(top);
-  return newAliases.length ? `${newAliases.join("\n")}
-${body}` : body;
+	const top = parse(tokenize(code));
+	const counts = /* @__PURE__ */ new Map();
+	const aliasByKey = /* @__PURE__ */ new Map();
+	const usedNames = /* @__PURE__ */ new Set();
+	walkLiterals(top, [], ({ group, path, aliasName }) => {
+		const key = keyOf(group);
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+		if (aliasName && !aliasByKey.has(key)) aliasByKey.set(key, aliasName);
+		for (const segment of path) usedNames.add(segment);
+		if (aliasName) usedNames.add(aliasName);
+	});
+	const uniqueName = (base) => {
+		let name = base;
+		let counter = 1;
+		while (usedNames.has(name)) name = `${base}${counter++}`;
+		usedNames.add(name);
+		return name;
+	};
+	const newAliases = [];
+	walkLiterals(top, [], ({ siblings, index, group, aliasName, path }) => {
+		const key = keyOf(group);
+		if ((counts.get(key) ?? 0) < 2 || aliasName) return;
+		let name = aliasByKey.get(key);
+		if (!name) {
+			const deduped = [...new Set(path)];
+			name = uniqueName(deduped.length ? deduped.join("") : "UnnamedType");
+			aliasByKey.set(key, name);
+			newAliases.push(`type ${name} = ${printNodes([{
+				...group,
+				nl: 0
+			}])}`);
+		}
+		siblings[index] = {
+			kind: "word",
+			text: name,
+			nl: group.nl
+		};
+	});
+	const body = printNodes(top);
+	return newAliases.length ? `${newAliases.join("\n")}\n${body}` : body;
 }
 async function hoistTypings(code, formatOptions) {
-  formatOptions ??= {};
-  formatOptions.throwOnError ??= true;
-  for (let i = 1; i <= 5; i++) {
-    try {
-      const initialCode = code;
-      code = extractAndHoistTypes(code);
-      if (initialCode === code) {
-        break;
-      }
-    } catch (err) {
-      console.error(err);
-      if (formatOptions.throwOnError) {
-        throw new CodeFormattingError(err instanceof Error ? err.message : String(err ?? "Unknown Error"), code);
-      }
-      break;
-    }
-  }
-  return formatTypings(code, formatOptions);
+	formatOptions ??= {};
+	formatOptions.throwOnError ??= true;
+	for (let i = 1; i <= 5; i++) try {
+		const initialCode = code;
+		code = extractAndHoistTypes(code);
+		if (initialCode === code) break;
+	} catch (err) {
+		console.error(err);
+		if (formatOptions.throwOnError) throw new CodeFormattingError(err instanceof Error ? err.message : String(err ?? "Unknown Error"), code);
+		break;
+	}
+	return formatTypings(code, formatOptions);
 }
-
-// src/objects.ts
-var LARGE_OBJECT_LINES_OF_CODE = 10;
+//#endregion
+//#region src/objects.ts
+/** How many lines of code an object needs to have before we insert a comment for end tag */
+const LARGE_OBJECT_LINES_OF_CODE = 10;
+/**
+* ObjectInstance creates stateful, namespace-scoped objects for LLMz agents.
+*
+* Objects combine properties (stateful variables) and tools (functions) into a
+* single namespace that the LLM can interact with. This provides organized,
+* type-safe interfaces for complex data and functionality.
+*
+* ## Key Features
+* - **Stateful Properties**: Variables that persist across execution iterations
+* - **Validation**: Zod schema validation for property changes
+* - **Tool Grouping**: Organize related tools under a common namespace
+* - **Type Safety**: Full TypeScript inference and validation
+* - **Dynamic Updates**: Properties can reflect real-time state changes
+*
+* ## Use Cases
+* - **User Profile Management**: Collect and validate user data over time
+* - **API Namespacing**: Group related API calls under a common interface
+* - **State Machines**: Track and modify execution state
+* - **Configuration Objects**: Manage settings and preferences
+* - **Multi-Agent Systems**: Per-agent state and capabilities
+*
+* ## Basic Usage
+*
+* ### Simple Property Object
+* ```typescript
+* const userProfile = new ObjectInstance({
+*   name: 'user',
+*   description: 'User profile data',
+*   properties: [
+*     {
+*       name: 'name',
+*       value: 'John Doe',
+*       type: z.string().min(1),
+*       writable: true,
+*     },
+*     {
+*       name: 'email',
+*       value: null,
+*       type: z.string().email().nullable(),
+*       writable: true,
+*     },
+*     {
+*       name: 'id',
+*       value: 'user_123',
+*       writable: false, // Read-only
+*     },
+*   ],
+* })
+*
+* // LLM can access and modify: user.name, user.email
+* // LLM can read only: user.id
+* ```
+*
+* ### Tool Grouping
+* ```typescript
+* const fileSystem = new ObjectInstance({
+*   name: 'fs',
+*   description: 'File system operations',
+*   tools: [
+*     new Tool({
+*       name: 'readFile',
+*       input: z.object({ path: z.string() }),
+*       output: z.string(),
+*       handler: async ({ path }) => readFileSync(path, 'utf8'),
+*     }),
+*     new Tool({
+*       name: 'writeFile',
+*       input: z.object({ path: z.string(), content: z.string() }),
+*       handler: async ({ path, content }) => writeFileSync(path, content),
+*     }),
+*   ],
+* })
+*
+* // LLM can call: fs.readFile(), fs.writeFile()
+* ```
+*
+* ### Combined Properties and Tools
+* ```typescript
+* const database = new ObjectInstance({
+*   name: 'db',
+*   description: 'Database connection with state',
+*   properties: [
+*     {
+*       name: 'connectionString',
+*       value: 'postgresql://localhost:5432/mydb',
+*       writable: false,
+*     },
+*     {
+*       name: 'lastQuery',
+*       value: null,
+*       type: z.string().nullable(),
+*       writable: true,
+*     },
+*   ],
+*   tools: [
+*     new Tool({
+*       name: 'query',
+*       input: z.object({ sql: z.string() }),
+*       output: z.array(z.record(z.any())),
+*       handler: async ({ sql }) => {
+*         // Execute query and update lastQuery property
+*         const results = await executeQuery(sql)
+*         return results
+*       },
+*     }),
+*   ],
+* })
+* ```
+*
+* ## Dynamic Objects
+*
+* Objects can be created dynamically to reflect current state:
+*
+* ```typescript
+* const memory: Record<string, any> = {}
+*
+* const getObjects = () => [
+*   new ObjectInstance({
+*     name: 'user',
+*     properties: [
+*       {
+*         name: 'name',
+*         value: memory.name ?? null,
+*         type: z.string().nullable(),
+*         writable: true,
+*       },
+*       {
+*         name: 'age',
+*         value: memory.age ?? null,
+*         type: z.number().min(18).max(100).nullable(),
+*         writable: true,
+*       },
+*     ],
+*   }),
+* ]
+*
+* await execute({
+*   objects: getObjects, // Function returning current state
+*   onTrace: ({ trace }) => {
+*     if (trace.type === 'property') {
+*       // Persist property changes
+*       memory[trace.property] = trace.value
+*     }
+*   },
+*   // ...
+* })
+* ```
+*
+* ## Property Validation
+*
+* Properties support comprehensive validation through Zod schemas:
+*
+* ```typescript
+* const userSettings = new ObjectInstance({
+*   name: 'settings',
+*   properties: [
+*     {
+*       name: 'theme',
+*       value: 'light',
+*       type: z.enum(['light', 'dark']),
+*       writable: true,
+*     },
+*     {
+*       name: 'maxRetries',
+*       value: 3,
+*       type: z.number().min(1).max(10),
+*       writable: true,
+*     },
+*     {
+*       name: 'email',
+*       value: null,
+*       type: z.string().email().nullable(),
+*       writable: true,
+*     },
+*   ],
+* })
+* ```
+*
+* ## TypeScript Integration
+*
+* Objects generate TypeScript namespace declarations:
+*
+* ```typescript
+* // Generated types for the LLM context:
+* export namespace user {
+*   const name: Writable<string | null> = null
+*   const age: Writable<number | null> = null
+*   const id: Readonly<string> = "user_123"
+* }
+*
+* export namespace fs {
+*   function readFile(args: { path: string }): Promise<string>
+*   function writeFile(args: { path: string, content: string }): Promise<void>
+* }
+* ```
+*
+* @see {@link https://github.com/botpress/botpress/blob/master/packages/llmz/examples/09_chat_variables/index.ts} Example usage
+*/
 var ObjectInstance = class {
-  name;
-  description;
-  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)) {
-      throw new Error(
-        `Invalid name for tool ${props.name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`
-      );
-    }
-    if (props.description !== void 0 && typeof props.description !== "string") {
-      throw new Error(
-        `Invalid description for tool ${props.name}. Expected a string, but got type "${typeof props.description}"`
-      );
-    }
-    if (props.metadata !== void 0 && typeof props.metadata !== "object") {
-      throw new Error(
-        `Invalid metadata for tool ${props.name}. Expected an object, but got type "${typeof props.metadata}"`
-      );
-    }
-    if (props.properties !== void 0 && !Array.isArray(props.properties)) {
-      throw new Error(
-        `Invalid properties for tool ${props.name}. Expected an array, but got type "${typeof props.properties}"`
-      );
-    }
-    if (props.tools !== void 0 && !Array.isArray(props.tools)) {
-      throw new Error(`Invalid tools for tool ${props.name}. Expected an array, but got type "${typeof props.tools}"`);
-    }
-    if ((_a = props.properties) == null ? void 0 : _a.length) {
-      if (props.properties.length > 100) {
-        throw new Error(
-          `Too many properties for tool ${props.name}. Expected at most 100 properties, but got ${props.properties.length}`
-        );
-      }
-      for (const prop of props.properties) {
-        if (props.properties.filter((p) => p.name === prop.name).length > 1) {
-          throw new Error(`Duplicate property name "${prop.name}" in tool ${props.name}`);
-        }
-        if (!isValidIdentifier(prop.name)) {
-          throw new Error(
-            `Invalid name for property ${prop.name}. A property name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`
-          );
-        }
-        if (prop.description !== void 0 && typeof prop.description !== "string") {
-          throw new Error(
-            `Invalid description for property ${prop.name}. Expected a string, but got type "${typeof prop.description}"`
-          );
-        }
-        if (props.description && props.description.length >= 5e3) {
-          throw new Error(
-            `Description for property ${prop.name} is too long. Expected at most 5000 characters, but got ${props.description.length}`
-          );
-        }
-        if (typeof prop.writable !== "boolean") {
-          prop.writable = false;
-        }
-      }
-    }
-    this.name = props.name;
-    this.description = props.description;
-    this.metadata = props.metadata ?? {};
-    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();
-  }
-  /**
-   * Converts this ObjectInstance to its JSON representation.
-   *
-   * This method serializes the object into a JSON format that includes its name,
-   * description, properties, tools, and metadata. It is used for serialization
-   * and transmission of the object state.
-   *
-   * @returns JSON representation of the ObjectInstance
-   */
-  toJSON() {
-    return {
-      name: this.name,
-      description: this.description,
-      properties: this.properties,
-      tools: (this.tools ?? []).map((tool) => tool.toJSON()),
-      metadata: this.metadata
-    };
-  }
+	name;
+	description;
+	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 _props$properties;
+		if (!isValidIdentifier(props.name)) throw new Error(`Invalid name for tool ${props.name}. A tool name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
+		if (props.description !== void 0 && typeof props.description !== "string") throw new Error(`Invalid description for tool ${props.name}. Expected a string, but got type "${typeof props.description}"`);
+		if (props.metadata !== void 0 && typeof props.metadata !== "object") throw new Error(`Invalid metadata for tool ${props.name}. Expected an object, but got type "${typeof props.metadata}"`);
+		if (props.properties !== void 0 && !Array.isArray(props.properties)) throw new Error(`Invalid properties for tool ${props.name}. Expected an array, but got type "${typeof props.properties}"`);
+		if (props.tools !== void 0 && !Array.isArray(props.tools)) throw new Error(`Invalid tools for tool ${props.name}. Expected an array, but got type "${typeof props.tools}"`);
+		if ((_props$properties = props.properties) === null || _props$properties === void 0 ? void 0 : _props$properties.length) {
+			if (props.properties.length > 100) throw new Error(`Too many properties for tool ${props.name}. Expected at most 100 properties, but got ${props.properties.length}`);
+			for (const prop of props.properties) {
+				if (props.properties.filter((p) => p.name === prop.name).length > 1) throw new Error(`Duplicate property name "${prop.name}" in tool ${props.name}`);
+				if (!isValidIdentifier(prop.name)) throw new Error(`Invalid name for property ${prop.name}. A property name must start with a letter and contain only letters, numbers, and underscores. It must be 1-50 characters long.`);
+				if (prop.description !== void 0 && typeof prop.description !== "string") throw new Error(`Invalid description for property ${prop.name}. Expected a string, but got type "${typeof prop.description}"`);
+				if (props.description && props.description.length >= 5e3) throw new Error(`Description for property ${prop.name} is too long. Expected at most 5000 characters, but got ${props.description.length}`);
+				if (typeof prop.writable !== "boolean") prop.writable = false;
+			}
+		}
+		this.name = props.name;
+		this.description = props.description;
+		this.metadata = props.metadata ?? {};
+		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();
+	}
+	/**
+	* Converts this ObjectInstance to its JSON representation.
+	*
+	* This method serializes the object into a JSON format that includes its name,
+	* description, properties, tools, and metadata. It is used for serialization
+	* and transmission of the object state.
+	*
+	* @returns JSON representation of the ObjectInstance
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			description: this.description,
+			properties: this.properties,
+			tools: (this.tools ?? []).map((tool) => tool.toJSON()),
+			metadata: this.metadata
+		};
+	}
 };
+/**
+* Creates a TypeScript namespace builder for an ObjectInstance.
+*
+* This function provides a fluent API for generating TypeScript declarations
+* that include properties, tools, or both. It's used internally by ObjectInstance.getTypings().
+*
+* @param obj - The ObjectInstance to generate typings for
+* @returns A builder object with methods to configure and build the namespace
+* @internal
+*/
 function getObjectTypings(obj) {
-  let includeProperties = false;
-  let includeTools = false;
-  let hoisting = false;
-  const typings = [];
-  const addProperties = async () => {
-    var _a;
-    if (includeProperties && ((_a = obj.properties) == null ? void 0 : _a.length)) {
-      typings.push("");
-      typings.push("// ---------------- //");
-      typings.push("//    Properties    //");
-      typings.push("// ---------------- //");
-      typings.push("");
-      for (const prop of obj.properties ?? []) {
-        const description = prop.description ?? "";
-        if (description == null ? void 0 : description.trim().length) {
-          typings.push(getMultilineComment(description));
-        }
-        let type = "unknown";
-        if (prop.type) {
-          type = await getTypings(prop.type, {});
-        } else if (prop.value !== void 0) {
-          type = typeof prop.value;
-        }
-        type = prop.writable ? `Writable<${type}>` : `Readonly<${type}>`;
-        const value = embedPropertyValue(prop);
-        typings.push(`const ${prop.name}: ${type} = ${value}`);
-      }
-    }
-  };
-  const addTools = async () => {
-    var _a;
-    if (includeTools && ((_a = obj.tools) == null ? void 0 : _a.length)) {
-      typings.push("");
-      typings.push("// ---------------- //");
-      typings.push("//       Tools      //");
-      typings.push("// ---------------- //");
-      typings.push("");
-      for (const tool of obj.tools) {
-        const fnType = z.function(tool.zInput, tool.zOutput).title(tool.name).describe(tool.description ?? "");
-        let temp = await getTypings(fnType, {
-          declaration: true
-        });
-        temp = temp.replace("declare function ", "function ");
-        typings.push(temp);
-      }
-    }
-  };
-  const finalize = async () => {
-    var _a;
-    let closingBracket = "";
-    if (typings.length >= LARGE_OBJECT_LINES_OF_CODE) {
-      closingBracket = ` // end namespace "${obj.name}"`;
-    }
-    let body = typings.join("\n");
-    if (hoisting) {
-      body = await hoistTypings(body, { throwOnError: false });
-    }
-    typings.push("}" + closingBracket);
-    let header = "";
-    if ((_a = obj.description) == null ? void 0 : _a.trim().length) {
-      header = getMultilineComment(obj.description);
-    }
-    return formatTypings(
-      `${header}
+	let includeProperties = false;
+	let includeTools = false;
+	let hoisting = false;
+	const typings = [];
+	const addProperties = async () => {
+		var _obj$properties;
+		if (includeProperties && ((_obj$properties = obj.properties) === null || _obj$properties === void 0 ? void 0 : _obj$properties.length)) {
+			typings.push("");
+			typings.push("// ---------------- //");
+			typings.push("//    Properties    //");
+			typings.push("// ---------------- //");
+			typings.push("");
+			for (const prop of obj.properties ?? []) {
+				const description = prop.description ?? "";
+				if (description === null || description === void 0 ? void 0 : description.trim().length) typings.push(getMultilineComment(description));
+				let type = "unknown";
+				if (prop.type) type = await getTypings(prop.type, {});
+				else if (prop.value !== void 0) type = typeof prop.value;
+				type = prop.writable ? `Writable<${type}>` : `Readonly<${type}>`;
+				const value = embedPropertyValue(prop);
+				typings.push(`const ${prop.name}: ${type} = ${value}`);
+			}
+		}
+	};
+	const addTools = async () => {
+		var _obj$tools;
+		if (includeTools && ((_obj$tools = obj.tools) === null || _obj$tools === void 0 ? void 0 : _obj$tools.length)) {
+			typings.push("");
+			typings.push("// ---------------- //");
+			typings.push("//       Tools      //");
+			typings.push("// ---------------- //");
+			typings.push("");
+			for (const tool of obj.tools) {
+				const fnType = z.function(tool.zInput, tool.zOutput).title(tool.name).describe(tool.description ?? "");
+				let temp = await getTypings(fnType, { declaration: true });
+				temp = temp.replace("declare function ", "function ");
+				typings.push(temp);
+			}
+		}
+	};
+	const finalize = async () => {
+		var _obj$description;
+		let closingBracket = "";
+		if (typings.length >= LARGE_OBJECT_LINES_OF_CODE) closingBracket = ` // end namespace "${obj.name}"`;
+		let body = typings.join("\n");
+		if (hoisting) body = await hoistTypings(body, { throwOnError: false });
+		typings.push("}" + closingBracket);
+		let header = "";
+		if ((_obj$description = obj.description) === null || _obj$description === void 0 ? void 0 : _obj$description.trim().length) header = getMultilineComment(obj.description);
+		return formatTypings(`${header}
       export namespace ${obj.name} {
       ${body}
-      } ${closingBracket}`.trim(),
-      { throwOnError: false }
-    );
-  };
-  const api = {
-    withProperties: () => {
-      includeProperties = true;
-      return api;
-    },
-    withTools: () => {
-      includeTools = true;
-      return api;
-    },
-    withHoisting: () => {
-      hoisting = true;
-      return api;
-    },
-    async build() {
-      await addProperties();
-      await addTools();
-      return finalize();
-    }
-  };
-  return api;
+      } ${closingBracket}`.trim(), { throwOnError: false });
+	};
+	const api = {
+		withProperties: () => {
+			includeProperties = true;
+			return api;
+		},
+		withTools: () => {
+			includeTools = true;
+			return api;
+		},
+		withHoisting: () => {
+			hoisting = true;
+			return api;
+		},
+		async build() {
+			await addProperties();
+			await addTools();
+			return finalize();
+		}
+	};
+	return api;
 }
+/**
+* Converts a property value to its TypeScript literal representation.
+*
+* This function handles the serialization of various JavaScript types into
+* TypeScript code that can be embedded in generated namespace declarations.
+* It supports primitives, objects, arrays, dates, regex, and other common types.
+*
+* @param property - The ObjectProperty containing the value to embed
+* @returns String representation of the value for use in TypeScript code
+* @internal
+*/
 function embedPropertyValue(property) {
-  if (typeof property.value === "string") {
-    return escapeString(property.value);
-  }
-  if (Number.isNaN(property.value)) {
-    return "NaN";
-  }
-  if (typeof property.value === "number" && Number.isInteger(property.value)) {
-    return property.value.toString();
-  }
-  if (typeof property.value === "boolean") {
-    return property.value.toString();
-  }
-  if (Array.isArray(property.value) || typeof property.value === "object") {
-    return JSON.stringify(property.value);
-  }
-  if (property.value instanceof Date) {
-    return `new Date('${property.value.toISOString()}')`;
-  }
-  if (property.value instanceof RegExp) {
-    return `new RegExp(${escapeString(property.value.source)}, ${escapeString(property.value.flags)})`;
-  }
-  if (property.value === null) {
-    return "null";
-  }
-  if (property.value === void 0) {
-    return "undefined";
-  }
-  if (typeof property.value === "function") {
-    return "function() {}";
-  }
-  if (typeof property.value === "symbol") {
-    return "Symbol()";
-  }
-  if (typeof property.value === "bigint") {
-    return `${property.value}n`;
-  }
-  if (property.value instanceof Error) {
-    return `Error(${escapeString(property.value.message)})`;
-  }
-  if (property.value instanceof Map) {
-    return `new Map(${JSON.stringify(Array.from(property.value.entries()))})`;
-  }
-  if (property.value instanceof Set) {
-    return `new Set(${JSON.stringify(Array.from(property.value.values()))})`;
-  }
-  return "unknown";
+	if (typeof property.value === "string") return escapeString(property.value);
+	if (Number.isNaN(property.value)) return "NaN";
+	if (typeof property.value === "number" && Number.isInteger(property.value)) return property.value.toString();
+	if (typeof property.value === "boolean") return property.value.toString();
+	if (Array.isArray(property.value) || typeof property.value === "object") return JSON.stringify(property.value);
+	if (property.value instanceof Date) return `new Date('${property.value.toISOString()}')`;
+	if (property.value instanceof RegExp) return `new RegExp(${escapeString(property.value.source)}, ${escapeString(property.value.flags)})`;
+	if (property.value === null) return "null";
+	if (property.value === void 0) return "undefined";
+	if (typeof property.value === "function") return "function() {}";
+	if (typeof property.value === "symbol") return "Symbol()";
+	if (typeof property.value === "bigint") return `${property.value}n`;
+	if (property.value instanceof Error) return `Error(${escapeString(property.value.message)})`;
+	if (property.value instanceof Map) return `new Map(${JSON.stringify(Array.from(property.value.entries()))})`;
+	if (property.value instanceof Set) return `new Set(${JSON.stringify(Array.from(property.value.values()))})`;
+	return "unknown";
 }
-
-// src/citations.ts
-var RARE_SYMBOLS = {
-  ARROW_UP: "\u2191",
-  CIRCLE_BULLET: "\u30FB",
-  STAR_BULLET_FULL: "\u2605",
-  STAR_BULLET_EMPTY: "\u2606",
-  ARROW_BULLET: "\u2192",
-  SQUARE_BULLET: "\u25A0",
-  TRIANGLE_BULLET: "\u25BA",
-  OPENING_TAG: "\u3010",
-  CLOSING_TAG: "\u3011",
-  SS: "\xA7",
-  CROSS: "\u2020"
+//#endregion
+//#region src/citations.ts
+/** These are all single-token symbols that are very rare in natural texts, making them suitable for usage within GPT Prompts. */
+const RARE_SYMBOLS = {
+	ARROW_UP: "↑",
+	CIRCLE_BULLET: "・",
+	STAR_BULLET_FULL: "★",
+	STAR_BULLET_EMPTY: "☆",
+	ARROW_BULLET: "→",
+	SQUARE_BULLET: "■",
+	TRIANGLE_BULLET: "►",
+	OPENING_TAG: "【",
+	CLOSING_TAG: "】",
+	SS: "§",
+	CROSS: "†"
 };
 var CitationsManager = class {
-  _citations = /* @__PURE__ */ new Map();
-  _nextId = 0;
-  /**
-   * Registers a new source and returns the created Citation.
-   * @param source An object representing the source of the citation.
-   * @returns The created Citation.
-   */
-  registerSource(source) {
-    const id = this._nextId++;
-    const tag = `${RARE_SYMBOLS.OPENING_TAG}${id}${RARE_SYMBOLS.CLOSING_TAG}`;
-    const citation = {
-      id,
-      source,
-      tag
-    };
-    this._citations.set(id, citation);
-    return citation;
-  }
-  /**
-   * Extracts citations from the provided content and cleans the content of citation tags.
-   * Non-found citations are replaced with a special "Not Found" citation.
-   * @param content The string content containing citation tags.
-   * @returns An object containing the cleaned content and an array of found citations.
-   */
-  extractCitations(content, replace) {
-    const citations = [];
-    const notFoundCitation = {
-      id: -1,
-      source: "Not Found",
-      tag: ""
-    };
-    const regex = new RegExp(`${RARE_SYMBOLS.OPENING_TAG}([\\d|\\w|\\s|,]{0,})${RARE_SYMBOLS.CLOSING_TAG}`, "ig");
-    let match;
-    const offsets = [];
-    while ((match = regex.exec(content)) !== null) {
-      const offset = match.index;
-      const length = match[0].length;
-      offsets.push({ start: offset, length });
-      const multi = (match[1] ?? "").split(/\D/g).map((s) => s.trim()).filter(Boolean).map((s) => parseInt(s, 10)).filter((s) => !isNaN(s) && s >= 0);
-      for (const citationId of multi) {
-        const citation = this._citations.get(citationId);
-        if (citation) {
-          citations.push({ ...citation, offset });
-        } else {
-          citations.push({ ...notFoundCitation, offset });
-        }
-      }
-    }
-    const entries = offsets.map((o) => ({
-      start: o.start,
-      length: o.length,
-      citations: citations.filter((x) => x.offset === o.start && x.id !== -1)
-    })).sort((a, b) => a.start - b.start);
-    let result = "";
-    let cursor = 0;
-    for (const { start, length, citations: citations2 } of entries) {
-      result += content.slice(cursor, start);
-      const replacement = citations2.map((citation) => replace ? replace(citation) : "").join("");
-      result += replacement;
-      cursor = start + length;
-    }
-    result += content.slice(cursor);
-    return { cleaned: result, citations };
-  }
-  /**
-   * Strips citation tags from the provided content.
-   * @param content The string content containing citation tags.
-   * @returns The cleaned content without citation tags.
-   */
-  static stripCitationTags(content) {
-    const regex = new RegExp(`${RARE_SYMBOLS.OPENING_TAG}([\\d|\\w|\\s|,]{0,})${RARE_SYMBOLS.CLOSING_TAG}?`, "g");
-    return content.replace(regex, "");
-  }
-  /**
-   * Removes citations from a deeply nested plain object and returns a new object with citations removed.
-   * @param obj The plain object to process.
-   * @returns A tuple containing the new object and an array of extracted citations with paths.
-   */
-  removeCitationsFromObject(obj) {
-    const result = [];
-    const processObject = (current, path) => {
-      if (typeof current === "string") {
-        const extraction = this.extractCitations(current);
-        if (extraction.citations.length > 0) {
-          result.push(...extraction.citations.map((citation) => ({ path, citation })));
-        }
-        return extraction.cleaned;
-      } else if (typeof current === "object" && current !== null) {
-        const newObject = Array.isArray(current) ? [] : {};
-        for (const key of Object.keys(current)) {
-          newObject[key] = processObject(current[key], `${path}.${key}`);
-        }
-        return newObject;
-      }
-      return current;
-    };
-    const newObj = processObject(obj, "root");
-    return [newObj, result];
-  }
-  /**
-   * Re-adds citations to the cleaned content based on their offsets.
-   * @param cleaned The cleaned string without citation tags.
-   * @param citations The array of citations with offsets.
-   * @returns The string with citation tags re-added.
-   */
-  reAddCitations(cleaned, citations) {
-    let content = cleaned;
-    citations.sort((a, b) => (a.offset ?? 0) - (b.offset ?? 0));
-    const adjustment = 0;
-    for (const citation of citations) {
-      if (citation.offset != null) {
-        const position = citation.offset + adjustment;
-        content = content.slice(0, position) + citation.tag + content.slice(position);
-      }
-    }
-    return content;
-  }
+	_citations = /* @__PURE__ */ new Map();
+	_nextId = 0;
+	/**
+	* Registers a new source and returns the created Citation.
+	* @param source An object representing the source of the citation.
+	* @returns The created Citation.
+	*/
+	registerSource(source) {
+		const id = this._nextId++;
+		const citation = {
+			id,
+			source,
+			tag: `${RARE_SYMBOLS.OPENING_TAG}${id}${RARE_SYMBOLS.CLOSING_TAG}`
+		};
+		this._citations.set(id, citation);
+		return citation;
+	}
+	/**
+	* Extracts citations from the provided content and cleans the content of citation tags.
+	* Non-found citations are replaced with a special "Not Found" citation.
+	* @param content The string content containing citation tags.
+	* @returns An object containing the cleaned content and an array of found citations.
+	*/
+	extractCitations(content, replace) {
+		const citations = [];
+		const notFoundCitation = {
+			id: -1,
+			source: "Not Found",
+			tag: ""
+		};
+		const regex = new RegExp(`${RARE_SYMBOLS.OPENING_TAG}([\\d|\\w|\\s|,]{0,})${RARE_SYMBOLS.CLOSING_TAG}`, "ig");
+		let match;
+		const offsets = [];
+		while ((match = regex.exec(content)) !== null) {
+			const offset = match.index;
+			const length = match[0].length;
+			offsets.push({
+				start: offset,
+				length
+			});
+			const multi = (match[1] ?? "").split(/\D/g).map((s) => s.trim()).filter(Boolean).map((s) => parseInt(s, 10)).filter((s) => !isNaN(s) && s >= 0);
+			for (const citationId of multi) {
+				const citation = this._citations.get(citationId);
+				if (citation) citations.push({
+					...citation,
+					offset
+				});
+				else citations.push({
+					...notFoundCitation,
+					offset
+				});
+			}
+		}
+		const entries = offsets.map((o) => ({
+			start: o.start,
+			length: o.length,
+			citations: citations.filter((x) => x.offset === o.start && x.id !== -1)
+		})).sort((a, b) => a.start - b.start);
+		let result = "";
+		let cursor = 0;
+		for (const { start, length, citations } of entries) {
+			result += content.slice(cursor, start);
+			const replacement = citations.map((citation) => replace ? replace(citation) : "").join("");
+			result += replacement;
+			cursor = start + length;
+		}
+		result += content.slice(cursor);
+		return {
+			cleaned: result,
+			citations
+		};
+	}
+	/**
+	* Strips citation tags from the provided content.
+	* @param content The string content containing citation tags.
+	* @returns The cleaned content without citation tags.
+	*/
+	static stripCitationTags(content) {
+		const regex = new RegExp(`${RARE_SYMBOLS.OPENING_TAG}([\\d|\\w|\\s|,]{0,})${RARE_SYMBOLS.CLOSING_TAG}?`, "g");
+		return content.replace(regex, "");
+	}
+	/**
+	* Removes citations from a deeply nested plain object and returns a new object with citations removed.
+	* @param obj The plain object to process.
+	* @returns A tuple containing the new object and an array of extracted citations with paths.
+	*/
+	removeCitationsFromObject(obj) {
+		const result = [];
+		const processObject = (current, path) => {
+			if (typeof current === "string") {
+				const extraction = this.extractCitations(current);
+				if (extraction.citations.length > 0) result.push(...extraction.citations.map((citation) => ({
+					path,
+					citation
+				})));
+				return extraction.cleaned;
+			} else if (typeof current === "object" && current !== null) {
+				const newObject = Array.isArray(current) ? [] : {};
+				for (const key of Object.keys(current)) newObject[key] = processObject(current[key], `${path}.${key}`);
+				return newObject;
+			}
+			return current;
+		};
+		return [processObject(obj, "root"), result];
+	}
+	/**
+	* Re-adds citations to the cleaned content based on their offsets.
+	* @param cleaned The cleaned string without citation tags.
+	* @param citations The array of citations with offsets.
+	* @returns The string with citation tags re-added.
+	*/
+	reAddCitations(cleaned, citations) {
+		let content = cleaned;
+		citations.sort((a, b) => (a.offset ?? 0) - (b.offset ?? 0));
+		const adjustment = 0;
+		for (const citation of citations) if (citation.offset != null) {
+			const position = citation.offset + adjustment;
+			content = content.slice(0, position) + citation.tag + content.slice(position);
+		}
+		return content;
+	}
 };
-
-// src/component.default.ts
-import { z as z2 } from "@bpinternal/zui";
-var Button = new Component({
-  type: "leaf",
-  description: "A button component that can perform actions when clicked",
-  name: "Button",
-  aliases: ["btn"],
-  generation: {
-    usage: "Attach quick actions to a message, e.g. postback choices or a URL to open.",
-    examples: [{ props: { action: "postback", label: "Buy", value: "buy_product" } }]
-  },
-  leaf: {
-    props: z2.object({
-      action: z2.enum(["say", "url", "postback"]).default("say").describe('The action to perform when the button is clicked. Can be "say", "url", or "postback"'),
-      label: z2.string().describe("The text displayed on the button (min 1 character, max 250 characters)"),
-      value: z2.string().optional().describe('The postback value to send when the button is clicked. Required if action is "postback"'),
-      url: z2.string().optional().describe('The URL to open when the button is clicked. Required if action is "url"')
-    })
-  }
-});
-var Image = new Component({
-  type: "leaf",
-  name: "Image",
-  description: "Displays an image from a URL.",
-  aliases: [],
-  generation: {
-    examples: [{ props: { url: "https://example.com/photo.jpg", alt: "Example image" } }]
-  },
-  leaf: {
-    props: z2.object({
-      url: z2.string().describe("The URL of the image (must be valid)"),
-      alt: z2.string().optional().describe("Alternative text describing the image")
-    })
-  }
+//#endregion
+//#region src/component.default.ts
+const Button = new Component({
+	type: "leaf",
+	description: "A button component that can perform actions when clicked",
+	name: "Button",
+	aliases: ["btn"],
+	generation: {
+		usage: "Attach quick actions to a message, e.g. postback choices or a URL to open.",
+		examples: [{ props: {
+			action: "postback",
+			label: "Buy",
+			value: "buy_product"
+		} }]
+	},
+	leaf: { props: z.object({
+		action: z.enum([
+			"say",
+			"url",
+			"postback"
+		]).default("say").describe("The action to perform when the button is clicked. Can be \"say\", \"url\", or \"postback\""),
+		label: z.string().describe("The text displayed on the button (min 1 character, max 250 characters)"),
+		value: z.string().optional().describe("The postback value to send when the button is clicked. Required if action is \"postback\""),
+		url: z.string().optional().describe("The URL to open when the button is clicked. Required if action is \"url\"")
+	}) }
 });
-var File = new Component({
-  type: "leaf",
-  name: "File",
-  description: "Sends a downloadable file to the user.",
-  aliases: [],
-  generation: {
-    examples: [{ props: { url: "https://example.com/report.pdf", name: "Report.pdf" } }]
-  },
-  leaf: {
-    props: z2.object({
-      url: z2.string().describe("The URL of the file (must be valid)"),
-      name: z2.string().optional().describe("The display name of the file")
-    })
-  }
+const Image = new Component({
+	type: "leaf",
+	name: "Image",
+	description: "Displays an image from a URL.",
+	aliases: [],
+	generation: { examples: [{ props: {
+		url: "https://example.com/photo.jpg",
+		alt: "Example image"
+	} }] },
+	leaf: { props: z.object({
+		url: z.string().describe("The URL of the image (must be valid)"),
+		alt: z.string().optional().describe("Alternative text describing the image")
+	}) }
 });
-var Video = new Component({
-  type: "leaf",
-  name: "Video",
-  description: "Embeds a video from a URL.",
-  aliases: [],
-  generation: {
-    examples: [{ props: { url: "https://example.com/intro.mp4", title: "Welcome" } }]
-  },
-  leaf: {
-    props: z2.object({
-      url: z2.string().describe("The URL of the video (must be valid)"),
-      title: z2.string().optional().describe("Title for the video")
-    })
-  }
+const File = new Component({
+	type: "leaf",
+	name: "File",
+	description: "Sends a downloadable file to the user.",
+	aliases: [],
+	generation: { examples: [{ props: {
+		url: "https://example.com/report.pdf",
+		name: "Report.pdf"
+	} }] },
+	leaf: { props: z.object({
+		url: z.string().describe("The URL of the file (must be valid)"),
+		name: z.string().optional().describe("The display name of the file")
+	}) }
 });
-var Audio = new Component({
-  type: "leaf",
-  name: "Audio",
-  description: "Plays an audio clip from a URL.",
-  aliases: [],
-  generation: {
-    examples: [{ props: { url: "https://example.com/audio.mp3", title: "Sample" } }]
-  },
-  leaf: {
-    props: z2.object({
-      url: z2.string().describe("The URL of the audio clip (must be valid)"),
-      title: z2.string().optional().describe("Title for the audio clip")
-    })
-  }
+const Video = new Component({
+	type: "leaf",
+	name: "Video",
+	description: "Embeds a video from a URL.",
+	aliases: [],
+	generation: { examples: [{ props: {
+		url: "https://example.com/intro.mp4",
+		title: "Welcome"
+	} }] },
+	leaf: { props: z.object({
+		url: z.string().describe("The URL of the video (must be valid)"),
+		title: z.string().optional().describe("Title for the video")
+	}) }
 });
-var Card = new Component({
-  type: "container",
-  name: "Card",
-  description: "A visual card component that can include an image and buttons.",
-  aliases: [],
-  generation: {
-    examples: [{ props: { title: "Product Name", subtitle: "Limited offer" }, body: "Featured product of the week." }]
-  },
-  container: {
-    props: z2.object({
-      title: z2.string().min(1).max(250).describe("Title text (1\u2013250 characters)"),
-      subtitle: z2.string().optional().describe("Optional subtitle for the card")
-    }),
-    children: [
-      {
-        description: "Image (optional, max 1)",
-        component: Image.definition
-      },
-      {
-        description: "Button (optional, up to 5)",
-        component: Button.definition
-      }
-    ]
-  }
+const Audio = new Component({
+	type: "leaf",
+	name: "Audio",
+	description: "Plays an audio clip from a URL.",
+	aliases: [],
+	generation: { examples: [{ props: {
+		url: "https://example.com/audio.mp3",
+		title: "Sample"
+	} }] },
+	leaf: { props: z.object({
+		url: z.string().describe("The URL of the audio clip (must be valid)"),
+		title: z.string().optional().describe("Title for the audio clip")
+	}) }
 });
-var Carousel = new Component({
-  type: "container",
-  name: "Carousel",
-  description: "A virtual container for displaying 1 to 10 Card components as a carousel.",
-  aliases: [],
-  container: {
-    props: z2.object({}),
-    children: [
-      {
-        description: "Card component (required, 1\u201310 allowed)",
-        component: Card.definition
-      }
-    ]
-  }
+const Card = new Component({
+	type: "container",
+	name: "Card",
+	description: "A visual card component that can include an image and buttons.",
+	aliases: [],
+	generation: { examples: [{
+		props: {
+			title: "Product Name",
+			subtitle: "Limited offer"
+		},
+		body: "Featured product of the week."
+	}] },
+	container: {
+		props: z.object({
+			title: z.string().min(1).max(250).describe("Title text (1–250 characters)"),
+			subtitle: z.string().optional().describe("Optional subtitle for the card")
+		}),
+		children: [{
+			description: "Image (optional, max 1)",
+			component: Image.definition
+		}, {
+			description: "Button (optional, up to 5)",
+			component: Button.definition
+		}]
+	}
 });
-var Text = new Component({
-  type: "default",
-  name: "Message",
-  aliases: ["Text", "Markdown"],
-  description: "A Markdown-formatted text message. Long answers are written the same way: plain Markdown prose.",
-  generation: {
-    examples: [
-      // A long-form example matters: models shown only short bodies have been
-      // observed drifting into JSON-wrapping long replies ({"body": "..."})
-      {
-        body: `Great question! Deploying happens in three steps.
+const DefaultComponents = {
+	Button,
+	Image,
+	File,
+	Video,
+	Audio,
+	Card,
+	Carousel: new Component({
+		type: "container",
+		name: "Carousel",
+		description: "A virtual container for displaying 1 to 10 Card components as a carousel.",
+		aliases: [],
+		container: {
+			props: z.object({}),
+			children: [{
+				description: "Card component (required, 1–10 allowed)",
+				component: Card.definition
+			}]
+		}
+	}),
+	Text: new Component({
+		type: "default",
+		name: "Message",
+		aliases: ["Text", "Markdown"],
+		description: "A Markdown-formatted text message. Long answers are written the same way: plain Markdown prose.",
+		generation: { examples: [{ body: `Great question! Deploying happens in three steps.
 
-First, connect your repository from the dashboard \u2014 we support GitHub and GitLab. Once connected, every push to your main branch triggers a build automatically.
+First, connect your repository from the dashboard — we support GitHub and GitLab. Once connected, every push to your main branch triggers a build automatically.
 
 Then configure your build settings:
 
-- **Build command** \u2014 usually \`npm run build\`
-- **Output directory** \u2014 where the compiled assets end up
+- **Build command** — usually \`npm run build\`
+- **Output directory** — where the compiled assets end up
 
-Finally, hit **Deploy**. The first build takes a couple of minutes; subsequent ones are incremental and much faster. Want me to walk you through connecting your repository?`
-      },
-      { body: "**Hello**, welcome to our service!" }
-    ]
-  },
-  default: {
-    props: z2.object({}),
-    children: []
-  }
-});
-var Speech = new Component({
-  type: "default",
-  name: "Speech",
-  aliases: ["speak", "spoken"],
-  description: "A message spoken aloud to the user via text-to-speech.",
-  body: {
-    format: "text",
-    description: 'Plain conversational prose only, written to be read aloud: no Markdown, no links or URLs, no emojis, no code, no bullet points, tables or headings. Write everything the way it should be pronounced \u2014 spell out numbers, dates, units and abbreviations (e.g. "June third at three thirty PM", not "06/03 @ 3:30pm").'
-  },
-  generation: {
-    usage: "Use when the reply will be played back as audio (voice conversations).",
-    examples: [
-      { body: "Sure! Your order shipped this morning and should arrive on Tuesday, June third, around noon." }
-    ]
-  },
-  default: {
-    props: z2.object({}),
-    children: []
-  }
-});
-var DefaultComponents = {
-  Button,
-  Image,
-  File,
-  Video,
-  Audio,
-  Card,
-  Carousel,
-  Text,
-  Speech
+Finally, hit **Deploy**. The first build takes a couple of minutes; subsequent ones are incremental and much faster. Want me to walk you through connecting your repository?` }, { body: "**Hello**, welcome to our service!" }] },
+		default: {
+			props: z.object({}),
+			children: []
+		}
+	}),
+	Speech: new Component({
+		type: "default",
+		name: "Speech",
+		aliases: ["speak", "spoken"],
+		description: "A message spoken aloud to the user via text-to-speech.",
+		body: {
+			format: "text",
+			description: "Plain conversational prose only, written to be read aloud: no Markdown, no links or URLs, no emojis, no code, no bullet points, tables or headings. Write everything the way it should be pronounced — spell out numbers, dates, units and abbreviations (e.g. \"June third at three thirty PM\", not \"06/03 @ 3:30pm\")."
+		},
+		generation: {
+			usage: "Use when the reply will be played back as audio (voice conversations).",
+			examples: [{ body: "Sure! Your order shipped this morning and should arrive on Tuesday, June third, around noon." }]
+		},
+		default: {
+			props: z.object({}),
+			children: []
+		}
+	})
 };
-
-// src/chat.ts
+//#endregion
+//#region src/chat.ts
+/**
+* Base class for implementing chat interfaces in LLMz agents.
+*
+* The Chat class provides the foundation for interactive conversational agents by defining
+* how agents communicate with users. It manages the conversation transcript, available UI
+* components, and message handling. This is the bridge between the agent's generated code
+* and your user interface.
+*
+* ## Key Concepts
+*
+* **Handler Function**: The core method that receives agent messages (rendered components)
+* and displays them to the user. This is called every time the agent wants to communicate.
+*
+* **Transcript**: An up-to-date conversation history that is evaluated at each iteration.
+* The transcript must reflect the complete conversation state as the agent uses it to
+* understand context and generate appropriate responses.
+*
+* **Components**: The UI elements available to the agent for creating rich interactive
+* experiences (text, buttons, images, cards, etc.).
+*
+* ## Implementation Requirements
+*
+* To create a functional chat interface, you must:
+* 1. Implement the MessageHandler to display agent messages to users
+* 2. Maintain an accurate transcript of the conversation
+* 3. Provide the available UI components (typically includes DefaultComponents)
+* 4. Optional: Override onExecutionDone() to handle execution completion
+*
+* ## Basic Implementation
+*
+* ```typescript
+* import { Chat, DefaultComponents, isComponent } from 'llmz'
+*
+* class MyChat extends Chat {
+*   private messages: Array<{role: 'user' | 'assistant', content: string}> = []
+*
+*   constructor() {
+*     super({
+*       // Handle agent messages - this is called for every agent output
+*       handler: async (input) => {
+*         if (isComponent(input, DefaultComponents.Text)) {
+*           const text = input.children.join('')
+*           console.log('Agent:', text)
+*           this.messages.push({ role: 'assistant', content: text })
+*         } else if (isComponent(input, DefaultComponents.Button)) {
+*           console.log('Button:', input.props.label)
+*         }
+*       },
+*
+*       // Provide available components - agent can use these in generated code
+*       components: [DefaultComponents.Text, DefaultComponents.Button],
+*
+*       // Return current transcript - evaluated at each iteration
+*       transcript: () => this.messages,
+*     })
+*   }
+*
+*   // Add user message to transcript
+*   addUserMessage(content: string) {
+*     this.messages.push({ role: 'user', content })
+*   }
+* }
+*
+* // Usage
+* const chat = new MyChat()
+* chat.addUserMessage('Hello!')
+*
+* const result = await execute({
+*   instructions: 'You are a helpful assistant',
+*   chat, // Enable chat mode
+*   client,
+* })
+* ```
+*
+* ## Advanced Implementation (CLIChat Example)
+*
+* ```typescript
+* import { Chat, DefaultComponents, ListenExit } from 'llmz'
+*
+* class CLIChat extends Chat {
+*   public transcript: Array<{role: 'user' | 'assistant', content: string}> = []
+*   private buttons: string[] = []
+*   public result?: ExecutionResult
+*
+*   constructor() {
+*     super({
+*       // Dynamic component list with custom renderers
+*       components: () => [
+*         DefaultComponents.Text,
+*         DefaultComponents.Button,
+*         ...this.customComponents
+*       ],
+*
+*       // Dynamic transcript access
+*       transcript: () => this.transcript,
+*
+*       // Sophisticated message handling
+*       handler: async (input) => {
+*         if (isComponent(input, DefaultComponents.Text)) {
+*           const text = input.children.join('')
+*           console.log('🤖 Agent:', text)
+*           this.transcript.push({ role: 'assistant', content: text })
+*         } else if (isComponent(input, DefaultComponents.Button)) {
+*           this.buttons.push(input.props.label)
+*         }
+*       },
+*     })
+*   }
+*
+*   // Handle execution completion
+*   onExecutionDone(result: ExecutionResult) {
+*     this.result = result
+*   }
+*
+*   // Check if agent is waiting for user input
+*   isWaitingForInput(): boolean {
+*     return this.result?.is(ListenExit) ?? false
+*   }
+*
+*   // Conversation loop
+*   async iterate(): Promise<boolean> {
+*     if (this.isWaitingForInput()) {
+*       const userInput = await this.promptUser()
+*       this.transcript.push({ role: 'user', content: userInput })
+*       return true // Continue conversation
+*     }
+*     return false // End conversation
+*   }
+* }
+* ```
+*
+* ## Component System
+*
+* The agent generates JSX code using available components:
+*
+* ```typescript
+* // Agent generates this TSX code:
+* yield <Text>Welcome! Choose an option:</Text>
+* yield <Button action="postback" label="Get Help" value="help" />
+* yield <Button action="postback" label="Contact Sales" value="sales" />
+*
+* // Your handler receives these as RenderedComponent objects
+* ```
+*
+* ## Transcript Management
+*
+* The transcript is critical for agent context and must be kept up-to-date:
+*
+* ```typescript
+* // ❌ Bad - static transcript
+* transcript: [{ role: 'user', content: 'Hello' }]
+*
+* // ✅ Good - dynamic transcript that reflects current state
+* transcript: () => this.messages
+*
+* // The transcript is evaluated at each iteration, so the agent
+* // always sees the current conversation state
+* ```
+*
+* ## Custom Components
+*
+* Extend the UI with custom components for your specific use case:
+*
+* ```typescript
+* import { Component } from 'llmz'
+*
+* const ProductCard = new Component({
+*   type: 'leaf',
+*   name: 'ProductCard',
+*   leaf: {
+*     props: z.object({
+*       name: z.string(),
+*       price: z.number(),
+*       imageUrl: z.string(),
+*     })
+*   }
+* })
+*
+* class ShoppingChat extends Chat {
+*   constructor() {
+*     super({
+*       components: [
+*         ...DefaultComponents,
+*         ProductCard, // Add custom component
+*       ],
+*       handler: async (input) => {
+*         if (isComponent(input, ProductCard)) {
+*           // Handle custom component rendering
+*           this.renderProduct(input.props)
+*         }
+*         // ... handle other components
+*       },
+*     })
+*   }
+* }
+* ```
+*
+* @see {@link DefaultComponents} For standard UI components
+* @see {@link https://github.com/botpress/botpress/blob/master/packages/llmz/examples/utils/cli-chat.ts} Complete CLIChat implementation
+*/
 var Chat = class {
-  handler;
-  onMessageDelta;
-  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.onMessageDelta = props.onMessageDelta;
-    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) {
-  }
+	handler;
+	onMessageDelta;
+	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.onMessageDelta = props.onMessageDelta;
+		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/message-stream/replayable.ts
+//#endregion
+//#region src/message-stream/replayable.ts
+/**
+* Wraps an async iterable so it can be iterated multiple times: chunks pulled
+* from the source are cached, and every iteration replays the cache before
+* pulling new chunks. Concurrent iterations are safe — pulls on the underlying
+* source are serialized. If the source fails, the failure is cached too:
+* every iteration replays the chunks received before the failure, then
+* rethrows the source error.
+*/
 var ReplayableAsyncIterable = class {
-  _source;
-  _chunks = [];
-  _done = false;
-  _failed = false;
-  _error;
-  _lock = Promise.resolve();
-  constructor(source) {
-    this._source = source[Symbol.asyncIterator]();
-  }
-  /** True once the underlying source has been fully consumed (or has failed). */
-  get done() {
-    return this._done;
-  }
-  /** The chunks pulled from the source so far. */
-  get chunks() {
-    return [...this._chunks];
-  }
-  async *[Symbol.asyncIterator]() {
-    let index = 0;
-    while (true) {
-      if (index < this._chunks.length) {
-        yield this._chunks[index++];
-      } else if (this._failed) {
-        throw this._error;
-      } else if (this._done) {
-        return;
-      } else {
-        await this._pull();
-      }
-    }
-  }
-  /** Consumes the entire source and returns all chunks. */
-  async collect() {
-    for await (const _ of this) {
-    }
-    return this.chunks;
-  }
-  _pull() {
-    const next = this._lock.then(async () => {
-      if (this._done) {
-        return;
-      }
-      let result;
-      try {
-        result = await this._source.next();
-      } catch (thrown) {
-        this._done = true;
-        this._failed = true;
-        this._error = thrown;
-        throw thrown;
-      }
-      if (result.done) {
-        this._done = true;
-      } else {
-        this._chunks.push(result.value);
-      }
-    });
-    this._lock = next.catch(() => {
-    });
-    return next;
-  }
+	_source;
+	_chunks = [];
+	_done = false;
+	_failed = false;
+	_error;
+	_lock = Promise.resolve();
+	constructor(source) {
+		this._source = source[Symbol.asyncIterator]();
+	}
+	/** True once the underlying source has been fully consumed (or has failed). */
+	get done() {
+		return this._done;
+	}
+	/** The chunks pulled from the source so far. */
+	get chunks() {
+		return [...this._chunks];
+	}
+	async *[Symbol.asyncIterator]() {
+		let index = 0;
+		while (true) if (index < this._chunks.length) yield this._chunks[index++];
+		else if (this._failed) throw this._error;
+		else if (this._done) return;
+		else await this._pull();
+	}
+	/** Consumes the entire source and returns all chunks. */
+	async collect() {
+		for await (const _ of this);
+		return this.chunks;
+	}
+	_pull() {
+		const next = this._lock.then(async () => {
+			if (this._done) return;
+			let result;
+			try {
+				result = await this._source.next();
+			} catch (thrown) {
+				this._done = true;
+				this._failed = true;
+				this._error = thrown;
+				throw thrown;
+			}
+			if (result.done) this._done = true;
+			else this._chunks.push(result.value);
+		});
+		this._lock = next.catch(() => {});
+		return next;
+	}
 };
-var collectText = async (iterable) => {
-  let text = "";
-  for await (const chunk of iterable) {
-    text += chunk;
-  }
-  return text;
+/** Drains a string iterable into a single string. */
+const collectText = async (iterable) => {
+	let text = "";
+	for await (const chunk of iterable) text += chunk;
+	return text;
 };
-
-// src/message-stream/stream.ts
+//#endregion
+//#region src/message-stream/stream.ts
 var BaseResponse = class {
-  constructor(action, item) {
-    this.action = action;
-    this.item = item;
-  }
-  get diagnostics() {
-    return this.item.diagnostics;
-  }
+	action;
+	item;
+	constructor(action, item) {
+		this.action = action;
+		this.item = item;
+	}
+	get diagnostics() {
+		return this.item.diagnostics;
+	}
 };
+/** `■send=<component> { props? }` followed by an optional streaming body. */
 var SendResponse = class extends BaseResponse {
-  constructor(item, content) {
-    super("send", item);
-    this.content = content;
-  }
-  get component() {
-    return this.item.name;
-  }
-  get props() {
-    return this.item.props;
-  }
-  static formatToText(component, props, body) {
-    const header = `${MARKER}send=${component}${props && Object.keys(props).length ? ` ${JSON.stringify(props)}` : ""}`;
-    return body ? `${header}
-${body}` : header;
-  }
+	content;
+	constructor(item, content) {
+		super("send", item);
+		this.content = content;
+	}
+	get component() {
+		return this.item.name;
+	}
+	get props() {
+		return this.item.props;
+	}
+	static formatToText(component, props, body) {
+		const header = `■send=${component}${props && Object.keys(props).length ? ` ${JSON.stringify(props)}` : ""}`;
+		return body ? `${header}\n${body}` : header;
+	}
 };
+/** `■run` followed by streaming code. */
 var RunResponse = class extends BaseResponse {
-  constructor(item, code) {
-    super("run", item);
-    this.code = code;
-  }
-  static formatToText(code) {
-    return `${MARKER}run
-${code}`;
-  }
+	code;
+	constructor(item, code) {
+		super("run", item);
+		this.code = code;
+	}
+	static formatToText(code) {
+		return `■run\n${code}`;
+	}
 };
+/** `■next=<name> { props? }` — hands control to an exit (e.g. listen) with optional props. */
 var NextResponse = class extends BaseResponse {
-  constructor(item) {
-    super("next", item);
-  }
-  get name() {
-    return this.item.name;
-  }
-  get props() {
-    return this.item.props;
-  }
-  static formatToText(name, props) {
-    return `${MARKER}next=${name}${props && Object.keys(props).length ? ` ${JSON.stringify(props)}` : ""}`;
-  }
+	constructor(item) {
+		super("next", item);
+	}
+	get name() {
+		return this.item.name;
+	}
+	get props() {
+		return this.item.props;
+	}
+	static formatToText(name, props) {
+		return `■next=${name}${props && Object.keys(props).length ? ` ${JSON.stringify(props)}` : ""}`;
+	}
 };
+/**
+* Pulls transport chunks through the parser on demand and hands out events one
+* at a time. Shared by the main response loop and by body streams; pulls are
+* serialized so interleaved consumers cannot race the source iterator.
+*/
 var EventPump = class {
-  _iterator;
-  _parser;
-  _queue = [];
-  _sourceDone = false;
-  _lock = Promise.resolve();
-  constructor(stream, parser) {
-    this._iterator = stream[Symbol.asyncIterator]();
-    this._parser = parser;
-  }
-  next() {
-    const next = this._lock.then(() => this._next());
-    this._lock = next.catch(() => {
-    });
-    return next;
-  }
-  unshift(event) {
-    this._queue.unshift(event);
-  }
-  async _next() {
-    while (this._queue.length === 0) {
-      if (this._sourceDone) {
-        return void 0;
-      }
-      let result;
-      try {
-        result = await this._iterator.next();
-      } catch {
-        this._sourceDone = true;
-        this._queue.push(...this._parser.finish("interrupted"));
-        continue;
-      }
-      if (result.done) {
-        this._sourceDone = true;
-        this._queue.push(...this._parser.finish());
-      } else {
-        this._queue.push(...this._parser.push(result.value));
-      }
-    }
-    return this._queue.shift();
-  }
+	_iterator;
+	_parser;
+	_queue = [];
+	_sourceDone = false;
+	_lock = Promise.resolve();
+	constructor(stream, parser) {
+		this._iterator = stream[Symbol.asyncIterator]();
+		this._parser = parser;
+	}
+	next() {
+		const next = this._lock.then(() => this._next());
+		this._lock = next.catch(() => {});
+		return next;
+	}
+	unshift(event) {
+		this._queue.unshift(event);
+	}
+	async _next() {
+		while (this._queue.length === 0) {
+			if (this._sourceDone) return;
+			let result;
+			try {
+				result = await this._iterator.next();
+			} catch {
+				this._sourceDone = true;
+				this._queue.push(...this._parser.finish("interrupted"));
+				continue;
+			}
+			if (result.done) {
+				this._sourceDone = true;
+				this._queue.push(...this._parser.finish());
+			} else this._queue.push(...this._parser.push(result.value));
+		}
+		return this._queue.shift();
+	}
 };
+/**
+* Parses a raw LLM text stream into typed responses.
+*
+* `send` and `run` responses are yielded as soon as their header is parsed —
+* while their body is still streaming — with the body exposed as a replayable
+* async iterable. `next` responses are yielded once complete.
+*
+* The body streams are pull-based: consuming them drives the underlying
+* transport. Requesting the next response first drains the previous body into
+* its replay cache, so it can always be read later.
+*/
 function parseStream(stream, options) {
-  return parseResponses(stream, options);
+	return parseResponses(stream, options);
 }
+/** Parses a complete text (convenience wrapper over {@link parseStream}). */
 function parseText(text, options) {
-  return parseResponses(
-    async function* () {
-      yield text;
-    }(),
-    options
-  );
+	return parseResponses((async function* () {
+		yield text;
+	})(), options);
 }
 async function* parseResponses(stream, options) {
-  const parser = new StreamingMessageParser(options);
-  const pump = new EventPump(stream, parser);
-  let activeBody;
-  while (true) {
-    if (activeBody) {
-      await activeBody.collect();
-      activeBody = void 0;
-    }
-    const event = await pump.next();
-    if (!event) {
-      return;
-    }
-    if (event.type === "item-ready" && (event.item.kind === "send" || event.item.kind === "run")) {
-      const body = new ReplayableAsyncIterable(bodyStream(pump, event.item.id));
-      activeBody = body;
-      yield event.item.kind === "send" ? new SendResponse(event.item, body) : new RunResponse(event.item, body);
-      continue;
-    }
-    if (event.type === "item-complete" && event.item.kind === "next") {
-      yield new NextResponse(event.item);
-      continue;
-    }
-  }
+	const pump = new EventPump(stream, new StreamingMessageParser(options));
+	let activeBody;
+	while (true) {
+		if (activeBody) {
+			await activeBody.collect();
+			activeBody = void 0;
+		}
+		const event = await pump.next();
+		if (!event) return;
+		if (event.type === "item-ready" && (event.item.kind === "send" || event.item.kind === "run")) {
+			const body = new ReplayableAsyncIterable(bodyStream(pump, event.item.id));
+			activeBody = body;
+			yield event.item.kind === "send" ? new SendResponse(event.item, body) : new RunResponse(event.item, body);
+			continue;
+		}
+		if (event.type === "item-complete" && event.item.kind === "next") {
+			yield new NextResponse(event.item);
+			continue;
+		}
+	}
 }
 async function* bodyStream(pump, itemId) {
-  while (true) {
-    const event = await pump.next();
-    if (!event) {
-      return;
-    }
-    if (event.type === "body-delta" && event.itemId === itemId) {
-      yield event.delta;
-      continue;
-    }
-    if (event.type === "body-start" && event.itemId === itemId) {
-      continue;
-    }
-    if (event.type === "diagnostic") {
-      continue;
-    }
-    if (event.type === "item-complete" && event.item.id === itemId) {
-      return;
-    }
-    pump.unshift(event);
-    return;
-  }
+	while (true) {
+		const event = await pump.next();
+		if (!event) return;
+		if (event.type === "body-delta" && event.itemId === itemId) {
+			yield event.delta;
+			continue;
+		}
+		if (event.type === "body-start" && event.itemId === itemId) continue;
+		if (event.type === "diagnostic") continue;
+		if (event.type === "item-complete" && event.item.id === itemId) return;
+		pump.unshift(event);
+		return;
+	}
 }
-
-// src/message-stream/registry.ts
+//#endregion
+//#region src/message-stream/registry.ts
+/**
+* Stores normalized component definitions. The registry (not the parser) is the
+* single source of truth for which components exist and how they are validated.
+*/
 var ComponentRegistry = class {
-  _definitions = /* @__PURE__ */ new Map();
-  constructor(definitions = []) {
-    for (const definition of definitions) {
-      this.register(definition);
-    }
-  }
-  register(definition) {
-    if (!NAME_REGEX.test(definition.name)) {
-      throw new Error(
-        `Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`
-      );
-    }
-    this._definitions.set(definition.name, definition);
-  }
-  unregister(name) {
-    this._definitions.delete(name);
-  }
-  has(name) {
-    return this._definitions.has(name);
-  }
-  get(name) {
-    return this._definitions.get(name);
-  }
-  list() {
-    return [...this._definitions.values()];
-  }
+	_definitions = /* @__PURE__ */ new Map();
+	constructor(definitions = []) {
+		for (const definition of definitions) this.register(definition);
+	}
+	register(definition) {
+		if (!NAME_REGEX.test(definition.name)) throw new Error(`Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`);
+		this._definitions.set(definition.name, definition);
+	}
+	unregister(name) {
+		this._definitions.delete(name);
+	}
+	has(name) {
+		return this._definitions.has(name);
+	}
+	get(name) {
+		return this._definitions.get(name);
+	}
+	list() {
+		return [...this._definitions.values()];
+	}
 };
-
-// src/message-stream/normalizer.ts
-import { transforms } from "@bpinternal/zui";
-var EMPTY_PROPS_SCHEMA = { type: "object", properties: {}, additionalProperties: false };
-var normalizeComponentName = (name) => name.trim().toLowerCase();
+//#endregion
+//#region src/message-stream/normalizer.ts
+const EMPTY_PROPS_SCHEMA = {
+	type: "object",
+	properties: {},
+	additionalProperties: false
+};
+const normalizeComponentName = (name) => name.trim().toLowerCase();
 function normalizeComponentDefinition(definition) {
-  const name = normalizeComponentName(definition.name ?? "");
-  if (!NAME_REGEX.test(name)) {
-    throw new Error(
-      `Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`
-    );
-  }
-  return {
-    name,
-    description: definition.description,
-    propsJsonSchema: normalizePropsSchema(definition.props, name),
-    body: definition.body ? {
-      format: definition.body.type,
-      description: definition.body.description,
-      required: definition.body.required ?? false
-    } : void 0,
-    generation: definition.generation
-  };
+	const name = normalizeComponentName(definition.name ?? "");
+	if (!NAME_REGEX.test(name)) throw new Error(`Invalid component name "${definition.name}". Component names must be lowercase ([a-z][a-z0-9_-]*).`);
+	return {
+		name,
+		description: definition.description,
+		propsJsonSchema: normalizePropsSchema(definition.props, name),
+		body: definition.body ? {
+			format: definition.body.type,
+			description: definition.body.description,
+			required: definition.body.required ?? false
+		} : void 0,
+		generation: definition.generation
+	};
 }
 function normalizePropsSchema(props, name) {
-  if (props === void 0) {
-    return EMPTY_PROPS_SCHEMA;
-  }
-  if (isZuiSchema(props)) {
-    try {
-      return transforms.toJSONSchema(props);
-    } catch {
-      return transforms.toJSONSchemaLegacy(props);
-    }
-  }
-  if (isJsonSchema(props)) {
-    return props;
-  }
-  throw new Error(
-    `Invalid props schema for "${name}". Expected a ZUI/Zod object schema or a JSON schema, but got type "${typeof props}".`
-  );
+	if (props === void 0) return EMPTY_PROPS_SCHEMA;
+	if (isZuiSchema(props)) try {
+		return transforms.toJSONSchema(props);
+	} catch {
+		return transforms.toJSONSchemaLegacy(props);
+	}
+	if (isJsonSchema(props)) return props;
+	throw new Error(`Invalid props schema for "${name}". Expected a ZUI/Zod object schema or a JSON schema, but got type "${typeof props}".`);
 }
-
-// src/message-stream/validator.ts
+//#endregion
+//#region src/message-stream/validator.ts
+/**
+* Validates a syntactically parsed `■send` item against the registered
+* component definitions. Validation is intentionally separate from parsing: a
+* validation failure never stops the stream, it only produces errors the caller
+* can turn into diagnostics or fallback rendering.
+*/
 function validateComponent(item, registry) {
-  const definition = registry.get(item.name);
-  if (!definition) {
-    const registered = registry.list().map((d) => d.name).join(", ") || "(none)";
-    return {
-      valid: false,
-      props: item.props,
-      errors: [
-        {
-          code: "unknown-component",
-          message: `Unknown component "${item.name}". Registered components: ${registered}`
-        }
-      ]
-    };
-  }
-  const errors = [
-    ..._validateProps(item.props, definition),
-    ..._validateBody(item, definition)
-  ];
-  return { valid: errors.length === 0, props: item.props, errors };
+	const definition = registry.get(item.name);
+	if (!definition) {
+		const registered = registry.list().map((d) => d.name).join(", ") || "(none)";
+		return {
+			valid: false,
+			props: item.props,
+			errors: [{
+				code: "unknown-component",
+				message: `Unknown component "${item.name}". Registered components: ${registered}`
+			}]
+		};
+	}
+	const errors = [..._validateProps(item.props, definition), ..._validateBody(item, definition)];
+	return {
+		valid: errors.length === 0,
+		props: item.props,
+		errors
+	};
 }
+/** Validates a props object against a JSON schema (also used for `■next` exit props). */
 function validateProps(props, schema) {
-  const errors = [];
-  _checkValue(props, schema, "", errors);
-  return errors;
+	const errors = [];
+	_checkValue(props, schema, "", errors);
+	return errors;
 }
-var _validateProps = (props, definition) => validateProps(props, definition.propsJsonSchema);
-var _validateBody = (item, definition) => {
-  var _a;
-  const hasBody = typeof item.body === "string" && item.body.length > 0;
-  if (hasBody && !definition.body) {
-    return [
-      {
-        code: "body-not-allowed",
-        message: `Component "${definition.name}" does not support a body`
-      }
-    ];
-  }
-  if (!hasBody && ((_a = definition.body) == null ? void 0 : _a.required)) {
-    return [
-      {
-        code: "missing-required-body",
-        message: `Component "${definition.name}" requires a body`
-      }
-    ];
-  }
-  return [];
-};
-var _typeOf = (value) => {
-  if (value === null)
-    return "null";
-  if (Array.isArray(value))
-    return "array";
-  return typeof value;
+const _validateProps = (props, definition) => validateProps(props, definition.propsJsonSchema);
+const _validateBody = (item, definition) => {
+	var _definition$body;
+	const hasBody = typeof item.body === "string" && item.body.length > 0;
+	if (hasBody && !definition.body) return [{
+		code: "body-not-allowed",
+		message: `Component "${definition.name}" does not support a body`
+	}];
+	if (!hasBody && ((_definition$body = definition.body) === null || _definition$body === void 0 ? void 0 : _definition$body.required)) return [{
+		code: "missing-required-body",
+		message: `Component "${definition.name}" requires a body`
+	}];
+	return [];
 };
-var _matchesType = (value, type) => {
-  switch (type) {
-    case "string":
-      return typeof value === "string";
-    case "number":
-      return typeof value === "number";
-    case "integer":
-      return typeof value === "number" && Number.isInteger(value);
-    case "boolean":
-      return typeof value === "boolean";
-    case "null":
-      return value === null;
-    case "array":
-      return Array.isArray(value);
-    case "object":
-      return !!value && typeof value === "object" && !Array.isArray(value);
-    default:
-      return true;
-  }
+const _typeOf = (value) => {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
 };
-var _isEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-var _checkValue = (value, schema, path, errors) => {
-  if (schema === void 0 || typeof schema === "boolean" || typeof schema !== "object") {
-    return;
-  }
-  const label = path || "props";
-  const propError = (message) => {
-    errors.push({ code: "invalid-prop-value", message, path: path || void 0 });
-  };
-  if (schema.const !== void 0 && !_isEqual(value, schema.const)) {
-    propError(`Expected "${label}" to equal ${JSON.stringify(schema.const)}`);
-    return;
-  }
-  if (schema.enum && !schema.enum.some((allowed) => _isEqual(value, allowed))) {
-    propError(`Expected "${label}" to be one of: ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`);
-    return;
-  }
-  const variants = schema.anyOf ?? schema.oneOf;
-  if (variants == null ? void 0 : variants.length) {
-    const matchesAny = variants.some((variant) => {
-      const variantErrors = [];
-      _checkValue(value, variant, path, variantErrors);
-      return variantErrors.length === 0;
-    });
-    if (!matchesAny) {
-      propError(`Value of "${label}" does not match any of the allowed types`);
-      return;
-    }
-  }
-  if (schema.type) {
-    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
-    if (!types.some((type) => _matchesType(value, type))) {
-      propError(`Expected "${label}" to be of type ${types.join(" | ")}, but got ${_typeOf(value)}`);
-      return;
-    }
-  }
-  if (Array.isArray(value) && schema.items && !Array.isArray(schema.items)) {
-    value.forEach((item, index) => _checkValue(item, schema.items, `${label}[${index}]`, errors));
-  }
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    const record = value;
-    const properties = schema.properties ?? {};
-    for (const requiredKey of schema.required ?? []) {
-      if (record[requiredKey] === void 0) {
-        errors.push({
-          code: "missing-required-prop",
-          message: `Missing required prop "${path ? `${path}.` : ""}${requiredKey}"`,
-          path: path ? `${path}.${requiredKey}` : requiredKey
-        });
-      }
-    }
-    for (const [key, propValue] of Object.entries(record)) {
-      const propSchema = properties[key];
-      const propPath = path ? `${path}.${key}` : key;
-      if (propSchema === void 0) {
-        if (schema.additionalProperties === false) {
-          errors.push({
-            code: "unexpected-prop",
-            message: `Unexpected prop "${propPath}"`,
-            path: propPath
-          });
-        }
-        continue;
-      }
-      _checkValue(propValue, propSchema, propPath, errors);
-    }
-  }
+const _matchesType = (value, type) => {
+	switch (type) {
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number";
+		case "integer": return typeof value === "number" && Number.isInteger(value);
+		case "boolean": return typeof value === "boolean";
+		case "null": return value === null;
+		case "array": return Array.isArray(value);
+		case "object": return !!value && typeof value === "object" && !Array.isArray(value);
+		default: return true;
+	}
 };
-
-// src/message-stream/sanitize.ts
-var sanitizeMessageText = (value, options = {}) => value.replaceAll(MARKER, options.markerReplacement ?? "\u25AA");
-
-// src/index.ts
-var utils = {
-  toValidObjectName,
-  toValidFunctionName,
-  wrapContent,
-  truncateWrappedContent,
-  stripTruncationTags
+const _isEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+* Minimal JSON-schema subset checker covering what component schemas need:
+* type, enum, const, required, properties, additionalProperties, items, anyOf/oneOf.
+* Unknown keywords are ignored (lenient by design).
+*/
+const _checkValue = (value, schema, path, errors) => {
+	if (schema === void 0 || typeof schema === "boolean" || typeof schema !== "object") return;
+	const label = path || "props";
+	const propError = (message) => {
+		errors.push({
+			code: "invalid-prop-value",
+			message,
+			path: path || void 0
+		});
+	};
+	if (schema.const !== void 0 && !_isEqual(value, schema.const)) {
+		propError(`Expected "${label}" to equal ${JSON.stringify(schema.const)}`);
+		return;
+	}
+	if (schema.enum && !schema.enum.some((allowed) => _isEqual(value, allowed))) {
+		propError(`Expected "${label}" to be one of: ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}`);
+		return;
+	}
+	const variants = schema.anyOf ?? schema.oneOf;
+	if (variants === null || variants === void 0 ? void 0 : variants.length) {
+		if (!variants.some((variant) => {
+			const variantErrors = [];
+			_checkValue(value, variant, path, variantErrors);
+			return variantErrors.length === 0;
+		})) {
+			propError(`Value of "${label}" does not match any of the allowed types`);
+			return;
+		}
+	}
+	if (schema.type) {
+		const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+		if (!types.some((type) => _matchesType(value, type))) {
+			propError(`Expected "${label}" to be of type ${types.join(" | ")}, but got ${_typeOf(value)}`);
+			return;
+		}
+	}
+	if (Array.isArray(value) && schema.items && !Array.isArray(schema.items)) value.forEach((item, index) => _checkValue(item, schema.items, `${label}[${index}]`, errors));
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const record = value;
+		const properties = schema.properties ?? {};
+		for (const requiredKey of schema.required ?? []) if (record[requiredKey] === void 0) errors.push({
+			code: "missing-required-prop",
+			message: `Missing required prop "${path ? `${path}.` : ""}${requiredKey}"`,
+			path: path ? `${path}.${requiredKey}` : requiredKey
+		});
+		for (const [key, propValue] of Object.entries(record)) {
+			const propSchema = properties[key];
+			const propPath = path ? `${path}.${key}` : key;
+			if (propSchema === void 0) {
+				if (schema.additionalProperties === false) errors.push({
+					code: "unexpected-prop",
+					message: `Unexpected prop "${propPath}"`,
+					path: propPath
+				});
+				continue;
+			}
+			_checkValue(propValue, propSchema, propPath, errors);
+		}
+	}
 };
-var execute = async (props) => {
-  const { executeContext } = await import("./execute-FF7D46TY.js");
-  return executeContext(props);
+//#endregion
+//#region src/message-stream/sanitize.ts
+/**
+* The protocol has no escaping mechanism by design. Any untrusted text that is
+* inserted into model context (user messages, tool results, documents) must be
+* sanitized so it cannot inject protocol blocks.
+*/
+const sanitizeMessageText = (value, options = {}) => value.replaceAll("■", options.markerReplacement ?? "▪");
+//#endregion
+//#region src/index.ts
+const utils = {
+	toValidObjectName,
+	toValidFunctionName,
+	wrapContent,
+	truncateWrappedContent,
+	stripTruncationTags
 };
-var init = async () => {
-  await import("./execute-FF7D46TY.js");
-  await import("./component-ASNZHQUR.js");
-  await import("./tool-KD7FL45V.js");
-  await import("./exit-UQ3EUX5D.js");
-  await import("./jsx-DDZ63UUF.js");
-  await import("./vm-QO5FSGPN.js");
-  await import("./utils-IATCUNKF.js");
-  await import("./truncator-73RCL52Y.js");
-  await import("./typings-E2RROCLT.js");
-  await import("./dual-modes-S5TJ5JVJ.js");
+/**
+* Executes an LLMz agent in either Chat Mode or Worker Mode.
+*
+* LLMz is a code-first AI agent framework that generates and runs TypeScript code
+* in a sandbox rather than using traditional JSON tool calling. This enables complex
+* logic, multi-tool orchestration, and native LLM thinking via comments and code structure.
+*
+* @param props - Configuration object for the execution
+* @param props.client - Botpress Client or Cognitive Client instance for LLM generation
+* @param props.instructions - System prompt/instructions for the LLM (static string or dynamic function)
+* @param props.chat - Optional Chat instance to enable Chat Mode with user interaction
+* @param props.tools - Array of Tool instances available to the agent (static or dynamic)
+* @param props.objects - Array of ObjectInstance for namespaced tools and variables (static or dynamic)
+* @param props.exits - Array of Exit definitions for structured completion (static or dynamic)
+* @param props.snapshot - Optional Snapshot to resume paused execution
+* @param props.signal - Optional AbortSignal to cancel execution
+* @param props.model - Optional model name (or array or models to use as fallback) (static or dynamic function)
+* @param props.temperature - Optional temperature value (static or dynamic function)
+* @param props.metadata - Optional metadata attached to cognitive usage records for each LLM call
+* @param props.options - Optional execution options (loop limit, timeout, maxTokens context cap)
+* @param props.onTrace - Optional non-blocking hook for monitoring traces during execution
+* @param props.onIterationEnd - Optional blocking hook called after each iteration
+* @param props.onExit - Optional blocking hook called when an exit is reached (can prevent exit)
+* @param props.onBeforeExecution - Optional blocking hook to modify code before VM execution
+* @param props.onBeforeTool - Optional blocking hook to modify tool inputs before execution
+* @param props.onAfterTool - Optional blocking hook to modify tool outputs after execution
+*
+* @returns Promise<ExecutionResult> - Result containing success/error/interrupted status with type-safe exit checking
+*
+* @example
+* // Worker Mode - Automated execution
+* const result = await execute({
+*   client: cognitiveClient,
+*   instructions: 'Calculate the sum of numbers 1 to 100',
+*   exits: [myExit]
+* })
+*
+* if (result.is(myExit)) {
+*   console.log('Result:', result.output)
+* }
+*
+* @example
+* // Chat Mode - Interactive conversation
+* const result = await execute({
+*   client: cognitiveClient,
+*   instructions: 'You are a helpful assistant',
+*   chat: myChatInstance,
+*   tools: [searchTool, calculatorTool]
+* })
+*
+* if (result.is(ListenExit)) {
+*   // Agent is waiting for user input
+* }
+*
+* @example
+* // With dynamic instructions and hooks
+* const result = await execute({
+*   client: cognitiveClient,
+*   instructions: (ctx) => `Process ${ctx.variables.dataCount} records`,
+*   tools: async (ctx) => await getContextualTools(ctx),
+*   model: 'best',
+*   temperature: 0.1,
+*   options: { loop: 10 },
+*   onTrace: ({ trace, iteration }) => console.log(trace),
+*   onExit: async (result) => await validateResult(result)
+* })
+*/
+const execute = async (props) => {
+	const { executeContext } = await import("./execute-DYvFRs54.js");
+	return executeContext(props);
 };
-export {
-  BaseResponse,
-  Chat,
-  CitationsManager,
-  Component,
-  ComponentRegistry,
-  DefaultComponents,
-  DefaultExit,
-  ErrorExecutionResult,
-  ExecutionResult,
-  Exit,
-  ListenExit,
-  LoopExceededError,
-  MARKER,
-  NAME_REGEX,
-  NextResponse,
-  ObjectInstance,
-  PartialExecutionResult,
-  ReplayableAsyncIterable,
-  RunResponse,
-  SendResponse,
-  Snapshot,
-  SnapshotSignal,
-  StreamingMessageParser,
-  SuccessExecutionResult,
-  ThinkExit,
-  ThinkSignal,
-  Tool,
-  _CustomModelClient,
-  assertValidComponent,
-  collectText,
-  configureQuickJS,
-  configureTokenizer,
-  execute,
-  generateInstructions,
-  getValue,
-  init,
-  isAnyComponent,
-  isComponent,
-  normalizeComponentDefinition,
-  normalizeComponentName,
-  normalizePropsSchema,
-  parseExit,
-  parseStream,
-  parseText,
-  sanitizeMessageText,
-  tryParseJson,
-  utils,
-  validateComponent,
-  validateProps,
-  version
+/**
+* Loads the necessary dependencies for the library to work
+* Calling this function is optional, but it will improve the performance of the first call to `executeContext`
+* It's recommended to call this function at the beginning of your application without awaiting it (void init())
+*/
+const init = async () => {
+	await import("./execute-DYvFRs54.js");
+	await import("./component-DGG7d_Mz.js").then((n) => n.r);
+	await import("./tool-CAo-BQHs.js").then((n) => n.n);
+	await import("./exit-CDdxDBRT.js").then((n) => n.n);
+	await import("./jsx-CIgdGGVs.js").then((n) => n.i);
+	await import("./vm-C5vf1LH3.js");
+	await import("./utils-UBeAFeEI.js").then((n) => n.h);
+	await import("./truncator-DZqEqnpD.js").then((n) => n.r);
+	await import("./typings-CrBa7Tyy.js").then((n) => n.n);
+	await import("./dual-modes-D_p-jedw.js").then((n) => n.n);
 };
+//#endregion
+export { BaseResponse, Chat, CitationsManager, Component, ComponentRegistry, DefaultComponents, DefaultExit, ErrorExecutionResult, ExecutionResult, Exit, ListenExit, LoopExceededError, MARKER, NAME_REGEX, NextResponse, ObjectInstance, PartialExecutionResult, ReplayableAsyncIterable, RunResponse, SendResponse, Snapshot, SnapshotSignal, StreamingMessageParser, SuccessExecutionResult, ThinkExit, ThinkSignal, Tool, _CustomModelClient, assertValidComponent, collectText, configureQuickJS, configureTokenizer, execute, generateInstructions, getValue, init, isAnyComponent, isComponent, normalizeComponentDefinition, normalizeComponentName, normalizePropsSchema, parseExit, parseStream, parseText, sanitizeMessageText, tryParseJson, utils, validateComponent, validateProps, version };