@capybara-hq/kernel 0.1.0-rc.19 → 0.1.0-rc.20

package/dist/infra/presence/presence.module.js

@@ -0,0 +1,22 @@
+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;
+};
+import { Global, Module } from "@nestjs/common";
+import { ReplicaPresence } from "./replica-presence.js";
+/**
+ * Global: {@link ReplicaPresence}, on every role (each process reports itself; `KernelLifecycle`
+ * starts and stops it), read by the admin health overview.
+ */
+let PresenceModule = class PresenceModule {
+};
+PresenceModule = __decorate([
+    Global(),
+    Module({
+        providers: [ReplicaPresence],
+        exports: [ReplicaPresence],
+    })
+], PresenceModule);
+export { PresenceModule };

package/dist/infra/presence/replica-presence.d.ts

@@ -0,0 +1,87 @@
+import type { Redis } from "ioredis";
+import type { KernelLogger } from "../../log.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+/** How often each process writes its presence (admin overview spec §5.1). */
+export declare const PRESENCE_DEFAULT_INTERVAL_MS = 15000;
+/** Optional provider: the presence interval (ms) instead of {@link PRESENCE_DEFAULT_INTERVAL_MS} (tests). */
+export declare const PRESENCE_INTERVAL_MS: unique symbol;
+/** The ZSET of live replicas: member = replica id, score = last beat (Redis server clock, ms). */
+export declare const REPLICAS_KEY = "capk:replicas";
+/** One replica's facts: `capk:replica:<replicaId>`. */
+export declare const replicaKey: (replicaId: string) => string;
+/** A kernel role (`roles` in the config). */
+export type ReplicaRole = "api" | "worker" | "gateway";
+/** What a live replica last reported about itself. */
+export interface LiveReplica {
+    /** The process id (`ReplicaStatusStore.replicaId`, the gateway heartbeat's member). */
+    id: string;
+    roles: ReplicaRole[];
+    /** `KERNEL_VERSION` of the process. */
+    version: string;
+    /** When the process's start sequence was done, before it listens (ISO 8601). */
+    startedAt: string;
+    /** The configured `http.replicaId` (the `x-capybara-replica` header), null when unset. */
+    httpReplicaId: string | null;
+    /** Channel long connections this process holds (0 without the gateway role). */
+    channelsHeld: number;
+    /** Device sockets open on this process (0 without the gateway role). */
+    devicesConnected: number;
+}
+/** The per-process facts the presence reports, read at every beat. */
+export interface PresenceSources {
+    /** This process's replica id (`ReplicaStatusStore.replicaId`). */
+    replicaId: string;
+    channelsHeld(): number;
+    devicesConnected(): number;
+}
+/**
+ * The replicas with a beat newer than `windowMs` (Redis server clock): one script for the members,
+ * then one pipelined HGETALL each. A member whose facts already expired is left out. Sorted by
+ * start time, then id.
+ */
+export declare function readLiveReplicas(redis: Pick<Redis, "eval" | "pipeline">, windowMs: number): Promise<LiveReplica[]>;
+/**
+ * Replica presence (admin overview spec §5.1): every process, whatever its roles, says every
+ * {@link PRESENCE_DEFAULT_INTERVAL_MS} that it is alive, with its roles, version, start time and
+ * the connections it holds, so the admin console can tell which replicas run in which role.
+ *
+ * Multi-replica: the state lives only in Redis, with a TTL of three intervals on both keys; the
+ * score is the Redis server clock (replica clocks may drift), as in the gateway heartbeat. Each
+ * process writes only its own entry and holds nothing other processes need: no lock, no
+ * transaction, no shared job. So it is not a `@LockedInterval` (that runs once across replicas)
+ * but a `setTimeout` chain of this process (`unref`), started by `KernelLifecycle` at the end of
+ * the start (after the start gate opened) and stopped first thing in the stop, which removes the
+ * entry at once; a crashed process ages out of {@link live} within the window. A failing beat is
+ * logged at warn and never thrown.
+ */
+export declare class ReplicaPresence {
+    private readonly redis;
+    private readonly config;
+    private readonly log;
+    /** The beat interval; the window (and the TTL) is three of them. */
+    readonly intervalMs: number;
+    private sources;
+    private startedAt;
+    private timer;
+    private running;
+    private halted;
+    constructor(redis: Redis, config: Pick<KernelConfigService, "get">, log: Pick<KernelLogger, "warn">, intervalMs?: number);
+    /** How long an entry stays live without a beat (ms). */
+    get windowMs(): number;
+    /** Starts beating (the first beat at once). Called once, at the end of the start. */
+    start(sources: PresenceSources): void;
+    private schedule;
+    private beat;
+    /**
+     * Stops beating and waits for a beat in flight, leaving the entry to age out (a crash looks like
+     * this; the tests use it as one). Idempotent.
+     */
+    halt(): Promise<void>;
+    /** The stop: {@link halt}, then removes this process's entry at once (best effort). Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * The live replicas (a beat within the window, by the Redis server clock), sorted by start time.
+     * Throws when Redis does not answer.
+     */
+    live(): Promise<LiveReplica[]>;
+}

