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

package/dist/admin/overview.schemas.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { IanaTimeZone } from "../time-zone.js";
+/** `GET /api/v1/admin/overview/usage`: the reader's zone; days are calendar days in it (spec §5.2). */
+export const UsageQuery = z.object({
+    tz: IanaTimeZone.describe("The IANA time zone the days are counted in (the reader's zone), such as Asia/Shanghai."),
+});
+/** The admin overview's routes (admin overview spec §5.2): reads, only usage takes input. */
+export const OVERVIEW_ROUTES = [
+    { route: "GET /api/v1/admin/overview" },
+    { route: "GET /api/v1/admin/overview/attention" },
+    { route: "GET /api/v1/admin/overview/health" },
+    { route: "GET /api/v1/admin/overview/usage", query: UsageQuery },
+];

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

@@ -0,0 +1,112 @@
+import type { LocalizedName, Logger } from "@capybara-hq/plugin-sdk";
+import { CatalogService } from "../catalog/catalog.service.js";
+import { MarketplacesService } from "../catalog/marketplaces.service.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import type { AdminExtensionView, DeploymentExtensionStatus } from "../extensions/permission-view.js";
+import { PluginIcons } from "../extensions/plugin-icons.js";
+import { AccountsService } from "../identity/accounts.js";
+import { PlatformInboxService } from "../inbox/platform-inbox.service.js";
+import { OrgsService } from "../orgs/orgs.service.js";
+import { ProviderRegistry, type ProviderStatus } from "../runtime/providers.js";
+/** The most rows each attention list returns; the rest are counted in `more`. */
+export declare const ATTENTION_LIST_MAX = 20;
+/** The admin overview's numbers (`GET /api/v1/admin/overview`): counts only. */
+export interface AdminOverviewStats {
+    orgs: number;
+    accounts: number;
+    /**
+     * What waits for a super admin: the platform inbox total plus the extensions, plugin updates and
+     * model providers of {@link AdminAttention} (each counted in full, not capped).
+     */
+    attentionTotal: number;
+    /** An attention source could not be read: `attentionTotal` leaves its items out. */
+    partial: boolean;
+}
+/**
+ * Why an extension needs a look (spec §5.2), from its status and `configValid`: `config` (missing
+ * or invalid deployment config), `load_failed`, `approval` (permissions wait for confirmation),
+ * `dependency`, `conflict`, `converging` (replicas disagree, or a migration waits) and
+ * `legacy_format`. Never the raw replica detail.
+ */
+export type AttentionExtensionReason = "config" | "load_failed" | "approval" | "dependency" | "conflict" | "converging" | "legacy_format";
+/** What is wrong with a model provider: its model list failed, or it lists no usable chat model. */
+export type AttentionProviderProblem = "list_failed" | "no_chat_model";
+/** An attention list a source failed to read (it is then empty, the others intact). */
+export type AttentionSource = "extensions" | "updates" | "providers";
+export interface AttentionExtension {
+    name: string;
+    displayName: LocalizedName | null;
+    icon: string | null;
+    status: DeploymentExtensionStatus;
+    reason: AttentionExtensionReason;
+}
+/** A platform plugin whose marketplace has a newer version than the newest imported one. */
+export interface AttentionUpdate {
+    itemId: string;
+    name: string;
+    displayName: LocalizedName | null;
+    icon: string | null;
+    /** The newest imported version. */
+    version: string;
+    marketplaceVersion: string;
+    marketplaceId: string | null;
+    /** The marketplace's name; null without a marketplace (or when it was deleted). */
+    marketplaceName: string | null;
+}
+export interface AttentionProvider {
+    /** The model provider (its extension's plugin name). */
+    plugin: string;
+    displayName: LocalizedName | null;
+    icon: string | null;
+    problem: AttentionProviderProblem;
+}
+/**
+ * `GET /api/v1/admin/overview/attention` (spec §5.2, §9): what needs a super admin besides the
+ * inbox, each list at most {@link ATTENTION_LIST_MAX} rows with the rest counted in `more`, and
+ * `unavailable` naming each source that could not be read. Reason categories only: never an error
+ * text, a replica detail or a config value.
+ */
+export interface AdminAttention {
+    extensions: AttentionExtension[];
+    updates: AttentionUpdate[];
+    providers: AttentionProvider[];
+    more: Record<AttentionSource, number>;
+    unavailable: AttentionSource[];
+}
+/** The reason an extension is listed, or null when it needs nothing. */
+export declare function extensionReason(e: Pick<AdminExtensionView, "status" | "configValid">): AttentionExtensionReason | null;
+/** The problem of a provider in the platform view, or null (`org_configured` is not one). */
+export declare function providerProblem(p: ProviderStatus): AttentionProviderProblem | null;
+/**
+ * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the
+ * sources the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached
+ * lists). Each source is read on its own: a failing one is reported in `unavailable`. Reads are not
+ * audited (decision D5) and not cached further (every source is PG or already Redis-cached).
+ */
+export declare class AdminOverviewService {
+    private readonly extensions;
+    private readonly catalog;
+    private readonly registry;
+    private readonly displayNames;
+    private readonly icons;
+    private readonly inbox;
+    private readonly orgs;
+    private readonly accounts;
+    private readonly marketplaces;
+    private readonly log;
+    constructor(extensions: ExtensionAdmin, catalog: CatalogService, registry: ProviderRegistry, displayNames: ExtensionDisplayNames, icons: PluginIcons, inbox: PlatformInboxService, orgs: OrgsService, accounts: AccountsService, marketplaces: MarketplacesService, log: Logger);
+    stats(): Promise<AdminOverviewStats>;
+    attention(): Promise<AdminAttention>;
+    /**
+     * The extensions needing a look, but not one pending approval whose plugin waits in the platform
+     * inbox (a permission confirmation or an org upload: the inbox already lists and counts it). A
+     * config-declared extension has no catalog item and stays. Without the catalog nothing is left out.
+     */
+    private extensionRows;
+    /** Every live catalog item, page by page (the catalog lists by name). */
+    private catalogItems;
+    /** Platform plugins with a newer marketplace version (org items are their org admins'). */
+    private updateRows;
+    private providerRows;
+}

