bazis 0.138.0 → 0.140.0

package/core/infra/connectors/openaiCompatible.ts

@@ -1,5 +1,7 @@
 import {
+  AgentModelContextOverflowError,
   AgentModelTimeoutError,
+  AgentModelUnavailableError,
   agentMessage,
   agentModelResponse,
   agentToolCall,
@@ -22,6 +24,7 @@ import {
   type LlmProviderAdapter,
 } from "./llm";
 import { readOpenAiTextStream } from "./openaiTextStream";
+import { providerToolName, toolNameMapping, type ToolNameMapping } from "./toolNames";
 import { InfraError } from "../InfraConnector";
 import { redactSensitiveText } from "../../../library/redaction";
 
@@ -52,9 +55,14 @@ export class OpenAiCompatibleProviderError extends Error {
 
 type OpenAiChatRole = "system" | "user" | "assistant" | "tool";
 
+type OpenAiContentPart =
+  | { readonly type: "text"; readonly text: string }
+  | { readonly type: "image_url"; readonly image_url: { readonly url: string; readonly detail: "auto" | "low" | "high" } }
+  | { readonly type: "file"; readonly file: { readonly file_data: string; readonly filename: string } };
+
 interface OpenAiChatMessage {
   readonly role: OpenAiChatRole;
-  readonly content?: string | null;
+  readonly content?: string | readonly OpenAiContentPart[] | null;
   readonly tool_call_id?: string;
   readonly tool_calls?: readonly OpenAiToolCall[];
 }
@@ -92,17 +100,14 @@ interface OpenAiChatResponse {
     readonly prompt_tokens?: number;
     readonly completion_tokens?: number;
     readonly total_tokens?: number;
+    readonly prompt_tokens_details?: { readonly cached_tokens?: number } | null;
+    readonly completion_tokens_details?: { readonly reasoning_tokens?: number } | null;
   };
   readonly error?: {
     readonly message?: string;
   };
 }
 
-interface ToolNameMapping {
-  readonly providerToBazis: ReadonlyMap<string, string>;
-  readonly bazisToProvider: ReadonlyMap<string, string>;
-}
-
 function stripTrailingSlash(value: string): string {
   return value.replace(/\/+$/, "");
 }
@@ -126,47 +131,6 @@ function cancelBodyBestEffort(body: ReadableStream<Uint8Array> | null | undefine
   void body.cancel(reason).catch(() => undefined);
 }
 
-function shortHash(value: string): string {
-  let hash = 2166136261;
-  for (let index = 0; index < value.length; index += 1) {
-    hash ^= value.charCodeAt(index);
-    hash = Math.imul(hash, 16777619);
-  }
-  return (hash >>> 0).toString(36);
-}
-
-function providerToolName(name: string, used: Set<string>): string {
-  const replaced = name.replace(/[^a-zA-Z0-9_-]/g, "_");
-  const prefixed = /^[a-zA-Z_]/.test(replaced) ? replaced : `tool_${replaced}`;
-  const trimmed = prefixed.length <= 64 ? prefixed : `${prefixed.slice(0, 55)}_${shortHash(name)}`;
-  if (!used.has(trimmed)) {
-    used.add(trimmed);
-    return trimmed;
-  }
-
-  const suffix = shortHash(name);
-  const base = trimmed.slice(0, Math.max(1, 63 - suffix.length));
-  const unique = `${base}_${suffix}`;
-  if (used.has(unique)) {
-    throw new OpenAiCompatibleProviderError(`Tool name "${name}" collides after OpenAI-compatible normalization.`);
-  }
-  used.add(unique);
-  return unique;
-}
-
-function toolNameMapping(tools: readonly AgentToolContract[]): ToolNameMapping {
-  const providerToBazis = new Map<string, string>();
-  const bazisToProvider = new Map<string, string>();
-  const used = new Set<string>();
-  for (let index = 0; index < tools.length; index += 1) {
-    const tool = tools[index] as AgentToolContract;
-    const providerName = providerToolName(tool.name, used);
-    providerToBazis.set(providerName, tool.name);
-    bazisToProvider.set(tool.name, providerName);
-  }
-  return Object.freeze({ providerToBazis, bazisToProvider });
-}
-
 function schemaForTool(tool: AgentToolContract): JsonObject {
   if (tool.input?.kind === "json-schema") {
     return tool.input.schema;
@@ -227,6 +191,28 @@ function contentText(parts: readonly AgentContentPart[]): string {
   return lines.join("\n");
 }
 
+/**
+ * What a user sends as the provider expects it: one string for words, parts
+ * when there is an image or a file whose bytes are in the dialog. A file given
+ * by address is named in the text: Chat Completions takes file content only.
+ */
+function userContent(parts: readonly AgentContentPart[]): string | readonly OpenAiContentPart[] {
+  const inline = (part: AgentContentPart): boolean => part.kind === "image" || (part.kind === "file" && part.uri.startsWith("data:"));
+  if (!parts.some(inline)) return contentText(parts);
+  const out: OpenAiContentPart[] = [];
+  for (const part of parts) {
+    if (part.kind === "image") {
+      out.push({ type: "image_url", image_url: { url: part.uri, detail: part.detail } });
+    } else if (part.kind === "file" && part.uri.startsWith("data:")) {
+      out.push({ type: "file", file: { file_data: part.uri, filename: part.name ?? "file" } });
+    } else {
+      const text = contentText([part]);
+      if (text.length > 0) out.push({ type: "text", text });
+    }
+  }
+  return Object.freeze(out);
+}
+
 function toOpenAiRole(role: AgentMessage["role"]): OpenAiChatRole {
   if (role === "developer") {
     return "system";
@@ -266,17 +252,75 @@ function finishReasonOf(reason: string | undefined, hasToolCalls: boolean): Agen
   return "error";
 }
 
-function parseToolArguments(raw: string, callId: string): JsonValue {
+/** Arguments the model wrote: the value, or why they could not be read. */
+function parseToolArguments(raw: string, callId: string): { readonly input: JsonValue } | { readonly inputError: string } {
   if (raw.trim().length === 0) {
-    return Object.freeze({});
+    return { input: Object.freeze({}) };
   }
   try {
-    return normalizeJsonValue(JSON.parse(raw), `toolCall.${callId}.arguments`);
+    return { input: normalizeJsonValue(JSON.parse(raw), `toolCall.${callId}.arguments`) };
   } catch (error) {
-    throw new OpenAiCompatibleProviderError(`OpenAI-compatible tool arguments for "${callId}" are invalid JSON: ${errorMessageOf(error)}`);
+    // Not a provider failure: the model gets the reason as a Tool error and writes the call again.
+    return { inputError: errorMessageOf(error) };
+  }
+}
+
+/** HTTP statuses that mean "not now": the runtime repeats the request. */
+function isUnavailableStatus(status: number): boolean {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+
+const MAX_ERROR_BODY_BYTES = 64 * 1024;
+
+/**
+ * Whether an error body says the request is longer than the model's window.
+ * The body is only classified: its text may repeat the prompt and never
+ * leaves this function.
+ */
+async function saysContextOverflow(response: Response, signal: AbortSignal): Promise<boolean> {
+  if (response.body === null) return false;
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  const cancel = (): void => { void reader.cancel().catch(() => undefined); };
+  signal.addEventListener("abort", cancel, { once: true });
+  try {
+    while (total < MAX_ERROR_BODY_BYTES) {
+      const item = await reader.read();
+      if (item.done) break;
+      chunks.push(item.value);
+      total += item.value.byteLength;
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+    const text = new TextDecoder().decode(bytes.subarray(0, MAX_ERROR_BODY_BYTES));
+    let code: unknown;
+    let message: unknown = text;
+    try {
+      const error = (JSON.parse(text) as { error?: { code?: unknown; message?: unknown } }).error;
+      code = error?.code;
+      if (typeof error?.message === "string") message = error.message;
+    } catch { /* Not JSON: the plain text is looked at. */ }
+    return code === "context_length_exceeded"
+      || (typeof message === "string" && /context[ _-]?length|context window|maximum context|prompt is too long|too many (input )?tokens|input is too long/i.test(message));
+  } catch {
+    return false;
+  } finally {
+    signal.removeEventListener("abort", cancel);
+    cancel();
   }
 }
 
+/** `Retry-After`: seconds or an HTTP date. */
+function retryAfterMsOf(header: string | null): number | undefined {
+  if (header === null) return undefined;
+  const text = header.trim();
+  if (/^\d+(\.\d+)?$/.test(text)) return Math.round(Number(text) * 1000);
+  const date = Date.parse(text);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+
 function normalizeToolCalls(
   calls: readonly OpenAiToolCall[] | undefined,
   mapping: ToolNameMapping,
@@ -298,7 +342,7 @@ function normalizeToolCalls(
     out.push(agentToolCall({
       id: call.id,
       name,
-      input: parseToolArguments(call.function?.arguments ?? "", call.id),
+      ...parseToolArguments(call.function?.arguments ?? "", call.id),
     }));
   }
   return Object.freeze(out);
@@ -312,6 +356,8 @@ function buildUsage(usage: OpenAiChatResponse["usage"]): AgentModelResponse["usa
     ...(usage.prompt_tokens !== undefined ? { inputTokens: usage.prompt_tokens } : {}),
     ...(usage.completion_tokens !== undefined ? { outputTokens: usage.completion_tokens } : {}),
     ...(usage.total_tokens !== undefined ? { totalTokens: usage.total_tokens } : {}),
+    ...(typeof usage.prompt_tokens_details?.cached_tokens === "number" ? { cacheReadTokens: usage.prompt_tokens_details.cached_tokens } : {}),
+    ...(typeof usage.completion_tokens_details?.reasoning_tokens === "number" ? { reasoningTokens: usage.completion_tokens_details.reasoning_tokens } : {}),
   });
 }
 
@@ -401,6 +447,11 @@ export class OpenAiCompatibleModelProvider implements AgentModelProvider {
     }
   }
 
+  /** The context window the application stated for this model (`contextTokens`). */
+  public contextTokens(): number | undefined {
+    return this.connection.contextTokens;
+  }
+
   /** Base URL of the provider, for diagnostics. */
   public get address(): string {
     return this.baseUrl;
@@ -490,9 +541,10 @@ export class OpenAiCompatibleModelProvider implements AgentModelProvider {
         continue;
       }
 
+      const role = toOpenAiRole(message.role);
       out.push(Object.freeze({
-        role: toOpenAiRole(message.role),
-        content: contentText(message.content),
+        role,
+        content: role === "user" ? userContent(message.content) : contentText(message.content),
       }));
     }
     return Object.freeze(out);
@@ -507,19 +559,32 @@ export class OpenAiCompatibleModelProvider implements AgentModelProvider {
       : setTimeout(() => abort.abort(new AgentModelTimeoutError("OpenAI-compatible request timed out.")), this.requestTimeoutMs);
     try {
       abort.signal.throwIfAborted();
-      const response = await this.fetcher(`${this.baseUrl}${path}`, {
-        method,
-        headers: this.headers,
-        body: body === undefined ? undefined : JSON.stringify(body),
-        signal: abort.signal,
-      });
+      let response: Response;
+      try {
+        response = await this.fetcher(`${this.baseUrl}${path}`, {
+          method,
+          headers: this.headers,
+          body: body === undefined ? undefined : JSON.stringify(body),
+          signal: abort.signal,
+        });
+      } catch (error) {
+        // A cancelled or timed-out request keeps its own reason; a broken connection can be repeated.
+        if (abort.signal.aborted) throw error;
+        throw new AgentModelUnavailableError(`OpenAI-compatible ${method} ${path} could not reach the provider: ${errorMessageOf(error)}`);
+      }
       if (!response.ok) {
+        const message = `OpenAI-compatible ${method} ${path} failed with HTTP ${response.status}.`;
+        // A refusal of a chat request may mean "too long": the runtime answers that by compacting the dialog.
+        if (method === "POST" && (response.status === 400 || response.status === 413 || response.status === 422) && await saysContextOverflow(response, abort.signal)) {
+          throw new AgentModelContextOverflowError(`${message} The request does not fit the model's context window.`);
+        }
         // Cancel the provider-controlled body without exposing it: error bodies
         // may echo prompts, credentials or tenant data.
         cancelBodyBestEffort(response.body);
-        throw new OpenAiCompatibleProviderError(
-          `OpenAI-compatible ${method} ${path} failed with HTTP ${response.status}.`,
-        );
+        if (isUnavailableStatus(response.status)) {
+          throw new AgentModelUnavailableError(message, { retryAfterMs: retryAfterMsOf(response.headers.get("retry-after")) });
+        }
+        throw new OpenAiCompatibleProviderError(message);
       }
       if (response.status === 204) {
         return {};

package/core/infra/connectors/openaiTextStream.ts

@@ -121,10 +121,13 @@ export async function readOpenAiTextStream(
     // EOF alone is not success: both a terminal choice and [DONE] are required.
     if (!done) fail("was interrupted before completion");
     const toolCalls = [...calls.entries()].sort(([a], [b]) => a - b).map(([index, call], position) => {
-      if (index !== position || !call.id || !call.function.name || !call.function.arguments) fail("contains an incomplete tool call");
+      if (index !== position || !call.id || !call.function.name) fail("contains an incomplete tool call");
       return call;
     });
-    if ((toolCalls.length > 0) !== (finish === "tool_calls") || new Set(toolCalls.map(call => call.id)).size !== toolCalls.length) fail("contains inconsistent tool calls");
+    // "length" with tool calls: the output limit cut the arguments. The calls are
+    // kept, so the model hears that the arguments are broken and writes them again.
+    const cut = finish === "length" && toolCalls.length > 0;
+    if ((!cut && (toolCalls.length > 0) !== (finish === "tool_calls")) || new Set(toolCalls.map(call => call.id)).size !== toolCalls.length) fail("contains inconsistent tool calls");
     return { choices: [{ finish_reason: finish, message: { content: text.join(""), ...(toolCalls.length ? { tool_calls: toolCalls } : {}) } }], usage };
   } finally {
     signal.removeEventListener("abort", cancel);

package/core/infra/connectors/toolNames.ts

@@ -0,0 +1,49 @@
+import type { AgentToolContract } from "../../agent";
+
+export interface ToolNameMapping {
+  readonly providerToBazis: ReadonlyMap<string, string>;
+  readonly bazisToProvider: ReadonlyMap<string, string>;
+}
+
+function shortHash(value: string): string {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+/** A Tool name as providers accept it: Latin letters, digits, `_` and `-`, at most 64 characters, unique in a request. */
+export function providerToolName(name: string, used: Set<string>): string {
+  const replaced = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const prefixed = /^[a-zA-Z_]/.test(replaced) ? replaced : `tool_${replaced}`;
+  const trimmed = prefixed.length <= 64 ? prefixed : `${prefixed.slice(0, 55)}_${shortHash(name)}`;
+  if (!used.has(trimmed)) {
+    used.add(trimmed);
+    return trimmed;
+  }
+
+  const suffix = shortHash(name);
+  const base = trimmed.slice(0, Math.max(1, 63 - suffix.length));
+  const unique = `${base}_${suffix}`;
+  if (used.has(unique)) {
+    throw new Error(`Tool name "${name}" collides with another Tool after its name is made acceptable to the model provider.`);
+  }
+  used.add(unique);
+  return unique;
+}
+
+/** Names of a request's Tools as the provider sees them, and the way back. */
+export function toolNameMapping(tools: readonly AgentToolContract[]): ToolNameMapping {
+  const providerToBazis = new Map<string, string>();
+  const bazisToProvider = new Map<string, string>();
+  const used = new Set<string>();
+  for (let index = 0; index < tools.length; index += 1) {
+    const tool = tools[index] as AgentToolContract;
+    const providerName = providerToolName(tool.name, used);
+    providerToBazis.set(providerName, tool.name);
+    bazisToProvider.set(tool.name, providerName);
+  }
+  return Object.freeze({ providerToBazis, bazisToProvider });
+}

package/core/scripts/di-generate.ts

@@ -191,6 +191,8 @@ interface ConstructorDependencies {
 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 }>();
+/** The prefixes of `permissionSources` of the target's modules: any key under one is a permission key. */
+let permissionSourcePrefixes = new Set<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.
@@ -507,7 +509,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(); permissionDeclarations = new Map();
+  classDeps = new Map(); inferredDiClasses = new Set(); explicitlyBoundDiClasses = new Set(); permissionDeclarations = new Map(); permissionSourcePrefixes = new Set();
   tokenDescriptions = new Set(); configPrefixesByType = new Map(); knownClassNames = new Set(); warnings = []; fatalErrors = [];
   httpBindings = {}; httpControllerFiles = {}; openApiSchemas = {}; openApiOperations = {};
   grpcBindings = new Map();
@@ -557,7 +559,7 @@ 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());
+  if (permissionDeclarations.size > 0 || permissionSourcePrefixes.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`);
@@ -715,9 +717,17 @@ function renderGeneratedRuntime(targetId: string): string {
 /** 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";'];
+  const lines = ["// This file is auto-generated by `bazis codegen`.", "// Do not edit manually."];
+  // Without an import or an export the file would be a script, and `declare module` would replace the module instead of adding to it.
+  lines.push(entries.length > 0 ? 'import type { PermissionsOf } from "bazis/core/access";' : "export {};");
   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(", ")} {}`, "}", "");
+  lines.push("", 'declare module "bazis/core/access" {');
+  if (entries.length > 0) lines.push(`  interface BazisPermissions extends ${entries.map((_, index) => `PermissionsOf<typeof Permissions_${index}>`).join(", ")} {}`);
+  // The prefixes of `permissionSources`: `${prefix}.${string}` is a permission key too (ACCESS-001 §3.1).
+  if (permissionSourcePrefixes.size > 0) {
+    lines.push("  interface BazisPermissionSources {", ...[...permissionSourcePrefixes].sort().map((prefix) => `    ${JSON.stringify(prefix)}: true;`), "  }");
+  }
+  lines.push("}", "");
   return lines.join("\n");
 }
 
@@ -1036,6 +1046,9 @@ function collectDiClassRegistrations(source: ts.SourceFile): void {
     // `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);
+    // `permissionSources: { data: DataPermissionSource }`: the field registers the classes too.
+    const permissionSources = objectFor(properties.get("permissionSources"));
+    if (permissionSources) for (const entry of propertiesOf(permissionSources).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");
@@ -1177,6 +1190,22 @@ function collectProviderFormErrors(source: ts.SourceFile): void {
     }
     permissionDeclarations.set(`${file}\0${exported.name}`, { name: exported.name, file });
   };
+  /**
+   * `permissionSources: { data: DataPermissionSource }`: the prefixes go to the
+   * generated `permissions.ts`, which makes every key under them a permission
+   * key for `can` and `access.filter`. A framework pack names its own in its sources.
+   */
+  const collectPermissionSources = (module: string, initializer: ts.Expression): void => {
+    const file = normalizeProjectPath(initializer.getSourceFile().fileName);
+    if (file.includes("/node_modules/") || isFrameworkPackPath(file)) return;
+    const object = resolved(initializer, ts.isObjectLiteralExpression);
+    const named = object?.properties.every((property) => ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)));
+    if (!object || named !== true) {
+      fatalErrors.push(`BAZIS_ACCESS_SOURCES_FORM: ${sourceLocation(initializer)}: permissionSources of ${module}: "${text(initializer)}" — write an object "prefix: Class" in the module, so that the keys under the prefixes become the type of can(...).`);
+      return;
+    }
+    for (const property of object.properties) permissionSourcePrefixes.add((property.name as ts.Identifier | ts.StringLiteralLike).text);
+  };
   const checkModule = (module: string, argument: ts.Expression | undefined): void => {
     const object = argument && resolved(argument, ts.isObjectLiteralExpression);
     if (!object) return;
@@ -1184,6 +1213,7 @@ function collectProviderFormErrors(source: ts.SourceFile): void {
       if (!ts.isPropertyAssignment(property)) continue;
       const field = property.name.getText().replace(/["']/g, "");
       if (field === "permissions") collectPermissions(module, property.initializer);
+      if (field === "permissionSources") collectPermissionSources(module, property.initializer);
       if (field !== "providers" && !CLASS_LISTS.includes(field)) continue;
       const list = resolved(property.initializer, ts.isArrayLiteralExpression);
       if (!list) {

package/core/websocket/DESIGN.md

@@ -22,7 +22,7 @@ export class ChatGateway {
 }
 ```
 
-Declare it in its module, like a controller; `runApp` serves it on the HTTP listener:
+Declare it in its module, like a controller; the application started by `runApp(Application)` serves it on the HTTP listener:
 
 ```ts
 import { Module, singleton } from "@/core/di";
@@ -34,7 +34,7 @@ export class ChatModule {}
 export class Application {}
 ```
 
-Without `runApp`, `websocketModule({ imports: [ChatModule], ... })` next to
+Without `@App`, `websocketModule({ imports: [ChatModule], ... })` next to
 `httpModule` does the same. Services send with `WebSocketService`:
 `this.ws.to("user:ann").emit("order-paid", { id })`.
 

package/index.ts

@@ -84,6 +84,8 @@ export {
   AgentRuntimeError,
   AgentSemanticError,
   AgentModelTimeoutError,
+  AgentModelUnavailableError,
+  AgentModelContextOverflowError,
   AgentToolExecutionError,
   ToolError,
   ApproximateAgentContextTokenEstimator,
@@ -94,6 +96,7 @@ export {
   agentInvocation,
   agentJsonSchema,
   agentMessage,
+  agentMessageText,
   agentModelCapabilities,
   agentModelRequest,
   agentModelResponse,
@@ -117,6 +120,8 @@ export {
   type AgentOutputContract,
   type AgentRuntimeInvokeOptions,
   type AgentRuntimeOptions,
+  type AgentModelRetryPolicy,
+  type AgentCompactionOptions,
   type AgentRuntimeResult,
   type AgentRuntimeStatus,
   type AgentRuntimeToolExecutionOptions,

package/library/orm/Repository/README.md

@@ -284,14 +284,16 @@ class MyModule {}
 
 ### Explicit dependencies in a provider
 
+An application never lists dependencies: codegen reads the constructor
+(`scoped(UserService)` is enough). A package that extends the framework and builds
+providers by hand takes the low-level forms from `bazis/core/di/lowLevel` (0.138.0):
+
 ```ts
-import { scoped, DI } from "@/core/di";
-import { repositoryFor } from "@/core/orm";
+import { DI } from "bazis/core/di/lowLevel";
+import { repositoryFor } from "bazis/core/orm";
 
 providers: [
-  scoped(
-    DI.classProvider(UserService, UserService, [repositoryFor(User)] as const),
-  ),
+  DI.scoped(DI.classProvider(UserService, UserService, [repositoryFor(User)] as const)),
 ],
 ```
 
@@ -385,12 +387,11 @@ export class UserService {
 
 ```ts
 import { Module, scoped } from "@/core/di";
-import { repositoryFor } from "@/core/orm";
 
 @Module({
   imports: [DataModule],
   providers: [
-    scoped(UserService, UserService, [repositoryFor(User)] as const),
+    scoped(UserService), // codegen reads `IRepository<User>` from the constructor
   ],
   exports: [UserService],
 })
@@ -517,7 +518,9 @@ books.add(book);
 `di:generate` wires a constructor parameter typed `IRepository<User>` automatically. Explicit deps are needed only when the class is registered without codegen (for example in a hand-built test container):
 
 ```ts
-scoped(UserService, UserService, [repositoryFor(User)] as const)
+import { DI } from "bazis/core/di/lowLevel"; // since 0.138.0; not in bazis/core/di
+
+DI.scoped(DI.classProvider(UserService, UserService, [repositoryFor(User)] as const))
 ```
 
 ### 4. `ensureCreated` in tests without starting the application
@@ -596,7 +599,7 @@ A mock usually needs only the methods the service calls.
 For **controller** tests it is enough to replace the store contract the controller depends on (here a hypothetical `IUserStore`):
 
 ```ts
-import { Module, createContainer, DI } from "bazis/core/di";
+import { Module, createContainer, singletonValue } from "bazis/core/di";
 import { InMemoryUserStore } from "./InMemoryUserStore";
 import { IUserStore } from "./IUserStore";
 import { UsersController } from "./UsersController";
@@ -604,7 +607,7 @@ import { UsersController } from "./UsersController";
 @Module({
   controllers: [UsersController],
   providers: [
-    DI.scoped(DI.valueProvider(IUserStore, new InMemoryUserStore())),
+    singletonValue(IUserStore, new InMemoryUserStore()),
   ],
 })
 class TestUsersModule {}
@@ -652,7 +655,7 @@ expect(await service.list(10)).toHaveLength(1);
 1. **Do not mock `query()`** if you test SQL/filters: use PostgreSQL qualification.
 2. **Mock `saveChanges()`** to check that the service saves data at all.
 3. **One scope per test**: `scope.dispose()` in `afterEach`, otherwise scoped services leak.
-4. In hand-built DI test containers (without codegen) with `validateOnBuild: true`, give Repository deps explicitly: `[repositoryFor(User)]`.
+4. In hand-built DI test containers (without codegen) with `validateOnBuild: true`, give Repository deps explicitly through `DI.classProvider(…, [repositoryFor(User)])` from `bazis/core/di/lowLevel`. With codegen, prefer `createTestContainer(Application, { overrides })` from `bazis/core/testing`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.138.0",
+  "version": "0.140.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",
@@ -42,6 +42,7 @@
     "./core/http-client": "./core/http-client/index.ts",
     "./core/http/OpenApi/generatedOpenApiRegistry": "./core/http/OpenApi/generatedOpenApiRegistry.ts",
     "./core/infra": "./core/infra/index.ts",
+    "./core/infra/anthropic": "./core/infra/anthropic.ts",
     "./core/kernel": "./core/kernel/index.ts",
     "./core/orm": "./core/orm/index.ts",
     "./core/testing": "./core/testing/index.ts",
@@ -81,7 +82,8 @@
   },
   "peerDependencies": {
     "typescript": "^5.9.3 || ^6.0.0 || ^7.0.0",
-    "@typescript/typescript6": "^6.0.0"
+    "@typescript/typescript6": "^6.0.0",
+    "@anthropic-ai/sdk": "^1.8.0"
   },
   "publishConfig": {
     "access": "public",
@@ -90,6 +92,9 @@
   "peerDependenciesMeta": {
     "@typescript/typescript6": {
       "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
     }
   }
 }