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

package/dist/client/client-reports.service.js

@@ -0,0 +1,102 @@
+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 { ApiError } from "../errors.js";
+import { enabledExtensionsQuery } from "../extensions/enabled.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";
+import { ClientAccess } from "./client-access.service.js";
+/** Reports older than this (by `last_at`) are deleted by the daily prune (spec §10.4). */
+export const REPORT_RETENTION_DAYS = 30;
+/**
+ * Crash and load reports of client code (client extensions spec §10.4): one row per (plugin,
+ * build, org, contribution, kind), upserted so a crash loop is one row with a count. A report is
+ * accepted only for a build the reporter could fetch ({@link ClientAccess.fetchable}), in an org
+ * an extension enabled there, and a `contribution` that is null or a component of that build's
+ * manifest, so nobody writes rows about plugins or orgs they cannot see and the key bounds the
+ * rows (a made-up contribution cannot add one); anything else is the same 404
+ * `client.not_found` the delivery route answers.
+ */
+let ClientReports = class ClientReports {
+    db;
+    txHost;
+    access;
+    constructor(db, txHost, access) {
+        this.db = db;
+        this.txHost = txHost;
+        this.access = access;
+    }
+    /** A report from a workspace page of org `orgId`. */
+    async recordForOrg(accountId, orgId, body) {
+        const enabled = await this.db.db
+            .selectFrom(enabledExtensionsQuery(this.db.db, orgId).as("en"))
+            .select("en.plugin")
+            .where("en.plugin", "=", body.plugin)
+            .executeTakeFirst();
+        if (enabled === undefined)
+            throw notFound();
+        await this.check(accountId, false, body);
+        await this.upsert(orgId, body);
+    }
+    /** A report from the admin console (no org; super admins only, the caller checks that). */
+    async recordForAdmin(accountId, body) {
+        await this.check(accountId, true, body);
+        await this.upsert(null, body);
+    }
+    /** The build must be fetchable and the contribution null or one of its components. */
+    async check(accountId, superAdmin, b) {
+        const build = await this.access.fetchable(accountId, superAdmin, b.plugin, b.build);
+        if (build === null)
+            throw notFound();
+        if (b.contribution !== null && !build.components.has(b.contribution))
+            throw notFound();
+    }
+    async upsert(orgId, b) {
+        await this.db.db
+            .insertInto("extension_client_reports")
+            .values({
+            plugin: b.plugin,
+            build: b.build,
+            org_id: orgId,
+            contribution: b.contribution,
+            kind: b.kind,
+            last_message: b.message,
+        })
+            .onConflict((oc) => oc
+            .expression(sql `plugin, build, (coalesce(org_id, '')), (coalesce(contribution, '')), kind`)
+            .doUpdateSet({
+            count: sql `extension_client_reports.count + 1`,
+            last_at: sql `now()`,
+            last_message: b.message,
+        }))
+            .execute();
+    }
+    /** Deletes the reports last seen more than {@link REPORT_RETENTION_DAYS} days ago; the count. */
+    async prune() {
+        const r = await this.db.db
+            .deleteFrom("extension_client_reports")
+            .where("last_at", "<", sql `now() - make_interval(days => ${REPORT_RETENTION_DAYS})`)
+            .executeTakeFirst();
+        return Number(r.numDeletedRows);
+    }
+};
+__decorate([
+    Transactional()
+], ClientReports.prototype, "upsert", null);
+ClientReports = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(ClientAccess))
+], ClientReports);
+export { ClientReports };
+const notFound = () => new ApiError("client.not_found", "Client file not found");

package/dist/client/client-sign-in.service.d.ts

@@ -0,0 +1,21 @@
+import type { Keyring } from "../ctx/secrets.js";
+import type { UserPrincipal } from "../identity/principal.js";
+/**
+ * The sign-in ids of the shell reads (client extensions spec §4.2, `ClientApi.signIn`): an opaque
+ * id per plugin that stays the same for one sign-in (one web session, across token refreshes and
+ * every tab of it) and changes on the next sign-in, so client code can do something once per
+ * sign-in. It is `HMAC-SHA256(key, "<sign-in>\0<plugin>")` truncated to 128 bits, the key derived
+ * from the master keyring: not a credential and not reversible to the session id. The plugin name
+ * is an input only so that the id is not the same string in every plugin; that is no isolation
+ * boundary: client code runs with full trust in the page (spec D2) and can read the whole shell
+ * read (or the query cache), which lists every plugin's id. Derived per request from the
+ * principal, no state. A personal token (no session) is its own sign-in. Rotating the master key
+ * changes every id once (client code then treats the session as a new sign-in); during a rolling
+ * restart old and new replicas answer different ids, so it may look like more than one.
+ */
+export declare class ClientSignIn {
+    private readonly key;
+    constructor(keyring: Keyring);
+    /** The id function of the caller's sign-in: plugin name → that plugin's sign-in id. */
+    of(principal: UserPrincipal): (plugin: string) => string;
+}

