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

package/dist/runtime/subagents/definition.js

@@ -1,4 +1,5 @@
-import { connectorToolKey, extensionToolKey, parseToolKey, SKILL_ENTRY_FILE, sanitizeParams, } from "@capybara-hq/plugin-sdk";
+import { SKILL_ENTRY_FILE, sanitizeParams, } from "@capybara-hq/plugin-sdk";
+import { canonicalDisabledTools, } from "../../agents/definition.js";
 import { loadTemplates } from "../../agents/templates.js";
 import { ApiError } from "../../errors.js";
 import { PINNED_SKILLS_LIMITS } from "../../skills/catalog.js";
@@ -38,78 +39,28 @@ export function stricterPolicies(base, over) {
     }
     return out;
 }
-async function loadConnectors(db, orgId, refs) {
-    const ids = [...new Set(refs.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : [])))];
-    const out = new Map();
-    if (ids.length === 0)
-        return out;
-    const rows = await db
-        .selectFrom("connectors")
-        .select(["id", "slug"])
-        .where("org_id", "=", orgId)
-        .where("deleted_at", "is", null)
-        .where("id", "in", ids)
-        .execute();
-    const tools = rows.length === 0
-        ? []
-        : await db
-            .selectFrom("connector_tools")
-            .select(["connector_id", "name"])
-            .where("connector_id", "in", rows.map((r) => r.id))
-            .orderBy("name")
-            .execute();
-    for (const r of rows) {
-        out.set(r.id, {
-            slug: r.slug,
-            tools: tools.filter((t) => t.connector_id === r.id).map((t) => t.name),
-        });
-    }
-    return out;
-}
 /**
- * Narrows tool refs by resolved key (spec §5.3): keeps a key when `allow` (if given) lists it and
- * neither `deny` nor {@link CHILD_REMOVED_TOOLS} does (nor, with `removeAgent`, it is `Agent`). A connector ref with `tools: "all"` stays
- * live only when nothing can narrow it (no allowlist and no deny key under `mcp__<slug>__`), so a tool
- * the connector gains later never slips past the template; otherwise it becomes the kept names, or
- * is dropped. A connector that no longer exists keeps its ref only without an allowlist.
+ * A child's key filter (tools default-on spec §4): `deny` = the parent's own filter's (a nested
+ * child), {@link CHILD_REMOVED_TOOLS}, `Agent` when the child is at the depth limit, and the
+ * template's `disallowedTools`; `allow` = the template's `tools` allowlist met with the parent's
+ * (absent on both = everything the parent has). Keys are deduplicated in first-seen order.
  */
