bazis 0.137.0 → 0.139.0

package/README.md

@@ -71,8 +71,11 @@ npm page shows the source commit and the workflow that built it. The release
 tarball is also attached to each
 [GitHub Release](https://github.com/asus97178/bazis/releases).
 
-`bazis new` creates a project with `src/index.ts`, a root `AppModule`,
-`bazis.config.json`, scripts, a `/health` test and an `.env.example`.
+`bazis new` creates a project with `src/app/App.ts` (the application declared by
+`@App`), `src/index.ts` (`runApp(Application)`, no options), a root `AppModule`,
+`bazis.config.json`, scripts, a `/health` test that starts the declared application
+in the test process and an `.env.example` with `BAZIS_HTTP__HOST` and
+`BAZIS_HTTP__PORT`.
 
 ## CLI
 
@@ -141,19 +144,25 @@ import { dbConfig } from "../config/db.config"; // defineConfig("db", { default:
 @Infra({ db: ormBazisConnect(dbConfig) })
 export class AppInfra {}
 
+// src/app/App.ts
+@App({ modules: [AppModule], infra: AppInfra, http: { health: true } })
+export class Application {}
+
 // src/index.ts
-await runApp(AppModule, { infra: AppInfra, http: { port: 3000, health: true } });
+await registerBazisGeneratedRuntime();
+await runApp(Application);
 ```
 
 A feature module attaches its own `DbContext` and entities with
-`ormBazis: { context, entities }`; its services take that context in their
+`ormBazis: { context }` (the entities of its sets are mapped by themselves); its services take that context in their
 constructors. `bunx bazis g module Task --minimal` generates such a module.
 Configuration values can be overridden from the environment
 (`BAZIS_DB__HOST`, `BAZIS_DB__PASSWORD`, ...). Invalid configuration or a
 missing production secret stops startup with an error that names the key.
 
 A unique index violation in `saveChanges()` rejects with
-`UniqueViolationError` (with `constraint` and `table`); catch it to answer 409.
+`UniqueViolationError` (with `constraint`, `table` and `properties`); uncaught, it
+answers 409 by itself, as other database errors answer 404, 422 or 503.
 Request-body fields declared as `string`, `number` or `boolean` are checked
 against the JSON type automatically (400 on mismatch); other rules come from
 `@Validator`.
@@ -180,11 +189,13 @@ import { CodexError, RU_CODEX_MESSAGES } from "bazis/core/infra";
 import { RU_UI_LABELS } from "bazis/core/app";
 
 CodexError.useMessages(RU_CODEX_MESSAGES); // Codex connector errors
-await runApp(AppModule, {
+@App({
+  modules: [AppModule],
   language: "ru",                          // response texts: validation, 404/405, 401/403, binding errors
   messages: { notFound: "Нет такой страницы" }, // optional: own texts for single keys
-  ui: { labels: RU_UI_LABELS, surfaces: [/* ... */] }, // generated UI texts
-});
+  ui: { labels: RU_UI_LABELS, surfaces: [/* ... */] }, // generated UI texts,
+})
+export class Application {}
 ```
 
 `language` is per application: it is applied when the response is written, so

package/cli/generateProject.ts

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

package/cli/main.ts

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

package/cli/templates/passport.ts

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

package/core/access/catalog/moduleFields.ts

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

package/core/access/testing/index.ts

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

package/core/agent/AgentContextBuilder.ts

@@ -2,6 +2,8 @@ import type { AgentDefinition } from "./AgentRegistry";
 import { AgentRuntimeError } from "./errors";
 import {
   agentMessage,
+  agentToolResult,
+  agentToolResultPart,
   type AgentContentPart,
   type AgentMessage,
   type AgentMessageRole,
@@ -9,10 +11,20 @@ import {
   type JsonValue,
 } from "./semantic";
 
+/** A Tool result longer than this reaches the model cut, unless `maxToolResultChars` says otherwise. */
+export const DEFAULT_MAX_TOOL_RESULT_CHARS = 100_000;
+
 export interface AgentContextLimits {
   readonly maxMessages?: number;
   readonly maxChars?: number;
   readonly maxTokens?: number;
+  /**
+   * The longest Tool output, as JSON text, the model gets in full. A longer
+   * one is sent as `{ truncated: true, totalChars, text }` with its beginning,
+   * so one large result does not fill the model's window; `result.toolResults`
+   * and `result.messages` keep the whole output. 100 000 by default.
+   */
+  readonly maxToolResultChars?: number;
 }
 
 export interface AgentContextBuildInput {
@@ -21,6 +33,12 @@ export interface AgentContextBuildInput {
   readonly messages: readonly AgentMessage[];
   readonly metadata: JsonObject;
   readonly limits?: AgentContextLimits;
+  /**
+   * How many real tokens one estimated token turned out to be for this model:
+   * the runtime measures it from the usage the provider reports. Estimates are
+   * multiplied by it before `maxTokens` is applied. 1 when nothing is known yet.
+   */
+  readonly tokenScale?: number;
 }
 
 export interface AgentContextTraceEntry {
@@ -55,6 +73,8 @@ interface ContextCandidate {
   readonly message: AgentMessage;
   readonly chars: number;
   readonly tokens: number;
+  /** The Tool result was too long and is sent cut. */
+  readonly cut?: true;
 }
 
 function errorMessageOf(error: unknown): string {
@@ -83,7 +103,11 @@ export function normalizeAgentContextLimits(
     return undefined;
   }
 
-  const normalized: { maxMessages?: number; maxChars?: number; maxTokens?: number } = {};
+  const normalized: { maxMessages?: number; maxChars?: number; maxTokens?: number; maxToolResultChars?: number } = {};
+  const maxToolResultChars = optionalPositiveInteger(limits.maxToolResultChars, `${field}.maxToolResultChars`);
+  if (maxToolResultChars !== undefined) {
+    normalized.maxToolResultChars = maxToolResultChars;
+  }
   const maxMessages = optionalPositiveInteger(limits.maxMessages, `${field}.maxMessages`);
   const maxChars = optionalPositiveInteger(limits.maxChars, `${field}.maxChars`);
   const maxTokens = optionalPositiveInteger(limits.maxTokens, `${field}.maxTokens`);
@@ -129,10 +153,48 @@ function cloneMessage(message: AgentMessage, field: string): AgentMessage {
   }
 }
 
+/** The message the model gets instead of a Tool result that is too long; `undefined` when it fits. */
+function cutToolResult(message: AgentMessage, maxChars: number): AgentMessage | undefined {
+  const part = message.content[0];
+  if (message.role !== "tool" || part?.kind !== "tool-result" || part.result.status !== "success") return undefined;
+  const json = JSON.stringify(part.result.output) ?? "";
+  if (json.length <= maxChars) return undefined;
+  const result = agentToolResult({
+    callId: part.result.callId,
+    name: part.result.name,
+    status: "success",
+    output: { truncated: true, totalChars: json.length, text: json.slice(0, maxChars) },
+    durationMs: part.result.durationMs,
+    metadata: part.result.metadata,
+  });
+  return agentMessage("tool", agentToolResultPart(result), {
+    id: message.id, name: message.name, toolCallId: message.toolCallId, createdAtUnixMs: message.createdAtUnixMs, metadata: message.metadata,
+  });
+}
+
+function withoutReasoning(message: AgentMessage): AgentMessage {
+  if (!message.content.some((part) => part.kind === "reasoning")) return message;
+  const content = message.content.filter((part) => part.kind !== "reasoning");
+  if (content.length === 0) return message;
+  return agentMessage(message.role, content, { id: message.id, name: message.name, toolCallId: message.toolCallId, createdAtUnixMs: message.createdAtUnixMs, metadata: message.metadata });
+}
+
 function jsonLength(value: unknown): number {
   return JSON.stringify(value)?.length ?? 0;
 }
 
+/** Tokens of an image whatever its size: providers scale images down to about this much. */
+const IMAGE_TOKENS = 1_200;
+
+function isDataUri(uri: string): boolean {
+  return uri.startsWith("data:");
+}
+
+/** A file in the request costs what its content does; an address alone says nothing about it. */
+function fileTokens(uri: string): number {
+  return isDataUri(uri) ? Math.min(200_000, Math.max(500, Math.ceil(uri.length / 12))) : 2_000;
+}
+
 function contentPartChars(part: AgentContentPart): number {
   switch (part.kind) {
     case "text":
@@ -140,9 +202,12 @@ function contentPartChars(part: AgentContentPart): number {
     case "data":
       return jsonLength(part.value) + (part.name?.length ?? 0);
     case "image":
-      return part.uri.length + (part.mediaType?.length ?? 0) + part.detail.length;
+      // Bytes written into the dialog are not characters of a prompt.
+      return (isDataUri(part.uri) ? IMAGE_TOKENS * 4 : part.uri.length) + (part.mediaType?.length ?? 0) + part.detail.length;
     case "file":
-      return part.uri.length + (part.mediaType?.length ?? 0) + (part.name?.length ?? 0);
+      return (isDataUri(part.uri) ? fileTokens(part.uri) * 4 : part.uri.length) + (part.mediaType?.length ?? 0) + (part.name?.length ?? 0);
+    case "reasoning":
+      return part.text.length + (part.data === undefined ? 0 : jsonLength(part.data));
     case "tool-result":
       return jsonLength(part.result);
     case "tool-call":
@@ -150,9 +215,35 @@ function contentPartChars(part: AgentContentPart): number {
   }
 }
 
+/**
+ * An estimate close to what tokenizers produce, without a tokenizer: Latin
+ * letters and digits are about four characters a token, letters of other
+ * alphabets about two, a CJK character is a token, punctuation is about two
+ * marks a token. The runtime corrects the rest by the usage a provider reports.
+ */
 function textTokenCount(text: string): number {
-  const matches = text.match(/[\p{L}\p{N}_]+|[^\s]/gu);
-  return matches?.length ?? 0;
+  let latin = 0;
+  let letters = 0;
+  let marks = 0;
+  let whole = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    if (code <= 0x20) continue;
+    if (code < 0x80) {
+      if ((code >= 0x30 && code <= 0x39) || (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a) || code === 0x5f) latin += 1;
+      else marks += 1;
+    } else if (code === 0xa0 || (code >= 0x2000 && code <= 0x200b) || code === 0x3000) {
+      continue;
+    } else if ((code >= 0x2e80 && code <= 0x9fff) || (code >= 0xac00 && code <= 0xd7af) || (code >= 0xf900 && code <= 0xfaff)) {
+      whole += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      // The second half of a surrogate pair: its first half was counted.
+      continue;
+    } else {
+      letters += 1;
+    }
+  }
+  return Math.ceil(latin / 4 + letters / 2 + marks / 2 + whole);
 }
 
 function contentPartTokens(part: AgentContentPart): number {
@@ -162,9 +253,12 @@ function contentPartTokens(part: AgentContentPart): number {
     case "data":
       return textTokenCount(JSON.stringify(part.value) ?? "") + (part.name === undefined ? 0 : textTokenCount(part.name));
     case "image":
-      return textTokenCount(JSON.stringify({ uri: part.uri, mediaType: part.mediaType ?? null, detail: part.detail }));
+      return IMAGE_TOKENS;
     case "file":
-      return textTokenCount(JSON.stringify({ uri: part.uri, mediaType: part.mediaType ?? null, name: part.name ?? null }));
+      return fileTokens(part.uri);
+    case "reasoning":
+      // The provider's record of a block is about as long as the reasoning it holds.
+      return Math.max(textTokenCount(part.text), part.data === undefined ? 0 : Math.ceil(jsonLength(part.data) / 4));
     case "tool-result":
       return textTokenCount(JSON.stringify(part.result) ?? "");
     case "tool-call":
@@ -387,13 +481,15 @@ export class DefaultAgentContextBuilder implements AgentContextBuilder {
 
   build(input: AgentContextBuildInput): AgentContext {
     const limits = normalizeAgentContextLimits(input.limits);
-    const candidates = this.candidates(input.agent, input.messages);
+    const tokenScale = input.tokenScale !== undefined && Number.isFinite(input.tokenScale) && input.tokenScale > 0 ? input.tokenScale : 1;
+    const candidates = this.candidates(input.agent, input.messages, limits?.maxToolResultChars ?? DEFAULT_MAX_TOOL_RESULT_CHARS, tokenScale);
     if (candidates.length === 0) {
       throw new AgentRuntimeError("agent context requires at least one message.");
     }
 
     const included = candidates.map(() => true);
-    const reasons = candidates.map(() => undefined as string | undefined);
+    // A result sent cut stays in the context; the trace says why it is shorter.
+    const reasons = candidates.map((candidate) => candidate.cut ? "maxToolResultChars" : undefined as string | undefined);
     const protectedItems = protectedIndexes(candidates);
     const selection = new ContextSelection(candidates, included, reasons, protectedItems);
     selection.apply("maxMessages", limits?.maxMessages);
@@ -402,12 +498,15 @@ export class DefaultAgentContextBuilder implements AgentContextBuilder {
 
     const messages: AgentMessage[] = [];
     const trace: AgentContextTraceEntry[] = [];
+    // A provider ties reasoning to the dialog it was written in: once older
+    // messages are dropped, the reasoning in the rest no longer matches it.
+    const trimmed = included.includes(false);
     for (let index = 0; index < candidates.length; index += 1) {
       const candidate = candidates[index] as ContextCandidate;
       const isIncluded = included[index] === true;
       trace.push(traceEntry(candidate, isIncluded, reasons[index]));
       if (isIncluded) {
-        messages.push(candidate.message);
+        messages.push(trimmed ? withoutReasoning(candidate.message) : candidate.message);
       }
     }
 
@@ -421,16 +520,17 @@ export class DefaultAgentContextBuilder implements AgentContextBuilder {
         messageCount: messages.length,
         charCount,
         tokenCount,
+        ...(tokenScale === 1 ? {} : { tokenScale }),
         trace: traceToJson(trace),
       }),
     });
   }
 
-  private candidates(agent: AgentDefinition, messages: readonly AgentMessage[]): readonly ContextCandidate[] {
+  private candidates(agent: AgentDefinition, messages: readonly AgentMessage[], maxToolResultChars: number, tokenScale: number): readonly ContextCandidate[] {
     const candidates: ContextCandidate[] = [];
     const prompt = this.promptMessage(agent);
     if (prompt !== undefined) {
-      const tokens = this.estimatedTokens(prompt, "prompt");
+      const tokens = this.estimatedTokens(prompt, "prompt", tokenScale);
       candidates.push(Object.freeze({
         section: "prompt",
         message: prompt,
@@ -440,19 +540,22 @@ export class DefaultAgentContextBuilder implements AgentContextBuilder {
     }
 
     for (let index = 0; index < messages.length; index += 1) {
-      const message = cloneMessage(messages[index] as AgentMessage, `agentContext.messages[${index}]`);
-      const tokens = this.estimatedTokens(message, `conversation[${index}]`);
+      const whole = cloneMessage(messages[index] as AgentMessage, `agentContext.messages[${index}]`);
+      const cut = cutToolResult(whole, maxToolResultChars);
+      const message = cut ?? whole;
+      const tokens = this.estimatedTokens(message, `conversation[${index}]`, tokenScale);
       candidates.push(Object.freeze({
         section: `conversation[${index}]`,
         message,
         chars: messageChars(message),
         tokens,
+        ...(cut === undefined ? {} : { cut: true as const }),
       }));
     }
     return Object.freeze(candidates);
   }
 
-  private estimatedTokens(message: AgentMessage, field: string): number {
+  private estimatedTokens(message: AgentMessage, field: string, tokenScale: number): number {
     let estimate: unknown;
     try { estimate = this.tokenEstimator.estimateMessage(message); } catch (error) {
       throw new AgentRuntimeError(`agentContext token estimator failed for ${field}: ${errorMessageOf(error)}`);
@@ -460,7 +563,7 @@ export class DefaultAgentContextBuilder implements AgentContextBuilder {
     if (!Number.isFinite(estimate) || typeof estimate !== "number" || estimate < 0) {
       throw new AgentRuntimeError(`agentContext token estimator returned an invalid estimate for ${field}.`);
     }
-    return estimate;
+    return tokenScale === 1 ? estimate : Math.ceil(estimate * tokenScale);
   }
 
   /** The definition's instructions are the system prompt, sent as written. */

package/core/agent/AgentRuntime.ts

@@ -14,6 +14,8 @@ import {
 import type { AgentModelProvider } from "./ModelProvider";
 
 export {
+  type AgentCompactionOptions,
+  type AgentModelRetryPolicy,
   type AgentRuntimeInvokeOptions,
   type AgentExecutionDriverOptions,
   type AgentRuntimeOptions,
@@ -58,7 +60,13 @@ export class AgentRuntime {
     this.options = {
       ...options,
       toolExecutorOptions: { schemaValidator: modelValidatorAdapter, ...toolExecutorOptions },
+      // What a model's tokens turned out to cost is learned once for every run.
+      tokenScales: new Map<string, number>(),
     };
+    const summaryProfile = options.compaction === undefined || options.compaction === false ? undefined : options.compaction.modelProfile;
+    if (summaryProfile !== undefined && typeof modelProvider.modelProfiles === "function" && !modelProvider.modelProfiles().includes(summaryProfile)) {
+      throw new AgentSetupError(`AgentRuntime.compaction: model profile "${summaryProfile}" is not configured (configured: ${[...modelProvider.modelProfiles()].sort().join(", ")}).`);
+    }
     // Invalid options and hook setup fail here, at the first resolve, not on the first run.
     new AgentExecutionDriver(services, this.catalog, modelProvider, this.options);
   }

package/core/agent/AgentToolExecutor.ts

@@ -903,6 +903,13 @@ export class AgentToolExecutor {
       return this.finish(call, result, startedAt, metadata, options, audit, tool, options.agentName, undefined, executionState);
     }
 
+    // The provider could not read the arguments the model wrote: the Tool is
+    // not run, and the model gets the reason so it can write the call again.
+    if (call.inputError !== undefined) {
+      const result = this.errorResult(call, "TOOL_ARGUMENTS_INVALID", `Tool "${tool.metadata.name}" arguments are not valid JSON: ${call.inputError}`, metadata, startedAt, { phase: "pre-execute" });
+      return this.finish(call, result, startedAt, metadata, options, audit, tool, visibility.agentName, undefined, executionState);
+    }
+
     const schema = this.schemaSettings(options);
     const schemaGate = this.ensureSchemaValidator(call, tool, schema, metadata, startedAt);
     if (schemaGate) {

package/core/agent/ModelProvider.ts

@@ -22,6 +22,12 @@ export interface AgentModelProvider {
    * the model is called. Without it any profile is passed through.
    */
   modelProfiles?(): readonly string[];
+  /**
+   * The context window of the model behind a profile, in tokens, when infra
+   * knows it (`contextTokens` of the LLM connector). The runtime starts
+   * compacting a long dialog before it reaches the window.
+   */
+  contextTokens?(modelProfile?: string): number | undefined;
 }
 
 export const AGENT_MODEL_PROVIDER = createToken<AgentModelProvider>("AgentModelProvider");

package/core/agent/README.md

@@ -86,11 +86,11 @@ are shared by agents and `ToolRunner`:
 ```ts
 @Module({
   providers: [
-    DI.singleton(DI.valueProvider(AGENT_RUNTIME_OPTIONS, { maxSteps: 6 })),
-    DI.singleton(DI.valueProvider(TOOL_EXECUTION_OPTIONS, {
+    singletonValue(AGENT_RUNTIME_OPTIONS, { maxSteps: 6 }),
+    singletonValue(TOOL_EXECUTION_OPTIONS, {
       approvalPolicy: (request) => request.tool.metadata.sideEffect === "read",
       auditSink: (entry) => auditStore.write(entry),
-    })),
+    }),
   ],
 })
 export class AgentSettingsModule {}
@@ -144,6 +144,38 @@ await this.agents.run(support, {
 conversation message when trimming old history. Provider requests include
 `metadata.agentContext.trace` so context assembly is inspectable.
 
+The runtime recovers before it fails a run. A model request the provider
+cannot serve right now (`AgentModelUnavailableError`: HTTP 429, 5xx, a broken
+connection) is repeated, three attempts by default (`modelRetry`). A text
+answer cut by the output limit is continued (`maxOutputContinuations`, 3), a
+structured answer that is not valid is sent back to the model with the issues
+(`maxOutputRepairs`, 2); the finished dialog keeps one answer. Tool arguments
+the provider could not read (`AgentToolCall.inputError`) give the model
+`TOOL_ARGUMENTS_INVALID` instead of failing the run. Tools of one step that
+change nothing (`none`, `read`) and stand next to each other run together
+(`maxParallelToolCalls`, 8); `write` and `external` run one by one.
+`runTimeoutMs` bounds a whole run (`AGENT_RUN_TIMEOUT`), `result.usage` sums
+the tokens of every model call, and a Tool output longer than
+`contextLimits.maxToolResultChars` (100 000) reaches the model cut.
+
+A long dialog is compacted: its older part is replaced by a summary the
+model writes (a user message with `metadata.runtime: "summary"`), the newest
+messages stay as written and a Tool call is never separated from its results.
+It starts at 80% of the model's window when the LLM connector states
+`contextTokens`, at `compaction.maxTokens`, or after the provider refuses a
+request as too long (`AgentModelContextOverflowError`); `result.compactions`
+says it happened and `compaction: false` turns it off. Token estimates are
+corrected by the usage a provider reports (`metadata.agentContext.tokenScale`).
+
+A model's reasoning is a `reasoning` content part of its assistant message
+(`agentReasoning(text, { data })`): `data` is the provider's own record of the
+block and goes back to it unchanged with the dialog. The runtime drops
+reasoning wherever it rewrites a dialog (compaction, trimming by
+`contextLimits`, dropped drafts). `AgentUsage` also reports `cacheReadTokens`,
+`cacheWriteTokens` and `reasoningTokens`; `inputTokens` is the whole request,
+cached tokens included. Claude is served by `anthropicAdapter` from
+`bazis/core/infra/anthropic`, on the official SDK.
+
 With `llmRouter`, `check` and `run` reject a `modelProfile` the router does
 not serve; a fallback to another profile is logged as `LLM model profile
 failed, using fallback`. A model provider that gives up after its own deadline

package/core/agent/ToolRunner.ts

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