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

package/dist/index.d.ts

@@ -71,4 +71,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

@@ -67,4 +67,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,10 +28,16 @@ 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 environments service reads the personal limit at every create.
+    "environments.maxPersonal": () => { },
     // 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.
@@ -41,6 +47,18 @@ const HOT_APPLIERS = {
     "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);
@@ -61,6 +79,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/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

@@ -72,12 +72,21 @@ 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
@@ -86,6 +95,14 @@ export interface KernelEventMap {
     "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/queue/add-job-once.d.ts

@@ -0,0 +1,14 @@
+import { type JobsOptions } from "bullmq";
+import type { Redis } from "ioredis";
+/** One job to add: its name, data and options (a deterministic `jobId` makes the add idempotent). */
+export interface OneJob<T> {
+    name: string;
+    data: T;
+    opts: JobsOptions;
+}
+/**
+ * Adds one job to a kernel queue from a process that hosts no queue of its own (a CLI command),
+ * over the caller's Redis connection (left open), with BullMQ's default key prefix like the
+ * kernel's queues. The queue handle is closed again before returning.
+ */
+export declare function addJobOnce<T>(connection: Redis, queue: string, job: OneJob<T>): Promise<void>;

package/dist/infra/queue/add-job-once.js

@@ -0,0 +1,16 @@
+import { Queue } from "bullmq";
+/**
+ * Adds one job to a kernel queue from a process that hosts no queue of its own (a CLI command),
+ * over the caller's Redis connection (left open), with BullMQ's default key prefix like the
+ * kernel's queues. The queue handle is closed again before returning.
+ */
+export async function addJobOnce(connection, queue, job) {
+    const q = new Queue(queue, { connection });
+    try {
+        // biome-ignore lint/suspicious/noExplicitAny: BullMQ's name and data generics do not line up here
+        await q.add(job.name, job.data, job.opts);
+    }
+    finally {
+        await q.close();
+    }
+}

package/dist/kernel.module.js

@@ -33,6 +33,8 @@ import { KernelLifecycle } from "./lifecycle/kernel-lifecycle.js";
 import { KERNEL_APP_OPTIONS } from "./lifecycle/tokens.js";
 import { createConfiguredLogger } from "./log-config.js";
 import { KERNEL_OVERRIDE_TOKENS } from "./overrides.js";
+import { PlatformModule } from "./platform/platform.module.js";
+import { PlatformOpsModule } from "./platform/platform-ops.module.js";
 import { GatewayModule } from "./roles/gateway.module.js";
 import { WorkerModule } from "./roles/worker.module.js";
 import { UsageReportModule } from "./runtime/usage-report.js";
@@ -108,6 +110,10 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 TitlesModule,
                 UsageReportModule,
                 ChannelsModule,
+                // the Platform tool's operation registry and actor facts
+                PlatformModule,
+                // its operations (skills, agents, ...), registered at start on every role
+                PlatformOpsModule,
                 // the role modules, by `roles` (nest kernel spec §2)
                 ...(config.roles.includes("api") ? [ApiModule] : []),
                 ...(config.roles.includes("worker") ? [WorkerModule.forRoot(config)] : []),

package/dist/lifecycle/kernel-lifecycle.d.ts

@@ -123,7 +123,7 @@ export declare class KernelLifecycle implements OnApplicationBootstrap, BeforeAp
      * and the next start tries again while it stays incomplete.
      */
     private runBootstrap;
-    /** 部署尚无活跃企业管理员时提示去初始化；查询失败只记日志，不影响启动。 */
+    /** 部署尚无活跃超级管理员时提示去初始化；查询失败只记日志，不影响启动。 */
     private warnIfSetupPending;
     beforeApplicationShutdown(): Promise<void>;
     /** Logs the end of the stop phases (Redis and the pool close right after, in the infra modules). */

package/dist/lifecycle/kernel-lifecycle.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { SANDBOX_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { SANDBOX_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable, Optional, } from "@nestjs/common";
 import { sql } from "kysely";
 import { MarketplacesService } from "../catalog/marketplaces.service.js";
@@ -237,7 +237,7 @@ let KernelLifecycle = class KernelLifecycle {
             .list("sandbox")
             .find((x) => x.capability === SANDBOX_EXTENSION_POINT);
         if (sandboxEntry !== undefined) {
-            for (const w of sandboxConfigWarnings(cfg(), sandboxEntry.plugin, sandboxEntry.impl)) {
+            for (const w of sandboxConfigWarnings(cfg(), sandboxEntry.plugin)) {
                 this.log[w.level](w.message);
             }
         }
@@ -318,10 +318,10 @@ let KernelLifecycle = class KernelLifecycle {
             throw e;
         }
     }
-    /** 部署尚无活跃企业管理员时提示去初始化；查询失败只记日志，不影响启动。 */
+    /** 部署尚无活跃超级管理员时提示去初始化；查询失败只记日志，不影响启动。 */
     async warnIfSetupPending() {
         try {
-            if ((await this.accounts.countEnterpriseAdmins()) === 0) {
+            if ((await this.accounts.countSuperAdmins()) === 0) {
                 this.log.warn("deployment is not set up; open the setup wizard or run `capybara admin create`");
             }
         }

package/dist/models/embeddings.d.ts

@@ -0,0 +1,82 @@
+import { type ExtensionEmbedRequest, type ExtensionEmbedResult, type ExtensionModelTarget, type ExtensionPermissions, type Logger } from "@capybara-hq/plugin-sdk";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { type HookRunner } from "../runtime/hook-calls.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { ModelPurposesService } from "./purposes.js";
+/** An extension's `permissions.models` (what it declared, as approved in its manifest). */
+export type DeclaredModelPurposes = readonly NonNullable<ExtensionPermissions["models"]>[number][];
+/** Most texts one `ctx.models.embed` call may carry (the kernel splits them by `maxBatch`). */
+export declare const EMBED_MAX_INPUTS = 2048;
+/**
+ * The `ctx.models` broker for embeddings (model platform spec B §5.4). Every call:
+ * - accepts only a purpose the calling extension declared in `permissions.models` with
+ *   `kind: "embedding"` (`model.purpose_unknown` otherwise: the manifest is what was approved), for
+ *   an org that enabled the extension (`extension.not_enabled`);
+ * - resolves the org's effective target ({@link ModelPurposesService.resolve}: unmapped, or mapped
+ *   to a model the org cannot use, is `model.unconfigured`) and the model in the org's view, enabled
+ *   and of kind `embedding` ({@link ProviderRegistry.resolve}, bound to the org's effective config);
+ * - fires `model.request` once (`purpose: "embedding"`, every text of the call, no conversation
+ *   fields) through the host's hook registry before anything is sent; a policy denial (a deny, a
+ *   hook error or timeout, a policy extension not loaded here or without a valid config in the org)
+ *   writes one `hook.denied` audit row and rejects with `ApiError("model.hook_denied")` (403) whose
+ *   message is the one a denied run step fails with: no provider call, no usage row. A call with no input sends nothing
+ *   and fires nothing;
+ * - splits the input into batches of the model's `maxBatch`, calls the provider's `embed` once per
+ *   batch in order with the extension's signal (plus the request's own `signal`), each batch
+ *   limited by `models.embedTimeoutMs` (`ModelError("timeout")`), checks each result ({@link validateEmbedResult}: a
+ *   wrong count, dimension or a non-finite number is a `ModelError` of kind `server`), and
+ *   concatenates the vectors; no retries (an extension retries itself if it wants to);
+ * - writes one `model_usage` row (the sum of the batches' input tokens) and announces it after the
+ *   commit (`model_usage.recorded`: the usage reporter's `ModelUsageJobs` enqueues its
+ *   `usage.report` delivery; the usage sweep catches up a lost one). A call that fails after the
+ *   provider answered some batches (an invalid result, a later batch failing) still records their
+ *   input tokens before the error reaches the extension; one that fails before any answer records
+ *   nothing.
+ * Purpose params are not sent: an `embed` request carries none (`EmbedRequest`).
+ */
+export declare class ModelEmbeddings {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly purposes;
+    private readonly providers;
+    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
+    private readonly events;
+    private readonly log;
+    /** `models.embedTimeoutMs` (hot). */
+    private readonly config;
+    constructor(kdb: KernelDb, txHost: TransactionHost, purposes: Pick<ModelPurposesService, "resolve">, providers: Pick<ProviderRegistry, "resolve">, 
+    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
+    events: Pick<KernelEvents, "emit">, log: Pick<Logger, "warn">, 
+    /** `models.embedTimeoutMs` (hot). */
+    config: Pick<KernelConfigService, "get">);
+    /** Refuses a purpose `plugin` did not declare with kind `embedding`, or an org it is off in. */
+    private admit;
+    /** The org's target for the purpose and the model bound to the org's config. */
+    private target;
+    /**
+     * One batch to the provider, limited by `models.embedTimeoutMs` (hot, read per call): at the limit
+     * the call's signal aborts and the batch fails with `ModelError("timeout")`, even when the
+     * provider ignores the signal (its late answer is dropped).
+     */
+    private callWithTimeout;
+    /**
+     * `ctx.models.embed` for `plugin` (its declared purposes), aborted by `signal`; `hooks` is the
+     * host's hook registry (`model.request`), absent only for a ctx built without a host (tests).
+     */
+    embed(plugin: string, declared: DeclaredModelPurposes, request: ExtensionEmbedRequest, signal: AbortSignal, hooks: HookRunner | undefined): Promise<ExtensionEmbedResult>;
+    /**
+     * `model.request` for an embed call (policy hooks may deny it). Rejects with the caller's abort
+     * reason when `signal` aborts while the hooks run (an abort is never a deny).
+     */
+    private checkHooks;
+    /** `ctx.models.describe` for `plugin`: null when the purpose maps to no model the org can use. */
+    describe(plugin: string, declared: DeclaredModelPurposes, req: {
+        orgId: string;
+        purpose: string;
+    }): Promise<ExtensionModelTarget | null>;
+    /** One `model_usage` row; its `usage.report` delivery is enqueued after the commit. */
+    private record;
+}