bazis 0.137.0 → 0.138.0

package/README.md

@@ -142,7 +142,8 @@ import { dbConfig } from "../config/db.config"; // defineConfig("db", { default:
 export class AppInfra {}
 
 // src/index.ts
-await runApp(AppModule, { infra: AppInfra, http: { port: 3000, health: true } });
+@App({ modules: [AppModule], infra: AppInfra, http: { health: true } })
+export class Application {}
 ```
 
 A feature module attaches its own `DbContext` and entities with
@@ -180,11 +181,13 @@ import { CodexError, RU_CODEX_MESSAGES } from "bazis/core/infra";
 import { RU_UI_LABELS } from "bazis/core/app";
 
 CodexError.useMessages(RU_CODEX_MESSAGES); // Codex connector errors
-await runApp(AppModule, {
+@App({
+  modules: [AppModule],
   language: "ru",                          // response texts: validation, 404/405, 401/403, binding errors
   messages: { notFound: "Нет такой страницы" }, // optional: own texts for single keys
-  ui: { labels: RU_UI_LABELS, surfaces: [/* ... */] }, // generated UI texts
-});
+  ui: { labels: RU_UI_LABELS, surfaces: [/* ... */] }, // generated UI texts,
+})
+export class Application {}
 ```
 
 `language` is per application: it is applied when the response is written, so

package/cli/generateProject.ts

