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

package/dist/devices/devices.controller.js

@@ -0,0 +1,124 @@
+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, Delete, Get, HttpCode, Inject, Patch, Post } from "@nestjs/common";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { DevicesService } from "./devices.service.js";
+import { DeviceCreateBodyDto, DeviceParamsDto, DeviceRenameBodyDto, } from "./dto.js";
+/**
+ * A person's devices in an org (`/api/v1/orgs/:orgId/devices`, spec
+ * 2026-11-07-environments-design §9; `agents.use`, human users only: a service token gets 403).
+ * Phase 1 has personal cloud devices only, each visible to its owner alone: another member
+ * gets 404 `device.not_found`.
+ * - `GET /` → `{ items, defaultId, lastUsedId, cloudAvailable }` (`cloudAvailable`: there is a
+ *   current sandbox provider; ruling R4);
+ * - `POST / { name }` → 201 `{ device }`; `GET /:id`, `PATCH /:id { name }` → `{ device }`;
+ * - `DELETE /:id` → 202 (destroyed by a job after the response);
+ * - `POST /:id/files/reset` → 202 (the reset is enqueued: a worker empties the files, the next use
+ *   starts empty);
+ * - `DELETE /:id/machine` → 204: a local device's machine is disconnected (its credential
+ *   revoked; it must sign in again).
+ */
+let DevicesController = class DevicesController {
+    devices;
+    constructor(devices) {
+        this.devices = devices;
+    }
+    async list(principal, org) {
+        const p = requireUser(principal);
+        return this.devices.list(org.orgId, p.account.id);
+    }
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        return {
+            device: await this.devices.create(org.orgId, p.account.id, { name: body.name }, patTokenId(p)),
+        };
+    }
+    async get(principal, org, params) {
+        const p = requireUser(principal);
+        return { device: await this.devices.get(org.orgId, p.account.id, params.id) };
+    }
+    async rename(principal, org, params, body) {
+        const p = requireUser(principal);
+        return {
+            device: await this.devices.rename(org.orgId, p.account.id, params.id, body.name, patTokenId(p)),
+        };
+    }
+    async remove(principal, org, params) {
+        const p = requireUser(principal);
+        await this.devices.remove(org.orgId, p.account.id, params.id, patTokenId(p));
+    }
+    async resetFiles(principal, org, params) {
+        const p = requireUser(principal);
+        await this.devices.resetFiles(org.orgId, p.account.id, params.id, patTokenId(p));
+    }
+    async revokeMachine(principal, org, params) {
+        const p = requireUser(principal);
+        await this.devices.revokeMachine(org.orgId, p.account.id, params.id, patTokenId(p));
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], DevicesController.prototype, "list", null);
+__decorate([
+    Post(),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZBody(DeviceCreateBodyDto))
+], DevicesController.prototype, "create", null);
+__decorate([
+    Get(":id"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(DeviceParamsDto))
+], DevicesController.prototype, "get", null);
+__decorate([
+    Patch(":id"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(DeviceParamsDto)),
+    __param(3, ZBody(DeviceRenameBodyDto))
+], DevicesController.prototype, "rename", null);
+__decorate([
+    Delete(":id"),
+    HttpCode(202),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(DeviceParamsDto))
+], DevicesController.prototype, "remove", null);
+__decorate([
+    Post(":id/files/reset"),
+    HttpCode(202),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(DeviceParamsDto))
+], DevicesController.prototype, "resetFiles", null);
+__decorate([
+    Delete(":id/machine"),
+    HttpCode(204),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(DeviceParamsDto))
+], DevicesController.prototype, "revokeMachine", null);
+DevicesController = __decorate([
+    Controller("api/v1/orgs/:orgId/devices"),
+    __param(0, Inject(DevicesService))
+], DevicesController);
+export { DevicesController };

package/dist/devices/devices.module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Devices (spec 2026-11-07-environments-design): a person's devices
+ * ({@link DevicesService}), who may use one ({@link DeviceAccess}) and the one a
+ * conversation works in ({@link ConversationDevices}). The instances and file systems are the
+ * {@link SandboxModule}'s.
+ */
+export declare class DevicesModule {
+}

package/dist/devices/devices.module.js

