@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/orgs/orgs.controller.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { type ApiTokenRecord, type ApiTokenService } from "../identity/api-tokens.js";
+import { type Principal } from "../identity/principal.js";
+import type { Member, MembersService } from "./members.service.js";
+import { type OrgContext } from "./org.guard.js";
+import type { Org, OrgsService } from "./orgs.service.js";
+import { type OrgRole } from "./roles.js";
+declare const CreateBody: z.ZodObject<{
+    name: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const UpdateBody: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const TransferBody: z.ZodObject<{
+    toAccountId: z.ZodString;
+}, z.core.$strip>;
+declare const ServiceTokenBody: z.ZodObject<{
+    name: z.ZodString;
+    role: z.ZodEnum<{
+        admin: "admin";
+        guest: "guest";
+        member: "member";
+    }>;
+    expiresAt: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
+}, z.core.$strip>;
+declare const RoleBody: z.ZodObject<{
+    role: z.ZodEnum<{
+        admin: "admin";
+        guest: "guest";
+        member: "member";
+        owner: "owner";
+    }>;
+}, z.core.$strip>;
+/** 组织与成员（`/api/v1/orgs`）。组织级路由由 `@OrgAction` + OrgGuard 每请求实时鉴权。 */
+export declare class OrgsController {
+    private readonly orgs;
+    private readonly members;
+    private readonly tokens;
+    constructor(orgs: OrgsService, members: MembersService, tokens: ApiTokenService);
+    create(principal: Principal, body: z.infer<typeof CreateBody>): Promise<{
+        org: Org;
+        role: "owner";
+    }>;
+    list(principal: Principal): Promise<{
+        orgs: (Org & {
+            role: OrgRole;
+        })[];
+    }>;
+    get(org: OrgContext): Promise<{
+        org: Org;
+        role: OrgRole;
+    }>;
+    update(principal: Principal, org: OrgContext, body: z.infer<typeof UpdateBody>): Promise<{
+        org: Org;
+    }>;
+    remove(principal: Principal, org: OrgContext): Promise<void>;
+    transfer(principal: Principal, org: OrgContext, body: z.infer<typeof TransferBody>): Promise<void>;
+    leave(principal: Principal, org: OrgContext): Promise<void>;
+    listMembers(org: OrgContext): Promise<{
+        members: Member[];
+    }>;
+    changeRole(principal: Principal, org: OrgContext, accountId: string, body: z.infer<typeof RoleBody>): Promise<{
+        accountId: string;
+        role: OrgRole;
+    }>;
+    removeMember(principal: Principal, org: OrgContext, accountId: string): Promise<void>;
+    createServiceToken(principal: Principal, org: OrgContext, body: z.infer<typeof ServiceTokenBody>): Promise<{
+        token: string;
+        record: ApiTokenRecord;
+    }>;
+    listServiceTokens(org: OrgContext): Promise<{
+        tokens: ApiTokenRecord[];
+    }>;
+    revokeServiceToken(principal: Principal, org: OrgContext, tokenId: string): Promise<void>;
+}
+export {};

package/dist/orgs/orgs.controller.js

@@ -0,0 +1,192 @@
+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 { Body, Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { API_TOKENS, MEMBERS, ORGS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { FutureIsoDate, } from "../identity/api-tokens.js";
+import { CurrentPrincipal, patTokenId, requireUser, SessionOnly, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "./org.guard.js";
+import { ORG_ROLES } from "./roles.js";
+const CreateBody = z.object({
+    name: z.string().min(1).max(100),
+    slug: z.string().min(1).max(40).optional(),
+});
+const UpdateBody = z.object({
+    name: z.string().min(1).max(100).optional(),
+    slug: z.string().min(1).max(40).optional(),
+});
+const TransferBody = z.object({ toAccountId: z.string().min(1) });
+const ServiceTokenBody = z.object({
+    name: z.string().min(1).max(100),
+    role: z.enum(["admin", "member", "guest"]),
+    expiresAt: FutureIsoDate.optional(),
+});
+const RoleBody = z.object({ role: z.enum(ORG_ROLES) });
+/** 组织与成员（`/api/v1/orgs`）。组织级路由由 `@OrgAction` + OrgGuard 每请求实时鉴权。 */
+let OrgsController = class OrgsController {
+    orgs;
+    members;
+    tokens;
+    constructor(orgs, members, tokens) {
+        this.orgs = orgs;
+        this.members = members;
+        this.tokens = tokens;
+    }
+    async create(principal, body) {
+        const p = requireUser(principal);
+        const org = await this.orgs.create(body, p.account, { actorTokenId: patTokenId(p) });
+        return { org, role: "owner" };
+    }
+    async list(principal) {
+        const p = requireUser(principal);
+        return { orgs: await this.orgs.listForAccount(p.account.id) };
+    }
+    async get(org) {
+        const found = await this.orgs.get(org.orgId);
+        if (!found)
+            throw new ApiError("org.not_found", "Organization not found");
+        return { org: found, role: org.role };
+    }
+    async update(principal, org, body) {
+        const p = requireUser(principal);
+        return { org: await this.orgs.update(org.orgId, body, p.account, patTokenId(p)) };
+    }
+    async remove(principal, org) {
+        const p = requireUser(principal);
+        await this.orgs.softDelete(org.orgId, p.account, patTokenId(p));
+    }
+    async transfer(principal, org, body) {
+        const p = requireUser(principal);
+        await this.members.transferOwnership(org.orgId, p.account.id, body.toAccountId, patTokenId(p));
+    }
+    async leave(principal, org) {
+        const p = requireUser(principal);
+        await this.members.leave(org.orgId, p.account.id, patTokenId(p));
+    }
+    async listMembers(org) {
+        return { members: await this.members.list(org.orgId) };
+    }
+    async changeRole(principal, org, accountId, body) {
+        const p = requireUser(principal);
+        await this.members.changeRole(org.orgId, accountId, body.role, p.account.id, patTokenId(p));
+        return { accountId, role: body.role };
+    }
+    async removeMember(principal, org, accountId) {
+        const p = requireUser(principal);
+        await this.members.remove(org.orgId, accountId, p.account.id, patTokenId(p));
+    }
+    async createServiceToken(principal, org, body) {
+        const p = requireUser(principal);
+        return this.tokens.createServiceAs(org.orgId, p.account.id, body);
+    }
+    async listServiceTokens(org) {
+        return { tokens: await this.tokens.list({ orgId: org.orgId }) };
+    }
+    async revokeServiceToken(principal, org, tokenId) {
+        const p = requireUser(principal);
+        await this.tokens.revokeServiceAs(org.orgId, tokenId, p.account.id);
+    }
+};
+__decorate([
+    Post(),
+    __param(0, CurrentPrincipal()),
+    __param(1, Body(new ZodPipe(CreateBody)))
+], OrgsController.prototype, "create", null);
+__decorate([
+    Get(),
+    __param(0, CurrentPrincipal())
+], OrgsController.prototype, "list", null);
+__decorate([
+    Get(":orgId"),
+    OrgAction("org.read"),
+    __param(0, CurrentOrg())
+], OrgsController.prototype, "get", null);
+__decorate([
+    Patch(":orgId"),
+    OrgAction("org.update"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(UpdateBody)))
+], OrgsController.prototype, "update", null);
+__decorate([
+    Delete(":orgId"),
+    OrgAction("org.delete"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], OrgsController.prototype, "remove", null);
+__decorate([
+    Post(":orgId/transfer"),
+    OrgAction("org.transfer"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(TransferBody)))
+], OrgsController.prototype, "transfer", null);
+__decorate([
+    Post(":orgId/leave"),
+    OrgAction("org.read"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], OrgsController.prototype, "leave", null);
+__decorate([
+    Get(":orgId/members"),
+    OrgAction("org.members.read"),
+    __param(0, CurrentOrg())
+], OrgsController.prototype, "listMembers", null);
+__decorate([
+    Patch(":orgId/members/:accountId"),
+    OrgAction("org.members.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("accountId")),
+    __param(3, Body(new ZodPipe(RoleBody)))
+], OrgsController.prototype, "changeRole", null);
+__decorate([
+    Delete(":orgId/members/:accountId"),
+    OrgAction("org.members.manage"),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("accountId"))
+], OrgsController.prototype, "removeMember", null);
+__decorate([
+    Post(":orgId/service-tokens"),
+    OrgAction("org.tokens.manage"),
+    SessionOnly(),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(ServiceTokenBody)))
+], OrgsController.prototype, "createServiceToken", null);
+__decorate([
+    Get(":orgId/service-tokens"),
+    OrgAction("org.tokens.manage"),
+    SessionOnly(),
+    __param(0, CurrentOrg())
+], OrgsController.prototype, "listServiceTokens", null);
+__decorate([
+    Delete(":orgId/service-tokens/:tokenId"),
+    OrgAction("org.tokens.manage"),
+    SessionOnly(),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("tokenId"))
+], OrgsController.prototype, "revokeServiceToken", null);
+OrgsController = __decorate([
+    Controller("api/v1/orgs"),
+    __param(0, Inject(ORGS)),
+    __param(1, Inject(MEMBERS)),
+    __param(2, Inject(API_TOKENS))
+], OrgsController);
+export { OrgsController };

package/dist/orgs/orgs.service.d.ts

@@ -0,0 +1,61 @@
+import { type Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { Account } from "../identity/accounts.js";
+import type { ApiTokenService } from "../identity/api-tokens.js";
+import type { SettingsService } from "../identity/settings.js";
+import type { OrgRole } from "./roles.js";
+type Trx = Transaction<KernelDatabase>;
+export type Org = {
+    id: string;
+    slug: string;
+    name: string;
+    createdAt: Date;
+};
+/** 组织 slug：小写字母数字与 `-`，首尾不能是 `-`，1–40 个字符。 */
+export declare const SLUG_RE: RegExp;
+/** 由名字生成 slug：转小写、非字母数字换 `-`、去首尾 `-`；为空则 `org-<6 位随机>`。 */
+export declare function slugFromName(name: string): string;
+/** 组织服务：创建、查询、修改与软删除。框架无关，由调用方注入依赖。 */
+export declare class OrgsService {
+    private readonly db;
+    private readonly settings;
+    private readonly apiTokens;
+    private readonly hooks;
+    constructor(db: KernelDb, settings: SettingsService, apiTokens: ApiTokenService, hooks?: {
+        /** 软删除提交之后（内核传：给该组织的渠道连接广播 `channel.changed`，长连接立即断开）。 */
+        afterDelete?: (orgId: string) => Promise<void>;
+    });
+    /**
+     * 建组织，创建者为 owner。传入 `opts.trx` 时在调用方的事务内执行（初始化向导与建账号同一事务）；
+     * 此时 slug 冲突同样转成 `org.slug_taken`，但该事务已中止，调用方只能回滚。
+     */
+    create(input: {
+        name: string;
+        slug?: string | undefined;
+    }, actor: Account, opts?: {
+        trx?: Trx | undefined;
+        actorTokenId?: string | undefined;
+    }): Promise<Org>;
+    /** 账号所属的（未软删除的）组织及其角色，按创建时间升序。 */
+    listForAccount(accountId: string): Promise<(Org & {
+        role: OrgRole;
+    })[]>;
+    /** 全部（未软删除的）组织及成员数（企业管理员用）。 */
+    listAll(): Promise<(Org & {
+        memberCount: number;
+    })[]>;
+    /** 未软删除的组织；不存在或已软删除为 undefined。 */
+    get(orgId: string): Promise<Org | undefined>;
+    /** 改名 / slug（需 admin，锁内实时判定）。 */
+    update(orgId: string, patch: {
+        name?: string | undefined;
+        slug?: string | undefined;
+    }, actor: Account, actorTokenId?: string): Promise<Org>;
+    /**
+     * 软删除（需 owner，锁内实时判定）：同一事务吊销该组织的服务令牌、取消在执行的评测运行与挂着的目录申请、清空指向它的
+     * 会话当前组织；
+     * 提交后调用 `afterDelete`（渠道连接随组织失效：运行时读连接行时 join 组织过滤已删除的）。
+     */
+    softDelete(orgId: string, actor: Account, actorTokenId?: string): Promise<void>;
+}
+export {};

package/dist/orgs/orgs.service.js

@@ -0,0 +1,209 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { cancelPendingRequests } from "../catalog/requests.service.js";
+import { ApiError } from "../errors.js";
+import { cancelEvalRuns } from "../evals/budget.js";
+import { audit } from "../identity/audit.js";
+import { lockOrgAndAuthorize } from "./org-lock.js";
+/** 组织 slug：小写字母数字与 `-`，首尾不能是 `-`，1–40 个字符。 */
+export const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+const MAX_SLUG = 40;
+const MAX_NAME = 100;
+function toOrg(r) {
+    return { id: r.id, slug: r.slug, name: r.name, createdAt: r.created_at };
+}
+/** 由名字生成 slug：转小写、非字母数字换 `-`、去首尾 `-`；为空则 `org-<6 位随机>`。 */
+export function slugFromName(name) {
+    const s = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, MAX_SLUG)
+        .replace(/^-+|-+$/g, "");
+    if (s)
+        return s;
+    const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+    const rand = [...randomBytes(6)].map((b) => alphabet[b % alphabet.length]).join("");
+    return `org-${rand}`;
+}
+function checkSlug(slug) {
+    if (!SLUG_RE.test(slug)) {
+        throw new ApiError("validation_failed", "Slug must be 1-40 lowercase letters, digits or '-', not starting or ending with '-'");
+    }
+}
+function checkName(name) {
+    const n = name.trim();
+    if (n.length < 1 || n.length > MAX_NAME) {
+        throw new ApiError("validation_failed", `Organization name must be 1-${MAX_NAME} characters`);
+    }
+    return n;
+}
+/** 仅当违反「存活组织 slug 唯一」索引时为 true。 */
+function isSlugTaken(e) {
+    const err = e;
+    return err.code === "23505" && err.constraint === "orgs_slug_live_uq";
+}
+async function slugGuard(p) {
+    try {
+        return await p;
+    }
+    catch (e) {
+        if (isSlugTaken(e))
+            throw new ApiError("org.slug_taken", "Slug is already taken");
+        throw e;
+    }
+}
+/** 组织服务：创建、查询、修改与软删除。框架无关，由调用方注入依赖。 */
+export class OrgsService {
+    db;
+    settings;
+    apiTokens;
+    hooks;
+    constructor(db, settings, apiTokens, hooks = {}) {
+        this.db = db;
+        this.settings = settings;
+        this.apiTokens = apiTokens;
+        this.hooks = hooks;
+    }
+    /**
+     * 建组织，创建者为 owner。传入 `opts.trx` 时在调用方的事务内执行（初始化向导与建账号同一事务）；
+     * 此时 slug 冲突同样转成 `org.slug_taken`，但该事务已中止，调用方只能回滚。
+     */
+    async create(input, actor, opts = {}) {
+        const { trx, actorTokenId } = opts;
+        // 在调用方事务内读设置：调用方已占着一个连接时再向池要第二个，并发下可能把池耗尽
+        const { orgCreation } = await this.settings.get(trx);
+        if (orgCreation === "enterprise_admin" && !actor.isEnterpriseAdmin) {
+            throw new ApiError("org.creation_disabled", "Only enterprise admins can create organizations");
+        }
+        const name = checkName(input.name);
+        const slug = input.slug ?? slugFromName(name);
+        checkSlug(slug);
+        const run = async (t) => {
+            const row = await t
+                .insertInto("orgs")
+                .values({ id: randomUUID(), slug, name, created_by: actor.id })
+                .returning(["id", "slug", "name", "created_at"])
+                .executeTakeFirstOrThrow();
+            await t
+                .insertInto("memberships")
+                .values({ org_id: row.id, account_id: actor.id, role: "owner" })
+                .execute();
+            await audit(t, {
+                actorAccountId: actor.id,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId: row.id,
+                action: "org.created",
+                target: row.id,
+                detail: { slug, name },
+            });
+            return toOrg(row);
+        };
+        return slugGuard(trx ? run(trx) : this.db.transaction().execute(run));
+    }
+    /** 账号所属的（未软删除的）组织及其角色，按创建时间升序。 */
+    async listForAccount(accountId) {
+        const rows = await this.db
+            .selectFrom("memberships")
+            .innerJoin("orgs", "orgs.id", "memberships.org_id")
+            .select(["orgs.id", "orgs.slug", "orgs.name", "orgs.created_at", "memberships.role"])
+            .where("memberships.account_id", "=", accountId)
+            .where("orgs.deleted_at", "is", null)
+            .orderBy("orgs.created_at")
+            .orderBy("orgs.id")
+            .execute();
+        return rows.map((r) => ({ ...toOrg(r), role: r.role }));
+    }
+    /** 全部（未软删除的）组织及成员数（企业管理员用）。 */
+    async listAll() {
+        const rows = await this.db
+            .selectFrom("orgs")
+            .leftJoin("memberships", "memberships.org_id", "orgs.id")
+            .select(["orgs.id", "orgs.slug", "orgs.name", "orgs.created_at"])
+            .select((eb) => eb.fn.count("memberships.account_id").as("member_count"))
+            .where("orgs.deleted_at", "is", null)
+            .groupBy(["orgs.id", "orgs.slug", "orgs.name", "orgs.created_at"])
+            .orderBy("orgs.created_at")
+            .orderBy("orgs.id")
+            .execute();
+        return rows.map((r) => ({ ...toOrg(r), memberCount: Number(r.member_count) }));
+    }
+    /** 未软删除的组织；不存在或已软删除为 undefined。 */
+    async get(orgId) {
+        const row = await this.db
+            .selectFrom("orgs")
+            .select(["id", "slug", "name", "created_at"])
+            .where("id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return row && toOrg(row);
+    }
+    /** 改名 / slug（需 admin，锁内实时判定）。 */
+    async update(orgId, patch, actor, actorTokenId) {
+        const values = {};
+        if (patch.name !== undefined)
+            values.name = checkName(patch.name);
+        if (patch.slug !== undefined) {
+            checkSlug(patch.slug);
+            values.slug = patch.slug;
+        }
+        return slugGuard(this.db.transaction().execute(async (trx) => {
+            const { org: before } = await lockOrgAndAuthorize(trx, orgId, actor.id, "org.update");
+            if (Object.keys(values).length === 0) {
+                const row = await trx
+                    .selectFrom("orgs")
+                    .select(["id", "slug", "name", "created_at"])
+                    .where("id", "=", orgId)
+                    .executeTakeFirstOrThrow();
+                return toOrg(row);
+            }
+            const row = await trx
+                .updateTable("orgs")
+                .set(values)
+                .where("id", "=", orgId)
+                .returning(["id", "slug", "name", "created_at"])
+                .executeTakeFirstOrThrow();
+            await audit(trx, {
+                actorAccountId: actor.id,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.updated",
+                target: orgId,
+                detail: { before, after: values },
+            });
+            return toOrg(row);
+        }));
+    }
+    /**
+     * 软删除（需 owner，锁内实时判定）：同一事务吊销该组织的服务令牌、取消在执行的评测运行与挂着的目录申请、清空指向它的
+     * 会话当前组织；
+     * 提交后调用 `afterDelete`（渠道连接随组织失效：运行时读连接行时 join 组织过滤已删除的）。
+     */
+    async softDelete(orgId, actor, actorTokenId) {
+        await this.db.transaction().execute(async (trx) => {
+            await lockOrgAndAuthorize(trx, orgId, actor.id, "org.delete");
+            await trx
+                .updateTable("orgs")
+                .set({ deleted_at: sql `now()` })
+                .where("id", "=", orgId)
+                .execute();
+            await this.apiTokens.revokeAllForOrg(orgId, trx);
+            // 组织删除后评测运行不再花钱：显式取消（审计带原因）
+            await cancelEvalRuns(trx, { orgId }, { accountId: actor.id, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, "org_deleted");
+            // 挂着的目录申请（含已交企业管理员的）一并取消
+            await cancelPendingRequests(trx, { orgId }, actor.id, "org_deleted", actorTokenId !== undefined ? { actorTokenId } : {});
+            await trx
+                .updateTable("sessions")
+                .set({ current_org_id: null })
+                .where("current_org_id", "=", orgId)
+                .execute();
+            await audit(trx, {
+                actorAccountId: actor.id,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "org.deleted",
+                target: orgId,
+            });
+        });
+        await this.hooks.afterDelete?.(orgId);
+    }
+}

package/dist/orgs/roles.d.ts

@@ -0,0 +1,13 @@
+/** 组织内角色，由低到高。 */
+export declare const ORG_ROLES: readonly ["guest", "member", "admin", "owner"];
+export type OrgRole = (typeof ORG_ROLES)[number];
+/** `role` 是否不低于 `min`。 */
+export declare function roleAtLeast(role: OrgRole, min: OrgRole): boolean;
+/** 组织级动作；路由用 `@OrgAction(action)` 声明所需动作。 */
+export type OrgAction = "org.read" | "org.update" | "org.delete" | "org.transfer" | "org.members.read" | "org.members.manage" | "org.invitations.manage" | "org.tokens.manage" | "org.extensions.manage" | "agents.create" | "agents.use" | "agents.manage" | "connectors.manage" | "connectors.use" | "approvals.decide" | "channels.manage" | "skills.read" | "skills.manage" | "ui.use" | "trajectories.read" | "evals.manage" | "org.models.manage" | "catalog.read" | "catalog.request" | "catalog.decide";
+/** 每个动作所需的最低角色。 */
+export declare const ACTION_MIN_ROLE: Record<OrgAction, OrgRole>;
+/** 只允许 user principal 执行的动作：服务令牌即使角色足够也拒绝（除 SERVICE_ALLOWED 外全部）。 */
+export declare const HUMAN_ONLY: ReadonlySet<OrgAction>;
+/** 该角色能否执行该动作。 */
+export declare function can(role: OrgRole, action: OrgAction): boolean;

package/dist/orgs/roles.js

@@ -0,0 +1,58 @@
+/** 组织内角色，由低到高。 */
+export const ORG_ROLES = ["guest", "member", "admin", "owner"];
+/** `role` 是否不低于 `min`。 */
+export function roleAtLeast(role, min) {
+    return ORG_ROLES.indexOf(role) >= ORG_ROLES.indexOf(min);
+}
+/** 每个动作所需的最低角色。 */
+export const ACTION_MIN_ROLE = {
+    "org.read": "guest",
+    "org.members.read": "member",
+    "org.update": "admin",
+    "org.members.manage": "admin",
+    "org.invitations.manage": "admin",
+    "org.tokens.manage": "admin",
+    "org.extensions.manage": "admin",
+    "org.delete": "owner",
+    "org.transfer": "owner",
+    "agents.create": "member",
+    "agents.use": "guest",
+    // 管理他人的 agent（如离职后重新指派负责人）
+    "agents.manage": "admin",
+    // 安装 / 配置连接器与审阅工具
+    "connectors.manage": "admin",
+    // 读取本人可见的连接器、连接自己的凭据（凭据属于具体的人，服务令牌不可用）
+    "connectors.use": "guest",
+    // 能否处理某条审批另由 requested_for / approver_role 判定；审批只能由人处理（服务令牌 / agent 不可）
+    "approvals.decide": "guest",
+    // 渠道连接（bot 凭据、绑定的 agent、未绑定用户策略）
+    "channels.manage": "admin",
+    // 组织技能库：成员可查看（给 agent 选技能），管理员上传新技能 / 新版本与删除
+    "skills.read": "member",
+    "skills.manage": "admin",
+    // 插件界面（列出贡献、取视图、执行动作、组织级刷新流）：只给人用，服务令牌不可
+    "ui.use": "guest",
+    // 轨迹查看器：服务里再判定「组织管理员或该 agent 的负责人」（实时读负责人），其余一律 404
+    "trajectories.read": "member",
+    // 评测集、用例与评测运行（用例快照即对话内容，只给组织管理员）
+    "evals.manage": "admin",
+    // 本组织的模型用途映射（覆盖部署默认，如评委用途 eval）
+    "org.models.manage": "admin",
+    // 企业目录（组织视角）：成员浏览（看不到 disabled）与申请；组织管理员决定成员申请（F-AF）。
+    // 安装另按条目种类要求 skills.manage / connectors.manage / org.extensions.manage（服务里在组织行锁内复核）
+    "catalog.read": "member",
+    "catalog.request": "member",
+    "catalog.decide": "admin",
+};
+/** 服务令牌也可执行的动作：只读的 org.read、org.members.read，以及使用 agent 的 agents.use。 */
+const SERVICE_ALLOWED = new Set([
+    "org.read",
+    "org.members.read",
+    "agents.use",
+]);
+/** 只允许 user principal 执行的动作：服务令牌即使角色足够也拒绝（除 SERVICE_ALLOWED 外全部）。 */
+export const HUMAN_ONLY = new Set(Object.keys(ACTION_MIN_ROLE).filter((a) => !SERVICE_ALLOWED.has(a)));
+/** 该角色能否执行该动作。 */
+export function can(role, action) {
+    return roleAtLeast(role, ACTION_MIN_ROLE[action]);
+}

package/dist/orgs/settings.controller.d.ts

@@ -0,0 +1,20 @@
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "./org.guard.js";
+import { type OrgSandboxLimits, type OrgSettings, type OrgSettingsDeployment, type OrgSettingsPatch, type OrgSettingsService } from "./settings.service.js";
+/**
+ * 组织设置（`/api/v1/orgs/:orgId/settings`）：成员可读，修改需 `org.update`（admin）。
+ * 响应带 `deployment`（部署默认值，如沙箱出站），设置页据此展示「跟随部署」时的实际取值；
+ * 以及只读的 `sandboxLimits`（组织实际生效的沙箱 cpu / 内存与来源，企业管理员在部署设置里覆盖，C19）。
+ */
+type SettingsResponse = {
+    settings: OrgSettings;
+    deployment: OrgSettingsDeployment;
+    sandboxLimits: OrgSandboxLimits;
+};
+export declare class OrgSettingsController {
+    private readonly settings;
+    constructor(settings: OrgSettingsService);
+    get(org: OrgContext): Promise<SettingsResponse>;
+    update(principal: Principal, org: OrgContext, body: OrgSettingsPatch): Promise<SettingsResponse>;
+}
+export {};