@@ -169,39 +169,32 @@ function buildProjectFiles(name: string, dependency: string, frameworkMode: Fram
     ["bazis.config.json", `${JSON.stringify(codegen, null, 2)}\n`],
     // Bun reads .env, .env.local and .env.<NODE_ENV>: none of them belongs in git.
     [".gitignore", "node_modules/\nbin/\nsrc/generated/\n.env\n.env.*\n!.env.example\n"],
-    [".env.example", "# Copy to .env (Bun loads it automatically).\nBAZIS_ENV=development\nHOST=127.0.0.1\nPORT=3000\n"],
+    [".env.example", "# Copy to .env (Bun loads it automatically).\nBAZIS_ENV=development\nBAZIS_HTTP__HOST=127.0.0.1\nBAZIS_HTTP__PORT=3000\n"],
     ["src/app/test/health.test.ts", HEALTH_TEST],
     ["AGENTS.md", "# Working on this bazis project\n\nBefore changing the application, read the [module architecture](docs/architecture/MODULE_ARCHITECTURE.md). Create new modules only with `bunx bazis g module` or `bunx bazis g pack`; fill in the generated `MODULE.md` afterwards. Only codegen updates `src/generated/`.\n"],
-    ["docs/architecture/MODULE_ARCHITECTURE.md", "# Application module architecture\n\n`src/index.ts` calls `runApp`; `src/app/modules/App.module.ts` composes feature modules through `imports`. The application root owns no domain logic.\n\nOne self-contained function is an atomic module. It owns its data, services, HTTP and background handlers. A composite module is only for several independent functions; its root does composition. Layers and file counts alone do not create submodules.\n\nCreate new modules only with `bunx bazis g module <Name> --empty|--minimal|--full` or `bunx bazis g pack <Name> --parts <a,b>`; add a part to an existing composite with `bunx bazis g module <Name> --pack <Pack>`. The generated `MODULE.md` records the creation command. Before implementing, define the responsibility and public entries, then fill in the generated `MODULE.md`: fields, errors, dependencies, exports and checks. Use the public APIs of the `bazis` package and its DI and ORM. Do not edit `src/generated/` by hand; run `bunx bazis codegen`.\n\n`--minimal` creates a sample CRUD with the ORM. To run it the application needs a database provider and a ready schema. For a first function without a database use `--empty`. Check types and the binary build after changes that affect startup.\n"],
+    ["docs/architecture/MODULE_ARCHITECTURE.md", "# Application module architecture\n\n`src/index.ts` calls `runApp(Application)`; `src/app/App.ts` declares the application with `@App`: its modules, infrastructure and servers; `src/app/modules/App.module.ts` composes feature modules through `imports`. The application root owns no domain logic.\n\nOne self-contained function is an atomic module. It owns its data, services, HTTP and background handlers. A composite module is only for several independent functions; its root does composition. Layers and file counts alone do not create submodules.\n\nCreate new modules only with `bunx bazis g module <Name> --empty|--minimal|--full` or `bunx bazis g pack <Name> --parts <a,b>`; add a part to an existing composite with `bunx bazis g module <Name> --pack <Pack>`. The generated `MODULE.md` records the creation command. Before implementing, define the responsibility and public entries, then fill in the generated `MODULE.md`: fields, errors, dependencies, exports and checks. Use the public APIs of the `bazis` package and its DI and ORM. Do not edit `src/generated/` by hand; run `bunx bazis codegen`.\n\n`--minimal` creates a sample CRUD with the ORM. To run it the application needs a database provider and a ready schema. For a first function without a database use `--empty`. Check types and the binary build after changes that affect startup.\n"],
     ["src/app/modules/App.module.ts", 'import { Module } from "bazis/core/di";\n\n@Module({ imports: [], exports: [] })\nexport class AppModule {}\n'],
-    ["src/index.ts", 'import { runApp } from "bazis/core/app";\nimport { AppModule } from "./app/modules/App.module";\nimport { registerBazisGeneratedRuntime } from "./generated/bazis/runtime";\n\nawait registerBazisGeneratedRuntime();\nawait runApp(AppModule, { http: { hostname: process.env.HOST ?? "127.0.0.1", port: Number(process.env.PORT ?? 3000), health: true } });\n'],
+    ["src/app/App.ts", 'import { App } from "bazis/core/app";\nimport { AppModule } from "./modules/App.module";\n\n/** The application: its modules and the servers it starts. `src/index.ts` runs it, tests start the same one. */\n@App({\n  modules: [AppModule],\n  http: { health: true },\n})\nexport class Application {}\n'],
+    ["src/index.ts", 'import { runApp } from "bazis/core/app";\nimport { Application } from "./app/App";\nimport { registerBazisGeneratedRuntime } from "./generated/bazis/runtime";\n\nawait registerBazisGeneratedRuntime();\nawait runApp(Application);\n'],
     ["README.md", `# ${name}\n\nA [bazis](https://www.npmjs.com/package/bazis) application. ${frameworkMode === "registry"
       ? "The framework comes from npm as the `bazis` dependency; update it with `bun update bazis`."
       : frameworkMode === "snapshot"
       ? "The framework package is copied to `vendor/bazis`; keep it in Git and move it with the project. The framework checkout is no longer needed. Framework updates do not reach this copy automatically."
-      : "The `bazis` dependency links an external local checkout (`--link-framework`). Moving the project needs the same package and an updated path in `package.json`."}\nRead the [local architecture](docs/architecture/MODULE_ARCHITECTURE.md) before changing modules.\n\nNeeds Bun ≥ 1.4.0. Settings go to \`.env\` (example: \`.env.example\`).\n\n\`\`\`sh\nbun install\nbunx bazis dev\n# GET http://127.0.0.1:3000/health\n# If the port is busy: PORT=3100 bunx bazis dev\n\`\`\`\n\nAdd an atomic module from the project root: \`bunx bazis g module Task --empty\`.\nAfter filling in its passport and implementation, run \`bunx bazis codegen\`.\nTests: \`bunx bazis test\`. Typecheck: \`bunx bazis build\`. Binary: \`bunx bazis build --bin\`, run it with \`bun run start\`.\n\n\`--minimal\` creates a sample CRUD with paging (20 records by default, at most 100 over HTTP); it needs a database provider and a schema to run. The service returns \`PageResult\`; the HTTP controller builds JSON:API. \`DbContext.saveChanges()\` saves every change of its context. In ORM predicates combine conditions with \`.and()\` and \`.or()\`; codegen rejects \`&&\` and \`||\` between predicates.\n`],
+      : "The `bazis` dependency links an external local checkout (`--link-framework`). Moving the project needs the same package and an updated path in `package.json`."}\nRead the [local architecture](docs/architecture/MODULE_ARCHITECTURE.md) before changing modules.\n\nNeeds Bun ≥ 1.4.0. Settings go to \`.env\` (example: \`.env.example\`).\n\n\`\`\`sh\nbun install\nbunx bazis dev\n# GET http://127.0.0.1:3000/health\n# If the port is busy: BAZIS_HTTP__PORT=3100 bunx bazis dev\n\`\`\`\n\nAdd an atomic module from the project root: \`bunx bazis g module Task --empty\`.\nAfter filling in its passport and implementation, run \`bunx bazis codegen\`.\nTests: \`bunx bazis test\`. Typecheck: \`bunx bazis build\`. Binary: \`bunx bazis build --bin\`, run it with \`bun run start\`.\n\n\`--minimal\` creates a sample CRUD with paging (20 records by default, at most 100 over HTTP); it needs a database provider and a schema to run. The service returns \`PageResult\`; the HTTP controller builds JSON:API. \`DbContext.saveChanges()\` saves every change of its context. In ORM predicates combine conditions with \`.and()\` and \`.or()\`; codegen rejects \`&&\` and \`||\` between predicates.\n`],
   ];
 }
 
 const HEALTH_TEST = `import { expect, test } from "bun:test";
+import { startTestApp } from "bazis/core/testing";
+import { Application } from "../App";
 
-// Starts the app from source exactly as \`bazis dev\` does and checks /health.
+// Starts the application declared in src/app/App.ts on a free port and checks /health.
 test("app starts and answers /health", async () => {
-  // A free port from the operating system, not a random guess that may be taken.
-  const probe = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() });
-  const port = String(probe.port);
-  probe.stop(true);
-  const app = Bun.spawn([process.execPath, "run", "src/index.ts"], { env: { ...process.env, HOST: "127.0.0.1", PORT: port }, stdout: "ignore", stderr: "inherit" });
+  const app = await startTestApp(Application);
   try {
-    let status = 0;
-    for (let attempt = 0; attempt < 100 && status !== 200; attempt++) {
-      await Bun.sleep(100);
-      status = await fetch(\`http://127.0.0.1:\${port}/health\`).then((response) => response.status, () => 0);
-    }
-    expect(status).toBe(200);
+    expect((await app.fetch("/health")).status).toBe(200);
   } finally {
-    app.kill();
-    await app.exited;
+    await app.stop();
   }
 });
 `;

