@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.6

package/dist/runtime/usage-report-jobs.d.ts

@@ -0,0 +1,88 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type OnApplicationShutdown } from "@nestjs/common";
+import type { JobsOptions, Queue } from "bullmq";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+/**
+ * The producer half of `usage.report` delivery for `model_usage` rows, and the queue's ids and job
+ * options shared with the reporter (`usage-report.ts`). The `ctx.models` broker sits below the
+ * extension host and must not register a queue there (CLI contexts that build the extensions
+ * module never connect to Redis eagerly), so it only announces a row (`model_usage.recorded`) and
+ * {@link ModelUsageJobs} enqueues it here.
+ */
+/** Queue of `usage.report` deliveries (no `:` in the name). */
+export declare const USAGE_REPORT_QUEUE = "cap-kernel-usage-report";
+/** The job name of every delivery. */
+export declare const USAGE_REPORT_JOB = "usage-report";
+/** One job per `usage` event (no `:`: conversation ids are UUIDs, seq is a number). */
+export declare const usageReportJobId: (conversationId: string, seq: number) => string;
+/** One job per `model_usage` row (spec B §5.4; row ids are UUIDs, so no clash with the above). */
+export declare const modelUsageJobId: (usageId: string) => string;
+/**
+ * Job data: ids only (the payload is read when the job runs): a conversation `usage` event
+ * (`conversationId` + `seq`), or a `model_usage` row (`usageId`).
+ */
+export type UsageReportJob = ({
+    conversationId: string;
+    seq: number;
+    usageId?: undefined;
+} | {
+    usageId: string;
+    conversationId?: undefined;
+    seq?: undefined;
+}) & {
+    /** Plugins not yet succeeded; absent = every subscriber (decided on the first attempt). */
+    pending?: string[];
+    /**
+     * Targets dropped so far (plugin → why), accumulated across attempts (m-2): when the job would
+     * otherwise complete it fails naming them, and `pending` is then exactly these plugins, so a
+     * manual retry reaches only them (m-1). A later delivery to one of them removes it.
+     */
+    dropped?: Record<string, string>;
+};
+/** First attempt plus 5 retries (F11). */
+export declare const USAGE_REPORT_ATTEMPTS = 6;
+/** Retry backoff: 2 s, doubling (2, 4, 8, 16, 32 s). */
+export declare const USAGE_REPORT_BACKOFF_MS = 2000;
+/** The delivery retry policy: attempts and the first exponential backoff. */
+export interface UsageReportRetry {
+    attempts: number;
+    backoffMs: number;
+}
+/** Optional provider: the {@link UsageReportRetry} instead of the defaults above (tests). */
+export declare const USAGE_REPORT_RETRY: unique symbol;
+/** The options of one delivery job: its id, the retry policy and the retention of finished jobs. */
+export declare function usageReportJobOpts(jobId: string, retry: UsageReportRetry, keepHours: number): JobsOptions;
+/**
+ * Plugins that subscribe to `usage.report` according to deployment state: an approved permission
+ * snapshot that declares the `usage.report` hook, for a plugin the deployment still knows: an enabled
+ * install, or a config-declared plugin with a replica status row that is not `unloaded`. With `orgId`, only plugins
+ * the organization enabled (org config rows and required bootstrap plugins).
+ */
+export declare function queryUsageSubscribers(db: KernelSchemaDb, orgId?: string): Promise<Set<string>>;
+/**
+ * Enqueues the `usage.report` delivery of `model_usage` rows on `model_usage.recorded` (fast path;
+ * the reporter's sweep re-enqueues rows still unreported, so a lost event or enqueue is caught up).
+ */
+export declare class ModelUsageJobs implements OnApplicationShutdown {
+    private readonly kdb;
+    private readonly queue;
+    private readonly config;
+    private readonly log;
+    private readonly retry;
+    private readonly unsubscribe;
+    /** Set at shutdown: a late event enqueues nothing (the sweep offers the row later). */
+    private closed;
+    constructor(kdb: KernelDb, queue: Queue<UsageReportJob>, config: Pick<KernelConfigService, "get">, log: Logger, retry: UsageReportRetry | undefined, events: KernelEvents);
+    onApplicationShutdown(): void;
+    /**
+     * Enqueues the delivery of one row (job `usage-model-<rowId>`). Without any subscriber nothing is
+     * enqueued (the sweep marks the row). Never throws: a failure only logs; the sweep catches up.
+     */
+    enqueue(usageId: string): Promise<void>;
+}
+/** The usage report queue and its `model_usage` producer (no dependency on the extension host). */
+export declare class UsageReportJobsModule {
+}

package/dist/runtime/usage-report-jobs.js

