@dudousxd/nestjs-agent-core 0.25.0 → 0.27.0

package/dist/genui/index.cjs

@@ -0,0 +1,1225 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/genui/index.ts
+var genui_exports = {};
+__export(genui_exports, {
+  COMPONENT_NAME: () => COMPONENT_NAME,
+  GENUI_SHOW_TOOL: () => GENUI_SHOW_TOOL,
+  GENUI_TREE_COMPONENT: () => GENUI_TREE_COMPONENT,
+  ajvValidator: () => ajvValidator,
+  builtinJsonSchemaValidator: () => builtinJsonSchemaValidator,
+  catalogToModelText: () => catalogToModelText,
+  componentToText: () => componentToText,
+  defineCatalog: () => defineCatalog,
+  defineComponent: () => defineComponent,
+  fillTemplate: () => fillTemplate,
+  formatIssues: () => formatIssues,
+  genuiTools: () => genuiTools,
+  getPath: () => getPath,
+  isStandardSchema: () => isStandardSchema,
+  jsonStandardSchema: () => jsonStandardSchema,
+  showToolJsonSchema: () => showToolJsonSchema,
+  summarizeSchema: () => summarizeSchema,
+  toJsonSchema: () => toJsonSchema,
+  toSnakeCase: () => toSnakeCase,
+  toolNameFor: () => toolNameFor,
+  treeJsonSchema: () => treeJsonSchema,
+  treeToFlatSpec: () => treeToFlatSpec,
+  treeToText: () => treeToText,
+  validateProps: () => validateProps,
+  validatePropsSync: () => validatePropsSync,
+  validateTree: () => validateTree
+});
+module.exports = __toCommonJS(genui_exports);
+
+// src/genui/schema.ts
+function isStandardSchema(schema) {
+  return typeof schema === "object" && schema !== null && "~standard" in schema && typeof schema["~standard"]?.validate === "function";
+}
+__name(isStandardSchema, "isStandardSchema");
+function toJsonSchema(schema) {
+  if (!isStandardSchema(schema)) {
+    return schema;
+  }
+  const standard = schema["~standard"];
+  const converter = standard.jsonSchema;
+  if (converter === void 0 || typeof converter.input !== "function") {
+    return void 0;
+  }
+  try {
+    return converter.input({
+      target: "draft-07"
+    });
+  } catch {
+    return void 0;
+  }
+}
+__name(toJsonSchema, "toJsonSchema");
+async function validateProps(schema, value, validator) {
+  if (isStandardSchema(schema)) {
+    const result = await schema["~standard"].validate(value);
+    if (result.issues !== void 0) {
+      return {
+        ok: false,
+        issues: toGenuiIssues(result.issues)
+      };
+    }
+    return {
+      ok: true,
+      value: result.value
+    };
+  }
+  const issues = validator.validate(schema, value);
+  return issues.length > 0 ? {
+    ok: false,
+    issues
+  } : {
+    ok: true,
+    value
+  };
+}
+__name(validateProps, "validateProps");
+function validatePropsSync(schema, value, validator) {
+  if (!isStandardSchema(schema)) {
+    const issues = validator.validate(schema, value);
+    return issues.length > 0 ? {
+      ok: false,
+      issues
+    } : {
+      ok: true,
+      value
+    };
+  }
+  const result = schema["~standard"].validate(value);
+  if (result instanceof Promise) {
+    result.catch(() => void 0);
+    return void 0;
+  }
+  return result.issues !== void 0 ? {
+    ok: false,
+    issues: toGenuiIssues(result.issues)
+  } : {
+    ok: true,
+    value: result.value
+  };
+}
+__name(validatePropsSync, "validatePropsSync");
+function toGenuiIssues(issues) {
+  return issues.map((issue) => ({
+    path: (issue.path ?? []).map((segment) => typeof segment === "object" && segment !== null && "key" in segment ? segment.key : segment),
+    message: issue.message
+  }));
+}
+__name(toGenuiIssues, "toGenuiIssues");
+function formatIssues(issues) {
+  return issues.map((issue) => `${issue.path.length > 0 ? formatPath(issue.path) : "(root)"}: ${issue.message}`).join("; ");
+}
+__name(formatIssues, "formatIssues");
+function formatPath(path) {
+  return path.map((segment, index) => typeof segment === "number" ? `[${segment}]` : index === 0 ? segment : `.${segment}`).join("");
+}
+__name(formatPath, "formatPath");
+function ajvValidator(ajv) {
+  const compiled = /* @__PURE__ */ new WeakMap();
+  return {
+    validate(schema, value) {
+      let fn = compiled.get(schema);
+      if (fn === void 0) {
+        fn = ajv.compile(schema);
+        compiled.set(schema, fn);
+      }
+      if (fn(value) === true) {
+        return [];
+      }
+      return (fn.errors ?? []).map((error) => ({
+        path: (error.instancePath ?? "").split("/").filter((segment) => segment.length > 0).map((segment) => {
+          const decoded = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+          return /^\d+$/.test(decoded) ? Number(decoded) : decoded;
+        }),
+        message: error.message ?? "is invalid"
+      }));
+    }
+  };
+}
+__name(ajvValidator, "ajvValidator");
+var builtinJsonSchemaValidator = {
+  validate(schema, value) {
+    const issues = [];
+    check(schema, value, [], schema, issues, 0);
+    return issues;
+  }
+};
+var MAX_DEPTH = 64;
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+__name(typeOf, "typeOf");
+function matchesType(type, value) {
+  switch (type) {
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    default:
+      return typeOf(value) === type;
+  }
+}
+__name(matchesType, "matchesType");
+function resolveRef(root, ref) {
+  if (ref === "#") return root;
+  if (!ref.startsWith("#/")) return void 0;
+  let current = root;
+  for (const raw of ref.slice(2).split("/")) {
+    const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (typeof current !== "object" || current === null) return void 0;
+    current = current[key];
+  }
+  return typeof current === "object" && current !== null ? current : void 0;
+}
+__name(resolveRef, "resolveRef");
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((key) => deepEqual(a[key], b[key]));
+}
+__name(deepEqual, "deepEqual");
+function check(schema, value, path, root, issues, depth) {
+  if (schema === true || schema === void 0) return;
+  if (schema === false) {
+    issues.push({
+      path,
+      message: "is not allowed"
+    });
+    return;
+  }
+  if (typeof schema !== "object" || schema === null) return;
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      path,
+      message: "is nested too deeply"
+    });
+    return;
+  }
+  const s = schema;
+  if (typeof s.$ref === "string") {
+    const target = resolveRef(root, s.$ref);
+    if (target === void 0) {
+      issues.push({
+        path,
+        message: `references unknown schema ${s.$ref}`
+      });
+      return;
+    }
+    check(target, value, path, root, issues, depth + 1);
+  }
+  if (s.type !== void 0) {
+    const types = Array.isArray(s.type) ? s.type : [
+      s.type
+    ];
+    if (!types.some((type) => matchesType(type, value))) {
+      issues.push({
+        path,
+        message: `must be ${types.join(" or ")}`
+      });
+      return;
+    }
+  }
+  if (Array.isArray(s.enum) && !s.enum.some((option) => deepEqual(option, value))) {
+    issues.push({
+      path,
+      message: `must be one of ${s.enum.map((option) => JSON.stringify(option)).join(", ")}`
+    });
+  }
+  if ("const" in s && !deepEqual(s.const, value)) {
+    issues.push({
+      path,
+      message: `must be ${JSON.stringify(s.const)}`
+    });
+  }
+  if (typeof value === "string") {
+    if (typeof s.minLength === "number" && value.length < s.minLength) {
+      issues.push({
+        path,
+        message: `must be at least ${s.minLength} characters`
+      });
+    }
+    if (typeof s.maxLength === "number" && value.length > s.maxLength) {
+      issues.push({
+        path,
+        message: `must be at most ${s.maxLength} characters`
+      });
+    }
+    if (typeof s.pattern === "string") {
+      let pattern;
+      try {
+        pattern = new RegExp(s.pattern, "u");
+      } catch {
+        pattern = void 0;
+      }
+      if (pattern !== void 0 && !pattern.test(value)) {
+        issues.push({
+          path,
+          message: `must match ${s.pattern}`
+        });
+      }
+    }
+  }
+  if (typeof value === "number") {
+    if (typeof s.minimum === "number" && value < s.minimum) {
+      issues.push({
+        path,
+        message: `must be >= ${s.minimum}`
+      });
+    }
+    if (typeof s.maximum === "number" && value > s.maximum) {
+      issues.push({
+        path,
+        message: `must be <= ${s.maximum}`
+      });
+    }
+  }
+  if (Array.isArray(value)) {
+    if (typeof s.minItems === "number" && value.length < s.minItems) {
+      issues.push({
+        path,
+        message: `must have at least ${s.minItems} items`
+      });
+    }
+    if (typeof s.maxItems === "number" && value.length > s.maxItems) {
+      issues.push({
+        path,
+        message: `must have at most ${s.maxItems} items`
+      });
+    }
+    if (s.items !== void 0 && !Array.isArray(s.items)) {
+      value.forEach((item, index) => {
+        check(s.items, item, [
+          ...path,
+          index
+        ], root, issues, depth + 1);
+      });
+    }
+  }
+  if (matchesType("object", value)) {
+    const record = value;
+    const properties = typeof s.properties === "object" && s.properties !== null ? s.properties : {};
+    if (Array.isArray(s.required)) {
+      for (const key of s.required) {
+        if (record[key] === void 0) {
+          issues.push({
+            path: [
+              ...path,
+              key
+            ],
+            message: "is required"
+          });
+        }
+      }
+    }
+    for (const [key, entry] of Object.entries(record)) {
+      if (key in properties) {
+        if (entry !== void 0) {
+          check(properties[key], entry, [
+            ...path,
+            key
+          ], root, issues, depth + 1);
+        }
+      } else if (s.additionalProperties === false) {
+        issues.push({
+          path: [
+            ...path,
+            key
+          ],
+          message: "is not a known property"
+        });
+      } else if (typeof s.additionalProperties === "object" && s.additionalProperties !== null) {
+        check(s.additionalProperties, entry, [
+          ...path,
+          key
+        ], root, issues, depth + 1);
+      }
+    }
+  }
+  if (Array.isArray(s.allOf)) {
+    for (const sub of s.allOf) check(sub, value, path, root, issues, depth + 1);
+  }
+  if (Array.isArray(s.anyOf) || Array.isArray(s.oneOf)) {
+    const options = Array.isArray(s.anyOf) ? s.anyOf : s.oneOf;
+    const passing = options.filter((sub) => {
+      const nested = [];
+      check(sub, value, path, root, nested, depth + 1);
+      return nested.length === 0;
+    }).length;
+    if (Array.isArray(s.anyOf) ? passing === 0 : passing !== 1) {
+      issues.push({
+        path,
+        message: Array.isArray(s.anyOf) ? "does not match any allowed shape" : "must match exactly one allowed shape"
+      });
+    }
+  }
+  if (s.not !== void 0) {
+    const nested = [];
+    check(s.not, value, path, root, nested, depth + 1);
+    if (nested.length === 0) {
+      issues.push({
+        path,
+        message: "matches a shape that is not allowed"
+      });
+    }
+  }
+}
+__name(check, "check");
+
+// src/genui/catalog.ts
+var COMPONENT_NAME = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
+function defineComponent(definition) {
+  if (!COMPONENT_NAME.test(definition.name)) {
+    throw new Error(`genui: component name "${definition.name}" must be letters and digits, starting with a letter (e.g. DataTable)`);
+  }
+  return definition;
+}
+__name(defineComponent, "defineComponent");
+function defineCatalog(components, options = {}) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const component of components) {
+    defineComponent(component);
+    if (byName.has(component.name)) {
+      throw new Error(`genui: component "${component.name}" is defined twice in one catalog`);
+    }
+    byName.set(component.name, component);
+  }
+  return buildCatalog(byName, options.jsonSchemaValidator ?? builtinJsonSchemaValidator);
+}
+__name(defineCatalog, "defineCatalog");
+function buildCatalog(byName, validator) {
+  const list = Object.freeze([
+    ...byName.values()
+  ]);
+  return {
+    components: list,
+    validator,
+    get: /* @__PURE__ */ __name((name) => byName.get(name), "get"),
+    has: /* @__PURE__ */ __name((name) => byName.has(name), "has"),
+    modelComponents: /* @__PURE__ */ __name(() => list.filter((component) => component.internal !== true), "modelComponents"),
+    async validate(component, props) {
+      const definition = byName.get(component);
+      if (definition === void 0) {
+        return {
+          ok: false,
+          issues: [
+            {
+              path: [],
+              message: `unknown component "${component}"`
+            }
+          ]
+        };
+      }
+      const result = await validateProps(definition.props, props, validator);
+      return result;
+    },
+    validateSync(component, props) {
+      const definition = byName.get(component);
+      if (definition === void 0) {
+        return {
+          ok: false,
+          issues: [
+            {
+              path: [],
+              message: `unknown component "${component}"`
+            }
+          ]
+        };
+      }
+      return validatePropsSync(definition.props, props, validator);
+    },
+    jsonSchemaFor(component) {
+      const definition = byName.get(component);
+      return definition === void 0 ? void 0 : toJsonSchema(definition.props);
+    },
+    extend(more) {
+      const next = new Map(byName);
+      for (const component of more) {
+        defineComponent(component);
+        next.set(component.name, component);
+      }
+      return buildCatalog(next, validator);
+    }
+  };
+}
+__name(buildCatalog, "buildCatalog");
+function toSnakeCase(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/[^a-zA-Z0-9]+/g, "_").toLowerCase();
+}
+__name(toSnakeCase, "toSnakeCase");
+function toolNameFor(component, prefix = "ui__show_") {
+  return `${prefix}${toSnakeCase(component)}`;
+}
+__name(toolNameFor, "toolNameFor");
+
+// src/genui/tree.ts
+var GENUI_TREE_COMPONENT = "genui:tree";
+async function validateTree(catalog, tree, limits = {}) {
+  const maxDepth = limits.maxDepth ?? 12;
+  const maxNodes = limits.maxNodes ?? 200;
+  const issues = [];
+  let nodes = 0;
+  const visit = /* @__PURE__ */ __name(async (node, path, depth) => {
+    nodes += 1;
+    if (nodes > maxNodes) {
+      if (nodes === maxNodes + 1) {
+        issues.push({
+          path,
+          message: `the tree has more than ${maxNodes} elements`
+        });
+      }
+      return void 0;
+    }
+    if (depth > maxDepth) {
+      issues.push({
+        path,
+        message: `the tree is nested deeper than ${maxDepth} levels`
+      });
+      return void 0;
+    }
+    if (typeof node !== "object" || node === null || Array.isArray(node)) {
+      issues.push({
+        path,
+        message: "must be an element object { type, props, children? }"
+      });
+      return void 0;
+    }
+    const element = node;
+    if (typeof element.type !== "string") {
+      issues.push({
+        path: [
+          ...path,
+          "type"
+        ],
+        message: "must be a component name"
+      });
+      return void 0;
+    }
+    const definition = catalog.get(element.type);
+    if (definition === void 0 || definition.internal === true) {
+      issues.push({
+        path: [
+          ...path,
+          "type"
+        ],
+        message: `unknown component "${element.type}" (allowed: ${catalog.modelComponents().map((component) => component.name).join(", ")})`
+      });
+      return void 0;
+    }
+    const validated = await catalog.validate(element.type, element.props ?? {});
+    let props = {};
+    if (!validated.ok) {
+      for (const issue of validated.issues) {
+        issues.push({
+          path: [
+            ...path,
+            "props",
+            ...issue.path
+          ],
+          message: issue.message
+        });
+      }
+    } else {
+      props = validated.value;
+    }
+    const rawChildren = parseChildrenIfStringified(element.children);
+    if (rawChildren === void 0 || rawChildren === null) {
+      return {
+        type: element.type,
+        props
+      };
+    }
+    if (!Array.isArray(rawChildren)) {
+      issues.push({
+        path: [
+          ...path,
+          "children"
+        ],
+        message: "must be an array of elements (a literal array, not a string)"
+      });
+      return void 0;
+    }
+    if (rawChildren.length > 0 && definition.children !== true) {
+      issues.push({
+        path: [
+          ...path,
+          "children"
+        ],
+        message: `${element.type} does not take children`
+      });
+      return void 0;
+    }
+    const children = [];
+    for (const [index, child] of rawChildren.entries()) {
+      const next = await visit(child, [
+        ...path,
+        "children",
+        index
+      ], depth + 1);
+      if (next !== void 0) {
+        children.push(next);
+      }
+    }
+    return children.length > 0 ? {
+      type: element.type,
+      props,
+      children
+    } : {
+      type: element.type,
+      props
+    };
+  }, "visit");
+  const root = await visit(tree, [], 1);
+  return issues.length > 0 || root === void 0 ? {
+    ok: false,
+    issues: issues.length > 0 ? issues : [
+      {
+        path: [],
+        message: "is invalid"
+      }
+    ]
+  } : {
+    ok: true,
+    value: root
+  };
+}
+__name(validateTree, "validateTree");
+function treeJsonSchema(catalog) {
+  return {
+    type: "object",
+    properties: {
+      type: {
+        type: "string",
+        enum: catalog.modelComponents().map((component) => component.name),
+        description: "Component name from the catalog"
+      },
+      props: {
+        type: "object",
+        description: "The component's props, as the catalog describes them"
+      },
+      children: {
+        type: "array",
+        items: {
+          $ref: "#"
+        },
+        description: "Nested elements, only for components that take children. A literal JSON array, never a JSON-stringified one."
+      }
+    },
+    required: [
+      "type",
+      "props"
+    ]
+  };
+}
+__name(treeJsonSchema, "treeJsonSchema");
+function treeToFlatSpec(root) {
+  const elements = {};
+  let next = 0;
+  const visit = /* @__PURE__ */ __name((node) => {
+    const id = `el-${next++}`;
+    const entry = {
+      type: node.type,
+      props: node.props,
+      children: []
+    };
+    elements[id] = entry;
+    for (const child of node.children ?? []) {
+      entry.children.push(visit(child));
+    }
+    return id;
+  }, "visit");
+  return {
+    root: visit(root),
+    elements
+  };
+}
+__name(treeToFlatSpec, "treeToFlatSpec");
+function parseChildrenIfStringified(value) {
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("[")) return value;
+  return leadingJsonArray(trimmed) ?? value;
+}
+__name(parseChildrenIfStringified, "parseChildrenIfStringified");
+function leadingJsonArray(text) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') inString = true;
+    else if (char === "[" || char === "{") depth += 1;
+    else if (char === "]" || char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        try {
+          const parsed = JSON.parse(text.slice(0, index + 1));
+          return Array.isArray(parsed) ? parsed : void 0;
+        } catch {
+          return void 0;
+        }
+      }
+    }
+  }
+  return void 0;
+}
+__name(leadingJsonArray, "leadingJsonArray");
+
+// src/genui/text.ts
+function componentToText(catalog, component, props) {
+  if (component === GENUI_TREE_COMPONENT) {
+    const root = props.root;
+    return root === void 0 ? "" : treeToText(catalog, root);
+  }
+  const fallback = catalog.get(component)?.fallbackText;
+  if (fallback !== void 0) {
+    try {
+      return fallback(props);
+    } catch {
+    }
+  }
+  return jsonBlock(props);
+}
+__name(componentToText, "componentToText");
+function treeToText(catalog, root) {
+  const out = [];
+  const visit = /* @__PURE__ */ __name((node, depth) => {
+    if (depth > 32) return;
+    const definition = catalog.get(node.type);
+    if (definition?.fallbackText !== void 0) {
+      try {
+        out.push(definition.fallbackText(node.props));
+      } catch {
+        out.push(jsonBlock(node.props));
+      }
+    } else if (definition?.children !== true) {
+      out.push(jsonBlock(node.props));
+    }
+    for (const child of node.children ?? []) visit(child, depth + 1);
+  }, "visit");
+  visit(root, 0);
+  return out.filter((line) => line.trim().length > 0).join("\n");
+}
+__name(treeToText, "treeToText");
+function jsonBlock(props) {
+  const title = typeof props.title === "string" && props.title.length > 0 ? `*${props.title}*
+` : "";
+  return `${title}\`\`\`
+${JSON.stringify(props, null, 2).slice(0, 2500)}
+\`\`\``;
+}
+__name(jsonBlock, "jsonBlock");
+function catalogToModelText(catalog, options = {}) {
+  const mode = options.mode ?? "tree";
+  const lines = [];
+  if (mode === "tree") {
+    lines.push('Compose the UI as ONE tree of elements: { "type": <component>, "props": { \u2026 }, "children"?: [ \u2026 ] }.', 'Only components marked "takes children" accept children; `children` is a literal JSON array, never a string.', "Components:");
+  } else if (mode === "show") {
+    lines.push('Pass { "component": <name>, "props": { \u2026 } } with one of these components:');
+  } else {
+    lines.push("Components you can show (one tool each):");
+  }
+  for (const component of catalog.modelComponents()) {
+    const schema = catalog.jsonSchemaFor(component.name);
+    const head = mode === "per-component" ? `- ${component.name} (tool \`${toolNameFor(component.name, options.namePrefix)}\`)` : `- ${component.name}`;
+    lines.push(`${head}: ${component.description}`);
+    if (schema !== void 0) {
+      lines.push(`  props: ${summarizeSchema(schema, schema, 0)}`);
+    }
+    if (mode === "tree" && component.children === true) {
+      lines.push("  takes children");
+    }
+  }
+  return lines.join("\n");
+}
+__name(catalogToModelText, "catalogToModelText");
+function summarizeSchema(schema, root, depth) {
+  if (typeof schema !== "object" || schema === null) return "unknown";
+  const s = schema;
+  if (depth > 5) return "\u2026";
+  if (typeof s.$ref === "string") {
+    return s.$ref === "#" ? "Self" : s.$ref.split("/").pop() ?? "unknown";
+  }
+  if (Array.isArray(s.enum)) {
+    return s.enum.map((option) => JSON.stringify(option)).join(" | ");
+  }
+  if ("const" in s) return JSON.stringify(s.const);
+  const variants = s.anyOf ?? s.oneOf;
+  if (Array.isArray(variants)) {
+    return variants.map((variant) => summarizeSchema(variant, root, depth + 1)).join(" | ");
+  }
+  const types = Array.isArray(s.type) ? s.type : s.type !== void 0 ? [
+    s.type
+  ] : [];
+  if (types.length > 1) {
+    return types.map((type2) => summarizeSchema({
+      ...s,
+      type: type2
+    }, root, depth + 1)).join(" | ");
+  }
+  const type = types[0];
+  if (type === "array") {
+    const item = s.items === void 0 ? "unknown" : summarizeSchema(s.items, root, depth + 1);
+    return /[|\s]/.test(item) && !item.startsWith("{") ? `(${item})[]` : `${item}[]`;
+  }
+  if (type === "object" || type === void 0 && s.properties !== void 0) {
+    const properties = s.properties ?? {};
+    const keys = Object.keys(properties);
+    if (keys.length === 0) return "object";
+    const required = new Set(Array.isArray(s.required) ? s.required : []);
+    const fields = keys.map((key) => {
+      const field = properties[key];
+      const note = typeof field?.description === "string" && depth === 0 ? ` /* ${field.description} */` : "";
+      return `${key}${required.has(key) ? "" : "?"}: ${summarizeSchema(field, root, depth + 1)}${note}`;
+    });
+    return `{ ${fields.join(", ")} }`;
+  }
+  if (type === "integer") return "number";
+  return type ?? "unknown";
+}
+__name(summarizeSchema, "summarizeSchema");
+function fillTemplate(template, props) {
+  return template.replace(/\{\{\s*([\w.[\]]+)\s*\}\}/g, (_match, path) => {
+    const value = getPath(props, path);
+    if (value === null || value === void 0) return "";
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+  });
+}
+__name(fillTemplate, "fillTemplate");
+function getPath(source, path) {
+  let current = source;
+  for (const part of path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean)) {
+    if (current === null || current === void 0) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+__name(getPath, "getPath");
+
+// src/genui/tools.ts
+var GENUI_SHOW_TOOL = "ui__show";
+function genuiTools(catalog, options = {}) {
+  const tools = options.mode === "tree" ? [
+    treeTool(catalog, options)
+  ] : catalog.modelComponents().map((component) => componentTool(catalog, component, options));
+  if (options.showTool !== void 0 && options.showTool !== false) {
+    tools.push(showTool(catalog, options));
+  }
+  return tools;
+}
+__name(genuiTools, "genuiTools");
+function scopeOf(input) {
+  return {
+    actor: input.actor,
+    ...input.threadId !== void 0 ? {
+      threadId: input.threadId
+    } : {},
+    ...input.actor.tenantRef !== void 0 ? {
+      tenant: input.actor.tenantRef
+    } : {},
+    ...input.agentName !== void 0 ? {
+      agentName: input.agentName
+    } : {}
+  };
+}
+__name(scopeOf, "scopeOf");
+function catalogFor(catalog, options, scope) {
+  return options.resolveCatalog === void 0 ? catalog : options.resolveCatalog(scope);
+}
+__name(catalogFor, "catalogFor");
+function common(options) {
+  return {
+    ...options.roles !== void 0 ? {
+      roles: options.roles
+    } : {},
+    ...options.terminal === true ? {
+      terminal: true
+    } : {}
+  };
+}
+__name(common, "common");
+function componentTool(catalog, component, options) {
+  const presentation = options.presentation?.(component.name) ?? {
+    label: component.title,
+    running: `Showing ${lowerFirst(component.title)}`,
+    done: `Showed ${lowerFirst(component.title)}`,
+    result: {
+      kind: "elsewhere"
+    }
+  };
+  const describeFor = /* @__PURE__ */ __name((definition) => `Show the user a ${definition.title} (${definition.name}). ${definition.description}`, "describeFor");
+  const dynamic = options.resolveCatalog !== void 0;
+  const inputSchema = dynamic ? permissiveSchema(toJsonSchema(component.props) ?? {
+    type: "object"
+  }) : isStandardSchema(component.props) ? component.props : jsonStandardSchema(component.props, (value) => catalog.validator.validate(component.props, value));
+  const handler = {
+    async execute(input, ctx) {
+      const resolved = await catalogFor(catalog, options, scopeOf(ctx));
+      const definition = modelComponent(resolved, component.name);
+      if (definition === void 0) {
+        throw new Error(`component "${component.name}" is not available here`);
+      }
+      const validated = await validateProps(definition.props, input, resolved.validator);
+      if (!validated.ok) {
+        throw new Error(`invalid ${component.name} props: ${formatIssues(validated.issues)}`);
+      }
+      return push(ctx, component.name, validated.value, definition.version);
+    }
+  };
+  if (dynamic) {
+    handler.describe = async (scope) => {
+      const resolved = await catalogFor(catalog, options, scopeOf(scope));
+      const definition = modelComponent(resolved, component.name);
+      if (definition === void 0) {
+        return {
+          description: `Not available in this conversation \u2014 do not call this tool. (${component.name})`
+        };
+      }
+      return {
+        description: describeFor(definition),
+        inputSchema: permissiveSchema(toJsonSchema(definition.props) ?? {
+          type: "object"
+        })
+      };
+    };
+  }
+  return {
+    spec: {
+      name: toolNameFor(component.name, options.namePrefix),
+      kind: "read",
+      description: describeFor(component),
+      inputSchema,
+      presentation,
+      ...common(options)
+    },
+    handler
+  };
+}
+__name(componentTool, "componentTool");
+function treeTool(catalog, options) {
+  const name = options.treeToolName ?? "ui__render";
+  const presentation = options.presentation?.(name) ?? {
+    label: "Answer",
+    running: "Laying out the answer",
+    done: "Laid out the answer",
+    result: {
+      kind: "elsewhere"
+    }
+  };
+  const describeFor = /* @__PURE__ */ __name((resolved) => [
+    options.treeInstructions ?? "Render a rich UI to present the answer to the user.",
+    catalogToModelText(resolved, {
+      mode: "tree"
+    })
+  ].join("\n"), "describeFor");
+  const dynamic = options.resolveCatalog !== void 0;
+  const handler = {
+    async execute(input, ctx) {
+      const resolved = await catalogFor(catalog, options, scopeOf(ctx));
+      const result = await validateTree(resolved, input, options.treeLimits);
+      if (!result.ok) {
+        throw new Error(`invalid UI tree: ${formatIssues(result.issues)}`);
+      }
+      const root = result.value;
+      return push(ctx, GENUI_TREE_COMPONENT, {
+        root
+      });
+    }
+  };
+  if (dynamic) {
+    handler.describe = async (scope) => {
+      const resolved = await catalogFor(catalog, options, scopeOf(scope));
+      return {
+        description: describeFor(resolved),
+        inputSchema: permissiveSchema(treeJsonSchema(resolved))
+      };
+    };
+  }
+  return {
+    spec: {
+      name,
+      kind: "read",
+      description: describeFor(catalog),
+      inputSchema: dynamic ? permissiveSchema(treeJsonSchema(catalog)) : asyncJsonStandardSchema(treeJsonSchema(catalog), async (value) => {
+        const result = await validateTree(catalog, value, options.treeLimits);
+        return result.ok ? {
+          value: result.value
+        } : {
+          issues: result.issues
+        };
+      }),
+      presentation,
+      ...common(options)
+    },
+    handler
+  };
+}
+__name(treeTool, "treeTool");
+function showToolJsonSchema(catalog) {
+  return {
+    type: "object",
+    properties: {
+      component: {
+        type: "string",
+        enum: catalog.modelComponents().map((component) => component.name),
+        description: "Component name from the catalog"
+      },
+      props: {
+        type: "object",
+        description: "The component's props, as the catalog describes them"
+      }
+    },
+    required: [
+      "component",
+      "props"
+    ]
+  };
+}
+__name(showToolJsonSchema, "showToolJsonSchema");
+async function validateShow(catalog, input) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: [],
+          message: "must be { component, props }"
+        }
+      ]
+    };
+  }
+  const { component, props } = input;
+  if (typeof component !== "string") {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: [
+            "component"
+          ],
+          message: "must be a component name"
+        }
+      ]
+    };
+  }
+  const definition = modelComponent(catalog, component);
+  if (definition === void 0) {
+    const allowed = catalog.modelComponents().map((each) => each.name).join(", ");
+    return {
+      ok: false,
+      issues: [
+        {
+          path: [
+            "component"
+          ],
+          message: `unknown component "${component}" (allowed: ${allowed})`
+        }
+      ]
+    };
+  }
+  const validated = await validateProps(definition.props, props ?? {}, catalog.validator);
+  if (!validated.ok) {
+    return {
+      ok: false,
+      issues: validated.issues.map((issue) => ({
+        ...issue,
+        path: [
+          "props",
+          ...issue.path
+        ]
+      }))
+    };
+  }
+  return {
+    ok: true,
+    definition,
+    props: validated.value
+  };
+}
+__name(validateShow, "validateShow");
+function showTool(catalog, options) {
+  const name = typeof options.showTool === "string" ? options.showTool : GENUI_SHOW_TOOL;
+  const presentation = options.presentation?.(name) ?? {
+    label: "Show",
+    running: "Preparing a view",
+    done: "Showed a view",
+    result: {
+      kind: "elsewhere"
+    }
+  };
+  const describeFor = /* @__PURE__ */ __name((resolved) => [
+    options.showInstructions ?? "Show the user one component from the catalog.",
+    catalogToModelText(resolved, {
+      mode: "show"
+    })
+  ].join("\n"), "describeFor");
+  const dynamic = options.resolveCatalog !== void 0;
+  const handler = {
+    async execute(input, ctx) {
+      const resolved = await catalogFor(catalog, options, scopeOf(ctx));
+      const result = await validateShow(resolved, input);
+      if (!result.ok) {
+        throw new Error(`invalid ${name} call: ${formatIssues(result.issues)}`);
+      }
+      return push(ctx, result.definition.name, result.props, result.definition.version);
+    }
+  };
+  if (dynamic) {
+    handler.describe = async (scope) => {
+      const resolved = await catalogFor(catalog, options, scopeOf(scope));
+      return {
+        description: describeFor(resolved),
+        inputSchema: permissiveSchema(showToolJsonSchema(resolved))
+      };
+    };
+  }
+  return {
+    spec: {
+      name,
+      kind: "read",
+      description: describeFor(catalog),
+      inputSchema: dynamic ? permissiveSchema(showToolJsonSchema(catalog)) : asyncJsonStandardSchema(showToolJsonSchema(catalog), async (value) => {
+        const result = await validateShow(catalog, value);
+        return result.ok ? {
+          value: {
+            component: result.definition.name,
+            props: result.props
+          }
+        } : {
+          issues: result.issues
+        };
+      }),
+      presentation,
+      ...common(options)
+    },
+    handler
+  };
+}
+__name(showTool, "showTool");
+function modelComponent(catalog, name) {
+  const definition = catalog.get(name);
+  return definition === void 0 || definition.internal === true ? void 0 : definition;
+}
+__name(modelComponent, "modelComponent");
+async function push(ctx, component, props, version) {
+  const { id } = await ctx.emitUi(component, props, version !== void 0 ? {
+    version
+  } : {});
+  return {
+    shown: component,
+    id
+  };
+}
+__name(push, "push");
+function lowerFirst(text) {
+  return text.length > 0 ? `${text[0]?.toLowerCase()}${text.slice(1)}` : text;
+}
+__name(lowerFirst, "lowerFirst");
+function jsonStandardSchema(schema, validate) {
+  return asyncJsonStandardSchema(schema, (value) => {
+    const issues = validate(value);
+    return issues.length > 0 ? {
+      issues
+    } : {
+      value
+    };
+  });
+}
+__name(jsonStandardSchema, "jsonStandardSchema");
+function permissiveSchema(schema) {
+  return asyncJsonStandardSchema(schema, (value) => ({
+    value
+  }));
+}
+__name(permissiveSchema, "permissiveSchema");
+function asyncJsonStandardSchema(schema, validate) {
+  const toResult = /* @__PURE__ */ __name((outcome) => outcome.issues !== void 0 ? {
+    issues: outcome.issues.map((issue) => ({
+      message: issue.message,
+      path: issue.path
+    }))
+  } : {
+    value: outcome.value
+  }, "toResult");
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "nestjs-agent-genui",
+      validate(value) {
+        const outcome = validate(value);
+        return outcome instanceof Promise ? outcome.then(toResult) : toResult(outcome);
+      },
+      jsonSchema: {
+        input: /* @__PURE__ */ __name(() => schema, "input"),
+        output: /* @__PURE__ */ __name(() => schema, "output")
+      }
+    }
+  };
+}
+__name(asyncJsonStandardSchema, "asyncJsonStandardSchema");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  COMPONENT_NAME,
+  GENUI_SHOW_TOOL,
+  GENUI_TREE_COMPONENT,
+  ajvValidator,
+  builtinJsonSchemaValidator,
+  catalogToModelText,
+  componentToText,
+  defineCatalog,
+  defineComponent,
+  fillTemplate,
+  formatIssues,
+  genuiTools,
+  getPath,
+  isStandardSchema,
+  jsonStandardSchema,
+  showToolJsonSchema,
+  summarizeSchema,
+  toJsonSchema,
+  toSnakeCase,
+  toolNameFor,
+  treeJsonSchema,
+  treeToFlatSpec,
+  treeToText,
+  validateProps,
+  validatePropsSync,
+  validateTree
+});
+//# sourceMappingURL=index.cjs.map