package/cli/main.ts

@@ -48,7 +48,7 @@ Generation options:
   --minimal             Compact example CRUD and MODULE.md (default)
   --full                Example CRUD/list/cache/auth/background/AI and MODULE.md;
                         uses src/app/modules/auth helpers when the project has them.
-                        To run, the host needs a cache (runApp({ cache: memory() }))
+                        To run, the host needs a cache (@App({ cache: memory() }))
                         and a database provider. Legacy alias: --enterprise
   --parts <a,b,...>      Independent empty atomic parts; pack only, at least two
   --dry-run             Validate and list planned changes without writing

package/cli/templates/passport.ts

@@ -76,7 +76,7 @@ exports: [I${m}Service]. TypeScript contract: services/I${e}.service.ts;
 HTTP access is defined by the controller and the host policy, separately from DI exports.
 I${m}Service → ${m}Service, scoped lifetime. The context and DbSet belong to the ORM.
 ${profile === "full" ? `${m}SummaryTool is listed in tools: [${m}SummaryTool]; the framework registers it as scoped, the tool is not exported.
-The service is scoped; its keyed @Cacheable works when the host installs the cache (runApp cache: memory()).
+The service is scoped; its keyed @Cacheable works when the host installs the cache (@App cache: memory()).
 The background service gets its own scope per tick and disposes it in finally.
 The host also provides auth from src/app/modules/auth (TokenKind.Admin/Client)
 and an LLM connector, which registers AgentRuntime. The CLI does not create them.

package/core/access/catalog/moduleFields.ts

@@ -26,6 +26,8 @@ const REFERENCE_CHANNEL = createModuleOwnedMetadataChannel<ReferencePayload>("ac
 const ROLE_CHANNEL = createModuleOwnedMetadataChannel<RolePayload>("access.role/v1");
 /** The classes of `references`: the field registers them, like `tools` and `controllers`. */
 const REFERENCE_CLASS_CHANNEL = createModuleOwnedProviderChannel<{ readonly kind: string }, object>("access.reference-class/v1");
+/** The `lookup` classes of `permissions`: the field registers them too. */
+const LOOKUP_CLASS_CHANNEL = createModuleOwnedProviderChannel<{ readonly permission: string }, object>("access.lookup-class/v1");
 
 /** The values of `in`/`notIn` a role may list; the run-time limit is `access.maxInList`. */
 const STARTUP_MAX_IN_LIST = 1000;
@@ -46,7 +48,20 @@ registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context)
     if (!isDeclaredPermissions(fields.permissions)) throw new AccessSetupError(`${module}: permissions must be a definePermissions(...) result.`);
     const problems = Object.entries(fields.permissions).flatMap(([key, spec]) => permissionProblems(key, spec));
     if (problems.length > 0) throw setupError(module, "permissions", problems);
-    for (const [key, spec] of Object.entries(fields.permissions)) context.addMetadata(PERMISSION_CHANNEL, { key, spec });
+    const lookups = new Set<unknown>();
+    for (const [key, spec] of Object.entries(fields.permissions)) {
+      context.addMetadata(PERMISSION_CHANNEL, { key, spec });
+      for (const lookup of lookupsOf(spec)) {
+        // A lookup another module owns and exports is taken from it.
+        if (lookups.has(lookup) || importsExport(metadata, lookup)) continue;
+        lookups.add(lookup);
+        try {
+          context.registerScoped(LOOKUP_CLASS_CHANNEL, scoped(lookup as Class<object>), { permission: key });
+        } catch {
+          // The module registered the class its own way: that registration stands.
+        }
+      }
+    }
   }
   if (fields.references !== undefined) {
     const references = fields.references;
@@ -117,7 +132,7 @@ registerModuleOwnedContributionValidator((snapshot) => {
       }
     }
     for (const lookup of lookupsOf(payload.spec)) {
-      if (snapshot.countProviders(lookup) === 0) throw new AccessSetupError(`${ownerName}: ${lookup.name} of permission "${payload.key}" is not registered: add it to the module's providers.`);
+      if (snapshot.countProviders(lookup) === 0) throw new AccessSetupError(`${ownerName}: ${lookup.name} of permission "${payload.key}" is not registered.`);
     }
   }
 
