@dudousxd/nestjs-agent 1.29.0 → 1.31.0

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

@@ -0,0 +1,147 @@
+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

@@ -0,0 +1,147 @@
+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/{chat-queue.service-B-fVOJGf.d.ts → chat-queue.service-Bdz43pAC.d.ts}

@@ -2,7 +2,7 @@ import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPol
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
-import { GenuiCatalogResolver } from './genui/index.js';
+import { G as GenuiCatalogResolver } from './agent-genui.module-D0X3YnzO.js';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
 interface AgentDeps {

package/dist/{chat-queue.service-Bk7DCKGV.d.cts → chat-queue.service-ZwQ9p-Ps.d.cts}

@@ -2,7 +2,7 @@ import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPol
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
-import { GenuiCatalogResolver } from './genui/index.cjs';
+import { G as GenuiCatalogResolver } from './agent-genui.module-D0X3YnzO.cjs';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
 interface AgentDeps {