package/dist/admin/overview.service.js

@@ -0,0 +1,223 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { CATALOG_LIST_MAX_LIMIT, CatalogService, } from "../catalog/catalog.service.js";
+import { MarketplacesService } from "../catalog/marketplaces.service.js";
+import { ExtensionAdmin } from "../extensions/admin-view.js";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { PluginIcons } from "../extensions/plugin-icons.js";
+import { AccountsService } from "../identity/accounts.js";
+import { PlatformInboxService } from "../inbox/platform-inbox.service.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { OrgsService } from "../orgs/orgs.service.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+/** The most rows each attention list returns; the rest are counted in `more`. */
+export const ATTENTION_LIST_MAX = 20;
+/** The reason an extension is listed, or null when it needs nothing. */
+export function extensionReason(e) {
+    switch (e.status) {
+        case "pending_config":
+            return "config";
+        case "failed":
+            return "load_failed";
+        case "pending_approval":
+            return "approval";
+        case "dependency":
+        case "conflict":
+        case "legacy_format":
+            return e.status;
+        case "converging":
+        case "pending_migration":
+            return "converging";
+        case "enabled":
+            return e.configValid ? null : "config";
+        case "disabled":
+            return null;
+    }
+}
+/** The problem of a provider in the platform view, or null (`org_configured` is not one). */
+export function providerProblem(p) {
+    if (p.status === "error")
+        return "list_failed";
+    if (p.status !== "ok")
+        return null;
+    return p.models.some((m) => m.kind === "chat" && m.disabled !== true) ? null : "no_chat_model";
+}
+/**
+ * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the
+ * sources the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached
+ * lists). Each source is read on its own: a failing one is reported in `unavailable`. Reads are not
+ * audited (decision D5) and not cached further (every source is PG or already Redis-cached).
+ */
+let AdminOverviewService = class AdminOverviewService {
+    extensions;
+    catalog;
+    registry;
+    displayNames;
+    icons;
+    inbox;
+    orgs;
+    accounts;
+    marketplaces;
+    log;
+    constructor(extensions, catalog, registry, displayNames, icons, inbox, orgs, accounts, marketplaces, log) {
+        this.extensions = extensions;
+        this.catalog = catalog;
+        this.registry = registry;
+        this.displayNames = displayNames;
+        this.icons = icons;
+        this.inbox = inbox;
+        this.orgs = orgs;
+        this.accounts = accounts;
+        this.marketplaces = marketplaces;
+        this.log = log;
+    }
+    async stats() {
+        const [orgs, accounts, inbox, attention] = await Promise.all([
+            this.orgs.listAll(),
+            this.accounts.count(),
+            this.inbox.count(),
+            this.attention(),
+        ]);
+        const listed = (s) => attention[s].length + attention.more[s];
+        return {
+            orgs: orgs.length,
+            accounts,
+            attentionTotal: inbox + listed("extensions") + listed("updates") + listed("providers"),
+            partial: attention.unavailable.length > 0,
+        };
+    }
+    async attention() {
+        // the catalog is read once: the update rows, and the plugins the inbox already lists
+        const items = this.catalogItems();
+        items.catch(() => { }); // awaited (and reported) by updateRows
+        const [extensions, updates, providers] = await Promise.allSettled([
+            this.extensionRows(items),
+            this.updateRows(items),
+            this.providerRows(),
+        ]);
+        const out = {
+            extensions: [],
+            updates: [],
+            providers: [],
+            more: { extensions: 0, updates: 0, providers: 0 },
+            unavailable: [],
+        };
+        /** The rows of a source that answered (capped), or none and its name in `unavailable`. */
+        const take = (source, r) => {
+            if (r.status === "rejected") {
+                // logged for the operator; the answer carries only the source's name (spec §9)
+                this.log.warn("admin overview: an attention source could not be read", {
+                    source,
+                    err: r.reason,
+                });
+                out.unavailable.push(source);
+                return [];
+            }
+            out.more[source] = Math.max(0, r.value.length - ATTENTION_LIST_MAX);
+            return r.value.slice(0, ATTENTION_LIST_MAX);
+        };
+        out.extensions = take("extensions", extensions);
+        out.updates = take("updates", updates);
+        out.providers = take("providers", providers);
+        return out;
+    }
+    /**
+     * The extensions needing a look, but not one pending approval whose plugin waits in the platform
+     * inbox (a permission confirmation or an org upload: the inbox already lists and counts it). A
+     * config-declared extension has no catalog item and stays. Without the catalog nothing is left out.
+     */
+    async extensionRows(items) {
+        const [views, catalog] = await Promise.all([this.extensions.list(), items.catch(() => [])]);
+        const inInbox = new Set(catalog.filter((i) => i.pending).map((i) => i.name));
+        return views.flatMap((v) => {
+            // every status of extensionNeedsAction has a reason, and so has enabled with an invalid config
+            const reason = extensionReason(v);
+            if (reason === null)
+                return [];
+            if (v.status === "pending_approval" && inInbox.has(v.name))
+                return [];
+            return [
+                {
+                    name: v.name,
+                    displayName: v.displayName,
+                    icon: v.icon ?? null,
+                    status: v.status,
+                    reason,
+                },
+            ];
+        });
+    }
+    /** Every live catalog item, page by page (the catalog lists by name). */
+    async catalogItems() {
+        const items = [];
+        let offset = 0;
+        while (offset !== null) {
+            const page = await this.catalog.page({ limit: CATALOG_LIST_MAX_LIMIT, offset });
+            items.push(...page.items);
+            offset = page.nextOffset;
+        }
+        return items;
+    }
+    /** Platform plugins with a newer marketplace version (org items are their org admins'). */
+    async updateRows(items) {
+        const newer = (await items).filter((i) => i.owner.kind === "platform" && i.newerInMarketplace && i.latestMarketplaceVersion !== null);
+        if (newer.length === 0)
+            return [];
+        const [icons, marketplaces] = await Promise.all([
+            this.icons.ofItems(newer.map((i) => i.id), { kind: "admin" }),
+            this.marketplaces.list(),
+        ]);
+        const names = new Map(marketplaces.map((m) => [m.id, m.name]));
+        return newer.map((i) => ({
+            itemId: i.id,
+            name: i.name,
+            displayName: i.displayName,
+            icon: icons.get(i.id) ?? null,
+            version: i.latestVersion,
+            marketplaceVersion: i.latestMarketplaceVersion,
+            marketplaceId: i.marketplaceId,
+            marketplaceName: i.marketplaceId === null ? null : (names.get(i.marketplaceId) ?? null),
+        }));
+    }
+    async providerRows() {
+        const problems = (await this.registry.listWithStatus()).flatMap((p) => {
+            const problem = providerProblem(p);
+            return problem === null ? [] : [{ plugin: p.plugin, problem }];
+        });
+        if (problems.length === 0)
+            return [];
+        const plugins = problems.map((p) => p.plugin);
+        const [names, icons] = await Promise.all([
+            this.displayNames.many(plugins),
+            this.icons.many(plugins, { kind: "admin" }),
+        ]);
+        return problems.map((p) => ({
+            plugin: p.plugin,
+            displayName: names.get(p.plugin) ?? null,
+            icon: icons.get(p.plugin) ?? null,
+            problem: p.problem,
+        }));
+    }
+};
+AdminOverviewService = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionAdmin)),
+    __param(1, Inject(CatalogService)),
+    __param(2, Inject(ProviderRegistry)),
+    __param(3, Inject(ExtensionDisplayNames)),
+    __param(4, Inject(PluginIcons)),
+    __param(5, Inject(PlatformInboxService)),
+    __param(6, Inject(OrgsService)),
+    __param(7, Inject(AccountsService)),
+    __param(8, Inject(MarketplacesService)),
+    __param(9, Inject(KERNEL_LOGGER))
+], AdminOverviewService);
+export { AdminOverviewService };