package/dist/client/client-sign-in.service.js

@@ -0,0 +1,49 @@
+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 { createHmac } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { KEYRING } from "../infra/tokens.js";
+/** The HKDF purpose of the sign-in id key (`capybara:client-sign-in/v1`). */
+const SIGN_IN_KEY_INFO = "client-sign-in/v1";
+/** A sign-in id is 128 bits of the HMAC, base64url (22 characters). */
+const SIGN_IN_ID_BYTES = 16;
+/**
+ * The sign-in ids of the shell reads (client extensions spec §4.2, `ClientApi.signIn`): an opaque
+ * id per plugin that stays the same for one sign-in (one web session, across token refreshes and
+ * every tab of it) and changes on the next sign-in, so client code can do something once per
+ * sign-in. It is `HMAC-SHA256(key, "<sign-in>\0<plugin>")` truncated to 128 bits, the key derived
+ * from the master keyring: not a credential and not reversible to the session id. The plugin name
+ * is an input only so that the id is not the same string in every plugin; that is no isolation
+ * boundary: client code runs with full trust in the page (spec D2) and can read the whole shell
+ * read (or the query cache), which lists every plugin's id. Derived per request from the
+ * principal, no state. A personal token (no session) is its own sign-in. Rotating the master key
+ * changes every id once (client code then treats the session as a new sign-in); during a rolling
+ * restart old and new replicas answer different ids, so it may look like more than one.
+ */
+let ClientSignIn = class ClientSignIn {
+    key;
+    constructor(keyring) {
+        this.key = keyring.deriveKey(SIGN_IN_KEY_INFO).current;
+    }
+    /** The id function of the caller's sign-in: plugin name → that plugin's sign-in id. */
+    of(principal) {
+        const signIn = principal.via === "session" ? `session:${principal.sessionId}` : `pat:${principal.tokenId}`;
+        return (plugin) => createHmac("sha256", this.key)
+            .update(`${signIn}\0${plugin}`)
+            .digest()
+            .subarray(0, SIGN_IN_ID_BYTES)
+            .toString("base64url");
+    }
+};
+ClientSignIn = __decorate([
+    Injectable(),
+    __param(0, Inject(KEYRING))
+], ClientSignIn);
+export { ClientSignIn };

package/dist/client/client.controller.d.ts

