bazis 0.98.33 → 0.99.0

package/core/cache/errors/CacheError.ts

@@ -1,7 +1,8 @@
+import { DiError } from "../../di";
 /** Base error of the cache module. */
 export class CacheError extends Error {
-  public constructor(message: string) {
-    super(message);
+  public constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
     this.name = new.target.name;
   }
 }
@@ -12,5 +13,19 @@ export class CacheKeyError extends CacheError {}
 /** Invalid value (size limit exceeded and the like). */
 export class CacheValueError extends CacheError {}
 
+/**
+ * The distributed store did not answer in time or failed. On the cache-aside
+ * path (`getOrCreateAsync`, `@CacheableRedis`) the value is computed without
+ * the cache; explicit operations (`get`, `remove`, `evictByTag`) throw it.
+ */
+export class CacheUnavailableError extends CacheError {}
+
 /** The limit of unfinished factories is exhausted; the new factory was not started. */
 export class CacheCapacityError extends CacheError {}
+
+/**
+ * A cache declaration that can never work, found while the container is built
+ * (a cached scoped method without a key, a cached transient service). A DI
+ * error, so the start prints it as a configuration error.
+ */
+export class CacheDeclarationError extends DiError {}

package/core/cache/http/outputRedisCacheMiddleware.ts

@@ -1,5 +1,5 @@
 import type { HttpMiddleware } from "../../http";