package/dist/admin/platform-audit.service.d.ts

@@ -0,0 +1,41 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * One platform-level audit event (admin overview spec §5.2, §9): who, what, on what and when, and
+ * two flags. Never the event's `detail` (it may carry config field names or ids); a deleted actor
+ * account reads as its id with a null name and email; `actor` is null for the kernel itself.
+ */
+export interface PlatformAuditEvent {
+    /** The event id (a bigserial, as a decimal string); also the keyset cursor. */
+    id: string;
+    at: string;
+    actor: {
+        id: string;
+        name: string | null;
+        email: string | null;
+    } | null;
+    /** Done with a personal access token. */
+    viaToken: boolean;
+    /** Done through the Platform tool by the actor's own agent (`detail.via === "agent"`). */
+    viaAgent: boolean;
+    /** The action; a legacy name is mapped through {@link LEGACY_AUDIT_ACTIONS}. */
+    action: string;
+    target: string | null;
+}
+/** A page of {@link PlatformAuditEvent}s; `next` is the `after` of the next page, null at the end. */
+export interface PlatformAuditPage {
+    events: PlatformAuditEvent[];
+    next: string | null;
+}
+/**
+ * Reads the platform-level audit log: events with no org (`org_id IS NULL`, decision D3), newest
+ * first by id, keyset paged (`audit_events_platform_idx`). Read-only and not audited (D5).
+ */
+export declare class PlatformAuditService {
+    private readonly kdb;
+    constructor(kdb: KernelDb);
+    /** `limit` events with an id below `after` (from the newest without it); one extra row tells `next`. */
+    list(q: {
+        after?: string | undefined;
+        limit: number;
+    }): Promise<PlatformAuditPage>;
+}

