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

package/dist/inbox/platform-inbox.service.js

@@ -0,0 +1,281 @@
+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 } from "@nestjs/common";
+import { sql } from "kysely";
+import { CatalogService } from "../catalog/catalog.service.js";
+import { CatalogRequestsService } from "../catalog/requests.service.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/** The most items one platform inbox read returns. */
+export const PLATFORM_INBOX_MAX_ITEMS = 100;
+/** The most open scope sync failures one read takes. */
+export const SCOPE_SYNC_FAILURES_LIST_MAX = 200;
+/**
+ * A platform components migration run unfinished this long after its start is stuck (its worker
+ * stopped mid-run; a run takes seconds, and the next one starts at the next worker start or day).
+ */
+export const MIGRATION_RUN_STUCK_MS = 60 * 60_000;
+/** Plugin install statuses of a plugin that is on in the org. */
+const LIVE_INSTALL = ["installing", "installed", "upgrading"];
+/** Every {@link PlatformInboxItem} type, in the order the admin overview lists them. */
+export const PLATFORM_INBOX_TYPES = [
+    "catalog_request",
+    "permission_confirmation",
+    "org_upload_pending",
+    "scope_sync_failed",
+    "platform_migration",
+    "ownership_transferred",
+];
+/**
+ * The super admin's inbox (plugin scope spec §5.1 rule 5, §13.5): what waits on the platform,
+ * gathered from the sources the admin pages read (the 待确认 tab's requests and permission
+ * confirmations), plus the scope sync's open failures and the platform components migration's
+ * latest run. Stateless, read live from PG.
+ */
+let PlatformInboxService = class PlatformInboxService {
+    requests;
+    catalog;
+    kdb;
+    constructor(requests, catalog, kdb) {
+        this.requests = requests;
+        this.catalog = catalog;
+        this.kdb = kdb;
+    }
+    async list() {
+        const [requests, requestCount, pending, failures, failureCount, run, notices, noticeCount] = await Promise.all([
+            this.requests.listDeployment(),
+            this.requests.countPendingDeployment(),
+            this.catalog.list({ pending: true }),
+            this.scopeSyncFailures(),
+            this.countScopeSyncFailures(),
+            this.migrationRun(),
+            this.notices(),
+            this.countNotices(),
+        ]);
+        const all = [
+            ...requests.map((r) => ({
+                type: "catalog_request",
+                id: r.id,
+                createdAt: r.createdAt,
+                request: r,
+            })),
+            ...pending.map((i) => ({
+                type: i.owner.kind === "org" ? "org_upload_pending" : "permission_confirmation",
+                id: i.id,
+                createdAt: i.updatedAt,
+                item: i,
+            })),
+            ...failures.map((f) => ({
+                type: "scope_sync_failed",
+                id: `${f.item.id}/${f.org.id}`,
+                createdAt: f.failedAt,
+                failure: f,
+            })),
+            ...notices.map((n) => ({
+                type: "ownership_transferred",
+                id: n.id,
+                createdAt: n.createdAt,
+                notice: n,
+            })),
+            ...(run === null
+                ? []
+                : [
+                    {
+                        type: "platform_migration",
+                        id: run.id,
+                        createdAt: run.finishedAt ?? run.startedAt,
+                        run,
+                    },
+                ]),
+        ];
+        // newest first; equal times by id (a stable order)
+        all.sort((a, b) => a.createdAt !== b.createdAt
+            ? a.createdAt < b.createdAt
+                ? 1
+                : -1
+            : a.id < b.id
+                ? -1
+                : a.id > b.id
+                    ? 1
+                    : 0);
+        const orgUploads = pending.filter((i) => i.owner.kind === "org").length;
+        const byType = {
+            catalog_request: requestCount,
+            permission_confirmation: pending.length - orgUploads,
+            org_upload_pending: orgUploads,
+            scope_sync_failed: failureCount,
+            platform_migration: run === null ? 0 : 1,
+            ownership_transferred: noticeCount,
+        };
+        const total = Object.values(byType).reduce((a, b) => a + b, 0);
+        const items = all.slice(0, PLATFORM_INBOX_MAX_ITEMS);
+        return { items, truncated: total > items.length, total, byType };
+    }
+    /**
+     * How many items wait (the sidebar's count): the same sources, counted where they can be (the
+     * requests and the failures; the permission confirmations are the catalog's pending list).
+     */
+    async count() {
+        const [requests, pending, failures, run, notices] = await Promise.all([
+            this.requests.countPendingDeployment(),
+            this.catalog.list({ pending: true }),
+            this.countScopeSyncFailures(),
+            this.migrationRun(),
+            this.countNotices(),
+        ]);
+        return requests + pending.length + failures + (run === null ? 0 : 1) + notices;
+    }
+    async countNotices() {
+        const r = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select(sql `count(*)`.as("n"))
+            .where("dismissed_at", "is", null)
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** The open platform notices, newest first, at most {@link PLATFORM_INBOX_MAX_ITEMS}. */
+    async notices() {
+        const rows = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select(["id", "kind", "detail", "created_at"])
+            .where("dismissed_at", "is", null)
+            .orderBy("created_at", "desc")
+            .orderBy("id")
+            .limit(PLATFORM_INBOX_MAX_ITEMS)
+            .execute();
+        return rows.map((r) => ({
+            id: r.id,
+            kind: r.kind,
+            createdAt: r.created_at.toISOString(),
+            detail: r.detail,
+        }));
+    }
+    /**
+     * A super admin dismisses a platform notice (for every super admin). Dismissing one already
+     * dismissed is fine; no notice with that id -> `inbox.notice_not_found`.
+     */
+    async dismissNotice(accountId, id) {
+        if (!UUID_RE.test(id))
+            throw new ApiError("inbox.notice_not_found", "Notice not found");
+        const r = await this.kdb.db
+            .updateTable("platform_notices")
+            .set({ dismissed_at: sql `now()`, dismissed_by: accountId })
+            .where("id", "=", id)
+            .where("dismissed_at", "is", null)
+            .executeTakeFirst();
+        if (r.numUpdatedRows > 0n)
+            return;
+        const exists = await this.kdb.db
+            .selectFrom("platform_notices")
+            .select("id")
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!exists)
+            throw new ApiError("inbox.notice_not_found", "Notice not found");
+    }
+    /**
+     * The open failures still worth a look, joined to their item and org: of a live item and org,
+     * and the pair still differs in the failed direction (a person may have converged it meanwhile):
+     * an install failure while the org has no live install of the item; an uninstall or dependencies
+     * failure while it has one.
+     */
+    failureRows() {
+        return this.kdb.db
+            .selectFrom("plugin_scope_sync_failures as f")
+            .innerJoin("catalog_items as i", "i.id", "f.item_id")
+            .innerJoin("orgs as o", "o.id", "f.org_id")
+            .where("i.deleted_at", "is", null)
+            .where("o.deleted_at", "is", null)
+            .where((eb) => {
+            const live = eb.exists(eb
+                .selectFrom("plugin_installs as p")
+                .select("p.id")
+                .whereRef("p.org_id", "=", "f.org_id")
+                .whereRef("p.item_id", "=", "f.item_id")
+                .where("p.status", "in", [...LIVE_INSTALL]));
+            return eb.or([
+                eb.and([eb("f.op", "=", "install"), eb.not(live)]),
+                eb.and([eb("f.op", "in", ["uninstall", "dependencies"]), live]),
+            ]);
+        });
+    }
+    async countScopeSyncFailures() {
+        const r = await this.failureRows()
+            .select(sql `count(*)`.as("n"))
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** The open scope sync failures ({@link failureRows}), newest first. */
+    async scopeSyncFailures() {
+        const rows = await this.failureRows()
+            .select([
+            "f.item_id",
+            "i.name as item_name",
+            "i.display_name",
+            "f.org_id",
+            "o.name as org_name",
+            "f.op",
+            "f.code",
+            "f.message",
+            "f.failed_at",
+        ])
+            .orderBy("f.failed_at", "desc")
+            .orderBy("f.item_id")
+            .orderBy("f.org_id")
+            .limit(SCOPE_SYNC_FAILURES_LIST_MAX)
+            .execute();
+        return rows.map((r) => ({
+            item: { id: r.item_id, name: r.item_name, displayName: r.display_name },
+            org: { id: r.org_id, name: r.org_name },
+            op: r.op,
+            code: r.code,
+            message: r.message,
+            failedAt: r.failed_at.toISOString(),
+        }));
+    }
+    /**
+     * The latest migration run when it needs a look (see {@link MigrationRunView}); null when it
+     * finished without failed items, is still running, or there was none. An earlier run's failure
+     * is not shown: each run tries every unwritten item again.
+     */
+    async migrationRun() {
+        const run = await this.kdb.db
+            .selectFrom("platform_migration_runs")
+            .select(["id", "started_at", "finished_at", "stats"])
+            .orderBy("started_at", "desc")
+            .orderBy("id", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        if (run === undefined)
+            return null;
+        const failed = run.stats.itemsFailed;
+        const itemsFailed = Array.isArray(failed)
+            ? failed.filter((x) => typeof x === "string")
+            : [];
+        const stuck = run.finished_at === null && run.started_at.getTime() < Date.now() - MIGRATION_RUN_STUCK_MS;
+        if (!stuck && (run.finished_at === null || itemsFailed.length === 0))
+            return null;
+        return {
+            id: run.id,
+            startedAt: run.started_at.toISOString(),
+            finishedAt: run.finished_at?.toISOString() ?? null,
+            stuck,
+            itemsFailed,
+        };
+    }
+};
+PlatformInboxService = __decorate([
+    Injectable(),
+    __param(0, Inject(CatalogRequestsService)),
+    __param(1, Inject(CatalogService)),
+    __param(2, Inject(KernelDb))
+], PlatformInboxService);
+export { PlatformInboxService };
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/dist/inbox/platform-notices.d.ts

@@ -0,0 +1,19 @@
+import type { OwnedRef } from "../catalog/ownership.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+export type PlatformNoticeKind = "ownership_transferred";
+/** The `detail` of each platform notice kind. */
+export interface PlatformNoticeDetails {
+    /** A deleted org's (or owner's) shared item now belongs to the platform. */
+    ownership_transferred: {
+        ref: OwnedRef;
+        name: string;
+        fromOrg: {
+            id: string;
+            name: string;
+        };
+        reason: "owner_deleted" | "org_deleted";
+        /** How many other orgs use it. */
+        usedBy: number;
+    };
+}
+export declare function addPlatformNotice<K extends PlatformNoticeKind>(db: KernelSchemaDb, kind: K, detail: PlatformNoticeDetails[K]): Promise<void>;

package/dist/inbox/platform-notices.js

@@ -0,0 +1,9 @@
+// Platform notices (`platform_notices`, plugin scope phase 3, ruling P3-22): what the super admins
+// are told, until any one of them dismisses it. Written in the caller's transaction.
+import { randomUUID } from "node:crypto";
+export async function addPlatformNotice(db, kind, detail) {
+    await db
+        .insertInto("platform_notices")
+        .values({ id: randomUUID(), kind, detail: JSON.stringify(detail) })
+        .execute();
+}

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { type ApprovalDecision, ExtensionApprovals, type PendingExtension, type
 export { blobKey, ExtensionBlobIntegrityError, type ExtensionBlobSource, ExtensionBlobs, } from "./extensions/blobs.js";
 export { BOOTSTRAP_MANIFEST_FILE, type BootstrapEntryResult, BootstrapFailedError, type BootstrapFailure, type BootstrapResolveOptions, type BootstrapResult, BootstrapService, bootstrapManifestSha256, readBootstrapManifest, resolveBootstrapPackages, } from "./extensions/bootstrap.js";
 export { type ExtensionCli, openExtensionCli } from "./extensions/cli.js";
-export { DEPLOYMENT_SECRETS_ORG, type DeploymentConfigField, type DeploymentConfigView, ExtensionDeploymentConfigService, mergeDeploymentConfig, PLUGIN_DEPLOYMENT_CONFIG_TOPIC, readStoredDeploymentConfig, } from "./extensions/deployment-config.js";
+export { DEPLOYMENT_SECRETS_ORG, type DeploymentConfigField, type DeploymentConfigView, ExtensionDeploymentConfigService, mergeDeploymentConfig, PLUGIN_DEPLOYMENT_CONFIG_TOPIC, readStoredDeploymentConfig, type SecretEntry, } from "./extensions/deployment-config.js";
 export { assertSecretsReachable, ExtensionHost, type ExtensionLoadPlan, type InspectedExtension, type InstalledExtensionLoader, type InstallFailureReason, } from "./extensions/host.js";
 export { ExtensionUnloadedError, type InflightEntry, InflightTracker, PLUGIN_UNLOADED_TOOL_ERROR, type TrackOptions, trackCalls, } from "./extensions/inflight.js";
 export { type DesiredExtension, type ExtensionInstallRow, ExtensionInstalls, type IngestSource, type PackageReview, } from "./extensions/installs.js";
@@ -63,6 +63,10 @@ export { type ContextJob, type JobWrapper, type LogContext, logContext, setJobWr
 export { type Org, OrgsService } from "./orgs/orgs.service.js";
 export type { KernelOverride } from "./overrides.js";
 export { fetchNpmPackage, IntegrityMismatchError, type NpmFetchConfig, NpmFetchError, PackageTooLargeError, } from "./packages/npm.js";
+export { checkInputParity, inputParity, type ParityFinding, type ParityOperation, } from "./platform/parity.js";
+export { PLATFORM_OPERATION_PROVIDERS } from "./platform/platform-ops.module.js";
+export { PlatformOperations } from "./platform/registry.js";
+export { ROUTE_SCHEMAS, type RouteSchemas } from "./platform/route-schemas.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
 export type { AgentLoop, LoopContext, LoopOutcome } from "./runtime/loop.js";
 export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
@@ -71,4 +75,4 @@ export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, type SandboxUseInfo, } from "./sandbox/sandbox.service.js";
 export { MAX_STORAGE_KEY_BYTES, StorageKeyError, } from "./storage/prefix.js";
 export { PrefixedStorage, StorageService, type StorageSource, } from "./storage/storage.service.js";
-export { SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";
+export { SANDBOX_RESTARTED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";

package/dist/index.js

@@ -60,6 +60,12 @@ export { createConfiguredLogger, loggerOptionsFromConfig } from "./log-config.js
 export { logContext, setJobWrapper, setTraceContextSource, withJobContext, withLogContext, } from "./log-context.js";
 export { OrgsService } from "./orgs/orgs.service.js";
 export { fetchNpmPackage, IntegrityMismatchError, NpmFetchError, PackageTooLargeError, } from "./packages/npm.js";
+// Test seam: the Platform input-parity test in tools/checks (no runtime caller).
+export { checkInputParity, inputParity, } from "./platform/parity.js";
+// Test seam (the parity test builds every operation from these without a Nest app).
+export { PLATFORM_OPERATION_PROVIDERS } from "./platform/platform-ops.module.js";
+export { PlatformOperations } from "./platform/registry.js";
+export { ROUTE_SCHEMAS } from "./platform/route-schemas.js";
 export { UNKNOWN_RESULT_TEXT } from "./runtime/context/pairing.js";
 export { MAINTENANCE_QUEUE_NAME } from "./runtime/maintenance-queue.js";
 export { runJobId } from "./runtime/run-queue.js";
@@ -67,4 +73,4 @@ export { SANDBOX_DESTROY_JOB, SANDBOX_SUSPEND_JOB, } from "./sandbox/jobs.js";
 export { SANDBOX_LOCK_TTL_MS, SandboxService, } from "./sandbox/sandbox.service.js";
 export { MAX_STORAGE_KEY_BYTES, StorageKeyError, } from "./storage/prefix.js";
 export { PrefixedStorage, StorageService, } from "./storage/storage.service.js";
-export { SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";
+export { SANDBOX_RESTARTED_NOTICE, SANDBOX_STARTED_NOTICE, } from "./tools/builtins/sandbox/common.js";

package/dist/infra/cli/kernel-cli.module.js

@@ -13,6 +13,7 @@ import { NestFactory } from "@nestjs/core";
 import { Redis } from "ioredis";
 import { createBus } from "../../ctx/bus.js";
 import { KERNEL_APP_OPTIONS } from "../../lifecycle/tokens.js";
+import { CacheModule } from "../cache/cache.module.js";
 import { ConfigModule } from "../config/config.module.js";
 import { KernelConfigService } from "../config/kernel-config.service.js";
 import { DatabaseModule } from "../database/database.module.js";
@@ -20,6 +21,7 @@ import { KernelEventsModule } from "../events/kernel-events.js";
 import { GracefulShutdownModule } from "../lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "../lock/lock.module.js";
 import { LoggingModule } from "../logging/logging.module.js";
+import { QueueModule } from "../queue/queue.module.js";
 import { KERNEL_BUS, KERNEL_LOGGER, REDIS, REDIS_SUBSCRIBER } from "../tokens.js";
 /** How long the CLI's Redis connection may take before a command fails (a publish only warns). */
 const CLI_REDIS_CONNECT_TIMEOUT_MS = 3_000;
@@ -108,7 +110,13 @@ let KernelCliModule = KernelCliModule_1 = class KernelCliModule {
                 ConfigModule.forRoot(config, opts.env !== undefined ? { env: opts.env } : {}),
                 GracefulShutdownModule,
                 DatabaseModule.forRoot(),
-                ...(opts.redis === false ? [] : [CliRedisModule, LockModule]),
+                // QueueModule's root gives the queues a command's modules register (the catalog's scope
+                // sync and maintenance queues) the configured Redis; without it BullMQ would connect to
+                // its default 127.0.0.1:6379
+                // CacheModule: `@Cacheable` providers of the domain modules (EffectiveConfigs) need it
+                ...(opts.redis === false
+                    ? []
+                    : [CliRedisModule, LockModule, CacheModule, QueueModule.forRoot()]),
                 KernelEventsModule,
                 ...opts.modules,
             ],

package/dist/infra/config/kernel-config.service.js

@@ -28,13 +28,39 @@ const HOT_APPLIERS = {
     "auth.trustedIdentitySources": () => { },
     // The hook registry reads the time limit on every run.
     "hooks.timeoutMs": () => { },
+    // The provider registry reads the list time limit at every listModels call.
+    "models.listTimeoutMs": () => { },
+    "models.embedTimeoutMs": () => { },
     // SandboxService reads the shared-lease cap at every acquisition.
     "sandbox.maxConcurrentCommands": () => { },
+    // The devices service reads the personal limit at every create.
+    "devices.maxPersonal": () => { },
+    // The local device relay reads the reconnect grace at every disconnect and token response.
+    "devices.local.reconnectGraceSeconds": () => { },
     // Sub-agent limits are read at every dispatch, child step and tool resolution.
-    "subagents.maxConcurrentPerRun": () => { },
+    "subagents.maxDepth": () => { },
+    "subagents.maxConcurrentPerConversation": () => { },
     "subagents.maxDispatchesPerRun": () => { },
     "subagents.maxTokensPerRun": () => { },
+    // The web tools read these limits through the config service on every call.
+    "web.search.maxResults": () => { },
+    "web.fetch.maxPageChars": () => { },
+    "web.fetch.maxAnswerTokens": () => { },
+    "web.fetch.cacheSeconds": () => { },
+    "web.fetch.timeoutMs": () => { },
 };
+/**
+ * Environment variables of renamed config keys, with their replacements: warned about once when
+ * the service starts (agent map spec §6: `subagents.maxConcurrentPerRun` became
+ * `subagents.maxConcurrentPerConversation`). A retired file or Nacos key cannot be told here: the
+ * schema strips unknown keys before the kernel receives its config.
+ */
+const RETIRED_ENV = [
+    [
+        "CAPYBARA_SUBAGENTS__MAX_CONCURRENT_PER_RUN",
+        "CAPYBARA_SUBAGENTS__MAX_CONCURRENT_PER_CONVERSATION",
+    ],
+];
 const HOT_PATHS = configFields(KernelConfigSchema)
     .filter((f) => f.meta?.hot)
     .map((f) => f.path);
@@ -55,6 +81,11 @@ let KernelConfigService = class KernelConfigService {
         this.env = input.env ?? process.env;
         log.setLevel(input.config.log.level);
         log.addSecrets(secretValues(KernelConfigSchema, input.config));
+        for (const [old, now] of RETIRED_ENV) {
+            if (this.env[old] !== undefined) {
+                log.warn(`${old} is no longer read and is ignored; set ${now} instead`, { env: old });
+            }
+        }
     }
     get() {
         return this.current;

package/dist/infra/database/database.module.js

@@ -66,6 +66,7 @@ let DatabaseModule = class DatabaseModule {
                     const { db } = config.get();
                     return createDb(db.url, db.poolMax, (err) => log.error("pg idle client error", { err }), {
                         connectTimeoutMs: db.connectTimeoutMs,
+                        idleTimeoutMs: db.idleTimeoutMs,
                         onClientError: (err) => log.warn("pg client error", { err }),
                     });
                 },

package/dist/infra/database/xact-lock.d.ts

@@ -4,7 +4,7 @@ import { TransactionHost } from "./transaction-host.js";
  * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
  * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
  * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
- * transaction ("never zero active enterprise admins", "set up once", "one account per external
+ * transaction ("never zero active super admins", "set up once", "one account per external
  * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
  * a transaction (where the lock would be released at once) throw.
  */

package/dist/infra/database/xact-lock.js

@@ -16,7 +16,7 @@ import { Transactional } from "./transactional.decorator.js";
  * Transaction-scoped advisory locks (decision R9 of the Nest kernel spec): `pg_advisory_xact_lock`
  * is transaction semantics, like `FOR UPDATE`. It is held by the caller's transaction and released
  * at its COMMIT or ROLLBACK, so it serializes writers whose invariant is checked inside that same
- * transaction ("never zero active enterprise admins", "set up once", "one account per external
+ * transaction ("never zero active super admins", "set up once", "one account per external
  * identity"). The one place that takes such a lock; `propagation: "mandatory"` makes a call outside
  * a transaction (where the lock would be released at once) throw.
  */

package/dist/infra/events/kernel-events.d.ts

@@ -34,7 +34,8 @@ export interface KernelEventMap {
         status: "approved" | "denied";
     };
     /**
-     * A person answered a tool call's input request (after the commit, exactly once). Same
+     * A person answered a tool call's input request, or skipped it with a message (after the commit,
+     * exactly once). Same
      * consumers and the same re-derivation as `approval.decided`.
      */
     "question.answered": {
@@ -42,6 +43,8 @@ export interface KernelEventMap {
         orgId: string;
         conversationId: string;
         runId: string;
+        /** `skipped`: the run's starter sent a message instead (reply-while-question spec §6.3). */
+        outcome: "answered" | "skipped";
     };
     /**
      * EventAppended: a conversation's event log advanced to `toSeq` (after the commit, from
@@ -72,12 +75,37 @@ export interface KernelEventMap {
         runId: string;
     };
     /**
-     * `ensureRun` marked an orphaned run failed (after the commit): the waits stop its active
-     * sub-agents at once. A lost event is repaired by the wait sweep (children of finished runs).
+     * `ensureRun` marked an orphaned run failed (after the commit): the waits stop its active fork
+     * sub-agent at once (background sub-agents keep running, agent map spec §5.4). A lost event is
+     * repaired by the wait sweep (fork children of finished runs).
      */
     "run.orphaned": {
         runId: string;
     };
+    /**
+     * A sub-agent's `subagent_delivery` was appended to its parent conversation (after the commit;
+     * `SubagentDeliveries`). Waking an idle parent follows it; a lost event is re-derived by the
+     * next `ensureRun` (a message, the end of a run, a page opening).
+     */
+    "subagent.delivered": {
+        conversationId: string;
+    };
+    /**
+     * A background task of the conversation finished (after the commit of its
+     * `background_task_finished` event). `BackgroundWake` asks the run queue for a wake run; a lost
+     * event is re-derived by the next `ensureRun` (a message, the end of a run, a page opening).
+     */
+    "background_task.finished": {
+        conversationId: string;
+    };
+    /**
+     * An extension's `ctx.models.embed` call wrote a `model_usage` row (after the commit, spec B
+     * §5.4). The usage reporter enqueues its `usage.report` delivery; a lost event is re-derived by
+     * the usage sweep (rows whose `reported_at` is still null).
+     */
+    "model_usage.recorded": {
+        id: string;
+    };
 }
 type Handler<K extends keyof KernelEventMap> = (payload: KernelEventMap[K]) => Promise<void> | void;
 /** Typed in-process event emitter; handlers run in order, a failing one is logged and skipped. */

package/dist/infra/lifecycle/process-guards.js

@@ -39,6 +39,10 @@ export function createFatalRecorder(deps) {
     let recent = [];
     let open = false;
     return (kind, err) => {
+        // Exiting already: log nothing more. A failing log write (EPIPE on a dead stdout) raises the
+        // next event itself; logging it again would keep the process busy forever and starve the exit.
+        if (open)
+            return;
         try {
             const t = now();
             recent = recent.filter((x) => t - x < GUARD_CIRCUIT_WINDOW_MS);

package/dist/infra/lock/lock.service.d.ts

@@ -74,6 +74,14 @@ export declare class LockService {
     holderOf(key: string): Promise<string | null>;
     /** Deletes `key` when `holder` still owns it. */
     releaseIf(key: string, holder: string): Promise<boolean>;
+    /**
+     * Takes one of `limit` slots of the counting semaphore `key` for `holder` (a unique token), for at
+     * most `ttlMs` (a crashed holder's slot frees itself then; no renewal). False when every slot is
+     * taken. Release with {@link releaseSlot}.
+     */
+    takeSlot(key: string, holder: string, limit: number, ttlMs: number): Promise<boolean>;
+    /** Gives back `holder`'s slot of the semaphore `key` (nothing when it already expired). */
+    releaseSlot(key: string, holder: string): Promise<void>;
     /**
      * Takes `key` (no `lock:` prefix) with the caller's `holder` value for `ttlMs`, unless it is
      * held, and renews it every TTL/3 like {@link acquire} (a run longer than the TTL keeps it, a

package/dist/infra/lock/lock.service.js

@@ -20,6 +20,20 @@ import { ACQUIRE_EXCLUSIVE, ACQUIRE_SHARED, COUNT_SHARED_LEASES, DOWNGRADE_SHARE
 const RELEASE_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end`;
 /** Extends the key only while it holds our token. */
 const RENEW_IF = `if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('pexpire', KEYS[1], tonumber(ARGV[2])) else return 0 end`;
+/**
+ * Takes a slot of a counting semaphore: a sorted set of holder tokens scored by expiry time. Expired
+ * holders (a crashed replica's) drop out first, so a slot is never lost for longer than its TTL;
+ * then the token is added when fewer than ARGV[2] slots are taken. The set itself expires with
+ * its last slot. KEYS[1] the set; ARGV: token, limit, ttl ms. Returns 1 when taken.
+ */
+const TAKE_SLOT = `local now = redis.call('time')
+local ms = tonumber(now[1]) * 1000 + math.floor(tonumber(now[2]) / 1000)
+redis.call('zremrangebyscore', KEYS[1], '-inf', ms)
+if redis.call('zcard', KEYS[1]) >= tonumber(ARGV[2]) then return 0 end
+redis.call('zadd', KEYS[1], ms + tonumber(ARGV[3]), ARGV[1])
+local last = redis.call('zrange', KEYS[1], -1, -1, 'withscores')
+redis.call('pexpireat', KEYS[1], tonumber(last[2]))
+return 1`;
 /** Resolves after `ms`; rejects with the abort reason when `signal` aborts first. */
 function sleep(ms, signal) {
     return new Promise((resolve, reject) => {
@@ -117,6 +131,19 @@ let LockService = class LockService {
     async releaseIf(key, holder) {
         return (await this.redis.eval(RELEASE_IF, 1, key, holder)) === 1;
     }
+    /**
+     * Takes one of `limit` slots of the counting semaphore `key` for `holder` (a unique token), for at
+     * most `ttlMs` (a crashed holder's slot frees itself then; no renewal). False when every slot is
+     * taken. Release with {@link releaseSlot}.
+     */
+    async takeSlot(key, holder, limit, ttlMs) {
+        assertNoTransaction("takeSlot");
+        return ((await this.redis.eval(TAKE_SLOT, 1, key, holder, String(limit), String(Math.ceil(ttlMs)))) === 1);
+    }
+    /** Gives back `holder`'s slot of the semaphore `key` (nothing when it already expired). */
+    async releaseSlot(key, holder) {
+        await this.redis.zrem(key, holder);
+    }
     /**
      * Takes `key` (no `lock:` prefix) with the caller's `holder` value for `ttlMs`, unless it is
      * held, and renews it every TTL/3 like {@link acquire} (a run longer than the TTL keeps it, a

package/dist/infra/logging/logging.module.d.ts

@@ -6,8 +6,10 @@ export interface LoggingModuleOptions {
     logger?: KernelLogger;
 }
 /**
- * Provides the process logger as `KERNEL_LOGGER`. The logger is created before the Nest context
- * (it must exist for startup errors), so it is passed in or derived from the startup config here.
+ * Provides the process logger as `KERNEL_ROOT_LOGGER` and, as `KERNEL_LOGGER`, one child per injecting
+ * class with `context` = the class name (the `[context=…]` of the pretty output; octok's
+ * per-class Nest logger context). The logger is created before the Nest context (it must exist for
+ * startup errors), so it is passed in or derived from the startup config here.
  */
 export declare class LoggingModule {
     static forRoot(config: KernelConfig, opts?: LoggingModuleOptions): DynamicModule;