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

package/dist/runtime/usage-report.js

@@ -9,9 +9,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable, Module, Optional } from "@nestjs/common";
-import { DelayedError, Job, UnrecoverableError, } from "bullmq";
+import { DelayedError, Job, UnrecoverableError } from "bullmq";
 import { sql } from "kysely";
-import { enabledExtensionsQuery } from "../extensions/enabled.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { deepFreeze, errMsg, HookNeedsConfigError, } from "../extensions/hooks.js";
 import { ExtensionHost } from "../extensions/host.js";
@@ -19,31 +18,13 @@ import { STALE_RECONCILE_PERIODS } from "../extensions/lifecycle-topics.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { LockService } from "../infra/lock/lock.service.js";
-import { QueueModule } from "../infra/queue/queue.module.js";
 import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { deliveryRowOfChildRun } from "./subagents/child.js";
-/** Queue of `usage.report` deliveries (no `:` in the name). */
-export const USAGE_REPORT_QUEUE = "cap-kernel-usage-report";
-/** One job per `usage` event (no `:`: conversation ids are UUIDs, seq is a number). */
-export const usageReportJobId = (conversationId, seq) => `usage-${conversationId}-${seq}`;
-/** First attempt plus 5 retries (F11). */
-export const USAGE_REPORT_ATTEMPTS = 6;
-/** Retry backoff: 2 s, doubling (2, 4, 8, 16, 32 s). */
-export const USAGE_REPORT_BACKOFF_MS = 2000;
-/** Optional provider: the {@link UsageReportRetry} instead of the defaults above (tests). */
-export const USAGE_REPORT_RETRY = Symbol("USAGE_REPORT_RETRY");
-/** Failed jobs (given up) are kept for inspection, at most {@link KEEP_FAILED_MAX} of them. */
-const KEEP_FAILED_S = 7 * 86_400;
-/** Upper bound on kept failed jobs (I-2): a long outage of a billing endpoint cannot grow Redis. */
-const KEEP_FAILED_MAX = 100_000;
+import { modelUsageJobId, queryUsageSubscribers, USAGE_REPORT_ATTEMPTS, USAGE_REPORT_BACKOFF_MS, USAGE_REPORT_JOB, USAGE_REPORT_QUEUE, USAGE_REPORT_RETRY, UsageReportJobsModule, usageReportJobId, usageReportJobOpts, } from "./usage-report-jobs.js";
+export { ModelUsageJobs, modelUsageJobId, queryUsageSubscribers, USAGE_REPORT_ATTEMPTS, USAGE_REPORT_BACKOFF_MS, USAGE_REPORT_QUEUE, USAGE_REPORT_RETRY, UsageReportJobsModule, usageReportJobId, } from "./usage-report-jobs.js";
 /** Warnings about a plugin that cannot take deliveries are logged at most once per this window. */
 const WARN_WINDOW_MS = 60_000;
-/**
- * Upper bound on kept finished jobs (Redis memory). At the default retention it only bites above
- * ~1.1 usage events per second sustained for a day; dedupe needs the jobs only for the sweeper overlap.
- */
-const KEEP_COMPLETED_MAX = 100_000;
 /** The sweeper's cron job name (no `:`; every minute, once across replicas). */
 export const USAGE_SWEEP_JOB = "usage-report-sweep";
 /** The maintenance scheduler the sweep ran on before it became a `@LockedCron` (retired). */
@@ -57,38 +38,6 @@ export const USAGE_SWEEP_LAG_MS = 30_000;
  */
 export const USAGE_SWEEP_OVERLAP_MS = 10 * 60_000;
 const SWEEP_PAGE = 500;
