@capybara-hq/kernel 0.1.0-rc.19 → 0.1.0-rc.20

package/dist/admin/admin.module.js

@@ -5,18 +5,64 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { CatalogModule } from "../catalog/catalog.module.js";
+import { ChannelsModule } from "../channels/channels.module.js";
+import { TitlesModule } from "../conversations/titles.js";
+import { EvalsModule } from "../evals/evals.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { IdentityModule } from "../identity/identity.module.js";
+import { InboxModule } from "../inbox/inbox.module.js";
+import { ModelsModule } from "../models/models.module.js";
 import { OrgsModule } from "../orgs/orgs.module.js";
+import { ProvidersModule } from "../runtime/providers.js";
+import { RunJobsModule } from "../runtime/run-jobs.js";
+import { UsageReportJobsModule } from "../runtime/usage-report-jobs.js";
+import { AdminHealthService } from "./health.service.js";
+import { AdminOverviewService } from "./overview.service.js";
+import { PlatformAuditService } from "./platform-audit.service.js";
 import { SetupService } from "./setup.service.js";
 import { SetupLockModule } from "./setup-lock.js";
-/** Deployment administration: the setup wizard (its controllers are the api role's, `ApiModule`). */
+import { AdminUsageService } from "./usage.service.js";
+/**
+ * Deployment administration: the setup wizard, the platform-level audit log and the admin overview
+ * with its health read and seven-day usage aggregate (its controllers are the api role's, `ApiModule`).
+ */
 let AdminModule = class AdminModule {
 };
 AdminModule = __decorate([
     Module({
-        imports: [IdentityModule, OrgsModule, SetupLockModule],
-        providers: [SetupService],
-        exports: [SetupService],
+        imports: [
+            IdentityModule,
+            OrgsModule,
+            SetupLockModule,
+            ExtensionsModule,
+            CatalogModule,
+            ProvidersModule,
+            InboxModule,
+            // the kernel queues the health overview counts, as their owners register them (shared
+            // instances: no queue connection of its own)
+            RunJobsModule,
+            ChannelsModule,
+            TitlesModule,
+            UsageReportJobsModule,
+            EvalsModule,
+            // the price table of the usage aggregate
+            ModelsModule,
+        ],
+        providers: [
+            SetupService,
+            PlatformAuditService,
+            AdminOverviewService,
+            AdminHealthService,
+            AdminUsageService,
+        ],
+        exports: [
+            SetupService,
+            PlatformAuditService,
+            AdminOverviewService,
+            AdminHealthService,
+            AdminUsageService,
+        ],
     })
 ], AdminModule);
 export { AdminModule };

package/dist/admin/admin.schemas.d.ts

