@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.24

package/dist/conversations/titles.js

@@ -22,7 +22,7 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { ModelsModule } from "../models/models.module.js";
 import { ModelPurposesService, PurposeAttemptError } from "../models/purposes.js";
 import { fireObserve, hookDeniedAudit, hookDeniedEvent, hookRequestOf, } from "../runtime/hook-calls.js";
-import { UsageReporter, UsageReportModule } from "../runtime/usage-report.js";
+import { UsageReportJobs, UsageReportJobsModule } from "../runtime/usage-report-jobs.js";
 import { HIDDEN_FORMAT_RE } from "../text.js";
 import { EventLog, EventLogModule } from "./event-log.js";
 import { typedInvocation } from "./events.js";
@@ -275,10 +275,8 @@ export async function runTitleJob(d, conversationId, attempt) {
         });
     }
     const { written, usage } = await d.writes.writeResult(conversationId, attempt, out, title);
-    if (usage) {
+    if (usage)
         await d.eventLog.notify(conversationId, usage.seq);
-        void d.usageReport?.enqueue(conversationId, usage.seq);
-    }
     if (written)
         await d.eventLog.publishChanged(conversationId, "title");
 }
@@ -291,9 +289,9 @@ const usageEvent = (attempt, u) => ({
     payload: { step: 0, provider: u.provider, model: u.model, ...u.usage, purpose: "title" },
 });
 async function logUsage(d, conversationId, attempt, u) {
-    const [ev] = await d.eventLog.append(conversationId, [usageEvent(attempt, u)]);
+    const ev = await d.writes.writeUsage(conversationId, attempt, u);
     if (ev)
-        void d.usageReport?.enqueue(conversationId, ev.seq);
+        await d.eventLog.notify(conversationId, ev.seq);
 }
 /** Returns a claimed attempt (shutdown before the call was sent). */
 async function giveBack(db, conversationId, attempt) {
@@ -383,17 +381,19 @@ let TitleGenerator = class TitleGenerator {
     eventLog;
     purposes;
     host;
-    usageReport;
+    usage;
     log;
     txHost;
     constructor(kdb, eventLog, purposes, 
     /** The title call fires the plugin hooks (`model.request`, `model.response`). */
-    host, usageReport, log, txHost) {
+    host, 
+    /** The title call's `usage.report` delivery, owed with its usage event. */
+    usage, log, txHost) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.purposes = purposes;
         this.host = host;
-        this.usageReport = usageReport;
+        this.usage = usage;
         this.log = log;
         this.txHost = txHost;
     }
@@ -409,21 +409,20 @@ let TitleGenerator = class TitleGenerator {
             purposes: this.purposes,
             log: this.log,
             ...(hooks !== undefined && { hooks }),
-            ...(this.usageReport !== undefined && { usageReport: this.usageReport }),
             ...(signal !== undefined && { signal }),
             writes: this,
         }, conversationId, attempt);
     }
     /**
-     * Appends the call's `usage` event and writes the title while `title_source IS NULL` (a rename
-     * wins), in one transaction.
+     * Appends the call's `usage` event (owing its `usage.report` delivery) and writes the title while
+     * `title_source IS NULL` (a rename wins), in one transaction.
      */
     async writeResult(conversationId, attempt, out, title) {
         // Append first: it locks the conversation row FOR UPDATE before this transaction touches it.
         // Updating the title first held the row FOR NO KEY UPDATE, which lets in another
         // transaction's foreign key check (FOR KEY SHARE, e.g. inserting an approval); the append's
         // FOR UPDATE then waited for that one while it waited for the title row: 40P01
-        const [ev] = await this.eventLog.appendIn(conversationId, [usageEvent(attempt, out)]);
+        const ev = await this.appendUsage(conversationId, attempt, out);
         const row = title === null
             ? undefined
             : await this.kdb.db
@@ -435,6 +434,22 @@ let TitleGenerator = class TitleGenerator {
                 .executeTakeFirst();
         return { written: row !== undefined, usage: ev };
     }
+    /**
+     * Appends the usage event of a call that failed after it was sent (billed, so reported) and owes
+     * its `usage.report` delivery, in one transaction.
+     */
+    async writeUsage(conversationId, attempt, u) {
+        return this.appendUsage(conversationId, attempt, u);
+    }
+    /** The usage event and its owed delivery (only when this call wrote it, not on a retry's hit). */
+    async appendUsage(conversationId, attempt, u) {
+        const { events, fresh } = await this.eventLog.appendInReport(conversationId, [
+            usageEvent(attempt, u),
+        ]);
+        if (fresh[0])
+            await this.usage.oweEvents(conversationId, events);
+        return events[0];
+    }
     /** The `hook.denied` audit row of a denied title call. */
     async auditDenied(entry) {
         await audit(this.kdb.db, entry);
@@ -443,6 +458,12 @@ let TitleGenerator = class TitleGenerator {
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], TitleGenerator.prototype, "writeResult", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], TitleGenerator.prototype, "writeUsage", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], TitleGenerator.prototype, "appendUsage", null);
 __decorate([
     Transactional({ propagation: "requires_new" })
 ], TitleGenerator.prototype, "auditDenied", null);