@@ -0,0 +1,158 @@
+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, Module, Optional } from "@nestjs/common";
+import { sql } from "kysely";
+import { enabledExtensionsQuery } from "../extensions/enabled.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+/**
+ * The producer half of `usage.report` delivery for `model_usage` rows, and the queue's ids and job
+ * options shared with the reporter (`usage-report.ts`). The `ctx.models` broker sits below the
+ * extension host and must not register a queue there (CLI contexts that build the extensions
+ * module never connect to Redis eagerly), so it only announces a row (`model_usage.recorded`) and
+ * {@link ModelUsageJobs} enqueues it here.
+ */
+/** Queue of `usage.report` deliveries (no `:` in the name). */
+export const USAGE_REPORT_QUEUE = "cap-kernel-usage-report";
+/** The job name of every delivery. */
+export const USAGE_REPORT_JOB = "usage-report";
+/** One job per `usage` event (no `:`: conversation ids are UUIDs, seq is a number). */
+export const usageReportJobId = (conversationId, seq) => `usage-${conversationId}-${seq}`;
+/** One job per `model_usage` row (spec B §5.4; row ids are UUIDs, so no clash with the above). */
+export const modelUsageJobId = (usageId) => `usage-model-${usageId}`;
+/** First attempt plus 5 retries (F11). */
+export const USAGE_REPORT_ATTEMPTS = 6;
+/** Retry backoff: 2 s, doubling (2, 4, 8, 16, 32 s). */
+export const USAGE_REPORT_BACKOFF_MS = 2000;
+/** Optional provider: the {@link UsageReportRetry} instead of the defaults above (tests). */
+export const USAGE_REPORT_RETRY = Symbol("USAGE_REPORT_RETRY");
+/** Failed jobs (given up) are kept for inspection, at most {@link KEEP_FAILED_MAX} of them. */
+const KEEP_FAILED_S = 7 * 86_400;
+/** Upper bound on kept failed jobs (I-2): a long outage of a billing endpoint cannot grow Redis. */
+const KEEP_FAILED_MAX = 100_000;
+/**
+ * Upper bound on kept finished jobs (Redis memory). At the default retention it only bites above
+ * ~1.1 usage events per second sustained for a day; dedupe needs the jobs only for the sweeper overlap.
+ */
+const KEEP_COMPLETED_MAX = 100_000;
+/** The options of one delivery job: its id, the retry policy and the retention of finished jobs. */
+export function usageReportJobOpts(jobId, retry, keepHours) {
+    return {
+        jobId,
+        attempts: retry.attempts,
+        backoff: { type: "exponential", delay: retry.backoffMs },
+        removeOnComplete: { age: keepHours * 3600, count: KEEP_COMPLETED_MAX },
+        removeOnFail: { age: KEEP_FAILED_S, count: KEEP_FAILED_MAX },
+    };
+}
+/**
+ * Plugins that subscribe to `usage.report` according to deployment state: an approved permission
+ * snapshot that declares the `usage.report` hook, for a plugin the deployment still knows: an enabled
+ * install, or a config-declared plugin with a replica status row that is not `unloaded`. With `orgId`, only plugins
+ * the organization enabled (org config rows and required bootstrap plugins).
+ */
+export async function queryUsageSubscribers(db, orgId) {
+    let q = db
+        .selectFrom("extension_permission_snapshots as s")
+        .select("s.plugin")
+        .where(sql `s.permissions -> 'permissions' -> 'hooks' ? 'usage.report'`)
+        .where((eb) => eb.or([
+        eb.exists(eb
+            .selectFrom("extension_installs as i")
+            .select(sql `1`.as("one"))
+            .whereRef("i.name", "=", "s.plugin")
+            .where("i.desired_state", "=", "enabled")),
+        // config-declared plugins still declared (and not unloaded) on some replica; installs are
+        // covered by desired_state above (their replica rows linger as `unloaded` when disabled)
+        eb.exists(eb
+            .selectFrom("extension_replica_status as r")
+            .select(sql `1`.as("one"))
+            .whereRef("r.plugin", "=", "s.plugin")
+            .where("r.source", "=", "config")
+            .where("r.state", "<>", "unloaded")),
+    ]));
+    if (orgId !== undefined) {
+        q = q.where("s.plugin", "in", enabledExtensionsQuery(db, orgId));
+    }
+    return new Set((await q.execute()).map((r) => r.plugin));
+}
+/**
+ * Enqueues the `usage.report` delivery of `model_usage` rows on `model_usage.recorded` (fast path;
+ * the reporter's sweep re-enqueues rows still unreported, so a lost event or enqueue is caught up).
+ */
+let ModelUsageJobs = class ModelUsageJobs {
+    kdb;
+    queue;
+    config;
+    log;
+    retry;
+    unsubscribe;
+    /** Set at shutdown: a late event enqueues nothing (the sweep offers the row later). */
+    closed = false;
+    constructor(kdb, queue, config, log, retry = {
+        attempts: USAGE_REPORT_ATTEMPTS,
+        backoffMs: USAGE_REPORT_BACKOFF_MS,
+    }, events) {
+        this.kdb = kdb;
+        this.queue = queue;
+        this.config = config;
+        this.log = log;
+        this.retry = retry;
+        this.unsubscribe = events.on("model_usage.recorded", ({ id }) => this.enqueue(id));
+    }
+    onApplicationShutdown() {
+        this.closed = true;
+        this.unsubscribe();
+    }
+    /**
+     * Enqueues the delivery of one row (job `usage-model-<rowId>`). Without any subscriber nothing is
+     * enqueued (the sweep marks the row). Never throws: a failure only logs; the sweep catches up.
+     */
+    async enqueue(usageId) {
+        if (this.closed)
+            return;
+        try {
+            if ((await queryUsageSubscribers(this.kdb.db)).size === 0)
+                return;
+            await this.queue.add(USAGE_REPORT_JOB, { usageId }, usageReportJobOpts(modelUsageJobId(usageId), this.retry, this.config.get().hooks.usageReportKeepHours));
+        }
+        catch (err) {
+            this.log.warn("cannot enqueue model usage report", { usageId, err });
+        }
+    }
+};
+ModelUsageJobs = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(getQueueToken(USAGE_REPORT_QUEUE))),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Optional()),
+    __param(4, Inject(USAGE_REPORT_RETRY)),
+    __param(5, Inject(KernelEvents))
+], ModelUsageJobs);
+export { ModelUsageJobs };
+/** The usage report queue's registration, shared by the producer and the reporter's module. */
+const USAGE_REPORT_QUEUE_MODULE = QueueModule.registerQueue(USAGE_REPORT_QUEUE);
+/** The usage report queue and its `model_usage` producer (no dependency on the extension host). */
+let UsageReportJobsModule = class UsageReportJobsModule {
+};
+UsageReportJobsModule = __decorate([
+    Module({
+        imports: [USAGE_REPORT_QUEUE_MODULE],
+        providers: [ModelUsageJobs],
+        exports: [ModelUsageJobs, USAGE_REPORT_QUEUE_MODULE],
+    })
+], UsageReportJobsModule);
+export { UsageReportJobsModule };