package/dist/infra/presence/replica-presence.js

@@ -0,0 +1,189 @@
+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, Optional } from "@nestjs/common";
+import { KERNEL_VERSION } from "../../version.js";
+import { KernelConfigService } from "../config/kernel-config.service.js";
+import { KERNEL_LOGGER, REDIS } from "../tokens.js";
+/** How often each process writes its presence (admin overview spec §5.1). */
+export const PRESENCE_DEFAULT_INTERVAL_MS = 15_000;
+/** Optional provider: the presence interval (ms) instead of {@link PRESENCE_DEFAULT_INTERVAL_MS} (tests). */
+export const PRESENCE_INTERVAL_MS = Symbol("PRESENCE_INTERVAL_MS");
+/** The ZSET of live replicas: member = replica id, score = last beat (Redis server clock, ms). */
+export const REPLICAS_KEY = "capk:replicas";
+/** One replica's facts: `capk:replica:<replicaId>`. */
+export const replicaKey = (replicaId) => `capk:replica:${replicaId}`;
+/**
+ * One beat: ZADD the member at the server clock, write the facts, give both keys a TTL of the
+ * window and trim members older than it. KEYS: the ZSET, the replica's hash. ARGV: the replica id,
+ * the window (ms), then the hash's field / value pairs.
+ */
+const BEAT = `
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+local ttl = tonumber(ARGV[2])
+redis.call('ZADD', KEYS[1], now, ARGV[1])
+redis.call('HSET', KEYS[2], unpack(ARGV, 3))
+redis.call('PEXPIRE', KEYS[2], ttl)
+redis.call('PEXPIRE', KEYS[1], ttl)
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now - ttl)
+return now
+`;
+/** The members newer than the window (ARGV[1], ms) by the Redis server clock. */
+const LIVE = `
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+return redis.call('ZRANGEBYSCORE', KEYS[1], '(' .. (now - tonumber(ARGV[1])), '+inf')
+`;
+const ROLES = ["api", "worker", "gateway"];
+const count = (v) => {
+    const n = Number(v);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+};
+/**
+ * The replicas with a beat newer than `windowMs` (Redis server clock): one script for the members,
+ * then one pipelined HGETALL each. A member whose facts already expired is left out. Sorted by
+ * start time, then id.
+ */
+export async function readLiveReplicas(redis, windowMs) {
+    const ids = (await redis.eval(LIVE, 1, REPLICAS_KEY, windowMs));
+    if (ids.length === 0)
+        return [];
+    const pipe = redis.pipeline();
+    for (const id of ids)
+        pipe.hgetall(replicaKey(id));
+    const res = (await pipe.exec()) ?? [];
+    const out = [];
+    ids.forEach((id, i) => {
+        const [err, h] = res[i] ?? [null, null];
+        if (err)
+            throw err;
+        const f = h;
+        if (f === null || f.version === undefined)
+            return;
+        out.push({
+            id,
+            roles: (f.roles ?? "")
+                .split(",")
+                .filter((r) => ROLES.includes(r)),
+            version: f.version,
+            startedAt: f.startedAt ?? "",
+            httpReplicaId: f.httpReplicaId ? f.httpReplicaId : null,
+            channelsHeld: count(f.channelsHeld),
+            devicesConnected: count(f.devicesConnected),
+        });
+    });
+    return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.id.localeCompare(b.id));
+}
+/**
+ * Replica presence (admin overview spec §5.1): every process, whatever its roles, says every
+ * {@link PRESENCE_DEFAULT_INTERVAL_MS} that it is alive, with its roles, version, start time and
+ * the connections it holds, so the admin console can tell which replicas run in which role.
+ *
+ * Multi-replica: the state lives only in Redis, with a TTL of three intervals on both keys; the
+ * score is the Redis server clock (replica clocks may drift), as in the gateway heartbeat. Each
+ * process writes only its own entry and holds nothing other processes need: no lock, no
+ * transaction, no shared job. So it is not a `@LockedInterval` (that runs once across replicas)
+ * but a `setTimeout` chain of this process (`unref`), started by `KernelLifecycle` at the end of
+ * the start (after the start gate opened) and stopped first thing in the stop, which removes the
+ * entry at once; a crashed process ages out of {@link live} within the window. A failing beat is
+ * logged at warn and never thrown.
+ */
+let ReplicaPresence = class ReplicaPresence {
+    redis;
+    config;
+    log;
+    /** The beat interval; the window (and the TTL) is three of them. */
+    intervalMs;
+    sources;
+    startedAt = "";
+    timer;
+    running;
+    halted = false;
+    constructor(redis, config, log, intervalMs) {
+        this.redis = redis;
+        this.config = config;
+        this.log = log;
+        this.intervalMs = intervalMs ?? PRESENCE_DEFAULT_INTERVAL_MS;
+    }
+    /** How long an entry stays live without a beat (ms). */
+    get windowMs() {
+        return this.intervalMs * 3;
+    }
+    /** Starts beating (the first beat at once). Called once, at the end of the start. */
+    start(sources) {
+        if (this.sources !== undefined || this.halted)
+            return;
+        this.sources = sources;
+        this.startedAt = new Date().toISOString();
+        this.schedule(0);
+    }
+    schedule(ms) {
+        if (this.halted)
+            return;
+        this.timer = setTimeout(() => {
+            this.running = this.beat().finally(() => {
+                this.running = undefined;
+                this.schedule(this.intervalMs);
+            });
+        }, ms);
+        this.timer.unref?.();
+    }
+    async beat() {
+        const s = this.sources;
+        if (s === undefined || this.halted)
+            return;
+        try {
+            const http = this.config.get().http.replicaId;
+            await this.redis.eval(BEAT, 2, REPLICAS_KEY, replicaKey(s.replicaId), s.replicaId, this.windowMs, "roles", this.config.get().roles.join(","), "version", KERNEL_VERSION, "startedAt", this.startedAt, "httpReplicaId", http === undefined ? "" : String(http), "channelsHeld", s.channelsHeld(), "devicesConnected", s.devicesConnected());
+        }
+        catch (err) {
+            this.log.warn("replica presence beat failed", { err });
+        }
+    }
+    /**
+     * Stops beating and waits for a beat in flight, leaving the entry to age out (a crash looks like
+     * this; the tests use it as one). Idempotent.
+     */
+    async halt() {
+        this.halted = true;
+        clearTimeout(this.timer);
+        await this.running;
+    }
+    /** The stop: {@link halt}, then removes this process's entry at once (best effort). Idempotent. */
+    async stop() {
+        await this.halt();
+        const s = this.sources;
+        if (s === undefined)
+            return;
+        this.sources = undefined;
+        try {
+            await this.redis.multi().zrem(REPLICAS_KEY, s.replicaId).del(replicaKey(s.replicaId)).exec();
+        }
+        catch (err) {
+            this.log.warn("cannot remove replica presence", { err });
+        }
+    }
+    /**
+     * The live replicas (a beat within the window, by the Redis server clock), sorted by start time.
+     * Throws when Redis does not answer.
+     */
+    live() {
+        return readLiveReplicas(this.redis, this.windowMs);
+    }
+};
+ReplicaPresence = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Optional()),
+    __param(3, Inject(PRESENCE_INTERVAL_MS))
+], ReplicaPresence);
+export { ReplicaPresence };

