@adonis-agora/agent 0.60.1 → 0.62.0

package/dist/src/genui/tools.d.ts

@@ -0,0 +1,91 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+import type { ToolHandler } from '../spi/tool.js';
+import type { ToolPresentation } from '../tool-presentation.js';
+import type { Actor, ToolSpec } from '../types.js';
+import { type Catalog } from './catalog.js';
+import { type GenuiIssue, type JsonSchema } from './schema.js';
+import { type TreeLimits } from './tree.js';
+/** A lib tool: register it with `aiTool(tool)` (AdonisJS) or `registry.register(tool.spec, tool.handler)`. */
+export interface GenuiTool {
+    spec: ToolSpec & {
+        terminal?: boolean;
+    };
+    handler: ToolHandler;
+}
+/** What a genui tool returns to the model: what was pushed, and the `ui` frame's id. */
+export interface GenuiToolOutput {
+    shown: string;
+    id: string;
+}
+/**
+ * Who a catalog is being resolved for. `tenant` is `actor.tenantRef`. `threadId` is absent only
+ * when a tool list is built outside a conversation (the MCP server's `tools/list`).
+ */
+export interface GenuiCatalogScope {
+    actor: Actor;
+    threadId?: string;
+    tenant?: string;
+    agentName?: string;
+}
+/** Answers which catalog applies to a request — a tenant's own, versioned components. */
+export type ResolveGenuiCatalog = (scope: GenuiCatalogScope) => Catalog | Promise<Catalog>;
+export interface GenuiToolsOptions {
+    /**
+     * `per-component` (default): one tool per model-facing component, `ui__show_<snake>`, whose input
+     * IS the component's props. `tree`: a single tool whose input is a nested
+     * `{ type, props, children }` tree composed from the catalog (json-render's nested shape).
+     */
+    mode?: 'per-component' | 'tree';
+    /**
+     * The model's turn ends once a genui call succeeds — no further model call to narrate what the UI
+     * already shows. Stamped as `spec.terminal`.
+     */
+    terminal?: boolean;
+    /** Tool-name prefix for `per-component`. Default `ui__show_`. */
+    namePrefix?: string;
+    /** Tool name for `tree`. Default `ui__render`. */
+    treeToolName?: string;
+    /** Extra text prepended to the tree tool's description (when to call it, house rules). */
+    treeInstructions?: string;
+    /** Size limits for `tree`. */
+    treeLimits?: TreeLimits;
+    /**
+     * Also offer ONE generic tool taking `{ component, props }`, validated against the (resolved)
+     * catalog — how a model reaches components that only exist per request (a tenant's own), which a
+     * boot-time tool list cannot name. `true` names it `ui__show`; a string names it.
+     */
+    showTool?: boolean | string;
+    /** Extra text prepended to the show tool's description. */
+    showInstructions?: string;
+    /** Roles allowed to call the tools (the `ToolSpec.roles` gate). Undefined → the roles policy default. */
+    roles?: string[];
+    /** Override the generated presentation per component (or for the tree / show tool, under its tool name). */
+    presentation?: (component: string) => ToolPresentation | undefined;
+    /**
+     * The catalog for THIS request, consulted when a call is validated and when the turn's tool list
+     * is described to the model. The `catalog` argument is then the boot-time one: it names the
+     * per-component tools and is what a list built without a resolver would show. Omit → the
+     * `catalog` argument serves every request.
+     */
+    resolveCatalog?: ResolveGenuiCatalog;
+}
+/** The default name of the generic show tool ({@link GenuiToolsOptions.showTool}). */
+export declare const GENUI_SHOW_TOOL = "ui__show";
+/**
+ * Tools that let a model push catalog components into the conversation as `ui` frames. Each call
+ * validates its input against the catalog (a refused call reaches the model as a tool error it can
+ * fix) and then pushes through `ctx.emitUi`, which streams the frame live and persists it on the
+ * assistant message.
+ */
+export declare function genuiTools(catalog: Catalog, options?: GenuiToolsOptions): GenuiTool[];
+/** The show tool's input: a component name (one of the catalog's) and its props. */
+export declare function showToolJsonSchema(catalog: Catalog): JsonSchema;
+type JsonStandardSchema = StandardSchemaV1 & StandardJSONSchemaV1;
+/**
+ * A JSON Schema presented as a Standard Schema WITH the Standard JSON Schema extension, so the lib
+ * validates tool input through `~standard.validate` and the AI SDK adapter hands the model the
+ * schema itself (it reads `~standard.jsonSchema.input`).
+ */
+export declare function jsonStandardSchema(schema: JsonSchema, validate: (value: unknown) => GenuiIssue[]): JsonStandardSchema;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/src/genui/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/genui/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,KAAK,EAAiD,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACjG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,KAAK,OAAO,EAAyC,MAAM,cAAc,CAAC;AACnF,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAErB,OAAO,EAGL,KAAK,UAAU,EAGhB,MAAM,WAAW,CAAC;AAEnB,8GAA8G;AAC9G,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,GAAG;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACxC,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yFAAyF;AACzF,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE3F,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yGAAyG;IACzG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4GAA4G;IAC5G,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAC;IACnE;;;;;OAKG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED,sFAAsF;AACtF,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,iBAAsB,GAAG,SAAS,EAAE,CASzF;AAuKD,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAgB/D;AAsHD,KAAK,kBAAkB,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,UAAU,EAAE,GACzC,kBAAkB,CAKpB"}

