@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

package/dist/environments/environments.service.d.ts

@@ -0,0 +1,251 @@
+import type { LocalizedName, SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { MachinesService } from "../devices/machines.js";
+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 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 { EnvironmentAccess } from "./access.js";
+/** An environment as its owner sees it (`GET /orgs/:orgId/environments`). */
+export interface EnvironmentView {
+    id: string;
+    /**
+     * null for the default environment (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 environment.
+     */
+    demotedFrom: {
+        provider: string;
+        displayName: LocalizedName | null;
+        ordinal: number;
+    } | null;
+    ownerKind: "personal";
+    /** `device`: a connected machine (provider `@device`). */
+    source: "cloud" | "device";
+    /** 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 `@device` registered. */
+    available: boolean;
+    /** A device environment: some replica holds its machine's connection now; null for cloud. */
+    online: boolean | null;
+    /** A device environment's connected machine (its unrevoked one); null for cloud or none. */
+    machine: EnvironmentMachineView | 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 environments use them unchanged, spec §8.4). */
+    limits: SandboxLimits;
+    createdAt: string;
+}
+/** The machine connected to a device environment, as its owner sees it. */
+export interface EnvironmentMachineView {
+    id: string;
+    name: string;
+    os: string;
+    mode: "os" | "docker" | null;
+    programVersion: string | null;
+    lastSeenAt: string | null;
+}
+/** The list response: the person's live environments in the org. */
+export interface EnvironmentList {
+    items: EnvironmentView[];
+    /** The person's default environment; null when there is none (no sandbox provider to make it). */
+    defaultId: string | null;
+    /** The environment of the person's most recently updated conversation that has a live one. */
+    lastUsedId: string | null;
+    /** There is a current sandbox provider (new cloud environments can be made; ruling R4). */
+    cloudAvailable: boolean;
+}
+/**
+ * Personal environments (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 environments in an org, visible and usable only by their owner (anyone else gets
+ * `environment.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 EnvironmentsService {
+    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<EnvironmentAccess, "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 environments in the org, the default first, then by creation. With a
+     * current sandbox provider the default environment 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<EnvironmentList>;
+    /** One of the person's live environments; anyone else's (or a missing one) → `not_found`. */
+    get(orgId: string, accountId: string, id: string): Promise<EnvironmentView>;
+    /**
+     * A new personal cloud environment, ready at once (its instance and files are made on first
+     * use). Needs a current sandbox provider (`environment.unavailable`); a live name of the person's
+     * (case-insensitive) → `environment.name_taken`; `environments.maxPersonal` live ones (the
+     * default counts) → `environment.limit_reached`. Serialized per person by their membership row.
+     */
+    create(orgId: string, accountId: string, input: {
+        name: string;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<EnvironmentView>;
+    private insert;
+    /**
+     * A new personal `device` environment for a machine being connected (provider `@device`; the
+     * machine row is the caller's). Joins the caller's transaction (the device authorization's).
+     * Counted against `environments.maxPersonal` (`environment.limit_reached`); a live name of the
+     * person's → `environment.name_taken`. Needs no cloud provider.
+     */
+    createDevice(orgId: string, accountId: string, name: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * Inserts a named personal environment under the person's membership lock, after the limit
+     * and name checks, and audits `environment.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 environment (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
+     * environment), 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 environments (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<EnvironmentView>;
+    private renameIn;
+    /**
+     * Deletes one of the person's live environments: 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 `environment.not_found`. A device environment'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 device environments (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 environments over with empty files (after
+     * `environment.files_lost`): records the request (audit), then, after the commit, enqueues the
+     * `sandbox-reset-files` job (deterministic id per environment), 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 (`environment.unavailable`); a connected environment's files
+     * are its machine owner's (`environment.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 environment 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 environments.
+     *
+     * 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
+     * (`environment.unavailable`). It is the person's baseline, so it is created even at
+     * `environments.maxPersonal`.
+     */
+    ensureDefault(orgId: string, accountId: string): Promise<string>;
+    private insertDefault;
+    /**
+     * Turns the live default into an ordinary environment 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 `/env` set): the environment 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 environments in the org, usable now
+     * (`environment.not_found` / `environment.unavailable` otherwise); the row is written by one
+     * statement that re-checks the environment 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, environmentId: string): Promise<void>;
+    /**
+     * The person's live default environment 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 environments (or the one `id`) as views. */
+    private views;
+    /**
+     * Serializes the person's environment 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 environments (after their membership); else `not_found`. */
+    private lockOwn;
+    private assertNameFree;
+}