@@ -62,4 +62,8 @@ export declare const DeploymentSettingsBody: z.ZodObject<{
 export declare const PurposeParams: z.ZodObject<{
     purpose: z.ZodString;
 }, z.core.$strip>;
+/** `:orgId` of an admin route: any org, the super admin need not be a member. */
+export declare const AdminOrgParams: z.ZodObject<{
+    orgId: z.ZodString;
+}, z.core.$strip>;
 export declare const ADMIN_ROUTES: readonly RouteSchemas[];

package/dist/admin/admin.schemas.js

@@ -25,8 +25,9 @@ export const UpdateAccountBody = z.object({
 /** At least one key; `runConcurrencyOverrides` merges by org, a null value drops that org's. */
 export const DeploymentSettingsBody = DEPLOYMENT_SETTINGS_PATCH.refine((b) => Object.keys(b).length > 0, { message: "at least one setting is required" });
 export const PurposeParams = z.object({ purpose: z.string().min(1).max(100) });
+/** `:orgId` of an admin route: any org, the super admin need not be a member. */
+export const AdminOrgParams = z.object({ orgId: z.string().min(1).max(100) });
 export const ADMIN_ROUTES = [
-    { route: "GET /api/v1/admin/overview" },
     { route: "GET /api/v1/admin/accounts", query: AccountListQuery },
     { route: "POST /api/v1/admin/accounts", body: CreateAccountBody },
     {
@@ -35,6 +36,8 @@ export const ADMIN_ROUTES = [
         body: UpdateAccountBody,
     },
     { route: "GET /api/v1/admin/orgs" },
+    // `:orgId` is the conversation's org for the operation, so never an operation field
+    { route: "GET /api/v1/admin/orgs/:orgId/members" },
     { route: "GET /api/v1/admin/settings" },
     { route: "PUT /api/v1/admin/settings", body: DeploymentSettingsBody },
     { route: "GET /api/v1/admin/models" },

package/dist/admin/audit.controller.d.ts

@@ -0,0 +1,14 @@
+import type { z } from "zod";
+import { AuditListQuery } from "./audit.schemas.js";
+import { type PlatformAuditPage, PlatformAuditService } from "./platform-audit.service.js";
+/**
+ * The platform-level audit log (`GET /api/v1/admin/audit`, admin overview spec §5.2, decision D2):
+ * events with no org, newest first, keyset paged; never an event's `detail`. Super admins only;
+ * the read itself is not audited (D5).
+ */
+export declare class AdminAuditController {
+    private readonly audit;
+    constructor(audit: PlatformAuditService);
+    /** `next` is the `after` of the next page, null at the end. */
+    list(q: z.infer<typeof AuditListQuery>): Promise<PlatformAuditPage>;
+}

package/dist/admin/audit.controller.js

@@ -0,0 +1,42 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Inject } from "@nestjs/common";
+import { SuperAdmin } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZQuery } from "../infra/validation/zod-params.js";
+import { AuditListQuery } from "./audit.schemas.js";
+import { PlatformAuditService } from "./platform-audit.service.js";
+class AuditListQueryDto extends createZodDto(AuditListQuery, "AuditListQuery") {
+}
+/**
+ * The platform-level audit log (`GET /api/v1/admin/audit`, admin overview spec §5.2, decision D2):
+ * events with no org, newest first, keyset paged; never an event's `detail`. Super admins only;
+ * the read itself is not audited (D5).
+ */
+let AdminAuditController = class AdminAuditController {
+    audit;
+    constructor(audit) {
+        this.audit = audit;
+    }
+    /** `next` is the `after` of the next page, null at the end. */
+    list(q) {
+        return this.audit.list(q);
+    }
+};
+__decorate([
+    Get(),
+    __param(0, ZQuery(AuditListQueryDto))
+], AdminAuditController.prototype, "list", null);
+AdminAuditController = __decorate([
+    Controller("api/v1/admin/audit"),
+    SuperAdmin(),
+    __param(0, Inject(PlatformAuditService))
+], AdminAuditController);
+export { AdminAuditController };

package/dist/admin/audit.schemas.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `GET /api/v1/admin/audit`: keyset paging by event id, newest first (admin overview spec §5.2). */
+export declare const AuditListQuery: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const AUDIT_ROUTES: readonly RouteSchemas[];

package/dist/admin/audit.schemas.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/** The largest `bigserial` id; a larger `after` would make PG refuse the comparison. */
+const MAX_BIGINT = 9223372036854775807n;
+/** `GET /api/v1/admin/audit`: keyset paging by event id, newest first (admin overview spec §5.2). */
+export const AuditListQuery = z.object({
+    after: z
+        .string()
+        .regex(/^\d{1,19}$/, "after must be an event id (digits)")
+        // checks do not abort: only digits reach BigInt
+        .refine((v) => !/^\d{1,19}$/.test(v) || BigInt(v) <= MAX_BIGINT, "after must be an event id")
+        .optional()
+        .describe("The id of the last event of the previous page (its next); absent: the newest."),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export const AUDIT_ROUTES = [
+    { route: "GET /api/v1/admin/audit", query: AuditListQuery },
+];

package/dist/admin/health.service.d.ts

@@ -0,0 +1,104 @@
+import type { Queue } from "bullmq";
+import type { Redis } from "ioredis";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type LiveReplica, ReplicaPresence } from "../infra/presence/replica-presence.js";
+import type { KernelLogger } from "../log.js";
+/** The kernel's own queues, in the order the overview lists them (extension queues are not read). */
+export declare const KERNEL_QUEUE_NAMES: readonly ["cap-kernel-runs", "cap-kernel-subagent-runs", "cap-kernel-channels", "cap-kernel-maintenance", "cap-kernel-plugin-scope", "cap-kernel-titles", "cap-kernel-usage-report", "cap-kernel-evals"];
+/** How long each source's reads may take before the answer marks it unavailable. */
+export declare const HEALTH_READ_TIMEOUT_MS = 3000;
+/** A live replica as the overview shows it. */
+export interface AdminHealthReplica {
+    /** The process id (the one extension status rows and the gateway heartbeat use). */
+    id: string;
+    roles: LiveReplica["roles"];
+    version: string;
+    startedAt: string;
+    httpReplicaId: string | null;
+}
+/** One kernel queue: counts only, never job data or a failure text (spec §9). */
+export interface AdminHealthQueue {
+    name: (typeof KERNEL_QUEUE_NAMES)[number];
+    /** Waiting to be picked up (a paused queue keeps them here too), prioritized ones included. */
+    waiting: number;
+    active: number;
+    /** Delayed: scheduled for later, or waiting out a retry backoff. */
+    delayed: number;
+    /** Failed jobs still kept (each queue keeps the last 5000). */
+    failed: number;
+    /** Of those, the ones that failed in the last 24 hours (by `finishedOn`). */
+    failedLastDay: number;
+}
+/** A source the answer could not read right now (its numbers are null). */
+export type AdminHealthSource = "redis" | "database";
+/**
+ * The admin overview's 运行状况 (`GET /api/v1/admin/overview/health`, admin overview spec §5.2,
+ * §6.2). Each source degrades on its own: when Redis does not answer, `replicas`, `roles`,
+ * `queues`, `channels.online` / `.offline` and `devices.online` are null; when PostgreSQL does
+ * not, the channel, device and sandbox numbers read from it are null; `unavailable` names them.
+ */
+export interface AdminHealth {
+    kernel: {
+        version: string;
+    };
+    /** Live replicas (presence beat within its window), oldest start first. */
+    replicas: AdminHealthReplica[] | null;
+    /** Live replicas per role (a replica with several roles counts in each). */
+    roles: {
+        api: number;
+        worker: number;
+        gateway: number;
+    } | null;
+    queues: AdminHealthQueue[] | null;
+    /**
+     * Channel connections of orgs not deleted (deleted connections are not counted):
+     * - `online`: long connections held by a live gateway replica now (the replicas' own counts);
+     * - `offline`: active long-connection connections no replica holds (`max(0, active − online)`):
+     *   waiting for a gateway, backing off after a failure, or their plugin is off in the org;
+     * - `webhook`: active connections in webhook mode (callbacks, nothing to hold);
+     * - `disabled` / `error`: connections in that status, whatever their mode.
+     */
+    channels: {
+        online: number | null;
+        offline: number | null;
+        webhook: number | null;
+        disabled: number | null;
+        error: number | null;
+    };
+    /**
+     * `local`: local devices (not deleted, org not deleted); `online`: the devices whose connection a
+     * live replica holds (lease held), at most `local`.
+     */
+    devices: {
+        online: number | null;
+        local: number | null;
+    };
+    /** Sandbox instances by status, and running ones per provider (most first). */
+    sandboxes: {
+        running: number;
+        suspended: number;
+        byProvider: {
+            provider: string;
+            running: number;
+        }[];
+    } | null;
+    unavailable: AdminHealthSource[];
+}
+/**
+ * Reads the platform's health for the admin overview: the live replicas (replica presence), the
+ * kernel queues (BullMQ counts plus a ZCOUNT of each failed set over the last 24 hours, the set's
+ * score being `finishedOn`), and channel, device and sandbox counts (grouped PostgreSQL counts,
+ * plus the connections the live replicas report holding). Not cached: it is cheap, and stale health
+ * misleads. Reads the shared queue instances (no connection per request).
+ */
+export declare class AdminHealthService {
+    private readonly presence;
+    private readonly db;
+    private readonly redis;
+    private readonly log;
+    private readonly queues;
+    constructor(presence: Pick<ReplicaPresence, "live">, db: KernelDb, redis: Pick<Redis, "zcount" | "status">, log: Pick<KernelLogger, "warn">, runs: Queue, subagentRuns: Queue, channels: Queue, maintenance: Queue, pluginScope: Queue, titles: Queue, usageReport: Queue, evals: Queue);
+    read(): Promise<AdminHealth>;
+    private readRedis;
+    private readDb;
+}

package/dist/admin/health.service.js

@@ -0,0 +1,246 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { getQueueToken } from "@nestjs/bullmq";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { PLUGIN_SCOPE_QUEUE } from "../catalog/scope-sync.js";
+import { CHANNEL_QUEUE_NAME } from "../channels/jobs.js";
+import { TITLE_QUEUE } from "../conversations/titles.js";
+import { EVAL_QUEUE_NAME } from "../evals/jobs.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ReplicaPresence } from "../infra/presence/replica-presence.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { RUN_QUEUE_NAME, SUBAGENT_RUN_QUEUE_NAME } from "../runtime/run-jobs.js";
+import { USAGE_REPORT_QUEUE } from "../runtime/usage-report-jobs.js";
+import { KERNEL_VERSION } from "../version.js";
+/** The kernel's own queues, in the order the overview lists them (extension queues are not read). */
+export const KERNEL_QUEUE_NAMES = [
+    RUN_QUEUE_NAME,
+    SUBAGENT_RUN_QUEUE_NAME,
+    CHANNEL_QUEUE_NAME,
+    MAINTENANCE_QUEUE_NAME,
+    PLUGIN_SCOPE_QUEUE,
+    TITLE_QUEUE,
+    USAGE_REPORT_QUEUE,
+    EVAL_QUEUE_NAME,
+];
+/** How long each source's reads may take before the answer marks it unavailable. */
+export const HEALTH_READ_TIMEOUT_MS = 3_000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Rejects when `p` does not settle within `ms` (a down Redis makes commands wait, not fail). */
+function within(p, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no answer within ${ms} ms`)), ms);
+        timer.unref?.();
+    });
+    p.catch(() => { }); // a late rejection after the timeout is not unhandled
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Reads the platform's health for the admin overview: the live replicas (replica presence), the
+ * kernel queues (BullMQ counts plus a ZCOUNT of each failed set over the last 24 hours, the set's
+ * score being `finishedOn`), and channel, device and sandbox counts (grouped PostgreSQL counts,
+ * plus the connections the live replicas report holding). Not cached: it is cheap, and stale health
+ * misleads. Reads the shared queue instances (no connection per request).
+ */
+let AdminHealthService = class AdminHealthService {
+    presence;
+    db;
+    redis;
+    log;
+    queues;
+    constructor(presence, db, redis, log, runs, subagentRuns, channels, maintenance, pluginScope, titles, usageReport, evals) {
+        this.presence = presence;
+        this.db = db;
+        this.redis = redis;
+        this.log = log;
+        // the order of KERNEL_QUEUE_NAMES
+        this.queues = [
+            runs,
+            subagentRuns,
+            channels,
+            maintenance,
+            pluginScope,
+            titles,
+            usageReport,
+            evals,
+        ];
+    }
+    async read() {
+        const [r, d] = await Promise.allSettled([
+            within(this.readRedis(), HEALTH_READ_TIMEOUT_MS),
+            // a query left running past the limit finishes on its pooled connection
+            within(this.readDb(), HEALTH_READ_TIMEOUT_MS),
+        ]);
+        const unavailable = [];
+        const redis = r.status === "fulfilled" ? r.value : null;
+        if (r.status === "rejected") {
+            unavailable.push("redis");
+            this.log.warn("admin health: cannot read Redis", { err: r.reason });
+        }
+        const db = d.status === "fulfilled" ? d.value : null;
+        if (d.status === "rejected") {
+            unavailable.push("database");
+            this.log.warn("admin health: cannot read the database", { err: d.reason });
+        }
+        const replicas = redis?.replicas ?? null;
+        const sum = (k) => replicas === null ? null : replicas.reduce((n, x) => n + x[k], 0);
+        const online = sum("channelsHeld");
+        const channelCount = (f) => db === null ? null : db.channels.filter(f).reduce((n, c) => n + c.n, 0);
+        const longActive = channelCount((c) => c.status === "active" && c.mode === "long_connection");
+        // Each replica counts only the devices whose lease it holds, so a device is online on at most
+        // one; the clamp covers a lease handover in flight and devices deleted while still connected
+        const connected = sum("devicesConnected");
+        const devicesOnline = connected === null || db === null ? connected : Math.min(connected, db.localDevices);
+        let sandboxes = null;
+        if (db !== null) {
+            const byProvider = new Map();
+            let running = 0;
+            let suspended = 0;
+            for (const i of db.instances) {
+                if (i.status === "suspended")
+                    suspended += i.n;
+                if (i.status !== "running")
+                    continue;
+                running += i.n;
+                if (i.provider !== null) {
+                    byProvider.set(i.provider, (byProvider.get(i.provider) ?? 0) + i.n);
+                }
+            }
+            sandboxes = {
+                running,
+                suspended,
+                byProvider: [...byProvider]
+                    .map(([provider, n]) => ({ provider, running: n }))
+                    .sort((a, b) => b.running - a.running || a.provider.localeCompare(b.provider)),
+            };
+        }
+        return {
+            kernel: { version: KERNEL_VERSION },
+            replicas: replicas?.map((x) => ({
+                id: x.id,
+                roles: x.roles,
+                version: x.version,
+                startedAt: x.startedAt,
+                httpReplicaId: x.httpReplicaId,
+            })) ?? null,
+            roles: replicas === null
+                ? null
+                : {
+                    api: replicas.filter((x) => x.roles.includes("api")).length,
+                    worker: replicas.filter((x) => x.roles.includes("worker")).length,
+                    gateway: replicas.filter((x) => x.roles.includes("gateway")).length,
+                },
+            queues: redis?.queues ?? null,
+            channels: {
+                online,
+                offline: online === null || longActive === null ? null : Math.max(0, longActive - online),
+                webhook: channelCount((c) => c.status === "active" && c.mode === "webhook"),
+                disabled: channelCount((c) => c.status === "disabled"),
+                error: channelCount((c) => c.status === "error"),
+            },
+            devices: { online: devicesOnline, local: db?.localDevices ?? null },
+            sandboxes,
+            unavailable,
+        };
+    }
+    async readRedis() {
+        // Fail fast while a connection is down: ioredis queues commands until it reconnects (the
+        // BullMQ connections retry forever, maxRetriesPerRequest null), so with the page polling every
+        // 30 s the reads would pile up in the offline queues instead of reporting Redis unavailable
+        if (this.redis.status !== "ready")
+            throw new Error(`redis is ${this.redis.status}`);
+        for (const q of this.queues) {
+            const status = (await q.getBackend().client).status;
+            if (status !== "ready")
+                throw new Error(`queue ${q.name} connection is ${status}`);
+        }
+        const since = Date.now() - DAY_MS;
+        const [replicas, queues] = await Promise.all([
+            this.presence.live(),
+            Promise.all(this.queues.map(async (q, i) => {
+                const [c, failedLastDay] = await Promise.all([
+                    q.getJobCounts("wait", "prioritized", "active", "delayed", "failed"),
+                    // the failed set is scored by finishedOn (pinned by the health test)
+                    this.redis.zcount(q.toKey("failed"), since, "+inf"),
+                ]);
+                return {
+                    name: KERNEL_QUEUE_NAMES[i],
+                    waiting: (c.wait ?? 0) + (c.prioritized ?? 0),
+                    active: c.active ?? 0,
+                    delayed: c.delayed ?? 0,
+                    failed: c.failed ?? 0,
+                    failedLastDay,
+                };
+            })),
+        ]);
+        return { replicas, queues };
+    }
+    async readDb() {
+        const db = this.db.db;
+        const [channels, devices, instances] = await Promise.all([
+            db
+                .selectFrom("channel_connections as c")
+                .innerJoin("orgs as o", "o.id", "c.org_id")
+                .select(["c.status as status", "c.inbound_mode as mode"])
+                .select(sql `count(*)`.as("n"))
+                .where("c.deleted_at", "is", null)
+                .where("o.deleted_at", "is", null)
+                .groupBy(["c.status", "c.inbound_mode"])
+                .execute(),
+            db
+                .selectFrom("devices as d")
+                .innerJoin("orgs as o", "o.id", "d.org_id")
+                .select(sql `count(*)`.as("n"))
+                .where("d.source", "=", "local")
+                .where("d.deleted_at", "is", null)
+                .where("o.deleted_at", "is", null)
+                .executeTakeFirst(),
+            // the partial indexes on device_instances (running / live) serve these statuses; an
+            // instance of a deleted org is left out like its channels and devices
+            db
+                .selectFrom("device_instances as i")
+                .innerJoin("orgs as o", "o.id", "i.org_id")
+                .select(["i.provider as provider", "i.status as status"])
+                .select(sql `count(*)`.as("n"))
+                .where("i.status", "in", ["running", "suspended"])
+                .where("o.deleted_at", "is", null)
+                .groupBy(["i.provider", "i.status"])
+                .execute(),
+        ]);
+        return {
+            channels: channels.map((c) => ({ status: c.status, mode: c.mode, n: Number(c.n) })),
+            localDevices: Number(devices?.n ?? 0),
+            instances: instances.map((i) => ({
+                provider: i.provider,
+                status: i.status,
+                n: Number(i.n),
+            })),
+        };
+    }
+};
+AdminHealthService = __decorate([
+    Injectable(),
+    __param(0, Inject(ReplicaPresence)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(REDIS)),
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Inject(getQueueToken(RUN_QUEUE_NAME))),
+    __param(5, Inject(getQueueToken(SUBAGENT_RUN_QUEUE_NAME))),
+    __param(6, Inject(getQueueToken(CHANNEL_QUEUE_NAME))),
+    __param(7, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(8, Inject(getQueueToken(PLUGIN_SCOPE_QUEUE))),
+    __param(9, Inject(getQueueToken(TITLE_QUEUE))),
+    __param(10, Inject(getQueueToken(USAGE_REPORT_QUEUE))),
+    __param(11, Inject(getQueueToken(EVAL_QUEUE_NAME)))
+], AdminHealthService);
+export { AdminHealthService };

package/dist/admin/overview.controller.d.ts

@@ -0,0 +1,31 @@
+import type { z } from "zod";
+import { type AdminHealth, AdminHealthService } from "./health.service.js";
+import { UsageQuery } from "./overview.schemas.js";
+import { type AdminAttention, AdminOverviewService, type AdminOverviewStats } from "./overview.service.js";
+import { AdminUsageService, type AdminUsageWeek } from "./usage.service.js";
+/**
+ * The admin console overview (`/api/v1/admin/overview*`, admin overview spec §5.2): one read per
+ * block, each failing on its own. Super admins only; service tokens 403; reads are not audited
+ * (decision D5).
+ */
+export declare class AdminOverviewController {
+    private readonly overview;
+    private readonly health;
+    private readonly usage;
+    constructor(overview: AdminOverviewService, health: AdminHealthService, usage: AdminUsageService);
+    /** The numbers: orgs, accounts and everything waiting for a super admin. */
+    stats(): Promise<AdminOverviewStats>;
+    /** Extensions, plugin updates and model providers needing a look (reason categories only). */
+    attention(): Promise<AdminAttention>;
+    /**
+     * How the platform runs: live replicas by role, kernel queue counts, channel, device and sandbox
+     * counts. Not cached; a source that does not answer is named in `unavailable`.
+     */
+    readHealth(): Promise<AdminHealth>;
+    /**
+     * Runs, tokens and estimated cost per calendar day in `tz` over today and the 6 days before,
+     * and the top 10 orgs. Cached 300 s (Redis, every replica); a timeout is
+     * `admin.usage_unavailable` (503).
+     */
+    readUsage(q: z.infer<typeof UsageQuery>): Promise<AdminUsageWeek>;
+}

package/dist/admin/overview.controller.js

@@ -0,0 +1,78 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Inject } from "@nestjs/common";
+import { SuperAdmin } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZQuery } from "../infra/validation/zod-params.js";
+import { AdminHealthService } from "./health.service.js";
+import { UsageQuery } from "./overview.schemas.js";
+import { AdminOverviewService, } from "./overview.service.js";
+import { AdminUsageService } from "./usage.service.js";
+class UsageQueryDto extends createZodDto(UsageQuery, "AdminUsageQuery") {
+}
+/**
+ * The admin console overview (`/api/v1/admin/overview*`, admin overview spec §5.2): one read per
+ * block, each failing on its own. Super admins only; service tokens 403; reads are not audited
+ * (decision D5).
+ */
+let AdminOverviewController = class AdminOverviewController {
+    overview;
+    health;
+    usage;
+    constructor(overview, health, usage) {
+        this.overview = overview;
+        this.health = health;
+        this.usage = usage;
+    }
+    /** The numbers: orgs, accounts and everything waiting for a super admin. */
+    stats() {
+        return this.overview.stats();
+    }
+    /** Extensions, plugin updates and model providers needing a look (reason categories only). */
+    attention() {
+        return this.overview.attention();
+    }
+    /**
+     * How the platform runs: live replicas by role, kernel queue counts, channel, device and sandbox
+     * counts. Not cached; a source that does not answer is named in `unavailable`.
+     */
+    readHealth() {
+        return this.health.read();
+    }
+    /**
+     * Runs, tokens and estimated cost per calendar day in `tz` over today and the 6 days before,
+     * and the top 10 orgs. Cached 300 s (Redis, every replica); a timeout is
+     * `admin.usage_unavailable` (503).
+     */
+    readUsage(q) {
+        return this.usage.week(q.tz);
+    }
+};
+__decorate([
+    Get()
+], AdminOverviewController.prototype, "stats", null);
+__decorate([
+    Get("attention")
+], AdminOverviewController.prototype, "attention", null);
+__decorate([
+    Get("health")
+], AdminOverviewController.prototype, "readHealth", null);
+__decorate([
+    Get("usage"),
+    __param(0, ZQuery(UsageQueryDto))
+], AdminOverviewController.prototype, "readUsage", null);
+AdminOverviewController = __decorate([
+    Controller("api/v1/admin/overview"),
+    SuperAdmin(),
+    __param(0, Inject(AdminOverviewService)),
+    __param(1, Inject(AdminHealthService)),
+    __param(2, Inject(AdminUsageService))
+], AdminOverviewController);
+export { AdminOverviewController };

package/dist/admin/overview.schemas.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `GET /api/v1/admin/overview/usage`: the reader's zone; days are calendar days in it (spec §5.2). */
+export declare const UsageQuery: z.ZodObject<{
+    tz: z.ZodString;
+}, z.core.$strip>;
+/** The admin overview's routes (admin overview spec §5.2): reads, only usage takes input. */
+export declare const OVERVIEW_ROUTES: readonly RouteSchemas[];