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

package/dist/runtime/subagents/roster.d.ts

@@ -1,4 +1,6 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../../agents/definition.js";
+import { templateTypeOf } from "../../agents/templates.js";
 import type { KernelSchemaDb } from "../../db/kernel-schema.js";
 /**
  * The sub-agent roster of an agent version (phase C, spec §4.3, §5.1): the agent types its `agent`
@@ -10,8 +12,18 @@ export interface RosterEntry {
     source: "general" | "inline" | "plugin" | "agent";
     /** When to use it (shown in the tool description), cut to {@link ROSTER_DESCRIPTION_MAX}. */
     description: string;
-    /** Plugin templates: the `agent_templates` id. */
+    /**
+     * Plugin templates: the selected id (an org template's, a linked copy's own, or a platform
+     * template's; `subagent_started.template.id`).
+     */
     templateId?: string;
+    /**
+     * Plugin templates: other selected ids this entry stands for: ids resolving to the same platform
+     * template under this type (an org copy linked since the save), or a selected platform id an org
+     * row of the same component shadows (the entry is that row); a follow-up recorded under one of
+     * them finds this entry.
+     */
+    aliasTemplateIds?: string[];
     /** Org agents: the allowlisted agent id. */
     agentId?: string;
     /** Org agents: the agent's current name, when it is still a live agent of the org. */