package/dist/src/genui/tools.js

@@ -0,0 +1,292 @@
+import { negotiateCatalog } from './capabilities.js';
+import { toolNameFor } from './catalog.js';
+import { formatIssues, isStandardSchema, toJsonSchema, validateProps, } from './schema.js';
+import { catalogToModelText } from './text.js';
+import { GENUI_TREE_COMPONENT, treeJsonSchema, validateTree, } from './tree.js';
+/** The default name of the generic show tool ({@link GenuiToolsOptions.showTool}). */
+export const GENUI_SHOW_TOOL = 'ui__show';
+/**
+ * Tools that let a model push catalog components into the conversation as `ui` frames. Each call
+ * validates its input against the catalog (a refused call reaches the model as a tool error it can
+ * fix) and then pushes through `ctx.emitUi`, which streams the frame live and persists it on the
+ * assistant message.
+ */
+export function genuiTools(catalog, options = {}) {
+    const tools = options.mode === 'tree'
+        ? [treeTool(catalog, options)]
+        : catalog.modelComponents().map((component) => componentTool(catalog, component, options));
+    if (options.showTool !== undefined && options.showTool !== false) {
+        tools.push(showTool(catalog, options));
+    }
+    return tools;
+}
+function scopeOf(input) {
+    return {
+        actor: input.actor,
+        ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),
+        ...(input.actor.tenantRef !== undefined ? { tenant: input.actor.tenantRef } : {}),
+        ...(input.agentName !== undefined ? { agentName: input.agentName } : {}),
+    };
+}
+function catalogFor(catalog, options, scope) {
+    return options.resolveCatalog === undefined ? catalog : options.resolveCatalog(scope);
+}
+function common(options) {
+    return {
+        ...(options.roles !== undefined ? { roles: options.roles } : {}),
+        ...(options.terminal === true ? { terminal: true } : {}),
+    };
+}
+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 = (definition) => `Show the user a ${definition.title} (${definition.name}). ${definition.description}`;
+    const dynamic = options.resolveCatalog !== undefined;
+    // With a resolver the component's schema may differ per request (a tenant's version of it), so
+    // the registry lets any object through and `execute` validates against the resolved definition.
+    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 === undefined) {
+                throw new Error(`component "${component.name}" is not available here`);
+            }
+            // Static handlers receive the registry's parsed output; dynamic handlers parse the
+            // request-specific input here. Never run an input transformation on portable output.
+            const validated = await validateProps(dynamic ? definition.props : (definition.outputProps ?? 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);
+        },
+    };
+    handler.describe = async (scope) => {
+        const resolved = negotiateCatalog(await catalogFor(catalog, options, scopeOf(scope)), scope.uiCapabilities);
+        const definition = modelComponent(resolved, component.name);
+        if (definition === undefined) {
+            return {
+                available: false,
+                description: `Not available in this conversation — 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,
+    };
+}
+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 = (resolved) => [
+        options.treeInstructions ?? 'Render a rich UI to present the answer to the user.',
+        catalogToModelText(resolved, { mode: 'tree' }),
+    ].join('\n');
+    const dynamic = options.resolveCatalog !== undefined;
+    const handler = {
+        async execute(input, ctx) {
+            const resolved = await catalogFor(catalog, options, scopeOf(ctx));
+            const result = await validateTree(resolved, input, options.treeLimits, dynamic ? 'input' : 'output');
+            if (!result.ok) {
+                throw new Error(`invalid UI tree: ${formatIssues(result.issues)}`);
+            }
+            const root = result.value;
+            return push(ctx, GENUI_TREE_COMPONENT, { root });
+        },
+    };
+    handler.describe = async (scope) => {
+        const resolved = negotiateCatalog(await catalogFor(catalog, options, scopeOf(scope)), scope.uiCapabilities);
+        return {
+            available: resolved.modelComponents().length > 0,
+            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, 'input');
+                    return result.ok ? { value: result.value } : { issues: result.issues };
+                }),
+            presentation,
+            ...common(options),
+        },
+        handler,
+    };
+}
+/** The show tool's input: a component name (one of the catalog's) and its props. */
+export 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'],
+    };
+}
+async function validateShow(catalog, input, phase = '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 === undefined) {
+        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(phase === 'input' ? definition.props : (definition.outputProps ?? 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 };
+}
+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 = (resolved) => [
+        options.showInstructions ?? 'Show the user one component from the catalog.',
+        catalogToModelText(resolved, { mode: 'show' }),
+    ].join('\n');
+    const dynamic = options.resolveCatalog !== undefined;
+    const handler = {
+        async execute(input, ctx) {
+            const resolved = await catalogFor(catalog, options, scopeOf(ctx));
+            const result = await validateShow(resolved, input, dynamic ? 'input' : 'output');
+            if (!result.ok) {
+                throw new Error(`invalid ${name} call: ${formatIssues(result.issues)}`);
+            }
+            return push(ctx, result.definition.name, result.props, result.definition.version);
+        },
+    };
+    handler.describe = async (scope) => {
+        const resolved = negotiateCatalog(await catalogFor(catalog, options, scopeOf(scope)), scope.uiCapabilities);
+        return {
+            available: resolved.modelComponents().length > 0,
+            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,
+    };
+}
+function modelComponent(catalog, name) {
+    const definition = catalog.get(name);
+    return definition === undefined || definition.internal === true ? undefined : definition;
+}
+async function push(ctx, component, props, version) {
+    const { id } = await ctx.emitUi(component, props, version !== undefined ? { version } : {});
+    return { shown: component, id };
+}
+function lowerFirst(text) {
+    return text.length > 0 ? `${text[0]?.toLowerCase()}${text.slice(1)}` : text;
+}
+/**
+ * A JSON Schema presented as a Standard Schema WITH the Standard JSON Schema extension, so the lib
+ * validates tool input through `~standard.validate` and the AI SDK adapter hands the model the
+ * schema itself (it reads `~standard.jsonSchema.input`).
+ */
+export function jsonStandardSchema(schema, validate) {
+    return asyncJsonStandardSchema(schema, (value) => {
+        const issues = validate(value);
+        return issues.length > 0 ? { issues } : { value };
+    });
+}
+/** Shows the model `schema`, accepts any value: validation happens in `execute`, per request. */
+function permissiveSchema(schema) {
+    return asyncJsonStandardSchema(schema, (value) => ({ value }));
+}
+function asyncJsonStandardSchema(schema, validate) {
+    const toResult = (outcome) => outcome.issues !== undefined
+        ? {
+            issues: outcome.issues.map((issue) => ({ message: issue.message, path: issue.path })),
+        }
+        : { value: outcome.value };
+    return {
+        '~standard': {
+            version: 1,
+            vendor: 'adonis-agora-agent-genui',
+            validate(value) {
+                const outcome = validate(value);
+                return outcome instanceof Promise ? outcome.then(toResult) : toResult(outcome);
+            },
+            jsonSchema: {
+                input: () => schema,
+                output: () => schema,
+            },
+        },
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/src/genui/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/genui/tools.ts"],"names":[],"mappings":"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"}

package/dist/src/genui/tree.d.ts

@@ -0,0 +1,56 @@
+import type { Catalog } from './catalog.js';
+import { type GenuiValidation, type JsonSchema } from './schema.js';
+/**
+ * One node of a composed UI: a catalog component, its props, and — for components declared with
+ * `children: true` — nested nodes. The shape json-render calls a "nested element", so a tree
+ * converts to a json-render flat spec with {@link treeToFlatSpec}.
+ */
+export interface GenuiElement {
+    type: string;
+    props: Record<string, unknown>;
+    children?: GenuiElement[];
+}
+/**
+ * The `ui` frame component a tree-mode tool pushes: `{ component: GENUI_TREE_COMPONENT, props: {
+ * root } }`. Not a valid component name, so it can never collide with a catalog entry.
+ */
+export declare const GENUI_TREE_COMPONENT = "genui:tree";
+/** Props of a {@link GENUI_TREE_COMPONENT} frame. */
+export interface GenuiTreeProps {
+    root: GenuiElement;
+}
+export interface TreeLimits {
+    /** Deepest nesting accepted. Default 12. */
+    maxDepth?: number;
+    /** Most nodes accepted in one tree. Default 200. */
+    maxNodes?: number;
+}
+/**
+ * Validate a model-composed tree against the catalog: every node's `type` must be a model-facing
+ * component, its props must pass that component's schema, and only components declared with
+ * `children: true` may have children. Returns the tree with each node's props as its schema
+ * produced them (defaults applied by a Standard Schema, for instance).
+ *
+ * Lenient about one thing models get wrong: a `children` array sent as a JSON STRING (sometimes
+ * with a stray trailing `}`) is parsed back into the array the model plainly meant.
+ */
+export declare function validateTree(catalog: Catalog, tree: unknown, limits?: TreeLimits, phase?: 'input' | 'output'): Promise<GenuiValidation<GenuiElement>>;
+/**
+ * The JSON Schema of a tree-mode tool's input: a recursive `{ type, props, children? }` node whose
+ * `type` is one of the catalog's model-facing component names. Per-component props are described
+ * to the model in the tool description (see `catalogToModelText`) and checked by
+ * {@link validateTree}, which keeps this schema small enough for every provider.
+ */
+export declare function treeJsonSchema(catalog: Catalog): JsonSchema;
+/** A json-render flat spec: `{ root, elements: { [id]: { type, props, children: id[] } } }`. */
+export interface FlatSpec {
+    root: string;
+    elements: Record<string, {
+        type: string;
+        props: Record<string, unknown>;
+        children: string[];
+    }>;
+}
+/** Convert a tree to a json-render flat spec (ids are `el-0`, `el-1`, … in depth-first order). */
+export declare function treeToFlatSpec(root: GenuiElement): FlatSpec;
+//# sourceMappingURL=tree.d.ts.map

package/dist/src/genui/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/genui/tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAmB,KAAK,eAAe,EAAE,KAAK,UAAU,EAAiB,MAAM,aAAa,CAAC;AAEpG;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,EACb,MAAM,GAAE,UAAe,EACvB,KAAK,GAAE,OAAO,GAAG,QAAmB,GACnC,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,CA4FxC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAsB3D;AAED,gGAAgG;AAChG,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAChG;AAED,kGAAkG;AAClG,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CAa3D"}

package/dist/src/genui/tree.js

@@ -0,0 +1,188 @@
+import { validateProps } from './schema.js';
+/**
+ * The `ui` frame component a tree-mode tool pushes: `{ component: GENUI_TREE_COMPONENT, props: {
+ * root } }`. Not a valid component name, so it can never collide with a catalog entry.
+ */
+export const GENUI_TREE_COMPONENT = 'genui:tree';
+/**
+ * Validate a model-composed tree against the catalog: every node's `type` must be a model-facing
+ * component, its props must pass that component's schema, and only components declared with
+ * `children: true` may have children. Returns the tree with each node's props as its schema
+ * produced them (defaults applied by a Standard Schema, for instance).
+ *
+ * Lenient about one thing models get wrong: a `children` array sent as a JSON STRING (sometimes
+ * with a stray trailing `}`) is parsed back into the array the model plainly meant.
+ */
+export async function validateTree(catalog, tree, limits = {}, phase = 'output') {
+    const maxDepth = limits.maxDepth ?? 12;
+    const maxNodes = limits.maxNodes ?? 200;
+    const issues = [];
+    let nodes = 0;
+    const visit = 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 undefined;
+        }
+        if (depth > maxDepth) {
+            issues.push({ path, message: `the tree is nested deeper than ${maxDepth} levels` });
+            return undefined;
+        }
+        if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+            issues.push({ path, message: 'must be an element object { type, props, children? }' });
+            return undefined;
+        }
+        const element = node;
+        if (typeof element.type !== 'string') {
+            issues.push({ path: [...path, 'type'], message: 'must be a component name' });
+            return undefined;
+        }
+        const definition = catalog.get(element.type);
+        if (definition === undefined || definition.internal === true) {
+            issues.push({
+                path: [...path, 'type'],
+                message: `unknown component "${element.type}" (allowed: ${catalog
+                    .modelComponents()
+                    .map((component) => component.name)
+                    .join(', ')})`,
+            });
+            return undefined;
+        }
+        const validated = phase === 'input'
+            ? (await validateProps(definition.props, element.props ?? {}, catalog.validator))
+            : 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 === undefined || 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 undefined;
+        }
+        if (rawChildren.length > 0 && definition.children !== true) {
+            issues.push({
+                path: [...path, 'children'],
+                message: `${element.type} does not take children`,
+            });
+            return undefined;
+        }
+        const children = [];
+        for (const [index, child] of rawChildren.entries()) {
+            const next = await visit(child, [...path, 'children', index], depth + 1);
+            if (next !== undefined) {
+                children.push(next);
+            }
+        }
+        return children.length > 0
+            ? { type: element.type, props, children }
+            : { type: element.type, props };
+    };
+    const root = await visit(tree, [], 1);
+    return issues.length > 0 || root === undefined
+        ? { ok: false, issues: issues.length > 0 ? issues : [{ path: [], message: 'is invalid' }] }
+        : { ok: true, value: root };
+}
+/**
+ * The JSON Schema of a tree-mode tool's input: a recursive `{ type, props, children? }` node whose
+ * `type` is one of the catalog's model-facing component names. Per-component props are described
+ * to the model in the tool description (see `catalogToModelText`) and checked by
+ * {@link validateTree}, which keeps this schema small enough for every provider.
+ */
+export 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'],
+    };
+}
+/** Convert a tree to a json-render flat spec (ids are `el-0`, `el-1`, … in depth-first order). */
+export function treeToFlatSpec(root) {
+    const elements = {};
+    let next = 0;
+    const visit = (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;
+    };
+    return { root: visit(root), elements };
+}
+function parseChildrenIfStringified(value) {
+    if (typeof value !== 'string')
+        return value;
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('['))
+        return value;
+    return leadingJsonArray(trimmed) ?? value;
+}
+/**
+ * The array `text` opens with, ignoring what follows: a model that stringifies `children` tends to
+ * carry the enclosing object's `}` along, which `JSON.parse` refuses whole.
+ */
+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 : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=tree.js.map