bazis 0.99.3 → 0.99.5

package/core/agent/AgentRuntime.ts

@@ -1,5 +1,6 @@
 import { createToken, type ServiceProvider } from "../di";
 import { modelValidatorAdapter } from "../../library/validation";
+import { AgentSetupError } from "./errors";
 import type { AgentDataDefinition } from "./AgentDataDefinition";
 import { AgentRegistry, type ToolDefinition } from "./AgentRegistry";
 import {
@@ -62,6 +63,15 @@ export class AgentRuntime {
     return this.catalog.listTools();
   }
 
+  /** A profile the model provider does not serve fails before the model is called. */
+  private assertModelProfile(agentName: string, profile: string | undefined): void {
+    if (profile === undefined || typeof this.modelProvider.modelProfiles !== "function") return;
+    const configured = this.modelProvider.modelProfiles();
+    if (!configured.includes(profile)) {
+      throw new AgentSetupError(`Agent "${agentName}": model profile "${profile}" is not configured (configured: ${[...configured].sort().join(", ")}).`);
+    }
+  }
+
   /**
    * Checks a definition the way `run` does, without calling the model: an
    * invalid field or a tool name not registered in `@Module.tools` throws
@@ -69,6 +79,7 @@ export class AgentRuntime {
    */
   check(definition: AgentDataDefinition): void {
     AgentRegistry.fromDefinition(definition, this.catalog.listTools());
+    this.assertModelProfile(definition.name, definition.modelProfile);
   }
 
   /**
@@ -78,6 +89,7 @@ export class AgentRuntime {
    */
   async run(definition: AgentDataDefinition, options: AgentRuntimeInvokeOptions = {}): Promise<AgentRuntimeResult> {
     const registry = AgentRegistry.fromDefinition(definition, this.catalog.listTools());
+    this.assertModelProfile(definition.name, options.modelProfile ?? definition.modelProfile);
     const driver = new AgentExecutionDriver(this.services, registry, this.modelProvider, this.options);
     return driver.invoke(definition.name, options);
   }

package/core/agent/AgentToolExecutor.ts

@@ -811,7 +811,8 @@ export class AgentToolExecutor {
     });
     // Observer evidence is deliberately best effort and uses an independent
     // bounded write: it cannot alter the already-terminal Tool result.
-    await awaitHook(Promise.resolve().then(() => auditSinkFunction(this.auditSink!)(entry)), undefined, timeoutMs);
+    const recorded = await awaitHook(Promise.resolve().then(() => auditSinkFunction(this.auditSink!)(entry)), undefined, timeoutMs);
+    if (recorded.kind !== "value") this.logAuditFailure("observer", settlement.toolName, settlement.callId, settlement.agentName, "best-effort", recorded);
   }
 
   private async executePipeline(
@@ -1195,8 +1196,12 @@ export class AgentToolExecutor {
     if (!this.auditSink) return true;
     try {
       const outcome = await awaitHook(Promise.resolve().then(() => auditSinkFunction(this.auditSink!)({ kind: "agent-tool", phase, callId: call.id, toolName: tool.metadata.name, input: redactSensitive(normalizeJsonValue(call.input, "hook.audit.input"), this.hookRedaction), tool: { name: tool.metadata.name, sideEffect: tool.metadata.sideEffect, approval: tool.metadata.approval, tags: tool.metadata.tags ?? [] }, startedAtUnixMs: startedAt, finishedAtUnixMs: Date.now(), durationMs: Date.now() - startedAt, metadata: redactSensitive(metadata, this.hookRedaction) as JsonObject, hook })), signal, timeoutMs);
+      if (outcome.kind !== "value") this.logAuditFailure(phase, call.name, call.id, options.agentName, "required", outcome);
       return outcome.kind !== "value";
-    } catch { return true; }
+    } catch (error) {
+      this.logAuditFailure(phase, call.name, call.id, options.agentName, "required", { kind: "failed", error });
+      return true;
+    }
   }
 
   private frameworkTerminalAuditTimeout(remainingMs: number | undefined): number {
@@ -1216,8 +1221,12 @@ export class AgentToolExecutor {
         result: redactSensitive(result, this.hookRedaction) as AgentToolResult,
         startedAtUnixMs: startedAt, finishedAtUnixMs: Date.now(), durationMs: Date.now() - startedAt,
       })), signal, timeoutMs);
+      if (outcome.kind !== "value") this.logAuditFailure("result", result.name, result.callId, undefined, "required", outcome);
       return outcome.kind !== "value";