-const JOB = "usage-report";
-/**
- * Plugins that subscribe to `usage.report` according to deployment state: an approved permission
- * snapshot that declares the `usage.report` hook, for a plugin the deployment still knows: an enabled
- * install, or a config-declared plugin with a replica status row that is not `unloaded`. With `orgId`, only plugins
- * the organization enabled (org config rows and required bootstrap plugins).
- */
-export async function queryUsageSubscribers(db, orgId) {
-    let q = db
-        .selectFrom("extension_permission_snapshots as s")
-        .select("s.plugin")
-        .where(sql `s.permissions -> 'permissions' -> 'hooks' ? 'usage.report'`)
-        .where((eb) => eb.or([
-        eb.exists(eb
-            .selectFrom("extension_installs as i")
-            .select(sql `1`.as("one"))
-            .whereRef("i.name", "=", "s.plugin")
-            .where("i.desired_state", "=", "enabled")),
-        // config-declared plugins still declared (and not unloaded) on some replica; installs are
-        // covered by desired_state above (their replica rows linger as `unloaded` when disabled)
-        eb.exists(eb
-            .selectFrom("extension_replica_status as r")
-            .select(sql `1`.as("one"))
-            .whereRef("r.plugin", "=", "s.plugin")
-            .where("r.source", "=", "config")
-            .where("r.state", "<>", "unloaded")),
-    ]));
-    if (orgId !== undefined) {
-        q = q.where("s.plugin", "in", enabledExtensionsQuery(db, orgId));
-    }
-    return new Set((await q.execute()).map((r) => r.plugin));
-}
 /**
  * Of `plugins`, those that are **definitely** unservable right now (I-2, N-3): live replicas report
  * them (a `extension_replica_status` row with a heartbeat newer than `staleSeconds`), no live row is
@@ -128,6 +77,10 @@ class Undeliverable extends Error {
         this.name = "Undeliverable";
     }
 }
+/** A job's identity: its `usage` event or its `model_usage` row. */
+const keyOf = (d) => d.usageId !== undefined
+    ? { usageId: d.usageId }
+    : { conversationId: d.conversationId, seq: d.seq };
 /**
  * The next `pending` set (m-2 fence): plugins that failed now, narrowed to what the stored job data
  * still lists. A plugin another (stalled-over) execution already delivered never comes back.
@@ -159,11 +112,18 @@ export function narrowPending(stored, failed) {
  *   most 100 000. Each call runs through the instance's `inflight.run`, limited by `hooks.timeoutMs`;
  *   when this replica stops, in-flight calls are aborted and the job goes back to the queue without
  *   using up an attempt.
- * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`). Nothing is written to the event
- * log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
+ * Handlers must be idempotent by `eventId` (`<conversationId>/<seq>`, or a `model_usage` row id).
+ * Nothing is written to the event log (never model-visible). Compaction calls log usage too (`purpose: "compaction"`) and are reported,
  * as are conversation title calls (`purpose: "title"`, no run: `runId` is "") and `WebFetch`
  * extraction calls (`purpose: "web_fetch"`).
  * Single-step eval replays and judge requests log no usage: not reported (M7).
+ * - **Model usage outside conversations** (spec B §5.4): each `ctx.models.embed` call writes a
+ *   `model_usage` row; on its `model_usage.recorded` event `ModelUsageJobs` (`usage-report-jobs.ts`)
+ *   enqueues job `usage-model-<rowId>` (only while some plugin subscribes); the payload
+ *   (`purpose: "embedding"`, `eventId` = the row id, the calling `extension`, no conversation fields)
+ *   is read from the row when the job runs, and the row's `reported_at` is set once nothing is left
+ *   to deliver; a job that gives up after its last attempt sets `report_failed_at`. The sweep
+ *   re-enqueues recent rows that are neither (see {@link sweep}).
  */
 let UsageReporter = class UsageReporter {
     kdb;
@@ -226,17 +186,8 @@ let UsageReporter = class UsageReporter {
     subscribers(orgId) {
         return queryUsageSubscribers(this.db, orgId);
     }
-    jobOpts(conversationId, seq) {
-        return {
-            jobId: usageReportJobId(conversationId, seq),
-            attempts: this.retry.attempts,
-            backoff: { type: "exponential", delay: this.retry.backoffMs },
-            removeOnComplete: {
-                age: this.config.get().hooks.usageReportKeepHours * 3600,
-                count: KEEP_COMPLETED_MAX,
-            },
-            removeOnFail: { age: KEEP_FAILED_S, count: KEEP_FAILED_MAX },
-        };
+    jobOpts(jobId) {
+        return usageReportJobOpts(jobId, this.retry, this.config.get().hooks.usageReportKeepHours);
     }
     /**
      * Enqueues the delivery of one `usage` event. Returns without a job when no plugin subscribes.
@@ -252,7 +203,7 @@ let UsageReporter = class UsageReporter {
         try {
             if ((await this.subscribers()).size === 0)
                 return;
-            await this.queue.add(JOB, { conversationId, seq }, this.jobOpts(conversationId, seq));
+            await this.queue.add(USAGE_REPORT_JOB, { conversationId, seq }, this.jobOpts(usageReportJobId(conversationId, seq)));
         }
         catch (err) {
             this.log.warn("cannot enqueue usage report", { conversationId, seq, err });
@@ -261,7 +212,10 @@ let UsageReporter = class UsageReporter {
     /**
      * One sweep (R13): re-enqueues the `usage` events created in `[watermark - overlap, now - lag]` in
      * pages, then advances the watermark to `now - lag`. With no subscriber it only advances. The first
-     * sweep starts at `now - lag - overlap`. Returns the number of events offered to the queue.
+     * sweep starts at `now - lag - overlap`. Also re-enqueues the `model_usage` rows of the same
+     * window that are neither reported nor given up (spec B §5.4),
+     * or, with no subscriber, marks those rows reported (nobody to deliver to). Returns the number of
+     * events and rows offered to the queue.
      */
     async sweep(opts = {}) {
         // bounds and keyset as full-precision timestamp text (microseconds), computed with the DB clock
@@ -278,7 +232,8 @@ let UsageReporter = class UsageReporter {
             .executeTakeFirst();
         const watermark = row?.watermark ?? to;
         let offered = 0;
-        if ((await this.subscribers()).size > 0) {
+        const subscribed = (await this.subscribers()).size > 0;
+        if (subscribed) {
             let after;
             for (;;) {
                 let q = this.db
@@ -298,9 +253,9 @@ let UsageReporter = class UsageReporter {
                     .execute();
                 if (page.length > 0) {
                     await this.queue.addBulk(page.map((r) => ({
-                        name: JOB,
+                        name: USAGE_REPORT_JOB,
                         data: { conversationId: r.conversation_id, seq: Number(r.seq) },
-                        opts: this.jobOpts(r.conversation_id, Number(r.seq)),
+                        opts: this.jobOpts(usageReportJobId(r.conversation_id, Number(r.seq))),
                     })));
                     offered += page.length;
                 }
@@ -310,6 +265,7 @@ let UsageReporter = class UsageReporter {
                 after = { at: last.at, conv: last.conversation_id, seq: String(last.seq) };
             }
         }
+        offered += await this.sweepModelUsage(watermark, to, subscribed);
         await this.db
             .insertInto("usage_report_sweep")
             .values({ id: 1, watermark: sql `${to}::timestamptz` })
@@ -320,6 +276,51 @@ let UsageReporter = class UsageReporter {
             .execute();
         return offered;
     }
+    /**
+     * The `model_usage` half of {@link sweep}: rows neither reported nor given up that occurred in
+     * the same window as the events (`[watermark - overlap, to]`), oldest first. Bounded like the
+     * event sweep, so a row whose job failed for good is never offered again, even after its failed
+     * job left Redis (no repeated backlog, no second delivery to plugins already served).
+     */
+    async sweepModelUsage(watermark, to, subscribed) {
+        if (!subscribed) {
+            await this.db
+                .updateTable("model_usage")
+                .set({ reported_at: sql `now()` })
+                .where("reported_at", "is", null)
+                .where(sql `occurred_at <= ${to}::timestamptz`)
+                .execute();
+            return 0;
+        }
+        let offered = 0;
+        let after;
+        for (;;) {
+            let q = this.db
+                .selectFrom("model_usage")
+                .select(["id", sql `occurred_at::text`.as("at")])
+                .where("reported_at", "is", null)
+                .where("report_failed_at", "is", null)
+                .where(sql `occurred_at >= ${watermark}::timestamptz - make_interval(secs => ${USAGE_SWEEP_OVERLAP_MS / 1000})`)
+                .where(sql `occurred_at <= ${to}::timestamptz`);
+            if (after) {
+                q = q.where(sql `(occurred_at, id) > (${after.at}::timestamptz, ${after.id}::uuid)`);
+            }
+            const page = await q.orderBy("occurred_at").orderBy("id").limit(SWEEP_PAGE).execute();
+            if (page.length > 0) {
+                await this.queue.addBulk(page.map((r) => ({
+                    name: USAGE_REPORT_JOB,
+                    data: { usageId: r.id },
+                    opts: this.jobOpts(modelUsageJobId(r.id)),
+                })));
+                offered += page.length;
+            }
+            const last = page.at(-1);
+            if (!last || page.length < SWEEP_PAGE)
+                break;
+            after = { at: last.at, id: last.id };
+        }
+        return offered;
+    }
     /**
      * Starts consuming (worker role only): `worker` is the `@Processor` worker of
      * {@link USAGE_REPORT_QUEUE} (built with the run queue's job lock and stalled detection).
@@ -344,14 +345,17 @@ let UsageReporter = class UsageReporter {
         const final = j.attemptsMade >= (j.opts.attempts ?? 1);
         const fields = {
             jobId: j.id,
-            conversationId: j.data.conversationId,
-            seq: j.data.seq,
+            ...(j.data.usageId !== undefined
+                ? { usageId: j.data.usageId }
+                : { conversationId: j.data.conversationId, seq: j.data.seq }),
             pending: j.data.pending,
             attempt: j.attemptsMade,
             error: err.message,
         };
-        if (final)
+        if (final) {
             this.log.error("usage report given up after retries", fields);
+            void this.markFailed(j.data);
+        }
         else
             this.log.warn("usage report attempt failed; retrying", fields);
     }
@@ -366,6 +370,67 @@ let UsageReporter = class UsageReporter {
         this.worker = undefined;
         await w?.close().catch(() => { });
     }
+    /** The payload of a job: a `usage` event's or a `model_usage` row's; null when it is gone. */
+    payloadOfJob(data) {
+        return data.usageId !== undefined
+            ? this.payloadOfUsage(data.usageId)
+            : this.payloadOf(data.conversationId, data.seq);
+    }
+    /**
+     * The payload of one `model_usage` row (spec B §5.4): purpose `embedding`, the calling extension,
+     * no conversation fields; `eventId` is the row id. Null when the row no longer exists.
+     */
+    async payloadOfUsage(id) {
+        const row = await this.db
+            .selectFrom("model_usage")
+            .select(["id", "org_id", "extension", "provider", "model", "input_tokens", "occurred_at"])
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        return {
+            eventId: row.id,
+            purpose: "embedding",
+            orgId: row.org_id,
+            extension: row.extension,
+            provider: row.provider,
+            model: row.model,
+            usage: {
+                inputTokens: row.input_tokens,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                cacheWriteTokens: 0,
+            },
+            occurredAt: new Date(row.occurred_at).toISOString(),
+        };
+    }
+    /** A `model_usage` job is done (delivered, or nothing left to deliver to): marks the row. */
+    async markReported(data) {
+        if (data.usageId === undefined)
+            return;
+        await this.db
+            .updateTable("model_usage")
+            .set({ reported_at: sql `now()` })
+            .where("id", "=", data.usageId)
+            .where("reported_at", "is", null)
+            .execute();
+    }
+    /** A `model_usage` job gave up after its last attempt: the sweep never offers the row again. */
+    async markFailed(data) {
+        if (data.usageId === undefined)
+            return;
+        try {
+            await this.db
+                .updateTable("model_usage")
+                .set({ report_failed_at: sql `now()` })
+                .where("id", "=", data.usageId)
+                .where("reported_at", "is", null)
+                .execute();
+        }
+        catch (err) {
+            this.log.warn("cannot mark a model usage report as given up", { usageId: data.usageId, err });
+        }
+    }
     /** The payload of one usage event, read from the log; null when the event no longer exists. */
     async payloadOf(conversationId, seq) {
         const row = await this.db
@@ -435,8 +500,7 @@ let UsageReporter = class UsageReporter {
         const allowed = stored === undefined ? undefined : [...stored, ...Object.keys(storedDropped)];
         const keep = [...dropped].filter(([p]) => allowed === undefined || allowed.includes(p));
         const out = {
-            conversationId: j.data.conversationId,
-            seq: j.data.seq,
+            ...keyOf(j.data),
             pending: narrowPending(allowed, next),
             ...(keep.length > 0 && { dropped: Object.fromEntries(keep) }),
         };
@@ -445,22 +509,24 @@ let UsageReporter = class UsageReporter {
     }
     /** One delivery job (the `@Processor` of {@link USAGE_REPORT_QUEUE} calls it). */
     async process(j, token) {
-        const { conversationId, seq } = j.data;
-        const payload = await this.payloadOf(conversationId, seq);
+        const payload = await this.payloadOfJob(j.data);
+        // conversation (or org) deleted meanwhile: nothing to report
         if (payload === null)
-            return; // conversation deleted meanwhile: nothing to report
+            return;
         const subscribers = await this.subscribers(payload.orgId);
         if (j.data.pending === undefined) {
             // first attempt: the targets come from deployment state, recorded so later attempts (on any
             // replica) deliver exactly the plugins that have not succeeded yet
             const targets = [...subscribers];
-            await j.updateData({ conversationId, seq, pending: targets });
+            await j.updateData({ ...keyOf(j.data), pending: targets });
             j.data.pending = targets;
         }
         // plugins the organization disabled meanwhile are dropped (not a failure)
         const targets = (j.data.pending ?? []).filter((p) => subscribers.has(p));
-        if (targets.length === 0)
+        if (targets.length === 0) {
+            await this.markReported(j.data);
             return;
+        }
         const byPlugin = new Map();
         for (const h of this.hooks.handlers("usage.report")) {
             byPlugin.set(h.plugin, [...(byPlugin.get(h.plugin) ?? []), h.handler]);
@@ -539,6 +605,8 @@ let UsageReporter = class UsageReporter {
         // m-1: pending = the dropped plugins only, so a manual retry reaches them and never the
         // plugins already served
         await this.writePending(j, [...allDropped.keys()], allDropped);
+        // delivered to every target still servable (a definite drop is final too): the row is done
+        await this.markReported(j.data);
         const traced = new Map([...allDropped].filter(([p]) => j.data.dropped?.[p] !== undefined));
         if (traced.size === 0)
             return;
@@ -649,9 +717,9 @@ let UsageReportModule = class UsageReportModule {
 };
 UsageReportModule = __decorate([
     Module({
-        imports: [ExtensionsModule, QueueModule.registerQueue(USAGE_REPORT_QUEUE)],
+        imports: [ExtensionsModule, UsageReportJobsModule],
         providers: [UsageReporter],
-        exports: [UsageReporter],
+        exports: [UsageReporter, UsageReportJobsModule],
     })
 ], UsageReportModule);
 export { UsageReportModule };

package/dist/tools/pipeline.js

@@ -11,6 +11,7 @@ import { parseToolKey, ToolError, validateInputForm, validateToolDisplay, } from
 import { Inject, Injectable, Optional } from "@nestjs/common";
 import { EventLog } from "../conversations/event-log.js";
 import { ToolViewSchema } from "../conversations/events.js";
+import { ApiError } from "../errors.js";
 import { EffectiveConfigs, NEEDS_CONFIG_REASON } from "../extensions/effective-config.js";
 import { clipText } from "../extensions/hooks.js";
 import { ExtensionHost } from "../extensions/host.js";
@@ -1012,6 +1013,11 @@ let ToolPipeline = class ToolPipeline {
     thrown(key, e) {
         if (e instanceof ToolError)
             return { kind: "error", message: e.message };
+        // an extension tool's ctx.models.embed denied by a policy hook (spec B §5.4): the model sees the
+        // deny text (sanitized reason), as for a denied tool call, not a generic failure
+        if (e instanceof ApiError && e.code === "model.hook_denied") {
+            return { kind: "error", message: e.message };
+        }
         // 提供工具的插件实例在调用进行中被撤销（停用 / 升级），排空时限到后中止（C17）
         if (e instanceof ExtensionUnloadedError) {
             this.deps.log.warn("tool call aborted: plugin unloaded", { toolKey: key, plugin: e.plugin });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.6",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {
@@ -64,14 +64,14 @@
     "yaml": "^2.9.1",
     "yauzl": "3.4.0",
     "zod": "^4.6.7",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.3"
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.4"
   },
   "devDependencies": {
     "@langchain/langgraph-checkpoint-validation": "^1.2.0",
     "@types/pg": "^8.23.1",
     "@types/semver": "^7.8.0",
     "@types/yauzl": "3.4.0",
-    "@capybara-hq/testing": "0.1.0-rc.6"
+    "@capybara-hq/testing": "0.1.0-rc.7"
   },
   "scripts": {
     "build": "tsc -b"

package/src/migrations/0089_model_kinds_usage.sql

@@ -0,0 +1,38 @@
+-- Model platform providers (spec 2026-11-06-model-platform-providers-design.md). Expand-only: two
+-- new tables, nothing existing changes.
+
+-- 0089, spec §5.3: models disabled on two layers. `org_id` null is the platform's list (the super
+-- admin; such a model is invisible to every org), otherwise the org's own list (an org admin, among
+-- the models the platform left on). No row means the model is enabled; a model a provider lists
+-- later is enabled everywhere until someone disables it. Keyed on the model id, so a row applies to
+-- whichever list the org sees (the platform's config or the org's own copy); an id the list does
+-- not contain is kept harmlessly.
+CREATE TABLE IF NOT EXISTS model_disabled (
+  org_id text NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  provider text NOT NULL,
+  model text NOT NULL,
+  disabled_by text REFERENCES accounts(id) ON DELETE SET NULL,
+  disabled_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS model_disabled_scope_key
+  ON model_disabled ((coalesce(org_id, '')), provider, model);
+
+-- 0089, spec §5.4: model usage outside conversations (an extension's `ctx.models.embed` call). One
+-- row per call; `reported_at` is set once the `usage.report` job for the row (eventId = id) has
+-- nothing left to deliver (delivered, no subscriber, or a definite drop); `report_failed_at` once
+-- the job gave up after its last attempt. The sweeper re-enqueues recent rows where both are null.
+CREATE TABLE IF NOT EXISTS model_usage (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id text NOT NULL REFERENCES orgs(id) ON DELETE CASCADE,
+  extension text NOT NULL,
+  purpose text NOT NULL,
+  provider text NOT NULL,
+  model text NOT NULL,
+  input_tokens integer NOT NULL,
+  occurred_at timestamptz NOT NULL DEFAULT now(),
+  reported_at timestamptz NULL,
+  report_failed_at timestamptz NULL
+);
+CREATE INDEX IF NOT EXISTS model_usage_org_time ON model_usage (org_id, occurred_at DESC);
+CREATE INDEX IF NOT EXISTS model_usage_unreported ON model_usage (occurred_at)
+  WHERE reported_at IS NULL AND report_failed_at IS NULL;