bazis 0.138.0 → 0.139.0

package/core/agent/internal/AgentExecutionState.ts

@@ -9,6 +9,7 @@ import {
   agentData,
   agentMessage,
   agentModelResponse,
+  agentReasoning,
   agentText,
   agentToolCall,
   agentToolCallPart,
@@ -340,13 +341,21 @@ function parseResponse(value: BoundaryJsonValue): AgentExecutionResponse {
 }
 
 function parseUsage(value: BoundaryJsonValue): NonNullable<AgentModelResponse["usage"]> {
-  const record = closed(value, ["inputTokens", "outputTokens", "totalTokens", "latencyMs", "cost", "cacheHit"]);
+  // Checkpoints written before the cache and reasoning counts have six fields.
+  const extended = Object.prototype.hasOwnProperty.call(object(value), "cacheReadTokens");
+  const record: { readonly [Key in "inputTokens" | "outputTokens" | "totalTokens" | "latencyMs" | "cost" | "cacheHit"]: BoundaryJsonValue } & { readonly [Key in "cacheReadTokens" | "cacheWriteTokens" | "reasoningTokens"]?: BoundaryJsonValue } = extended
+    ? closed(value, ["inputTokens", "outputTokens", "totalTokens", "cacheReadTokens", "cacheWriteTokens", "reasoningTokens", "latencyMs", "cost", "cacheHit"])
+    : closed(value, ["inputTokens", "outputTokens", "totalTokens", "latencyMs", "cost", "cacheHit"]);
   if (record.cacheHit !== null && typeof record.cacheHit !== "boolean") throw invalid();
+  const optionalCount = (count: BoundaryJsonValue | undefined): number | undefined => count === undefined || count === null ? undefined : nonNegativeInteger(count);
   const cost = record.cost === null ? undefined : parseCost(record.cost);
   return freezeWithoutUndefined({
     inputTokens: record.inputTokens === null ? undefined : nonNegativeInteger(record.inputTokens),
     outputTokens: record.outputTokens === null ? undefined : nonNegativeInteger(record.outputTokens),
     totalTokens: record.totalTokens === null ? undefined : nonNegativeInteger(record.totalTokens),
+    cacheReadTokens: optionalCount(record.cacheReadTokens),
+    cacheWriteTokens: optionalCount(record.cacheWriteTokens),
+    reasoningTokens: optionalCount(record.reasoningTokens),
     latencyMs: record.latencyMs === null ? undefined : nonNegativeInteger(record.latencyMs),
     cost,
     cacheHit: record.cacheHit === null ? undefined : record.cacheHit,
@@ -385,6 +394,11 @@ function parseContentPart(value: BoundaryJsonValue): AgentContentPart {
     const call = closed(record, ["kind", "call"]);
     return agentToolCallPart(parseToolCall(call.call));
   }
+  if (record.kind === "reasoning") {
+    const reasoning = closed(record, ["kind", "text", "data"]);
+    if (typeof reasoning.text !== "string") throw invalid();
+    return agentReasoning(reasoning.text, { data: reasoning.data === null ? undefined : asJsonObject(reasoning.data) });
+  }
   if (record.kind === "tool-result") {
     const result = closed(record, ["kind", "result"]);
     return agentToolResultPart(parseToolResult(result.result));
@@ -393,11 +407,16 @@ function parseContentPart(value: BoundaryJsonValue): AgentContentPart {
 }
 
 function parseToolCall(value: BoundaryJsonValue): AgentToolCall {
-  const record = closed(value, ["id", "name", "input", "metadata"]);
+  // `inputError` is written only for a call whose arguments could not be read.
+  const withError = Object.prototype.hasOwnProperty.call(object(value), "inputError");
+  const record: { readonly id: BoundaryJsonValue; readonly name: BoundaryJsonValue; readonly input: BoundaryJsonValue; readonly metadata: BoundaryJsonValue; readonly inputError?: BoundaryJsonValue } = withError
+    ? closed(value, ["id", "name", "input", "inputError", "metadata"])
+    : closed(value, ["id", "name", "input", "metadata"]);
   return agentToolCall({
     id: requiredString(record.id),
     name: requiredString(record.name),
     input: asJsonValue(record.input),
+    ...(record.inputError === undefined ? {} : { inputError: requiredString(record.inputError) }),
     metadata: asJsonObject(record.metadata),
   });
 }
@@ -631,6 +650,9 @@ function responseRecord(response: AgentExecutionResponse): Record<string, unknow
       inputTokens: response.usage.inputTokens ?? null,
       outputTokens: response.usage.outputTokens ?? null,
       totalTokens: response.usage.totalTokens ?? null,
+      cacheReadTokens: response.usage.cacheReadTokens ?? null,
+      cacheWriteTokens: response.usage.cacheWriteTokens ?? null,
+      reasoningTokens: response.usage.reasoningTokens ?? null,
       latencyMs: response.usage.latencyMs ?? null,
       cost: response.usage.cost ?? null,
       cacheHit: response.usage.cacheHit ?? null,
@@ -655,12 +677,13 @@ function contentPartRecord(part: AgentContentPart): Record<string, unknown> {
   if (part.kind === "text") return { kind: "text", text: part.text };
   if (part.kind === "data") return { kind: "data", value: part.value, name: part.name ?? null };
   if (part.kind === "tool-call") return { kind: "tool-call", call: toolCallRecord(part.call) };
+  if (part.kind === "reasoning") return { kind: "reasoning", text: part.text, data: part.data ?? null };
   if (part.kind === "tool-result") return { kind: "tool-result", result: toolResultRecord(part.result) };
   throw invalid();
 }
 
 function toolCallRecord(call: AgentToolCall): Record<string, unknown> {
-  return { id: call.id, name: call.name, input: call.input, metadata: call.metadata };
+  return { id: call.id, name: call.name, input: call.input, ...(call.inputError === undefined ? {} : { inputError: call.inputError }), metadata: call.metadata };
 }
 
 function toolResultRecord(result: AgentToolResult): Record<string, unknown> {

package/core/agent/semantic.ts

@@ -15,6 +15,7 @@ export type AgentContentPart =
   | AgentDataPart
   | AgentImagePart
   | AgentFilePart
+  | AgentReasoningPart
   | AgentToolCallPart
   | AgentToolResultPart;
 export type AgentContentInput = string | AgentContentPart | readonly AgentContentPart[];
@@ -44,6 +45,19 @@ export interface AgentFilePart {
   readonly name?: string;
 }
 
+/**
+ * What a model thought before it answered or called a Tool. It stands in the
+ * assistant message it belongs to and goes back to the same provider with the
+ * dialog, unchanged: a provider may refuse reasoning it did not write.
+ */
+export interface AgentReasoningPart {
+  readonly kind: "reasoning";
+  /** What the provider lets an application see of the reasoning; may be empty. */
+  readonly text: string;
+  /** The provider's own record of the block (a signature, encrypted reasoning); opaque to everything else. */
+  readonly data?: JsonObject;
+}
+
 export interface AgentToolResultPart {
   readonly kind: "tool-result";
   readonly result: AgentToolResult;
@@ -77,6 +91,12 @@ export interface AgentToolCall {
   readonly id: string;
   readonly name: string;
   readonly input: JsonValue;
+  /**
+   * Why the arguments the model wrote could not be read (broken or cut-off
+   * JSON). Such a call is never executed: the model gets this text as the
+   * Tool error `TOOL_ARGUMENTS_INVALID` and can write the call again.
+   */
+  readonly inputError?: string;
   readonly metadata: JsonObject;
 }
 
@@ -84,6 +104,8 @@ export interface AgentToolCallOptions {
   readonly id: string;
   readonly name: string;
   readonly input?: unknown;
+  /** Set by a model provider instead of throwing when the arguments are not valid JSON. */
+  readonly inputError?: string;
   readonly metadata?: unknown;
 }
 
@@ -247,9 +269,16 @@ export interface AgentModelRequestOptions {
 export type AgentFinishReason = "stop" | "tool-calls" | "length" | "content-filter" | "error";
 
 export interface AgentUsage {
+  /** The whole request as the provider counted it, tokens read from its prompt cache included. */
   readonly inputTokens?: number;
   readonly outputTokens?: number;
   readonly totalTokens?: number;
+  /** The part of `inputTokens` the provider read from its prompt cache, at a lower price. */
+  readonly cacheReadTokens?: number;
+  /** The part of `inputTokens` the provider wrote to its prompt cache. */
+  readonly cacheWriteTokens?: number;
+  /** The part of `outputTokens` the model spent on reasoning. */
+  readonly reasoningTokens?: number;
   readonly latencyMs?: number;
   readonly cost?: AgentUsageCost;
   readonly cacheHit?: boolean;
@@ -264,6 +293,9 @@ export interface AgentUsageInput {
   readonly inputTokens?: number;
   readonly outputTokens?: number;
   readonly totalTokens?: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheWriteTokens?: number;
+  readonly reasoningTokens?: number;
   readonly latencyMs?: number;
   readonly cost?: {
     readonly amount: number;
@@ -409,6 +441,15 @@ export function agentFile(uri: string, options: { readonly mediaType?: string; r
   });
 }
 
+export function agentReasoning(text: string, options: { readonly data?: unknown } = {}): AgentReasoningPart {
+  if (typeof text !== "string") throw new AgentSemanticError("reasoning.text must be a string.");
+  return freezeWithoutUndefined({
+    kind: "reasoning" as const,
+    text,
+    data: options.data === undefined ? undefined : normalizeJsonObject(options.data, "reasoning.data"),
+  });
+}
+
 export function agentToolResultPart(result: AgentToolResult): AgentToolResultPart {
   return Object.freeze({ kind: "tool-result", result: normalizeToolResult(result) });
 }
@@ -431,6 +472,9 @@ export function agentMessage(role: AgentMessageRole, content: AgentContentInput,
   if (role !== "assistant" && parts.some((part) => part.kind === "tool-call")) {
     throw new AgentSemanticError("tool-call content parts require an assistant message.");
   }
+  if (role !== "assistant" && parts.some((part) => part.kind === "reasoning")) {
+    throw new AgentSemanticError("reasoning content parts require an assistant message.");
+  }
   const resultParts = parts.filter((part) => part.kind === "tool-result");
   if (role === "tool") {
     if (parts.length !== 1 || resultParts.length !== 1) {
@@ -454,11 +498,21 @@ export function agentMessage(role: AgentMessageRole, content: AgentContentInput,
   });
 }
 
+/**
+ * The words of a message: its text parts joined, without reasoning, data and
+ * Tool calls. An empty string for a message that has no text or is absent.
+ */
+export function agentMessageText(message: AgentMessage | undefined): string {
+  if (message === undefined) return "";
+  return message.content.map((part) => part.kind === "text" ? part.text : "").join("");
+}
+
 export function agentToolCall(options: AgentToolCallOptions): AgentToolCall {
-  return Object.freeze({
+  return freezeWithoutUndefined({
     id: requiredName(options.id, "toolCall.id"),
     name: requiredName(options.name, "toolCall.name"),
     input: normalizeJsonValue(options.input ?? {}, "toolCall.input"),
+    inputError: optionalContentText(options.inputError, "toolCall.inputError"),
     metadata: normalizeJsonObject(options.metadata ?? {}, "toolCall.metadata"),
   });
 }
@@ -661,6 +715,8 @@ function normalizeContentPart(part: AgentContentPart, field: string): AgentConte
       return agentImage(part.uri, { mediaType: part.mediaType, detail: part.detail });
     case "file":
       return agentFile(part.uri, { mediaType: part.mediaType, name: part.name });
+    case "reasoning":
+      return agentReasoning(part.text, { data: part.data });
     case "tool-result":
       return agentToolResultPart(part.result);
     case "tool-call":
@@ -715,6 +771,9 @@ function normalizeUsage(usage: AgentUsageInput): AgentUsage {
     inputTokens: optionalNonNegativeInteger(usage.inputTokens, "usage.inputTokens"),
     outputTokens: optionalNonNegativeInteger(usage.outputTokens, "usage.outputTokens"),
     totalTokens: optionalNonNegativeInteger(usage.totalTokens, "usage.totalTokens"),
+    cacheReadTokens: optionalNonNegativeInteger(usage.cacheReadTokens, "usage.cacheReadTokens"),
+    cacheWriteTokens: optionalNonNegativeInteger(usage.cacheWriteTokens, "usage.cacheWriteTokens"),
+    reasoningTokens: optionalNonNegativeInteger(usage.reasoningTokens, "usage.reasoningTokens"),
     latencyMs: optionalNonNegativeInteger(usage.latencyMs, "usage.latencyMs"),
     cost: usage.cost
       ? Object.freeze({

package/core/cache/SPEC.md

@@ -161,7 +161,7 @@ flowchart TB
 
 ```ts
 import { Cacheable, OutputCache, memory } from "@/core/cache";
-import { runApp } from "@/core/app";
+import { App } from "@/core/app";
 
 @App({
   modules: [AppModule],
@@ -196,7 +196,7 @@ class UserService implements IUserStore {
 
 // UsersModule:
 providers: [
-  scoped(IUserStore, UserService, [repositoryFor(User)]),
+  scoped(IUserStore, UserService), // codegen reads the constructor
 ],
 ```
 
@@ -207,7 +207,7 @@ The backend is connected from `@/core/infra/*`; the framework stays backend-agno
 ```ts
 import { memory } from "@/core/cache";
 import { Infra, redisConnect } from "@/core/infra";
-import { runApp } from "@/core/app";
+import { App } from "@/core/app";
 import { redisConfig } from "@/app/config/redis.config";
 import { AppModule } from "@/app/modules/App.module";
 

package/core/di/README.md

@@ -5,7 +5,10 @@ contracts are described in [MODULE.md](MODULE.md).
 
 ## Public API
 
-- `index.ts`: the single public DI entry point.
+- `index.ts`: the public DI entry point for applications (`bazis/core/di`): only the agreed
+  provider forms, tokens, `@Module` and the container.
+- `lowLevel.ts`: `bazis/core/di/lowLevel` (0.138.0): the low-level provider forms (`DI`,
+  factories, dependency lists), for the framework's own modules and packages that extend it.
 - `MODULE.md`: the contracts, boundaries and checks of the DI core.
 
 ## Container core
@@ -33,7 +36,7 @@ contracts are described in [MODULE.md](MODULE.md).
 
 ## Module layer
 
-- `module/DI.ts`: low-level provider constructors.
+- `module/DI.ts`: low-level provider constructors, exported only through `lowLevel.ts`.
 - `module/shortcuts.ts`: the short API (`singleton/scoped/transient`).
 - `module/createContainer.ts`: builds a container from modules.
 - `module/encapsulation.ts`: build-time check of module isolation (`exports`).
@@ -81,7 +84,11 @@ contracts are described in [MODULE.md](MODULE.md).
   (or the class alone), `singletonValue(TOKEN, value)`, `singletonAsyncFactory(TOKEN, [deps], async factory)`
   and `...withEventSubscribers(Class)`. Codegen refuses anything else (`BAZIS_DI_PROVIDER_FORM`).
 - The low-level path (`DI.classProvider(...)`, `DI.factoryProvider(...)`) stays for the kernel's own
-  plumbing and test `overrides`, never in a module's `providers`.
+  plumbing and packages that extend the framework, never in a module's `providers`. Since 0.138.0
+  it is imported from `bazis/core/di/lowLevel`; `bazis/core/di` no longer exports `DI`, the
+  dependency-list argument of `scoped`/`singleton`/`transient`, `singletonFactory`,
+  `singletonFactoryWithResolver` or `singletonAsyncFactoryWithResolver`. Test `overrides` use
+  the agreed forms: `singletonValue(IStore, fake)`, `scoped(IStore, FakeStore)`.
 
 ## Contributing Checklist
 

package/core/infra/anthropic.ts

@@ -0,0 +1,11 @@
+/**
+ * The Claude adapter lives in its own entry: it imports `@anthropic-ai/sdk`,
+ * which only an application that uses Claude installs.
+ */
+export {
+  AnthropicModelProvider,
+  AnthropicProviderError,
+  anthropicAdapter,
+  type AnthropicAdapterOptions,
+  type AnthropicClient,
+} from "./connectors/anthropic";