@dudousxd/nestjs-agent 1.21.0 → 1.22.0

package/dist/genui/index.cjs

@@ -35,6 +35,7 @@ var import_genui = require("@dudousxd/nestjs-agent-core/genui");
 var import_common = require("@nestjs/common");
 
 // src/functional-tool.ts
+var import_nestjs_agent_core = require("@dudousxd/nestjs-agent-core");
 var AGENT_TOOL_BRAND = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:functional-tool");
 function brand(tool) {
   return {

package/dist/genui/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/genui/index.ts","../../src/genui/agent-genui.module.ts","../../src/functional-tool.ts"],"sourcesContent":["/**\n * `@dudousxd/nestjs-agent/genui` — generative UI for NestJS: {@link AgentGenuiModule} registers the\n * tools that push catalog components, `GENUI_CATALOG` / `@InjectGenuiCatalog()` expose the catalog,\n * and {@link GenuiCatalogResolver} serves per-request (per-tenant) catalogs. The catalog itself —\n * `defineComponent`, `defineCatalog`, validation, text fallbacks — is re-exported from\n * `@dudousxd/nestjs-agent-core/genui`, the isomorphic entry a browser imports too.\n */\nexport {\n  AgentGenuiModule,\n  type AgentGenuiModuleAsyncOptions,\n  type AgentGenuiModuleOptions,\n  type AgentGenuiOptions,\n  GENUI_CATALOG,\n  GENUI_OPTIONS,\n  GenuiCatalogResolver,\n  InjectGenuiCatalog,\n} from './agent-genui.module.js';\nexport * from '@dudousxd/nestjs-agent-core/genui';\n","import type { ToolPresentation } from '@dudousxd/nestjs-agent-core';\nimport type {\n  Catalog,\n  GenuiCatalogScope,\n  GenuiToolsOptions,\n  TreeLimits,\n} from '@dudousxd/nestjs-agent-core/genui';\nimport { defineCatalog, genuiTools } from '@dudousxd/nestjs-agent-core/genui';\nimport {\n  type DynamicModule,\n  type FactoryProvider,\n  Inject,\n  Module,\n  type ModuleMetadata,\n  type Provider,\n  type Type,\n} from '@nestjs/common';\nimport { provideAgentTools } from '../functional-tool.js';\n\n/** The app's genui catalog — `@InjectGenuiCatalog()` it anywhere; `overrideProvider` it in tests. */\nexport const GENUI_CATALOG = Symbol.for('@dudousxd/nestjs-agent:genui-catalog');\n\n/** The resolved {@link AgentGenuiOptions} (without the resolver). */\nexport const GENUI_OPTIONS = Symbol.for('@dudousxd/nestjs-agent:genui-options');\n\n/** Inject the app's genui catalog ({@link GENUI_CATALOG}). */\nexport const InjectGenuiCatalog = (): ParameterDecorator & PropertyDecorator =>\n  Inject(GENUI_CATALOG);\n\n/**\n * Picks the catalog for ONE request — a tenant's own, versioned components. Consulted when a genui\n * call is validated and when the turn's tool list is described to the model, so components can\n * change without rebuilding tools at boot. Cache in here if resolving costs a round trip: it runs\n * once per turn per genui tool, and once per call.\n *\n * Provide it through `AgentGenuiModule.forRoot({ resolver })` (a class, resolved with DI, or an\n * instance); it is then injectable, and replaceable in a test with\n * `overrideProvider(GenuiCatalogResolver)`.\n */\nexport abstract class GenuiCatalogResolver {\n  abstract resolve(scope: GenuiCatalogScope): Catalog | Promise<Catalog>;\n}\n\n/** What {@link AgentGenuiModule} builds tools from. */\nexport interface AgentGenuiOptions {\n  /**\n   * The catalog. With a {@link GenuiCatalogResolver} it is the boot-time one — it names the\n   * per-component tools — and may be empty. Default: an empty catalog.\n   */\n  catalog?: Catalog;\n  /** `per-component` (default): one `ui__show_<snake>` tool per component. `tree`: one tool taking a composed tree. */\n  mode?: 'per-component' | 'tree';\n  /** End the model's turn once a genui call succeeds (no narrating follow-up call). */\n  terminal?: boolean;\n  /** Tool name in `tree` mode. Default `ui__render`. */\n  treeToolName?: string;\n  /** Text prepended to the tree tool's description. */\n  treeInstructions?: string;\n  treeLimits?: TreeLimits;\n  /** Tool-name prefix in `per-component` mode. Default `ui__show_`. */\n  namePrefix?: string;\n  /**\n   * Also register ONE generic tool taking `{ component, props }`, validated against the request's\n   * catalog — how a model reaches a tenant's own components, which no boot-time tool names. `true`\n   * names it `ui__show`.\n   */\n  showTool?: boolean | string;\n  /** Text prepended to the show tool's description. */\n  showInstructions?: string;\n  /** Roles allowed to call the tools. Undefined → the roles policy default. */\n  roles?: string[];\n  /** Override the generated presentation per component (or per tree / show tool name). */\n  presentation?: (component: string) => ToolPresentation | undefined;\n}\n\ntype ResolverOption = Type<GenuiCatalogResolver> | GenuiCatalogResolver;\n\nexport interface AgentGenuiModuleOptions extends AgentGenuiOptions {\n  /** Per-request catalogs. A class is instantiated with DI (its dependencies must be global or exported to the root). */\n  resolver?: ResolverOption;\n}\n\nexport interface AgentGenuiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {\n  inject?: FactoryProvider['inject'];\n  useFactory: (...deps: any[]) => AgentGenuiOptions | Promise<AgentGenuiOptions>;\n  /** Per-request catalogs. A class resolves its dependencies from `imports`. */\n  resolver?: ResolverOption;\n}\n\nfunction resolverProviders(resolver: ResolverOption | undefined): Provider[] {\n  if (resolver === undefined) return [];\n  return [\n    typeof resolver === 'function'\n      ? { provide: GenuiCatalogResolver, useClass: resolver }\n      : { provide: GenuiCatalogResolver, useValue: resolver },\n  ];\n}\n\nfunction toolOptions(\n  options: AgentGenuiOptions,\n  resolver: GenuiCatalogResolver | undefined,\n): GenuiToolsOptions {\n  const { catalog: _catalog, ...rest } = options;\n  return {\n    ...rest,\n    ...(resolver !== undefined\n      ? { resolveCatalog: (scope: GenuiCatalogScope) => resolver.resolve(scope) }\n      : {}),\n  };\n}\n\nfunction coreProviders(resolver: ResolverOption | undefined): Provider[] {\n  return [\n    {\n      provide: GENUI_CATALOG,\n      useFactory: (options: AgentGenuiOptions) => options.catalog ?? defineCatalog([]),\n      inject: [GENUI_OPTIONS],\n    },\n    ...resolverProviders(resolver),\n    // The generated tools, registered by the agent module's discovery like any `provideAgentTool`.\n    // Built from the injected catalog, so `overrideProvider(GENUI_CATALOG)` changes them too.\n    provideAgentTools(\n      (options: AgentGenuiOptions, catalog: Catalog, perRequest?: GenuiCatalogResolver) =>\n        genuiTools(catalog, toolOptions(options, perRequest)),\n      [GENUI_OPTIONS, GENUI_CATALOG, { token: GenuiCatalogResolver, optional: true }],\n    ),\n  ];\n}\n\nconst EXPORTS = [GENUI_CATALOG, GENUI_OPTIONS];\n\n/**\n * Generative UI for the agent: registers the tools that let the model push catalog components\n * (`ui__show_<component>`, or one tree tool, or the generic `ui__show`), and makes the catalog\n * injectable. Global, like `AgentModule`; import it once, next to it.\n *\n * ```ts\n * AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true })\n * ```\n */\n@Module({})\nexport class AgentGenuiModule {\n  static forRoot(options: AgentGenuiModuleOptions = {}): DynamicModule {\n    const { resolver, ...rest } = options;\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      providers: [{ provide: GENUI_OPTIONS, useValue: rest }, ...coreProviders(resolver)],\n      exports: resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n\n  static forRootAsync(options: AgentGenuiModuleAsyncOptions): DynamicModule {\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      imports: options.imports ?? [],\n      providers: [\n        { provide: GENUI_OPTIONS, useFactory: options.useFactory, inject: options.inject ?? [] },\n        ...coreProviders(options.resolver),\n      ],\n      exports: options.resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n}\n","import type { ToolHandler, ToolSpec } from '@dudousxd/nestjs-agent-core';\nimport type { FactoryProvider, Provider } from '@nestjs/common';\n\n/**\n * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up\n * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.\n */\nexport const AGENT_TOOL_BRAND = Symbol.for('@dudousxd/nestjs-agent:functional-tool');\n\n/** A tool expressed as data + handler (e.g. from `createExecuteSqlTool`), not an `@AiTool` class. */\nexport interface FunctionalTool {\n  spec: ToolSpec;\n  handler: ToolHandler;\n}\n\n/** A {@link FunctionalTool} carrying {@link AGENT_TOOL_BRAND} — what a provider resolves to. */\nexport interface BrandedFunctionalTool extends FunctionalTool {\n  readonly [AGENT_TOOL_BRAND]: true;\n}\n\nfunction brand(tool: FunctionalTool): BrandedFunctionalTool {\n  return { [AGENT_TOOL_BRAND]: true, spec: tool.spec, handler: tool.handler };\n}\n\n/** Narrows a provider instance to a branded functional tool for boot-time registration. */\nexport function isBrandedFunctionalTool(value: object): value is BrandedFunctionalTool {\n  return AGENT_TOOL_BRAND in value && 'spec' in value && 'handler' in value;\n}\n\n/**\n * Registers a functional tool declaratively — drop the returned provider in a module's `providers`\n * and `AiToolDiscoveryService` auto-registers it at boot. Each call uses a fresh, unique provide\n * token so the same tool can be provided many times without collisions.\n *\n * Two forms: a static tool (`useValue`) or a factory with `inject` for DI-resolved dependencies\n * (`useFactory`). Either way the resolved instance is branded with {@link AGENT_TOOL_BRAND}.\n */\nexport function provideAgentTool(tool: FunctionalTool): Provider;\nexport function provideAgentTool(\n  factory: (...deps: never[]) => FunctionalTool,\n  inject?: FactoryProvider['inject'],\n): Provider;\nexport function provideAgentTool(\n  factoryOrTool: FunctionalTool | ((...deps: never[]) => FunctionalTool),\n  inject?: FactoryProvider['inject'],\n): Provider {\n  const provide = Symbol('nestjs-agent:functional-tool-instance');\n  if (typeof factoryOrTool === 'function') {\n    return {\n      provide,\n      useFactory: (...deps: never[]) => brand(factoryOrTool(...deps)),\n      inject: inject ?? [],\n    };\n  }\n  return { provide, useValue: brand(factoryOrTool) };\n}\n\n/**\n * Registers a LIST of functional tools from one factory — for a producer whose tool count is only\n * known once its dependencies resolve (a catalog loaded from config, one tool per entry). The\n * factory's result is branded element by element; `AiToolDiscoveryService` registers each.\n */\nexport function provideAgentTools(\n  factory: (...deps: never[]) => readonly FunctionalTool[] | Promise<readonly FunctionalTool[]>,\n  inject?: FactoryProvider['inject'],\n): Provider {\n  return {\n    provide: Symbol('nestjs-agent:functional-tool-list'),\n    useFactory: async (...deps: never[]) => (await factory(...deps)).map(brand),\n    inject: inject ?? [],\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;ACOA,mBAA0C;AAC1C,oBAQO;;;ACTA,IAAMA,mBAAmBC,uBAAOC,IAAI,wCAAA;AAa3C,SAASC,MAAMC,MAAoB;AACjC,SAAO;IAAE,CAACJ,gBAAAA,GAAmB;IAAMK,MAAMD,KAAKC;IAAMC,SAASF,KAAKE;EAAQ;AAC5E;AAFSH;AA0CF,SAASI,kBACdC,SACAC,QAAkC;AAElC,SAAO;IACLC,SAASC,uBAAO,mCAAA;IAChBC,YAAY,iCAAUC,UAAmB,MAAML,QAAAA,GAAWK,IAAAA,GAAOC,IAAIC,KAAAA,GAAzD;IACZN,QAAQA,UAAU,CAAA;EACpB;AACF;AATgBF;;;;;;;;;;;;;;;;;AD1CT,IAAMS,gBAAgBC,uBAAOC,IAAI,sCAAA;AAGjC,IAAMC,gBAAgBF,uBAAOC,IAAI,sCAAA;AAGjC,IAAME,qBAAqB,iCAChCC,sBAAOL,aAAAA,GADyB;AAa3B,IAAeM,uBAAf,MAAeA;SAAAA;;;AAEtB;AAgDA,SAASC,kBAAkBC,UAAoC;AAC7D,MAAIA,aAAaC,OAAW,QAAO,CAAA;AACnC,SAAO;IACL,OAAOD,aAAa,aAChB;MAAEE,SAASJ;MAAsBK,UAAUH;IAAS,IACpD;MAAEE,SAASJ;MAAsBM,UAAUJ;IAAS;;AAE5D;AAPSD;AAST,SAASM,YACPC,SACAN,UAA0C;AAE1C,QAAM,EAAEO,SAASC,UAAU,GAAGC,KAAAA,IAASH;AACvC,SAAO;IACL,GAAGG;IACH,GAAIT,aAAaC,SACb;MAAES,gBAAgB,wBAACC,UAA6BX,SAASY,QAAQD,KAAAA,GAA/C;IAAsD,IACxE,CAAC;EACP;AACF;AAXSN;AAaT,SAASQ,cAAcb,UAAoC;AACzD,SAAO;IACL;MACEE,SAASV;MACTsB,YAAY,wBAACR,YAA+BA,QAAQC,eAAWQ,4BAAc,CAAA,CAAE,GAAnE;MACZC,QAAQ;QAACrB;;IACX;OACGI,kBAAkBC,QAAAA;;;IAGrBiB,kBACE,CAACX,SAA4BC,SAAkBW,mBAC7CC,yBAAWZ,SAASF,YAAYC,SAASY,UAAAA,CAAAA,GAC3C;MAACvB;MAAeH;MAAe;QAAE4B,OAAOtB;QAAsBuB,UAAU;MAAK;KAAE;;AAGrF;AAhBSR;AAkBT,IAAMS,UAAU;EAAC9B;EAAeG;;AAYzB,IAAM4B,mBAAN,MAAMA,kBAAAA;SAAAA;;;EACX,OAAOC,QAAQlB,UAAmC,CAAC,GAAkB;AACnE,UAAM,EAAEN,UAAU,GAAGS,KAAAA,IAASH;AAC9B,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRC,WAAW;QAAC;UAAEzB,SAASP;UAAeS,UAAUK;QAAK;WAAMI,cAAcb,QAAAA;;MACzE4B,SAAS5B,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IAC3D;EACF;EAEA,OAAO+B,aAAavB,SAAsD;AACxE,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRI,SAASxB,QAAQwB,WAAW,CAAA;MAC5BH,WAAW;QACT;UAAEzB,SAASP;UAAemB,YAAYR,QAAQQ;UAAYE,QAAQV,QAAQU,UAAU,CAAA;QAAG;WACpFH,cAAcP,QAAQN,QAAQ;;MAEnC4B,SAAStB,QAAQN,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IACnE;EACF;AACF;;;;;;ADnJA,0BAAc,8CAjBd;","names":["AGENT_TOOL_BRAND","Symbol","for","brand","tool","spec","handler","provideAgentTools","factory","inject","provide","Symbol","useFactory","deps","map","brand","GENUI_CATALOG","Symbol","for","GENUI_OPTIONS","InjectGenuiCatalog","Inject","GenuiCatalogResolver","resolverProviders","resolver","undefined","provide","useClass","useValue","toolOptions","options","catalog","_catalog","rest","resolveCatalog","scope","resolve","coreProviders","useFactory","defineCatalog","inject","provideAgentTools","perRequest","genuiTools","token","optional","EXPORTS","AgentGenuiModule","forRoot","module","global","providers","exports","forRootAsync","imports"]}
+{"version":3,"sources":["../../src/genui/index.ts","../../src/genui/agent-genui.module.ts","../../src/functional-tool.ts"],"sourcesContent":["/**\n * `@dudousxd/nestjs-agent/genui` — generative UI for NestJS: {@link AgentGenuiModule} registers the\n * tools that push catalog components, `GENUI_CATALOG` / `@InjectGenuiCatalog()` expose the catalog,\n * and {@link GenuiCatalogResolver} serves per-request (per-tenant) catalogs. The catalog itself —\n * `defineComponent`, `defineCatalog`, validation, text fallbacks — is re-exported from\n * `@dudousxd/nestjs-agent-core/genui`, the isomorphic entry a browser imports too.\n */\nexport {\n  AgentGenuiModule,\n  type AgentGenuiModuleAsyncOptions,\n  type AgentGenuiModuleOptions,\n  type AgentGenuiOptions,\n  GENUI_CATALOG,\n  GENUI_OPTIONS,\n  GenuiCatalogResolver,\n  InjectGenuiCatalog,\n} from './agent-genui.module.js';\nexport * from '@dudousxd/nestjs-agent-core/genui';\n","import type { ToolPresentation } from '@dudousxd/nestjs-agent-core';\nimport type {\n  Catalog,\n  GenuiCatalogScope,\n  GenuiToolsOptions,\n  TreeLimits,\n} from '@dudousxd/nestjs-agent-core/genui';\nimport { defineCatalog, genuiTools } from '@dudousxd/nestjs-agent-core/genui';\nimport {\n  type DynamicModule,\n  type FactoryProvider,\n  Inject,\n  Module,\n  type ModuleMetadata,\n  type Provider,\n  type Type,\n} from '@nestjs/common';\nimport { provideAgentTools } from '../functional-tool.js';\n\n/** The app's genui catalog — `@InjectGenuiCatalog()` it anywhere; `overrideProvider` it in tests. */\nexport const GENUI_CATALOG = Symbol.for('@dudousxd/nestjs-agent:genui-catalog');\n\n/** The resolved {@link AgentGenuiOptions} (without the resolver). */\nexport const GENUI_OPTIONS = Symbol.for('@dudousxd/nestjs-agent:genui-options');\n\n/** Inject the app's genui catalog ({@link GENUI_CATALOG}). */\nexport const InjectGenuiCatalog = (): ParameterDecorator & PropertyDecorator =>\n  Inject(GENUI_CATALOG);\n\n/**\n * Picks the catalog for ONE request — a tenant's own, versioned components. Consulted when a genui\n * call is validated and when the turn's tool list is described to the model, so components can\n * change without rebuilding tools at boot. Cache in here if resolving costs a round trip: it runs\n * once per turn per genui tool, and once per call.\n *\n * Provide it through `AgentGenuiModule.forRoot({ resolver })` (a class, resolved with DI, or an\n * instance); it is then injectable, and replaceable in a test with\n * `overrideProvider(GenuiCatalogResolver)`.\n */\nexport abstract class GenuiCatalogResolver {\n  abstract resolve(scope: GenuiCatalogScope): Catalog | Promise<Catalog>;\n}\n\n/** What {@link AgentGenuiModule} builds tools from. */\nexport interface AgentGenuiOptions {\n  /**\n   * The catalog. With a {@link GenuiCatalogResolver} it is the boot-time one — it names the\n   * per-component tools — and may be empty. Default: an empty catalog.\n   */\n  catalog?: Catalog;\n  /** `per-component` (default): one `ui__show_<snake>` tool per component. `tree`: one tool taking a composed tree. */\n  mode?: 'per-component' | 'tree';\n  /** End the model's turn once a genui call succeeds (no narrating follow-up call). */\n  terminal?: boolean;\n  /** Tool name in `tree` mode. Default `ui__render`. */\n  treeToolName?: string;\n  /** Text prepended to the tree tool's description. */\n  treeInstructions?: string;\n  treeLimits?: TreeLimits;\n  /** Tool-name prefix in `per-component` mode. Default `ui__show_`. */\n  namePrefix?: string;\n  /**\n   * Also register ONE generic tool taking `{ component, props }`, validated against the request's\n   * catalog — how a model reaches a tenant's own components, which no boot-time tool names. `true`\n   * names it `ui__show`.\n   */\n  showTool?: boolean | string;\n  /** Text prepended to the show tool's description. */\n  showInstructions?: string;\n  /** Roles allowed to call the tools. Undefined → the roles policy default. */\n  roles?: string[];\n  /** Override the generated presentation per component (or per tree / show tool name). */\n  presentation?: (component: string) => ToolPresentation | undefined;\n}\n\ntype ResolverOption = Type<GenuiCatalogResolver> | GenuiCatalogResolver;\n\nexport interface AgentGenuiModuleOptions extends AgentGenuiOptions {\n  /** Per-request catalogs. A class is instantiated with DI (its dependencies must be global or exported to the root). */\n  resolver?: ResolverOption;\n}\n\nexport interface AgentGenuiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {\n  inject?: FactoryProvider['inject'];\n  useFactory: (...deps: any[]) => AgentGenuiOptions | Promise<AgentGenuiOptions>;\n  /** Per-request catalogs. A class resolves its dependencies from `imports`. */\n  resolver?: ResolverOption;\n}\n\nfunction resolverProviders(resolver: ResolverOption | undefined): Provider[] {\n  if (resolver === undefined) return [];\n  return [\n    typeof resolver === 'function'\n      ? { provide: GenuiCatalogResolver, useClass: resolver }\n      : { provide: GenuiCatalogResolver, useValue: resolver },\n  ];\n}\n\nfunction toolOptions(\n  options: AgentGenuiOptions,\n  resolver: GenuiCatalogResolver | undefined,\n): GenuiToolsOptions {\n  const { catalog: _catalog, ...rest } = options;\n  return {\n    ...rest,\n    ...(resolver !== undefined\n      ? { resolveCatalog: (scope: GenuiCatalogScope) => resolver.resolve(scope) }\n      : {}),\n  };\n}\n\nfunction coreProviders(resolver: ResolverOption | undefined): Provider[] {\n  return [\n    {\n      provide: GENUI_CATALOG,\n      useFactory: (options: AgentGenuiOptions) => options.catalog ?? defineCatalog([]),\n      inject: [GENUI_OPTIONS],\n    },\n    ...resolverProviders(resolver),\n    // The generated tools, registered by the agent module's discovery like any `provideAgentTool`.\n    // Built from the injected catalog, so `overrideProvider(GENUI_CATALOG)` changes them too.\n    provideAgentTools(\n      (options: AgentGenuiOptions, catalog: Catalog, perRequest?: GenuiCatalogResolver) =>\n        genuiTools(catalog, toolOptions(options, perRequest)),\n      [GENUI_OPTIONS, GENUI_CATALOG, { token: GenuiCatalogResolver, optional: true }],\n    ),\n  ];\n}\n\nconst EXPORTS = [GENUI_CATALOG, GENUI_OPTIONS];\n\n/**\n * Generative UI for the agent: registers the tools that let the model push catalog components\n * (`ui__show_<component>`, or one tree tool, or the generic `ui__show`), and makes the catalog\n * injectable. Global, like `AgentModule`; import it once, next to it.\n *\n * ```ts\n * AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true })\n * ```\n */\n@Module({})\nexport class AgentGenuiModule {\n  static forRoot(options: AgentGenuiModuleOptions = {}): DynamicModule {\n    const { resolver, ...rest } = options;\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      providers: [{ provide: GENUI_OPTIONS, useValue: rest }, ...coreProviders(resolver)],\n      exports: resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n\n  static forRootAsync(options: AgentGenuiModuleAsyncOptions): DynamicModule {\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      imports: options.imports ?? [],\n      providers: [\n        { provide: GENUI_OPTIONS, useFactory: options.useFactory, inject: options.inject ?? [] },\n        ...coreProviders(options.resolver),\n      ],\n      exports: options.resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n}\n","import {\n  type FunctionalToolDefinition,\n  type ToolHandler,\n  type ToolSpec,\n  createFunctionalTool,\n} from '@dudousxd/nestjs-agent-core';\nimport type { FactoryProvider, Provider } from '@nestjs/common';\n\n/**\n * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up\n * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.\n */\nexport const AGENT_TOOL_BRAND = Symbol.for('@dudousxd/nestjs-agent:functional-tool');\n\n/** A tool expressed as data + handler (e.g. from `createExecuteSqlTool`), not an `@AiTool` class. */\nexport interface FunctionalTool {\n  spec: ToolSpec;\n  handler: ToolHandler;\n}\n\n/** A {@link FunctionalTool} carrying {@link AGENT_TOOL_BRAND} — what a provider resolves to. */\nexport interface BrandedFunctionalTool extends FunctionalTool {\n  readonly [AGENT_TOOL_BRAND]: true;\n}\n\nfunction brand(tool: FunctionalTool): BrandedFunctionalTool {\n  return { [AGENT_TOOL_BRAND]: true, spec: tool.spec, handler: tool.handler };\n}\n\n/** Narrows a provider instance to a branded functional tool for boot-time registration. */\nexport function isBrandedFunctionalTool(value: object): value is BrandedFunctionalTool {\n  return AGENT_TOOL_BRAND in value && 'spec' in value && 'handler' in value;\n}\n\n/**\n * Registers a functional tool declaratively — drop the returned provider in a module's `providers`\n * and `AiToolDiscoveryService` auto-registers it at boot. Each call uses a fresh, unique provide\n * token so the same tool can be provided many times without collisions.\n *\n * Two forms: a static tool (`useValue`) or a factory with `inject` for DI-resolved dependencies\n * (`useFactory`). Either way the resolved instance is branded with {@link AGENT_TOOL_BRAND}.\n */\nexport function provideAgentTool(tool: FunctionalTool): Provider;\nexport function provideAgentTool(\n  factory: (...deps: never[]) => FunctionalTool,\n  inject?: FactoryProvider['inject'],\n): Provider;\nexport function provideAgentTool(\n  factoryOrTool: FunctionalTool | ((...deps: never[]) => FunctionalTool),\n  inject?: FactoryProvider['inject'],\n): Provider {\n  const provide = Symbol('nestjs-agent:functional-tool-instance');\n  if (typeof factoryOrTool === 'function') {\n    return {\n      provide,\n      useFactory: (...deps: never[]) => brand(factoryOrTool(...deps)),\n      inject: inject ?? [],\n    };\n  }\n  return { provide, useValue: brand(factoryOrTool) };\n}\n\n/**\n * Registers a LIST of functional tools from one factory — for a producer whose tool count is only\n * known once its dependencies resolve (a catalog loaded from config, one tool per entry). The\n * factory's result is branded element by element; `AiToolDiscoveryService` registers each.\n */\nexport function provideAgentTools(\n  factory: (...deps: never[]) => readonly FunctionalTool[] | Promise<readonly FunctionalTool[]>,\n  inject?: FactoryProvider['inject'],\n): Provider {\n  return {\n    provide: Symbol('nestjs-agent:functional-tool-list'),\n    useFactory: async (...deps: never[]) => (await factory(...deps)).map(brand),\n    inject: inject ?? [],\n  };\n}\n\n/** Author a functional tool with inferred Standard Schema input and domain output. */\nexport const defineTool = createFunctionalTool;\nexport type { FunctionalToolDefinition };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;ACOA,mBAA0C;AAC1C,oBAQO;;;AChBP,+BAKO;AAOA,IAAMA,mBAAmBC,uBAAOC,IAAI,wCAAA;AAa3C,SAASC,MAAMC,MAAoB;AACjC,SAAO;IAAE,CAACJ,gBAAAA,GAAmB;IAAMK,MAAMD,KAAKC;IAAMC,SAASF,KAAKE;EAAQ;AAC5E;AAFSH;AA0CF,SAASI,kBACdC,SACAC,QAAkC;AAElC,SAAO;IACLC,SAASC,uBAAO,mCAAA;IAChBC,YAAY,iCAAUC,UAAmB,MAAML,QAAAA,GAAWK,IAAAA,GAAOC,IAAIC,KAAAA,GAAzD;IACZN,QAAQA,UAAU,CAAA;EACpB;AACF;AATgBF;;;;;;;;;;;;;;;;;AD/CT,IAAMS,gBAAgBC,uBAAOC,IAAI,sCAAA;AAGjC,IAAMC,gBAAgBF,uBAAOC,IAAI,sCAAA;AAGjC,IAAME,qBAAqB,iCAChCC,sBAAOL,aAAAA,GADyB;AAa3B,IAAeM,uBAAf,MAAeA;SAAAA;;;AAEtB;AAgDA,SAASC,kBAAkBC,UAAoC;AAC7D,MAAIA,aAAaC,OAAW,QAAO,CAAA;AACnC,SAAO;IACL,OAAOD,aAAa,aAChB;MAAEE,SAASJ;MAAsBK,UAAUH;IAAS,IACpD;MAAEE,SAASJ;MAAsBM,UAAUJ;IAAS;;AAE5D;AAPSD;AAST,SAASM,YACPC,SACAN,UAA0C;AAE1C,QAAM,EAAEO,SAASC,UAAU,GAAGC,KAAAA,IAASH;AACvC,SAAO;IACL,GAAGG;IACH,GAAIT,aAAaC,SACb;MAAES,gBAAgB,wBAACC,UAA6BX,SAASY,QAAQD,KAAAA,GAA/C;IAAsD,IACxE,CAAC;EACP;AACF;AAXSN;AAaT,SAASQ,cAAcb,UAAoC;AACzD,SAAO;IACL;MACEE,SAASV;MACTsB,YAAY,wBAACR,YAA+BA,QAAQC,eAAWQ,4BAAc,CAAA,CAAE,GAAnE;MACZC,QAAQ;QAACrB;;IACX;OACGI,kBAAkBC,QAAAA;;;IAGrBiB,kBACE,CAACX,SAA4BC,SAAkBW,mBAC7CC,yBAAWZ,SAASF,YAAYC,SAASY,UAAAA,CAAAA,GAC3C;MAACvB;MAAeH;MAAe;QAAE4B,OAAOtB;QAAsBuB,UAAU;MAAK;KAAE;;AAGrF;AAhBSR;AAkBT,IAAMS,UAAU;EAAC9B;EAAeG;;AAYzB,IAAM4B,mBAAN,MAAMA,kBAAAA;SAAAA;;;EACX,OAAOC,QAAQlB,UAAmC,CAAC,GAAkB;AACnE,UAAM,EAAEN,UAAU,GAAGS,KAAAA,IAASH;AAC9B,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRC,WAAW;QAAC;UAAEzB,SAASP;UAAeS,UAAUK;QAAK;WAAMI,cAAcb,QAAAA;;MACzE4B,SAAS5B,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IAC3D;EACF;EAEA,OAAO+B,aAAavB,SAAsD;AACxE,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRI,SAASxB,QAAQwB,WAAW,CAAA;MAC5BH,WAAW;QACT;UAAEzB,SAASP;UAAemB,YAAYR,QAAQQ;UAAYE,QAAQV,QAAQU,UAAU,CAAA;QAAG;WACpFH,cAAcP,QAAQN,QAAQ;;MAEnC4B,SAAStB,QAAQN,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IACnE;EACF;AACF;;;;;;ADnJA,0BAAc,8CAjBd;","names":["AGENT_TOOL_BRAND","Symbol","for","brand","tool","spec","handler","provideAgentTools","factory","inject","provide","Symbol","useFactory","deps","map","brand","GENUI_CATALOG","Symbol","for","GENUI_OPTIONS","InjectGenuiCatalog","Inject","GenuiCatalogResolver","resolverProviders","resolver","undefined","provide","useClass","useValue","toolOptions","options","catalog","_catalog","rest","resolveCatalog","scope","resolve","coreProviders","useFactory","defineCatalog","inject","provideAgentTools","perRequest","genuiTools","token","optional","EXPORTS","AgentGenuiModule","forRoot","module","global","providers","exports","forRootAsync","imports"]}

package/dist/genui/index.js

@@ -6,6 +6,7 @@ import { defineCatalog, genuiTools } from "@dudousxd/nestjs-agent-core/genui";
 import { Inject, Module } from "@nestjs/common";
 
 // src/functional-tool.ts
+import { createFunctionalTool } from "@dudousxd/nestjs-agent-core";
 var AGENT_TOOL_BRAND = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:functional-tool");
 function brand(tool) {
   return {

package/dist/genui/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/genui/agent-genui.module.ts","../../src/functional-tool.ts","../../src/genui/index.ts"],"sourcesContent":["import type { ToolPresentation } from '@dudousxd/nestjs-agent-core';\nimport type {\n  Catalog,\n  GenuiCatalogScope,\n  GenuiToolsOptions,\n  TreeLimits,\n} from '@dudousxd/nestjs-agent-core/genui';\nimport { defineCatalog, genuiTools } from '@dudousxd/nestjs-agent-core/genui';\nimport {\n  type DynamicModule,\n  type FactoryProvider,\n  Inject,\n  Module,\n  type ModuleMetadata,\n  type Provider,\n  type Type,\n} from '@nestjs/common';\nimport { provideAgentTools } from '../functional-tool.js';\n\n/** The app's genui catalog — `@InjectGenuiCatalog()` it anywhere; `overrideProvider` it in tests. */\nexport const GENUI_CATALOG = Symbol.for('@dudousxd/nestjs-agent:genui-catalog');\n\n/** The resolved {@link AgentGenuiOptions} (without the resolver). */\nexport const GENUI_OPTIONS = Symbol.for('@dudousxd/nestjs-agent:genui-options');\n\n/** Inject the app's genui catalog ({@link GENUI_CATALOG}). */\nexport const InjectGenuiCatalog = (): ParameterDecorator & PropertyDecorator =>\n  Inject(GENUI_CATALOG);\n\n/**\n * Picks the catalog for ONE request — a tenant's own, versioned components. Consulted when a genui\n * call is validated and when the turn's tool list is described to the model, so components can\n * change without rebuilding tools at boot. Cache in here if resolving costs a round trip: it runs\n * once per turn per genui tool, and once per call.\n *\n * Provide it through `AgentGenuiModule.forRoot({ resolver })` (a class, resolved with DI, or an\n * instance); it is then injectable, and replaceable in a test with\n * `overrideProvider(GenuiCatalogResolver)`.\n */\nexport abstract class GenuiCatalogResolver {\n  abstract resolve(scope: GenuiCatalogScope): Catalog | Promise<Catalog>;\n}\n\n/** What {@link AgentGenuiModule} builds tools from. */\nexport interface AgentGenuiOptions {\n  /**\n   * The catalog. With a {@link GenuiCatalogResolver} it is the boot-time one — it names the\n   * per-component tools — and may be empty. Default: an empty catalog.\n   */\n  catalog?: Catalog;\n  /** `per-component` (default): one `ui__show_<snake>` tool per component. `tree`: one tool taking a composed tree. */\n  mode?: 'per-component' | 'tree';\n  /** End the model's turn once a genui call succeeds (no narrating follow-up call). */\n  terminal?: boolean;\n  /** Tool name in `tree` mode. Default `ui__render`. */\n  treeToolName?: string;\n  /** Text prepended to the tree tool's description. */\n  treeInstructions?: string;\n  treeLimits?: TreeLimits;\n  /** Tool-name prefix in `per-component` mode. Default `ui__show_`. */\n  namePrefix?: string;\n  /**\n   * Also register ONE generic tool taking `{ component, props }`, validated against the request's\n   * catalog — how a model reaches a tenant's own components, which no boot-time tool names. `true`\n   * names it `ui__show`.\n   */\n  showTool?: boolean | string;\n  /** Text prepended to the show tool's description. */\n  showInstructions?: string;\n  /** Roles allowed to call the tools. Undefined → the roles policy default. */\n  roles?: string[];\n  /** Override the generated presentation per component (or per tree / show tool name). */\n  presentation?: (component: string) => ToolPresentation | undefined;\n}\n\ntype ResolverOption = Type<GenuiCatalogResolver> | GenuiCatalogResolver;\n\nexport interface AgentGenuiModuleOptions extends AgentGenuiOptions {\n  /** Per-request catalogs. A class is instantiated with DI (its dependencies must be global or exported to the root). */\n  resolver?: ResolverOption;\n}\n\nexport interface AgentGenuiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {\n  inject?: FactoryProvider['inject'];\n  useFactory: (...deps: any[]) => AgentGenuiOptions | Promise<AgentGenuiOptions>;\n  /** Per-request catalogs. A class resolves its dependencies from `imports`. */\n  resolver?: ResolverOption;\n}\n\nfunction resolverProviders(resolver: ResolverOption | undefined): Provider[] {\n  if (resolver === undefined) return [];\n  return [\n    typeof resolver === 'function'\n      ? { provide: GenuiCatalogResolver, useClass: resolver }\n      : { provide: GenuiCatalogResolver, useValue: resolver },\n  ];\n}\n\nfunction toolOptions(\n  options: AgentGenuiOptions,\n  resolver: GenuiCatalogResolver | undefined,\n): GenuiToolsOptions {\n  const { catalog: _catalog, ...rest } = options;\n  return {\n    ...rest,\n    ...(resolver !== undefined\n      ? { resolveCatalog: (scope: GenuiCatalogScope) => resolver.resolve(scope) }\n      : {}),\n  };\n}\n\nfunction coreProviders(resolver: ResolverOption | undefined): Provider[] {\n  return [\n    {\n      provide: GENUI_CATALOG,\n      useFactory: (options: AgentGenuiOptions) => options.catalog ?? defineCatalog([]),\n      inject: [GENUI_OPTIONS],\n    },\n    ...resolverProviders(resolver),\n    // The generated tools, registered by the agent module's discovery like any `provideAgentTool`.\n    // Built from the injected catalog, so `overrideProvider(GENUI_CATALOG)` changes them too.\n    provideAgentTools(\n      (options: AgentGenuiOptions, catalog: Catalog, perRequest?: GenuiCatalogResolver) =>\n        genuiTools(catalog, toolOptions(options, perRequest)),\n      [GENUI_OPTIONS, GENUI_CATALOG, { token: GenuiCatalogResolver, optional: true }],\n    ),\n  ];\n}\n\nconst EXPORTS = [GENUI_CATALOG, GENUI_OPTIONS];\n\n/**\n * Generative UI for the agent: registers the tools that let the model push catalog components\n * (`ui__show_<component>`, or one tree tool, or the generic `ui__show`), and makes the catalog\n * injectable. Global, like `AgentModule`; import it once, next to it.\n *\n * ```ts\n * AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true })\n * ```\n */\n@Module({})\nexport class AgentGenuiModule {\n  static forRoot(options: AgentGenuiModuleOptions = {}): DynamicModule {\n    const { resolver, ...rest } = options;\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      providers: [{ provide: GENUI_OPTIONS, useValue: rest }, ...coreProviders(resolver)],\n      exports: resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n\n  static forRootAsync(options: AgentGenuiModuleAsyncOptions): DynamicModule {\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      imports: options.imports ?? [],\n      providers: [\n        { provide: GENUI_OPTIONS, useFactory: options.useFactory, inject: options.inject ?? [] },\n        ...coreProviders(options.resolver),\n      ],\n      exports: options.resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n}\n","import type { ToolHandler, ToolSpec } from '@dudousxd/nestjs-agent-core';\nimport type { FactoryProvider, Provider } from '@nestjs/common';\n\n/**\n * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up\n * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.\n */\nexport const AGENT_TOOL_BRAND = Symbol.for('@dudousxd/nestjs-agent:functional-tool');\n\n/** A tool expressed as data + handler (e.g. from `createExecuteSqlTool`), not an `@AiTool` class. */\nexport interface FunctionalTool {\n  spec: ToolSpec;\n  handler: ToolHandler;\n}\n\n/** A {@link FunctionalTool} carrying {@link AGENT_TOOL_BRAND} — what a provider resolves to. */\nexport interface BrandedFunctionalTool extends FunctionalTool {\n  readonly [AGENT_TOOL_BRAND]: true;\n}\n\nfunction brand(tool: FunctionalTool): BrandedFunctionalTool {\n  return { [AGENT_TOOL_BRAND]: true, spec: tool.spec, handler: tool.handler };\n}\n\n/** Narrows a provider instance to a branded functional tool for boot-time registration. */\nexport function isBrandedFunctionalTool(value: object): value is BrandedFunctionalTool {\n  return AGENT_TOOL_BRAND in value && 'spec' in value && 'handler' in value;\n}\n\n/**\n * Registers a functional tool declaratively — drop the returned provider in a module's `providers`\n * and `AiToolDiscoveryService` auto-registers it at boot. Each call uses a fresh, unique provide\n * token so the same tool can be provided many times without collisions.\n *\n * Two forms: a static tool (`useValue`) or a factory with `inject` for DI-resolved dependencies\n * (`useFactory`). Either way the resolved instance is branded with {@link AGENT_TOOL_BRAND}.\n */\nexport function provideAgentTool(tool: FunctionalTool): Provider;\nexport function provideAgentTool(\n  factory: (...deps: never[]) => FunctionalTool,\n  inject?: FactoryProvider['inject'],\n): Provider;\nexport function provideAgentTool(\n  factoryOrTool: FunctionalTool | ((...deps: never[]) => FunctionalTool),\n  inject?: FactoryProvider['inject'],\n): Provider {\n  const provide = Symbol('nestjs-agent:functional-tool-instance');\n  if (typeof factoryOrTool === 'function') {\n    return {\n      provide,\n      useFactory: (...deps: never[]) => brand(factoryOrTool(...deps)),\n      inject: inject ?? [],\n    };\n  }\n  return { provide, useValue: brand(factoryOrTool) };\n}\n\n/**\n * Registers a LIST of functional tools from one factory — for a producer whose tool count is only\n * known once its dependencies resolve (a catalog loaded from config, one tool per entry). The\n * factory's result is branded element by element; `AiToolDiscoveryService` registers each.\n */\nexport function provideAgentTools(\n  factory: (...deps: never[]) => readonly FunctionalTool[] | Promise<readonly FunctionalTool[]>,\n  inject?: FactoryProvider['inject'],\n): Provider {\n  return {\n    provide: Symbol('nestjs-agent:functional-tool-list'),\n    useFactory: async (...deps: never[]) => (await factory(...deps)).map(brand),\n    inject: inject ?? [],\n  };\n}\n","/**\n * `@dudousxd/nestjs-agent/genui` — generative UI for NestJS: {@link AgentGenuiModule} registers the\n * tools that push catalog components, `GENUI_CATALOG` / `@InjectGenuiCatalog()` expose the catalog,\n * and {@link GenuiCatalogResolver} serves per-request (per-tenant) catalogs. The catalog itself —\n * `defineComponent`, `defineCatalog`, validation, text fallbacks — is re-exported from\n * `@dudousxd/nestjs-agent-core/genui`, the isomorphic entry a browser imports too.\n */\nexport {\n  AgentGenuiModule,\n  type AgentGenuiModuleAsyncOptions,\n  type AgentGenuiModuleOptions,\n  type AgentGenuiOptions,\n  GENUI_CATALOG,\n  GENUI_OPTIONS,\n  GenuiCatalogResolver,\n  InjectGenuiCatalog,\n} from './agent-genui.module.js';\nexport * from '@dudousxd/nestjs-agent-core/genui';\n"],"mappings":";;;;AAOA,SAASA,eAAeC,kBAAkB;AAC1C,SAGEC,QACAC,cAIK;;;ACTA,IAAMC,mBAAmBC,uBAAOC,IAAI,wCAAA;AAa3C,SAASC,MAAMC,MAAoB;AACjC,SAAO;IAAE,CAACJ,gBAAAA,GAAmB;IAAMK,MAAMD,KAAKC;IAAMC,SAASF,KAAKE;EAAQ;AAC5E;AAFSH;AA0CF,SAASI,kBACdC,SACAC,QAAkC;AAElC,SAAO;IACLC,SAASC,uBAAO,mCAAA;IAChBC,YAAY,iCAAUC,UAAmB,MAAML,QAAAA,GAAWK,IAAAA,GAAOC,IAAIC,KAAAA,GAAzD;IACZN,QAAQA,UAAU,CAAA;EACpB;AACF;AATgBF;;;;;;;;;;;;;;;;;AD1CT,IAAMS,gBAAgBC,uBAAOC,IAAI,sCAAA;AAGjC,IAAMC,gBAAgBF,uBAAOC,IAAI,sCAAA;AAGjC,IAAME,qBAAqB,6BAChCC,OAAOL,aAAAA,GADyB;AAa3B,IAAeM,uBAAf,MAAeA;SAAAA;;;AAEtB;AAgDA,SAASC,kBAAkBC,UAAoC;AAC7D,MAAIA,aAAaC,OAAW,QAAO,CAAA;AACnC,SAAO;IACL,OAAOD,aAAa,aAChB;MAAEE,SAASJ;MAAsBK,UAAUH;IAAS,IACpD;MAAEE,SAASJ;MAAsBM,UAAUJ;IAAS;;AAE5D;AAPSD;AAST,SAASM,YACPC,SACAN,UAA0C;AAE1C,QAAM,EAAEO,SAASC,UAAU,GAAGC,KAAAA,IAASH;AACvC,SAAO;IACL,GAAGG;IACH,GAAIT,aAAaC,SACb;MAAES,gBAAgB,wBAACC,UAA6BX,SAASY,QAAQD,KAAAA,GAA/C;IAAsD,IACxE,CAAC;EACP;AACF;AAXSN;AAaT,SAASQ,cAAcb,UAAoC;AACzD,SAAO;IACL;MACEE,SAASV;MACTsB,YAAY,wBAACR,YAA+BA,QAAQC,WAAWQ,cAAc,CAAA,CAAE,GAAnE;MACZC,QAAQ;QAACrB;;IACX;OACGI,kBAAkBC,QAAAA;;;IAGrBiB,kBACE,CAACX,SAA4BC,SAAkBW,eAC7CC,WAAWZ,SAASF,YAAYC,SAASY,UAAAA,CAAAA,GAC3C;MAACvB;MAAeH;MAAe;QAAE4B,OAAOtB;QAAsBuB,UAAU;MAAK;KAAE;;AAGrF;AAhBSR;AAkBT,IAAMS,UAAU;EAAC9B;EAAeG;;AAYzB,IAAM4B,mBAAN,MAAMA,kBAAAA;SAAAA;;;EACX,OAAOC,QAAQlB,UAAmC,CAAC,GAAkB;AACnE,UAAM,EAAEN,UAAU,GAAGS,KAAAA,IAASH;AAC9B,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRC,WAAW;QAAC;UAAEzB,SAASP;UAAeS,UAAUK;QAAK;WAAMI,cAAcb,QAAAA;;MACzE4B,SAAS5B,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IAC3D;EACF;EAEA,OAAO+B,aAAavB,SAAsD;AACxE,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRI,SAASxB,QAAQwB,WAAW,CAAA;MAC5BH,WAAW;QACT;UAAEzB,SAASP;UAAemB,YAAYR,QAAQQ;UAAYE,QAAQV,QAAQU,UAAU,CAAA;QAAG;WACpFH,cAAcP,QAAQN,QAAQ;;MAEnC4B,SAAStB,QAAQN,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IACnE;EACF;AACF;;;;;;AEnJA,cAAc;","names":["defineCatalog","genuiTools","Inject","Module","AGENT_TOOL_BRAND","Symbol","for","brand","tool","spec","handler","provideAgentTools","factory","inject","provide","Symbol","useFactory","deps","map","brand","GENUI_CATALOG","Symbol","for","GENUI_OPTIONS","InjectGenuiCatalog","Inject","GenuiCatalogResolver","resolverProviders","resolver","undefined","provide","useClass","useValue","toolOptions","options","catalog","_catalog","rest","resolveCatalog","scope","resolve","coreProviders","useFactory","defineCatalog","inject","provideAgentTools","perRequest","genuiTools","token","optional","EXPORTS","AgentGenuiModule","forRoot","module","global","providers","exports","forRootAsync","imports"]}
+{"version":3,"sources":["../../src/genui/agent-genui.module.ts","../../src/functional-tool.ts","../../src/genui/index.ts"],"sourcesContent":["import type { ToolPresentation } from '@dudousxd/nestjs-agent-core';\nimport type {\n  Catalog,\n  GenuiCatalogScope,\n  GenuiToolsOptions,\n  TreeLimits,\n} from '@dudousxd/nestjs-agent-core/genui';\nimport { defineCatalog, genuiTools } from '@dudousxd/nestjs-agent-core/genui';\nimport {\n  type DynamicModule,\n  type FactoryProvider,\n  Inject,\n  Module,\n  type ModuleMetadata,\n  type Provider,\n  type Type,\n} from '@nestjs/common';\nimport { provideAgentTools } from '../functional-tool.js';\n\n/** The app's genui catalog — `@InjectGenuiCatalog()` it anywhere; `overrideProvider` it in tests. */\nexport const GENUI_CATALOG = Symbol.for('@dudousxd/nestjs-agent:genui-catalog');\n\n/** The resolved {@link AgentGenuiOptions} (without the resolver). */\nexport const GENUI_OPTIONS = Symbol.for('@dudousxd/nestjs-agent:genui-options');\n\n/** Inject the app's genui catalog ({@link GENUI_CATALOG}). */\nexport const InjectGenuiCatalog = (): ParameterDecorator & PropertyDecorator =>\n  Inject(GENUI_CATALOG);\n\n/**\n * Picks the catalog for ONE request — a tenant's own, versioned components. Consulted when a genui\n * call is validated and when the turn's tool list is described to the model, so components can\n * change without rebuilding tools at boot. Cache in here if resolving costs a round trip: it runs\n * once per turn per genui tool, and once per call.\n *\n * Provide it through `AgentGenuiModule.forRoot({ resolver })` (a class, resolved with DI, or an\n * instance); it is then injectable, and replaceable in a test with\n * `overrideProvider(GenuiCatalogResolver)`.\n */\nexport abstract class GenuiCatalogResolver {\n  abstract resolve(scope: GenuiCatalogScope): Catalog | Promise<Catalog>;\n}\n\n/** What {@link AgentGenuiModule} builds tools from. */\nexport interface AgentGenuiOptions {\n  /**\n   * The catalog. With a {@link GenuiCatalogResolver} it is the boot-time one — it names the\n   * per-component tools — and may be empty. Default: an empty catalog.\n   */\n  catalog?: Catalog;\n  /** `per-component` (default): one `ui__show_<snake>` tool per component. `tree`: one tool taking a composed tree. */\n  mode?: 'per-component' | 'tree';\n  /** End the model's turn once a genui call succeeds (no narrating follow-up call). */\n  terminal?: boolean;\n  /** Tool name in `tree` mode. Default `ui__render`. */\n  treeToolName?: string;\n  /** Text prepended to the tree tool's description. */\n  treeInstructions?: string;\n  treeLimits?: TreeLimits;\n  /** Tool-name prefix in `per-component` mode. Default `ui__show_`. */\n  namePrefix?: string;\n  /**\n   * Also register ONE generic tool taking `{ component, props }`, validated against the request's\n   * catalog — how a model reaches a tenant's own components, which no boot-time tool names. `true`\n   * names it `ui__show`.\n   */\n  showTool?: boolean | string;\n  /** Text prepended to the show tool's description. */\n  showInstructions?: string;\n  /** Roles allowed to call the tools. Undefined → the roles policy default. */\n  roles?: string[];\n  /** Override the generated presentation per component (or per tree / show tool name). */\n  presentation?: (component: string) => ToolPresentation | undefined;\n}\n\ntype ResolverOption = Type<GenuiCatalogResolver> | GenuiCatalogResolver;\n\nexport interface AgentGenuiModuleOptions extends AgentGenuiOptions {\n  /** Per-request catalogs. A class is instantiated with DI (its dependencies must be global or exported to the root). */\n  resolver?: ResolverOption;\n}\n\nexport interface AgentGenuiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {\n  inject?: FactoryProvider['inject'];\n  useFactory: (...deps: any[]) => AgentGenuiOptions | Promise<AgentGenuiOptions>;\n  /** Per-request catalogs. A class resolves its dependencies from `imports`. */\n  resolver?: ResolverOption;\n}\n\nfunction resolverProviders(resolver: ResolverOption | undefined): Provider[] {\n  if (resolver === undefined) return [];\n  return [\n    typeof resolver === 'function'\n      ? { provide: GenuiCatalogResolver, useClass: resolver }\n      : { provide: GenuiCatalogResolver, useValue: resolver },\n  ];\n}\n\nfunction toolOptions(\n  options: AgentGenuiOptions,\n  resolver: GenuiCatalogResolver | undefined,\n): GenuiToolsOptions {\n  const { catalog: _catalog, ...rest } = options;\n  return {\n    ...rest,\n    ...(resolver !== undefined\n      ? { resolveCatalog: (scope: GenuiCatalogScope) => resolver.resolve(scope) }\n      : {}),\n  };\n}\n\nfunction coreProviders(resolver: ResolverOption | undefined): Provider[] {\n  return [\n    {\n      provide: GENUI_CATALOG,\n      useFactory: (options: AgentGenuiOptions) => options.catalog ?? defineCatalog([]),\n      inject: [GENUI_OPTIONS],\n    },\n    ...resolverProviders(resolver),\n    // The generated tools, registered by the agent module's discovery like any `provideAgentTool`.\n    // Built from the injected catalog, so `overrideProvider(GENUI_CATALOG)` changes them too.\n    provideAgentTools(\n      (options: AgentGenuiOptions, catalog: Catalog, perRequest?: GenuiCatalogResolver) =>\n        genuiTools(catalog, toolOptions(options, perRequest)),\n      [GENUI_OPTIONS, GENUI_CATALOG, { token: GenuiCatalogResolver, optional: true }],\n    ),\n  ];\n}\n\nconst EXPORTS = [GENUI_CATALOG, GENUI_OPTIONS];\n\n/**\n * Generative UI for the agent: registers the tools that let the model push catalog components\n * (`ui__show_<component>`, or one tree tool, or the generic `ui__show`), and makes the catalog\n * injectable. Global, like `AgentModule`; import it once, next to it.\n *\n * ```ts\n * AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true })\n * ```\n */\n@Module({})\nexport class AgentGenuiModule {\n  static forRoot(options: AgentGenuiModuleOptions = {}): DynamicModule {\n    const { resolver, ...rest } = options;\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      providers: [{ provide: GENUI_OPTIONS, useValue: rest }, ...coreProviders(resolver)],\n      exports: resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n\n  static forRootAsync(options: AgentGenuiModuleAsyncOptions): DynamicModule {\n    return {\n      module: AgentGenuiModule,\n      global: true,\n      imports: options.imports ?? [],\n      providers: [\n        { provide: GENUI_OPTIONS, useFactory: options.useFactory, inject: options.inject ?? [] },\n        ...coreProviders(options.resolver),\n      ],\n      exports: options.resolver === undefined ? EXPORTS : [...EXPORTS, GenuiCatalogResolver],\n    };\n  }\n}\n","import {\n  type FunctionalToolDefinition,\n  type ToolHandler,\n  type ToolSpec,\n  createFunctionalTool,\n} from '@dudousxd/nestjs-agent-core';\nimport type { FactoryProvider, Provider } from '@nestjs/common';\n\n/**\n * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up\n * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.\n */\nexport const AGENT_TOOL_BRAND = Symbol.for('@dudousxd/nestjs-agent:functional-tool');\n\n/** A tool expressed as data + handler (e.g. from `createExecuteSqlTool`), not an `@AiTool` class. */\nexport interface FunctionalTool {\n  spec: ToolSpec;\n  handler: ToolHandler;\n}\n\n/** A {@link FunctionalTool} carrying {@link AGENT_TOOL_BRAND} — what a provider resolves to. */\nexport interface BrandedFunctionalTool extends FunctionalTool {\n  readonly [AGENT_TOOL_BRAND]: true;\n}\n\nfunction brand(tool: FunctionalTool): BrandedFunctionalTool {\n  return { [AGENT_TOOL_BRAND]: true, spec: tool.spec, handler: tool.handler };\n}\n\n/** Narrows a provider instance to a branded functional tool for boot-time registration. */\nexport function isBrandedFunctionalTool(value: object): value is BrandedFunctionalTool {\n  return AGENT_TOOL_BRAND in value && 'spec' in value && 'handler' in value;\n}\n\n/**\n * Registers a functional tool declaratively — drop the returned provider in a module's `providers`\n * and `AiToolDiscoveryService` auto-registers it at boot. Each call uses a fresh, unique provide\n * token so the same tool can be provided many times without collisions.\n *\n * Two forms: a static tool (`useValue`) or a factory with `inject` for DI-resolved dependencies\n * (`useFactory`). Either way the resolved instance is branded with {@link AGENT_TOOL_BRAND}.\n */\nexport function provideAgentTool(tool: FunctionalTool): Provider;\nexport function provideAgentTool(\n  factory: (...deps: never[]) => FunctionalTool,\n  inject?: FactoryProvider['inject'],\n): Provider;\nexport function provideAgentTool(\n  factoryOrTool: FunctionalTool | ((...deps: never[]) => FunctionalTool),\n  inject?: FactoryProvider['inject'],\n): Provider {\n  const provide = Symbol('nestjs-agent:functional-tool-instance');\n  if (typeof factoryOrTool === 'function') {\n    return {\n      provide,\n      useFactory: (...deps: never[]) => brand(factoryOrTool(...deps)),\n      inject: inject ?? [],\n    };\n  }\n  return { provide, useValue: brand(factoryOrTool) };\n}\n\n/**\n * Registers a LIST of functional tools from one factory — for a producer whose tool count is only\n * known once its dependencies resolve (a catalog loaded from config, one tool per entry). The\n * factory's result is branded element by element; `AiToolDiscoveryService` registers each.\n */\nexport function provideAgentTools(\n  factory: (...deps: never[]) => readonly FunctionalTool[] | Promise<readonly FunctionalTool[]>,\n  inject?: FactoryProvider['inject'],\n): Provider {\n  return {\n    provide: Symbol('nestjs-agent:functional-tool-list'),\n    useFactory: async (...deps: never[]) => (await factory(...deps)).map(brand),\n    inject: inject ?? [],\n  };\n}\n\n/** Author a functional tool with inferred Standard Schema input and domain output. */\nexport const defineTool = createFunctionalTool;\nexport type { FunctionalToolDefinition };\n","/**\n * `@dudousxd/nestjs-agent/genui` — generative UI for NestJS: {@link AgentGenuiModule} registers the\n * tools that push catalog components, `GENUI_CATALOG` / `@InjectGenuiCatalog()` expose the catalog,\n * and {@link GenuiCatalogResolver} serves per-request (per-tenant) catalogs. The catalog itself —\n * `defineComponent`, `defineCatalog`, validation, text fallbacks — is re-exported from\n * `@dudousxd/nestjs-agent-core/genui`, the isomorphic entry a browser imports too.\n */\nexport {\n  AgentGenuiModule,\n  type AgentGenuiModuleAsyncOptions,\n  type AgentGenuiModuleOptions,\n  type AgentGenuiOptions,\n  GENUI_CATALOG,\n  GENUI_OPTIONS,\n  GenuiCatalogResolver,\n  InjectGenuiCatalog,\n} from './agent-genui.module.js';\nexport * from '@dudousxd/nestjs-agent-core/genui';\n"],"mappings":";;;;AAOA,SAASA,eAAeC,kBAAkB;AAC1C,SAGEC,QACAC,cAIK;;;AChBP,SAIEC,4BACK;AAOA,IAAMC,mBAAmBC,uBAAOC,IAAI,wCAAA;AAa3C,SAASC,MAAMC,MAAoB;AACjC,SAAO;IAAE,CAACJ,gBAAAA,GAAmB;IAAMK,MAAMD,KAAKC;IAAMC,SAASF,KAAKE;EAAQ;AAC5E;AAFSH;AA0CF,SAASI,kBACdC,SACAC,QAAkC;AAElC,SAAO;IACLC,SAASC,uBAAO,mCAAA;IAChBC,YAAY,iCAAUC,UAAmB,MAAML,QAAAA,GAAWK,IAAAA,GAAOC,IAAIC,KAAAA,GAAzD;IACZN,QAAQA,UAAU,CAAA;EACpB;AACF;AATgBF;;;;;;;;;;;;;;;;;AD/CT,IAAMS,gBAAgBC,uBAAOC,IAAI,sCAAA;AAGjC,IAAMC,gBAAgBF,uBAAOC,IAAI,sCAAA;AAGjC,IAAME,qBAAqB,6BAChCC,OAAOL,aAAAA,GADyB;AAa3B,IAAeM,uBAAf,MAAeA;SAAAA;;;AAEtB;AAgDA,SAASC,kBAAkBC,UAAoC;AAC7D,MAAIA,aAAaC,OAAW,QAAO,CAAA;AACnC,SAAO;IACL,OAAOD,aAAa,aAChB;MAAEE,SAASJ;MAAsBK,UAAUH;IAAS,IACpD;MAAEE,SAASJ;MAAsBM,UAAUJ;IAAS;;AAE5D;AAPSD;AAST,SAASM,YACPC,SACAN,UAA0C;AAE1C,QAAM,EAAEO,SAASC,UAAU,GAAGC,KAAAA,IAASH;AACvC,SAAO;IACL,GAAGG;IACH,GAAIT,aAAaC,SACb;MAAES,gBAAgB,wBAACC,UAA6BX,SAASY,QAAQD,KAAAA,GAA/C;IAAsD,IACxE,CAAC;EACP;AACF;AAXSN;AAaT,SAASQ,cAAcb,UAAoC;AACzD,SAAO;IACL;MACEE,SAASV;MACTsB,YAAY,wBAACR,YAA+BA,QAAQC,WAAWQ,cAAc,CAAA,CAAE,GAAnE;MACZC,QAAQ;QAACrB;;IACX;OACGI,kBAAkBC,QAAAA;;;IAGrBiB,kBACE,CAACX,SAA4BC,SAAkBW,eAC7CC,WAAWZ,SAASF,YAAYC,SAASY,UAAAA,CAAAA,GAC3C;MAACvB;MAAeH;MAAe;QAAE4B,OAAOtB;QAAsBuB,UAAU;MAAK;KAAE;;AAGrF;AAhBSR;AAkBT,IAAMS,UAAU;EAAC9B;EAAeG;;AAYzB,IAAM4B,mBAAN,MAAMA,kBAAAA;SAAAA;;;EACX,OAAOC,QAAQlB,UAAmC,CAAC,GAAkB;AACnE,UAAM,EAAEN,UAAU,GAAGS,KAAAA,IAASH;AAC9B,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRC,WAAW;QAAC;UAAEzB,SAASP;UAAeS,UAAUK;QAAK;WAAMI,cAAcb,QAAAA;;MACzE4B,SAAS5B,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IAC3D;EACF;EAEA,OAAO+B,aAAavB,SAAsD;AACxE,WAAO;MACLmB,QAAQF;MACRG,QAAQ;MACRI,SAASxB,QAAQwB,WAAW,CAAA;MAC5BH,WAAW;QACT;UAAEzB,SAASP;UAAemB,YAAYR,QAAQQ;UAAYE,QAAQV,QAAQU,UAAU,CAAA;QAAG;WACpFH,cAAcP,QAAQN,QAAQ;;MAEnC4B,SAAStB,QAAQN,aAAaC,SAAYqB,UAAU;WAAIA;QAASxB;;IACnE;EACF;AACF;;;;;;AEnJA,cAAc;","names":["defineCatalog","genuiTools","Inject","Module","createFunctionalTool","AGENT_TOOL_BRAND","Symbol","for","brand","tool","spec","handler","provideAgentTools","factory","inject","provide","Symbol","useFactory","deps","map","brand","GENUI_CATALOG","Symbol","for","GENUI_OPTIONS","InjectGenuiCatalog","Inject","GenuiCatalogResolver","resolverProviders","resolver","undefined","provide","useClass","useValue","toolOptions","options","catalog","_catalog","rest","resolveCatalog","scope","resolve","coreProviders","useFactory","defineCatalog","inject","provideAgentTools","perRequest","genuiTools","token","optional","EXPORTS","AgentGenuiModule","forRoot","module","global","providers","exports","forRootAsync","imports"]}