-    } catch { return true; }
+    } catch (error) {
+      this.logAuditFailure("result", result.name, result.callId, undefined, "required", { kind: "failed", error });
+      return true;
+    }
   }
 
   private hasMandatoryHooks(): boolean {
@@ -1965,6 +1974,7 @@ export class AgentToolExecutor {
       (error: unknown) => ({ ok: false, error } as const),
     );
     const outcome = await awaitHook(settled, signal, timeoutMs);
+    if (outcome.kind === "timeout") this.logAuditFailure(entry.phase, entry.toolName, entry.callId, entry.agentName, audit.failureMode, outcome);
     if (outcome.kind !== "value") return outcome;
     return outcome.value.ok
       ? { kind: "value", value: undefined }
@@ -1980,6 +1990,8 @@ export class AgentToolExecutor {
     originalResult: AgentToolResult | undefined,
     error: unknown,
   ): AgentToolResult | undefined {
+    // Logged in both modes: in best-effort the call goes on, and the lost entry is visible only here.
+    this.logAuditFailure(entry.phase, entry.toolName, entry.callId, entry.agentName, audit.failureMode, { kind: "failed", error });
     if (audit.failureMode === "best-effort") return undefined;
     const sideEffectingSuccess = entry.phase === "result"
       && originalResult?.status === "success"
@@ -1991,8 +2003,8 @@ export class AgentToolExecutor {
         call,
         outcomeUnknown ? "TOOL_AUDIT_FAILED_OUTCOME_UNKNOWN" : "TOOL_AUDIT_FAILED",
         outcomeUnknown
-          ? `Tool result audit failed after an outcome-unknown side-effecting operation; retry safety is unknown: ${errorMessageOf(error)}`
-          : `Tool audit failed: ${errorMessageOf(error)}`,
+          ? "Tool result audit failed after an outcome-unknown side-effecting operation; retry safety is unknown."
+          : "Tool audit failed.",
         metadata,
         startedAt,
         {
@@ -2042,12 +2054,12 @@ export class AgentToolExecutor {
       .then(async (result) => {
         const error = await this.disposeScope(scope, scopeDisposeTimeoutMs);
         if (error !== undefined) {
-          console.error("[agent-tool] deferred scope disposal failed:", redactSensitive(error));
+          this.reportDeferred("Agent tool scope disposal failed", { tool: call.name, callId: call.id, error: redactSensitive(error) });
         }
         await onSettled(result);
       })
       .catch((error: unknown) => {
-        console.error("[agent-tool] deferred settlement handling failed:", redactSensitive(errorMessageOf(error)));
+        this.reportDeferred("Agent tool settlement handling failed", { tool: call.name, callId: call.id, error: redactSensitive(error) });
       });
   }
 
@@ -2056,11 +2068,36 @@ export class AgentToolExecutor {
     try {
       await auditSinkFunction(audit.sink)(entry);
     } catch (error) {
-      console.error("[agent-tool] deferred settlement audit failed:", redactSensitive(errorMessageOf(error)));
+      this.logAuditFailure(entry.phase, entry.toolName, entry.callId, entry.agentName, audit.failureMode, { kind: "failed", error });
     }
   }
 
 
+  /**
+   * The audit sink did not record an entry. `mode` is how the call treated it:
+   * `fail-closed` stopped it, `best-effort` let it go on, `required` is hook evidence.
+   */
+  private logAuditFailure(
+    phase: string,
+    toolName: string,
+    callId: string,
+    agentName: string | undefined,
+    mode: AgentToolAuditFailureMode | "required",
+    outcome: HookOutcome<unknown>,
+  ): void {
+    if (outcome.kind === "value" || outcome.kind === "cancelled") return;
+    this.logger?.error("Agent tool audit failed", {
+      phase, mode, agent: agentName ?? null, tool: toolName, callId,
+      ...(outcome.kind === "timeout" ? { reason: "timed out" } : outcome.error === undefined ? {} : { error: redactSensitive(outcome.error) }),
+    });
+  }
+
+  /** Late failures after the call returned; without an application logger they still reach stderr. */
+  private reportDeferred(message: string, fields: Record<string, unknown>): void {
+    if (this.logger) this.logger.error(message, fields);
+    else console.error(`[agent-tool] ${message}`, fields);
+  }
+
   /** A hook that failed, timed out or answered nonsense; a cancelled run is not a failure. */
   private logHookFailure(
     hook: Pick<AgentToolAuditHookProjectionV1, "kind" | "id" | "version" | "outcome">,

package/core/agent/ModelProvider.ts

@@ -16,6 +16,12 @@ export interface AgentModelProvider {
     request: AgentModelRequest,
     context: AgentModelProviderContext,
   ): AgentModelResponse | Promise<AgentModelResponse>;
+  /**
+   * Model profiles this provider serves, when it routes by profile
+   * (`llmRouter`). AgentRuntime rejects an agent naming another profile before
+   * the model is called. Without it any profile is passed through.
+   */
+  modelProfiles?(): readonly string[];
 }
 
 export const AGENT_MODEL_PROVIDER = createToken<AgentModelProvider>("AgentModelProvider");

package/core/agent/README.md

@@ -115,6 +115,10 @@ audit. A hook that throws, times out or returns an invalid answer is logged as
 `AgentRuntime` at start, so wrong runtime options or enforcement hooks without
 an audit sink stop the application with a configuration error.
 
+An audit sink that fails is logged as `Agent tool audit failed` with the
+phase and mode, in `best-effort` too, where the call goes on; the model sees
+only `Tool audit failed.`.
+
 Retries are opt-in. `write` and `external` tools need an idempotency key before
 the executor repeats them. Runtime-generated keys include both the invocation id
 and the unique model call id; `toolExecution.idempotencyKeyForCall` gives a
@@ -139,6 +143,11 @@ await this.agents.run(support, {
 conversation message when trimming old history. Provider requests include
 `metadata.agentContext.trace` so context assembly is inspectable.
 
+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
+throws `AgentModelTimeoutError`, and the run reports `AGENT_PROVIDER_TIMEOUT`.
+
 LLM clients are registered by infra connectors. Agents name a model profile;
 infra owns provider URLs, model ids, limits and fallback:
 

package/core/agent/errors.ts

@@ -47,6 +47,17 @@ export class AgentToolPreCommitError extends ToolError {
   }
 }
 
+/**
+ * A model provider gave up on a request after its own deadline (for example
+ * the connector's `timeoutMs`). The run reports it as AGENT_PROVIDER_TIMEOUT.
+ */
+export class AgentModelTimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AgentModelTimeoutError";
+  }
+}
+
 /** Error thrown when the agent runtime is configured incorrectly. */
 export class AgentRuntimeError extends Error {
   constructor(message: string) {

package/core/agent/index.ts

@@ -14,6 +14,7 @@ export {
   AgentSemanticError,
   AgentSetupError,
   AgentToolExecutionError,
+  AgentModelTimeoutError,
   AgentToolPreCommitError,
   ToolError,
 } from "./errors";

package/core/agent/internal/AgentExecutionDriver.ts

@@ -4,7 +4,7 @@ import type { ServiceProvider } from "../../di";
 import { getGeneratedOpenApiMetadata } from "../../http/OpenApi/generatedOpenApiRegistry";
 import { redactSensitive, redactSensitiveText } from "../../../library/redaction";
 import type { Logger } from "../../kernel/logging/Logger";
-import { AgentRuntimeError } from "../errors";
+import { AgentModelTimeoutError, AgentRuntimeError } from "../errors";
 import { validateAgentJsonSchema } from "./AgentJsonSchema";
 import type { AgentDefinition, AgentRegistry } from "../AgentRegistry";
 import {
@@ -1137,7 +1137,7 @@ export class AgentExecutionDriver {
         };
       }
     } catch (error) {
-      const code = error instanceof AgentRuntimeTimeoutError
+      const code = error instanceof AgentRuntimeTimeoutError || error instanceof AgentModelTimeoutError
         ? "AGENT_PROVIDER_TIMEOUT"
         : error instanceof AgentRuntimeAbortError
           ? "AGENT_ABORTED"

package/core/infra/InfraLifecycle.ts

@@ -1,4 +1,4 @@
-import type { HostedService } from "../di";
+import type { HostedService, HostedServiceDiagnostics } from "../di";
 import { InfraError, type InfraConnector } from "./InfraConnector";
 import { bindConnectorLifecycle } from "./connectorIdentity";
 import { awaitAbortable } from "../kernel/internal/awaitAbortable";
@@ -22,6 +22,7 @@ export class InfraLifecycle<TClient> implements HostedService {
   private disposed = false;
   private startPromise?: Promise<void>;
   private disposePromise?: Promise<void>;
+  private diagnostics?: HostedServiceDiagnostics;
 
   public constructor(
     private readonly name: string,
@@ -40,10 +41,22 @@ export class InfraLifecycle<TClient> implements HostedService {
     if (!this.created) {
       this.client = this.connector.create(this.configs);
       this.created = true;
+      this.forwardDiagnostics();
     }
     return this.client as TClient;
   }
 
+  /** The application logger reaches a client that reports on its own, such as `llmRouter` falling back. */
+  public useDiagnostics(diagnostics: HostedServiceDiagnostics): void {
+    this.diagnostics = diagnostics;
+    if (this.created) this.forwardDiagnostics();
+  }
+
+  private forwardDiagnostics(): void {
+    const client = this.client as { useDiagnostics?: (diagnostics: HostedServiceDiagnostics) => void } | undefined;
+    if (this.diagnostics !== undefined && typeof client?.useDiagnostics === "function") client.useDiagnostics(this.diagnostics);
+  }
+
   public start(signal?: AbortSignal): Promise<void> {
     this.startPromise ??= Promise.resolve().then(() => this.connect(signal));
     return this.startPromise;

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.99.3" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.99.5" }, 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/llmRouter.ts

@@ -1,6 +1,9 @@
 import type { AppConfig } from "../../kernel";
+import type { HostedServiceDiagnostics } from "../../di";
+import { redactSensitive } from "../../../library/redaction";
 import {
   AGENT_MODEL_PROVIDER,
+  AgentModelTimeoutError,
   AgentRuntime,
   agentModelRequest,
   type AgentModelProvider,
@@ -194,11 +197,13 @@ export class LlmModelRouter implements AgentModelProvider {
   private initializePromise?: Promise<void>;
   private disposePromise?: Promise<void>;
   private disposed = false;
+  private diagnostics?: HostedServiceDiagnostics;
 
   public constructor(
     profiles: readonly RuntimeProfile[],
     private readonly defaultProfile: string,
     private readonly factories: readonly (() => RuntimeProfile)[] = [],
+    private readonly profileNames: readonly string[] = profiles.map((profile) => profile.name),
   ) {
     for (let index = 0; index < profiles.length; index += 1) {
       const profile = profiles[index] as RuntimeProfile;
@@ -213,6 +218,16 @@ export class LlmModelRouter implements AgentModelProvider {
     return this.completeWithProfile(request, context, requested, new Set<string>());
   }
 
+  /** Profile names an agent may use in `modelProfile`. */
+  public modelProfiles(): readonly string[] {
+    return this.profileNames;
+  }
+
+  /** The application logger: a fallback is reported, not silent. */
+  public useDiagnostics(diagnostics: HostedServiceDiagnostics): void {
+    this.diagnostics = diagnostics;
+  }
+
   public connect(signal?: AbortSignal): Promise<void> {
     if (this.disposed) {
       return Promise.reject(new InfraError("LLM model router is already disposed."));
@@ -363,11 +378,15 @@ export class LlmModelRouter implements AgentModelProvider {
       // A second model must not silently append a new answer to already visible text.
       if (fallback !== undefined && !emittedText) {
         if (context.signal.aborted) throw new LlmModelRouterError("LLM model request was cancelled before provider dispatch.");
+        this.diagnostics?.warn("LLM model profile failed, using fallback", {
+          profile: profileName, fallback, agent: context.agentName, invocationId: context.invocationId, error: redactSensitive(error),
+        });
         return this.completeWithProfile(request, context, fallback, visited);
       }
-      throw new LlmModelRouterError(
-        `LLM model profile "${profileName}" failed: ${errorMessageOf(error)}`,
-      );
+      const message = `LLM model profile "${profileName}" failed: ${errorMessageOf(error)}`;
+      // Keep a timeout a timeout: the run reports it as AGENT_PROVIDER_TIMEOUT.
+      if (error instanceof AgentModelTimeoutError) throw new AgentModelTimeoutError(message);
+      throw new LlmModelRouterError(message);
     } finally {
       acceptingText = false;
     }
@@ -432,7 +451,7 @@ export function llmRouter(
           options: profile.options,
         });
       });
-      return new LlmModelRouter([], defaultProfile, factories);
+      return new LlmModelRouter([], defaultProfile, factories, entries.map(([name]) => name));
     },
     connect(client, signal) {
       return client instanceof LlmModelRouter ? client.connect(signal) : undefined;

package/core/infra/connectors/openaiCompatible.ts

@@ -1,4 +1,5 @@
 import {
+  AgentModelTimeoutError,
   agentMessage,
   agentModelResponse,
   agentToolCall,
@@ -490,7 +491,7 @@ export class OpenAiCompatibleModelProvider implements AgentModelProvider {
     const detach = attachAbortForwarding(signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal, abort);
     const timeout = this.requestTimeoutMs === undefined
       ? undefined
-      : setTimeout(() => abort.abort(new Error("OpenAI-compatible request timed out.")), this.requestTimeoutMs);
+      : setTimeout(() => abort.abort(new AgentModelTimeoutError("OpenAI-compatible request timed out.")), this.requestTimeoutMs);
     try {
       abort.signal.throwIfAborted();
       const response = await this.fetcher(`${this.baseUrl}${path}`, {

package/index.ts

@@ -82,6 +82,7 @@ export {
   AgentRuntime,
   AgentRuntimeError,
   AgentSemanticError,
+  AgentModelTimeoutError,
   AgentToolExecutionError,
   ToolError,
   ApproximateAgentContextTokenEstimator,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.99.3",
+  "version": "0.99.5",
   "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",