package/dist/admin/platform-audit.service.js

@@ -0,0 +1,70 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { LEGACY_AUDIT_ACTIONS } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * Reads the platform-level audit log: events with no org (`org_id IS NULL`, decision D3), newest
+ * first by id, keyset paged (`audit_events_platform_idx`). Read-only and not audited (D5).
+ */
+let PlatformAuditService = class PlatformAuditService {
+    kdb;
+    constructor(kdb) {
+        this.kdb = kdb;
+    }
+    /** `limit` events with an id below `after` (from the newest without it); one extra row tells `next`. */
+    async list(q) {
+        let query = this.kdb.db
+            .selectFrom("audit_events as a")
+            .leftJoin("accounts as ac", "ac.id", "a.actor_account_id")
+            .select([
+            "a.id",
+            "a.at",
+            "a.actor_account_id",
+            "a.actor_token_id",
+            "a.action",
+            "a.target",
+            "ac.display_name",
+            "ac.email",
+            // only the one flag the overview shows, never the whole detail (spec §9)
+            sql `a.detail->>'via'`.as("via"),
+        ])
+            .where("a.org_id", "is", null);
+        if (q.after !== undefined)
+            query = query.where("a.id", "<", q.after);
+        const rows = await query
+            .orderBy("a.id", "desc")
+            .limit(q.limit + 1)
+            .execute();
+        const events = rows.slice(0, q.limit).map((r) => ({
+            id: String(r.id),
+            at: r.at.toISOString(),
+            actor: r.actor_account_id === null
+                ? null
+                : {
+                    id: r.actor_account_id,
+                    name: r.display_name ?? null,
+                    email: r.email ?? null,
+                },
+            viaToken: r.actor_token_id !== null,
+            viaAgent: r.via === "agent",
+            action: LEGACY_AUDIT_ACTIONS[r.action] ?? r.action,
+            target: r.target,
+        }));
+        const next = rows.length > q.limit ? (events.at(-1)?.id ?? null) : null;
+        return { events, next };
+    }
+};
+PlatformAuditService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], PlatformAuditService);
+export { PlatformAuditService };

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