@@ -22,16 +34,21 @@ export interface RosterEntry {
 export declare const ROSTER_DESCRIPTION_MAX = 1024;
 /** The description of `general-purpose` in the roster (spec §4.3, model-visible). */
 export declare const GENERAL_PURPOSE_DESCRIPTION = "a copy of you with your tools and skills, for multi-step work.";
-/** Plugin template type: `<plugin>:<name>`. */
-export declare const templateType: (plugin: string, name: string) => string;
+/** Plugin template type: `<plugin>:<name>`; the bare `<name>` for a template without a plugin. */
+export declare const templateType: typeof templateTypeOf;
 /**
  * Resolves the roster of `parent` (spec §4.3): `general-purpose` first unless
  * `subagents.general === false`, then the plugin templates, inline templates and allowlisted org
- * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates deleted
- * since the save are skipped; allowlisted org agents stay listed (the dispatch checks their gates
- * and refuses with the §4.5 text), with `agentName` only while the agent is live.
+ * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates are
+ * the org's and the platform's ({@link loadTemplates}); ones deleted or off since the save are
+ * skipped. A template whose type is taken (`general-purpose`, an earlier template, an inline
+ * template's name; only a bare `<name>` can clash with the last two kinds, and the save refuses
+ * every clash) is skipped with a warning; when it resolves to the same platform template as the
+ * entry kept, its id becomes that entry's alias. Allowlisted org agents stay listed (the dispatch
+ * checks their gates and refuses with the §4.5 text), with `agentName` only while the agent is
+ * live.
  */
-export declare function resolveRoster(db: KernelSchemaDb, orgId: string, parent: Pick<AgentDefinition, "subagents">): Promise<RosterEntry[]>;
+export declare function resolveRoster(db: KernelSchemaDb, orgId: string, parent: Pick<AgentDefinition, "subagents">, log?: Pick<Logger, "warn">): Promise<RosterEntry[]>;
 /**
  * The roster entry for a requested `subagent_type`: an exact type first; else a bare `<name>`
  * matches the plugin template `<plugin>:<name>` when exactly one has it (as Claude Code accepts
@@ -45,7 +62,7 @@ export declare const isGeneralAlias: (agent: string) => boolean;
  * `general-purpose` for no `agent` and Claude's built-in types; else a roster type (a bare name
  * prefers the skill's own plugin's template `<plugin>:<name>`, then {@link findType}). An `agent`
  * that does not resolve falls back to `general-purpose` and is returned as `unknown`. `inRoster`:
- * the type is one the parent's `agent` tool offers (`general-purpose` is not when
+ * the type is one the parent's `Agent` tool offers (`general-purpose` is not when
  * `subagents.general === false`, which does not block a person's fork invocation).
  */
 export declare function resolveSkillForkType(db: KernelSchemaDb, orgId: string, parent: Pick<AgentDefinition, "subagents">, agent: string | undefined, plugin: string | undefined): Promise<{

package/dist/runtime/subagents/roster.js

@@ -1,19 +1,24 @@
 import { SUBAGENT_ROSTER_MAX } from "../../agents/definition.js";
-import { loadTemplates } from "../../agents/templates.js";
+import { loadTemplates, templateTypeOf } from "../../agents/templates.js";
 export const ROSTER_DESCRIPTION_MAX = 1024;
 /** The description of `general-purpose` in the roster (spec §4.3, model-visible). */
 export const GENERAL_PURPOSE_DESCRIPTION = "a copy of you with your tools and skills, for multi-step work.";
 const cut = (s) => s.slice(0, ROSTER_DESCRIPTION_MAX);
-/** Plugin template type: `<plugin>:<name>`. */
-export const templateType = (plugin, name) => `${plugin}:${name}`;
+/** Plugin template type: `<plugin>:<name>`; the bare `<name>` for a template without a plugin. */
+export const templateType = templateTypeOf;
 /**
  * Resolves the roster of `parent` (spec §4.3): `general-purpose` first unless
  * `subagents.general === false`, then the plugin templates, inline templates and allowlisted org
- * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates deleted
- * since the save are skipped; allowlisted org agents stay listed (the dispatch checks their gates
- * and refuses with the §4.5 text), with `agentName` only while the agent is live.
+ * agents, each in the owner's order, at most {@link SUBAGENT_ROSTER_MAX} entries. Templates are
+ * the org's and the platform's ({@link loadTemplates}); ones deleted or off since the save are
+ * skipped. A template whose type is taken (`general-purpose`, an earlier template, an inline
+ * template's name; only a bare `<name>` can clash with the last two kinds, and the save refuses
+ * every clash) is skipped with a warning; when it resolves to the same platform template as the
+ * entry kept, its id becomes that entry's alias. Allowlisted org agents stay listed (the dispatch
+ * checks their gates and refuses with the §4.5 text), with `agentName` only while the agent is
+ * live.
  */
-export async function resolveRoster(db, orgId, parent) {
+export async function resolveRoster(db, orgId, parent, log) {
     const sub = parent.subagents;
     const out = [];
     if (sub?.general !== false) {
@@ -24,19 +29,50 @@ export async function resolveRoster(db, orgId, parent) {
         });
     }
     const templateIds = sub?.templates ?? [];
-    const templates = await loadTemplates(db, orgId, templateIds);
+    const templates = await loadTemplates(db, orgId, templateIds, log);
+    const inlineNames = new Set((sub?.inline ?? []).map((t) => t.name));
+    const kept = new Map();
+    const alias = (e, id) => {
+        if (e.templateId !== id && !e.aliasTemplateIds?.includes(id)) {
+            e.aliasTemplateIds = [...(e.aliasTemplateIds ?? []), id];
+        }
+    };
     for (const id of templateIds) {
         const r = templates.get(id);
         if (!r)
             continue;
+        const type = templateType(r.plugin, r.name);
+        const first = kept.get(type);
+        if (first !== undefined || type === "general-purpose" || inlineNames.has(type)) {
+            if (first !== undefined &&
+                (first.entry.templateId === r.id ||
+                    (r.platformTemplateId !== undefined && first.platformTemplateId === r.platformTemplateId))) {
+                alias(first.entry, id);
+                continue;
+            }
+            log?.warn("agent template skipped in the roster: its type is taken", {
+                orgId,
+                type,
+                templateId: r.id,
+            });
+            continue;
+        }
         const description = r.template.description;
-        out.push({
-            type: templateType(r.plugin, r.name),
+        const entry = {
+            type,
             source: "plugin",
             description: cut(typeof description === "string" ? description : ""),
             templateId: r.id,
-            plugin: r.plugin,
+            ...(r.plugin ? { plugin: r.plugin } : {}),
+        };
+        // a selected platform id that an org row of the same component shadows resolves to that row
+        if (r.id !== id)
+            alias(entry, id);
+        kept.set(type, {
+            entry,
+            ...(r.platformTemplateId !== undefined && { platformTemplateId: r.platformTemplateId }),
         });
+        out.push(entry);
     }
     for (const t of sub?.inline ?? []) {
         out.push({ type: t.name, source: "inline", description: cut(t.description) });
@@ -90,7 +126,7 @@ export const isGeneralAlias = (agent) => GENERAL_ALIASES.has(agent);
  * `general-purpose` for no `agent` and Claude's built-in types; else a roster type (a bare name
  * prefers the skill's own plugin's template `<plugin>:<name>`, then {@link findType}). An `agent`
  * that does not resolve falls back to `general-purpose` and is returned as `unknown`. `inRoster`:
- * the type is one the parent's `agent` tool offers (`general-purpose` is not when
+ * the type is one the parent's `Agent` tool offers (`general-purpose` is not when
  * `subagents.general === false`, which does not block a person's fork invocation).
  */
 export async function resolveSkillForkType(db, orgId, parent, agent, plugin) {

package/dist/runtime/subagents/skill-fork.d.ts

@@ -8,8 +8,9 @@ import { type DispatchDeps } from "./dispatch.js";
 /**
  * Forked skills (phase D spec §6): a person's invocation of a `context: fork` skill starts its own
  * run (the run boundary, {@link forkBoundary}), whose `prepare` node dispatches the sub-agent
- * through phase C's `dispatchSubagent` before any model call and waits on it like an `agent` call
- * (`subagents` wait `sa-<runId>-0`). When the child has ended, `prepare` appends the model-visible
+ * through phase C's `dispatchSubagent` before any model call and waits on it (`subagents` wait
+ * `sa-<runId>-0`; the dispatch row has `for_skill`, agent map spec §5.4: a fork stays in the
+ * foreground while `Agent` calls run in the background). When the child has ended, `prepare` appends the model-visible
  * `skill_fork_result` and the parent's model answers. Every terminal path of the run (and the wait
  * sweep) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
  * a fork lead whose report is missing before the next model call.
@@ -110,7 +111,7 @@ export declare const recordedSkillForks: (eventLog: Pick<EventLog, "append" | "f
  * In the transaction of a run's terminal path (or the wait sweep): the run's fork invocation
  * (its trigger message, by the run boundary) without a report gets one now: the ended child's
  * result (and the parent's missing `subagent_finished`), {@link AGENT_STOPPED_WITH_RUN_TEXT} for a
- * child still active (the caller stops it after its commit, as for `agent` calls), or
+ * child still active (the caller stops it after its commit, as for `Agent` calls), or
  * {@link FORK_NOT_STARTED_TEXT} when nothing was dispatched. Returns the call ids written
  * (`skill-<seq>`) and the highest seq; the caller notifies after its commit.
  */

package/dist/runtime/subagents/skill-fork.js

@@ -7,8 +7,9 @@ import { dispatchSubagent } from "./dispatch.js";
 /**
  * Forked skills (phase D spec §6): a person's invocation of a `context: fork` skill starts its own
  * run (the run boundary, {@link forkBoundary}), whose `prepare` node dispatches the sub-agent
- * through phase C's `dispatchSubagent` before any model call and waits on it like an `agent` call
- * (`subagents` wait `sa-<runId>-0`). When the child has ended, `prepare` appends the model-visible
+ * through phase C's `dispatchSubagent` before any model call and waits on it (`subagents` wait
+ * `sa-<runId>-0`; the dispatch row has `for_skill`, agent map spec §5.4: a fork stays in the
+ * foreground while `Agent` calls run in the background). When the child has ended, `prepare` appends the model-visible
  * `skill_fork_result` and the parent's model answers. Every terminal path of the run (and the wait
  * sweep) pairs a fork invocation without a report ({@link pairStoppedForks}), so the log never holds
  * a fork lead whose report is missing before the next model call.
@@ -92,7 +93,7 @@ export async function advanceSkillForks(d, a) {
     const callId = skillCallId(seq);
     const row = await dispatchOfCall(d.db, ctx.runId, callId);
     if (row) {
-        const r = await childResult(d.eventLog, row, { forSkill: true });
+        const r = await childResult(d.eventLog, row);
         if (!r)
             return ctx.signal.aborted ? { kind: "aborted" } : suspend(d, ctx);
         await report(r.content, row, [finishedEvent(row, r.finished)]);
@@ -190,7 +191,7 @@ export const recordedSkillForks = (eventLog, recorded) => ({
  * In the transaction of a run's terminal path (or the wait sweep): the run's fork invocation
  * (its trigger message, by the run boundary) without a report gets one now: the ended child's
  * result (and the parent's missing `subagent_finished`), {@link AGENT_STOPPED_WITH_RUN_TEXT} for a
- * child still active (the caller stops it after its commit, as for `agent` calls), or
+ * child still active (the caller stops it after its commit, as for `Agent` calls), or
  * {@link FORK_NOT_STARTED_TEXT} when nothing was dispatched. Returns the call ids written
  * (`skill-<seq>`) and the highest seq; the caller notifies after its commit.
  */
@@ -236,6 +237,7 @@ t, eventLog, runId) {
         "parent_conversation_id",
         "child_conversation_id",
         "child_run_id",
+        "budget_run_id",
     ])
         .where("parent_run_id", "=", runId)
         .where("parent_call_id", "=", callId)
@@ -251,6 +253,8 @@ t, eventLog, runId) {
             parentConversationId: d.parent_conversation_id,
             childConversationId: d.child_conversation_id,
             childRunId: d.child_run_id,
+            budgetRunId: d.budget_run_id,
+            forSkill: true,
         };
         const child = await t
             .selectFrom("runs")
@@ -259,7 +263,7 @@ t, eventLog, runId) {
             .executeTakeFirst();
         // a child that already ended keeps its own result (its log is committed)
         const ended = child !== undefined && TERMINAL_STATUSES.has(child.status)
-            ? await childResult(eventLog, row, { forSkill: true })
+            ? await childResult(eventLog, row)
             : null;
         if (ended)
             events.push(finishedEvent(row, ended.finished));

package/dist/runtime/subagents/status.d.ts

@@ -0,0 +1,14 @@
+import type { EventPayload } from "../../conversations/events.js";
+/** How a sub-agent's run ended (`subagent_finished.status`, a finished `subagent_delivery`). */
+export type SubagentStatus = EventPayload<"subagent_finished">["status"];
+/** Who stopped an aborted sub-agent: a person, or the kernel on its parent run's behalf. */
+export type SubagentAbortedBy = "user" | "parent";
+/**
+ * How a sub-agent's run ended, as the model reads it: the status of `agentResultText`'s bracket
+ * line (a fork invocation's report) and of a finished `subagent_delivery`
+ * (`renderSubagentDelivery`).
+ */
+export declare function subagentStatusText(status: SubagentStatus, opts?: {
+    errorCode?: string | undefined;
+    abortedBy?: SubagentAbortedBy | undefined;
+}): string;

package/dist/runtime/subagents/status.js

@@ -0,0 +1,23 @@
+/**
+ * How a sub-agent's run ended, as the model reads it: the status of `agentResultText`'s bracket
+ * line (a fork invocation's report) and of a finished `subagent_delivery`
+ * (`renderSubagentDelivery`).
+ */
+export function subagentStatusText(status, opts = {}) {
+    switch (status) {
+        case "completed":
+            return "completed";
+        case "max_steps":
+            return "stopped at the step limit; the reply may be partial";
+        case "max_duration":
+            return "stopped at the time limit; the reply may be partial";
+        case "budget":
+            return "stopped: token budget used up";
+        case "aborted":
+            return opts.abortedBy === "parent" ? "stopped with this run" : "stopped by the user";
+        case "timed_out":
+            return "timed out";
+        case "failed":
+            return opts.errorCode === undefined ? "failed" : `failed (${opts.errorCode})`;
+    }
+}

package/dist/runtime/subagents/subagents.service.d.ts

@@ -12,12 +12,12 @@ import { type ChildWriter, type DispatchArgs, type DispatchCommit, type Dispatch
 import { type SubagentStep } from "./progress.js";
 import { type SkillForkDeps, type SkillForks } from "./skill-fork.js";
 /**
- * Sub-agents (phase C, spec §7) and forked skills (phase D): the `agent` tool's dispatch (the
+ * Sub-agents (phase C, spec §7) and forked skills (phase D): the `Agent` tool's dispatch (the
  * tool pipeline calls {@link dispatch}), a run's fork invocation ({@link skillForks}, the loop's
  * `prepare`) and a child step's progress on the parent's stream ({@link progress}). Child runs go
- * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch (a
- * finished child resumes its parent, a stopped parent stops its children) is the waits'
- * (`Waits.childFinished` / `stopChildren`).
+ * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch is the
+ * waits' (`Waits.childFinished`): a background child's finish is delivered to its parent
+ * ({@link SubagentDeliveries}), a fork invocation's child resumes its waiting parent run.
  */
 export declare class SubagentsService {
     private readonly bus;
@@ -28,13 +28,16 @@ export declare class SubagentsService {
     /** The live fork handler of the loop (`LoopDeps.skillForks`). */
     readonly skillForks: SkillForks;
     constructor(kdb: KernelDb, eventLog: EventLog, purposes: ModelPurposesService, registry: ProviderRegistry, config: KernelConfigService, jobs: RunJobs, invoker: SkillInvoker, bus: ExtensionContext["bus"], log: KernelLogger, txHost: TransactionHost);
-    /** Dispatches the sub-agent of one `agent` call (`dispatchSubagent`). */
+    /** Dispatches the sub-agent of one `Agent` call (`dispatchSubagent`). */
     dispatch(a: DispatchArgs): Promise<DispatchOutcome>;
     /** The dispatch's writes in a transaction of their own (see `commitDispatchIn`). */
     commitDispatch(a: DispatchArgs, plan: DispatchPlan, child: ChildWriter): Promise<DispatchCommit | null>;
     /** A sub-agent's finished step on its parent's stream (sub-agents spec §14.2). Never throws. */
     progress(s: SubagentStep): Promise<void>;
 }
-/** Sub-agent dispatch (the tools domain's `agent` tool and the run loop use it). */
+/**
+ * Sub-agent dispatch, deliveries and messages (the tools domain's `Agent`, `SendMessage` and
+ * `SubagentHandback`, the run loop, the waits).
+ */
 export declare class SubagentsModule {
 }

package/dist/runtime/subagents/subagents.service.js

@@ -20,16 +20,18 @@ import { SkillInvoker } from "../../skills/invoke.js";
 import { SkillsModule } from "../../skills/skills.module.js";
 import { ProviderRegistry, ProvidersModule } from "../providers.js";
 import { RunJobs, RunJobsModule } from "../run-jobs.js";
+import { SubagentDeliveries } from "./deliveries.js";
 import { commitDispatchIn, dispatchSubagent, } from "./dispatch.js";
+import { SubagentMessages } from "./messages.js";
 import { publishSubagentProgress } from "./progress.js";
 import { liveSkillForks } from "./skill-fork.js";
 /**
- * Sub-agents (phase C, spec §7) and forked skills (phase D): the `agent` tool's dispatch (the
+ * Sub-agents (phase C, spec §7) and forked skills (phase D): the `Agent` tool's dispatch (the
  * tool pipeline calls {@link dispatch}), a run's fork invocation ({@link skillForks}, the loop's
  * `prepare`) and a child step's progress on the parent's stream ({@link progress}). Child runs go
- * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch (a
- * finished child resumes its parent, a stopped parent stops its children) is the waits'
- * (`Waits.childFinished` / `stopChildren`).
+ * to the sub-agent run queue through {@link RunJobs}. The child lifecycle after dispatch is the
+ * waits' (`Waits.childFinished`): a background child's finish is delivered to its parent
+ * ({@link SubagentDeliveries}), a fork invocation's child resumes its waiting parent run.
  */
 let SubagentsService = class SubagentsService {
     bus;
@@ -58,7 +60,7 @@ let SubagentsService = class SubagentsService {
         };
         this.skillForks = liveSkillForks(this.deps);
     }
-    /** Dispatches the sub-agent of one `agent` call (`dispatchSubagent`). */
+    /** Dispatches the sub-agent of one `Agent` call (`dispatchSubagent`). */
     dispatch(a) {
         return dispatchSubagent(this.deps, a);
     }
@@ -88,14 +90,17 @@ SubagentsService = __decorate([
     __param(9, Inject(TransactionHost))
 ], SubagentsService);
 export { SubagentsService };
-/** Sub-agent dispatch (the tools domain's `agent` tool and the run loop use it). */
+/**
+ * Sub-agent dispatch, deliveries and messages (the tools domain's `Agent`, `SendMessage` and
+ * `SubagentHandback`, the run loop, the waits).
+ */
 let SubagentsModule = class SubagentsModule {
 };
 SubagentsModule = __decorate([
     Module({
         imports: [EventLogModule, ModelsModule, ProvidersModule, RunJobsModule, SkillsModule],
-        providers: [SubagentsService],
-        exports: [SubagentsService],
+        providers: [SubagentsService, SubagentDeliveries, SubagentMessages],
+        exports: [SubagentsService, SubagentDeliveries, SubagentMessages],
     })
 ], SubagentsModule);
 export { SubagentsModule };

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 };