@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,163 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { type HookRegistry } from "../extensions/hooks.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;
+/** Maintenance job of the sweeper (no `:`), its scheduler id and period. */
+export declare const USAGE_SWEEP_JOB = "usage-report-sweep";
+export declare const USAGE_SWEEP_SCHEDULER_ID = "usage-report-sweep-every";
+export declare const USAGE_SWEEP_EVERY_MS = 60000;
+/** The sweep leaves the newest events to the fast path (and to transactions still committing). */
+export declare const USAGE_SWEEP_LAG_MS = 30000;
+/**
+ * Each sweep re-scans this far behind the watermark: events whose transaction committed after a
+ * previous sweep passed their `created_at` are still found. Far inside the dedupe window
+ * (`hooks.usageReportKeepHours` ≥ 1 h), so re-enqueued events dedupe on the kept job.
+ */
+export declare const USAGE_SWEEP_OVERLAP_MS: number;
+export interface UsageReporterDeps {
+    db: KernelDb;
+    redisUrl: string;
+    /**
+     * The host's registry: handlers of the current local plugin generations (through inflight.run), and
+     * `has("usage.report")`, the in-process check that lets `enqueue` skip all I/O without handlers.
+     */
+    hooks: Pick<HookRegistry, "handlers" | "has">;
+    /**
+     * Whether the plugin's current instance is active on this replica (I-2): an active instance that
+     * registered no `usage.report` handler is not a subscriber, and its target is dropped. Absent: never.
+     */
+    isActive?(plugin: string): boolean;
+    /**
+     * Of these plugins, the ones no replica can serve right now (I-2): replicas report them (live
+     * `extension_replica_status` rows) and none has them loaded. Their targets are dropped at once instead
+     * of failing every attempt. See {@link queryUnservable}. Absent: none.
+     */
+    unservable?(plugins: readonly string[]): Promise<Set<string>>;
+    /**
+     * Plugins that subscribe to `usage.report`, from deployment state (approved manifests in PG), not from this replica's loaded handlers. With `orgId`: only those the
+     * organization enabled. See {@link queryUsageSubscribers}.
+     */
+    subscribers(orgId?: string): Promise<Set<string>>;
+    config: () => KernelConfig;
+    log: Logger;
+    /** Tests: retry policy (defaults {@link USAGE_REPORT_ATTEMPTS} / {@link USAGE_REPORT_BACKOFF_MS}). */
+    retry?: {
+        attempts: number;
+        backoffMs: 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: KernelDb, 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
+ * `loaded` or still serves an older version (`serving_version`, e.g. an upgrade pending approval), and
+ * the rows are not all `unloaded` (that is the state right after a re-enable, before the replicas
+ * reconcile). A plugin with no live row at all is unknown too (slow to load, or a host without a
+ * status store). Unknown plugins are never listed.
+ */
+export declare function queryUnservable(db: KernelDb, plugins: readonly string[], staleSeconds: number): Promise<Set<string>>;
+/**
+ * The next `pending` set (m-2 fence): plugins that failed now, narrowed to what the stored job data
+ * still lists. A plugin another (stalled-over) execution already delivered never comes back.
+ */
+export declare function narrowPending(stored: readonly string[] | undefined, failed: readonly string[]): string[];
+/**
+ * Reliable `usage.report` delivery (F11, P-17, R13). Every `usage` event written to the event log (chat
+ * runs and full-run eval replays) is delivered at least once to every subscribing plugin.
+ * - **Fast path:** `model-call` enqueues job `usage-<conversationId>-<seq>` right after writing the event
+ *   (never awaited; an enqueue failure only logs). Skipped without I/O when this replica has no
+ *   `usage.report` handler (M-2); the sweeper then offers the event.
+ * - **Sweeper (R13):** a maintenance job (once across replicas, every minute) re-enqueues the `usage`
+ *   events in `[watermark - 10 min, now - 30 s]` with the same job ids, so a lost fast-path enqueue is
+ *   caught up and duplicates dedupe on the kept job (`hooks.usageReportKeepHours`).
+ * - **Worker** (worker role, `hooks.usageReportConcurrency` per replica): reads the payload from the log
+ *   at execution time (the `usage` event, the conversation with `kind`, the run). On the first attempt
+ *   the targets are the deployment's subscribers the organization enabled (I-2: not this replica's
+ *   handlers), written into `pending`; plugins run concurrently (`allSettled`); failed ones stay in
+ *   `pending` and are retried (5 retries, 2 s doubling). A plugin not loaded on this replica (or
+ *   between generations) is a failure, so another replica or a later attempt delivers it. On the
+ *   last attempt it is dropped only when it is definitely unservable ({@link queryUnservable});
+ *   otherwise the job fails as usual. A plugin loaded here that registered no handler is dropped at
+ *   once (I-2). A drop (N-3) is never silent: after delivering to the other targets the job ends
+ *   failed with an `UnrecoverableError` whose failedReason names the dropped plugins, plus a
+ *   throttled warning. Plugins the organization disabled by delivery time are dropped silently (not
+ *   targets any more). The final failure logs an error (no audit); failed jobs are kept 7 days, at
+ *   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,
+ * as are conversation title calls (`purpose: "title"`, no run: `runId` is "").
+ * Single-step eval replays and judge requests log no usage: not reported (M7).
+ */
+export declare class UsageReporter {
+    private readonly d;
+    private queue;
+    private queueConn;
+    private worker;
+    private workerConn;
+    private closed;
+    private readonly stopping;
+    constructor(d: UsageReporterDeps);
+    private jobOpts;
+    /**
+     * Enqueues the delivery of one `usage` event. Returns without a job when no plugin subscribes.
+     * Never throws: an enqueue failure (e.g. a Redis hiccup) only logs a warning; the sweeper catches up.
+     */
+    enqueue(conversationId: string, seq: number): Promise<void>;
+    /**
+     * 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(opts?: {
+        now?: number;
+    }): Promise<number>;
+    /** Starts the worker (worker role only). Job lock and stalled detection follow the run queue. */
+    startWorker(): void;
+    /** Stops the worker (in-flight calls are aborted, their jobs requeued) and the queue. */
+    stop(): Promise<void>;
+    private getQueue;
+    /** The payload of one usage event, read from the log; null when the event no longer exists. */
+    private payloadOf;
+    /**
+     * Writes the next `pending` set and the accumulated drops, fenced against a concurrent
+     * (stalled-over) execution (m-2 fence): only plugins the stored data still lists as pending or
+     * dropped can stay, so a plugin another execution delivered never comes back.
+     */
+    private writePending;
+    private process;
+    /** {@link UsageReporterDeps.unservable}; a lookup failure counts as "unknown" (keep retrying). */
+    private unservable;
+    /** Logs a warning at most once per plugin and kind per minute (Redis key with a TTL). */
+    private warnOnce;
+    /** One handler call with its own signal (timeout or replica stop aborts it); rejects on either. */
+    private call;
+}