package/dist/kernel.module.js

@@ -25,6 +25,7 @@ import { databaseCheck, HEALTH_CHECKS, redisCheck } from "./infra/health/health.
 import { GracefulShutdownModule } from "./infra/lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "./infra/lock/lock.module.js";
 import { LoggingModule } from "./infra/logging/logging.module.js";
+import { PresenceModule } from "./infra/presence/presence.module.js";
 import { QueueModule } from "./infra/queue/queue.module.js";
 import { RedisModule } from "./infra/redis/redis.module.js";
 import { KernelThrottlerModule } from "./infra/throttler/throttler.module.js";
@@ -101,6 +102,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 QueueModule.forRoot(),
                 KernelThrottlerModule,
                 HealthModule,
+                // every process's presence beat (admin overview spec §5.1), whatever its roles
+                PresenceModule,
                 ValidationModule,
                 ErrorFilterModule,
                 KernelAppOptionsModule.forRoot({ ...options, logger }),

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

@@ -21,6 +21,7 @@ import { AccountsService } from "../identity/accounts.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { ReplicaPresence } from "../infra/presence/replica-presence.js";
 import type { KernelLogger } from "../log.js";
 import { GatewayRole } from "../roles/gateway-role.js";
 import { WorkerRole } from "../roles/worker-role.js";