@@ -136,6 +151,14 @@ registerModuleOwnedContributionValidator((snapshot) => {
   }
 });
 
+/** Whether a module the given one imports exports this class. */
+function importsExport(metadata: BazisModuleMetadata, type: unknown): boolean {
+  return (metadata.imports ?? []).some((imported) => {
+    const exported = (imported as { readonly exports?: unknown }).exports;
+    return Array.isArray(exported) && exported.includes(type);
+  });
+}
+
 /** What the modules of the application's container declared. */
 export function declarationsOf(services: ServiceProvider): { permissions: OwnedPermission[]; kinds: OwnedReferenceKind[]; roles: DeclaredRole[] } {
   if (!(services instanceof DiContainer)) throw new AccessSetupError("Access declarations require the framework DiContainer.");

package/core/access/testing/index.ts

@@ -2,13 +2,18 @@
  * Test helpers of access (ACCESS-001 §8): a rights system whose grants are set
  * right in the test.
  */
+import { singletonValue, type ProviderDefinition } from "../../di";
 import { PRINCIPAL_STATE_KEY, type AuthorizeContext, type RequestPrincipal } from "../../http";
 import { AccessPolicy, type ScopePrincipals } from "../contracts/AccessPolicy";
 import type { AccessSubject, Grants, Scope } from "../contracts/types";
 
 export interface StaticAccessOptions {
-  /** Subject → permission → grants; a permission not listed gives nothing. */
-  readonly grants: Readonly<Record<string, Readonly<Record<string, Grants>>>>;
+  /** Subject → permission → grants; a permission not listed gives {@link otherwise}. */
+  readonly grants?: Readonly<Record<string, Readonly<Record<string, Grants>>>>;
+  /** What a permission not listed in `grants` gives: nothing by default, `"all"` to allow everything. */
+  readonly otherwise?: Grants;
+  /** Who a request without a signed-in principal is; by default nobody, and the request is refused. */
+  readonly anonymous?: string;
   /** Subject → the owner ids meaning it; by default `sub` after the last `:`. */
   readonly owners?: Readonly<Record<string, readonly string[]>>;
   /** Subject → its addressees in every partition; by default `user:<owner id>`. */
@@ -32,11 +37,12 @@ export class StaticAccessPolicy extends AccessPolicy {
 
   subject(ctx: AuthorizeContext): AccessSubject | undefined {
     const sub = (ctx.state.get(PRINCIPAL_STATE_KEY) as RequestPrincipal | undefined)?.subject;
-    return sub === undefined || sub === "" ? undefined : { sub };
+    if (sub !== undefined && sub !== "") return { sub };
+    return this.options.anonymous === undefined ? undefined : { sub: this.options.anonymous };
   }
 
   grants(subject: AccessSubject, permission: string): Grants {
-    return this.options.grants[subject.sub]?.[permission] ?? [];
+    return this.options.grants?.[subject.sub]?.[permission] ?? this.options.otherwise ?? [];
   }
 
   ownerIds(subject: AccessSubject): readonly string[] {
@@ -49,6 +55,22 @@ export class StaticAccessPolicy extends AccessPolicy {
   }
 }
 
+/**
+ * A rights system that allows everything, for a test that is not about rights:
+ * every subject has every permission in every partition.
+ *
+ * ```ts
+ * const app = await startTestApp(OrdersApp, { overrides: [allowAll()] });
+ * ```
+ *
+ * Requests still need a signed-in principal; `allowAll({ anonymous: "test" })`
+ * also lets in a request without one, as the subject `test`. `grants` narrows
+ * single subjects: `allowAll({ grants: { "user:2": { "orders.delete": [] } } })`.
+ */
+export function allowAll(options: Omit<StaticAccessOptions, "otherwise"> = {}): ProviderDefinition {
+  return singletonValue(AccessPolicy, new StaticAccessPolicy({ ...options, otherwise: "all" }));
+}
+
 function ownerId(sub: string): string {
   return sub.slice(sub.lastIndexOf(":") + 1);
 }

package/core/agent/ToolRunner.ts

@@ -1,4 +1,5 @@
-import { DI, DiError, Global, HOSTED_SERVICE, Module, registerModuleMetadataExpander, SERVICE_PROVIDER, type BazisModuleMetadata, type ServiceProvider } from "../di";
+import { DiError, Global, HOSTED_SERVICE, Module, registerModuleMetadataExpander, SERVICE_PROVIDER, type BazisModuleMetadata, type ServiceProvider } from "../di";
+import { DI } from "../di/lowLevel";
 import { LOGGER } from "../kernel/logging/Logger";
 import { modelValidatorAdapter } from "../../library/validation";
 import { AgentRegistry, type ToolDefinition } from "./AgentRegistry";

package/core/agent/defineTool.ts

@@ -0,0 +1,109 @@
+import { ServiceProvider, type Class } from "../di";
+import { registerFrameworkClassDeps } from "../di/module/autoDeps";
+import { Tool } from "./decorators/Tool";
+import { AgentSetupError } from "./errors";
+import { toolMetadataOf, type ToolOptions } from "./metadata";
+import type { AgentToolExecutionContext } from "./AgentToolExecutor";
+
+declare const TOOL_TYPES: unique symbol;
+
+/**
+ * A Tool made by {@link defineTool}. It stands in `@Module({ tools })` next to
+ * the classes with `@Tool`, and a process names it by reference.
+ */
+export type DefinedTool<I = unknown, O = unknown> = Class<object> & {
+  /** The name it is called by: `orm.order.find`. */
+  readonly toolName: string;
+  /** Only for the types: what `execute` takes and gives back. */
+  readonly [TOOL_TYPES]?: { readonly input: I; readonly output: O };
+};
+
+/** Several made Tools under the names their factory gave them: `orderTools.find`. */
+export type ToolSet<K extends string = string> = { readonly [P in K]: DefinedTool };
+
+/** What `defineTool` takes: what `@Tool` takes, without the classes of input and output, and the work itself. */
+export interface DefinedToolOptions<I = unknown, O = unknown> extends Omit<ToolOptions, "input" | "output"> {
+  /**
+   * Does the work. `services` is the scope of the call: `services.resolve(OrdersDbContext)`.
+   * The input comes as the caller sent it: check it here.
+   */
+  execute(input: I, context: AgentToolExecutionContext, services: ServiceProvider): O | Promise<O>;
+}
+
+const DEFINED = new WeakSet<object>();
+
+/**
+ * A Tool without a class: for Tools made by a function, when their number and
+ * names are known only from its arguments. A Tool written by hand is a class
+ * with `@Tool`.
+ *
+ * ```ts
+ * export function exportTools(formats: readonly string[]): ToolSet {
+ *   return Object.fromEntries(formats.map((format) => [format, defineTool({
+ *     name: `reports.export.${format}`,
+ *     description: `Exports a report as ${format}.`,
+ *     sideEffect: "read",
+ *     callers: ["workflow"],
+ *     inputSchema: { type: "object", properties: { reportId: { type: "string" } }, required: ["reportId"] },
+ *     execute: (input: { reportId: string }, _context, services) => services.resolve(ReportService).export(input.reportId, format),
+ *   })]));
+ * }
+ *
+ * @Module({ tools: [SendReportTool, exportTools(["pdf", "csv"])] })
+ * ```
+ */
+export function defineTool<I = unknown, O = unknown>(definition: DefinedToolOptions<I, O>): DefinedTool<I, O> {
+  if (definition === null || typeof definition !== "object" || typeof definition.execute !== "function") {
+    throw new AgentSetupError("defineTool takes the description of a Tool with its execute(input, context, services).");
+  }
+  const { execute, ...options } = definition;
+
+  @Tool(options)
+  class MadeTool {
+    static readonly toolName = String(options.name).trim();
+
+    constructor(private readonly services: ServiceProvider) {}
+
+    execute(input: unknown, context: AgentToolExecutionContext): unknown {
+      return execute(input as I, context, this.services);
+    }
+  }
+
+  // The class is made here, so codegen never sees its constructor.
+  registerFrameworkClassDeps([[MadeTool, [ServiceProvider]]]);
+  DEFINED.add(MadeTool);
+  Object.defineProperty(MadeTool, "name", { value: `Tool(${MadeTool.toolName})` });
+  return MadeTool as unknown as DefinedTool<I, O>;
+}
+
+/** Whether a value came from {@link defineTool}. */
+export function isDefinedTool(value: unknown): value is DefinedTool {
+  return typeof value === "function" && DEFINED.has(value);
+}
+
+/**
+ * @internal The Tools a module lists in `tools`: classes with `@Tool`, made Tools
+ * and sets of them, as one list of classes.
+ */
+export function moduleToolsOf(value: unknown): readonly Class<object>[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new AgentSetupError("tools must be an array of classes with @Tool, Tools made by defineTool and sets of them.");
+  const out: Class<object>[] = [];
+  for (const entry of value) {
+    if (typeof entry === "function") {
+      out.push(entry as Class<object>);
+      continue;
+    }
+    const members = typeof entry === "object" && entry !== null && !Array.isArray(entry) ? Object.entries(entry) : undefined;
+    if (members === undefined || members.length === 0 || members.some(([, member]) => !isDefinedTool(member))) {
+      throw new AgentSetupError("tools must list classes with @Tool, Tools made by defineTool and sets of them: an object in the list must hold only Tools made by defineTool.");
+    }
+    for (const [, member] of members) out.push(member as Class<object>);
+  }
+  return out;
+}
+
+/** The name a class with `@Tool` or a made Tool is called by; `undefined` for anything else. */
+export function toolNameOf(tool: unknown): string | undefined {
+  return typeof tool === "function" ? toolMetadataOf(tool as Class<object>)?.name : undefined;
+}

package/core/agent/index.ts

@@ -1,14 +1,16 @@
 import type { Class } from "../di";
 import { registerModuleDescriber } from "../kernel/report/moduleTree";
+import { moduleToolsOf, type DefinedTool, type ToolSet } from "./defineTool";
 import { toolMetadataOf } from "./metadata";
 
 // The module tree of the startup screen: `orders.summary · read`.
-registerModuleDescriber((metadata) => (metadata.tools ?? []).map((tool) => {
+registerModuleDescriber((metadata) => moduleToolsOf(metadata.tools).map((tool) => {
   const meta = toolMetadataOf(tool);
   return { kind: "tool" as const, text: meta === undefined ? tool.name : `${meta.name} · ${meta.sideEffect}` };
 }));
 
 export { Tool } from "./decorators/Tool";
+export { defineTool, isDefinedTool, toolNameOf, type DefinedTool, type DefinedToolOptions, type ToolSet } from "./defineTool";
 export { describeTool } from "./Tool.contract";
 export type {
   AgentToolHookKindV1, AgentToolHookRefV1, AgentToolRequiredHookRefV1, AgentToolHookRegistrationBaseV1,
@@ -149,8 +151,11 @@ export {
 // depend on program file order and silently stop merging in some projects.
 declare module "../di/module/types/BazisModule" {
   interface BazisModuleMetadata {
-    /** Tools agents may call: classes with `@Tool`. An agent definition names them in `toolNames`. */
-    readonly tools?: readonly Class<object>[];
+    /**
+     * The Tools of the module: classes with `@Tool`, Tools made by `defineTool`
+     * and sets of them (`ormEntityTools(...)`). An agent definition names them in `toolNames`.
+     */
+    readonly tools?: readonly (Class<object> | DefinedTool | ToolSet)[];
     readonly agentToolHooks?: readonly import("./AgentToolHooks").AgentToolHookRegistrationV1[];
   }
 }

package/core/agent/moduleContributions-v1.ts

@@ -11,6 +11,7 @@ import {
   type BazisModuleRef,
 } from "../di";
 import { AgentSetupError } from "./errors";
+import { moduleToolsOf } from "./defineTool";
 import { toolMetadataOf } from "./metadata";
 import type { AgentToolHookRegistrationV1 } from "./AgentToolHooks";
 
@@ -25,18 +26,10 @@ const HOOK_CHANNEL = createModuleOwnedProviderChannel<AgentOwnedHookContribution
 // Internal imports (including generatedRuntime's type-only AgentRegistry import)
 // must not depend on the public barrel having augmented DI's metadata interface.
 interface AgentModuleFields {
-  readonly tools?: readonly Class<object>[];
+  readonly tools?: readonly unknown[];
   readonly agentToolHooks?: readonly AgentToolHookRegistrationV1[];
 }
 
-function classValues(value: unknown, field: string): readonly Class<object>[] {
-  if (value === undefined) return [];
-  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "function")) {
-    throw new AgentSetupError(`${field} must be an array of classes.`);
-  }
-  return value as readonly Class<object>[];
-}
-
 export function assertAgentToolHookIdV1(id: unknown): asserts id is string {
   if (typeof id !== "string" || !/^[\x20-\x7e]{1,128}$/.test(id)) {
     throw new AgentSetupError("Agent Tool hook id must contain 1 to 128 printable ASCII characters.");
@@ -59,7 +52,7 @@ function assertHook(registration: AgentToolHookRegistrationV1): void {
 registerModuleOwnedProviderContributor((metadata: BazisModuleMetadata, context) => {
   const owner = metadata as BazisModuleRef;
   const fields = metadata as BazisModuleMetadata & AgentModuleFields;
-  for (const target of classValues(fields.tools, "tools")) {
+  for (const target of moduleToolsOf(fields.tools)) {
     const tool = toolMetadataOf(target);
     if (!tool) throw new AgentSetupError(`${target.name || "<anonymous class>"} is listed as a tool but is not decorated with @Tool(...).`);
     if (tool.callers.length === 0) {

package/core/app/index.ts

@@ -1,6 +1,6 @@
 // Composition layer: the single application entry point. Depends on the kernel, HTTP, gRPC and
 // the validation library (it is the composition root, so it may use everything), hiding
 // infrastructure wiring from application code.
-export { runApp, type RunAppOptions } from "./runApp";
+export { App, runApp, type AppClass, type AppOptions, type AppSettings } from "./runApp";
 export type { AppLanguage, AppMessages } from "./messages";
 export * from "./ui";

package/core/app/messages.ts

@@ -35,7 +35,7 @@ const CATALOGS: Readonly<Record<AppLanguage, Readonly<Record<string, string>>>>
  */
 export function createLocalize(language: AppLanguage = "en", messages: AppMessages = {}): Localize {
   if (!Object.prototype.hasOwnProperty.call(CATALOGS, language)) {
-    throw new KernelError(`runApp: language "${String(language)}" is not supported. Use one of: ${Object.keys(CATALOGS).join(", ")}.`);
+    throw new KernelError(`@App: language "${String(language)}" is not supported. Use one of: ${Object.keys(CATALOGS).join(", ")}.`);
   }
   const catalog = CATALOGS[language];
   const own = messages as Readonly<Record<string, string | undefined>>;
@@ -62,9 +62,9 @@ export function createLanguages(option: AppLanguage | AppLanguageOptions = "en",
     return { negotiated: false, select: () => single };
   }
   const supported = [...new Set(option.supported)];
-  if (supported.length === 0) throw new KernelError("runApp: language.supported needs at least one language.");
+  if (supported.length === 0) throw new KernelError("@App: language.supported needs at least one language.");
   if (!supported.includes(option.default)) {
-    throw new KernelError(`runApp: language.default "${String(option.default)}" must be one of language.supported (${supported.join(", ")}).`);
+    throw new KernelError(`@App: language.default "${String(option.default)}" must be one of language.supported (${supported.join(", ")}).`);
   }
   const selected = new Map<string, SelectedLanguage>(supported.map((language) => [language, { language, localize: createLocalize(language, messages) }]));
   const fallback = selected.get(option.default)!;