bazis 0.99.2 → 0.99.4

package/core/agent/AgentToolExecutor.ts

@@ -327,14 +327,14 @@ function isSettlementResult(value: unknown): value is { readonly status: "record
   } catch { return false; }
 }
 
-type HookOutcome<T> = { readonly kind: "value"; readonly value: T } | { readonly kind: "timeout" } | { readonly kind: "cancelled" } | { readonly kind: "failed" };
+type HookOutcome<T> = { readonly kind: "value"; readonly value: T } | { readonly kind: "timeout" } | { readonly kind: "cancelled" } | { readonly kind: "failed"; readonly error?: unknown };
 
 async function awaitHook<T>(operation: Promise<T>, signal: AbortSignal | undefined, timeoutMs: number | undefined): Promise<HookOutcome<T>> {
   // Observe both branches even after the caller's deadline wins: a late hook
   // rejection must never become an unhandled process-level rejection.
   const observed: Promise<HookOutcome<T>> = operation
     .then((value): HookOutcome<T> => ({ kind: "value", value }))
-    .catch((): HookOutcome<T> => ({ kind: "failed" }));
+    .catch((error: unknown): HookOutcome<T> => ({ kind: "failed", error }));
   if (signal?.aborted) return { kind: "cancelled" };
   let timer: ReturnType<typeof setTimeout> | undefined;
   let detach: (() => void) | undefined;
@@ -646,6 +646,7 @@ export class AgentToolExecutor {
         tier: this.isPlatformHook(record) ? "platform" : "application", order: registration.order ?? 0,
         outcome: "failed",
       };
+      let hookError: unknown;
       const postEffect = state.executeStarted;
       const configuredTimeoutMs = registration.timeoutMs ?? 5_000;
       const remainingMs = !postEffect && state.deadlineUnixMs !== undefined
@@ -683,6 +684,7 @@ export class AgentToolExecutor {
         const activated = await awaitHook(record.activation.activateAsync(scope), controller.signal, boundedTimeoutMs);
         if (activated.kind !== "value") {
           if (activated.kind === "timeout") controller.abort();
+          if (activated.kind === "failed") hookError = activated.error;
           projection = { ...projection, outcome: activated.kind === "timeout" ? "timed-out" : activated.kind === "cancelled" ? (state.callerSignal?.aborted ? "cancelled" : "timed-out") : "failed" };
           terminal = this.errorResult(call, "TOOL_HOOK_SETTLEMENT_FAILED", "Agent Tool settlement handler was unavailable.", metadata, startedAt);
         } else {
@@ -695,6 +697,7 @@ export class AgentToolExecutor {
             const outcome = await awaitHook(Promise.resolve((handler.settle as (value: AgentToolSettlementEventV1, context: AgentToolHookContextV1) => unknown)(event, context)), controller.signal, invocationTimeoutMs);
             if (outcome.kind === "timeout") controller.abort();
             if (outcome.kind !== "value") {
+              if (outcome.kind === "failed") hookError = outcome.error;
               projection = { ...projection, outcome: outcome.kind === "timeout" ? "timed-out" : outcome.kind === "cancelled" ? (state.callerSignal?.aborted ? "cancelled" : "timed-out") : "failed" };
               terminal = this.errorResult(call, "TOOL_HOOK_SETTLEMENT_FAILED", "Agent Tool settlement failed.", metadata, startedAt);
             } else if (!isSettlementResult(outcome.value)) {
@@ -707,17 +710,20 @@ export class AgentToolExecutor {
           }
         }
         }
-      } catch {
+      } catch (error) {
+        hookError = error;
         projection = { ...projection, outcome: "failed" };
         terminal = this.errorResult(call, "TOOL_HOOK_SETTLEMENT_FAILED", "Agent Tool settlement failed.", metadata, startedAt);
       } finally {
         detach?.();
         const disposeError = await this.disposeScope(scope, this.scopeDisposeTimeoutMs);
         if (disposeError !== undefined) {
+          hookError ??= disposeError;
           projection = { ...projection, outcome: "failed" };
           terminal = this.errorResult(call, "TOOL_HOOK_SETTLEMENT_FAILED", "Agent Tool settlement disposal failed.", metadata, startedAt);
         }
       }
+      this.logHookFailure(projection, call, event.agentName, hookError);
       const evidenceRemainingMs = postEffect || state.deadlineUnixMs === undefined
         ? registration.timeoutMs ?? 5_000
         : Math.max(0, Math.min(registration.timeoutMs ?? 5_000, state.deadlineUnixMs - Date.now()));
@@ -744,6 +750,7 @@ export class AgentToolExecutor {
       if (registration.kind !== "observer") continue;
       const scope = this.services.createScope();
       let outcome: AgentToolAuditHookProjectionV1["outcome"] = "failed";
+      let hookError: unknown;
       const timeoutMs = registration.timeoutMs ?? 5_000;
       const controller = new AbortController();
       const detach = attachAbortForwarding(options.signal, controller);
@@ -752,6 +759,7 @@ export class AgentToolExecutor {
         const activated = await awaitHook(record.activation.activateAsync(scope), controller.signal, timeoutMs);
         if (activated.kind !== "value") {
           if (activated.kind === "timeout") controller.abort();
+          if (activated.kind === "failed") hookError = activated.error;
           outcome = activated.kind === "timeout" ? "timed-out" : activated.kind === "cancelled" ? "cancelled" : "failed";
         } else {
           const handler = activated.value as { observe?: unknown };
@@ -764,15 +772,22 @@ export class AgentToolExecutor {
               Math.max(1, context.deadlineUnixMs - Date.now()),
             );
             if (observed.kind === "timeout" || observed.kind === "value") controller.abort();
+            if (observed.kind === "failed") hookError = observed.error;
             outcome = observed.kind === "value" ? "recorded" : observed.kind === "timeout" ? "timed-out" : observed.kind === "cancelled" ? "cancelled" : "failed";
           }
         }
-      } catch {
+      } catch (error) {
+        hookError = error;
         outcome = controller.signal.aborted && options.signal?.aborted ? "cancelled" : "failed";
       } finally {
         detach?.();
-        if (await this.disposeScope(scope, this.scopeDisposeTimeoutMs) !== undefined) outcome = "failed";
+        const disposeError = await this.disposeScope(scope, this.scopeDisposeTimeoutMs);
+        if (disposeError !== undefined) {
+          hookError ??= disposeError;
+          outcome = "failed";
+        }
       }
+      this.logHookFailure({ kind: registration.kind, id: registration.id, version: registration.version, outcome }, { id: settlement.callId, name: settlement.toolName }, settlement.agentName, hookError);
       await this.recordObserverHook(settlement, registration, record, outcome, timeoutMs);
     }
   }
