@dudousxd/nestjs-agent 1.31.0 → 1.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-agent",
-  "version": "1.31.0",
+  "version": "1.31.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",
@@ -110,7 +110,7 @@
   "dependencies": {
     "@standard-schema/spec": "1.1.0",
     "zod": "3.25.76",
-    "@dudousxd/nestjs-agent-core": "0.52.0"
+    "@dudousxd/nestjs-agent-core": "0.52.1"
   },
   "peerDependencies": {
     "@dudousxd/nestjs-durable": ">=0.34.0",

package/dist/agent-genui.module-D0X3YnzO.d.cts

@@ -1,147 +0,0 @@
-import { ToolPresentation } from '@dudousxd/nestjs-agent-core';
-import { GenuiCatalogScope, Catalog, TreeSchemaMode, GenuiStreaming, TreeLimits, DefineSandboxOptions, GenuiChannels } from '@dudousxd/nestjs-agent-core/genui';
-import { Type, DynamicModule, ModuleMetadata, FactoryProvider } from '@nestjs/common';
-
-/** The app's genui catalog — `@InjectGenuiCatalog()` it anywhere; `overrideProvider` it in tests. */
-declare const GENUI_CATALOG: unique symbol;
-/** The resolved {@link AgentGenuiOptions} (without the resolver). */
-declare const GENUI_OPTIONS: unique symbol;
-/** Inject the app's genui catalog ({@link GENUI_CATALOG}). */
-declare const InjectGenuiCatalog: () => ParameterDecorator & PropertyDecorator;
-/**
- * Picks the catalog for ONE request — a tenant's own, versioned components. Consulted when a genui
- * call is validated and when the turn's tool list is described to the model, so components can
- * change without rebuilding tools at boot. Cache in here if resolving costs a round trip: it runs
- * once per turn per genui tool, and once per call.
- *
- * Provide it through `AgentGenuiModule.forRoot({ resolver })` (a class, resolved with DI, or an
- * instance); it is then injectable, and replaceable in a test with
- * `overrideProvider(GenuiCatalogResolver)`.
- */
-declare abstract class GenuiCatalogResolver {
-    abstract resolve(scope: GenuiCatalogScope): Catalog | Promise<Catalog>;
-}
-/** What {@link AgentGenuiModule} builds tools from. */
-interface AgentGenuiOptions {
-    /**
-     * The catalog. With a {@link GenuiCatalogResolver} it is the boot-time one — it names the
-     * per-component tools — and may be empty. Default: an empty catalog.
-     */
-    catalog?: Catalog;
-    /**
-     * `tree` (default): one `ui__render` tool taking a composed tree (a single node is pushed as that
-     * component). `per-component`: one `ui__show_<snake>` tool per component.
-     */
-    mode?: 'per-component' | 'tree';
-    /** `ui__render`'s input schema: `'strict'` (default, a `$defs` union per component) or `'loose'`. */
-    treeSchema?: TreeSchemaMode;
-    /**
-     * Tree mode: `'complete'` (default) draws the tree once the call has run; `'partial'` streams it
-     * as `partial` ui frames while the model writes it. A component's own `streaming` overrides it.
-     */
-    streaming?: GenuiStreaming;
-    /** Least time between two partial tree frames of one call, in ms. Default 100. */
-    streamingThrottleMs?: number;
-    /** End the model's turn once a genui call succeeds (no narrating follow-up call). */
-    terminal?: boolean;
-    /** Tool name in `tree` mode. Default `ui__render`. */
-    treeToolName?: string;
-    /** Text prepended to the tree tool's description. */
-    treeInstructions?: string;
-    treeLimits?: TreeLimits;
-    /**
-     * Tree mode: components that ALSO get a flat tool whose input IS their props —
-     * `componentTools: ['Sandbox']` adds `ui__sandbox`, so a model writing a big component on its own
-     * has no `{ type, props }` envelope to leave out.
-     */
-    componentTools?: readonly string[];
-    /** Tool-name prefix for `componentTools`. Default `ui__` (`Sandbox` → `ui__sandbox`). */
-    componentToolPrefix?: string;
-    /** Tool-name prefix in `per-component` mode. Default `ui__show_`. */
-    namePrefix?: string;
-    /**
-     * Also register ONE generic tool taking `{ component, props }`, validated against the request's
-     * catalog — how a model reaches a tenant's own components, which no boot-time tool names. `true`
-     * names it `ui__show`.
-     */
-    showTool?: boolean | string;
-    /** Text prepended to the show tool's description. */
-    showInstructions?: string;
-    /** Roles allowed to call the tools. Undefined → the roles policy default. */
-    roles?: string[];
-    /** Override the generated presentation per component (or per tree / show tool name). */
-    presentation?: (component: string) => ToolPresentation | undefined;
-    /**
-     * Add the sandbox component (`Sandbox`): the model may write HTML, CSS and JS for a one-off
-     * interactive answer when no catalog component fits. `true` for the defaults (no network), or
-     * the {@link DefineSandboxOptions} (a policy listing origins, extra instructions). Off by default.
-     * The browser's catalog should carry the same definition (`defineSandbox(...)` in the shared
-     * catalog file) so the renderer enforces the same policy.
-     *
-     * `theme` (default on), `tailwind` and `kit` put the app's design system in the frame. `kit: true`
-     * (and the theme's variable names) are found through `sandboxKit`: the descriptor
-     * `genuiSandboxKit()` (`@dudousxd/nestjs-agent/vite`) writes in dev, the Vite manifest in
-     * production — and `GET <base>/config` tells the renderer where the assets are.
-     */
-    sandbox?: boolean | DefineSandboxOptions;
-    /**
-     * Per-channel generative UI: each entry sets the mode, streaming, sandbox and rendering of one
-     * channel (`web`, `mobile`, `whatsapp`, `telegram`, `email`, or `default` for the rest), over the
-     * top-level options. A text channel (`@dudousxd/nestjs-agent-channels`) configured here draws the
-     * components natively (reply buttons, lists, images). Omitted → every channel is served by the
-     * top-level options, as before.
-     */
-    channels?: GenuiChannels;
-    /**
-     * Where the sandbox kit is found (with `sandbox: { kit: true }`, `tailwind: true` or the theme's
-     * names). No Vite runs in the Nest process, so: the descriptor the dev plugin writes, else the
-     * production Vite manifest (read first when `NODE_ENV=production`).
-     */
-    sandboxKit?: AgentGenuiSandboxKitOptions;
-}
-/** {@link AgentGenuiOptions.sandboxKit}. Relative paths resolve against `root`. */
-interface AgentGenuiSandboxKitOptions {
-    /** Default `process.cwd()`. */
-    root?: string;
-    /** The dev descriptor `genuiSandboxKit()` writes. Default `.genui/sandbox-kit.json`. */
-    descriptor?: string;
-    /**
-     * The production Vite manifest, and the directory its `file`s are relative to. Default
-     * `{ file: 'public/.vite/manifest.json', outDir: 'public' }`; `false` → none.
-     */
-    manifest?: {
-        file: string;
-        outDir: string;
-    } | false;
-    /** An explicit kit url (an SPA served from elsewhere), over what is found. */
-    kitUrl?: string;
-    /** Read the manifest first. Default: `NODE_ENV === 'production'`. */
-    production?: boolean;
-}
-type ResolverOption = Type<GenuiCatalogResolver> | GenuiCatalogResolver;
-interface AgentGenuiModuleOptions extends AgentGenuiOptions {
-    /** Per-request catalogs. A class is instantiated with DI (its dependencies must be global or exported to the root). */
-    resolver?: ResolverOption;
-}
-interface AgentGenuiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-    inject?: FactoryProvider['inject'];
-    useFactory: (...deps: any[]) => AgentGenuiOptions | Promise<AgentGenuiOptions>;
-    /** Per-request catalogs. A class resolves its dependencies from `imports`. */
-    resolver?: ResolverOption;
-}
-/**
- * Generative UI for the agent: registers the tools that let the model push catalog components
- * (one `ui__render` tree tool, or `ui__show_<component>` per component, and/or the generic
- * `ui__show`), and makes the catalog
- * injectable. Global, like `AgentModule`; import it once, next to it.
- *
- * ```ts
- * AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true })
- * ```
- */
-declare class AgentGenuiModule {
-    static forRoot(options?: AgentGenuiModuleOptions): DynamicModule;
-    static forRootAsync(options: AgentGenuiModuleAsyncOptions): DynamicModule;
-}
-
-export { AgentGenuiModule as A, GenuiCatalogResolver as G, InjectGenuiCatalog as I, type AgentGenuiModuleAsyncOptions as a, type AgentGenuiModuleOptions as b, type AgentGenuiOptions as c, type AgentGenuiSandboxKitOptions as d, GENUI_CATALOG as e, GENUI_OPTIONS as f };

