@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

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

@@ -0,0 +1,153 @@
+import type { SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import 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"). */
+    name: string | null;
+    isDefault: boolean;
+    ownerKind: "personal";
+    source: "cloud";
+    /** The provider keeping its files, or the one its first use will create them with. */
+    provider: string | null;
+    /** Its provider is the deployment's current sandbox provider. */
+    available: boolean;
+    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 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 cloud environments (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §9): 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 log;
+    constructor(db: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, providers: Pick<SandboxProviders, "current">, sandbox: Pick<SandboxService, "orgLimits">, sandboxJobs: Pick<SandboxJobs, "destroy" | "resetFiles">, access: Pick<EnvironmentAccess, "usable">, log: Pick<KernelLogger, "warn">);
+    /**
+     * 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): Promise<EnvironmentView>;
+    private insert;
+    /** Renames one of the person's live environments (the default too); see {@link create}. */
+    rename(orgId: string, accountId: string, id: string, name: string, actorTokenId?: string): 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`.
+     */
+    remove(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`). An enqueue failure is thrown
+     * (the request can be repeated: the reset is idempotent).
+     */
+    resetFiles(orgId: string, accountId: string, id: string, actorTokenId?: string): 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, named `Personal (<provider>)` (` 2`, ` 3`, … when that
+     * name is taken) and stays listed as unavailable and deletable, and a fresh default is created,
+     * in one transaction. Creating 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, and
+     * their creates and renames (`FOR NO KEY UPDATE`) cannot race the demoted name; not a member
+     * (any more) → `org.not_found`. Idempotent under concurrency: the demotion locks the default
+     * row and re-checks it, 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 a stranded default into an ordinary environment named `Personal (<provider>)`, with
+     * ` 2`, ` 3`, … appended while that name is one of the person's live names (case-insensitive).
+     * Runs under the person's membership lock and the default row's lock.
+     */
+    private demote;
+    /**
+     * 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;
+}