@@ -0,0 +1,34 @@
+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 { ExtensionsModule } from "../extensions/extensions.module.js";
+import { LocalDevicesModule } from "../local-devices/local-devices.module.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { SandboxFileReader } from "../sandbox/sandbox-file-reader.js";
+import { DeviceAccess } from "./access.js";
+import { ConversationDevices } from "./conversation-devices.js";
+import { DevicesService } from "./devices.service.js";
+/**
+ * Devices (spec 2026-11-07-environments-design): a person's devices
+ * ({@link DevicesService}), who may use one ({@link DeviceAccess}) and the one a
+ * conversation works in ({@link ConversationDevices}). The instances and file systems are the
+ * {@link SandboxModule}'s.
+ */
+let DevicesModule = class DevicesModule {
+};
+DevicesModule = __decorate([
+    Module({
+        // ExtensionsModule: the provider display names of demoted defaults; LocalDevicesModule: deleting
+        // a local device revokes its machine
+        imports: [SandboxModule, ExtensionsModule, LocalDevicesModule],
+        // SandboxFileReader lives here, not in SandboxModule: it needs ConversationDevices, and this
+        // module already imports SandboxModule (the other way would be a module cycle)
+        providers: [DeviceAccess, DevicesService, ConversationDevices, SandboxFileReader],
+        exports: [DeviceAccess, DevicesService, ConversationDevices, SandboxFileReader],
+    })
+], DevicesModule);
+export { DevicesModule };

package/dist/devices/devices.schemas.d.ts

@@ -0,0 +1,3 @@
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** The devices routes the Platform operations mirror (`check:platform-ops` keys). */
+export declare const DEVICE_ROUTES: readonly RouteSchemas[];

package/dist/devices/devices.schemas.js

@@ -0,0 +1,14 @@
+import { DeviceNameBody, DeviceParams } from "./dto.js";
+/** The devices routes the Platform operations mirror (`check:platform-ops` keys). */
+export const DEVICE_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/devices" },
+    { route: "POST /api/v1/orgs/:orgId/devices", body: DeviceNameBody },
+    { route: "GET /api/v1/orgs/:orgId/devices/:id", params: DeviceParams },
+    {
+        route: "PATCH /api/v1/orgs/:orgId/devices/:id",
+        params: DeviceParams,
+        body: DeviceNameBody,
+    },
+    { route: "DELETE /api/v1/orgs/:orgId/devices/:id", params: DeviceParams },
+    { route: "POST /api/v1/orgs/:orgId/devices/:id/files/reset", params: DeviceParams },
+];

package/dist/devices/devices.service.d.ts