package/dist/agent-genui.module-D0X3YnzO.d.ts

@@ -1,147 +0,0 @@
-import { ToolPresentation } from '@dudousxd/nestjs-agent-core';
-import { GenuiCatalogScope, Catalog, TreeSchemaMode, GenuiStreaming, TreeLimits, DefineSandboxOptions, GenuiChannels } from '@dudousxd/nestjs-agent-core/genui';
-import { Type, DynamicModule, ModuleMetadata, FactoryProvider } from '@nestjs/common';
-
-/** The app's genui catalog — `@InjectGenuiCatalog()` it anywhere; `overrideProvider` it in tests. */
-declare const GENUI_CATALOG: unique symbol;
-/** The resolved {@link AgentGenuiOptions} (without the resolver). */
-declare const GENUI_OPTIONS: unique symbol;
-/** Inject the app's genui catalog ({@link GENUI_CATALOG}). */
-declare const InjectGenuiCatalog: () => ParameterDecorator & PropertyDecorator;
-/**
- * Picks the catalog for ONE request — a tenant's own, versioned components. Consulted when a genui
- * call is validated and when the turn's tool list is described to the model, so components can
- * change without rebuilding tools at boot. Cache in here if resolving costs a round trip: it runs
- * once per turn per genui tool, and once per call.
- *
- * Provide it through `AgentGenuiModule.forRoot({ resolver })` (a class, resolved with DI, or an
- * instance); it is then injectable, and replaceable in a test with
- * `overrideProvider(GenuiCatalogResolver)`.
- */
-declare abstract class GenuiCatalogResolver {
-    abstract resolve(scope: GenuiCatalogScope): Catalog | Promise<Catalog>;
-}
-/** What {@link AgentGenuiModule} builds tools from. */
-interface AgentGenuiOptions {
-    /**
-     * The catalog. With a {@link GenuiCatalogResolver} it is the boot-time one — it names the
-     * per-component tools — and may be empty. Default: an empty catalog.
-     */
-    catalog?: Catalog;
-    /**
-     * `tree` (default): one `ui__render` tool taking a composed tree (a single node is pushed as that
-     * component). `per-component`: one `ui__show_<snake>` tool per component.
-     */
-    mode?: 'per-component' | 'tree';
-    /** `ui__render`'s input schema: `'strict'` (default, a `$defs` union per component) or `'loose'`. */
-    treeSchema?: TreeSchemaMode;
-    /**
-     * Tree mode: `'complete'` (default) draws the tree once the call has run; `'partial'` streams it
-     * as `partial` ui frames while the model writes it. A component's own `streaming` overrides it.
-     */
-    streaming?: GenuiStreaming;
-    /** Least time between two partial tree frames of one call, in ms. Default 100. */
-    streamingThrottleMs?: number;
-    /** End the model's turn once a genui call succeeds (no narrating follow-up call). */
-    terminal?: boolean;
-    /** Tool name in `tree` mode. Default `ui__render`. */
-    treeToolName?: string;
-    /** Text prepended to the tree tool's description. */
-    treeInstructions?: string;
-    treeLimits?: TreeLimits;
-    /**
-     * Tree mode: components that ALSO get a flat tool whose input IS their props —
-     * `componentTools: ['Sandbox']` adds `ui__sandbox`, so a model writing a big component on its own
-     * has no `{ type, props }` envelope to leave out.
-     */
-    componentTools?: readonly string[];
-    /** Tool-name prefix for `componentTools`. Default `ui__` (`Sandbox` → `ui__sandbox`). */
-    componentToolPrefix?: string;
-    /** Tool-name prefix in `per-component` mode. Default `ui__show_`. */
-    namePrefix?: string;
-    /**
-     * Also register ONE generic tool taking `{ component, props }`, validated against the request's
-     * catalog — how a model reaches a tenant's own components, which no boot-time tool names. `true`
-     * names it `ui__show`.
-     */
-    showTool?: boolean | string;
-    /** Text prepended to the show tool's description. */
-    showInstructions?: string;
-    /** Roles allowed to call the tools. Undefined → the roles policy default. */
-    roles?: string[];
-    /** Override the generated presentation per component (or per tree / show tool name). */
-    presentation?: (component: string) => ToolPresentation | undefined;
-    /**
-     * Add the sandbox component (`Sandbox`): the model may write HTML, CSS and JS for a one-off
-     * interactive answer when no catalog component fits. `true` for the defaults (no network), or
-     * the {@link DefineSandboxOptions} (a policy listing origins, extra instructions). Off by default.
-     * The browser's catalog should carry the same definition (`defineSandbox(...)` in the shared
-     * catalog file) so the renderer enforces the same policy.
-     *
-     * `theme` (default on), `tailwind` and `kit` put the app's design system in the frame. `kit: true`
-     * (and the theme's variable names) are found through `sandboxKit`: the descriptor
-     * `genuiSandboxKit()` (`@dudousxd/nestjs-agent/vite`) writes in dev, the Vite manifest in
-     * production — and `GET <base>/config` tells the renderer where the assets are.
-     */
-    sandbox?: boolean | DefineSandboxOptions;
-    /**
-     * Per-channel generative UI: each entry sets the mode, streaming, sandbox and rendering of one
-     * channel (`web`, `mobile`, `whatsapp`, `telegram`, `email`, or `default` for the rest), over the
-     * top-level options. A text channel (`@dudousxd/nestjs-agent-channels`) configured here draws the
-     * components natively (reply buttons, lists, images). Omitted → every channel is served by the
-     * top-level options, as before.
-     */
-    channels?: GenuiChannels;
-    /**
-     * Where the sandbox kit is found (with `sandbox: { kit: true }`, `tailwind: true` or the theme's
-     * names). No Vite runs in the Nest process, so: the descriptor the dev plugin writes, else the
-     * production Vite manifest (read first when `NODE_ENV=production`).
-     */
-    sandboxKit?: AgentGenuiSandboxKitOptions;
-}
-/** {@link AgentGenuiOptions.sandboxKit}. Relative paths resolve against `root`. */
-interface AgentGenuiSandboxKitOptions {
-    /** Default `process.cwd()`. */
-    root?: string;
-    /** The dev descriptor `genuiSandboxKit()` writes. Default `.genui/sandbox-kit.json`. */
-    descriptor?: string;
-    /**
-     * The production Vite manifest, and the directory its `file`s are relative to. Default
-     * `{ file: 'public/.vite/manifest.json', outDir: 'public' }`; `false` → none.
-     */
-    manifest?: {
-        file: string;
-        outDir: string;
-    } | false;
-    /** An explicit kit url (an SPA served from elsewhere), over what is found. */
-    kitUrl?: string;
-    /** Read the manifest first. Default: `NODE_ENV === 'production'`. */
-    production?: boolean;
-}
-type ResolverOption = Type<GenuiCatalogResolver> | GenuiCatalogResolver;
-interface AgentGenuiModuleOptions extends AgentGenuiOptions {
-    /** Per-request catalogs. A class is instantiated with DI (its dependencies must be global or exported to the root). */
-    resolver?: ResolverOption;
-}
-interface AgentGenuiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-    inject?: FactoryProvider['inject'];
-    useFactory: (...deps: any[]) => AgentGenuiOptions | Promise<AgentGenuiOptions>;
-    /** Per-request catalogs. A class resolves its dependencies from `imports`. */
-    resolver?: ResolverOption;
-}
-/**
- * Generative UI for the agent: registers the tools that let the model push catalog components
- * (one `ui__render` tree tool, or `ui__show_<component>` per component, and/or the generic
- * `ui__show`), and makes the catalog
- * injectable. Global, like `AgentModule`; import it once, next to it.
- *
- * ```ts
- * AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true })
- * ```
- */
-declare class AgentGenuiModule {
-    static forRoot(options?: AgentGenuiModuleOptions): DynamicModule;
-    static forRootAsync(options: AgentGenuiModuleAsyncOptions): DynamicModule;
-}
-
-export { AgentGenuiModule as A, GenuiCatalogResolver as G, InjectGenuiCatalog as I, type AgentGenuiModuleAsyncOptions as a, type AgentGenuiModuleOptions as b, type AgentGenuiOptions as c, type AgentGenuiSandboxKitOptions as d, GENUI_CATALOG as e, GENUI_OPTIONS as f };