@@ -83,6 +84,7 @@ export declare class KernelLifecycle implements OnApplicationBootstrap, BeforeAp
     private readonly titles;
     private readonly channelJobs;
     private readonly channelOutbound;
+    private readonly presence;
     private readonly worker?;
     private readonly gateway?;
     /** The startup config (hot fields are read through the config service). */
@@ -97,7 +99,7 @@ export declare class KernelLifecycle implements OnApplicationBootstrap, BeforeAp
     private unwatchConfig;
     /** What the first bootstrap pass did, carried into the second one. */
     private bootstrapCarry;
-    constructor(accounts: AccountsService, configService: KernelConfigService, log: KernelLogger, options: KernelAppOptions, pool: Kysely<any>, redis: Redis, kdb: KernelDb, shutdown: GracefulShutdown, host: ExtensionHost, registry: ExtensionRegistry, installs: ExtensionInstalls, blobs: ExtensionBlobs, extensionLifecycle: ExtensionLifecycle, replicaStatus: ReplicaStatusStore, bootstrap: BootstrapService, marketplaces: MarketplacesService, pluginImport: PluginImport, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, usageReport: UsageReporter, titles: TitleQueue, channelJobs: ChannelJobs, channelOutbound: ChannelOutbound, worker?: WorkerRole | undefined, gateway?: GatewayRole | undefined);
+    constructor(accounts: AccountsService, configService: KernelConfigService, log: KernelLogger, options: KernelAppOptions, pool: Kysely<any>, redis: Redis, kdb: KernelDb, shutdown: GracefulShutdown, host: ExtensionHost, registry: ExtensionRegistry, installs: ExtensionInstalls, blobs: ExtensionBlobs, extensionLifecycle: ExtensionLifecycle, replicaStatus: ReplicaStatusStore, bootstrap: BootstrapService, marketplaces: MarketplacesService, pluginImport: PluginImport, bus: Pick<ExtensionContext["bus"], "publish" | "subscribe">, usageReport: UsageReporter, titles: TitleQueue, channelJobs: ChannelJobs, channelOutbound: ChannelOutbound, presence: ReplicaPresence, worker?: WorkerRole | undefined, gateway?: GatewayRole | undefined);
     /** The kernel HTTP application (set up by `buildKernelApp` before `init()`). */
     get http(): KernelHttpApp;
     attachHttp(http: KernelHttpApp): void;

package/dist/lifecycle/kernel-lifecycle.js

@@ -31,6 +31,7 @@ import { waitWithin } from "../infra/close-within.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { ReplicaPresence } from "../infra/presence/replica-presence.js";
 import { KERNEL_BUS, KERNEL_LOGGER, KERNEL_POOL, REDIS } from "../infra/tokens.js";
 import { KERNEL_MIGRATIONS_DIR, KERNEL_SCHEMA } from "../kernel.js";
 import { GatewayRole } from "../roles/gateway-role.js";
