bazis 0.97.9 → 0.97.10

package/core/background/BackgroundService.ts

@@ -1,4 +1,4 @@
-import type { HostedService } from "../di";
+import type { HostedService, HostedServiceDiagnostics } from "../di";
 import { backgroundOptionsOf } from "./decorator";
 import { delay } from "./delay";
 import { redactSensitive } from "../../library/redaction";
@@ -54,6 +54,9 @@ export abstract class BackgroundService implements HostedService {
   private controller?: AbortController;
   private runPromise?: Promise<void>;
 
+  /** The application logger, passed by the kernel; console until then. */
+  private diagnostics?: HostedServiceDiagnostics;
+
   public constructor(options?: BackgroundServiceOptions) {
     // Explicit `super(...)` options win over `@Background({...})` metadata.
     const resolved = { ...backgroundOptionsOf(this.constructor), ...options };
@@ -65,13 +68,22 @@ export abstract class BackgroundService implements HostedService {
   /** The background workload. Must observe `signal` for cooperative shutdown. */
   protected abstract execute(signal: AbortSignal): void | Promise<void>;
 
+  public useDiagnostics(diagnostics: HostedServiceDiagnostics): void {
+    this.diagnostics = diagnostics;
+  }
+
+  /** Reports a failure of this service: the application logger, or the console without one. */
+  protected reportFailure(message: string, error: unknown, fields: Readonly<Record<string, unknown>> = {}): void {
+    report(this.diagnostics, "error", this.constructor.name, message, { ...fields, error: redactSensitive(error) });
+  }
+
   public start(): void {
     if (this.controller) {
       return;
     }
     this.controller = new AbortController();
     this.runPromise = this.runSupervised(this.controller.signal)
-      .catch((error: unknown) => logBackgroundError(this.constructor.name, error));
+      .catch((error: unknown) => this.reportFailure("supervisor failed", error));
   }
 
   public async stop(): Promise<void> {
@@ -83,7 +95,9 @@ export abstract class BackgroundService implements HostedService {
     this.controller = undefined;
     this.runPromise = undefined;
     if (pending) {
-      await waitWithTimeout(pending, this.stopTimeoutMs, this.constructor.name);
+      await waitWithTimeout(pending, this.stopTimeoutMs, () => report(this.diagnostics, "warn", this.constructor.name,
+        `did not stop within ${this.stopTimeoutMs}ms: shutdown continues, but its unfinished work keeps the process alive until it ends`,
+        { stopTimeoutMs: this.stopTimeoutMs }));
     }
   }
 
@@ -104,6 +118,10 @@ export abstract class BackgroundService implements HostedService {
         }
         this.reportError(error, restarts);
         if (restarts >= maxRestarts) {
+          // Without this line the service would just go quiet.
+          report(this.diagnostics, "error", this.constructor.name, maxRestarts === 0
+            ? "stopped after a crash and will not run again (no restart policy)"
+            : `stopped after ${maxRestarts} restart${maxRestarts === 1 ? "" : "s"} and will not run again`, { restarts });
           return;
         }
         restarts += 1;
@@ -117,9 +135,9 @@ export abstract class BackgroundService implements HostedService {
 
   private reportError(error: unknown, restarts: number): void {
     if (this.restart.onError) {
-      observeDiagnostic(() => this.restart.onError!(error, restarts), this.constructor.name);
+      observeDiagnostic(() => this.restart.onError!(error, restarts), (failure) => this.reportFailure("onError callback failed", failure));
     } else {
-      logBackgroundError(this.constructor.name, error);
+      this.reportFailure("crashed", error, { restarts });
     }
   }
 }
@@ -162,7 +180,7 @@ export abstract class PeriodicBackgroundService extends BackgroundService {
 
   /** Hook for tick failures; default logs. The loop continues regardless. */
   protected onTickError(error: unknown): void {
-    logBackgroundError(this.constructor.name, error);
+    this.reportFailure("tick failed", error);
   }
 
   protected override async execute(signal: AbortSignal): Promise<void> {
@@ -176,7 +194,7 @@ export abstract class PeriodicBackgroundService extends BackgroundService {
         if (signal.aborted) {
           return;
         }
-        observeDiagnostic(() => this.onTickError(error), this.constructor.name);
+        observeDiagnostic(() => this.onTickError(error), (failure) => this.reportFailure("onTickError failed", failure));
       }
       if (signal.aborted) {
         return;
@@ -187,20 +205,34 @@ export abstract class PeriodicBackgroundService extends BackgroundService {
 }
 
 /** Diagnostics are best-effort; even an accidentally async observer cannot own the loop. */
-function observeDiagnostic(callback: () => unknown, name: string): void {
+function observeDiagnostic(callback: () => unknown, onFailure: (error: unknown) => void): void {
   try {
-    void Promise.resolve(callback()).catch((error: unknown) => logBackgroundError(name, error));
+    void Promise.resolve(callback()).catch(onFailure);
   } catch (error) {
-    logBackgroundError(name, error);
+    onFailure(error);
   }
 }
 
-function logBackgroundError(name: string, error: unknown): void {
-  try { console.error(`[background:${name}]`, redactSensitive(error)); }
-  catch { /* A broken diagnostic sink must not terminate the workload supervisor. */ }
+/** One line per event: "background Crasher crashed" with the service name in the fields. */
+function report(
+  diagnostics: HostedServiceDiagnostics | undefined,
+  level: "error" | "warn",
+  name: string,
+  message: string,
+  fields: Readonly<Record<string, unknown>>,
+): void {
+  try {
+    if (diagnostics) {
+      diagnostics[level](`background ${name} ${message}`, { service: name, ...fields });
+      return;
+    }
+    const { error, ...rest } = fields;
+    const details = error === undefined ? (Object.keys(rest).length ? [rest] : []) : [error];
+    (level === "error" ? console.error : console.warn)(`[background:${name}] ${message}`, ...details);
+  } catch { /* A broken diagnostic sink must not terminate the workload supervisor. */ }
 }
 
-async function waitWithTimeout(promise: Promise<void>, timeoutMs: number, name: string): Promise<void> {
+async function waitWithTimeout(promise: Promise<void>, timeoutMs: number, onTimeout: () => void): Promise<void> {
   const guarded = promise.catch(() => undefined);
   if (timeoutMs <= 0) {
     await guarded;
@@ -209,7 +241,7 @@ async function waitWithTimeout(promise: Promise<void>, timeoutMs: number, name:
   let timer: ReturnType<typeof setTimeout> | undefined;
   const timeout = new Promise<void>((resolve) => {
     timer = setTimeout(() => {
-      console.warn(`[background:${name}] did not stop within ${timeoutMs}ms; continuing shutdown`);
+      onTimeout();
       resolve();
     }, timeoutMs);
   });

package/core/di/extensions/hosted-service.ts

@@ -13,9 +13,20 @@ export interface HostedServicePlanValidator {
   validate(services: readonly HostedService[], signal?: AbortSignal): void | Promise<void>;
 }
 
+/**
+ * Where a hosted service reports what it handles itself: crashes, restarts, a
+ * slow stop. The application logger fits it structurally.
+ */
+export interface HostedServiceDiagnostics {
+  error(message: string, fields?: Readonly<Record<string, unknown>>): void;
+  warn(message: string, fields?: Readonly<Record<string, unknown>>): void;
+}
+
 export interface HostedService {
   /** Shared validators see real service identities, including inside supervised wrappers. */
   readonly planValidator?: HostedServicePlanValidator;
+  /** Receives the application logger before start, when one is registered. */
+  useDiagnostics?(diagnostics: HostedServiceDiagnostics): void;
   start(signal?: AbortSignal): void | Promise<void>;
   stop(): void | Promise<void>;
   /**

package/core/di/extensions/index.ts

@@ -1,6 +1,6 @@
 export { createInstance, type ActivatorDependency } from "./activator";
 export { Application, runApplication, type RunApplicationOptions } from "./application";
-export { addHostedService, HOSTED_SERVICE, startHostedServices, stopHostedServices, type HostedService, type HostedServicePlanValidator } from "./hosted-service";
+export { addHostedService, HOSTED_SERVICE, startHostedServices, stopHostedServices, type HostedService, type HostedServiceDiagnostics, type HostedServicePlanValidator } from "./hosted-service";
 export { SERVICE_PROVIDER } from "./service-provider-token";
 export {
   addOptions,

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.97.9" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.97.10" }, 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/kernel/LifecycleCoordinator.ts

@@ -1,6 +1,7 @@
 import { validateOptionsOnStart, type HostedService } from "../di";
 import type { Token } from "../di";
 import { LIFECYCLE_HOOK } from "./lifecycleHooks";
+import { LOGGER } from "./logging/Logger";
 import type { LifecycleHook } from "./types";
 import { ShutdownTimeoutError } from "./errors";
 import { awaitAbortable } from "./internal/awaitAbortable";
@@ -9,6 +10,7 @@ import { awaitShutdown } from "./internal/awaitShutdown";
 
 interface LifecycleResolver {
   resolveAll<T>(token: Token<T>): readonly T[];
+  tryResolve?<T>(token: Token<T>): T | undefined;
 }
 
 /**
@@ -57,6 +59,9 @@ export class LifecycleCoordinator {
     signal?.throwIfAborted();
     validateOptionsOnStart(this.resolver);
     const hosted = resolveHostedServices(this.resolver);
+    // Background failures go to the application logger, like HTTP errors.
+    const logger = this.resolver.tryResolve?.(LOGGER);
+    if (logger) for (const service of hosted) service.useDiagnostics?.(logger);
     const validation = validateHostedServicePlan(hosted, signal);
     if (validation) await awaitAbortable(validation, signal);
     this.hooks = this.resolver.resolveAll(LIFECYCLE_HOOK);

package/core/kernel/SupervisedHostedService.ts

@@ -1,4 +1,4 @@
-import type { HostedService, HostedServicePlanValidator } from "../di";
+import type { HostedService, HostedServiceDiagnostics, HostedServicePlanValidator } from "../di";
 import { validateHostedServicePlan, registerHostedServiceWrapper, type HostedServicePlanAdmission } from "../di/extensions/hosted-service";
 import { awaitAbortable } from "./internal/awaitAbortable";
 import { reportDiagnosticFailure } from "./internal/reportDiagnosticFailure";
@@ -34,6 +34,7 @@ export class SupervisedHostedService implements HostedService {
   private admittedPhase?: number;
   private starting?: Promise<void>;
   private stopping?: Promise<void>;
+  private diagnostics?: HostedServiceDiagnostics;
 
   public constructor(
     private readonly factory: () => HostedService,
@@ -46,6 +47,11 @@ export class SupervisedHostedService implements HostedService {
     });
   }
 
+  /** Passed on to every attempt's service before it starts. */
+  public useDiagnostics(diagnostics: HostedServiceDiagnostics): void {
+    this.diagnostics = diagnostics;
+  }
+
   public start(signal?: AbortSignal): Promise<void> {
     if (this.stopping) {
       const stopping = this.stopping;
@@ -71,6 +77,7 @@ export class SupervisedHostedService implements HostedService {
       this.prepared = undefined;
       try {
         signal?.throwIfAborted();
+        if (this.diagnostics) service.useDiagnostics?.(this.diagnostics);
         await service.start(signal);
         signal?.throwIfAborted();
         this.inner = service;

package/package.json

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