@@ -0,0 +1,49 @@
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { AdminClientQuery, type ClientExtensionsResponse, ReportBody } from "./client.schemas.js";
+import { ClientAccess } from "./client-access.service.js";
+import { ClientReports } from "./client-reports.service.js";
+import { ClientSignIn } from "./client-sign-in.service.js";
+/**
+ * The workspace shell read of client extensions (client extensions spec §9.2), `ui.use` (guest and
+ * up; a person, not a service token): `GET /api/v1/orgs/:orgId/ui/client` →
+ * {@link ClientExtensionsResponse}: the extensions enabled in the org that run with an approved
+ * client build, their file URLs and integrity, the components the caller's role may use and the
+ * caller's sign-in id per plugin (`ClientSignIn`);
+ * `enabled: false` with no items under the kill switch. `no-store`: the set changes with an org
+ * switch, an upgrade or the kill switch.
+ */
+export declare class OrgClientController {
+    private readonly access;
+    private readonly reports;
+    private readonly signIn;
+    constructor(access: ClientAccess, reports: ClientReports, signIn: ClientSignIn);
+    list(principal: Principal, org: OrgContext): Promise<ClientExtensionsResponse>;
+    /**
+     * `POST /api/v1/orgs/:orgId/ui/client/reports` (spec §10.4), `ui.use`, a person, 20 per minute
+     * per account (`client-reports`): a crash or load report of client code → 204. 404
+     * `client.not_found` for an extension not on in the org or a build the caller cannot fetch; 400
+     * for a message over 500 characters.
+     */
+    report(principal: Principal, org: OrgContext, body: z.infer<typeof ReportBody>): Promise<void>;
+}
+/**
+ * The admin console's client set (spec §9.6), super admins only: `GET /api/v1/admin/ui/client
+ * ?plugin=` → {@link ClientExtensionsResponse} with only `platform.page` components and no
+ * stylesheets (the admin console runs no org client code); with `plugin`, at most that one (the
+ * page `/admin/p/<plugin>/<id>` reads its own). `no-store`.
+ */
+export declare class AdminClientController {
+    private readonly access;
+    private readonly reports;
+    private readonly signIn;
+    constructor(access: ClientAccess, reports: ClientReports, signIn: ClientSignIn);
+    list(principal: Principal, q: z.infer<typeof AdminClientQuery>): Promise<ClientExtensionsResponse>;
+    /**
+     * `POST /api/v1/admin/ui/client/reports` (spec §10.4), super admins, 20 per minute per account:
+     * a report from an admin page (stored with no org) → 204; 404 `client.not_found` for a build
+     * that has no `platform.page` component or is not served.
+     */
+    report(principal: Principal, body: z.infer<typeof ReportBody>): Promise<void>;
+}

package/dist/client/client.controller.js