@@ -796,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(
@@ -1086,6 +1102,7 @@ export class AgentToolExecutor {
         tier: isPlatform(record) ? "platform" : "application", order: registration.order ?? 0,
         outcome: "failed",
       };
+      let hookError: unknown;
       const configuredTimeoutMs = registration.timeoutMs ?? 5_000;
       const remainingMs = executionState.deadlineUnixMs === undefined
         ? undefined : Math.max(0, executionState.deadlineUnixMs - Date.now());
@@ -1102,6 +1119,7 @@ export class AgentToolExecutor {
         const activated = await awaitHook(record.activation.activateAsync(scope), controller.signal, timeoutMs);
         if (activated.kind !== "value") {
           if (activated.kind === "timeout") controller.abort();
+          if (activated.kind === "failed") hookError = activated.error;
           projection = { ...projection, outcome: activated.kind === "timeout" ? "timed-out" : activated.kind === "cancelled" ? "cancelled" : "failed" };
           terminal = this.errorResult(call, activated.kind === "timeout" ? "TOOL_HOOK_TIMEOUT" : activated.kind === "cancelled" ? "TOOL_HOOK_CANCELLED" : "TOOL_HOOK_UNAVAILABLE", "Agent Tool enforcement handler was unavailable.", metadata, startedAt);
         } else {
@@ -1113,27 +1131,31 @@ export class AgentToolExecutor {
             if (outcome.kind === "timeout") controller.abort();
             if (outcome.kind === "timeout") { projection = { ...projection, outcome: "timed-out" }; terminal = this.errorResult(call, "TOOL_HOOK_TIMEOUT", "Agent Tool enforcement hook timed out.", metadata, startedAt); }
             else if (outcome.kind === "cancelled") { projection = { ...projection, outcome: "cancelled" }; terminal = this.errorResult(call, "TOOL_HOOK_CANCELLED", "Agent Tool enforcement hook was cancelled.", metadata, startedAt); }
-            else if (outcome.kind === "failed") { terminal = this.errorResult(call, "TOOL_HOOK_FAILED", "Agent Tool enforcement hook failed.", metadata, startedAt); }
+            else if (outcome.kind === "failed") { hookError = outcome.error; terminal = this.errorResult(call, "TOOL_HOOK_FAILED", "Agent Tool enforcement hook failed.", metadata, startedAt); }
             else if (!isHookDecision(outcome.value)) { projection = { ...projection, outcome: "invalid-result" }; terminal = this.errorResult(call, "TOOL_HOOK_DECISION_INVALID", "Agent Tool enforcement hook returned an invalid decision.", metadata, startedAt); }
             else {
               const decision = outcome.value;
-              projection = { ...projection, outcome: decision.decision === "allow" ? "allowed" : "denied", ...(decision.decision === "deny" && decision.reasonCode ? { reasonCode: decision.reasonCode } : {}), ...(decision.evidence ? { evidence: redactSensitive(normalizeHookEvidence(decision.evidence), this.hookRedaction) as JsonObject } : {}) };
-              if (decision.decision === "deny") terminal = this.deniedResult(call, "TOOL_HOOK_DENIED", "Tool execution was denied by an enforcement hook.", {}, metadata, startedAt);
+              projection = { ...projection, outcome: decision.decision === "allow" ? "allowed" : "denied", ...(decision.decision === "deny" && decision.reasonCode ? { reasonCode: decision.reasonCode } : {}), ...(decision.decision === "deny" && decision.message ? { message: redactSensitive(decision.message) as string } : {}), ...(decision.evidence ? { evidence: redactSensitive(normalizeHookEvidence(decision.evidence), this.hookRedaction) as JsonObject } : {}) };
+              // The hook's message is meant for the model, like a ToolError; reasonCode helps it branch.
+              if (decision.decision === "deny") terminal = this.deniedResult(call, "TOOL_HOOK_DENIED", decision.message ?? "Tool execution was denied by an enforcement hook.", decision.reasonCode ? { reasonCode: decision.reasonCode } : {}, metadata, startedAt);
             }
           }
         }
         }
-      } catch {
+      } catch (error) {
+        hookError = error;
         projection = { ...projection, outcome: "failed" };
         terminal = this.errorResult(call, options.signal?.aborted ? "TOOL_HOOK_CANCELLED" : "TOOL_HOOK_FAILED", "Agent Tool enforcement hook failed.", metadata, startedAt);
       } finally {
         detach?.();
         const disposeError = await this.disposeScope(scope, this.scopeDisposeTimeoutMs);
         if (disposeError !== undefined) {
+          hookError ??= disposeError;
           projection = { ...projection, outcome: "failed" };
           terminal = this.errorResult(call, "TOOL_HOOK_FAILED", "Agent Tool enforcement hook disposal failed.", metadata, startedAt);
         }
       }