@@ -0,0 +1,251 @@
+import type { LocalizedName, SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+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 { LockService } from "../infra/lock/lock.service.js";
+import { MachinesService } from "../local-devices/machines.js";
+import type { KernelLogger } from "../log.js";
+import { SandboxJobs } from "../sandbox/jobs.js";
+import { SandboxProviders } from "../sandbox/providers.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { DeviceAccess } from "./access.js";
+/** A device as its owner sees it (`GET /orgs/:orgId/devices`). */
+export interface DeviceView {
+    id: string;
+    /**
+     * null for the default device (shown as 「个人设备」 / "Personal") and for a demoted default
+     * (shown as 「个人设备（Docker 沙箱）」 / "Personal (Docker sandbox)", from {@link demotedFrom}).
+     */
+    name: string | null;
+    isDefault: boolean;
+    /**
+     * A former default demoted by a sandbox provider switch (spec §4.2 item 13): the provider it was
+     * demoted from, that extension's display name (null when it has none, e.g. uninstalled: show the
+     * id), and its place among the person's unnamed former defaults of that provider (1, 2, … by
+     * creation; a label shows " 2", " 3", … after the first). Switching back to that provider makes
+     * it the default again. null for every other device.
+     */
+    demotedFrom: {
+        provider: string;
+        displayName: LocalizedName | null;
+        ordinal: number;
+    } | null;
+    ownerKind: "personal";
+    /** `local`: a machine connected with capybara-device (provider `@local`). */
+    source: "cloud" | "local";
+    /** The provider keeping its files, or the one its first use will create them with. */
+    provider: string | null;
+    /** Its provider is there: the deployment's current cloud provider, or `@local` registered. */
+    available: boolean;
+    /** A local device: some replica holds its machine's connection now; null for cloud. */
+    online: boolean | null;
+    /** A local device's connected machine (its unrevoked one); null for cloud or none. */
+    machine: DeviceMachineView | null;
+    sessionIsolation: boolean;
+    /** Its file system is gone at the provider; reset the files to use it again. */
+    filesLost: boolean;
+    instance: {
+        status: "running" | "suspended";
+        lastUsedAt: string;
+    } | null;
+    /** The org's effective sandbox limits (phase 1 devices use them unchanged, spec §8.4). */
+    limits: SandboxLimits;
+    createdAt: string;
+}
+/** The machine connected to a local device, as its owner sees it. */
+export interface DeviceMachineView {
+    id: string;
+    name: string;
+    os: string;
+    mode: "os" | "docker" | null;
+    programVersion: string | null;
+    lastSeenAt: string | null;
+}
+/** The list response: the person's live devices in the org. */
+export interface DeviceList {
+    items: DeviceView[];
+    /** The person's default device; null when there is none (no sandbox provider to make it). */
+    defaultId: string | null;
+    /** The device of the person's most recently updated conversation that has a live one. */
+    lastUsedId: string | null;
+    /** There is a current sandbox provider (new cloud devices can be made; ruling R4). */
+    cloudAvailable: boolean;
+}
+/**
+ * Personal devices (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §6; §9):
+ * cloud ones on the deployment's sandbox provider and `device` ones on a connected machine; a
+ * person's devices in an org, visible and usable only by their owner (anyone else gets
+ * `device.not_found`). Deleting one soft-deletes it and destroys its instance and files in a
+ * `sandbox-destroy-for` job after the commit.
+ */
+export declare class DevicesService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly config;
+    private readonly providers;
+    private readonly sandbox;
+    private readonly sandboxJobs;
+    private readonly access;
+    private readonly displayNames;
+    private readonly log;
+    /** Reads the device relay's lease (`online`). */
+    private readonly locks;
+    private readonly machines;
+    constructor(db: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, providers: Pick<SandboxProviders, "cloud" | "forName">, sandbox: Pick<SandboxService, "orgLimits">, sandboxJobs: Pick<SandboxJobs, "destroy" | "resetFiles">, access: Pick<DeviceAccess, "usable">, displayNames: Pick<ExtensionDisplayNames, "many">, log: Pick<KernelLogger, "warn">, 
+    /** Reads the device relay's lease (`online`). */
+    locks: Pick<LockService, "holderOf">, machines: Pick<MachinesService, "revoke" | "revokeActive">);
+    /**
+     * The person's live devices in the org, the default first, then by creation. With a
+     * current sandbox provider the default device is created first if missing (its first need,
+     * spec §4.2 item 7; an existing one is only read).
+     */
+    list(orgId: string, accountId: string): Promise<DeviceList>;
+    /** One of the person's live devices; anyone else's (or a missing one) → `not_found`. */
+    get(orgId: string, accountId: string, id: string): Promise<DeviceView>;
+    /**
+     * A new personal cloud device, ready at once (its instance and files are made on first
+     * use). Needs a current sandbox provider (`device.unavailable`); a live name of the person's
+     * (case-insensitive) → `device.name_taken`; `devices.maxPersonal` live ones (the
+     * default counts) → `device.limit_reached`. Serialized per person by their membership row.
+     */
+    create(orgId: string, accountId: string, input: {
+        name: string;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<DeviceView>;
+    private insert;
+    /**
+     * A new personal local device for a machine being connected (provider `@local`; the
+     * machine row is the caller's). Joins the caller's transaction (the device authorization's).
+     * Counted against `devices.maxPersonal` (`device.limit_reached`); a live name of the
+     * person's → `device.name_taken`. Needs no cloud provider.
+     */
+    createLocal(orgId: string, accountId: string, name: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Inserts a named personal device under the person's membership lock, after the limit
+     * and name checks, and audits `device.created`. Runs in the caller's transaction.
+     */
+    private insertNamed;
+    /**
+     * The refusals {@link create} would raise, read without locks or writes (a precheck before a
+     * confirmation card): no sandbox provider, the person's limit, a name already taken. Throws the
+     * same {@link ApiError}s; a race still ends in `create`'s own refusal.
+     */
+    checkCreate(orgId: string, accountId: string, name: string): Promise<void>;
+    /** How many of the person's conversations work in the device (read only). */
+    boundConversations(orgId: string, accountId: string, id: string): Promise<number>;
+    /**
+     * The refusals {@link resetFiles} would raise (not found, its provider not current, a connected
+     * device), read only.
+     */
+    checkReset(orgId: string, accountId: string, id: string): Promise<void>;
+    /** The refusals {@link rename} would raise, read without locks (see {@link checkCreate}). */
+    checkRename(orgId: string, accountId: string, id: string, name: string): Promise<void>;
+    /**
+     * Renames one of the person's live devices (the default too); see {@link create}. A
+     * renamed former default is the person's own from then on: it loses its demotion mark, so a
+     * switch back to its provider no longer restores it.
+     */
+    rename(orgId: string, accountId: string, id: string, name: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<DeviceView>;
+    private renameIn;
+    /**
+     * Deletes one of the person's live devices: soft delete, its IM default row cleared, and
+     * after the commit a `sandbox-destroy-for` job (the worker waits for running commands, then
+     * destroys the instance and the files). Conversations bound to it keep pointing at it; their
+     * sandbox tools then fail with `device.not_found`. A local device's machine is
+     * revoked in the same transaction; after the commit it is told `stop { reason: "deleted" }`
+     * (while connected) and its connection is closed.
+     */
+    remove(orgId: string, accountId: string, id: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
+    /**
+     * Disconnects the machine of one of the person's own local devices (it must sign in
+     * again); see {@link MachinesService.revoke}.
+     */
+    revokeMachine(orgId: string, accountId: string, id: string, actorTokenId?: string): Promise<void>;
+    /**
+     * Starts one of the person's devices over with empty files (after
+     * `device.files_lost`): records the request (audit), then, after the commit, enqueues the
+     * `sandbox-reset-files` job (deterministic id per device), whose worker waits for running
+     * commands and destroys any instance and the file system; the next use creates new ones. Its
+     * provider must be the current one (`device.unavailable`); a local device's files
+     * are its machine owner's (`device.files_on_device`). An enqueue failure is thrown
+     * (the request can be repeated: the reset is idempotent).
+     */
+    resetFiles(orgId: string, accountId: string, id: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
+    /** The check and audit row of {@link resetFiles}, committed before the job is enqueued. */
+    private recordReset;
+    /**
+     * The person's default device in the org, created when missing (named by the UI, `name`
+     * NULL). An existing usable one is read without locking. A live default whose files or
+     * instance are kept by a provider that is not the current one (a provider switch, spec §4.2
+     * item 13) is stranded: it is demoted (marked with the provider it was demoted from; the UI
+     * names it 「个人设备（<provider display name>）」) and stays listed as unavailable and deletable.
+     * Its replacement is the person's former default demoted from the current provider when there
+     * is one (switching back restores it, with its files), else a fresh default. A live default
+     * not in use yet (no healthy files, no instance, none being created: {@link inUseForDefault})
+     * is likewise swapped for a former default holding healthy files at the current provider; it is
+     * demoted (from the provider it was made under) so it can come back in turn. A former default
+     * belongs to the provider holding its resources once it holds any, else to the one it was
+     * demoted from ({@link demotedProvider}), so one swapped out empty and used afterwards is
+     * labelled and restored by where its files are.
+     * All of it in one transaction: switching back and forth never adds devices.
+     *
+     * Replacing one first takes the person's membership row (`FOR SHARE`, after the org row), so an
+     * offboarding that removes them cannot leave a live default behind; not a member (any more) →
+     * `org.not_found`. Idempotent under concurrency: the live default row and the person's former
+     * defaults of the current provider are locked (`FOR NO KEY UPDATE`) and the live default re-read
+     * after them, the partial unique index on the live default makes a racing insert do nothing, and
+     * the select that follows reads the winner. Needs a current sandbox provider
+     * (`device.unavailable`). It is the person's baseline, so it is created even at
+     * `devices.maxPersonal`.
+     */
+    ensureDefault(orgId: string, accountId: string): Promise<string>;
+    private insertDefault;
+    /**
+     * Turns the live default into an ordinary device marked as demoted from `provider`; a name
+     * the person gave it stays. Runs under the person's membership lock and the default row's lock,
+     * before any other row becomes the default (the partial unique index).
+     */
+    private demote;
+    /**
+     * The person's live former defaults of `provider` ({@link demotedProvider}: files or an instance
+     * kept by `provider`, or none and demoted from it), the ones holding healthy files first (lost
+     * files count as none), then the most recently used, then the most recently demoted. `lock`
+     * takes their rows (`FOR NO KEY UPDATE`, in id order, so racing replacements queue on the same
+     * rows).
+     */
+    private formerDefaults;
+    /**
+     * The person's IM default (what `/device` set): the device their next new IM conversation
+     * uses. Null when none was set, or the chosen one is deleted (the row is cleared with it).
+     */
+    imDefault(orgId: string, accountId: string): Promise<string | null>;
+    /**
+     * Sets the person's IM default. Only one of their own live devices in the org, usable now
+     * (`device.not_found` / `device.unavailable` otherwise); the row is written by one
+     * statement that re-checks the device is live. There is no row lock, so a delete racing
+     * past that check can leave a stale row; reads ignore it ({@link imDefault} joins on
+     * `deleted_at IS NULL`).
+     */
+    setImDefault(orgId: string, accountId: string, deviceId: string): Promise<void>;
+    /**
+     * The person's live default device in the org, if any, with what decides its provider;
+     * `lock` takes its row (`FOR NO KEY UPDATE`; a racing demotion makes it read none).
+     */
+    private defaultOf;
+    /** Its files or instance are kept by a provider that is not the current one. */
+    private stranded;
+    /** The person's live devices (or the one `id`) as views. */
+    private views;
+    /**
+     * Serializes the person's device writes in the org: the org row (`FOR SHARE`), then their
+     * membership row (`FOR NO KEY UPDATE`, or `FOR SHARE` with `mode` share: enough to keep the
+     * membership from being removed meanwhile), the order member removal locks them in. Not a
+     * member (any more) → `org.not_found`, as the org guard answers.
+     */
+    private lockMember;
+    /** Locks one of the person's live devices (after their membership); else `not_found`. */
+    private lockOwn;
+    private assertNameFree;
+}