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

package/dist/admin/admin.module.js

@@ -10,6 +10,7 @@ import { ChannelsModule } from "../channels/channels.module.js";
 import { TitlesModule } from "../conversations/titles.js";
 import { EvalsModule } from "../evals/evals.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { LifecycleHooksModule } from "../extensions/lifecycle-hooks.js";
 import { IdentityModule } from "../identity/identity.module.js";
 import { InboxModule } from "../inbox/inbox.module.js";
 import { ModelsModule } from "../models/models.module.js";
@@ -48,6 +49,7 @@ AdminModule = __decorate([
             TitlesModule,
             UsageReportModule,
             EvalsModule,
+            LifecycleHooksModule,
             // the price table of the usage aggregate
             ModelsModule,
         ],

package/dist/admin/health.service.d.ts

@@ -4,7 +4,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { type LiveReplica, ReplicaPresence } from "../infra/presence/replica-presence.js";
 import type { KernelLogger } from "../log.js";
 /** The kernel's own queues, in the order the overview lists them (extension queues are not read). */
-export declare const KERNEL_QUEUE_NAMES: readonly ["cap-kernel-runs", "cap-kernel-subagent-runs", "cap-kernel-channels", "cap-kernel-maintenance", "cap-kernel-plugin-scope", "cap-kernel-titles", "cap-kernel-usage-report", "cap-kernel-evals"];
+export declare const KERNEL_QUEUE_NAMES: readonly ["cap-kernel-runs", "cap-kernel-subagent-runs", "cap-kernel-channels", "cap-kernel-maintenance", "cap-kernel-plugin-scope", "cap-kernel-titles", "cap-kernel-usage-report", "cap-kernel-evals", "cap-kernel-lifecycle"];
 /** How long each source's reads may take before the answer marks it unavailable. */
 export declare const HEALTH_READ_TIMEOUT_MS = 3000;
 /** A live replica as the overview shows it. */
@@ -97,7 +97,7 @@ export declare class AdminHealthService {
     private readonly redis;
     private readonly log;
     private readonly queues;
-    constructor(presence: Pick<ReplicaPresence, "live">, db: KernelDb, redis: Pick<Redis, "zcount" | "status">, log: Pick<KernelLogger, "warn">, runs: Queue, subagentRuns: Queue, channels: Queue, maintenance: Queue, pluginScope: Queue, titles: Queue, usageReport: Queue, evals: Queue);
+    constructor(presence: Pick<ReplicaPresence, "live">, db: KernelDb, redis: Pick<Redis, "zcount" | "status">, log: Pick<KernelLogger, "warn">, runs: Queue, subagentRuns: Queue, channels: Queue, maintenance: Queue, pluginScope: Queue, titles: Queue, usageReport: Queue, evals: Queue, lifecycle: Queue);
     read(): Promise<AdminHealth>;
     private readRedis;
     private readDb;

package/dist/admin/health.service.js

@@ -14,6 +14,7 @@ import { PLUGIN_SCOPE_QUEUE } from "../catalog/scope-sync.js";
 import { CHANNEL_QUEUE_NAME } from "../channels/jobs.js";
 import { TITLE_QUEUE } from "../conversations/titles.js";
 import { EVAL_QUEUE_NAME } from "../evals/jobs.js";
+import { LIFECYCLE_QUEUE } from "../extensions/lifecycle-hooks.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { ReplicaPresence } from "../infra/presence/replica-presence.js";
 import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
@@ -31,6 +32,7 @@ export const KERNEL_QUEUE_NAMES = [
     TITLE_QUEUE,
     USAGE_REPORT_QUEUE,
     EVAL_QUEUE_NAME,
+    LIFECYCLE_QUEUE,
 ];
 /** How long each source's reads may take before the answer marks it unavailable. */
 export const HEALTH_READ_TIMEOUT_MS = 3_000;
@@ -58,7 +60,7 @@ let AdminHealthService = class AdminHealthService {
     redis;
     log;
     queues;
-    constructor(presence, db, redis, log, runs, subagentRuns, channels, maintenance, pluginScope, titles, usageReport, evals) {
+    constructor(presence, db, redis, log, runs, subagentRuns, channels, maintenance, pluginScope, titles, usageReport, evals, lifecycle) {
         this.presence = presence;
         this.db = db;
         this.redis = redis;
@@ -73,6 +75,7 @@ let AdminHealthService = class AdminHealthService {
             titles,
             usageReport,
             evals,
+            lifecycle,
         ];
     }
     async read() {
@@ -241,6 +244,7 @@ AdminHealthService = __decorate([
     __param(8, Inject(getQueueToken(PLUGIN_SCOPE_QUEUE))),
     __param(9, Inject(getQueueToken(TITLE_QUEUE))),
     __param(10, Inject(getQueueToken(USAGE_REPORT_QUEUE))),
-    __param(11, Inject(getQueueToken(EVAL_QUEUE_NAME)))
+    __param(11, Inject(getQueueToken(EVAL_QUEUE_NAME))),
+    __param(12, Inject(getQueueToken(LIFECYCLE_QUEUE)))
 ], AdminHealthService);
 export { AdminHealthService };

package/dist/agents/agents.module.js

@@ -8,6 +8,7 @@ import { Module } from "@nestjs/common";
 import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EvalBudgetModule } from "../evals/budget.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { LifecycleHooksModule } from "../extensions/lifecycle-hooks.js";
 import { ModelsModule } from "../models/models.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { ProvidersModule } from "../runtime/providers.js";
@@ -48,6 +49,8 @@ AgentsModule = __decorate([
             // creating from a template: the extension tools and the tier purposes (rulings P4-4, P4-5)
             ExtensionsModule,
             ModelsModule,
+            // the agent delete records `agent.deleted` deliveries
+            LifecycleHooksModule,
         ],
         providers: [
             AgentsService,

package/dist/agents/agents.service.d.ts

@@ -1,5 +1,6 @@
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { EvalBudget } from "../evals/budget.js";
+import { LifecycleHooks } from "../extensions/lifecycle-hooks.js";
 import type { WriteActor } from "../identity/write-actor.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -92,6 +93,8 @@ export declare class AgentsService {
     private readonly evalBudget;
     /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
     private readonly setupRequests;
+    /** Records `agent.deleted` for the subscribing plugins in the delete's transaction. */
+    private readonly lifecycle;
     constructor(db: KernelDb, lookup: AgentLookup, tools: Pick<ToolRegistry, "checkDisabled">, 
     /**
      * Cancels the agent's pending skill requests: all of them when it is deleted, share requests
@@ -105,7 +108,9 @@ export declare class AgentsService {
     /** Cancels the deleted agent's running eval runs (in the delete's transaction). */
     evalBudget: Pick<EvalBudget, "cancelRuns">, 
     /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
-    setupRequests: Pick<PendingConnectorRequests, "settleIn" | "retargetIn">);
+    setupRequests: Pick<PendingConnectorRequests, "settleIn" | "retargetIn">, 
+    /** Records `agent.deleted` for the subscribing plugins in the delete's transaction. */
+    lifecycle: Pick<LifecycleHooks, "recordIn">);
     /**
      * Checks the turned-off tools and the policies (tools default-on spec §2): `disabledTools` must
      * name existing builtins, extensions and connectors (`ToolRegistry.checkDisabled`); `toolPolicies`

package/dist/agents/agents.service.js

@@ -13,7 +13,9 @@ import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { EvalBudget } from "../evals/budget.js";
+import { LifecycleHooks } from "../extensions/lifecycle-hooks.js";
 import { audit } from "../identity/audit.js";
+import { afterCommit } from "../infra/database/after-commit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
@@ -279,6 +281,7 @@ let AgentsService = class AgentsService {
     txHost;
     evalBudget;
     setupRequests;
+    lifecycle;
     constructor(db, lookup, tools, 
     /**
      * Cancels the agent's pending skill requests: all of them when it is deleted, share requests
@@ -292,7 +295,9 @@ let AgentsService = class AgentsService {
     /** Cancels the deleted agent's running eval runs (in the delete's transaction). */
     evalBudget, 
     /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
-    setupRequests) {
+    setupRequests, 
+    /** Records `agent.deleted` for the subscribing plugins in the delete's transaction. */
+    lifecycle) {
         this.db = db;
         this.lookup = lookup;
         this.tools = tools;
@@ -302,6 +307,7 @@ let AgentsService = class AgentsService {
         this.txHost = txHost;
         this.evalBudget = evalBudget;
         this.setupRequests = setupRequests;
+        this.lifecycle = lifecycle;
     }
     /**
      * Checks the turned-off tools and the policies (tools default-on spec §2): `disabledTools` must
@@ -746,6 +752,8 @@ let AgentsService = class AgentsService {
         });
         // 评测集的 agent 删除后其评测运行不再花钱：显式取消（审计带原因）
         await this.evalBudget.cancelRuns({ orgId, agentId }, { accountId: actorAccountId, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, "agent_deleted");
+        // plugins learn of the delete durably: owed here, delivered by the outbox after the commit
+        await this.lifecycle.recordIn("agent.deleted", { orgId, agentId });
         // joins this transaction (mandatory: it relies on the agent row lock taken above)
         return this.skillChanges.cancelPendingForAgent(orgId, agentId, actorAccountId, "agent_deleted", actorTokenId);
     }
@@ -907,6 +915,7 @@ AgentsService = __decorate([
     __param(5, Inject(ProviderRegistry)),
     __param(6, Inject(TransactionHost)),
     __param(7, Inject(EvalBudget)),
-    __param(8, Inject(PendingConnectorRequests))
+    __param(8, Inject(PendingConnectorRequests)),
+    __param(9, Inject(LifecycleHooks))
 ], AgentsService);
 export { AgentsService };

package/dist/catalog/catalog-import.module.js

@@ -8,9 +8,7 @@ import { Module } from "@nestjs/common";
 import { ClientModule } from "../client/client.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { SuperAdminLockModule } from "../identity/super-admin.js";
-import { QueueModule } from "../infra/queue/queue.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
-import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { StorageModule } from "../storage/storage.module.js";
 import { CatalogService } from "./catalog.service.js";
 import { ComponentPromotion } from "./component-promotion.js";
@@ -37,8 +35,6 @@ CatalogImportModule = __decorate([
             StorageModule,
             // the client build prefix goes with an expired org upload's package (`PluginImport`)
             ClientModule,
-            // a failed post-import platform sync enqueues the migration job (`PluginImport.syncPlatform`)
-            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
         providers: [
             CatalogSourceLock,

package/dist/catalog/catalog-scope.service.d.ts

@@ -1,4 +1,3 @@
-import type { Queue } from "bullmq";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionAdmin } from "../extensions/admin-view.js";
@@ -7,11 +6,14 @@ import { PluginInstallLock } from "../extensions/locks.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { type ThemePreview } from "../themes/theme-usage.js";
 import { type ActorOpts, type CatalogItemView, CatalogService } from "./catalog.service.js";
 import { type ComponentKind } from "./component-state.js";
+import { CatalogItemLock } from "./locks.js";
+import { PlatformComponents } from "./platform-components.js";
 import { type PluginConfirmResult, PluginImport } from "./plugin-import.js";
 import { PluginInstaller } from "./plugin-install.js";
 import { PlatformPluginUpdater } from "./plugin-upgrade.js";
@@ -85,10 +87,10 @@ export type ScopeTarget = {
 export declare function conflictsError(conflicts: ScopePreview["conflicts"]): ApiError;
 /**
  * The super admin's plugin scope and deployment-level disable (plugin and component management
- * spec §4.1, §5 rules 2-4 and 8), and the import confirm that enqueues the scope sync of the item it
+ * spec §4.1, §5 rules 2-4 and 8), and the import confirm that owes the scope sync of the item it
  * wrote. A change is previewed, then confirmed with the preview's `scopeHash`, recomputed under the
  * item row lock (a difference -> 409 `plugin.scope_stale`); it bumps `scope_version`, audits
- * `catalog.scope_changed` and, after the commit, enqueues the item's scope sync, which installs or
+ * `catalog.scope_changed` and owes the item's scope sync in the same transaction, which installs or
  * uninstalls in every org. Disabling keeps the scope, its org list and the org switches, so
  * re-enabling (no hash needed) reinstalls where it was on. Builtin items -> 409 `plugin.builtin`.
  * Stateless, shared by every replica.
@@ -98,6 +100,10 @@ export declare class CatalogScopeService {
     private readonly adminLock;
     private readonly catalog;
     private readonly pluginImport;
+    /** A confirmed first version's platform components (written in the confirming commit). */
+    private readonly platform;
+    /** The import's item name lock, taken by the confirming commit before the item row. */
+    private readonly itemLock;
     private readonly installer;
     private readonly extensions;
     private readonly ops;
@@ -109,23 +115,27 @@ export declare class CatalogScopeService {
     private readonly installLock;
     /** This replica's reconcile once a confirmed extension is enabled (before the scope sync). */
     private readonly lifecycle;
-    /** The removed org plugin's cleanup job, backing the take-out of P3-21 (pre-flight F9). */
-    private readonly maintenance;
+    /** Owes the scope syncs and the removed org plugin's cleanup (P3-21, pre-flight F9). */
+    private readonly outbox;
     private readonly log;
     readonly txHost: TransactionHost;
-    constructor(kdb: KernelDb, adminLock: SuperAdminLock, catalog: CatalogService, pluginImport: PluginImport, installer: PluginInstaller, extensions: ExtensionAdmin, ops: ExtensionAdminOps, sync: PluginScopeSync, updater: PlatformPluginUpdater, 
+    constructor(kdb: KernelDb, adminLock: SuperAdminLock, catalog: CatalogService, pluginImport: PluginImport, 
+    /** A confirmed first version's platform components (written in the confirming commit). */
+    platform: PlatformComponents, 
+    /** The import's item name lock, taken by the confirming commit before the item row. */
+    itemLock: CatalogItemLock, installer: PluginInstaller, extensions: ExtensionAdmin, ops: ExtensionAdminOps, sync: PluginScopeSync, updater: PlatformPluginUpdater, 
     /** The owner org's lock: an org admin withdrawing its pending upload (ruling P3-10). */
     orgLock: OrgLock, 
     /** The per-name install lock a reject / withdraw releases the name claim under (M1). */
     installLock: PluginInstallLock, 
     /** This replica's reconcile once a confirmed extension is enabled (before the scope sync). */
     lifecycle: ExtensionLifecycle, 
-    /** The removed org plugin's cleanup job, backing the take-out of P3-21 (pre-flight F9). */
-    maintenance: Pick<Queue, "add">, log: KernelLogger, txHost: TransactionHost);
+    /** Owes the scope syncs and the removed org plugin's cleanup (P3-21, pre-flight F9). */
+    outbox: Pick<OutboxService, "add">, log: KernelLogger, txHost: TransactionHost);
     private get db();
     /**
      * Confirms a staged import ({@link PluginImport.confirm}: installs and enables the extension,
-     * writes the new item's scope), then enqueues the item's scope sync when its scope turns it on
+     * writes the new item's scope), then owes the item's scope sync when its scope turns it on
      * by itself (`all` or `named`; an `optional` item is on only where an org admin switches it on).
      */
     confirmImport(actor: string, stagingId: string, input: Parameters<PluginImport["confirm"]>[2], opts?: ActorOpts): Promise<PluginConfirmResult>;
@@ -148,9 +158,10 @@ export declare class CatalogScopeService {
      * pending version (withdrawn, rejected, replaced by one without an extension) -> 409
      * `extension.not_pending`.
      *
-     * A first version: its extension installed, its permissions approved, enabled, then (one
-     * transaction) the item stops waiting and the owner is told (`upload_confirmed`); after the
-     * commit its platform components are written and the scope sync enqueued. Each step re-reads
+     * A first version: its platform components planned and their files copied (keyed by content),
+     * its extension installed, its permissions approved, enabled, then (one transaction) the item
+     * stops waiting, its platform component rows are written and the owner is told
+     * (`upload_confirmed`); after the commit the scope sync is owed. Each step re-reads
      * the item under its row lock: removed meanwhile -> 409 `catalog.item_removed`, the pending
      * version replaced -> `extension.approval_stale`; the extension this confirmation installed is
      * then taken out again. A new version: the platform update to it
@@ -160,8 +171,8 @@ export declare class CatalogScopeService {
      */
     private confirmOrgUpload;
     /**
-     * {@link confirmOrgUpload} under the item lock; returns the confirmed first version (its
-     * platform components and scope sync follow after), null for a new version.
+     * {@link confirmOrgUpload} under the item lock; returns the confirmed first version (its scope
+     * sync follows after), null for a new version.
      */
     private confirmLocked;
     /** The item is live and its first version confirmed (no longer awaiting). */
@@ -186,18 +197,33 @@ export declare class CatalogScopeService {
     /**
      * An extension a confirmation installed whose item was removed or replaced meanwhile is taken
      * out again (disabled, uninstalled; P3-21), and the name claim released when the item is gone
-     * (ruling P3-37). Inline and best effort (a failure is logged); a removed item's cleanup job
-     * (`owned-plugin-cleanup-<itemId>`, idempotent) is enqueued as well, so a failed take-out is
-     * retried (pre-flight F9).
+     * (ruling P3-37), in one transaction ({@link takeOutIn}). Inline (a failure is logged): when the
+     * take-out fails, a removed item's cleanup job (`owned-plugin-cleanup-<itemId>`, idempotent) is
+     * owed instead, so the job retries it (pre-flight F9). That owe is the last resort: when it
+     * fails too (PG unavailable) nothing retries the take-out, and it is logged as an error.
      */
     private takeOut;
-    /** Releases the name claim of a removed item (nothing installed under it any more). */
-    private releaseIfGone;
+    /**
+     * {@link takeOut}'s transaction, in the global lock order (ruling P3-50): the super admin lock,
+     * the item row, then the extension's install lock (taken by the disable): disabled,
+     * uninstalled, and the name claim released when the item is gone.
+     */
+    private takeOutIn;
+    /**
+     * Owes the cleanup of a removed item; a live item owes nothing (a removal committing later owes
+     * its own).
+     */
+    private oweCleanupIfGone;
     /** The item is still live and pending with `version` (row lock), else 409 (P3-21). */
     private stillPending;
     /** {@link stillPending} in the caller's transaction; returns the owner org. */
     private pendingRow;
-    /** A confirmed first version: the item stops waiting, the owner is told (`upload_confirmed`). */
+    /**
+     * A confirmed first version: the item stops waiting, its platform component rows are written
+     * from `components` (a component changed since they were planned -> 409
+     * `extension.approval_stale`: confirm again), the owner is told (`upload_confirmed`). The
+     * import's item name lock before the item row, as an import's commit takes them (ruling P3-50).
+     */
     private finishFirstVersion;
     /**
      * The super admin rejects an org upload's pending version (ruling P3-10, `reason` shown to the
@@ -238,8 +264,8 @@ export declare class CatalogScopeService {
     /**
      * Writes an org-owned plugin's 可共享 flag and copies it to its component rows (ruling P3-2).
      * Turning it off narrows an `optional` / `all` plugin, and each component with its own such
-     * scope, to the owner plus the orgs where it is on now (ruling P3-25), and enqueues the item's
-     * scope sync after the commit. The caller authorizes (the owner org's admin, Task 7). A platform
+     * scope, to the owner plus the orgs where it is on now (ruling P3-25), and owes the item's
+     * scope sync with it. The caller authorizes (the owner org's admin, Task 7). A platform
      * item (no owner) or a missing one -> 404.
      */
     setShareable(itemId: string, shareable: boolean, actor?: string | null): Promise<void>;
@@ -247,19 +273,30 @@ export declare class CatalogScopeService {
      * Adds one org to a `named` item's list in the caller's transaction (an approved `access`
      * request, spec §5.1 rule 2): nobody loses access, so no preview. The item row is locked; it
      * must be live and not builtin (404 / `plugin.builtin`). Bumps `scope_version`, audits
-     * `catalog.scope_changed` and enqueues the item's scope sync after the commit. Returns whether
+     * `catalog.scope_changed` and owes the item's scope sync in that transaction. Returns whether
      * the list changed (false: not `named`, or listed already).
      */
     addOrg(actor: string, itemId: string, orgId: string, opts?: ActorOpts & {
         requestId?: string;
     }): Promise<boolean>;
     /**
-     * Enqueues the item's scope sync after a commit made elsewhere (an org upload's confirm,
-     * `OrgPluginUploads`); a failure only warns.
+     * Owes the item's scope sync in the caller's transaction (an ownership transfer, an org upload's
+     * confirm in `OrgPluginUploads`).
      */
     enqueueSync(itemId: string): Promise<void>;
-    /** Enqueues the item's scope sync; a failure only warns (the next change or org sync converges). */
+    /** Owes the item's scope sync in the transaction that changes its scope (outbox spec §8.1). */
     private enqueue;
+    /**
+     * Owes the item's scope sync in a transaction of its own, after a confirmation whose last write
+     * (the extension's deploy, or the platform components) committed outside the scope service: the
+     * sync must not run before the extension it installs is enabled.
+     */
+    private oweSync;
+    /**
+     * Owes the delayed backstop of the item's sync in a transaction of its own (ruling R24): a
+     * permissions confirm writes nothing of the scope service's before its enable.
+     */
+    private oweBackstop;
     /**
      * 409 `theme.platform_default` when a live theme of the item is the platform default and `after`
      * says the change leaves it narrower than `all` or gone (themes spec §7). In the caller's