+      this.logHookFailure(projection, call, agentName, hookError);
       const evidenceRemainingMs = executionState.deadlineUnixMs === undefined
         ? registration.timeoutMs ?? 5_000
         : Math.max(0, Math.min(registration.timeoutMs ?? 5_000, executionState.deadlineUnixMs - Date.now()));
@@ -1174,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 {
@@ -1195,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 {
@@ -1944,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 }
@@ -1959,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"
@@ -1970,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,
         {
@@ -2021,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) });
       });
   }
 
@@ -2035,11 +2068,50 @@ 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">,
+    call: Pick<AgentToolCall, "id" | "name">,
+    agentName: string | undefined,
+    error: unknown,
+  ): void {
+    if (hook.outcome !== "failed" && hook.outcome !== "timed-out" && hook.outcome !== "invalid-result") return;
+    this.logger?.error("Agent tool hook failed", {
+      hook: `${hook.kind}:${hook.id}@${hook.version}`, outcome: hook.outcome, agent: agentName ?? null, tool: call.name, callId: call.id,
+      ...(error === undefined ? {} : { error: redactSensitive(error) }),
+    });
+  }
+
   /**
    * A tool's own failure: a ToolError message reaches the model as written;
    * anything else is replaced by `fallback` and logged with its stack.

package/core/agent/AgentToolHooks.ts

@@ -36,4 +36,4 @@ export interface AgentToolSettlementResultV1 { readonly status: "recorded"; read
 export interface AgentToolSettlementHookV1 { settle(event: AgentToolSettlementEventV1, context: AgentToolHookContextV1): AgentToolSettlementResultV1 | Promise<AgentToolSettlementResultV1>; }
 export interface AgentToolObserverEventV1 { readonly type: "agent-tool.observer/v1"; readonly settlement: AgentToolSettlementEventV1; }
 export interface AgentToolObserverHookV1 { observe(event: AgentToolObserverEventV1, context: AgentToolHookContextV1): void | Promise<void>; }
-export interface AgentToolAuditHookProjectionV1 extends AgentToolHookRefV1 { readonly tier: "platform" | "application"; readonly order: number; readonly outcome: "allowed" | "denied" | "recorded" | "failed" | "timed-out" | "cancelled" | "invalid-result"; readonly reasonCode?: string; readonly evidence?: JsonObject; }
+export interface AgentToolAuditHookProjectionV1 extends AgentToolHookRefV1 { readonly tier: "platform" | "application"; readonly order: number; readonly outcome: "allowed" | "denied" | "recorded" | "failed" | "timed-out" | "cancelled" | "invalid-result"; readonly reasonCode?: string; readonly message?: string; readonly evidence?: JsonObject; }

package/core/agent/README.md

@@ -108,6 +108,17 @@ details stay out of the LLM — and goes to the application log with its stack
 call failed`. The LLM connectors pass the application logger; a runtime created
 by hand takes `options.logger`.
 
+An enforcement hook that denies a call explains why with `message` — it reaches
+the model as written, with `reasonCode` in `error.details`, and both go to the
+audit. A hook that throws, times out or returns an invalid answer is logged as
+`Agent tool hook failed` with the error. `llmConnect` and `llmRouter` build
+`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

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.2" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.99.4" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/infra/connectors/llm.ts

@@ -1,6 +1,6 @@
 import type { AppConfig, ConfigRegistry, Secret } from "../../kernel";
 import { AGENT_MODEL_PROVIDER, AGENT_RUNTIME_OPTIONS, AgentRuntime, type AgentModelProvider } from "../../agent";
-import { DI, SERVICE_PROVIDER, type ProviderDefinition } from "../../di";
+import { DI, DiError, HOSTED_SERVICE, SERVICE_PROVIDER, type ProviderDefinition } from "../../di";
 import { LOGGER } from "../../kernel/logging/Logger";
 import { reader, requireValue } from "../connectorConfig";
 import { InfraError, type InfraConnector } from "../InfraConnector";
@@ -66,6 +66,19 @@ export const agentRuntimeProviders: readonly ProviderDefinition[] = Object.freez
     const options = services.has(AGENT_RUNTIME_OPTIONS) ? services.resolve(AGENT_RUNTIME_OPTIONS) : {};
     return new AgentRuntime(services, model, { ...options, logger: options.logger ?? services.tryResolve(LOGGER) });
   })),
+  // Builds the runtime at start: wrong options or hooks without an audit sink
+  // stop the application instead of failing every agent request.
+  DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => ({
+    start() {
+      try {
+        resolver.resolve(AgentRuntime);
+      } catch (error) {
+        if (error instanceof DiError) throw error;
+        throw new DiError(`AgentRuntime: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    },
+    stop() {},
+  }))),
 ]);
 
 export function llmConnect<T extends LlmConfigShape>(

package/package.json

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