@@ -0,0 +1,149 @@
+import { SettingsService } from "../identity/settings.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { PricesService } from "../models/prices.js";
+/** Seam token of the kernel's own tests: a shorter statement timeout and a fixed clock. */
+export declare const ADMIN_USAGE_TIMINGS: unique symbol;
+export interface AdminUsageTimings {
+    /** The aggregate's `statement_timeout` in milliseconds (default 10 000). */
+    statementTimeoutMs: number;
+    /** The clock "today" is read from (default `Date.now`). */
+    now: () => number;
+}
+/** Days in the window: today and the 6 days before. */
+export declare const USAGE_WINDOW_DAYS = 7;
+/** Orgs listed by name; the rest are summed in `otherOrgs`. */
+export declare const USAGE_TOP_ORGS = 10;
+/** Seconds one computed week stays cached (shared by every replica, Redis). */
+export declare const USAGE_CACHE_TTL = 300;
+/** Tokens of one day; the four chat kinds do not overlap (plugin-sdk `ModelUsage`). */
+export interface UsageTokens {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** Input tokens of `ctx.models.embed` calls (`model_usage`). */
+    embedding: number;
+}
+/** One calendar day in the requested time zone. */
+export interface UsageDay {
+    /** `YYYY-MM-DD` in the answer's `tz`. */
+    date: string;
+    /** Runs created that day (every run: sub-agent and eval replay runs included, D6). */
+    runs: number;
+    tokens: UsageTokens;
+    /**
+     * Estimated cost in `currency` of the priced tokens; null when the day used tokens and none of
+     * them had a price (0 for a day with no tokens).
+     */
+    cost: number | null;
+}
+/** One org's week: totals only (never per account, agent or conversation; spec §9). */
+export interface UsageOrg {
+    orgId: string;
+    /** The org's name (its id when the org row is gone). */
+    name: string;
+    runs: number;
+    /** Every token kind summed, embeddings included. */
+    tokens: number;
+    /** As {@link UsageDay.cost}, over the org's week. */
+    cost: number | null;
+}
+/**
+ * `AdminUsageService.week(tz)` (admin overview spec §4.3, §5.2): the platform's runs, tokens and
+ * estimated cost per calendar day in `tz` over today and the 6 days before, and the 10 orgs that
+ * used the most tokens (the rest summed in `otherOrgs`).
+ */
+export interface AdminUsageWeek {
+    /** Start of the first day in `tz` (ISO 8601, UTC). */
+    from: string;
+    /** End of today in `tz`, exclusive (ISO 8601, UTC). */
+    to: string;
+    tz: string;
+    /** The deployment setting `priceCurrency`. */
+    currency: string;
+    /** Exactly 7 days, oldest first, today last; days without usage are zeros. */
+    days: UsageDay[];
+    /** Some tokens of the week had no price: the costs count only the priced ones. */
+    costPartial: boolean;
+    /** At most 10, by total tokens descending (then runs, then id). */
+    orgs: UsageOrg[];
+    /** The orgs with usage outside the top 10, summed; `count` 0 when there are none. */
+    otherOrgs: {
+        count: number;
+        runs: number;
+        tokens: number;
+        cost: number | null;
+    };
+}
+/** `YYYY-MM-DD` of `at` in `tz`. */
+export declare function dateIn(tz: string, at: number): string;
+/** The calendar date `days` after `date` (`YYYY-MM-DD`; date arithmetic, no time zone involved). */
+export declare function addDays(date: string, days: number): string;
+interface TokenRow {
+    day: string;
+    org_id: string;
+    provider: string;
+    model: string;
+    input: string;
+    output: string;
+    cache_read: string;
+    cache_write: string;
+}
+interface RunRow {
+    day: string;
+    org_id: string;
+    runs: string;
+}
+interface EmbeddingRow {
+    day: string;
+    org_id: string;
+    provider: string;
+    model: string;
+    input: string;
+}
+/**
+ * The admin overview's usage block (spec §4.3, §5.2, §5.4). Three grouped queries over a bounded
+ * window (`conversation_events_usage_idx`, `runs_created_idx`, `model_usage_time_idx`) in one
+ * read-only transaction with a statement timeout; priced here with the model price table. The
+ * answer is cached in Redis for 300 s per time zone and first day, so every replica serves the
+ * same answer and a zone is recomputed at most once per 5 minutes (prices or currency changed in
+ * between show after the TTL). Aggregates only: no account, agent or conversation, no content.
+ */
+export declare class AdminUsageService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    readonly cacheService: CacheService;
+    private readonly prices;
+    private readonly settings;
+    private readonly statementTimeoutMs;
+    private readonly now;
+    constructor(db: KernelDb, txHost: TransactionHost, cacheService: CacheService, prices: Pick<PricesService, "table">, settings: Pick<SettingsService, "get">, timings?: Partial<AdminUsageTimings>);
+    /**
+     * The week ending today in `tz` (an IANA zone the caller validated, `IanaTimeZone`; normalized to
+     * its canonical spelling, which the answer echoes and the cache key holds). Throws
+     * `admin.usage_unavailable` (503) when the aggregate ran past its statement timeout, and
+     * `validation_failed` (400) for a zone PG does not know.
+     *
+     * Never call it inside a transaction: it leaves the caller's context on purpose (inside one,
+     * `@Cacheable` would be bypassed and the read-only transaction would hold a second connection).
+     */
+    week(tz: string): Promise<AdminUsageWeek>;
+    /** The cache key holds the zone and the first day: a new day starts a new entry. */
+    protected cachedWeek(tz: string, firstDay: string): Promise<AdminUsageWeek>;
+    /** The window's queries, in their own read-only transaction (the timeout must not leak into a caller's). */
+    protected aggregate(tz: string, firstDay: string): Promise<AdminUsageWeek>;
+}
+/**
+ * The three grouped queries over `[from, to)` (spec §5.4), each on its time index:
+ * `conversation_events_usage_idx`, `runs_created_idx`, `model_usage_time_idx`. Rows are bounded by
+ * days × orgs (× models), not by events. Days are calendar days in `tz` (`YYYY-MM-DD` text, so no
+ * driver turns them into local-time dates).
+ */
+export declare function usageQueries(tz: string, from: Date, to: Date): {
+    tokens: import("kysely").RawBuilder<TokenRow>;
+    runs: import("kysely").RawBuilder<RunRow>;
+    embeddings: import("kysely").RawBuilder<EmbeddingRow>;
+};
+export {};