bazis 0.98.32 → 0.98.33

package/core/background/BackgroundService.ts

@@ -1,4 +1,4 @@
-import type { HostedService, HostedServiceDiagnostics } from "../di";
+import type { HostedService, HostedServiceDiagnostics, HostedServiceHealth } from "../di";
 import { backgroundOptionsOf } from "./decorator";
 import { delay } from "./delay";
 import { redactSensitive } from "../../library/redaction";
@@ -56,6 +56,8 @@ export abstract class BackgroundService implements HostedService {
 
   /** The application logger, passed by the kernel; console until then. */
   private diagnostics?: HostedServiceDiagnostics;
+  /** Set when the service stopped for good after a crash: `/health` reports it. */
+  private terminated?: string;
 
   public constructor(options?: BackgroundServiceOptions) {
     // Explicit `super(...)` options win over `@Background({...})` metadata.
@@ -68,6 +70,15 @@ export abstract class BackgroundService implements HostedService {
   /** The background workload. Must observe `signal` for cooperative shutdown. */
   protected abstract execute(signal: AbortSignal): void | Promise<void>;
 
+  /**
+   * Unhealthy once the service stopped for good: it crashed without a restart
+   * policy, or used up its restarts. A pause before a restart, a tick failure
+   * of a periodic service and a normal end of `execute` stay healthy.
+   */
+  public checkHealth(): HostedServiceHealth {
+    return this.terminated === undefined ? { healthy: true } : { healthy: false, details: this.terminated };
+  }
+
   public useDiagnostics(diagnostics: HostedServiceDiagnostics): void {
     this.diagnostics = diagnostics;
   }
@@ -119,9 +130,11 @@ 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
+          const stopped = 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 });
+            : `stopped after ${maxRestarts} restart${maxRestarts === 1 ? "" : "s"} and will not run again`;
+          report(this.diagnostics, "error", this.constructor.name, stopped, { restarts });
+          this.terminated = `${stopped}: ${error instanceof Error ? error.message : String(error)}`;
           return;
         }
         restarts += 1;

package/core/background/decorator.ts

