bazis 0.136.0 → 0.138.0

package/core/scripts/di-generate.ts

@@ -189,6 +189,8 @@ interface ConstructorDependencies {
   readonly unsupportedParameter?: { readonly index: number; readonly name: string; readonly type: string };
 }
 let classDeps = new Map<ts.ClassDeclaration, readonly CollectedDependency[]>();
+/** `permissions` of the target's modules: the exported constant and its file. */
+let permissionDeclarations = new Map<string, { readonly name: string; readonly file: string }>();
 let inferredDiClasses = new Set<ts.ClassDeclaration>();
 let explicitlyBoundDiClasses = new Set<ts.ClassDeclaration>();
 // Known runtime token names: createToken descriptions + class names usable as class-tokens.
@@ -505,7 +507,7 @@ function collectDynamicImportDiagnostics(source: ts.SourceFile, target: string,
 
 function resetTargetAnalysis(files: Set<string>, generatedDir: string): void {
   activeGeneratedDir = generatedDir;
-  classDeps = new Map(); inferredDiClasses = new Set(); explicitlyBoundDiClasses = new Set();
+  classDeps = new Map(); inferredDiClasses = new Set(); explicitlyBoundDiClasses = new Set(); permissionDeclarations = new Map();
   tokenDescriptions = new Set(); configPrefixesByType = new Map(); knownClassNames = new Set(); warnings = []; fatalErrors = [];
   httpBindings = {}; httpControllerFiles = {}; openApiSchemas = {}; openApiOperations = {};
   grpcBindings = new Map();
@@ -555,6 +557,8 @@ async function generateTarget(name: string, reachable: Set<string>, production:
   stageWrite(`${generatedDir}/httpRequestModels.ts`, requestModels);
   stageWrite(`${generatedDir}/httpListModels.ts`, listModels);
   stageWrite(`${generatedDir}/openapi.ts`, openApi);
+  if (permissionDeclarations.size > 0) stageWrite(`${generatedDir}/permissions.ts`, renderPermissions());
+  else stageRemove(`${generatedDir}/permissions.ts`);
   // Generated before 0.99.0, when agents were classes; nothing imports it now.
   stageRemove(`${generatedDir}/agentCatalog.ts`);
   stageWrite(`${generatedDir}/runtime.ts`, renderGeneratedRuntime(name));
@@ -708,6 +712,15 @@ function renderGeneratedRuntime(targetId: string): string {
 }
 
 /** Sources of this target as codegen saw them; read back by the generated runtime. */
+/** Types only: the keys of the target's permissions for `can`, `access.can`, `access.filter` and `defineRoles`. */
+function renderPermissions(): string {
+  const entries = [...permissionDeclarations.values()].sort((left, right) => left.file.localeCompare(right.file) || left.name.localeCompare(right.name));
+  const lines = ["// This file is auto-generated by `bazis codegen`.", "// Do not edit manually.", 'import type { PermissionsOf } from "bazis/core/access";'];
+  entries.forEach((entry, index) => lines.push(`import type { ${entry.name} as Permissions_${index} } from ${JSON.stringify(toModuleSpecifierFrom(activeGeneratedDir, entry.file))};`));
+  lines.push("", 'declare module "bazis/core/access" {', `  interface BazisPermissions extends ${entries.map((_, index) => `PermissionsOf<typeof Permissions_${index}>`).join(", ")} {}`, "}", "");
+  return lines.join("\n");
+}
+
 function renderSourceFingerprint(): string {
   const files = sourceEntries.map((entry) => entry.filePath).sort();
   const framework = JSON.parse(readFileSync(path.join(FRAMEWORK_DIR, "package.json"), "utf8")).version as string;
@@ -832,6 +845,8 @@ function collectTokenDescriptions(source: ts.SourceFile): void {
   const visit = (node: ts.Node): void => {
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.arguments.length > 0) {
       const firstArg = node.arguments[0];
+      // defineConfig({ default: … }) without a section: its token is Config:default.
+      if (node.expression.text === "defineConfig" && firstArg && !ts.isStringLiteralLike(firstArg)) tokenDescriptions.add("Config:default");
       if (firstArg && ts.isStringLiteralLike(firstArg)) {
         if (node.expression.text === "createToken" || node.expression.text === "createOpenGenericTokenFamily") {
           tokenDescriptions.add(firstArg.text);
@@ -873,7 +888,9 @@ function resolveConfigViewDeps(): void {
       if (prefixes.length !== 1) {
         classDeps.delete(declaration);
         if (needsInferredDiDeps(declaration)) {
-          fatalErrors.push(prefixes.length === 0
+          fatalErrors.push(typeName.startsWith("typeof ")
+            ? `BAZIS_DI_CONFIG_UNKNOWN: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", but ${typeName.slice(7)} is not a declaration whose section codegen can read. Declare it as defineConfig("name", { default: {...} }) with a literal name and without a type argument.`
+            : prefixes.length === 0
             ? `BAZIS_DI_CONFIG_UNKNOWN: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", but no defineConfig<${typeName}>(...) declaration was found. Declare the configuration with an explicit type argument, for example defineConfig<${typeName}>("name", { default: {...} }).`
             : `BAZIS_DI_CONFIG_AMBIGUOUS: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", which matches several declarations: ${prefixes.map((prefix) => `"${prefix}"`).join(", ")}. Give each declaration its own type.`);
         }
@@ -977,6 +994,35 @@ function collectDiClassRegistrations(source: ts.SourceFile): void {
     if (properties.has("provide") && properties.has("useClass")
       && (!properties.has("deps") || properties.get("deps")!.getText() === "undefined")) record(properties.get("useClass"));
   };
+  /** The `lookup` classes of a `definePermissions({...})` result: of `scope` and of the attributes in `on`. */
+  const permissionLookups = (expression: ts.Expression | undefined): ts.Expression[] => {
+    const declared = (node: ts.Expression | undefined, depth = 0): ts.ObjectLiteralExpression | undefined => {
+      if (!node || depth > 5) return undefined;
+      if (ts.isCallExpression(node)) return objectFor(node.arguments[0]);
+      if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return declared(node.expression, depth + 1);
+      let symbol = checker.getSymbolAtLocation(node);
+      if (symbol && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol);
+      const declaration = symbol?.valueDeclaration;
+      return declaration && ts.isVariableDeclaration(declaration) ? declared(declaration.initializer, depth + 1) : undefined;
+    };
+    const permissions = declared(expression);
+    const found: ts.Expression[] = [];
+    if (!permissions) return found;
+    const lookupOf = (holder: ts.Expression | undefined): void => {
+      const object = objectFor(holder);
+      const lookup = object && propertiesOf(object).get("lookup");
+      if (lookup) found.push(lookup);
+    };
+    for (const spec of propertiesOf(permissions).values()) {
+      const permission = objectFor(spec);
+      if (!permission) continue;
+      const fields = propertiesOf(permission);
+      lookupOf(fields.get("scope"));
+      const attributes = objectFor(fields.get("on"));
+      if (attributes) for (const attribute of propertiesOf(attributes).values()) lookupOf(attribute);
+    }
+    return found;
+  };
   const visitedModules = new Set<ts.ObjectLiteralExpression>();
   const recordModule = (expression: ts.Expression | undefined): void => {
     const object = objectFor(expression);
@@ -987,6 +1033,11 @@ function collectDiClassRegistrations(source: ts.SourceFile): void {
       const classes = properties.get(name);
       if (classes && ts.isArrayLiteralExpression(classes)) for (const entry of classes.elements) record(entry);
     }
+    // `references: { "orders.order": OrderReferences }`: the field registers the classes.
+    const references = objectFor(properties.get("references"));
+    if (references) for (const entry of propertiesOf(references).values()) record(entry);
+    // `permissions: orderPermissions`: the field registers the `lookup` classes its permissions name.
+    for (const lookup of permissionLookups(properties.get("permissions"))) record(lookup);
     const imports = properties.get("imports");
     if (imports && ts.isArrayLiteralExpression(imports)) for (const entry of imports.elements) recordModule(entry);
   };
@@ -1086,12 +1137,45 @@ function collectProviderFormErrors(source: ts.SourceFile): void {
     }
     fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(element)}: providers of ${module}: "${text(element)}" is not an agreed registration. A computed service is a class with a constructor: scoped(IService, Service). Agreed forms: ${AGREED_PROVIDERS}.`);
   };
-  /** Tools made from an entity: they are classes too, and carry their own wiring. */
-  const isOrmEntityTools = (element: ts.Expression): boolean => {
-    if (!ts.isSpreadElement(element)) return false;
-    const call = resolved(element.expression, ts.isCallExpression);
-    const target = call && callee(call);
-    return target?.name === "ormEntityTools" && target.file?.endsWith("/core/tools/orm/ormEntityTools.ts") === true;
+  /**
+   * Tools made by a function: a Tool of `defineTool`, a set of them, or a call (or a
+   * spread) that gives them. They carry their own wiring, so codegen has nothing to add.
+   */
+  const madeToolType = (type: ts.Type, depth = 0): boolean => {
+    if (depth > 3) return false;
+    const alias = type.aliasSymbol;
+    if (alias && (alias.name === "DefinedTool" || alias.name === "ToolSet")
+      && alias.declarations?.some((entry) => entry.getSourceFile().fileName.replace(/\\/g, "/").endsWith("/core/agent/defineTool.ts"))) return true;
+    if (type.isUnion()) return type.types.every((part) => madeToolType(part, depth + 1));
+    if (checker.isArrayType(type) || checker.isTupleType(type)) {
+      const items = checker.getTypeArguments(type as ts.TypeReference);
+      return items.length > 0 && items.every((item) => madeToolType(item, depth + 1));
+    }
+    if ((type.flags & ts.TypeFlags.Object) === 0 || type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) return false;
+    const members = type.getProperties();
+    return members.length > 0 && members.every((member) => madeToolType(checker.getTypeOfSymbol(member), depth + 1));
+  };
+  const isMadeTools = (element: ts.Expression): boolean =>
+    madeToolType(checker.getTypeAtLocation(ts.isSpreadElement(element) ? element.expression : element));
+  /**
+   * `permissions: orderPermissions`: the exported constant goes to the generated
+   * `permissions.ts`, which makes its keys the type of `can` and `defineRoles`.
+   * A framework pack names its own in its sources.
+   */
+  const collectPermissions = (module: string, initializer: ts.Expression): void => {
+    let symbol = ts.isIdentifier(initializer) ? checker.getSymbolAtLocation(initializer) : undefined;
+    if (symbol && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.valueDeclaration;
+    const file = normalizeProjectPath((declaration ?? initializer).getSourceFile().fileName);
+    // A framework pack names its permissions in its own sources.
+    if (file.includes("/node_modules/") || isFrameworkPackPath(file)) return;
+    const fileSymbol = declaration && checker.getSymbolAtLocation(declaration.getSourceFile());
+    const exported = fileSymbol && symbol && checker.getExportsOfModule(fileSymbol).find((entry) => (entry.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(entry) : entry) === symbol);
+    if (!declaration || !ts.isVariableDeclaration(declaration) || exported === undefined) {
+      fatalErrors.push(`BAZIS_ACCESS_PERMISSIONS_FORM: ${sourceLocation(initializer)}: permissions of ${module}: "${text(initializer)}" — export the result of definePermissions(...) as a constant and name it here, so that its keys become the type of can(...) and defineRoles(...).`);
+      return;
+    }
+    permissionDeclarations.set(`${file}\0${exported.name}`, { name: exported.name, file });
   };
   const checkModule = (module: string, argument: ts.Expression | undefined): void => {
     const object = argument && resolved(argument, ts.isObjectLiteralExpression);
@@ -1099,6 +1183,7 @@ function collectProviderFormErrors(source: ts.SourceFile): void {
     for (const property of object.properties) {
       if (!ts.isPropertyAssignment(property)) continue;
       const field = property.name.getText().replace(/["']/g, "");
+      if (field === "permissions") collectPermissions(module, property.initializer);
       if (field !== "providers" && !CLASS_LISTS.includes(field)) continue;
       const list = resolved(property.initializer, ts.isArrayLiteralExpression);
       if (!list) {
@@ -1107,9 +1192,9 @@ function collectProviderFormErrors(source: ts.SourceFile): void {
       }
       for (const element of list.elements) {
         if (field === "providers") checkProvider(module, element);
-        else if (field === "tools" && isOrmEntityTools(element)) continue;
+        else if (field === "tools" && isMadeTools(element)) continue;
         else if (!ts.isIdentifier(element) && !ts.isPropertyAccessExpression(element)) {
-          fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(element)}: ${field} of ${module}: "${text(element)}" — list the class itself; its constructor dependencies come from codegen.`);
+          fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(element)}: ${field} of ${module}: "${text(element)}" — list the class itself; its constructor dependencies come from codegen.${field === "tools" ? " A Tool made by a function comes from defineTool(...)." : ""}`);
         }
       }
     }
@@ -1182,6 +1267,13 @@ function readInheritedConstructorDeps(node: ts.ClassDeclaration): ConstructorDep
   return { deps };
 }
 
+/** The section of a `defineConfig("mail", …)` declaration by its type: the literal of its `prefix`. */
+function configPrefixOf(type: ts.Type): string | undefined {
+  const prefix = type.getProperty("prefix");
+  const literal = prefix && checker.getTypeOfSymbol(prefix);
+  return literal?.isStringLiteral() ? literal.value : undefined;
+}
+
 function dependencyFromType(type: ts.Type): CollectedDependency | undefined {
   if (type.flags & ts.TypeFlags.TypeParameter) return undefined;
   const symbol = type.getSymbol();
@@ -1191,8 +1283,11 @@ function dependencyFromType(type: ts.Type): CollectedDependency | undefined {
   const name = declaration?.name?.text ?? type.aliasSymbol?.name ?? symbol?.name;
   if (!name || BUILTIN_DEPENDENCY_NAMES.has(name)) return undefined;
   const arguments_ = type.flags & ts.TypeFlags.Object ? checker.getTypeArguments(type as ts.TypeReference) : [];
-  if (name === "ConfigView") {
-    const configType = arguments_[0];
+  if (name === "ConfigView" || name === "ResolvedConfigView") {
+    // ConfigView<typeof mailConfig>: the declaration carries the name of its section in its type.
+    const declared = type.aliasTypeArguments?.[0] && configPrefixOf(type.aliasTypeArguments[0]);
+    if (declared !== undefined) return { name: `Config:${declared}` };
+    const configType = type.aliasTypeArguments?.[0] ?? arguments_[0];
     const configTypeName = configType && (configType.aliasSymbol?.name ?? configType.getSymbol()?.name);
     return configTypeName ? { name: `ConfigView<${configTypeName}>` } : undefined;
   }
@@ -1244,6 +1339,12 @@ function readConstructorTypeNames(node: ts.ClassDeclaration): ConstructorDepende
 
     if (refName === "ConfigView" && paramType && ts.isTypeReferenceNode(paramType)) {
       const configType = paramType.typeArguments?.[0];
+      if (configType && ts.isTypeQueryNode(configType)) {
+        // ConfigView<typeof mailConfig>: the declaration carries the name of its section in its type.
+        const declared = configPrefixOf(checker.getTypeFromTypeNode(configType));
+        deps.push({ name: declared === undefined ? `ConfigView<${configType.getText()}>` : `Config:${declared}`, ...optionalFlag });
+        continue;
+      }
       const configTypeName = configType ? getDependencyTypeName(configType) : undefined;
       if (configTypeName) {
         deps.push({ name: `ConfigView<${configTypeName}>`, ...optionalFlag });

package/core/testing/index.ts

@@ -1,9 +1,8 @@
-import { HOSTED_SERVICE, type BazisModuleRef, type DiContainer, type ProviderDefinition } from "../di";
+import { HOSTED_SERVICE, type BazisModuleRef, type DiContainer, type ProviderDefinition, type Token } from "../di";
 import { loadBazisGeneratedRuntime } from "../generatedRuntime";
 import { HttpServer, type HttpModuleOptions } from "../http";
 import { KernelBuilder, type Kernel } from "../kernel";
-import { composeApp } from "../app/runApp";
-import type { RunAppOptions } from "../app";
+import { appOptionsOf, composeApp, type AppSettings } from "../app/runApp";
 
 export interface TestContainerOptions {
   /** Replacements for registered providers: `singleton(ITaskStore, FakeStore)`. */
@@ -23,18 +22,30 @@ export interface TestContainerOptions {
  * const container = await createTestContainer(TaskModule, { overrides: [singleton(ITaskStore, FakeStore)] });
  * const tasks = container.createScope().resolve(TaskService);
  * ```
+ *
+ * Given an `@App` class, the graph also holds its infrastructure, cache and configs.
  */
 export async function createTestContainer(root: BazisModuleRef, options: TestContainerOptions = {}): Promise<DiContainer> {
   await loadBazisGeneratedRuntime();
-  const builder = new KernelBuilder(root).useOptions({ startupReport: false, environment: "test", signals: [] });
+  const declared = appOptionsOf(root);
+  const graph = declared === undefined ? root : composeApp(root, { infra: declared.infra, cache: declared.cache, config: declared.config, language: declared.language, messages: declared.messages });
+  const builder = new KernelBuilder(graph).useOptions({ startupReport: false, environment: "test", signals: [] });
   options.configure?.(builder);
   if (options.overrides !== undefined) builder.useOverrides(options.overrides);
   const kernel: Kernel = await builder.build();
   return kernel.container;
 }
 
-export interface TestAppOptions extends Omit<RunAppOptions, "http"> {
-  /** HTTP options; the test app always listens on 127.0.0.1 and a free port. `false`: no HTTP server. */
+/**
+ * What a test changes in the application it starts. For an `@App` class every
+ * field replaces the declared one; for a module it is the whole description.
+ */
+export interface TestAppOptions extends Omit<AppSettings, "http"> {
+  /**
+   * HTTP options; the test app always listens on 127.0.0.1 and a free port.
+   * `false`: no HTTP server. Left out: the `http` of the `@App` class; a module
+   * (or an `@App` without `http`, given other HTTP options here) gets a server with the defaults.
+   */
   readonly http?: Omit<HttpModuleOptions, "port" | "hostname"> | false;
   /** Replacements for registered providers, see `createContainer` `overrides`. */
   readonly overrides?: readonly ProviderDefinition[];
@@ -45,7 +56,16 @@ export interface TestApp {
   readonly url: string;
   /** `fetch` relative to {@link url}: `app.fetch("/tasks/1")`. */
   fetch(path: string, init?: RequestInit): Promise<Response>;
-  /** The application container: `app.container.createScope().resolve(TaskService)`. */
+  /**
+   * Calls a service the way a request does: in a scope of its own, closed when
+   * the work is done.
+   *
+   * ```ts
+   * const task = await app.use(ITaskService, (tasks) => tasks.create("Write the report"));
+   * ```
+   */
+  use<T, R>(service: Token<T>, work: (service: T) => R | Promise<R>): Promise<R>;
+  /** The application container, when {@link use} is not enough: singletons, several services of one scope. */
   readonly container: DiContainer;
   /** Graceful stop, like SIGTERM in a real run. */
   stop(): Promise<void>;
@@ -57,20 +77,32 @@ export interface TestApp {
  * Configuration errors and failing startup throw instead of exiting the process.
  *
  * ```ts
- * const app = await startTestApp(AppModule, { overrides: [singleton(ITaskStore, FakeStore)] });
+ * const app = await startTestApp(TodoApp, { overrides: [singleton(ITaskStore, FakeStore)] });
  * try {
  *   expect((await app.fetch("/tasks/1")).status).toBe(200);
  * } finally {
  *   await app.stop();
  * }
  * ```
+ *
+ * `root` is the `@App` class: the test starts what production starts, and the
+ * options only say what differs. A single module works too, to test a part of
+ * the application: `startTestApp(TaskModule, { infra: TestInfra })`.
  */
 export async function startTestApp(root: BazisModuleRef, options: TestAppOptions = {}): Promise<TestApp> {
   await loadBazisGeneratedRuntime();
-  const { http, overrides, configure, kernel: kernelOptions, ...rest } = options;
-  const appRoot = composeApp(root, { ...rest, http: http === false ? undefined : { ...http, hostname: "127.0.0.1", port: 0 } });
+  const declared = appOptionsOf(root);
+  const { modules: _modules, ...base } = declared ?? { modules: [] };
+  const merged: TestAppOptions & { readonly http?: HttpModuleOptions | Omit<HttpModuleOptions, "port" | "hostname"> | false } = { ...base, ...options };
+  const { http: _http, overrides, configure, kernel: kernelOptions, ...rest } = merged;
+  // A worker application (an `@App` without `http`) stays without a server unless the test asks for one.
+  const serve = options.http !== false && (declared === undefined || declared.http !== undefined || options.http !== undefined);
+  const http = options.http === false ? undefined : { ...declared?.http, ...options.http };
+  const appRoot = composeApp(root, { ...rest, http: serve ? { ...http, hostname: "127.0.0.1", port: 0 } : undefined });
   const builder = new KernelBuilder(appRoot).useOptions({ startupReport: false, ...kernelOptions, environment: kernelOptions?.environment ?? "test", signals: [] });
-  configure?.(builder);
+  if (declared !== undefined) builder.useApplicationRoot(root);
+  declared?.configure?.(builder);
+  if (configure !== declared?.configure) configure?.(builder);
   if (overrides !== undefined) builder.useOverrides(overrides);
   const kernel: Kernel = await builder.build();
   await kernel.start();
@@ -79,6 +111,14 @@ export async function startTestApp(root: BazisModuleRef, options: TestAppOptions
   return {
     url,
     container: kernel.container,
+    use: async (service, work) => {
+      const scope = kernel.container.createScope();
+      try {
+        return await work(scope.resolve(service));
+      } finally {
+        await scope.dispose();
+      }
+    },
     fetch: (path, init) => {
       if (!url) throw new Error("startTestApp was started with http: false.");
       return fetch(`${url}${path}`, init);

package/core/tools/StandardTools.module.ts

@@ -16,7 +16,7 @@ import { ConfigSecretStore, SecretStore } from "./secrets/SecretStore";
   config: [toolsConfig],
   references: { "orm.entity": OrmEntityReferences, "orm.field": OrmFieldReferences },
   tools: [HttpRequestTool],
-  providers: [singleton(OrmEntityReferences), singleton(OrmFieldReferences), singleton(SecretStore, ConfigSecretStore)],
+  providers: [singleton(SecretStore, ConfigSecretStore)],
   exports: [SecretStore],
 })
 export class StandardToolsModule {}

package/core/tools/contracts/Tools.config.ts

@@ -1,29 +1,35 @@
-import { defineConfig } from "../../kernel";
+import { configList, defineConfig } from "../../kernel";
 
 /**
- * Settings of the standard Tools. `http.allow` is the comma-separated list of hosts
- * `http.request` may reach: `api.example.com`, `*.example.com`, `localhost:8080`.
+ * Settings of the standard Tools. `http.allow` is the list of hosts `http.request`
+ * may reach, comma-separated in the environment: `api.example.com`, `*.example.com`,
+ * `localhost:8080`.
  * Empty by default: requests go nowhere. `http.allowPrivateNetworks` lets it reach
  * private and loopback addresses of a listed host: intranet services, tests.
  * `http.callers` says who may call it: `workflow`, `agent`.
  */
 export interface ToolsSettings {
-  readonly "http.allow": string;
-  readonly "http.callers": string;
+  readonly "http.allow": readonly string[];
+  readonly "http.callers": readonly string[];
   readonly "http.allowPrivateNetworks": boolean;
   readonly "http.maxResponseBytes": number;
   readonly "http.timeoutMs": number;
 }
 
+/** A host, a subdomain pattern or an IPv6 address in brackets, with an optional port. */
+const HOST = /^(\*\.)?[A-Za-z0-9]([A-Za-z0-9.-]*[A-Za-z0-9])?(:\d{1,5})?$|^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/;
+
 export const toolsConfig = defineConfig<ToolsSettings>("tools", {
   default: {
-    "http.allow": "",
-    "http.callers": "workflow",
+    "http.allow": configList(),
+    "http.callers": configList(["workflow"]),
     "http.allowPrivateNetworks": false,
     "http.maxResponseBytes": 1_048_576,
     "http.timeoutMs": 30_000,
   },
   validate: {
+    "http.allow": (value) => value.find((item) => !HOST.test(item)) === undefined ? undefined : `must list hosts like api.example.com, *.example.com or localhost:8080; ${JSON.stringify(value.find((item) => !HOST.test(item)))} is not one`,
+    "http.callers": (value) => (value.every((item) => /^[a-z][a-z0-9_.-]{0,63}$/.test(item)) ? undefined : "must list caller ids like workflow, agent"),
     "http.maxResponseBytes": (value) => (Number.isSafeInteger(value) && value >= 1 && value <= 104_857_600 ? undefined : "must be an integer 1–104857600"),
     "http.timeoutMs": (value) => (Number.isSafeInteger(value) && value >= 1 && value <= 600_000 ? undefined : "must be an integer 1–600000"),
   },

package/core/tools/generated/deps.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by `bun run di:generate` (framework.packs of bazis.config.json).
 // Do not edit manually.
 import { registerFrameworkClassDeps } from "../../di/module/autoDeps";
-import { ServiceProvider } from "../../di/ServiceProvider";
+import { ToolRunner } from "../../agent/ToolRunner";
 import { Configuration } from "../../kernel/config/Configuration";
 import { HttpRequestTool } from "../http/HttpRequest.tool";
 import { OrmEntityReferences, OrmFieldReferences } from "../orm/OrmEntity.references";
@@ -10,6 +10,6 @@ import { ConfigSecretStore } from "../secrets/SecretStore";
 registerFrameworkClassDeps([
   [ConfigSecretStore, [Configuration]],
   [HttpRequestTool, ["Config:tools"]],
-  [OrmEntityReferences, [ServiceProvider]],
-  [OrmFieldReferences, [ServiceProvider]],
+  [OrmEntityReferences, [ToolRunner]],
+  [OrmFieldReferences, [ToolRunner]],
 ]);

package/core/tools/http/HttpRequest.tool.ts

@@ -82,8 +82,7 @@ export class HttpRequestTool {
   constructor(private readonly config: ConfigView<ToolsSettings>) {}
 
   async execute(raw: unknown, context: AgentToolExecutionContext): Promise<unknown> {
-    const callers = this.config.get("http.callers").split(",").map((item) => item.trim());
-    if (context.caller !== undefined && !callers.includes(context.caller)) throw new ToolError(`tools.http.callers does not list ${context.caller}`, { reason: "caller_not_allowed" });
+    if (context.caller !== undefined && !this.config.get("http.callers").includes(context.caller)) throw new ToolError(`tools.http.callers does not list ${context.caller}`, { reason: "caller_not_allowed" });
     const request = this.requestOf(raw);
     if (context.dryRun === true && !SAFE_METHODS.has(request.method)) return { dryRun: true };
     const signal = AbortSignal.any([context.signal, AbortSignal.timeout(request.timeoutMs)]);

package/core/tools/http/publicAddress.ts

@@ -82,9 +82,9 @@ export function isPublicAddress(address: string): boolean {
 }
 
 /** Whether `tools.http.allow` lets this host and port through: `api.example.com`, `*.example.com`, `localhost:8080`. */
-export function hostAllowed(allow: string, hostname: string, port: string): boolean {
+export function hostAllowed(allow: readonly string[], hostname: string, port: string): boolean {
   const host = hostname.toLowerCase().replace(/\.$/, "");
-  return allow.split(",").map((item) => item.trim().toLowerCase()).filter((item) => item !== "").some((item) => {
+  return allow.map((item) => item.toLowerCase()).some((item) => {
     // An IPv6 address goes in brackets, as in a URL: [::1]:8080.
     const match = /^\[(.+)\](?::(\d+))?$/.exec(item) ?? /^(.*?)(?::(\d+))?$/.exec(item)!;
     const [name, wanted] = [match[1]!, match[2]];

package/core/tools/index.ts

@@ -8,4 +8,4 @@ export { StandardToolsModule } from "./StandardTools.module";
 export { toolsConfig, type ToolsSettings } from "./contracts/Tools.config";
 export { HttpRequestTool } from "./http/HttpRequest.tool";
 export { ConfigSecretStore, SecretStore, type SecretContext } from "./secrets/SecretStore";
-export { ormEntityTools, type OrmEntityOperation, type OrmEntityToolsOptions } from "./orm/ormEntityTools";
+export { ormEntityTools, type OrmEntityOperation, type OrmEntityToolInputs, type OrmEntityToolOutputs, type OrmEntityToolSet, type OrmEntityToolsOptions, type OrmEntityWhere } from "./orm/ormEntityTools";

package/core/tools/orm/OrmEntity.references.ts

@@ -1,13 +1,12 @@
 import type { ReferenceContext, ReferenceItem, ReferencePage } from "../../access";
 import { References } from "../../access";
-import { AgentRegistry } from "../../agent/AgentRegistry";
-import type { ServiceProvider } from "../../di";
+import type { ToolRunner } from "../../agent";
 import { ormEntityToolInfo, type OrmEntityToolInfo } from "./ormEntityTools";
 
 /** What `ormEntityTools` opened in this application: only that is referenced. */
-function opened(services: ServiceProvider): readonly OrmEntityToolInfo[] {
+function opened(tools: ToolRunner): readonly OrmEntityToolInfo[] {
   const entities = new Map<string, Set<string>>();
-  for (const tool of AgentRegistry.fromContainer(services).listTools()) {
+  for (const tool of tools.listTools()) {
     const info = ormEntityToolInfo(tool.target);
     if (info === undefined) continue;
     const fields = entities.get(info.entity) ?? new Set<string>();
@@ -24,12 +23,12 @@ function page(ids: readonly string[], text: string, { limit, offset }: Reference
 
 /** Reference kind `orm.entity`: an entity open to processes, `Order`. */
 export class OrmEntityReferences extends References {
-  constructor(private readonly services: ServiceProvider) {
+  constructor(private readonly tools: ToolRunner) {
     super();
   }
 
   private ids(): readonly string[] {
-    return opened(this.services).map((item) => item.entity);
+    return opened(this.tools).map((item) => item.entity);
   }
 
   async exists(ids: readonly string[]): Promise<ReadonlySet<string>> {
@@ -48,12 +47,12 @@ export class OrmEntityReferences extends References {
 
 /** Reference kind `orm.field`: a field open to processes, `Order.status`, or `status` within `Order`. */
 export class OrmFieldReferences extends References {
-  constructor(private readonly services: ServiceProvider) {
+  constructor(private readonly tools: ToolRunner) {
     super();
   }
 
   private ids(): readonly string[] {
-    return opened(this.services).flatMap((item) => item.fields.map((field) => `${item.entity}.${field}`));
+    return opened(this.tools).flatMap((item) => item.fields.map((field) => `${item.entity}.${field}`));
   }
 
   async exists(ids: readonly string[], context: ReferenceContext): Promise<ReadonlySet<string>> {

package/core/tools/orm/ormEntityTools.ts

@@ -1,15 +1,14 @@
-import { Tool, ToolError, type AgentToolExecutionContext } from "../../agent";
-import { type Class, ServiceProvider } from "../../di";
-import { registerFrameworkClassDeps } from "../../di/module/autoDeps";
+import { defineTool, ToolError, type AgentToolExecutionContext, type DefinedTool } from "../../agent";
+import type { Class } from "../../di";
 import { ModelBuilder, type DbContext, type DbSet, type EntityModel, type FieldSelector, type Operand, type Predicate, type PropertyModel } from "../../orm";
 
 /** What a process may do with an entity. */
 export type OrmEntityOperation = "find" | "create" | "update" | "delete";
 
-export interface OrmEntityToolsOptions {
+export interface OrmEntityToolsOptions<Op extends OrmEntityOperation = OrmEntityOperation> {
   /** The context of the entity, from `@Module({ ormBazis })`. */
   readonly context: Class<DbContext>;
-  readonly ops: readonly OrmEntityOperation[];
+  readonly ops: readonly Op[];
   /** The only fields a Tool reads, filters by, sorts by and writes. The key is always read and filtered by, never written. */
   readonly fields: readonly string[];
   /**
@@ -28,6 +27,33 @@ export interface OrmEntityToolsOptions {
   readonly maxChanges?: number;
 }
 
+/** A filter of records: field → a value to equal, or `{ eq, ne, gt, gte, lt, lte, in, nin, contains, startsWith, isNull }`. */
+export type OrmEntityWhere = Readonly<Record<string, unknown>>;
+
+/** What each Tool takes, as a step of a process maps it. */
+export interface OrmEntityToolInputs {
+  readonly find: {
+    readonly where?: OrmEntityWhere;
+    readonly sort?: readonly { readonly field: string; readonly dir?: "asc" | "desc" }[];
+    readonly limit?: number;
+    readonly offset?: number;
+  };
+  readonly create: { readonly values: Readonly<Record<string, unknown>> };
+  readonly update: { readonly where: OrmEntityWhere; readonly values: Readonly<Record<string, unknown>> };
+  readonly delete: { readonly where: OrmEntityWhere };
+}
+
+/** What each Tool gives back; a trial run adds `dryRun: true` to what would have changed. */
+export interface OrmEntityToolOutputs {
+  readonly find: { readonly items: readonly Readonly<Record<string, unknown>>[]; readonly total: number };
+  readonly create: { readonly item: Readonly<Record<string, unknown>>; readonly dryRun?: boolean };
+  readonly update: { readonly updated: number; readonly dryRun?: boolean };
+  readonly delete: { readonly deleted: number; readonly dryRun?: boolean };
+}
+
+/** The Tools of the listed operations, by operation: `orderTools.find`. */
+export type OrmEntityToolSet<Op extends OrmEntityOperation = OrmEntityOperation> = { readonly [P in Op]: DefinedTool<OrmEntityToolInputs[P], OrmEntityToolOutputs[P]> };
+
 /** What the reference kinds `orm.entity` and `orm.field` read about a made Tool. */
 export interface OrmEntityToolInfo {
   readonly entity: string;
@@ -66,15 +92,20 @@ type Run = (set: DbSet<object>, input: Json, context: AgentToolExecutionContext,
 /**
  * Tools `orm.<entity>.find|create|update|delete` over an entity of the application
  * (WORKFLOW-002 §7.4). Nothing is open by itself: the application names the
- * operations and the fields. The result goes to `@Module({ tools })`, and the
- * module imports `StandardToolsModule` for the reference kinds `orm.entity` and
- * `orm.field`. All of them run with `context.dryRun`: nothing is written then.
+ * operations and the fields. The result is a set of Tools named by operation: it
+ * goes to `@Module({ tools })`, and a process names a Tool of it by reference.
+ * The module imports `StandardToolsModule` for the reference kinds `orm.entity`
+ * and `orm.field`. All of them run with `context.dryRun`: nothing is written then.
  *
  * ```ts
- * @Module({ imports: [StandardToolsModule], tools: [...ormEntityTools(Order, { context: OrdersDbContext, ops: ["find", "update"], fields: ["status", "amount"], partitionField: "shopId" })] })
+ * export const orderTools = ormEntityTools(Order, { context: OrdersDbContext, ops: ["find", "update"], fields: ["status", "amount"], partitionField: "shopId" });
+ *
+ * @Module({ imports: [StandardToolsModule], tools: [orderTools] })
+ *
+ * serviceTask({ tool: orderTools.find, input: { where: { status: "new" } } })
  * ```
  */
-export function ormEntityTools(entity: EntityClass<object>, options: OrmEntityToolsOptions): Class<object>[] {
+export function ormEntityTools<const Op extends OrmEntityOperation>(entity: EntityClass<object>, options: OrmEntityToolsOptions<Op>): OrmEntityToolSet<Op> {
   const model = ModelBuilder.build(entity);
   const name = options.name ?? entity.name.replace(/(?<=[a-z0-9])[A-Z]/g, (letter) => `-${letter}`).toLowerCase();
   const fail = (problem: string) => new TypeError(`ormEntityTools(${entity.name}): ${problem}`);
@@ -101,10 +132,12 @@ export function ormEntityTools(entity: EntityClass<object>, options: OrmEntityTo
     maxChanges,
   };
   const callers = options.callers ?? ["workflow"];
-  return [...new Set(options.ops)].map((op) => {
+  const tools: Partial<Record<OrmEntityOperation, DefinedTool>> = {};
+  for (const op of new Set<OrmEntityOperation>(options.ops)) {
     if (!Object.hasOwn(OPERATIONS, op)) throw fail(`unknown operation ${JSON.stringify(op)}`);
-    return toolClass(spec, op, callers);
-  });
+    tools[op] = madeTool(spec, op, callers);
+  }
+  return Object.freeze(tools) as OrmEntityToolSet<Op>;
 }
 
 function limit(value: number | undefined, fallback: number, max: number, fail: (problem: string) => Error, name: string): number {
@@ -113,10 +146,9 @@ function limit(value: number | undefined, fallback: number, max: number, fail: (
   return value;
 }
 
-function toolClass(spec: Spec, op: OrmEntityOperation, callers: readonly string[]): Class<object> {
+function madeTool(spec: Spec, op: OrmEntityOperation, callers: readonly string[]): DefinedTool {
   const { describe, run, sideEffect, input, output } = OPERATIONS[op];
-
-  @Tool({
+  const tool = defineTool({
     name: `orm.${spec.name}.${op}`,
     description: describe(spec.entity.name),
     sideEffect,
@@ -124,19 +156,13 @@ function toolClass(spec: Spec, op: OrmEntityOperation, callers: readonly string[
     dryRun: "supported",
     inputSchema: input(spec),
     outputSchema: output(spec),
-  })
-  class OrmEntityTool {
-    constructor(private readonly services: ServiceProvider) {}
-
-    async execute(raw: unknown, context: AgentToolExecutionContext): Promise<unknown> {
-      const db = this.services.resolve(spec.context) as DbContext;
+    execute: async (raw, context, services) => {
+      const db = services.resolve(spec.context) as DbContext;
       return await run(spec)(db.setOf(spec.entity), inputOf(raw), context, db);
-    }
-  }
-
-  registerFrameworkClassDeps([[OrmEntityTool, [ServiceProvider]]]);
-  INFO.set(OrmEntityTool, { entity: spec.entity.name, fields: spec.readable });
-  return OrmEntityTool;
+    },
+  });
+  INFO.set(tool, { entity: spec.entity.name, fields: spec.readable });
+  return tool;
 }
 
 interface Operation {