@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

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,10 +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,
- * as are conversation title calls (`purpose: "title"`, no run: `runId` is "").
+ * 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;
@@ -150,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).
@@ -169,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;
     /**

package/dist/runtime/usage-report.js

@@ -9,40 +9,22 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable, Module, Optional } from "@nestjs/common";
-import { DelayedError, Job, UnrecoverableError, } from "bullmq";
+import { DelayedError, Job, UnrecoverableError } from "bullmq";
 import { sql } from "kysely";
-import { enabledExtensionsQuery } from "../extensions/enabled.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
-import { deepFreeze, errMsg } from "../extensions/hooks.js";
+import { deepFreeze, errMsg, HookNeedsConfigError, } from "../extensions/hooks.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { STALE_RECONCILE_PERIODS } from "../extensions/lifecycle-topics.js";
 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 { QueueModule } from "../infra/queue/queue.module.js";
 import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
-/** Queue of `usage.report` deliveries (no `:` in the name). */
-export const USAGE_REPORT_QUEUE = "cap-kernel-usage-report";
-/** One job per `usage` event (no `:`: conversation ids are UUIDs, seq is a number). */
-export const usageReportJobId = (conversationId, seq) => `usage-${conversationId}-${seq}`;
-/** 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;
+import { deliveryRowOfChildRun } from "./subagents/child.js";
+import { modelUsageJobId, queryUsageSubscribers, USAGE_REPORT_ATTEMPTS, USAGE_REPORT_BACKOFF_MS, USAGE_REPORT_JOB, USAGE_REPORT_QUEUE, USAGE_REPORT_RETRY, UsageReportJobsModule, usageReportJobId, usageReportJobOpts, } from "./usage-report-jobs.js";
+export { ModelUsageJobs, modelUsageJobId, queryUsageSubscribers, USAGE_REPORT_ATTEMPTS, USAGE_REPORT_BACKOFF_MS, USAGE_REPORT_QUEUE, USAGE_REPORT_RETRY, UsageReportJobsModule, usageReportJobId, } from "./usage-report-jobs.js";
 /** Warnings about a plugin that cannot take deliveries are logged at most once per this window. */
 const WARN_WINDOW_MS = 60_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 sweeper's cron job name (no `:`; every minute, once across replicas). */
 export const USAGE_SWEEP_JOB = "usage-report-sweep";
 /** The maintenance scheduler the sweep ran on before it became a `@LockedCron` (retired). */
@@ -56,38 +38,6 @@ export const USAGE_SWEEP_LAG_MS = 30_000;
  */
 export const USAGE_SWEEP_OVERLAP_MS = 10 * 60_000;
 const SWEEP_PAGE = 500;