package/dist/runtime/usage-report.d.ts

@@ -6,34 +6,8 @@ import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import type { KernelLogger } from "../log.js";
-/** Queue of `usage.report` deliveries (no `:` in the name). */
-export declare const USAGE_REPORT_QUEUE = "cap-kernel-usage-report";
-/** One job per `usage` event (no `:`: conversation ids are UUIDs, seq is a number). */
-export declare const usageReportJobId: (conversationId: string, seq: number) => string;
-/** Job data: ids only (the payload is read from the event log when the job runs). */
-export interface UsageReportJob {
-    conversationId: string;
-    seq: number;
-    /** Plugins not yet succeeded; absent = every subscriber (decided on the first attempt). */
-    pending?: string[];
-    /**
-     * Targets dropped so far (plugin → why), accumulated across attempts (m-2): when the job would
-     * otherwise complete it fails naming them, and `pending` is then exactly these plugins, so a
-     * manual retry reaches only them (m-1). A later delivery to one of them removes it.
-     */
-    dropped?: Record<string, string>;
-}
-/** First attempt plus 5 retries (F11). */
-export declare const USAGE_REPORT_ATTEMPTS = 6;
-/** Retry backoff: 2 s, doubling (2, 4, 8, 16, 32 s). */
-export declare const USAGE_REPORT_BACKOFF_MS = 2000;
-/** The delivery retry policy of {@link UsageReporter}: attempts and the first exponential backoff. */
-export interface UsageReportRetry {
-    attempts: number;
-    backoffMs: number;
-}
-/** Optional provider: the {@link UsageReportRetry} instead of the defaults above (tests). */
-export declare const USAGE_REPORT_RETRY: unique symbol;
+import { type UsageReportJob, type UsageReportRetry } from "./usage-report-jobs.js";
+export { ModelUsageJobs, modelUsageJobId, queryUsageSubscribers, USAGE_REPORT_ATTEMPTS, USAGE_REPORT_BACKOFF_MS, USAGE_REPORT_QUEUE, USAGE_REPORT_RETRY, type UsageReportJob, UsageReportJobsModule, type UsageReportRetry, usageReportJobId, } from "./usage-report-jobs.js";
 /** The sweeper's cron job name (no `:`; every minute, once across replicas). */
 export declare const USAGE_SWEEP_JOB = "usage-report-sweep";
 /** The maintenance scheduler the sweep ran on before it became a `@LockedCron` (retired). */