@@ -104,6 +105,7 @@ let KernelLifecycle = class KernelLifecycle {
     titles;
     channelJobs;
     channelOutbound;
+    presence;
     worker;
     gateway;
     /** The startup config (hot fields are read through the config service). */
@@ -123,6 +125,8 @@ let KernelLifecycle = class KernelLifecycle {
     pool, redis, kdb, shutdown, host, registry, installs, blobs, extensionLifecycle, replicaStatus, bootstrap, marketplaces, pluginImport, bus, 
     // the producers closed on every role (their consumers are the worker role's)
     usageReport, titles, channelJobs, channelOutbound, 
+    // this process's presence beat, on every role (admin overview spec §5.1)
+    presence, 
     // The role modules' parts: a role module is imported only when `roles` names it, so each is
     // present exactly when its role is (checked at the start)
     worker, gateway) {
@@ -148,6 +152,7 @@ let KernelLifecycle = class KernelLifecycle {
         this.titles = titles;
         this.channelJobs = channelJobs;
         this.channelOutbound = channelOutbound;
+        this.presence = presence;
         this.worker = worker;
         this.gateway = gateway;
         this.config = configService.get();
@@ -267,6 +272,12 @@ let KernelLifecycle = class KernelLifecycle {
             // 热更新：重新校验；只应用 hot 字段，其余变化 warn 并列出需重启的键；校验失败保持原配置
             this.unwatchConfig = opts.source.watch((raw) => this.configService.apply(raw), (err) => this.log.error("config watch error", { error: err.message }));
         }
+        // Last: the process says it is alive (in its roles) only once its start went through
+        this.presence.start({
+            replicaId: this.replicaStatus.replicaId,
+            channelsHeld: () => gateway?.channelsHeld() ?? 0,
+            devicesConnected: () => gateway?.devicesConnected() ?? 0,
+        });
     }
     /**
      * Listens on `port` (0.0.0.0; every role listens: worker-only serves only `/healthz` and
@@ -379,6 +390,8 @@ let KernelLifecycle = class KernelLifecycle {
         // Extension requests in progress (SSE and other long requests end on req.signal) are aborted
         // first, otherwise they would use up the http phase
         this.httpApp?.abortPluginRequests();
+        // Leave the replica presence first: the admin console stops counting this process at once
+        await within("presence", this.presence.stop(), 1_000);
         // Scheduled jobs (worker role): no new tick, the runs in progress get the stop signal; awaited
         // in the runs phase (before the extension host closes: a job may call an extension)
         const { worker, gateway } = this;
@@ -457,9 +470,10 @@ KernelLifecycle = __decorate([
     __param(19, Inject(TitleQueue)),
     __param(20, Inject(ChannelJobs)),
     __param(21, Inject(ChannelOutbound)),
-    __param(22, Optional()),
-    __param(22, Inject(WorkerRole)),
+    __param(22, Inject(ReplicaPresence)),
     __param(23, Optional()),
-    __param(23, Inject(GatewayRole))
+    __param(23, Inject(WorkerRole)),
+    __param(24, Optional()),
+    __param(24, Inject(GatewayRole))
 ], KernelLifecycle);
 export { KernelLifecycle };

package/dist/local-devices/local-device-gateway.d.ts

@@ -120,6 +120,12 @@ export declare class LocalDeviceGateway {
     authenticate(credential: string): Promise<MachineIdentity | null>;
     /** Serves one upgraded socket of an authenticated machine until it closes. */
     accept(socket: WebSocket, identity: MachineIdentity, credential: string): void;
+    /**
+     * How many devices this process holds the connection of (replica presence reports it): only
+     * sockets past the hello that hold their device's lease, so a socket still claiming or being
+     * replaced by a newer one does not count a device twice.
+     */
+    connectionCount(): number;
     /** @internal a connection that ended. */
     forget(conn: DeviceConnection): void;
     /** Closes every connection (1001) and hands their leases back. */

package/dist/local-devices/local-device-gateway.js

@@ -508,6 +508,18 @@ let LocalDeviceGateway = class LocalDeviceGateway {
         this.connections.add(conn);
         conn.start();
     }
+    /**
+     * How many devices this process holds the connection of (replica presence reports it): only
+     * sockets past the hello that hold their device's lease, so a socket still claiming or being
+     * replaced by a newer one does not count a device twice.
+     */
+    connectionCount() {
+        let n = 0;
+        for (const c of this.connections)
+            if (c.state === "holding")
+                n++;
+        return n;
+    }
     /** @internal a connection that ended. */
     forget(conn) {
         this.connections.delete(conn);

package/dist/overrides.d.ts

@@ -1,10 +1,12 @@
 import type { NestInterceptor } from "@nestjs/common";
 import { APP_INTERCEPTOR } from "@nestjs/core";
+import { ADMIN_USAGE_TIMINGS, type AdminUsageTimings } from "./admin/usage.service.js";
 import { CHANNEL_WEBHOOK_TIMINGS, type ChannelWebhookTimings } from "./channels/webhook.js";
 import type { EvalReplayHooks } from "./evals/run-replay.js";
 import { EVAL_REPLAY_HOOKS } from "./evals/worker.js";
 import { BOOTSTRAP_LOCK_TTL } from "./extensions/bootstrap.js";
 import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
+import { PRESENCE_INTERVAL_MS } from "./infra/presence/replica-presence.js";
 import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
 import { RUN_CONTEXT_CLOCK } from "./runtime/run-context.service.js";
 import { AGENT_LOOP_FACTORY, type AgentLoopFactory } from "./runtime/run-steps.js";
@@ -25,7 +27,9 @@ import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
  * - `TOOL_PIPELINE_HOOKS`: the tool pipeline's hooks and policy decision;
  * - `SUBAGENT_MESSAGES_HOOKS`: the sub-agent message tools' hooks (a send raced by a run's end);
  * - `BOOTSTRAP_LOCK_TTL`, `FILE_PREVIEW_TIMEOUT`, `LIST_MODELS_TIMEOUT`, `USAGE_REPORT_RETRY`,
- *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`, `SETUP_CHECK_TIMEOUT`: shorter timings;
+ *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`, `SETUP_CHECK_TIMEOUT`,
+ *   `PRESENCE_INTERVAL_MS`: shorter timings;
+ * - `ADMIN_USAGE_TIMINGS`: the usage aggregate's statement timeout and clock;
  * - `EMBED_TOKEN_CLOCK`: the clock embed tokens are issued and checked with;
  * - `RUN_CONTEXT_CLOCK`: the clock run start reads the run context's date from, and the
  *   `CurrentTime` builtin the time;
@@ -44,6 +48,8 @@ interface KernelSeams {
     [SANDBOX_LEASE_TIMINGS]: Partial<SandboxLeaseTimings>;
     [CHANNEL_WEBHOOK_TIMINGS]: Partial<ChannelWebhookTimings>;
     [SETUP_CHECK_TIMEOUT]: number;
+    [PRESENCE_INTERVAL_MS]: number;
+    [ADMIN_USAGE_TIMINGS]: Partial<AdminUsageTimings>;
     [EMBED_TOKEN_CLOCK]: () => number;
     [RUN_CONTEXT_CLOCK]: () => number;
     [APP_INTERCEPTOR]: NestInterceptor;

package/dist/overrides.js

@@ -1,8 +1,10 @@
 import { APP_INTERCEPTOR } from "@nestjs/core";
+import { ADMIN_USAGE_TIMINGS } from "./admin/usage.service.js";
 import { CHANNEL_WEBHOOK_TIMINGS } from "./channels/webhook.js";
 import { EVAL_REPLAY_HOOKS } from "./evals/worker.js";
 import { BOOTSTRAP_LOCK_TTL } from "./extensions/bootstrap.js";
 import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
+import { PRESENCE_INTERVAL_MS } from "./infra/presence/replica-presence.js";
 import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
 import { RUN_CONTEXT_CLOCK } from "./runtime/run-context.service.js";
 import { AGENT_LOOP_FACTORY } from "./runtime/run-steps.js";
@@ -26,6 +28,8 @@ const SEAM_TOKENS = [
     SANDBOX_LEASE_TIMINGS,
     CHANNEL_WEBHOOK_TIMINGS,
     SETUP_CHECK_TIMEOUT,
+    PRESENCE_INTERVAL_MS,
+    ADMIN_USAGE_TIMINGS,
     EMBED_TOKEN_CLOCK,
     RUN_CONTEXT_CLOCK,
     APP_INTERCEPTOR,

package/dist/platform/exclusions.js

@@ -73,6 +73,11 @@ export const PLATFORM_EXCLUSIONS = [
         category: "human-only",
         reason: "Transfers ownership of an agent to another person",
     },
+    {
+        route: "POST /api/v1/admin/agents/:agentId/owner",
+        category: "human-only",
+        reason: "Transfers ownership of an org's agent to another person on the platform's behalf, as the org's own transfer route",
+    },
     // background
     {
         route: "GET /api/v1/orgs/:orgId/conversations/:id/background-tasks/:taskId/output",
@@ -541,6 +546,16 @@ export const PLATFORM_EXCLUSIONS = [
         category: "transport",
         reason: "Uploads a skill archive as multipart bytes",
     },
+    {
+        route: "POST /api/v1/orgs/:orgId/skills",
+        category: "transport",
+        reason: "Creates an org skill from an uploaded archive; uploads are multipart bytes",
+    },
+    {
+        route: "POST /api/v1/orgs/:orgId/agents/:agentId/skills/uploads",
+        category: "transport",
+        reason: "Uploads a skill archive as multipart bytes",
+    },
     // approvals
     {
         route: "POST /api/v1/orgs/:orgId/approvals/:id/decision",

package/dist/platform/operation.d.ts

@@ -91,7 +91,7 @@ export interface PlatformOperation<I = unknown> {
     mirrors: readonly string[];
     /**
      * Fields of the mirrored route (body, query, path params but `:orgId`) the input leaves out, e.g.
-     * `uploadId` of `skills.create` (spec §14.5 item 3; the parity test in `tools/checks` holds it).
+     * an `uploadId` (spec §14.5 item 3; the parity test in `tools/checks` holds it).
      */
     omits?: readonly string[];
     /** Input fields the mirrored route lacks, e.g. `cursor` of a paged list. */

package/dist/platform/operation.js

@@ -57,7 +57,7 @@ export const PLATFORM_DOMAINS = [
     },
     {
         id: "admin",
-        description: "The admin console (super admin): dashboard totals and deployment settings.",
+        description: "The admin console (super admin): dashboard totals, deployment settings, the org's members, and the agents and connectors of the org (read, delete, disable or enable; other orgs' only in the console).",
     },
     {
         id: "models",

package/dist/platform/ops/admin-items.ops.d.ts

@@ -0,0 +1,37 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { AdminAgents } from "../../agents/admin-agents.js";
+import { AgentsService } from "../../agents/agents.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { MembersService } from "../../orgs/members.service.js";
+import { AdminConnectors } from "../../tools/admin-connectors.js";
+import { ConnectorsService } from "../../tools/connectors.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Refusal of an item another org owns: the tool's results enter this org's event log, where
+ * another org's items do not belong (Platform tool spec §6.1, §14.5 item 1).
+ */
+export declare const OTHER_ORG_ITEM = "This belongs to another organization; the Platform tool acts only on this conversation's organization. Use the admin console.";
+/**
+ * The super admin's agent and connector operations of the `Platform` tool (admin agents and
+ * connectors spec §4.5): the admin console's views and writes, run through the same services as
+ * the routes. Unlike the console they cover only the conversation's org: lists filter to it, and
+ * reads and writes of another org's item are refused (Platform tool spec §6.1). The owner transfer
+ * is excluded (human-only, as the org's own transfer route).
+ */
+export declare class AdminItemsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly adminAgents;
+    private readonly agents;
+    private readonly adminConnectors;
+    private readonly connectors;
+    private readonly members;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, adminAgents: AdminAgents, agents: AgentsService, adminConnectors: AdminConnectors, connectors: ConnectorsService, members: MembersService, kdb: KernelDb);
+    /** The agent's admin detail when it is the conversation org's; else {@link OTHER_ORG_ITEM}. */
+    private agentOf;
+    /** The connector's admin detail when it is the conversation org's; else {@link OTHER_ORG_ITEM}. */
+    private connectorOf;
+    /** A precheck from a read: its `ApiError` code, or `notFound` for another org's item. */
+    private precheck;
+    onModuleInit(): void;
+}