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

package/src/migrations/0087_approval_summary.sql

@@ -0,0 +1,6 @@
+-- Platform tool (spec 2026-11-07-platform-tool-design.md §6.2, §6.3): an approval carries the
+-- kernel-rendered summary of the call ({zh, en}) and the scopes the person may choose. Expand-only:
+-- both columns are nullable; null keeps today's behavior (no summary; scopes derived from the row:
+-- "once" for a role escalation, else once / session / always).
+ALTER TABLE approvals ADD COLUMN IF NOT EXISTS summary jsonb;
+ALTER TABLE approvals ADD COLUMN IF NOT EXISTS scopes text[];

package/src/migrations/0088_environments.sql

@@ -0,0 +1,80 @@
+-- Environments phase 1 (spec 2026-11-07-environments-design §4.2, §10): a long-lived environment
+-- is one sandbox instance plus a file system kept until the environment is deleted. This replaces
+-- the per-conversation `sandboxes` table with `environment_instances`; the old table stays only
+-- for the cleanup job that destroys its remaining instances. The CHECK lists of owner_kind and
+-- source grow in phases 2 and 3 through new migrations.
+CREATE TABLE IF NOT EXISTS capybara.environments (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES capybara.orgs(id) ON DELETE CASCADE,
+  owner_kind text NOT NULL CHECK (owner_kind IN ('personal')),
+  owner_account_id text NOT NULL REFERENCES capybara.accounts(id),
+  name text,
+  is_default boolean NOT NULL DEFAULT false,
+  source text NOT NULL CHECK (source IN ('cloud')),
+  provider text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz
+);
+CREATE UNIQUE INDEX IF NOT EXISTS environments_default_uq
+  ON capybara.environments (org_id, owner_account_id)
+  WHERE is_default AND deleted_at IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS environments_name_uq
+  ON capybara.environments (org_id, owner_account_id, lower(name))
+  WHERE name IS NOT NULL AND deleted_at IS NULL;
+
+-- Same columns and meaning as the old sandboxes table (0023), keyed by environment. fs_handle and
+-- fs_status describe the kept file system; status 'none' means no instance exists yet.
+CREATE TABLE IF NOT EXISTS capybara.environment_instances (
+  environment_id text PRIMARY KEY REFERENCES capybara.environments(id) ON DELETE CASCADE,
+  org_id text NOT NULL,
+  provider text,
+  fs_handle jsonb,
+  fs_status text NOT NULL DEFAULT 'none' CHECK (fs_status IN ('none', 'ready', 'lost')),
+  handle jsonb,
+  status text NOT NULL DEFAULT 'none'
+    CHECK (status IN ('none', 'creating', 'running', 'suspended', 'destroyed')),
+  last_used_at timestamptz NOT NULL DEFAULT now(),
+  running_since timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  suspended_at timestamptz,
+  destroyed_at timestamptz,
+  generation integer NOT NULL DEFAULT 0,
+  had_instance boolean NOT NULL DEFAULT false,
+  prev_provider text,
+  prev_handle jsonb,
+  sweep_failed_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS environment_instances_running_idx
+  ON capybara.environment_instances (last_used_at)
+  WHERE status = 'running';
+CREATE INDEX IF NOT EXISTS environment_instances_live_idx
+  ON capybara.environment_instances (last_used_at)
+  WHERE status <> 'destroyed';
+CREATE INDEX IF NOT EXISTS environment_instances_org_idx
+  ON capybara.environment_instances (org_id);
+
+-- The environment a member's new conversations use when they pick none.
+CREATE TABLE IF NOT EXISTS capybara.environment_defaults (
+  org_id text NOT NULL,
+  account_id text NOT NULL,
+  environment_id text NOT NULL REFERENCES capybara.environments(id) ON DELETE CASCADE,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (org_id, account_id)
+);
+
+-- No cascade: a deleted environment is soft-deleted and the conversation keeps pointing at it.
+ALTER TABLE capybara.conversations
+  ADD COLUMN IF NOT EXISTS environment_id text REFERENCES capybara.environments(id);
+
+ALTER TABLE capybara.background_tasks ADD COLUMN IF NOT EXISTS environment_id text;
+CREATE INDEX IF NOT EXISTS background_tasks_environment_running_idx
+  ON capybara.background_tasks (environment_id) WHERE status = 'running';
+
+-- Tasks that ran in a per-conversation sandbox lose it with the move to environments (the
+-- instances are destroyed by the cleanup job).
+UPDATE capybara.background_tasks
+  SET status = 'lost',
+      lost_reason = COALESCE(lost_reason, 'sandbox_replaced_by_environment'),
+      finished_at = COALESCE(finished_at, now())
+  WHERE status = 'running';

package/dist/catalog/upgrade-targets.d.ts

@@ -1,56 +0,0 @@
-import type { KernelSchemaDb } from "../db/kernel-schema.js";
-import type { ExtensionRegistry } from "../extensions/registry.js";
-/**
- * Which versions an org may upgrade an installed plugin to (package ecosystem spec §10, Decision
- * 10, Ruling 8):
- * - a plugin with an extension follows the deployment: the only target is the catalog version
- *   whose extension package (sha256) is the one installed on the deployment, the newest import on
- *   ties (`1.0.0` and `1.0.0+sha256.x` can share an extension version with different bytes); an
- *   extension loaded from the startup config (config, no package) is matched by its
- *   version;
- * - a purely declarative plugin may move to any other imported version (an older one is a
- *   rollback).
- */
-/** The extension the deployment runs for a plugin name. */
-export interface DeployedExtension {
-    /** The installed package's sha256 (null for a config extension). */
-    sha256: string | null;
-    version: string;
-}
-/** A catalog version row as the target rules read it. */
-export interface TargetVersion {
-    version: string;
-    manifest: unknown;
-    extension_sha256: string | null;
-    imported_at: Date;
-}
-/**
- * The deployment's extension for plugin `name`: its install record (`extension_installs`, the
- * deployment's desired package; disabled on the deployment counts as none), else the extension
- * this replica loaded from the startup config; undefined when the deployment runs none (then no
- * upgrade target and no "upgrade pending").
- */
-export declare function deployedExtension(db: KernelSchemaDb, host: Pick<ExtensionRegistry, "manifests">, name: string): Promise<DeployedExtension | undefined>;
-/** Whether catalog version `v` carries the deployment's extension `d`. */
-export declare const runsDeployed: (v: TargetVersion, d: DeployedExtension) => boolean;
-/**
- * The catalog version an org install of an extension-bearing plugin may move to: the one carrying
- * the deployment's extension, the newest import on ties; undefined when none does.
- */
-export declare function deploymentTarget(versions: readonly TargetVersion[], d: DeployedExtension | undefined): TargetVersion | undefined;
-/** What an install view says about upgrades (Decision 10). */
-export interface UpgradeInfo {
-    /** The version an upgrade can move to now (the highest allowed target), null when none. */
-    upgradeAvailable: string | null;
-    /** An extension-bearing plugin whose org version is not the one the deployment runs. */
-    deploymentPending: boolean;
-}
-/**
- * The upgrade info of org installs (`itemId`, `name`, `version`), keyed by `itemId@version`; reads
- * the items' catalog versions and the deployment's extensions in a few queries.
- */
-export declare function upgradeInfo(db: KernelSchemaDb, host: Pick<ExtensionRegistry, "manifests">, installs: readonly {
-    itemId: string;
-    name: string;
-    version: string;
-}[]): Promise<Map<string, UpgradeInfo>>;

package/dist/catalog/upgrade-targets.js

@@ -1,90 +0,0 @@
-import { compareVersions } from "./versions.js";
-/**
- * The deployment's extension for plugin `name`: its install record (`extension_installs`, the
- * deployment's desired package; disabled on the deployment counts as none), else the extension
- * this replica loaded from the startup config; undefined when the deployment runs none (then no
- * upgrade target and no "upgrade pending").
- */
-export async function deployedExtension(db, host, name) {
-    const row = await db
-        .selectFrom("extension_installs")
-        .select(["sha256", "version", "desired_state"])
-        .where("name", "=", name)
-        .executeTakeFirst();
-    if (row) {
-        return row.desired_state === "enabled"
-            ? { sha256: row.sha256, version: row.version }
-            : undefined;
-    }
-    const loaded = host.manifests().find((m) => m.name === name);
-    return loaded ? { sha256: null, version: loaded.version } : undefined;
-}
-const extensionVersionOf = (v) => v.manifest.extension?.manifest.version;
-/** Whether catalog version `v` carries the deployment's extension `d`. */
-export const runsDeployed = (v, d) => d.sha256 !== null
-    ? v.extension_sha256 === d.sha256
-    : v.manifest.extension !== undefined && extensionVersionOf(v) === d.version;
-/**
- * The catalog version an org install of an extension-bearing plugin may move to: the one carrying
- * the deployment's extension, the newest import on ties; undefined when none does.
- */
-export function deploymentTarget(versions, d) {
-    if (d === undefined)
-        return undefined;
-    let best;
-    for (const v of versions) {
-        if (!runsDeployed(v, d))
-            continue;
-        if (best === undefined ||
-            v.imported_at.getTime() > best.imported_at.getTime() ||
-            (v.imported_at.getTime() === best.imported_at.getTime() && compareVersions(v, best) > 0)) {
-            best = v;
-        }
-    }
-    return best;
-}
-/**
- * The upgrade info of org installs (`itemId`, `name`, `version`), keyed by `itemId@version`; reads
- * the items' catalog versions and the deployment's extensions in a few queries.
- */
-export async function upgradeInfo(db, host, installs) {
-    const out = new Map();
-    if (installs.length === 0)
-        return out;
-    const rows = await db
-        .selectFrom("catalog_item_versions")
-        .select(["item_id", "version", "manifest", "extension_sha256", "imported_at"])
-        .where("item_id", "in", [...new Set(installs.map((i) => i.itemId))])
-        .execute();
-    const deployed = new Map();
-    for (const i of installs) {
-        const versions = rows.filter((r) => r.item_id === i.itemId);
-        const current = versions.find((v) => v.version === i.version);
-        if (current && current.manifest.extension !== undefined) {
-            if (!deployed.has(i.name))
-                deployed.set(i.name, await deployedExtension(db, host, i.name));
-            const d = deployed.get(i.name);
-            const target = deploymentTarget(versions, d);
-            out.set(`${i.itemId}@${i.version}`, {
-                upgradeAvailable: target && target.version !== i.version ? target.version : null,
-                deploymentPending: d !== undefined && !runsDeployed(current, d),
-            });
-            continue;
-        }
-        let newest;
-        for (const v of versions) {
-            if (newest === undefined || compareVersions(v, newest) > 0)
-                newest = v;
-        }
-        const newer = newest !== undefined &&
-            newest.version !== i.version &&
-            (current === undefined
-                ? compareVersions(newest.version, i.version) > 0
-                : compareVersions(newest, current) > 0);
-        out.set(`${i.itemId}@${i.version}`, {
-            upgradeAvailable: newer ? newest.version : null,
-            deploymentPending: false,
-        });
-    }
-    return out;
-}

package/dist/conversations/sandbox-status.d.ts

@@ -1,24 +0,0 @@
-import { SandboxService } from "../sandbox/sandbox.service.js";
-import { ConversationAccess } from "./access.js";
-import { ConversationsService } from "./conversations.service.js";
-export interface SandboxStatusView {
-    status: "running" | "suspended";
-    lastUsedAt: string;
-}
-/**
- * 对话沙箱的状态（网页上下文标签，M5 T11）：会话不可见 → `conversation.not_found`；
- * 没有可用的沙箱（未创建、已销毁、正在创建）→ `sandbox.not_found`（界面显示「未创建」）。
- */
-export declare class ConversationSandboxStatus {
-    /** 会话可见性（与会话 SSE 流同一判定）。 */
-    private readonly access;
-    /** The conversation whose sandbox it works in: a sub-agent's parent, else itself. */
-    private readonly conversations;
-    private readonly sandbox;
-    constructor(
-    /** 会话可见性（与会话 SSE 流同一判定）。 */
-    access: Pick<ConversationAccess, "isAccessible">, 
-    /** The conversation whose sandbox it works in: a sub-agent's parent, else itself. */
-    conversations: Pick<ConversationsService, "sandboxConversationOf">, sandbox: Pick<SandboxService, "status">);
-    get(orgId: string, conversationId: string, viewerAccountId: string): Promise<SandboxStatusView>;
-}

package/dist/conversations/sandbox-status.js

@@ -1,52 +0,0 @@
-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 { ApiError } from "../errors.js";
-import { SandboxService } from "../sandbox/sandbox.service.js";
-import { UUID_RE } from "../ui/registry.js";
-import { ConversationAccess } from "./access.js";
-import { ConversationsService } from "./conversations.service.js";
-/**
- * 对话沙箱的状态（网页上下文标签，M5 T11）：会话不可见 → `conversation.not_found`；
- * 没有可用的沙箱（未创建、已销毁、正在创建）→ `sandbox.not_found`（界面显示「未创建」）。
- */
-let ConversationSandboxStatus = class ConversationSandboxStatus {
-    access;
-    conversations;
-    sandbox;
-    constructor(
-    /** 会话可见性（与会话 SSE 流同一判定）。 */
-    access, 
-    /** The conversation whose sandbox it works in: a sub-agent's parent, else itself. */
-    conversations, sandbox) {
-        this.access = access;
-        this.conversations = conversations;
-        this.sandbox = sandbox;
-    }
-    async get(orgId, conversationId, viewerAccountId) {
-        if (!UUID_RE.test(conversationId) ||
-            !(await this.access.isAccessible(orgId, conversationId, viewerAccountId))) {
-            throw new ApiError("conversation.not_found", "Conversation not found");
-        }
-        // a sub-agent works in its parent conversation's sandbox (sub-agents spec §10.1)
-        const sandboxConv = await this.conversations.sandboxConversationOf(orgId, conversationId);
-        const s = await this.sandbox.status(orgId, sandboxConv);
-        if (!s)
-            throw new ApiError("sandbox.not_found", "This conversation has no sandbox");
-        return { status: s.status, lastUsedAt: s.lastUsedAt.toISOString() };
-    }
-};
-ConversationSandboxStatus = __decorate([
-    Injectable(),
-    __param(0, Inject(ConversationAccess)),
-    __param(1, Inject(ConversationsService)),
-    __param(2, Inject(SandboxService))
-], ConversationSandboxStatus);
-export { ConversationSandboxStatus };

package/dist/extensions/org-config.controller.d.ts

@@ -1,32 +0,0 @@
-import type { LocalizedName } from "@capybara-hq/plugin-sdk";
-import { z } from "zod";
-import { type Principal } from "../identity/principal.js";
-import { type OrgContext } from "../orgs/org.guard.js";
-import { ExtensionDisplayNames } from "./display-name.js";
-import { OrgExtensionConfigs, type OrgExtensionView } from "./org-config.js";
-declare const PutBody: z.ZodObject<{
-    enabled: z.ZodOptional<z.ZodBoolean>;
-    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    force: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
-/** One extension of the org list: the org view plus the plugin's display name. */
-export type OrgExtensionItem = OrgExtensionView & {
-    displayName: LocalizedName | null;
-};
-/**
- * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
- * non-secret config and whether each secret is set.
- */
-export declare class OrgExtensionConfigsController {
-    private readonly configs;
-    private readonly displayNames;
-    constructor(configs: OrgExtensionConfigs, displayNames: ExtensionDisplayNames);
-    /** The org's extensions (also the channel plugin options: those providing `channel@1`). */
-    list(org: OrgContext): Promise<{
-        extensions: OrgExtensionItem[];
-    }>;
-    put(principal: Principal, org: OrgContext, extension: string, body: z.infer<typeof PutBody>): Promise<{
-        extension: OrgExtensionItem;
-    }>;
-}
-export {};

package/dist/extensions/org-config.controller.js

@@ -1,70 +0,0 @@
-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, Inject, Param, Put } from "@nestjs/common";
-import { z } from "zod";
-import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
-import { createZodDto } from "../infra/validation/create-zod-dto.js";
-import { ZBody } from "../infra/validation/zod-params.js";
-import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
-import { ExtensionDisplayNames } from "./display-name.js";
-import { OrgExtensionConfigs } from "./org-config.js";
-const PutBody = z
-    .object({
-    enabled: z.boolean().optional(),
-    config: z.record(z.string(), z.unknown()).optional(),
-    force: z.boolean().optional(),
-})
-    .strict();
-class OrgExtensionPutBody extends createZodDto(PutBody, "OrgExtensionPutBody") {
-}
-/**
- * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
- * non-secret config and whether each secret is set.
- */
-let OrgExtensionConfigsController = class OrgExtensionConfigsController {
-    configs;
-    displayNames;
-    constructor(configs, displayNames) {
-        this.configs = configs;
-        this.displayNames = displayNames;
-    }
-    /** The org's extensions (also the channel plugin options: those providing `channel@1`). */
-    async list(org) {
-        const views = await this.configs.list(org.orgId);
-        const names = await this.displayNames.many(views.map((v) => v.plugin));
-        return {
-            extensions: views.map((v) => ({ ...v, displayName: names.get(v.plugin) ?? null })),
-        };
-    }
-    async put(principal, org, extension, body) {
-        const p = requireUser(principal);
-        const view = await this.configs.put(org.orgId, extension, body, p.account.id, patTokenId(p));
-        return { extension: { ...view, displayName: await this.displayNames.get(view.plugin) } };
-    }
-};
-__decorate([
-    Get(),
-    OrgAction("org.extensions.manage"),
-    __param(0, CurrentOrg())
-], OrgExtensionConfigsController.prototype, "list", null);
-__decorate([
-    Put(":extension"),
-    OrgAction("org.extensions.manage"),
-    __param(0, CurrentPrincipal()),
-    __param(1, CurrentOrg()),
-    __param(2, Param("extension")),
-    __param(3, ZBody(OrgExtensionPutBody))
-], OrgExtensionConfigsController.prototype, "put", null);
-OrgExtensionConfigsController = __decorate([
-    Controller("api/v1/orgs/:orgId/extensions"),
-    __param(0, Inject(OrgExtensionConfigs)),
-    __param(1, Inject(ExtensionDisplayNames))
-], OrgExtensionConfigsController);
-export { OrgExtensionConfigsController };