@@ -26,7 +26,8 @@ interface BackgroundMetadataCarrier {
  * ```
  *
  * Options passed explicitly to `super(...)` take precedence over the decorator.
- * Registration stays explicit — list the class in `backgroundModule({ services })`.
+ * Registration stays explicit — list the class in `background` of its module:
+ * `@Module({ background: [Heartbeat] })`.
  */
 export function Background(options: BackgroundDecoratorOptions = {}) {
   return (_value: abstract new (...args: never[]) => unknown, context: ClassDecoratorContext): void => {

package/core/background/index.ts

@@ -10,6 +10,5 @@ export {
   type BackgroundServiceOptions,
   type PeriodicBackgroundServiceOptions,
 } from "./BackgroundService";
-export { backgroundModule, type BackgroundModuleConfig } from "./backgroundModule";
 export { Background, backgroundOptionsOf, type BackgroundDecoratorOptions } from "./decorator";
 export { delay } from "./delay";

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

@@ -22,7 +22,18 @@ export interface HostedServiceDiagnostics {
   warn(message: string, fields?: Readonly<Record<string, unknown>>): void;
 }
 
+/** What a hosted service reports to `/health`. */
+export interface HostedServiceHealth {
+  readonly healthy: boolean;
+  readonly details?: string;
+}
+
 export interface HostedService {
+  /**
+   * The service's own state for `/health`. A `background` service of a module
+   * is reported as `background:<Class>`; without this method it is healthy.
+   */
+  checkHealth?(): HostedServiceHealth;
   /** Shared validators see real service identities, including inside supervised wrappers. */
   readonly planValidator?: HostedServicePlanValidator;
   /** Receives the application logger before start, when one is registered. */
@@ -39,6 +50,15 @@ export interface HostedService {
 
 export const HOSTED_SERVICE = createToken<HostedService>("IHostedService");
 
+/** A health check contributed by a hosted service; the kernel reports it next to its own checks. */
+export interface HostedServiceHealthCheck {
+  readonly name: string;
+  check(): HostedServiceHealth;
+}
+
+/** Enumerable: one entry per `background` service of the module graph. */
+export const HOSTED_SERVICE_HEALTH = createToken<HostedServiceHealthCheck>("BazisHostedServiceHealth");
+
 interface HostedServiceResolver {
   resolveAll(token: typeof HOSTED_SERVICE): readonly HostedService[];
 }

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 HostedServiceDiagnostics, type HostedServicePlanValidator } from "./hosted-service";
+export { addHostedService, HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, startHostedServices, stopHostedServices, type HostedService, type HostedServiceDiagnostics, type HostedServiceHealth, type HostedServiceHealthCheck, type HostedServicePlanValidator } from "./hosted-service";
 export { SERVICE_PROVIDER } from "./service-provider-token";
 export {
   addOptions,

package/core/di/module/createContainer.ts

@@ -1,6 +1,6 @@
 import { DiContainer } from "../container";
 import { ServiceCollection } from "../ServiceCollection";
-import { HOSTED_SERVICE, type HostedService } from "../extensions/hosted-service";
+import { HOSTED_SERVICE, HOSTED_SERVICE_HEALTH, type HostedService } from "../extensions/hosted-service";
 import { SERVICE_PROVIDER, SERVICE_PROVIDER_BY_TYPE } from "../extensions/service-provider-token";
 import { isClassProvider, ProviderDefinition, type Provider } from "../provider";
 import { getClassDeps } from "../internal/classDeps";
@@ -162,6 +162,13 @@ export function createContainer(rootModule: BazisModuleRef, options?: CreateCont
         collection.add(
           DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => resolver.resolve(ServiceClass))),
         );
+        // `/health` sees a service that stopped for good, not only the process.
+        collection.add(
+          DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE_HEALTH, [], (resolver) => {
+            const service = resolver.resolve(ServiceClass);
+            return { name: `background:${ServiceClass.name}`, check: () => service.checkHealth?.() ?? { healthy: true } };
+          })),
+        );
       }
     }
 

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.98.32" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.33" }, 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/health/HealthService.ts

@@ -1,4 +1,4 @@
-import type { ServiceResolver } from "../../di";
+import { HOSTED_SERVICE_HEALTH, type ServiceResolver } from "../../di";
 import { redactSensitiveText } from "../../../library/redaction";
 import { awaitAbortable } from "../internal/awaitAbortable";
 import { KernelError } from "../errors";
@@ -21,7 +21,8 @@ export class HealthService {
     const timeoutMs = bounded(options.timeoutMs ?? 5000, "timeoutMs", 2147483647);
     const checkTimeoutMs = bounded(options.checkTimeoutMs ?? 1000, "checkTimeoutMs", 2147483647);
     const concurrency = bounded(options.concurrency ?? 4, "concurrency", 1024);
-    const checks = this.resolver.resolveAll(HEALTH_CHECK);
+    // Hosted services (background) report whether they still run.
+    const checks: readonly HealthCheck[] = [...this.resolver.resolveAll(HEALTH_CHECK), ...this.resolver.resolveAll(HOSTED_SERVICE_HEALTH)];
     const entries: HealthReportEntry[] = new Array(checks.length);
     const report = new AbortController();
     const timer = setTimeout(() => report.abort(new Error("Health report timed out.")), timeoutMs);

package/package.json

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

package/core/background/backgroundModule.ts

@@ -1,42 +0,0 @@
-import {
-  DI,
-  HOSTED_SERVICE,
-  Module,
-  singleton,
-  type Class,
-  type HostedService,
-  type BazisModule,
-  type ProviderDefinition,
-} from "../di";
-
-export interface BackgroundModuleConfig {
-  /**
-   * Background service classes (subclasses of `BackgroundService` /
-   * `PeriodicBackgroundService`). Each is registered as a singleton (with
-   * auto-resolved constructor dependencies) and exposed as a `HOSTED_SERVICE`,
-   * so the kernel starts and gracefully stops it with the rest of the app.
-   */
-  readonly services: readonly Class<HostedService>[];
-}
-
-/**
- * Registers background services in DI and wires them into the kernel lifecycle.
- *
- * ```ts
- * @Module({ imports: [backgroundModule({ services: [SessionCleanup, Heartbeat] })] })
- * class AppModule {}
- * ```
- */
-export function backgroundModule(config: BackgroundModuleConfig): BazisModule {
-  const providers: ProviderDefinition[] = config.services.flatMap((ServiceClass) => [
-    singleton(ServiceClass),
-    DI.singleton(
-      DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => resolver.resolve(ServiceClass)),
-    ),
-  ]);
-
-  @Module({ providers })
-  class BackgroundModule {}
-
-  return BackgroundModule;
-}