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

package/dist/environments/environments.service.js

@@ -0,0 +1,541 @@
+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 { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { afterCommit } from "../infra/database/after-commit.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 { KERNEL_LOGGER } from "../infra/tokens.js";
+import { SandboxJobs } from "../sandbox/jobs.js";
+import { SandboxProviders } from "../sandbox/providers.js";
+import { environmentNotFound, SandboxService } from "../sandbox/sandbox.service.js";
+import { EnvironmentAccess, environmentProvider, environmentUnavailable, } from "./access.js";
+const isUniqueViolation = (e, constraint) => typeof e === "object" &&
+    e !== null &&
+    e.code === "23505" &&
+    e.constraint === constraint;
+const nameTaken = () => new ApiError("environment.name_taken", "You already have an environment with this name");
+/**
+ * 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.
+ */
+let EnvironmentsService = class EnvironmentsService {
+    db;
+    txHost;
+    config;
+    providers;
+    sandbox;
+    sandboxJobs;
+    access;
+    log;
+    constructor(db, txHost, config, providers, sandbox, sandboxJobs, access, log) {
+        this.db = db;
+        this.txHost = txHost;
+        this.config = config;
+        this.providers = providers;
+        this.sandbox = sandbox;
+        this.sandboxJobs = sandboxJobs;
+        this.access = access;
+        this.log = log;
+    }
+    /**
+     * 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).
+     */
+    async list(orgId, accountId) {
+        const cloudAvailable = this.providers.current() !== undefined;
+        const defaultId = cloudAvailable ? await this.ensureDefault(orgId, accountId) : null;
+        const items = await this.views(orgId, accountId);
+        const last = await this.db
+            .selectFrom("conversations as c")
+            .innerJoin("environments as e", "e.id", "c.environment_id")
+            .select("c.environment_id")
+            .where("c.org_id", "=", orgId)
+            .where("c.account_id", "=", accountId)
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.deleted_at", "is", null)
+            .orderBy("c.updated_at", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        return {
+            items,
+            defaultId: defaultId ?? items.find((v) => v.isDefault)?.id ?? null,
+            lastUsedId: last?.environment_id ?? null,
+            cloudAvailable,
+        };
+    }
+    /** One of the person's live environments; anyone else's (or a missing one) → `not_found`. */
+    async get(orgId, accountId, id) {
+        const [view] = await this.views(orgId, accountId, id);
+        if (!view)
+            throw environmentNotFound();
+        return view;
+    }
+    /**
+     * 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.
+     */
+    async create(orgId, accountId, input, actorTokenId) {
+        const id = await this.insert(orgId, accountId, input.name, actorTokenId);
+        return this.get(orgId, accountId, id);
+    }
+    async insert(orgId, accountId, name, actorTokenId) {
+        const current = this.providers.current();
+        if (!current)
+            throw environmentUnavailable(null);
+        await this.lockMember(orgId, accountId);
+        const { n } = await this.db
+            .selectFrom("environments")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirstOrThrow();
+        const max = this.config.get().environments.maxPersonal;
+        if (Number(n) >= max) {
+            throw new ApiError("environment.limit_reached", `You already have ${max} environments in this organization; delete one to create another`);
+        }
+        await this.assertNameFree(orgId, accountId, name);
+        const id = randomUUID();
+        try {
+            await this.db
+                .insertInto("environments")
+                .values({
+                id,
+                org_id: orgId,
+                owner_kind: "personal",
+                owner_account_id: accountId,
+                name,
+                source: "cloud",
+                provider: current.plugin,
+            })
+                .execute();
+        }
+        catch (e) {
+            if (isUniqueViolation(e, "environments_name_uq"))
+                throw nameTaken();
+            throw e;
+        }
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.created",
+            target: id,
+            detail: { name },
+        });
+        return id;
+    }
+    /** Renames one of the person's live environments (the default too); see {@link create}. */
+    async rename(orgId, accountId, id, name, actorTokenId) {
+        await this.renameIn(orgId, accountId, id, name, actorTokenId);
+        return this.get(orgId, accountId, id);
+    }
+    async renameIn(orgId, accountId, id, name, actorTokenId) {
+        const before = await this.lockOwn(orgId, accountId, id);
+        if (before.name === name)
+            return;
+        // the same name in another case is this environment's own: the index allows it
+        if (before.name?.toLowerCase() !== name.toLowerCase()) {
+            await this.assertNameFree(orgId, accountId, name);
+        }
+        try {
+            await this.db
+                .updateTable("environments")
+                .set({ name, updated_at: sql `now()` })
+                .where("id", "=", id)
+                .execute();
+        }
+        catch (e) {
+            if (isUniqueViolation(e, "environments_name_uq"))
+                throw nameTaken();
+            throw e;
+        }
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.renamed",
+            target: id,
+            detail: { from: before.name, to: name },
+        });
+    }
+    /**
+     * 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`.
+     */
+    async remove(orgId, accountId, id, actorTokenId) {
+        const before = await this.lockOwn(orgId, accountId, id);
+        await this.db
+            .updateTable("environments")
+            .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
+            .where("id", "=", id)
+            .execute();
+        await this.db
+            .deleteFrom("environment_defaults")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .where("environment_id", "=", id)
+            .execute();
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.deleted",
+            target: id,
+            detail: { name: before.name, isDefault: before.is_default },
+        });
+        afterCommit(async () => {
+            try {
+                await this.sandboxJobs.destroy([id]);
+            }
+            catch (err) {
+                // the hourly destruction sweep destroys deleted environments too
+                this.log.warn("cannot schedule environment destruction", { environmentId: id, err });
+            }
+        });
+    }
+    /**
+     * 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).
+     */
+    async resetFiles(orgId, accountId, id, actorTokenId) {
+        await this.recordReset(orgId, accountId, id, actorTokenId);
+        await this.sandboxJobs.resetFiles(id);
+    }
+    /** The check and audit row of {@link resetFiles}, committed before the job is enqueued. */
+    async recordReset(orgId, accountId, id, actorTokenId) {
+        await this.access.usable(orgId, accountId, id);
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.files_reset",
+            target: id,
+        });
+    }
+    /**
+     * 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`.
+     */
+    async ensureDefault(orgId, accountId) {
+        const live = await this.defaultOf(orgId, accountId);
+        if (live && !this.stranded(live))
+            return live.id;
+        return this.insertDefault(orgId, accountId);
+    }
+    async insertDefault(orgId, accountId) {
+        const current = this.providers.current();
+        if (!current)
+            throw environmentUnavailable(null);
+        await this.lockMember(orgId, accountId, "share");
+        const live = await this.defaultOf(orgId, accountId, true);
+        if (live && !this.stranded(live))
+            return live.id;
+        if (live) {
+            const held = environmentProvider(live, current.plugin) ?? "unknown";
+            await this.demote(orgId, accountId, live.id, held);
+        }
+        await this.db
+            .insertInto("environments")
+            .values({
+            id: randomUUID(),
+            org_id: orgId,
+            owner_kind: "personal",
+            owner_account_id: accountId,
+            name: null,
+            is_default: true,
+            source: "cloud",
+            provider: current.plugin,
+        })
+            .onConflict((oc) => oc
+            .columns(["org_id", "owner_account_id"])
+            .where(sql `is_default AND deleted_at IS NULL`)
+            .doNothing())
+            .execute();
+        const row = await this.defaultOf(orgId, accountId);
+        if (row === undefined)
+            throw new Error("the default environment was not created");
+        return row.id;
+    }
+    /**
+     * 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.
+     */
+    async demote(orgId, accountId, id, provider) {
+        const base = `Personal (${provider})`;
+        const taken = new Set((await this.db
+            .selectFrom("environments")
+            .select("name")
+            .where("org_id", "=", orgId)
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .where("name", "is not", null)
+            .execute()).map((r) => r.name.toLowerCase()));
+        let name = base;
+        for (let n = 2; taken.has(name.toLowerCase()); n++)
+            name = `${base} ${n}`;
+        await this.db
+            .updateTable("environments")
+            .set({ is_default: false, name, updated_at: sql `now()` })
+            .where("id", "=", id)
+            .execute();
+    }
+    /**
+     * 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).
+     */
+    async imDefault(orgId, accountId) {
+        const row = await this.db
+            .selectFrom("environment_defaults as d")
+            .innerJoin("environments as e", "e.id", "d.environment_id")
+            .select("e.id")
+            .where("d.org_id", "=", orgId)
+            .where("d.account_id", "=", accountId)
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.deleted_at", "is", null)
+            .executeTakeFirst();
+        return row?.id ?? 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`).
+     */
+    async setImDefault(orgId, accountId, environmentId) {
+        await this.access.usable(orgId, accountId, environmentId);
+        const written = await this.db
+            .insertInto("environment_defaults")
+            .columns(["org_id", "account_id", "environment_id"])
+            .expression(this.db
+            .selectFrom("environments")
+            .select([
+            sql `${orgId}::text`.as("org_id"),
+            sql `${accountId}::text`.as("account_id"),
+            "id",
+        ])
+            .where("id", "=", environmentId)
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null))
+            .onConflict((oc) => oc
+            .columns(["org_id", "account_id"])
+            .doUpdateSet({ environment_id: environmentId, updated_at: new Date() }))
+            .executeTakeFirst();
+        if (Number(written.numInsertedOrUpdatedRows ?? 0) === 0)
+            throw environmentNotFound();
+    }
+    /**
+     * 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).
+     */
+    async defaultOf(orgId, accountId, lock = false) {
+        const row = await this.db
+            .selectFrom("environments as e")
+            .leftJoin("environment_instances as i", "i.environment_id", "e.id")
+            .select(["e.id", "e.provider", "i.provider as instance_provider", "i.fs_status", "i.handle"])
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.is_default", "=", true)
+            .where("e.deleted_at", "is", null)
+            .$if(lock, (q) => q.forNoKeyUpdate("e"))
+            .executeTakeFirst();
+        return (row && {
+            id: row.id,
+            provider: row.provider,
+            instanceProvider: row.instance_provider,
+            fsStatus: row.fs_status,
+            hasInstance: row.handle !== null,
+        });
+    }
+    /** Its files or instance are kept by a provider that is not the current one. */
+    stranded(f) {
+        const current = this.providers.current()?.plugin;
+        return current !== undefined && environmentProvider(f, current) !== current;
+    }
+    /** The person's live environments (or the one `id`) as views. */
+    async views(orgId, accountId, id) {
+        const rows = await this.db
+            .selectFrom("environments as e")
+            .leftJoin("environment_instances as i", "i.environment_id", "e.id")
+            .select([
+            "e.id",
+            "e.name",
+            "e.is_default",
+            "e.provider",
+            "e.created_at",
+            "i.provider as instance_provider",
+            "i.fs_status",
+            "i.handle",
+            "i.status",
+            "i.last_used_at",
+        ])
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.deleted_at", "is", null)
+            .$if(id !== undefined, (q) => q.where("e.id", "=", id))
+            .orderBy("e.is_default", "desc")
+            .orderBy("e.created_at")
+            .orderBy("e.id")
+            .execute();
+        if (rows.length === 0)
+            return [];
+        const limits = await this.sandbox.orgLimits(orgId);
+        const current = this.providers.current()?.plugin;
+        return rows.map((r) => {
+            const provider = environmentProvider({
+                provider: r.provider,
+                instanceProvider: r.instance_provider,
+                fsStatus: r.fs_status,
+                hasInstance: r.handle !== null,
+            }, current);
+            const live = (r.status === "running" || r.status === "suspended") && r.last_used_at;
+            return {
+                id: r.id,
+                name: r.name,
+                isDefault: r.is_default,
+                ownerKind: "personal",
+                source: "cloud",
+                provider,
+                available: current !== undefined && provider === current,
+                sessionIsolation: false,
+                filesLost: r.fs_status === "lost",
+                instance: live
+                    ? {
+                        status: r.status,
+                        lastUsedAt: r.last_used_at.toISOString(),
+                    }
+                    : null,
+                limits: { ...limits, allowHosts: [...limits.allowHosts] },
+                createdAt: r.created_at.toISOString(),
+            };
+        });
+    }
+    /**
+     * 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.
+     */
+    async lockMember(orgId, accountId, mode = "update") {
+        const org = await this.db
+            .selectFrom("orgs")
+            .select("id")
+            .where("id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .forShare()
+            .executeTakeFirst();
+        const m = org &&
+            (await this.db
+                .selectFrom("memberships")
+                .select("account_id")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
+                .$if(mode === "update", (q) => q.forNoKeyUpdate())
+                .$if(mode === "share", (q) => q.forShare())
+                .executeTakeFirst());
+        if (!m)
+            throw new ApiError("org.not_found", "Organization not found");
+    }
+    /** Locks one of the person's live environments (after their membership); else `not_found`. */
+    async lockOwn(orgId, accountId, id) {
+        await this.lockMember(orgId, accountId);
+        const row = await this.db
+            .selectFrom("environments")
+            .select(["name", "is_default"])
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .forNoKeyUpdate()
+            .executeTakeFirst();
+        if (!row)
+            throw environmentNotFound();
+        return row;
+    }
+    async assertNameFree(orgId, accountId, name) {
+        const clash = await this.db
+            .selectFrom("environments")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .where(sql `lower(name) = lower(${name})`)
+            .executeTakeFirst();
+        if (clash)
+            throw nameTaken();
+    }
+};
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "insert", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "renameIn", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "remove", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "recordReset", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "insertDefault", null);
+EnvironmentsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(SandboxProviders)),
+    __param(4, Inject(SandboxService)),
+    __param(5, Inject(SandboxJobs)),
+    __param(6, Inject(EnvironmentAccess)),
+    __param(7, Inject(KERNEL_LOGGER))
+], EnvironmentsService);
+export { EnvironmentsService };

package/dist/environments/legacy-cleanup.job.d.ts

@@ -0,0 +1,34 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { SandboxProviders } from "../sandbox/providers.js";
+/** The job's name (`@LockedInterval`, run lock `cron:environments-legacy-cleanup`). */
+export declare const LEGACY_CLEANUP_JOB = "environments-legacy-cleanup";
+/** What one run did: rows destroyed and deleted, rows kept because their provider is not loaded. */
+export interface LegacyCleanupResult {
+    destroyed: number;
+    kept: number;
+}
+/**
+ * The cleanup of the per-conversation sandboxes of before environments (spec
+ * 2026-11-07-environments-design §4.2 item 9): for up to {@link BATCH} rows of the legacy
+ * `sandboxes` table per tick, the row's provider destroys the instance and the file system named
+ * `cap-<conversationId>` (`destroyByName`, `destroyFileSystemByName`; also the instance of the
+ * provider it replaced, `prev_provider`, when that one is loaded), then the row is deleted. No
+ * lease is taken: nothing holds a legacy row after the upgrade. A row whose provider is not loaded
+ * is kept (warned once per hour: on the tick in the first {@link PERIOD_MS} of each hour); a row
+ * whose destruction failed is retried at a later tick, after the others (`sweep_failed_at`). With
+ * no rows left a tick is one `SELECT … LIMIT 1`. The table is dropped by a later migration.
+ */
+export declare class LegacySandboxCleanupJob {
+    private readonly db;
+    private readonly providers;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(db: KernelDb, providers: Pick<SandboxProviders, "lookup">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    tick(signal?: AbortSignal): Promise<void>;
+    /** One run (see the class); `signal` (the stop, or a lost run lock) is read between rows. */
+    runOnce(now?: Date, signal?: AbortSignal): Promise<LegacyCleanupResult>;
+}