@@ -46,13 +20,6 @@ export declare const USAGE_SWEEP_LAG_MS = 30000;
  * (`hooks.usageReportKeepHours` ≥ 1 h), so re-enqueued events dedupe on the kept job.
  */
 export declare const USAGE_SWEEP_OVERLAP_MS: number;
-/**
- * Plugins that subscribe to `usage.report` according to deployment state: an approved permission
- * snapshot that declares the `usage.report` hook, for a plugin the deployment still knows: an enabled
- * install, or a config-declared plugin with a replica status row that is not `unloaded`. With `orgId`, only plugins
- * the organization enabled (org config rows and required bootstrap plugins).
- */
-export declare function queryUsageSubscribers(db: KernelSchemaDb, orgId?: string): Promise<Set<string>>;
 /**
  * Of `plugins`, those that are **definitely** unservable right now (I-2, N-3): live replicas report
  * them (a `extension_replica_status` row with a heartbeat newer than `staleSeconds`), no live row is
@@ -91,11 +58,18 @@ export declare function narrowPending(stored: readonly string[] | undefined, fai
  *   most 100 000. Each call runs through the instance's `inflight.run`, limited by `hooks.timeoutMs`;
  *   when this replica stops, in-flight calls are aborted and the job goes back to the queue without
  *   using up an attempt.
- * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`). Nothing is written to the event
- * log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
+ * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`, or a `model_usage` row id).
+ * Nothing is written to the event log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
  * as are conversation title calls (`purpose: "title"`, no run: `runId` is "") and `WebFetch`
  * extraction calls (`purpose: "web_fetch"`).
  * Single-step eval replays and judge requests log no usage: not reported (M7).
+ * - **Model usage outside conversations** (spec B §5.4): each `ctx.models.embed` call writes a
+ *   `model_usage` row; on its `model_usage.recorded` event `ModelUsageJobs` (`usage-report-jobs.ts`)
+ *   enqueues job `usage-model-<rowId>` (only while some plugin subscribes); the payload
+ *   (`purpose: "embedding"`, `eventId` = the row id, the calling `extension`, no conversation fields)
+ *   is read from the row when the job runs, and the row's `reported_at` is set once nothing is left
+ *   to deliver; a job that gives up after its last attempt sets `report_failed_at`. The sweep
+ *   re-enqueues recent rows that are neither (see {@link sweep}).
  */
 export declare class UsageReporter {
     private readonly kdb;
@@ -151,11 +125,21 @@ export declare class UsageReporter {
     /**
      * One sweep (R13): re-enqueues the `usage` events created in `[watermark - overlap, now - lag]` in
      * pages, then advances the watermark to `now - lag`. With no subscriber it only advances. The first
-     * sweep starts at `now - lag - overlap`. Returns the number of events offered to the queue.
+     * sweep starts at `now - lag - overlap`. Also re-enqueues the `model_usage` rows of the same
+     * window that are neither reported nor given up (spec B §5.4),
+     * or, with no subscriber, marks those rows reported (nobody to deliver to). Returns the number of
+     * events and rows offered to the queue.
      */
     sweep(opts?: {
         now?: number;
     }): Promise<number>;
+    /**
+     * The `model_usage` half of {@link sweep}: rows neither reported nor given up that occurred in
+     * the same window as the events (`[watermark - overlap, to]`), oldest first. Bounded like the
+     * event sweep, so a row whose job failed for good is never offered again, even after its failed
+     * job left Redis (no repeated backlog, no second delivery to plugins already served).
+     */
+    private sweepModelUsage;
     /**
      * Starts consuming (worker role only): `worker` is the `@Processor` worker of
      * {@link USAGE_REPORT_QUEUE} (built with the run queue's job lock and stalled detection).
@@ -170,6 +154,17 @@ export declare class UsageReporter {
      * closes. The queue itself closes with the application.
      */
     stop(): Promise<void>;
+    /** The payload of a job: a `usage` event's or a `model_usage` row's; null when it is gone. */
+    private payloadOfJob;
+    /**
+     * The payload of one `model_usage` row (spec B §5.4): purpose `embedding`, the calling extension,
+     * no conversation fields; `eventId` is the row id. Null when the row no longer exists.
+     */
+    private payloadOfUsage;
+    /** A `model_usage` job is done (delivered, or nothing left to deliver to): marks the row. */
+    private markReported;
+    /** A `model_usage` job gave up after its last attempt: the sweep never offers the row again. */
+    private markFailed;
     /** The payload of one usage event, read from the log; null when the event no longer exists. */
     private payloadOf;
     /**