@@ -0,0 +1,129 @@
+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 { Controller, Get, Header, HttpCode, Inject, Post } from "@nestjs/common";
+import { CurrentPrincipal, requireUser, SuperAdmin, } from "../identity/principal.js";
+import { Throttled } from "../infra/throttler/throttler.guard.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { AdminClientQuery, ReportBody } from "./client.schemas.js";
+import { ClientAccess } from "./client-access.service.js";
+import { ClientReports } from "./client-reports.service.js";
+import { ClientSignIn } from "./client-sign-in.service.js";
+class AdminClientQueryDto extends createZodDto(AdminClientQuery, "AdminClientQuery") {
+}
+class ReportBodyDto extends createZodDto(ReportBody, "ClientReportBody") {
+}
+/**
+ * The workspace shell read of client extensions (client extensions spec §9.2), `ui.use` (guest and
+ * up; a person, not a service token): `GET /api/v1/orgs/:orgId/ui/client` →
+ * {@link ClientExtensionsResponse}: the extensions enabled in the org that run with an approved
+ * client build, their file URLs and integrity, the components the caller's role may use and the
+ * caller's sign-in id per plugin (`ClientSignIn`);
+ * `enabled: false` with no items under the kill switch. `no-store`: the set changes with an org
+ * switch, an upgrade or the kill switch.
+ */
+let OrgClientController = class OrgClientController {
+    access;
+    reports;
+    signIn;
+    constructor(access, reports, signIn) {
+        this.access = access;
+        this.reports = reports;
+        this.signIn = signIn;
+    }
+    async list(principal, org) {
+        const user = requireUser(principal);
+        return this.access.orgSet(org.orgId, org.role, this.signIn.of(user));
+    }
+    /**
+     * `POST /api/v1/orgs/:orgId/ui/client/reports` (spec §10.4), `ui.use`, a person, 20 per minute
+     * per account (`client-reports`): a crash or load report of client code → 204. 404
+     * `client.not_found` for an extension not on in the org or a build the caller cannot fetch; 400
+     * for a message over 500 characters.
+     */
+    async report(principal, org, body) {
+        const user = requireUser(principal);
+        await this.reports.recordForOrg(user.account.id, org.orgId, body);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("ui.use"),
+    Header("cache-control", "no-store"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], OrgClientController.prototype, "list", null);
+__decorate([
+    Post("reports"),
+    OrgAction("ui.use"),
+    HttpCode(204),
+    Throttled("client-reports"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZBody(ReportBodyDto))
+], OrgClientController.prototype, "report", null);
+OrgClientController = __decorate([
+    Controller("api/v1/orgs/:orgId/ui/client"),
+    __param(0, Inject(ClientAccess)),
+    __param(1, Inject(ClientReports)),
+    __param(2, Inject(ClientSignIn))
+], OrgClientController);
+export { OrgClientController };
+/**
+ * The admin console's client set (spec §9.6), super admins only: `GET /api/v1/admin/ui/client
+ * ?plugin=` → {@link ClientExtensionsResponse} with only `platform.page` components and no
+ * stylesheets (the admin console runs no org client code); with `plugin`, at most that one (the
+ * page `/admin/p/<plugin>/<id>` reads its own). `no-store`.
+ */
+let AdminClientController = class AdminClientController {
+    access;
+    reports;
+    signIn;
+    constructor(access, reports, signIn) {
+        this.access = access;
+        this.reports = reports;
+        this.signIn = signIn;
+    }
+    async list(principal, q) {
+        const user = requireUser(principal);
+        return this.access.platformSet(this.signIn.of(user), q.plugin);
+    }
+    /**
+     * `POST /api/v1/admin/ui/client/reports` (spec §10.4), super admins, 20 per minute per account:
+     * a report from an admin page (stored with no org) → 204; 404 `client.not_found` for a build
+     * that has no `platform.page` component or is not served.
+     */
+    async report(principal, body) {
+        const user = requireUser(principal);
+        await this.reports.recordForAdmin(user.account.id, body);
+    }
+};
+__decorate([
+    Get(),
+    Header("cache-control", "no-store"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZQuery(AdminClientQueryDto))
+], AdminClientController.prototype, "list", null);
+__decorate([
+    Post("reports"),
+    HttpCode(204),
+    Throttled("client-reports"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZBody(ReportBodyDto))
+], AdminClientController.prototype, "report", null);
+AdminClientController = __decorate([
+    Controller("api/v1/admin/ui/client"),
+    SuperAdmin(),
+    __param(0, Inject(ClientAccess)),
+    __param(1, Inject(ClientReports)),
+    __param(2, Inject(ClientSignIn))
+], AdminClientController);
+export { AdminClientController };

package/dist/client/client.module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Client extensions (spec 2026-11-09-client-extensions-design.md): the client builds stored with
+ * extension packages ({@link ClientBuilds}) and who may load them ({@link ClientAccess}: the
+ * delivery route and the shell reads, whose controllers the api role lists; {@link ClientSignIn}:
+ * the per-plugin sign-in ids of those reads).
+ */
+export declare class ClientModule {
+}

package/dist/client/client.module.js

@@ -0,0 +1,28 @@
+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 { Module } from "@nestjs/common";
+import { StorageModule } from "../storage/storage.module.js";
+import { ClientAccess } from "./client-access.service.js";
+import { ClientBuilds } from "./client-builds.service.js";
+import { ClientReports } from "./client-reports.service.js";
+import { ClientSignIn } from "./client-sign-in.service.js";
+/**
+ * Client extensions (spec 2026-11-09-client-extensions-design.md): the client builds stored with
+ * extension packages ({@link ClientBuilds}) and who may load them ({@link ClientAccess}: the
+ * delivery route and the shell reads, whose controllers the api role lists; {@link ClientSignIn}:
+ * the per-plugin sign-in ids of those reads).
+ */
+let ClientModule = class ClientModule {
+};
+ClientModule = __decorate([
+    Module({
+        imports: [StorageModule],
+        providers: [ClientBuilds, ClientAccess, ClientReports, ClientSignIn],
+        exports: [ClientBuilds, ClientAccess, ClientReports, ClientSignIn],
+    })
+], ClientModule);
+export { ClientModule };

package/dist/client/client.schemas.d.ts

@@ -0,0 +1,61 @@
+import { type UiSlotId } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas and response shapes of the client extension routes (spec §9.2). */
+/** `GET /api/v1/admin/ui/client?plugin=`: at most that plugin's platform set. */
+export declare const AdminClientQuery: z.ZodObject<{
+    plugin: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One file URL of a client build, with the integrity recorded when the package was stored. */
+export interface ClientFileRef {
+    url: string;
+    integrity: string;
+}
+/** One extension of a shell read: its build's files and the components the viewer may use. */
+export interface ClientExtensionItem {
+    plugin: string;
+    /** The package sha256: the build id in the file URLs. */
+    build: string;
+    entry: ClientFileRef | null;
+    /** Empty in the admin set (spec §9.6). */
+    styles: ClientFileRef[];
+    components: {
+        id: string;
+        slot: UiSlotId;
+    }[];
+    /**
+     * The viewer's sign-in id for this plugin (`ClientApi.signIn.id`, spec §4.2): opaque, the same
+     * for every read of one sign-in and different after the next one; a different string per plugin,
+     * not a secret between plugins (client code is full trust and reads the whole set).
+     */
+    signInId: string;
+}
+/** The shell read (spec §9.2). */
+export interface ClientExtensionsResponse {
+    /** False under the kill switch: `items` is then empty. */
+    enabled: boolean;
+    /** The host's `CLIENT_API_VERSION`, echoed for diagnostics. */
+    apiVersion: number;
+    items: ClientExtensionItem[];
+}
+/** The most characters of a report's `message` (spec §10.4): longer is refused, not truncated. */
+export declare const REPORT_MESSAGE_MAX = 500;
+/**
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` (spec
+ * §10.4): one crash or load report of client code, from the browser that ran it. `build` is the
+ * package sha256 the files were loaded from; `contribution` the component id (null: the whole
+ * extension, e.g. the entry failed to load), which must be a component of that build's manifest.
+ */
+export declare const ReportBody: z.ZodObject<{
+    plugin: z.ZodString;
+    build: z.ZodString;
+    contribution: z.ZodNullable<z.ZodString>;
+    kind: z.ZodEnum<{
+        api: "api";
+        budget: "budget";
+        event: "event";
+        load: "load";
+        render: "render";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type ReportBodyInput = z.infer<typeof ReportBody>;

package/dist/client/client.schemas.js

@@ -0,0 +1,27 @@
+import { EXTENSION_NAME_RE } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/** The DTO schemas and response shapes of the client extension routes (spec §9.2). */
+/** `GET /api/v1/admin/ui/client?plugin=`: at most that plugin's platform set. */
+export const AdminClientQuery = z.object({
+    plugin: z.string().regex(EXTENSION_NAME_RE, "must be an extension name").optional(),
+});
+/** The most characters of a report's `message` (spec §10.4): longer is refused, not truncated. */
+export const REPORT_MESSAGE_MAX = 500;
+/** The UI contribution id grammar of the SDK (`ui[].id`): what a report's `contribution` names. */
+const COMPONENT_ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+/**
+ * `POST /api/v1/orgs/:orgId/ui/client/reports` and `POST /api/v1/admin/ui/client/reports` (spec
+ * §10.4): one crash or load report of client code, from the browser that ran it. `build` is the
+ * package sha256 the files were loaded from; `contribution` the component id (null: the whole
+ * extension, e.g. the entry failed to load), which must be a component of that build's manifest.
+ */
+export const ReportBody = z.object({
+    plugin: z.string().regex(EXTENSION_NAME_RE, "must be an extension name"),
+    build: z.string().regex(/^[0-9a-f]{64}$/, "must be a 64-character lowercase hex sha256"),
+    contribution: z
+        .string()
+        .regex(COMPONENT_ID_RE, "must be a component id of the build (or null)")
+        .nullable(),
+    kind: z.enum(["load", "render", "event", "api", "budget"]),
+    message: z.string().max(REPORT_MESSAGE_MAX),
+});

package/dist/config/docs.js

@@ -63,7 +63,9 @@ export function renderConfigDocs(schema) {
         // body and package upload limits), apps/web/server.mjs (PORT / CAPYBARA_WEB_HOST) and
         // apps/web/src/dev/catalog/routes.tsx (CAPYBARA_DEV_UI); change this text together with them.
         // CAPYBARA_WEB_TRUST_PROXY: apps/web/src/lib/peer.ts; CAPYBARA_WEB_SHUTDOWN_GRACE_MS: apps/web/server.mjs.
+        // CAPYBARA_WEB_KEEP_ALIVE_TIMEOUT_MS: apps/web/src/lib/keep-alive.ts.
         // CAPYBARA_WEB_OBJECT_STORE_*: apps/web/src/lib/object-store-proxy.ts.
+        // CAPYBARA_WEB_GATEWAY_URL: apps/web/src/lib/device-connect-proxy.ts.
         "## Web tier (apps/web) environment variables",
         "",
         "The web tier is a separate process (started through `apps/web/server.mjs`); it does not read the kernel config and only honors the following environment variables:",
@@ -74,11 +76,13 @@ export function renderConfigDocs(schema) {
         "| `PORT` / `CAPYBARA_WEB_HOST` | The web tier's listen port (default 3000) and address |",
         "| `CAPYBARA_WEB_TRUST_PROXY` | Proxies in front of the web tier (TLS proxy, load balancer) trusted to report the client address in `X-Forwarded-For`: a hop count (`1` = the nearest proxy) or a list of IPs / CIDRs, comma-separated or a JSON array, in the grammar of `http.trustProxy` (dotted netmasks, `loopback` / `linklocal` / `uniquelocal`; a range that trusts every address such as `/0` is refused; no `true` / `false`). Unset (default) trusts nothing: the socket peer is the client, so behind a proxy every user shares the proxy's address for login rate limiting. A hop count is only safe when the web tier is reachable solely through exactly that many proxies. Either way the kernel receives one sanitized client address; a malformed value stops the web tier at startup |",
         "| `CAPYBARA_WEB_SHUTDOWN_GRACE_MS` | Production only: after SIGTERM / SIGINT, how long in-flight requests (including SSE streams) may run before the process exits; default 5000 |",
+        "| `CAPYBARA_WEB_KEEP_ALIVE_TIMEOUT_MS` | How long an idle HTTP keep-alive connection to the web tier stays open, in milliseconds; default 65000. Keep it above the idle timeout of any load balancer or proxy in front of the web tier (often 60 s): otherwise the web tier may close a connection just as the proxy reuses it, and that request fails (a 502 at the proxy). A value that is not a positive integer stops the web tier at startup |",
         "| `CAPYBARA_WEB_MAX_BODY_BYTES` | Request body limit of the `/api/*` proxy, default 1 MiB (matches the kernel's bodyLimit) |",
-        "| `CAPYBARA_WEB_MAX_PACKAGE_BYTES` | Request body limit for extension package and plugin uploads (`/api/v1/admin/extensions/packages/file`, `/api/v1/admin/catalog/import/file`), default 50 MiB, forwarded while being read. This is the web tier's limit; the kernel additionally rejects by `packages.maxBytes`. Raise both together, otherwise a large package uploaded through the web is first rejected by the web tier with a 413 |",
+        "| `CAPYBARA_WEB_MAX_PACKAGE_BYTES` | Request body limit for extension package and plugin uploads (`/api/v1/admin/extensions/packages/file`, `/api/v1/admin/catalog/import/file`, `/api/v1/orgs/:orgId/catalog/uploads/file`), default 50 MiB, forwarded while being read. This is the web tier's limit; the kernel additionally rejects by `packages.maxBytes`. Raise both together, otherwise a large package uploaded through the web is first rejected by the web tier with a 413 |",
         "| `CAPYBARA_WEB_OBJECT_STORE_URL` | Object storage on the web origin: the object store's address as web reaches it (e.g. `http://seaweedfs-s3:8333`). When set, web proxies `/<bucket>/**` (and `/<bucket>` itself for POST only) there, so browsers upload attachments (presigned POST) and download attachments and artifacts (presigned GET) through web; set the object-store extension's `publicEndpoint` to the web origin with `forcePathStyle: true`. Only GET, HEAD and POST; the path is forwarded unchanged; cookies and authorization are not forwarded; responses carry `X-Content-Type-Options: nosniff` and `Content-Security-Policy: sandbox`; uploads are capped at `CAPYBARA_WEB_MAX_PACKAGE_BYTES`. Unset (default): off |",
         "| `CAPYBARA_WEB_OBJECT_STORE_BUCKET` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the bucket, equal to the object-store extension's `bucket` (it is the first path segment web proxies) |",
         "| `CAPYBARA_WEB_OBJECT_STORE_PUBLIC_HOST` | With `CAPYBARA_WEB_OBJECT_STORE_URL`: the host of the extension's `publicEndpoint` (a host such as `capybara.example.com`, or that URL). Sent upstream as `Host` instead of the incoming one, because presigned URLs sign the host they were issued for and front proxies rewrite it |",
+        "| `CAPYBARA_WEB_GATEWAY_URL` | Local devices on the web origin: a `gateway` replica's address as web reaches it (an http(s) URL, e.g. `http://gateway:8080`). WebSocket upgrades on exactly `/device/connect` are forwarded to it (`capybara-device` connects at `<http.publicUrl>/device/connect`). Unset, they go to `CAPYBARA_KERNEL_URL` (the kernel runs every role unless the deployment splits them), so only deployments with separate gateway replicas set it (compose does). A malformed value stops the web tier at startup |",
         "| `CAPYBARA_DEV_UI` | When set to `1`, production builds also serve the `/dev/ui` component catalog page (off by default) |",
         "",
     ].join("\n");

package/dist/config/schema.d.ts

@@ -51,6 +51,7 @@ export declare const KernelConfigSchema: z.ZodObject<{
         url: z.ZodString;
         poolMax: z.ZodDefault<z.ZodNumber>;
         connectTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        idleTimeoutMs: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     redis: z.ZodPrefault<z.ZodObject<{
         url: z.ZodString;
@@ -119,6 +120,7 @@ export declare const KernelConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     runtime: z.ZodDefault<z.ZodObject<{
         maxSteps: z.ZodDefault<z.ZodNumber>;
+        wakeOnBackgroundTask: z.ZodDefault<z.ZodBoolean>;
         maxRunSeconds: z.ZodDefault<z.ZodNumber>;
         streamIdleMs: z.ZodDefault<z.ZodNumber>;
         maxOutputTokens: z.ZodDefault<z.ZodNumber>;
@@ -175,15 +177,32 @@ export declare const KernelConfigSchema: z.ZodObject<{
         requestMediaBytes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     subagents: z.ZodPrefault<z.ZodObject<{
-        maxConcurrentPerRun: z.ZodDefault<z.ZodNumber>;
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        maxConcurrentPerConversation: z.ZodDefault<z.ZodNumber>;
         maxDispatchesPerRun: z.ZodDefault<z.ZodNumber>;
         maxTokensPerRun: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    web: z.ZodPrefault<z.ZodObject<{
+        search: z.ZodPrefault<z.ZodObject<{
+            maxResults: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        fetch: z.ZodPrefault<z.ZodObject<{
+            maxPageChars: z.ZodDefault<z.ZodNumber>;
+            maxAnswerTokens: z.ZodDefault<z.ZodNumber>;
+            cacheSeconds: z.ZodDefault<z.ZodNumber>;
+            timeoutMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     sandbox: z.ZodPrefault<z.ZodObject<{
-        image: z.ZodDefault<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
         lockWaitSeconds: z.ZodDefault<z.ZodNumber>;
         maxConcurrentCommands: z.ZodDefault<z.ZodNumber>;
         deliverMaxBytes: z.ZodDefault<z.ZodNumber>;
+        background: z.ZodPrefault<z.ZodObject<{
+            maxTasks: z.ZodDefault<z.ZodNumber>;
+            maxSeconds: z.ZodDefault<z.ZodNumber>;
+            pollSeconds: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
         limits: z.ZodPrefault<z.ZodObject<{
             cpu: z.ZodDefault<z.ZodNumber>;
             memoryMb: z.ZodDefault<z.ZodNumber>;
@@ -200,6 +219,16 @@ export declare const KernelConfigSchema: z.ZodObject<{
             allowHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    devices: z.ZodPrefault<z.ZodObject<{
+        maxPersonal: z.ZodDefault<z.ZodNumber>;
+        local: z.ZodPrefault<z.ZodObject<{
+            reconnectGraceSeconds: z.ZodDefault<z.ZodNumber>;
+            leaseTtlMs: z.ZodDefault<z.ZodNumber>;
+            authCodeTtlSeconds: z.ZodDefault<z.ZodNumber>;
+            pollIntervalSeconds: z.ZodDefault<z.ZodNumber>;
+            maxFrameBytes: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     evals: z.ZodPrefault<z.ZodObject<{
         orgConcurrency: z.ZodDefault<z.ZodNumber>;
         workerConcurrency: z.ZodDefault<z.ZodNumber>;
@@ -210,6 +239,10 @@ export declare const KernelConfigSchema: z.ZodObject<{
         judgeMaxOutputTokens: z.ZodDefault<z.ZodNumber>;
         maxConsecutiveErrors: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    models: z.ZodPrefault<z.ZodObject<{
+        listTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        embedTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     hooks: z.ZodPrefault<z.ZodObject<{
         timeoutMs: z.ZodDefault<z.ZodNumber>;
         usageReportConcurrency: z.ZodDefault<z.ZodNumber>;