-import { CacheError } from "../errors/CacheError";
+import { CacheError, CacheUnavailableError } from "../errors/CacheError";
 import { DISTRIBUTED_OUTPUT_CACHE } from "../tokens/DISTRIBUTED_CACHE";
 import {
   DEFAULT_OUTPUT_CACHE_METHODS,
@@ -14,6 +14,7 @@ import {
   resolveCachedHttpPayloadReadOptions,
   responseAllowsServerCache,
   responseToCachedPayload,
+  type CachedHttpPayload,
 } from "./CachedHttpPayload";
 
 export interface OutputRedisCacheMiddlewareOptions {
@@ -81,7 +82,15 @@ export function outputRedisCacheMiddleware(options: OutputRedisCacheMiddlewareOp
     }
 
     const key = buildRedisOutputCacheKey(ctx, routeName, config);
-    const cached = await cache.get(key);
+    let cached: CachedHttpPayload | undefined;
+    try {
+      cached = await cache.get(key);
+    } catch (error) {
+      // The cache is optional: an unavailable store serves the route uncached.
+      if (!(error instanceof CacheUnavailableError)) throw error;
+      await next();
+      return;
+    }
     if (cached !== undefined) {
       ctx.response = applyClientCacheHeaders(cachedPayloadToResponse(cached, { hit: true }), clientCache);
       return;

package/core/cache/index.ts

@@ -51,7 +51,7 @@ export {
   type DistributedCacheVersionCheck,
   type DistributedCachePing,
   type DistributedCacheSetOptions,
-  type IDistributedCache,
+  IDistributedCache,
 } from "./distributed";
 export {
   DISTRIBUTED_CACHE_BACKEND,
@@ -66,7 +66,7 @@ export {
   type CacheModuleConfig,
   type CacheOutputCacheOptions,
 } from "./internal/buildCacheProviders";
-export { CacheError, CacheKeyError, CacheValueError, CacheCapacityError } from "./errors/CacheError";
+export { CacheError, CacheKeyError, CacheValueError, CacheCapacityError, CacheDeclarationError, CacheUnavailableError } from "./errors/CacheError";
 
 export { OutputCache, type OutputCacheOptions as OutputCacheDecoratorOptions } from "./decorators/OutputCache";
 export {
@@ -91,7 +91,3 @@ export {
 } from "./internal/resolveCachePolicy";
 export { buildOutputCacheKey, OUTPUT_CACHE_PRINCIPAL_STATE_KEY } from "./http/buildOutputCacheKey";
 export { wrapCachedService, type CacheProxyOptions } from "./services/cacheProxy";
-export {
-  cachedSingleton,
-  cachedScoped,
-} from "./providers/cachedProviders";

package/core/cache/services/cacheProxy.ts

@@ -11,7 +11,7 @@ import {
 } from "../decorators/cacheableRedisMetadata";
 import type { IDistributedCache } from "../distributed/IDistributedCache";
 import type { NamedCacheRegistry } from "../distributed/NamedCacheRegistry";
-import { CacheError } from "../errors/CacheError";
+import { CacheError, CacheValueError } from "../errors/CacheError";
 import type { ICache } from "../ICache";
 import { normalizeCacheKey } from "../internal/normalizeCacheKey";
 import { AutomaticCacheKey } from "../internal/AutomaticCacheKey";
@@ -141,7 +141,11 @@ function wrapDistributedMethod(
         return result instanceof Promise ? await result : result;
       },
       { ttlSeconds: options.seconds, tags: options.tags, lockSeconds: options.lockSeconds },
-    );
+    ).catch((error: unknown) => {
+      // Name the method: "value.at is a Date" alone does not say where.
+      if (error instanceof CacheValueError) throw new CacheValueError(`${className}.${String(methodName)}: ${error.message}`, { cause: error });
+      throw error;
+    });
   };
 }
 

package/core/generatedRuntime.ts

@@ -1,5 +1,4 @@
 import path from "node:path";
-import type { AgentMetadataIndex } from "./agent/AgentRegistry";
 import { registerGeneratedClassDeps, restoreGeneratedClassDeps, snapshotGeneratedClassDeps, type GeneratedClassDependency } from "./di/module/autoDeps";
 import { registerGeneratedBindings, restoreGeneratedBindings, snapshotGeneratedBindings } from "./http/Binding/autoBindings";
 import { registerRequestModelShape, restoreRequestModelRegistry, snapshotRequestModelRegistry, type RequestModelClass, type RequestModelShape } from "./http/Binding/requestModelRegistry";
@@ -27,10 +26,6 @@ type GeneratedRuntimeModule = {
   readonly registerBazisGeneratedRuntime?: () => void | Promise<void>;
 };
 
-type GeneratedAgentCatalogModule = {
-  readonly GENERATED_AGENT_METADATA?: AgentMetadataIndex;
-};
-
 let runtimeLoad: Promise<void> | undefined;
 
 export interface BazisGeneratedTargetDescriptor {
@@ -42,15 +37,12 @@ export interface BazisGeneratedTargetDescriptor {
   readonly listModels: readonly ListModelClass[];
   readonly openApi: GeneratedOpenApiMetadata;
   readonly openApiSchemaModels: readonly (readonly [GeneratedOpenApiSchemaModel, string])[];
-  /** Target-local generated Agent/Tool/Prompt metadata. */
-  readonly agentMetadata?: AgentMetadataIndex;
   /** Package-internal exact-class metadata attached atomically with this target. */
   readonly providerAttachments?: readonly GeneratedProviderAttachmentV1[];
 }
 
 const committedTargetDescriptors = new Set<string>();
 const targetDescriptorLoads = new Map<string, Promise<void>>();
-const committedTargetDescriptorsById = new Map<string, BazisGeneratedTargetDescriptor>();
 const explicitlyActivatedTargetIds = new Set<string>();
 
 /**
@@ -87,7 +79,6 @@ export function registerBazisGeneratedTargetDescriptor(descriptor: BazisGenerate
       for (const [model, name] of descriptor.openApiSchemaModels) registerGeneratedOpenApiSchemaModel(model, name);
       commitGeneratedProviderAttachments(preparedAttachments);
       committedTargetDescriptors.add(descriptor.id);
-      committedTargetDescriptorsById.set(descriptor.id, descriptor);
       explicitlyActivatedTargetIds.add(descriptor.id);
     } catch (error) {
       restoreGeneratedClassDeps(snapshots.classDeps);
@@ -136,28 +127,6 @@ export function loadBazisGeneratedRuntime(): Promise<void> {
   return runtimeLoad;
 }
 
-export async function loadBazisGeneratedAgentMetadata(
-  targets: readonly Class<object>[] = [],
-): Promise<AgentMetadataIndex | undefined> {
-  const registered = selectRegisteredAgentMetadata(targets);
-  if (registered !== undefined || explicitlyActivatedTargetIds.size > 0) return registered;
-  const module = await importGeneratedModule<GeneratedAgentCatalogModule>("agentCatalog");
-  return module?.GENERATED_AGENT_METADATA;
-}
-
-function selectRegisteredAgentMetadata(targets: readonly Class<object>[]): AgentMetadataIndex | undefined {
-  const candidates = [...committedTargetDescriptorsById.values()]
-    .map((descriptor) => descriptor.agentMetadata)
-    .filter((metadata): metadata is AgentMetadataIndex => metadata !== undefined);
-  if (candidates.length === 0) return undefined;
-  for (const metadata of candidates) {
-    for (const target of targets) {
-      if (metadata.agents.has(target) || metadata.tools.has(target) || metadata.prompts.has(target)) return metadata;
-    }
-  }
-  return candidates.length === 1 ? candidates[0] : undefined;
-}
-
 async function loadRuntimeOnce(): Promise<void> {
   const module = await importGeneratedModule<GeneratedRuntimeModule>("runtime");
   await module?.registerBazisGeneratedRuntime?.();

package/core/infra/cache/RedisDistributedCacheBackend.ts

@@ -25,6 +25,8 @@ export interface RedisDistributedCacheTuning {
   readonly maxValueBytes?: number;
   /** Polling interval (ms) while waiting for another worker's result. */
   readonly pollIntervalMs?: number;
+  /** Bound of one Redis operation (ms); on expiry the method runs without the cache. Default 1000. */
+  readonly operationTimeoutMs?: number;
 }
 
 const DEFAULT_KEY_PREFIX = "bazis:cache:";
@@ -59,6 +61,7 @@ export class RedisDistributedCacheBackend implements DistributedCacheStores {
       maxKeyLength: tuning.maxKeyLength,
       maxValueBytes: tuning.maxValueBytes,
       pollIntervalMs: tuning.pollIntervalMs,
+      operationTimeoutMs: tuning.operationTimeoutMs,
     };
 
     const output = new DistributedCache<CachedHttpPayload>(driver, httpPayloadCacheCodec, {

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.33" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.99.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/infra/connectors/llm.ts

@@ -1,5 +1,6 @@
 import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
-import { AGENT_MODEL_PROVIDER, type AgentModelProvider } from "../../agent";
+import { AGENT_MODEL_PROVIDER, AGENT_RUNTIME_OPTIONS, AgentRuntime, type AgentModelProvider } from "../../agent";
+import { DI, SERVICE_PROVIDER, type ProviderDefinition } from "../../di";
 import { reader, requireValue } from "../connectorConfig";
 import { InfraError, type InfraConnector } from "../InfraConnector";
 import { identifyConnector } from "../connectorIdentity";
@@ -54,6 +55,17 @@ export function resolveLlmConnectionOptions<T extends LlmConfigShape>(
   };
 }
 
+/**
+ * `AgentRuntime` on top of the connector's model provider, injectable by type.
+ * Options come from `AGENT_RUNTIME_OPTIONS` when the application registers it.
+ */
+export const agentRuntimeProviders: readonly ProviderDefinition[] = Object.freeze([
+  DI.singleton(DI.factoryProviderWithResolver(AgentRuntime, [AGENT_MODEL_PROVIDER], (resolver, model: AgentModelProvider) => {
+    const services = resolver.resolve(SERVICE_PROVIDER);
+    return new AgentRuntime(services, model, services.has(AGENT_RUNTIME_OPTIONS) ? services.resolve(AGENT_RUNTIME_OPTIONS) : {});
+  })),
+]);
+
 export function llmConnect<T extends LlmConfigShape>(
   config: AppConfig<T>,
   adapter: LlmProviderAdapter,
@@ -62,6 +74,8 @@ export function llmConnect<T extends LlmConfigShape>(
   return identifyConnector({
     token: AGENT_MODEL_PROVIDER,
     config,
+    providers: agentRuntimeProviders,
+    exports: [AgentRuntime],
     create(configs) {
       return adapter.create(resolveLlmConnectionOptions(config, options, configs));
     },

package/core/infra/connectors/llmRouter.ts

@@ -1,6 +1,7 @@
 import type { AppConfig } from "../../kernel";
 import {
   AGENT_MODEL_PROVIDER,
+  AgentRuntime,
   agentModelRequest,
   type AgentModelProvider,
   type AgentModelProviderContext,
@@ -11,6 +12,7 @@ import { InfraError, type InfraConnector } from "../InfraConnector";
 import { redactSensitiveText } from "../../../library/redaction";
 import { awaitAbortable } from "../../kernel/internal/awaitAbortable";
 import {
+  agentRuntimeProviders,
   resolveLlmConnectionOptions,
   type LlmConfigShape,
   type LlmConnectionOptions,
@@ -408,6 +410,8 @@ export function llmRouter(
   return {
     token: AGENT_MODEL_PROVIDER,
     config: configs,
+    providers: agentRuntimeProviders,
+    exports: [AgentRuntime],
     create(configs) {
       // The router must have an owner before adapters allocate resources.
       // Initialization happens inside an awaited operation, so rollback can

package/core/infra/connectors/redis.ts

@@ -3,6 +3,7 @@ import {
   DISTRIBUTED_CACHE_BACKEND,
   DISTRIBUTED_OUTPUT_CACHE,
   DISTRIBUTED_SERVICE_CACHE,
+  IDistributedCache,
   type DistributedCacheStores,
 } from "../../cache";
 import { createToken, DI, type InjectionToken, type ProviderDefinition } from "../../di";
@@ -60,6 +61,13 @@ function distributedCacheProviders(tuning: RedisDistributedCacheTuning, token: I
         backend.serviceCache,
       ),
     ),
+    // This connector's one connection by type, for services that evict tags or
+    // read values; its name may be "default" or the configured `connection`.
+    DI.singleton(
+      DI.factoryProvider(IDistributedCache, [DISTRIBUTED_CACHE_BACKEND], (backend: DistributedCacheStores) =>
+        backend.serviceCache.resolve(backend.serviceCache.connectionNames[0]),
+      ),
+    ),
   ];
 }
 
@@ -91,7 +99,7 @@ export function redisConnect<T extends RedisConfigShape>(
     token,
     config,
     providers: cacheProviders,
-    exports: cacheProviders ? [DISTRIBUTED_CACHE_BACKEND, DISTRIBUTED_OUTPUT_CACHE, DISTRIBUTED_SERVICE_CACHE] : undefined,
+    exports: cacheProviders ? [DISTRIBUTED_CACHE_BACKEND, DISTRIBUTED_OUTPUT_CACHE, DISTRIBUTED_SERVICE_CACHE, IDistributedCache] : undefined,
     create(configs) {
       return new RedisClient(redisUrl(reader(config, configs).get("url")));
     },

package/core/scripts/di-generate.ts

@@ -7,7 +7,7 @@ import {
   type OpenApiCodegenOperationSpec,
   type OpenApiCodegenSchema,
 } from "../../library/openapi/codegen";
-import { generateAgentMetadataCatalog, type AgentCodegenSource } from "./agent-codegen";
+import { collectToolSchemaModels, type ToolCodegenSource } from "./tool-codegen";
 import {
   analyzeRequestModelHydration,
   type RequestModelHydration,
@@ -30,8 +30,6 @@ const FRAMEWORK_SOURCE = ((): string | null => {
   try { return realpathSync("src/bazis") === FRAMEWORK_DIR ? "src/bazis" : null; } catch { return null; }
 })();
 const FRAMEWORK_ROOT = FRAMEWORK_SOURCE ?? "src/bazis";
-const CORE_AGENT_CATALOG_FILE = `${FRAMEWORK_ROOT}/core/agent/generated/catalog.ts`;
-const CORE_AGENT_GENERATED_DIR = `${FRAMEWORK_ROOT}/core/agent/generated`;
 const isFrameworkSourcePath = (file: string): boolean => FRAMEWORK_SOURCE !== null && file.startsWith(`${FRAMEWORK_SOURCE}/`);
 const APP_GENERATED_DIR = "src/generated/bazis";
 let activeGeneratedDir = APP_GENERATED_DIR;
@@ -209,10 +207,10 @@ let ambiguousClassNames = new Set<string>();
 // Exact roots that do not need convention name resolution: @RequestModel()
 // classes used by generated transport schemas.
 let explicitRequestModelRoots = new Set<ts.ClassDeclaration>();
-let agentCodegenSources: AgentCodegenSource[] = [];
+let toolCodegenSources: ToolCodegenSource[] = [];
 
 const ROUTE_DECORATORS = new Set(["Get", "Post", "Put", "Patch", "Delete", "Options", "Head", "All"]);
-const CODEGEN_CHANNEL_DECORATORS = new Set(["Controller", "GrpcController", "WebSocketGateway", "Agent", "Tool", "Prompt", "RequestModel", "UiProfile"]);
+const CODEGEN_CHANNEL_DECORATORS = new Set(["Controller", "GrpcController", "WebSocketGateway", "Tool", "RequestModel", "UiProfile"]);
 const PRIMITIVE_QUERY_TYPES: Record<string, HttpBindingSpec["type"]> = {
   string: "string",
   number: "number",
@@ -251,12 +249,7 @@ const BUILTIN_DEPENDENCY_NAMES = new Set([
 function isScannableFile(filePath: string): boolean {
   if (filePath.startsWith("../") || path.isAbsolute(filePath)) return false;
   if (!filePath.endsWith(".ts") || filePath.endsWith(".d.ts") || /\.(test|spec)\.ts$/.test(filePath)) return false;
-  if (
-    filePath === CORE_AGENT_CATALOG_FILE ||
-    filePath.startsWith(`${APP_GENERATED_DIR}/`)
-  ) {
-    return false;
-  }
+  if (filePath.startsWith(`${APP_GENERATED_DIR}/`)) return false;
   return !/(^|\/)(test|tests|__tests__|fixture|fixtures|__fixtures__|generated|node_modules|vendor|dist|build|bin|coverage|examples)(\/|$)/.test(filePath) && !filePath.startsWith("admin-ui/");
 }
 
@@ -414,7 +407,7 @@ function sourceHasCodegenCandidate(source: ts.SourceFile): boolean {
       const decorators = ts.getDecorators(node) ?? [];
       const constructorDeps = readConstructorTypeNames(node);
       // Shared all-channel boundary index: any class that feeds DI/HTTP,
-      // request/list, OpenAPI/UI, Agent/Tool/Prompt analysis must
+      // request/list, OpenAPI/UI, Tool analysis must
       // be owned by exactly one configured target before rendering begins.
       if (
         decorators.some((decorator) => {
@@ -456,7 +449,7 @@ function resetTargetAnalysis(files: Set<string>, generatedDir: string): void {
   httpBindings = {}; httpControllerFiles = {}; openApiSchemas = {}; openApiOperations = {};
   grpcBindings = new Map();
   uiProfileResponseModels = new Map(); openApiSchemaModels = new Map(); requestModelClassNames = new Set(); listRequestClassNames = new Set();
-  classFilesByName = new Map(); classDeclarationsByName = new Map(); ambiguousClassNames = new Set(); explicitRequestModelRoots = new Set(); agentCodegenSources = [];
+  classFilesByName = new Map(); classDeclarationsByName = new Map(); ambiguousClassNames = new Set(); explicitRequestModelRoots = new Set(); toolCodegenSources = [];
   sourceEntries = [...files].sort((a, b) => a.localeCompare(b)).map((filePath) => ({ filePath, source: programFiles.get(filePath) as ts.SourceFile }));
   sourceFilePathSet = new Set(sourceEntries.map((entry) => entry.filePath));
   openApiCodegen = createOpenApiCodegenAnalyzer({ checker, sourceFiles: sourceEntries.map((entry) => entry.source), schemaNameForDuplicate: duplicateOpenApiSchemaName });
@@ -478,7 +471,7 @@ async function generateTarget(name: string, reachable: Set<string>, production:
     if (!FRAMEWORK_INTERNAL_PREFIXES.some((prefix) => filePath.startsWith(prefix))) {
       collectClassDeps(source);
       collectGrpcBindings(source);
-      agentCodegenSources.push({ filePath, sourceFile: source });
+      toolCodegenSources.push({ filePath, sourceFile: source });
     }
     collectHttpBindings(source); collectOpenApiSchemas(source); collectUiProfileResponseModels(source);
   }
@@ -487,46 +480,39 @@ async function generateTarget(name: string, reachable: Set<string>, production:
   const requestModelImports = resolveRequestModelImports();
   const requestModelHydration = resolveRequestModelHydration(requestModelImports);
   const listModelImports = resolveListModelImports();
-  const agent = generateAgentMetadataCatalog(agentCodegenSources, {
-    generatedDir, frameworkImports: "public", schemaNameForDeclaration: openApiCodegen.schemaNameForDeclaration,
-  });
-  const schemaModels = resolveOpenApiSchemaModelImports(agent.schemaModels, agent.schemaNames);
-  classifyAgentWarnings(agent.warnings); failOnFatalErrors();
+  const tools = collectToolSchemaModels(toolCodegenSources, { schemaNameForDeclaration: openApiCodegen.schemaNameForDeclaration });
+  const schemaModels = resolveOpenApiSchemaModelImports(tools.schemaModels, tools.schemaNames);
+  classifyToolWarnings(tools.warnings); failOnFatalErrors();
   const analysisMs = performance.now() - startedAt;
   const renderStartedAt = performance.now();
   const requestModels = renderRequestModels(requestModelImports, requestModelHydration);
   const listModels = renderListModels(listModelImports);
-  const openApi = renderOpenApiMetadata(openApiSchemas, openApiOperations, "app", agent.schemaNames, schemaModels);
+  const openApi = renderOpenApiMetadata(openApiSchemas, openApiOperations, "app", tools.schemaNames, schemaModels);
   stageWrite(`${generatedDir}/deps.ts`, renderTargetDeps());
   stageWrite(`${generatedDir}/bindings.ts`, renderTargetBindings());
   stageWrite(`${generatedDir}/httpRequestModels.ts`, requestModels);
   stageWrite(`${generatedDir}/httpListModels.ts`, listModels);
   stageWrite(`${generatedDir}/openapi.ts`, openApi);
-  stageWrite(`${generatedDir}/agentCatalog.ts`, agent.output);
+  // Generated before 0.99.0, when agents were classes; nothing imports it now.
+  stageRemove(`${generatedDir}/agentCatalog.ts`);
   stageWrite(`${generatedDir}/runtime.ts`, renderGeneratedRuntime(name));
   if (production) stageWrite(`${generatedDir}/fingerprint.ts`, renderSourceFingerprint());
-  // The framework's own empty agent catalog (a fixture of agent.metadata.test)
-  // is refreshed only when the framework source is part of this project.
-  if (production) {
-    if (FRAMEWORK_SOURCE !== null) {
-      stageWrite(CORE_AGENT_CATALOG_FILE, generateAgentMetadataCatalog([], CORE_AGENT_GENERATED_DIR).output);
-    }
-  } else {
+  if (!production) {
     stageWrite(`${generatedDir}/bootstrap.ts`, 'import { registerBazisGeneratedRuntime } from "./runtime";\n\nawait registerBazisGeneratedRuntime();\n');
   }
   for (const warning of warnings) console.warn(`[di:generate] WARNING: ${warning}`);
-  console.log(`[di:generate] target=${name} sources=${sourceEntries.length} deps=${classDeps.size} controllers=${Object.keys(httpBindings).length} requestModels=${requestModelImports.length} listModels=${listModelImports.length} agents=${agent.agentCount} prepassMs=${prepassMs.toFixed(1)} analysisMs=${analysisMs.toFixed(1)} totalMs=${(performance.now() - startedAt).toFixed(1)}`);
+  console.log(`[di:generate] target=${name} sources=${sourceEntries.length} deps=${classDeps.size} controllers=${Object.keys(httpBindings).length} requestModels=${requestModelImports.length} listModels=${listModelImports.length} tools=${tools.toolCount} prepassMs=${prepassMs.toFixed(1)} analysisMs=${analysisMs.toFixed(1)} totalMs=${(performance.now() - startedAt).toFixed(1)}`);
   return {
     analysisMs,
     renderMs: performance.now() - renderStartedAt,
     eligible: sourceEntries.length,
-    candidates: classDeps.size + Object.keys(httpBindings).length + requestModelImports.length + listModelImports.length + agent.agentCount,
+    candidates: classDeps.size + Object.keys(httpBindings).length + requestModelImports.length + listModelImports.length + tools.toolCount,
   };
 }
 
-function classifyAgentWarnings(agentWarnings: readonly string[]): void {
-  for (let index = 0; index < agentWarnings.length; index += 1) {
-    const warning = agentWarnings[index] as string;
+function classifyToolWarnings(toolWarnings: readonly string[]): void {
+  for (let index = 0; index < toolWarnings.length; index += 1) {
+    const warning = toolWarnings[index] as string;
     if (warning.includes("ambiguous") || warning.includes("declared in more than one file")) {
       fatalErrors.push(warning);
     } else {
@@ -561,8 +547,8 @@ function renderGeneratedRuntime(targetId: string): string {
       "}",
       "",
       "async function loadTarget(): Promise<void> {",
-      "  const [deps, bindings, requests, lists, openApi, agentCatalog] = await Promise.all([import(\"./deps\"), import(\"./bindings\"), import(\"./httpRequestModels\"), import(\"./httpListModels\"), import(\"./openapi\"), import(\"./agentCatalog\")]);",
-      `  await registerBazisGeneratedTargetDescriptor({ id: ${JSON.stringify(targetId)}, classDeps: deps.GENERATED_TARGET_CLASS_DEPS, bindings: bindings.GENERATED_TARGET_BINDINGS, providerAttachments: bindings.GENERATED_PROVIDER_ATTACHMENTS, requestModels: requests.GENERATED_REQUEST_MODELS, requestShapes: requests.GENERATED_REQUEST_MODEL_SHAPES, listModels: lists.GENERATED_LIST_MODELS, openApi: openApi.GENERATED_OPENAPI_METADATA, openApiSchemaModels: openApi.GENERATED_OPENAPI_SCHEMA_MODELS, agentMetadata: agentCatalog.GENERATED_AGENT_METADATA });`,
+      "  const [deps, bindings, requests, lists, openApi] = await Promise.all([import(\"./deps\"), import(\"./bindings\"), import(\"./httpRequestModels\"), import(\"./httpListModels\"), import(\"./openapi\")]);",
+      `  await registerBazisGeneratedTargetDescriptor({ id: ${JSON.stringify(targetId)}, classDeps: deps.GENERATED_TARGET_CLASS_DEPS, bindings: bindings.GENERATED_TARGET_BINDINGS, providerAttachments: bindings.GENERATED_PROVIDER_ATTACHMENTS, requestModels: requests.GENERATED_REQUEST_MODELS, requestShapes: requests.GENERATED_REQUEST_MODEL_SHAPES, listModels: lists.GENERATED_LIST_MODELS, openApi: openApi.GENERATED_OPENAPI_METADATA, openApiSchemaModels: openApi.GENERATED_OPENAPI_SCHEMA_MODELS });`,
       "}",
       "",
     ].join("\n");
@@ -582,8 +568,8 @@ function renderGeneratedRuntime(targetId: string): string {
     "  // Test-only owner-private hook: it is inert unless an isolated test installs it before loading this generated module.",
     '  (globalThis as { __bazisGeneratedRuntimeTestHook?: (target: string) => void }).__bazisGeneratedRuntimeTestHook?.("production");',
     '  const { registerBazisGeneratedTargetDescriptor, warnIfGeneratedSourcesChanged } = await import("bazis/core/generatedRuntime");',
-    "  const [deps, bindings, requests, lists, openApi, agentCatalog] = await Promise.all([import(\"./deps\"), import(\"./bindings\"), import(\"./httpRequestModels\"), import(\"./httpListModels\"), import(\"./openapi\"), import(\"./agentCatalog\")]);",
-    `  await registerBazisGeneratedTargetDescriptor({ id: ${JSON.stringify(targetId)}, classDeps: deps.GENERATED_TARGET_CLASS_DEPS, bindings: bindings.GENERATED_TARGET_BINDINGS, providerAttachments: bindings.GENERATED_PROVIDER_ATTACHMENTS, requestModels: requests.GENERATED_REQUEST_MODELS, requestShapes: requests.GENERATED_REQUEST_MODEL_SHAPES, listModels: lists.GENERATED_LIST_MODELS, openApi: openApi.GENERATED_OPENAPI_METADATA, openApiSchemaModels: openApi.GENERATED_OPENAPI_SCHEMA_MODELS, agentMetadata: agentCatalog.GENERATED_AGENT_METADATA });`,
+    "  const [deps, bindings, requests, lists, openApi] = await Promise.all([import(\"./deps\"), import(\"./bindings\"), import(\"./httpRequestModels\"), import(\"./httpListModels\"), import(\"./openapi\")]);",
+    `  await registerBazisGeneratedTargetDescriptor({ id: ${JSON.stringify(targetId)}, classDeps: deps.GENERATED_TARGET_CLASS_DEPS, bindings: bindings.GENERATED_TARGET_BINDINGS, providerAttachments: bindings.GENERATED_PROVIDER_ATTACHMENTS, requestModels: requests.GENERATED_REQUEST_MODELS, requestShapes: requests.GENERATED_REQUEST_MODEL_SHAPES, listModels: lists.GENERATED_LIST_MODELS, openApi: openApi.GENERATED_OPENAPI_METADATA, openApiSchemaModels: openApi.GENERATED_OPENAPI_SCHEMA_MODELS });`,
     "  // Started from sources edited after codegen: say so instead of silently missing routes.",
     '  warnIfGeneratedSourcesChanged(import.meta.dir, (await import("./fingerprint")).GENERATED_SOURCE_FINGERPRINT);',
     "}",
@@ -1348,11 +1334,11 @@ function resolveUiProfileResponseModelImports(): OpenApiSchemaModelImport[] {
       || sourcePathForDeclaration(left.declaration).localeCompare(sourcePathForDeclaration(right.declaration)));
 }
 
-/** Agent DTOs and their referenced classes share the existing nominal OpenAPI registry. */
-function resolveOpenApiSchemaModelImports(agentModels: readonly ts.ClassDeclaration[], agentNames: readonly string[]): OpenApiSchemaModelImport[] {
+/** Tool contracts and their referenced classes share the existing nominal OpenAPI registry. */
+function resolveOpenApiSchemaModelImports(toolModels: readonly ts.ClassDeclaration[], toolNames: readonly string[]): OpenApiSchemaModelImport[] {
   const models = new Map(resolveUiProfileResponseModelImports().map((model) => [model.declaration, model.schemaName]));
   // Empty class contracts still have a real object schema and must survive filtering.
-  for (const declaration of agentModels) {
+  for (const declaration of toolModels) {
     const name = openApiCodegen.schemaNameForDeclaration(declaration.name!.text, declaration);
     openApiSchemas[name] ??= openApiCodegen.schemaFromDeclaration(declaration);
     models.set(declaration, name);
@@ -1363,11 +1349,11 @@ function resolveOpenApiSchemaModelImports(agentModels: readonly ts.ClassDeclarat
     reachable.add(name);
     collectSchemaRefs(openApiSchemas[name], add);
   };
-  for (const name of agentNames) add(name);
+  for (const name of toolNames) add(name);
   for (const [declaration, name] of openApiSchemaModels) {
     if (!reachable.has(name)) continue;
     if (!isNamedExportedTopLevelClass(declaration)) {
-      fatalErrors.push(`BAZIS_AGENT_SCHEMA_MODEL_UNIMPORTABLE: Agent schema ${name} must be a named exported top-level class (${sourcePathForDeclaration(declaration)}).`);
+      fatalErrors.push(`BAZIS_TOOL_SCHEMA_MODEL_UNIMPORTABLE: Tool schema ${name} must be a named exported top-level class (${sourcePathForDeclaration(declaration)}).`);
       continue;
     }
     openApiSchemas[name] ??= openApiCodegen.schemaFromDeclaration(declaration);

package/core/scripts/tool-codegen.ts

@@ -0,0 +1,122 @@
+import ts from "typescript";
+
+export interface ToolCodegenSource {
+  readonly filePath: string;
+  /** Program-owned AST; codegen never reparses application source. */
+  readonly sourceFile?: ts.SourceFile;
+  /** Test fixture input; project generation always supplies sourceFile. */
+  readonly content?: string;
+}
+
+export interface ToolCodegenResult {
+  readonly warnings: readonly string[];
+  readonly toolCount: number;
+  /** `input`/`output` classes of `@Tool` declarations: they get JSON schemas in the OpenAPI registry. */
+  readonly schemaNames: readonly string[];
+  /** Program-owned declarations of those classes, for nominal schema bindings. */
+  readonly schemaModels: readonly ts.ClassDeclaration[];
+}
+
+export interface ToolCodegenOptions {
+  /** Use the same naming policy as the project's OpenAPI analyzer. */
+  readonly schemaNameForDeclaration?: (name: string, declaration: ts.ClassDeclaration) => string;
+}
+
+/**
+ * Finds `@Tool({ input, output })` classes. Tool metadata itself is read at
+ * runtime from the decorator; codegen only makes sure the contract classes
+ * have generated JSON schemas for the model and for validation.
+ */
+export function collectToolSchemaModels(
+  sources: readonly ToolCodegenSource[],
+  options: ToolCodegenOptions = {},
+): ToolCodegenResult {
+  const warnings: string[] = [];
+  const declarations = new Map<string, ts.ClassDeclaration>();
+  const files = new Map<string, string>();
+  const ambiguous = new Set<string>();
+  const parsed = sources.map((source) =>
+    source.sourceFile ?? ts.createSourceFile(source.filePath, source.content ?? "", ts.ScriptTarget.ESNext, true, ts.ScriptKind.TS));
+
+  for (const source of parsed) {
+    visitClasses(source, (node) => {
+      const name = node.name!.text;
+      const existing = files.get(name);
+      if (existing === undefined) files.set(name, source.fileName);
+      else if (existing !== source.fileName) ambiguous.add(name);
+      declarations.set(name, node);
+    });
+  }
+
+  const contractNames = new Set<string>();
+  let toolCount = 0;
+  for (const source of parsed) {
+    visitClasses(source, (node) => {
+      const call = toolDecoratorCall(node);
+      if (call === undefined) return;
+      const className = node.name!.text;
+      const where = sourceLocation(source, node);
+      if (!isNamedExportedClass(node)) {
+        warnings.push(`@Tool class "${className}" (${where}) is not a named export; codegen can only import named-export classes.`);
+        return;
+      }
+      toolCount += 1;
+      const options = call.arguments[0];
+      if (options === undefined || !ts.isObjectLiteralExpression(options)) return;
+      for (const property of options.properties) {
+        if (!ts.isPropertyAssignment(property)) continue;
+        const key = ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name) ? property.name.text : undefined;
+        if (key !== "input" && key !== "output") continue;
+        if (!ts.isIdentifier(property.initializer)) {
+          warnings.push(`@Tool ${className} (${where}): ${key} must be a class identifier.`);
+          continue;
+        }
+        const contract = property.initializer.text;
+        if (ambiguous.has(contract)) {
+          warnings.push(`@Tool ${className} (${where}): ${key} class "${contract}" is declared in more than one file.`);
+          continue;
+        }
+        contractNames.add(contract);
+      }
+    });
+  }
+
+  const schemaModels = [...contractNames]
+    .map((name) => declarations.get(name))
+    .filter((declaration): declaration is ts.ClassDeclaration => declaration !== undefined);
+  return {
+    warnings: Object.freeze(warnings),
+    toolCount,
+    schemaNames: Object.freeze(schemaModels
+      .map((declaration) => options.schemaNameForDeclaration?.(declaration.name!.text, declaration) ?? declaration.name!.text)
+      .sort((left, right) => left.localeCompare(right))),
+    schemaModels: Object.freeze(schemaModels),
+  };
+}
+
+function visitClasses(source: ts.SourceFile, onClass: (node: ts.ClassDeclaration) => void): void {
+  const visit = (node: ts.Node): void => {
+    if (ts.isClassDeclaration(node) && node.name) onClass(node);
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(source, visit);
+}
+
+function toolDecoratorCall(node: ts.ClassDeclaration): ts.CallExpression | undefined {
+  for (const decorator of ts.getDecorators(node) ?? []) {
+    const expression = decorator.expression;
+    if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression) && expression.expression.text === "Tool") return expression;
+  }
+  return undefined;
+}
+
+function isNamedExportedClass(node: ts.ClassDeclaration): boolean {
+  const modifiers = ts.getModifiers(node) ?? [];
+  return modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    && !modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+}
+
+function sourceLocation(source: ts.SourceFile, node: ts.Node): string {
+  const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+  return `${source.fileName}:${position.line + 1}:${position.character + 1}`;
+}