@@ -452,7 +473,7 @@ TitleGenerator = __decorate([
     __param(1, Inject(EventLog)),
     __param(2, Inject(ModelPurposesService)),
     __param(3, Inject(ExtensionHost)),
-    __param(4, Inject(UsageReporter)),
+    __param(4, Inject(UsageReportJobs)),
     __param(5, Inject(KERNEL_LOGGER)),
     __param(6, Inject(TransactionHost))
 ], TitleGenerator);
@@ -535,7 +556,13 @@ let TitlesModule = class TitlesModule {
 };
 TitlesModule = __decorate([
     Module({
-        imports: [EventLogModule, ModelsModule, ExtensionsModule, UsageReportModule, TITLE_QUEUE_MODULE],
+        imports: [
+            EventLogModule,
+            ModelsModule,
+            ExtensionsModule,
+            UsageReportJobsModule,
+            TITLE_QUEUE_MODULE,
+        ],
         providers: [TitleGenerator, TitleQueue],
         exports: [TitleQueue, TITLE_QUEUE_MODULE],
     })

package/dist/db/kernel-schema.d.ts

@@ -939,6 +939,8 @@ export interface DeviceMachinesTable {
     features: ColumnType<string[], string[] | undefined, string[]>;
     /** 0114: the program's local network policy summary (hello, refreshed by each `policy` op). */
     local_policy: ColumnType<unknown | null, string | null | undefined, string | null>;
+    /** 0118: the `policy` ops sent whose answer is not recorded yet (`PendingPolicyOp[]`). */
+    pending_policy_ops: ColumnType<unknown, string | undefined, string>;
 }
 /** 0088_environments.sql, renamed in 0105: the device a member's new conversations use by default. */
 export interface DeviceDefaultsTable {
@@ -1156,12 +1158,6 @@ export interface ExtensionReplicaStatusTable {
     http_replica_id: string | null;
     heartbeat_at: Ts;
 }
-/** 0040: the usage.report sweeper's watermark (a single row, id = 1). */
-export interface UsageReportSweepTable {
-    id: ColumnType<number, number | undefined, never>;
-    watermark: Ts;
-    updated_at: ColumnType<Date, Date | string | undefined, Date | string>;
-}
 /** A model disabled on the platform (`org_id` null) or in one org (0089, spec B §5.3). */
 export interface ModelDisabledTable {
     org_id: string | null;
@@ -1181,7 +1177,7 @@ export interface ModelUsageTable {
     input_tokens: number;
     occurred_at: Ts;
     reported_at: TsNullable;
-    /** Set when the row's `usage.report` job gave up after its last attempt (the sweep skips it). */
+    /** Set when the row's `usage.report` job gave up after its last attempt. */
     report_failed_at: TsNullable;
 }
 type NullableText = ColumnType<string | null, string | null | undefined, string | null>;
@@ -1310,7 +1306,6 @@ export interface KernelDatabase {
     extension_blobs: ExtensionBlobsTable;
     extension_installs: ExtensionInstallsTable;
     extension_replica_status: ExtensionReplicaStatusTable;
-    usage_report_sweep: UsageReportSweepTable;
     extension_name_owners: ExtensionNameOwnersTable;
     extension_deployment_configs: ExtensionDeploymentConfigsTable;
     catalog_items: CatalogItemsTable;
@@ -1344,6 +1339,29 @@ export interface KernelDatabase {
     plugin_scope_sync_failures: PluginScopeSyncFailuresTable;
     extension_client_builds: ExtensionClientBuildsTable;
     extension_client_reports: ExtensionClientReportsTable;
+    outbox: OutboxTable;
+}
+/**
+ * 0119: the transactional outbox (transactional outbox spec §4). A row is a BullMQ job owed by a
+ * committed transaction; deleted on delivery, so only dead rows (`dead_at` set) stay.
+ */
+export interface OutboxTable {
+    /** bigint identity; the pg driver reads it as a string. */
+    id: Generated<string>;
+    queue: string;
+    job_name: string;
+    /** Unique per queue: a second add of the same job before delivery is a no-op. */
+    job_id: string;
+    data: Json;
+    /** The job's delay target; null runs it now. */
+    run_at: Date | null;
+    /** Null for platform work. */
+    org_id: string | null;
+    attempts: Generated<number>;
+    next_attempt_at: Generated<Date>;
+    last_error: string | null;
+    dead_at: Date | null;
+    created_at: Generated<Date>;
 }
 /**
  * 0107: the client files of an extension package (client extensions spec §9.1), keyed by the

package/dist/devices/devices.service.d.ts

@@ -111,7 +111,8 @@ export interface DeviceSandboxView {
 export declare const RECENT_POLICY_CHANGES = 10;
 /**
  * One sandbox change of a device, as its owner sees it on the device page (§10.4):
- * - `policy` (`device.policy_changed`): a local policy change sent to the machine;
+ * - `policy` (`device.policy_changed`): a local policy change sent to the machine (`web`, `im`),
+ *   or made on the machine by its owner (`device`, `capybara-device policy ...`);
  * - `tier` (`device.tier_changed`): a cloud device's tier set by its owner;
  * - `isolation` (`device.isolation_reported`): the machine reported running without a sandbox,
  *   or with one again.
@@ -122,15 +123,23 @@ export interface DeviceSandboxChangeView {
     /** Hosts added to / removed from the local allowlist (`policy` only; else empty). */
     add: string[];
     remove: string[];
-    /** The tier set (`to: null`: follow the org's default); null when the tier did not change. */
+    /**
+     * The tier set (`to: null`: follow the org's default; `from`, the tier before, only for a change
+     * made on the machine); null when the tier did not change.
+     */
     tier: {
+        from?: SandboxTier | null;
         to: SandboxTier | null;
     } | null;
     /** The isolation set or reported; null when it did not change. */
     isolation: "sandbox" | "none" | null;
+    /** The localhost access now (a change made on the machine only); null when it did not change. */
+    localhost: DeviceLocalPolicySummary["localhost"] | null;
+    /** Whether the machine takes the platform's changes now (made on the machine); null: unchanged. */
+    remoteGrants: DeviceLocalPolicySummary["remoteGrants"] | null;
     /** The deciding account's display name (null when the account is gone). */
     by: string | null;
-    /** `device`: reported by the machine itself (`isolation`). */
+    /** `device`: made or reported on the machine itself (a `policy` change, an `isolation`). */
     via: "web" | "im" | "device";
     /** The machine answered with the policy as written (false: the answer never came). */
     confirmed: boolean;

package/dist/devices/devices.service.js

@@ -1055,7 +1055,16 @@ const tierOrNull = (v) => v === "strict" || v === "dev" || v === "open" ? v : nu
 function sandboxChangeOf(action, at, d, by) {
     const hosts = (v) => Array.isArray(v) ? v.filter((h) => typeof h === "string") : [];
     const isolation = d.isolation === "sandbox" || d.isolation === "none" ? d.isolation : null;
-    const base = { at: at.toISOString(), add: [], remove: [], tier: null, isolation: null, by };
+    const base = {
+        at: at.toISOString(),
+        add: [],
+        remove: [],
+        tier: null,
+        isolation: null,
+        localhost: null,
+        remoteGrants: null,
+        by,
+    };
     if (action === "device.tier_changed") {
         return { ...base, kind: "tier", tier: { to: tierOrNull(d.to) }, via: "web", confirmed: true };
     }
@@ -1068,9 +1077,15 @@ function sandboxChangeOf(action, at, d, by) {
         add: hosts(d.add),
         remove: hosts(d.remove),
         // the key is there only when the change set the tier (null: follow the org's default)
-        tier: "tier" in d ? { to: tierOrNull(d.tier) } : null,
+        tier: "tier" in d
+            ? { ...("tierFrom" in d && { from: tierOrNull(d.tierFrom) }), to: tierOrNull(d.tier) }
+            : null,
         isolation,
-        via: d.via === "im" ? "im" : "web",
+        localhost: d.localhost === "on" || d.localhost === "off-proxy-detected" || d.localhost === "off"
+            ? d.localhost
+            : null,
+        remoteGrants: d.remoteGrants === "owner" || d.remoteGrants === "off" ? d.remoteGrants : null,
+        via: d.via === "im" ? "im" : d.via === "device" ? "device" : "web",
         confirmed: d.confirmed === true,
     };
 }

package/dist/errors.d.ts

@@ -225,10 +225,17 @@ export declare const ERROR_CODES: {
     readonly "plugin.upgrade_stale": 409;
     readonly "plugin.upgrade_target_invalid": 409;
     readonly "plugin.upgrade_failed": 502;
+    /**
+     * The platform's import and update imported the version but the update failed: the platform
+     * stays on its version, the imported version is in the catalog (retry with the plain update).
+     */
+    readonly "plugin.imported_not_updated": 409;
     readonly "setup.already_completed": 409;
     readonly "setup.token_invalid": 403;
     /** The admin overview's seven-day usage aggregate ran past its statement timeout (spec §5.5). */
     readonly "admin.usage_unavailable": 503;
+    /** No dead outbox row has this id (delivered, discarded, retried, or never dead). */
+    readonly "outbox.not_found": 404;
     readonly "agent.not_found": 404;
     readonly "agent.version_conflict": 409;
     /** The profile was changed since the client read it (`expectedUpdatedAt` is stale). */
@@ -319,6 +326,10 @@ export declare const ERROR_CODES: {
     readonly "attachment.too_many_pending": 429;
     readonly "sandbox.unavailable": 503;
     readonly "sandbox.busy": 409;
+    /** A cloud sandbox provider refused the device's tier (its config refuses open egress). */
+    readonly "sandbox.tier_refused": 409;
+    /** A cloud sandbox provider failed to create a device's sandbox for another reason. */
+    readonly "sandbox.create_failed": 502;
     /** A sandbox file path the kernel reads is not absolute or not under the sandbox roots. */
     readonly "sandbox.file_invalid_path": 422;
     /** No file at the sandbox path the kernel reads. */

package/dist/errors.js

@@ -225,10 +225,17 @@ export const ERROR_CODES = {
     "plugin.upgrade_stale": 409,
     "plugin.upgrade_target_invalid": 409,
     "plugin.upgrade_failed": 502,
+    /**
+     * The platform's import and update imported the version but the update failed: the platform
+     * stays on its version, the imported version is in the catalog (retry with the plain update).
+     */
+    "plugin.imported_not_updated": 409,
     "setup.already_completed": 409,
     "setup.token_invalid": 403,
     /** The admin overview's seven-day usage aggregate ran past its statement timeout (spec §5.5). */
     "admin.usage_unavailable": 503,
+    /** No dead outbox row has this id (delivered, discarded, retried, or never dead). */
+    "outbox.not_found": 404,
     "agent.not_found": 404,
     "agent.version_conflict": 409,
     /** The profile was changed since the client read it (`expectedUpdatedAt` is stale). */
@@ -319,6 +326,10 @@ export const ERROR_CODES = {
     "attachment.too_many_pending": 429,
     "sandbox.unavailable": 503,
     "sandbox.busy": 409,
+    /** A cloud sandbox provider refused the device's tier (its config refuses open egress). */
+    "sandbox.tier_refused": 409,
+    /** A cloud sandbox provider failed to create a device's sandbox for another reason. */
+    "sandbox.create_failed": 502,
     /** A sandbox file path the kernel reads is not absolute or not under the sandbox roots. */
     "sandbox.file_invalid_path": 422,
     /** No file at the sandbox path the kernel reads. */

package/dist/evals/run-replay.js

@@ -19,6 +19,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { estimateTokens } from "../runtime/context/tokens.js";
+import { runDeadline, tightestLimit } from "../runtime/limits.js";
 import { RunError } from "../runtime/model-call.js";
 import { runContextIdemKey } from "../runtime/run-context.service.js";
 import { recordedSkillForks } from "../runtime/subagents/skill-fork.js";
@@ -526,13 +527,18 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
         return out;
     };
     const runtime = d.config.get().runtime;
-    const deadline = Date.now() + runtime.maxRunSeconds * 1000;
+    // 0 in the config or the logged child limit = no limit there
+    const maxSteps = tightestLimit(subagent?.maxSteps, runtime.maxSteps);
+    // `runtime.maxRunSeconds` 0: no deadline and no timer
+    const deadline = runDeadline(Date.now(), runtime.maxRunSeconds);
     let deadlineHit = false;
-    const timer = setTimeout(() => {
-        deadlineHit = true;
-        stopper.abort();
-    }, Math.max(0, deadline - Date.now()));
-    timer.unref();
+    const timer = deadline === undefined
+        ? undefined
+        : setTimeout(() => {
+            deadlineHit = true;
+            stopper.abort();
+        }, Math.max(0, deadline - Date.now()));
+    timer?.unref();
     // a fork invocation's report is the recorded one: a replay never dispatches a sub-agent (A5)
     const skillForks = recordedSkillForks(eventLog, s.events.filter((e) => e.runId === s.runId));
     const loop = d.loop({ toolPipeline: pipeline, registry, skillForks, ...(media && { media }) });
@@ -551,8 +557,8 @@ export async function replayRun(d, s, candidate, evalRunId, signal) {
             sink: () => { },
             pendingAbsorbable,
             limits: {
-                maxSteps: subagent === undefined ? runtime.maxSteps : Math.min(subagent.maxSteps, runtime.maxSteps),
-                deadline,
+                ...(maxSteps !== undefined && { maxSteps }),
+                ...(deadline !== undefined && { deadline }),
             },
             // replays never fire plugin hooks (the loop deps omit them too, P-18)
             conversationKind: "eval",

package/dist/extensions/extensions.module.js

@@ -28,6 +28,7 @@ import { SingleProviderGuard } from "./single-provider.js";
 import { ReplicaStatusStore } from "./sources.js";
 import { ExtensionStateModule } from "./state.module.js";
 import { ExtensionAvailability } from "./unavailable.js";
+import { UsageSubscribersModule } from "./usage-subscribers.js";
 /**
  * The extensions domain: the extension host (it builds each `ctx` from the injected kernel
  * services), the package store and install records (the desired state the host converges to, one
@@ -48,6 +49,8 @@ ExtensionsModule = __decorate([
             ExtensionStateModule,
             // ctx.models: the embeddings broker (models domain, below the host through ExtensionStateModule)
             ModelsModule,
+            // the lifecycle clears the `usage.report` subscriber cache on PLUGINS_CHANGED
+            UsageSubscribersModule,
         ],
         providers: [
             PluginInstallLock,

package/dist/extensions/lifecycle.d.ts

@@ -7,6 +7,7 @@ import { ExtensionInstalls } from "./installs.js";
 import { PLUGINS_CHANGED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS } from "./lifecycle-topics.js";
 import { PLUGINS_MIGRATED_TOPIC } from "./migrate-lock.js";
 import { ReplicaStatusStore } from "./sources.js";
+import { UsageSubscribers } from "./usage-subscribers.js";
 export { PLUGINS_CHANGED_TOPIC, PLUGINS_MIGRATED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, };
 /**
  * 每副本一个：把本副本的插件加载状态收敛到 PG 期望状态（C16）。
@@ -24,6 +25,8 @@ export declare class ExtensionLifecycle {
     private readonly installs;
     private readonly config;
     private readonly log;
+    /** "Does any plugin subscribe to usage.report": its cached answer is cleared on PLUGINS_CHANGED. */
+    private readonly usageSubscribers;
     private running;
     private queued;
     private unsubs;
@@ -32,7 +35,9 @@ export declare class ExtensionLifecycle {
     private stopped;
     constructor(host: ExtensionHost, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, status: ReplicaStatusStore, 
     /** Every install record's name (any desired state): prunes status rows this replica no longer knows. */
-    installs: ExtensionInstalls, config: KernelConfigService, log: KernelLogger);
+    installs: ExtensionInstalls, config: KernelConfigService, log: KernelLogger, 
+    /** "Does any plugin subscribe to usage.report": its cached answer is cleared on PLUGINS_CHANGED. */
+    usageSubscribers: Pick<UsageSubscribers, "invalidate">);
     /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
     start(): Promise<void>;
     /**

package/dist/extensions/lifecycle.js

@@ -17,6 +17,7 @@ import { ExtensionInstalls } from "./installs.js";
 import { PLUGIN_DEPLOYMENT_CONFIG_TOPIC, PLUGINS_CHANGED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, } from "./lifecycle-topics.js";
 import { PLUGINS_MIGRATED_TOPIC } from "./migrate-lock.js";
 import { ReplicaStatusStore } from "./sources.js";
+import { UsageSubscribers } from "./usage-subscribers.js";
 export { PLUGINS_CHANGED_TOPIC, PLUGINS_MIGRATED_TOPIC, PLUGINS_RECONCILE_JOB, PLUGINS_RECONCILE_TOPIC, STALE_RECONCILE_PERIODS, };
 /** 心跳超过这么多个周期的行直接删除（副本早已退出；读的一方本来就不计入）。 */
 const PRUNE_RECONCILE_PERIODS = 10;
@@ -35,6 +36,7 @@ let ExtensionLifecycle = class ExtensionLifecycle {
     installs;
     config;
     log;
+    usageSubscribers;
     running;
     queued;
     unsubs = [];
@@ -43,13 +45,16 @@ let ExtensionLifecycle = class ExtensionLifecycle {
     stopped = false;
     constructor(host, bus, status, 
     /** Every install record's name (any desired state): prunes status rows this replica no longer knows. */
-    installs, config, log) {
+    installs, config, log, 
+    /** "Does any plugin subscribe to usage.report": its cached answer is cleared on PLUGINS_CHANGED. */
+    usageSubscribers) {
         this.host = host;
         this.bus = bus;
         this.status = status;
         this.installs = installs;
         this.config = config;
         this.log = log;
+        this.usageSubscribers = usageSubscribers;
     }
     /** 订阅三个主题（订阅失败只记 error：周期任务的消息同样收不到时，下次启动再来）。 */
     async start() {
@@ -65,6 +70,7 @@ let ExtensionLifecycle = class ExtensionLifecycle {
         await on(PLUGINS_CHANGED_TOPIC, (p) => {
             // 安装 / 卸载改变了「部署已知」的插件名：路由闸门不等 TTL
             this.host.invalidateKnownNames();
+            this.usageSubscribers.invalidate();
             this.trigger(`changed:${pluginOf(p)}`);
         });
         await on(PLUGINS_RECONCILE_TOPIC, () => this.trigger("periodic"));
@@ -176,7 +182,8 @@ ExtensionLifecycle = __decorate([
     __param(2, Inject(ReplicaStatusStore)),
     __param(3, Inject(ExtensionInstalls)),
     __param(4, Inject(KernelConfigService)),
-    __param(5, Inject(KERNEL_LOGGER))
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(UsageSubscribers))
 ], ExtensionLifecycle);
 export { ExtensionLifecycle };
 const pluginOf = (p) => typeof p === "object" && p !== null && typeof p.plugin === "string"

package/dist/extensions/usage-subscribers.d.ts

@@ -0,0 +1,43 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/**
+ * 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>>;
+/** How long one replica trusts its answer to "does any plugin subscribe" (spec §8.1). */
+export declare const USAGE_SUBSCRIBERS_TTL_MS = 30000;
+/**
+ * Test seam (`KernelOverride`): the clock {@link UsageSubscribers} ages its cached answer with
+ * (default `Date.now`); the kernel never provides it.
+ */
+export declare const USAGE_SUBSCRIBERS_CLOCK: unique symbol;
+/**
+ * Whether the deployment has at least one `usage.report` subscriber ({@link queryUsageSubscribers}
+ * without an org), which decides whether a usage write owes a delivery (transactional outbox spec
+ * §8.1): a usage event written while no plugin subscribes is never reported, later subscribers
+ * included. The answer comes from PG, not from this replica's loaded handlers, so a replica that
+ * has no handler still owes the delivery another replica makes.
+ *
+ * Per-process memoisation of that PG read: kept {@link USAGE_SUBSCRIBERS_TTL_MS} and cleared on
+ * `PLUGINS_CHANGED` (`ExtensionLifecycle` calls {@link invalidate}), so an enabled subscriber is
+ * seen at once, or within 30 s when the bus message is lost. It holds no state another request or
+ * replica relies on.
+ */
+export declare class UsageSubscribers {
+    private readonly kdb;
+    private readonly now;
+    private cached;
+    /** Bumped by {@link invalidate}: a read that started before it does not refill the cache. */
+    private generation;
+    constructor(kdb: KernelDb, now?: () => number);
+    /** Whether any plugin subscribes (cached; the read joins the caller's transaction, if any). */
+    any(): Promise<boolean>;
+    /** Forgets the cached answer (a plugin was installed, enabled, upgraded or removed). */
+    invalidate(): void;
+}
+/** {@link UsageSubscribers}: below the extension host, so the model broker and the runtime use it. */
+export declare class UsageSubscribersModule {
+}

package/dist/extensions/usage-subscribers.js

@@ -0,0 +1,108 @@
+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 { Inject, Injectable, Module, Optional } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { enabledExtensionsQuery } from "./enabled.js";
+/**
+ * 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));
+}
+/** How long one replica trusts its answer to "does any plugin subscribe" (spec §8.1). */
+export const USAGE_SUBSCRIBERS_TTL_MS = 30_000;
+/**
+ * Test seam (`KernelOverride`): the clock {@link UsageSubscribers} ages its cached answer with
+ * (default `Date.now`); the kernel never provides it.
+ */
+export const USAGE_SUBSCRIBERS_CLOCK = Symbol("USAGE_SUBSCRIBERS_CLOCK");
+/**
+ * Whether the deployment has at least one `usage.report` subscriber ({@link queryUsageSubscribers}
+ * without an org), which decides whether a usage write owes a delivery (transactional outbox spec
+ * §8.1): a usage event written while no plugin subscribes is never reported, later subscribers
+ * included. The answer comes from PG, not from this replica's loaded handlers, so a replica that
+ * has no handler still owes the delivery another replica makes.
+ *
+ * Per-process memoisation of that PG read: kept {@link USAGE_SUBSCRIBERS_TTL_MS} and cleared on
+ * `PLUGINS_CHANGED` (`ExtensionLifecycle` calls {@link invalidate}), so an enabled subscriber is
+ * seen at once, or within 30 s when the bus message is lost. It holds no state another request or
+ * replica relies on.
+ */
+let UsageSubscribers = class UsageSubscribers {
+    kdb;
+    now;
+    cached;
+    /** Bumped by {@link invalidate}: a read that started before it does not refill the cache. */
+    generation = 0;
+    constructor(kdb, now = Date.now) {
+        this.kdb = kdb;
+        this.now = now;
+    }
+    /** Whether any plugin subscribes (cached; the read joins the caller's transaction, if any). */
+    async any() {
+        const at = this.now();
+        const c = this.cached;
+        if (c !== undefined && at - c.at < USAGE_SUBSCRIBERS_TTL_MS)
+            return c.any;
+        const generation = this.generation;
+        const any = (await queryUsageSubscribers(this.kdb.db)).size > 0;
+        if (generation === this.generation)
+            this.cached = { any, at };
+        return any;
+    }
+    /** Forgets the cached answer (a plugin was installed, enabled, upgraded or removed). */
+    invalidate() {
+        this.generation++;
+        this.cached = undefined;
+    }
+};
+UsageSubscribers = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Optional()),
+    __param(1, Inject(USAGE_SUBSCRIBERS_CLOCK))
+], UsageSubscribers);
+export { UsageSubscribers };
+/** {@link UsageSubscribers}: below the extension host, so the model broker and the runtime use it. */
+let UsageSubscribersModule = class UsageSubscribersModule {
+};
+UsageSubscribersModule = __decorate([
+    Module({
+        providers: [UsageSubscribers],
+        exports: [UsageSubscribers],
+    })
+], UsageSubscribersModule);
+export { UsageSubscribersModule };

package/dist/http/api.module.js

@@ -12,6 +12,7 @@ import { AdminAgentsController } from "../admin/admin-agents.controller.js";
 import { AdminConnectorsController } from "../admin/admin-connectors.controller.js";
 import { AdminAuditController } from "../admin/audit.controller.js";
 import { AdminExtensionsController } from "../admin/extensions.controller.js";
+import { OutboxDeadController } from "../admin/outbox-dead.controller.js";
 import { AdminOverviewController } from "../admin/overview.controller.js";
 import { SetupController } from "../admin/setup.controller.js";
 import { AgentsController } from "../agents/agents.controller.js";
@@ -107,6 +108,7 @@ const CONTROLLERS = [
     AdminConnectorsController,
     AdminAuditController,
     AdminOverviewController,
+    OutboxDeadController,
     AdminExtensionsController,
     AdminCatalogController,
     AdminComponentsController,