-const JOB = "usage-report";
-/**
- * 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));
-}
 /**
  * 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
@@ -127,6 +77,10 @@ class Undeliverable extends Error {
         this.name = "Undeliverable";
     }
 }
+/** A job's identity: its `usage` event or its `model_usage` row. */
+const keyOf = (d) => d.usageId !== undefined
+    ? { usageId: d.usageId }
+    : { conversationId: d.conversationId, seq: d.seq };
 /**
  * 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.
@@ -158,10 +112,18 @@ export function narrowPending(stored, failed) {
  *   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 "").
+ * 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}).
  */
 let UsageReporter = class UsageReporter {
     kdb;
@@ -224,17 +186,8 @@ let UsageReporter = class UsageReporter {
     subscribers(orgId) {
         return queryUsageSubscribers(this.db, orgId);
     }
-    jobOpts(conversationId, seq) {
-        return {
-            jobId: usageReportJobId(conversationId, seq),
-            attempts: this.retry.attempts,
-            backoff: { type: "exponential", delay: this.retry.backoffMs },
-            removeOnComplete: {
-                age: this.config.get().hooks.usageReportKeepHours * 3600,
-                count: KEEP_COMPLETED_MAX,
-            },
-            removeOnFail: { age: KEEP_FAILED_S, count: KEEP_FAILED_MAX },
-        };
+    jobOpts(jobId) {
+        return usageReportJobOpts(jobId, this.retry, this.config.get().hooks.usageReportKeepHours);
     }
     /**
      * Enqueues the delivery of one `usage` event. Returns without a job when no plugin subscribes.
@@ -250,7 +203,7 @@ let UsageReporter = class UsageReporter {
         try {
             if ((await this.subscribers()).size === 0)
                 return;
-            await this.queue.add(JOB, { conversationId, seq }, this.jobOpts(conversationId, seq));
+            await this.queue.add(USAGE_REPORT_JOB, { conversationId, seq }, this.jobOpts(usageReportJobId(conversationId, seq)));
         }
         catch (err) {
             this.log.warn("cannot enqueue usage report", { conversationId, seq, err });
@@ -259,7 +212,10 @@ let UsageReporter = 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.
      */
     async sweep(opts = {}) {
         // bounds and keyset as full-precision timestamp text (microseconds), computed with the DB clock
@@ -276,7 +232,8 @@ let UsageReporter = class UsageReporter {
             .executeTakeFirst();
         const watermark = row?.watermark ?? to;
         let offered = 0;
-        if ((await this.subscribers()).size > 0) {
+        const subscribed = (await this.subscribers()).size > 0;
+        if (subscribed) {
             let after;
             for (;;) {
                 let q = this.db
@@ -296,9 +253,9 @@ let UsageReporter = class UsageReporter {
                     .execute();
                 if (page.length > 0) {
                     await this.queue.addBulk(page.map((r) => ({
-                        name: JOB,
+                        name: USAGE_REPORT_JOB,
                         data: { conversationId: r.conversation_id, seq: Number(r.seq) },
-                        opts: this.jobOpts(r.conversation_id, Number(r.seq)),
+                        opts: this.jobOpts(usageReportJobId(r.conversation_id, Number(r.seq))),
                     })));
                     offered += page.length;
                 }
@@ -308,6 +265,7 @@ let UsageReporter = class UsageReporter {
                 after = { at: last.at, conv: last.conversation_id, seq: String(last.seq) };
             }
         }
+        offered += await this.sweepModelUsage(watermark, to, subscribed);
         await this.db
             .insertInto("usage_report_sweep")
             .values({ id: 1, watermark: sql `${to}::timestamptz` })
@@ -318,6 +276,51 @@ let UsageReporter = class UsageReporter {
             .execute();
         return offered;
     }
+    /**
+     * 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).
+     */
+    async sweepModelUsage(watermark, to, subscribed) {
+        if (!subscribed) {
+            await this.db
+                .updateTable("model_usage")
+                .set({ reported_at: sql `now()` })
+                .where("reported_at", "is", null)
+                .where(sql `occurred_at <= ${to}::timestamptz`)
+                .execute();
+            return 0;
+        }
+        let offered = 0;
+        let after;
+        for (;;) {
+            let q = this.db
+                .selectFrom("model_usage")
+                .select(["id", sql `occurred_at::text`.as("at")])
+                .where("reported_at", "is", null)
+                .where("report_failed_at", "is", null)
+                .where(sql `occurred_at >= ${watermark}::timestamptz - make_interval(secs => ${USAGE_SWEEP_OVERLAP_MS / 1000})`)
+                .where(sql `occurred_at <= ${to}::timestamptz`);
+            if (after) {
+                q = q.where(sql `(occurred_at, id) > (${after.at}::timestamptz, ${after.id}::uuid)`);
+            }
+            const page = await q.orderBy("occurred_at").orderBy("id").limit(SWEEP_PAGE).execute();
+            if (page.length > 0) {
+                await this.queue.addBulk(page.map((r) => ({
+                    name: USAGE_REPORT_JOB,
+                    data: { usageId: r.id },
+                    opts: this.jobOpts(modelUsageJobId(r.id)),
+                })));
+                offered += page.length;
+            }
+            const last = page.at(-1);
+            if (!last || page.length < SWEEP_PAGE)
+                break;
+            after = { at: last.at, id: last.id };
+        }
+        return offered;
+    }
     /**
      * 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).
@@ -342,14 +345,17 @@ let UsageReporter = class UsageReporter {
         const final = j.attemptsMade >= (j.opts.attempts ?? 1);
         const fields = {
             jobId: j.id,
-            conversationId: j.data.conversationId,
-            seq: j.data.seq,
+            ...(j.data.usageId !== undefined
+                ? { usageId: j.data.usageId }
+                : { conversationId: j.data.conversationId, seq: j.data.seq }),
             pending: j.data.pending,
             attempt: j.attemptsMade,
             error: err.message,
         };
-        if (final)
+        if (final) {
             this.log.error("usage report given up after retries", fields);
+            void this.markFailed(j.data);
+        }
         else
             this.log.warn("usage report attempt failed; retrying", fields);
     }
@@ -364,14 +370,73 @@ let UsageReporter = class UsageReporter {
         this.worker = undefined;
         await w?.close().catch(() => { });
     }
+    /** The payload of a job: a `usage` event's or a `model_usage` row's; null when it is gone. */
+    payloadOfJob(data) {
+        return data.usageId !== undefined
+            ? this.payloadOfUsage(data.usageId)
+            : this.payloadOf(data.conversationId, data.seq);
+    }
+    /**
+     * 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.
+     */
+    async payloadOfUsage(id) {
+        const row = await this.db
+            .selectFrom("model_usage")
+            .select(["id", "org_id", "extension", "provider", "model", "input_tokens", "occurred_at"])
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        return {
+            eventId: row.id,
+            purpose: "embedding",
+            orgId: row.org_id,
+            extension: row.extension,
+            provider: row.provider,
+            model: row.model,
+            usage: {
+                inputTokens: row.input_tokens,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                cacheWriteTokens: 0,
+            },
+            occurredAt: new Date(row.occurred_at).toISOString(),
+        };
+    }
+    /** A `model_usage` job is done (delivered, or nothing left to deliver to): marks the row. */
+    async markReported(data) {
+        if (data.usageId === undefined)
+            return;
+        await this.db
+            .updateTable("model_usage")
+            .set({ reported_at: sql `now()` })
+            .where("id", "=", data.usageId)
+            .where("reported_at", "is", null)
+            .execute();
+    }
+    /** A `model_usage` job gave up after its last attempt: the sweep never offers the row again. */
+    async markFailed(data) {
+        if (data.usageId === undefined)
+            return;
+        try {
+            await this.db
+                .updateTable("model_usage")
+                .set({ report_failed_at: sql `now()` })
+                .where("id", "=", data.usageId)
+                .where("reported_at", "is", null)
+                .execute();
+        }
+        catch (err) {
+            this.log.warn("cannot mark a model usage report as given up", { usageId: data.usageId, err });
+        }
+    }
     /** The payload of one usage event, read from the log; null when the event no longer exists. */
     async payloadOf(conversationId, seq) {
         const row = await this.db
             .selectFrom("conversation_events as e")
             .innerJoin("conversations as c", "c.id", "e.conversation_id")
             .leftJoin("runs as r", "r.id", "e.run_id")
-            // a sub-agent's run: its dispatch says where it was dispatched from (spec §11)
-            .leftJoin("subagent_dispatches as sd", "sd.child_run_id", "e.run_id")
             .select([
             "e.payload",
             "e.run_id",
@@ -382,9 +447,6 @@ let UsageReporter = class UsageReporter {
             "c.account_id",
             "c.kind",
             "r.trigger_account_id",
-            "sd.parent_conversation_id",
-            "sd.parent_run_id",
-            "sd.parent_call_id",
         ])
             .where("e.conversation_id", "=", conversationId)
             .where("e.seq", "=", String(seq))
@@ -392,6 +454,11 @@ let UsageReporter = class UsageReporter {
         if (row?.type !== "usage")
             return null;
         const p = row.payload;
+        // a sub-agent's run: where it was dispatched from (spec §11), its own dispatch, else (a wake
+        // run nobody dispatched, agent map spec §5.3) its conversation's latest one
+        const parent = row.kind === "subagent" && row.run_id !== null
+            ? await deliveryRowOfChildRun(this.db, row.run_id)
+            : null;
         return {
             eventId: `${conversationId}/${seq}`,
             purpose: p.purpose ?? "step",
@@ -402,13 +469,11 @@ let UsageReporter = class UsageReporter {
             // a sub-agent's calls report "chat" (spec §11: the SDK union is not widened)
             conversationKind: row.kind === "eval" ? "eval" : "chat",
             runId: row.run_id ?? "",
-            ...(row.parent_conversation_id !== null &&
-                row.parent_run_id !== null &&
-                row.parent_call_id !== null && {
+            ...(parent !== null && {
                 parent: {
-                    conversationId: row.parent_conversation_id,
-                    runId: row.parent_run_id,
-                    callId: row.parent_call_id,
+                    conversationId: parent.parentConversationId,
+                    runId: parent.parentRunId,
+                    callId: parent.parentCallId,
                 },
             }),
             provider: p.provider,
@@ -435,8 +500,7 @@ let UsageReporter = class UsageReporter {
         const allowed = stored === undefined ? undefined : [...stored, ...Object.keys(storedDropped)];
         const keep = [...dropped].filter(([p]) => allowed === undefined || allowed.includes(p));
         const out = {
-            conversationId: j.data.conversationId,
-            seq: j.data.seq,
+            ...keyOf(j.data),
             pending: narrowPending(allowed, next),
             ...(keep.length > 0 && { dropped: Object.fromEntries(keep) }),
         };
@@ -445,22 +509,24 @@ let UsageReporter = class UsageReporter {
     }
     /** One delivery job (the `@Processor` of {@link USAGE_REPORT_QUEUE} calls it). */
     async process(j, token) {
-        const { conversationId, seq } = j.data;
-        const payload = await this.payloadOf(conversationId, seq);
+        const payload = await this.payloadOfJob(j.data);
+        // conversation (or org) deleted meanwhile: nothing to report
         if (payload === null)
-            return; // conversation deleted meanwhile: nothing to report
+            return;
         const subscribers = await this.subscribers(payload.orgId);
         if (j.data.pending === undefined) {
             // first attempt: the targets come from deployment state, recorded so later attempts (on any
             // replica) deliver exactly the plugins that have not succeeded yet
             const targets = [...subscribers];
-            await j.updateData({ conversationId, seq, pending: targets });
+            await j.updateData({ ...keyOf(j.data), pending: targets });
             j.data.pending = targets;
         }
         // plugins the organization disabled meanwhile are dropped (not a failure)
         const targets = (j.data.pending ?? []).filter((p) => subscribers.has(p));
-        if (targets.length === 0)
+        if (targets.length === 0) {
+            await this.markReported(j.data);
             return;
+        }
         const byPlugin = new Map();
         for (const h of this.hooks.handlers("usage.report")) {
             byPlugin.set(h.plugin, [...(byPlugin.get(h.plugin) ?? []), h.handler]);
@@ -492,6 +558,12 @@ let UsageReporter = class UsageReporter {
                     notHere.push(plugin);
                 return;
             }
+            // layering spec A §6: the extension's effective config is not valid in this organization, so
+            // it is not called there (an observe hook skipped); dropped, not retried
+            if (r.reason instanceof HookNeedsConfigError) {
+                dropped.set(plugin, "needs configuration in this organization");
+                return;
+            }
             failed.push(plugin);
             if (!this.stopping.signal.aborted) {
                 this.log.warn("usage.report delivery to a plugin failed", {
@@ -533,6 +605,8 @@ let UsageReporter = class UsageReporter {
         // m-1: pending = the dropped plugins only, so a manual retry reaches them and never the
         // plugins already served
         await this.writePending(j, [...allDropped.keys()], allDropped);
+        // delivered to every target still servable (a definite drop is final too): the row is done
+        await this.markReported(j.data);
         const traced = new Map([...allDropped].filter(([p]) => j.data.dropped?.[p] !== undefined));
         if (traced.size === 0)
             return;
@@ -643,9 +717,9 @@ let UsageReportModule = class UsageReportModule {
 };
 UsageReportModule = __decorate([
     Module({
-        imports: [ExtensionsModule, QueueModule.registerQueue(USAGE_REPORT_QUEUE)],
+        imports: [ExtensionsModule, UsageReportJobsModule],
         providers: [UsageReporter],
-        exports: [UsageReporter],
+        exports: [UsageReporter, UsageReportJobsModule],
     })
 ], UsageReportModule);
 export { UsageReportModule };