-function narrowTools(refs, connectors, allow, deny, removeAgent) {
-    const removed = new Set(CHILD_REMOVED_TOOLS);
-    if (removeAgent)
-        removed.add(AGENT_TOOL);
-    const keep = (key) => !removed.has(key) && !deny.has(key) && (allow === null || allow.has(key));
-    const out = [];
-    for (const ref of refs) {
-        if (ref.kind === "builtin") {
-            if (keep(ref.name))
-                out.push(ref);
-        }
-        else if (ref.kind === "plugin") {
-            if (keep(extensionToolKey(ref.plugin, ref.name)))
-                out.push(ref);
-        }
-        else {
-            const c = connectors.get(ref.connectorId);
-            if (!c) {
-                if (allow === null)
-                    out.push(ref);
-                continue;
-            }
-            const ownsKey = (k) => {
-                const parsed = parseToolKey(k);
-                return parsed?.kind === "connector" && parsed.slug === c.slug;
-            };
-            if (ref.tools === "all" && allow === null && ![...deny].some(ownsKey)) {
-                out.push(ref);
-                continue;
-            }
-            const names = ref.tools === "all" ? c.tools : ref.tools;
-            const kept = names.filter((name) => keep(connectorToolKey(c.slug, name)));
-            if (kept.length > 0)
-                out.push({ ...ref, tools: kept });
-        }
-    }
-    return out;
+function childFilter(removeAgent, template, parent) {
+    const deny = [
+        ...new Set([
+            ...(parent?.deny ?? []),
+            ...CHILD_REMOVED_TOOLS,
+            ...(removeAgent ? [AGENT_TOOL] : []),
+            ...(template?.disallowedTools ?? []),
+        ]),
+    ];
+    const own = template?.tools === undefined ? undefined : [...new Set(template.tools)];
+    const allow = own === undefined
+        ? parent?.allow
+        : parent?.allow === undefined
+            ? own
+            : own.filter((k) => parent.allow?.includes(k));
+    return { ...(allow !== undefined && { allow: [...allow] }), deny };
 }
 /**
  * The template's skills the parent selects (its `orgSkills` or the parent agent's own skills),
@@ -184,9 +135,9 @@ selected = []) {
     return { pinned, warnings };
 }
 /** The `effort` declaration of `model`, or null (or when the model cannot be resolved). */
-async function effortDecl(registry, model) {
+async function effortDecl(registry, orgId, model) {
     try {
-        const { info } = await registry.resolve(model);
+        const { info } = await registry.resolve(orgId, model);
         return info.parameters.find((p) => p.standard === "effort") ?? null;
     }
     catch {
@@ -236,10 +187,12 @@ function orgAgentDefinition(d, a) {
     // block stays: it is the roster the child dispatches from (agent map spec §4.1); pending
     // connectors are authoring data too (ruling P4-6)
     const { skills, instructionFiles: _files, pendingConnectors: _pending, ...rest } = own;
+    const { subagentTools: _filter, ...ownRest } = rest;
     const definition = {
-        ...rest,
+        ...ownRest,
         // its own tools, not intersected with the parent's; only the child-removed ones go
-        tools: narrowTools(own.tools, new Map(), null, new Set(), atMaxDepth(a)),
+        disabledTools: own.disabledTools ?? [],
+        subagentTools: childFilter(atMaxDepth(a), null),
         // its policies, then the parent's on top, stricter wins (keys outside its tools are inert)
         toolPolicies: stricterPolicies(own.toolPolicies ?? {}, a.parent.toolPolicies ?? {}),
         ...(skills !== undefined && {
@@ -298,15 +251,13 @@ export async function effectiveDefinition(d, a) {
             ...(row.platformTemplateId !== undefined && { platformTemplateId: row.platformTemplateId }),
         };
     }
-    const connectors = await loadConnectors(d.db, a.orgId, parent.tools);
-    const tools = narrowTools(parent.tools, connectors, template?.tools !== undefined ? new Set(template.tools) : null, new Set(template?.disallowedTools ?? []), atMaxDepth(a));
     const toolPolicies = stricterPolicies(parent.toolPolicies ?? {}, template?.toolPolicies ?? {});
     const { pinned, warnings } = await pinnedFor(d.db, a, template?.skills ?? [], entry.source === "plugin" ? { plugin: entry.plugin } : null, template?.selectedSkills ?? []);
     const tier = a.tier ?? template?.model ?? "inherit";
     const m = await resolveTier(d, a.orgId, parent, tier);
     let modelParams = m.modelParams;
     if (template?.effort !== undefined) {
-        const decl = await effortDecl(d.registry, m.model);
+        const decl = await effortDecl(d.registry, a.orgId, m.model);
         if (decl) {
             const v = sanitizeParams([decl], { [decl.key]: template.effort }).value[decl.key];
             if (v !== undefined)
@@ -322,7 +273,8 @@ export async function effectiveDefinition(d, a) {
         fallback: m.fallback,
         modelParams,
         fallbackParams: m.fallbackParams,
-        tools,
+        disabledTools: parent.disabledTools ?? [],
+        subagentTools: childFilter(atMaxDepth(a), template, parent.subagentTools),
         toolPolicies,
         ...((parentSkills !== undefined || pinned.length > 0) && {
             skills: {
@@ -341,57 +293,32 @@ export async function effectiveDefinition(d, a) {
         tierFallback: m.tierFallback,
     };
 }
-/**
- * The refs of `frozen` that `current` still has: a builtin or plugin tool by name, a connector by
- * id; a connector's `all` meets the other side's names (`all` on both stays `all`), and a
- * connector left with no names is dropped. Pure: a connector `current` lists is not looked up.
- */
-export function intersectTools(frozen, current) {
-    const out = [];
-    for (const ref of frozen) {
-        if (ref.kind === "builtin") {
-            if (current.some((c) => c.kind === "builtin" && c.name === ref.name))
-                out.push(ref);
-        }
-        else if (ref.kind === "plugin") {
-            if (current.some((c) => c.kind === "plugin" && c.plugin === ref.plugin && c.name === ref.name)) {
-                out.push(ref);
-            }
-        }
-        else {
-            const c = current.find((x) => x.kind === "connector" && x.connectorId === ref.connectorId);
-            if (!c)
-                continue;
-            if (c.tools === "all") {
-                out.push(ref);
-                continue;
-            }
-            const names = ref.tools === "all" ? c.tools : ref.tools.filter((n) => c.tools.includes(n));
-            if (names.length > 0)
-                out.push({ ...ref, tools: names });
-        }
-    }
-    return out;
-}
 /**
  * The narrowing of a follow-up (final review I1): `frozen` (the child's `subagent_started`
  * definition) against `current`, the definition a fresh dispatch would read now: the dispatching
  * parent run's version for `general` / inline / plugin children, the dispatched org agent's
  * current version for an org agent child (whose tools are its own at dispatch too, §5.5). Its
- * `orgSkills` keep only those `current` still selects; a pinned id that was one of the frozen org
- * skills goes with it (the agent's own skills stay).
+ * `disabledTools` are both lists together; its `orgSkills` keep only those `current` still
+ * selects; a pinned id that was one of the frozen org skills goes with it (the agent's own skills
+ * stay).
  */
 export function narrowFollowUp(frozen, current) {
-    const tools = intersectTools(frozen.tools, current.tools);
+    const disabledTools = canonicalDisabledTools([
+        ...(frozen.disabledTools ?? []),
+        ...(current.disabledTools ?? []),
+    ]);
     if (frozen.skills === undefined)
-        return { tools };
+        return { disabledTools };
     const frozenOrg = new Set(frozen.skills.orgSkills);
     const now = new Set(current.skills?.orgSkills ?? []);
     const orgSkills = frozen.skills.orgSkills.filter((id) => now.has(id));
     const pinned = frozen.skills.pinned?.filter((id) => !frozenOrg.has(id) || now.has(id));
-    return { tools, skills: { orgSkills, ...(pinned !== undefined && { pinned }) } };
+    return { disabledTools, skills: { orgSkills, ...(pinned !== undefined && { pinned }) } };
 }
-/** The definition a child run uses: the frozen one with its trigger's follow-up narrowing. */
+/**
+ * The definition a child run uses: the frozen one with its trigger's follow-up narrowing. A
+ * narrowing logged before tools were on by default (no `disabledTools`) narrows only skills.
+ */
 export function childRunDefinition(frozen, narrowed) {
     if (narrowed === undefined)
         return frozen;
@@ -403,5 +330,9 @@ export function childRunDefinition(frozen, narrowed) {
             orgSkills: narrowed.skills.orgSkills,
             ...(narrowed.skills.pinned !== undefined && { pinned: narrowed.skills.pinned }),
         };
-    return { ...rest, tools: narrowed.tools, ...(kept !== undefined && { skills: kept }) };
+    return {
+        ...rest,
+        ...(Array.isArray(narrowed.disabledTools) && { disabledTools: narrowed.disabledTools }),
+        ...(kept !== undefined && { skills: kept }),
+    };
 }

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;
     /**