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

package/dist/admin/setup.controller.js

@@ -8,28 +8,33 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { createHash, timingSafeEqual } from "node:crypto";
-import { Body, Controller, Get, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
+import { Controller, Get, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
-import { KERNEL_CONFIG, RATE_LIMITER, SESSIONS, SETUP } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { clientMeta } from "../identity/auth.controller.js";
 import { setSessionCookies } from "../identity/cookies.js";
 import { MAX_PASSWORD_LENGTH } from "../identity/login.js";
 import { Public } from "../identity/principal.js";
-const SetupBody = z.object({
+import { SessionService } from "../identity/sessions.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
+import { SetupService } from "./setup.service.js";
+const SetupSchema = z.object({
     login: z.string().min(1).max(64),
     password: z.string().min(1).max(MAX_PASSWORD_LENGTH),
     displayName: z.string().trim().min(1).max(100),
     orgName: z.string().max(100).optional(),
     setupToken: z.string().max(1024).optional(),
 });
+class SetupBody extends createZodDto(SetupSchema, "SetupBody") {
+}
 /**
- * 初始化令牌的限流（scope `setup`）：同一客户端 IP 10 次、全部署合计 100 次 / 900s
- * （合计上限防换 IP 爆破；令牌本身应足够长，正常情况下打不满）。
+ * The setup token's credential throttlers: 10 per client IP, 100 for the whole deployment per
+ * 900 s (the total stops guessing from many IPs; a long token never hits it in normal use).
  */
-const SETUP_TOKEN_LIMIT_TOTAL = 100;
-const SETUP_TOKEN_LIMIT_PER_IP = 10;
+const SETUP_THROTTLERS = ["setup-token", "setup-ip"];
 const sha256 = (s) => createHash("sha256").update(s, "utf8").digest();
 /** 常数时间比较：两边先取 SHA-256，长度恒等，不因长度不同提前返回或抛错。 */
 function tokenMatches(given, expected) {
@@ -40,35 +45,30 @@ let SetupController = class SetupController {
     setup;
     sessions;
     config;
-    limiter;
-    constructor(setup, sessions, config, limiter) {
+    throttler;
+    constructor(setup, sessions, config, throttler) {
         this.setup = setup;
         this.sessions = sessions;
         this.config = config;
-        this.limiter = limiter;
+        this.throttler = throttler;
     }
     async status() {
         return this.setup.status();
     }
     /**
-     * 建首个企业管理员（可选同时建组织），成功后直接登录（设会话 Cookie）。
+     * 建首个超级管理员（可选同时建组织），成功后直接登录（设会话 Cookie）。
      * 配置了 `auth.setupToken` 时 body 中的 `setupToken` 必须与之相等，否则 `setup.token_invalid`；
      * 核对前先占用限流额度，超限 → 429 `auth.rate_limited`，核对通过后退还。
      */
     async complete(body, req, reply) {
-        const cfg = this.config();
+        const cfg = this.config.get();
         const expected = cfg.auth.setupToken;
         if (expected !== undefined) {
-            const { ip } = clientMeta(req);
-            const rl = await this.limiter.reserveScoped("setup", "token", ip, SETUP_TOKEN_LIMIT_TOTAL, SETUP_TOKEN_LIMIT_PER_IP);
-            if (!rl.allowed) {
-                reply.header("retry-after", String(rl.retryAfterSeconds));
-                throw new ApiError("auth.rate_limited", "Too many setup attempts; try again later");
-            }
+            await this.throttler.reserve(SETUP_THROTTLERS, req, reply);
             if (!tokenMatches(body.setupToken, expected)) {
                 throw new ApiError("setup.token_invalid", "Setup token is missing or invalid");
             }
-            await this.limiter.succeededScoped("setup", "token", ip);
+            await this.throttler.succeeded(SETUP_THROTTLERS, req);
         }
         // 会话行与账号 / 组织在同一事务里写入；Cookie 在提交之后才设置
         const meta = clientMeta(req);
@@ -77,7 +77,9 @@ let SetupController = class SetupController {
             password: body.password,
             displayName: body.displayName,
             orgName: body.orgName,
-        }, (trx, account) => this.sessions.create(account.id, meta, trx));
+        }, 
+        // runs in the setup's transaction
+        (account) => this.sessions.create(account.id, meta));
         if (!session)
             throw new Error("setup completed without a session");
         setSessionCookies(reply, session, cfg);
@@ -92,15 +94,15 @@ __decorate([
     Post(),
     Public(),
     HttpCode(201),
-    __param(0, Body(new ZodPipe(SetupBody))),
+    __param(0, ZBody(SetupBody)),
     __param(1, Req()),
     __param(2, Res({ passthrough: true }))
 ], SetupController.prototype, "complete", null);
 SetupController = __decorate([
     Controller("api/v1/setup"),
-    __param(0, Inject(SETUP)),
-    __param(1, Inject(SESSIONS)),
-    __param(2, Inject(KERNEL_CONFIG)),
-    __param(3, Inject(RATE_LIMITER))
+    __param(0, Inject(SetupService)),
+    __param(1, Inject(SessionService)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(CredentialThrottler))
 ], SetupController);
 export { SetupController };

package/dist/admin/setup.service.d.ts

@@ -1,47 +1,39 @@
-import type { Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import type { Account, AccountsService } from "../identity/accounts.js";
-import type { Org, OrgsService } from "../orgs/orgs.service.js";
-/** 初始化向导与 CLI 建企业管理员。框架无关，由调用方注入依赖。 */
+import { type Account, AccountsService } from "../identity/accounts.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { type Org, OrgsService } from "../orgs/orgs.service.js";
+import { SetupLock } from "./setup-lock.js";
+/**
+ * The setup wizard. The CLI's super admin creation (`createSuperAdmin`,
+ * `createSuperAdminIfNone`) is on `AccountsService`, under the same {@link SetupLock}.
+ */
 export declare class SetupService {
     private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly setupLock;
     private readonly accounts;
     private readonly orgs;
-    constructor(db: KernelDb, accounts: AccountsService, orgs: OrgsService);
-    /** 不存在活跃企业管理员即需要初始化（每次实时查 PG，不缓存）。 */
+    constructor(db: KernelDb, txHost: TransactionHost, setupLock: SetupLock, accounts: AccountsService, orgs: OrgsService);
+    /** 不存在活跃超级管理员即需要初始化（每次实时查 PG，不缓存）。 */
     status(): Promise<{
         needsSetup: boolean;
     }>;
     /**
-     * 完成初始化：单个事务内先取咨询锁串行化并发的初始化请求，锁内再确认没有活跃企业管理员，
-     * 然后建企业管理员账号、（给了 `orgName` 时）建组织并以其为 owner。任一步失败整体回滚。
-     * 给了 `inTx` 时在同一事务的最后调用它（初始化向导用它建会话），结果放在 `extra`；它失败同样整体回滚。
+     * Completes the setup in one transaction: {@link SetupLock} serializes concurrent setups, and
+     * under it there must still be no active super admin; then creates the super admin
+     * and (with `orgName`) an org it owns. Any failure rolls everything back. `inTx` runs last in the
+     * same transaction (the wizard creates the session there), its result is `extra`; its failure
+     * rolls back too.
      */
     complete<T = undefined>(input: {
         login: string;
         password: string;
         displayName: string;
         orgName?: string | undefined;
-    }, inTx?: (trx: Transaction<KernelDatabase>, account: Account) => Promise<T>): Promise<{
+    }, inTx?: (account: Account) => Promise<T>): Promise<{
         account: Account;
         org?: Org;
         extra: T | undefined;
     }>;
-    /** CLI 用：直接建企业管理员，不检查是否已初始化；登录名已存在 → `account.login_taken`。 */
-    createEnterpriseAdmin(input: EnterpriseAdminInput): Promise<Account>;
-    /**
-     * CLI `admin create --if-none`: create an enterprise admin only when no active one exists. The
-     * check and the insert run in one transaction under the same advisory lock as {@link complete},
-     * so concurrent runs (and a concurrent web setup) create exactly one. Returns undefined when an
-     * active enterprise admin already exists; a taken login still throws `account.login_taken`.
-     */
-    createEnterpriseAdminIfNone(input: EnterpriseAdminInput): Promise<Account | undefined>;
-    private insertEnterpriseAdmin;
-}
-/** Input of the CLI enterprise admin creation. */
-export interface EnterpriseAdminInput {
-    login: string;
-    password: string;
-    displayName: string;
-    email?: string | undefined;
+    private completeIn;
 }

package/dist/admin/setup.service.js

@@ -1,90 +1,90 @@
-import { sql } from "kysely";
+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 { AccountsService } from "../identity/accounts.js";
 import { audit } from "../identity/audit.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 { OrgsService } from "../orgs/orgs.service.js";
+import { SetupLock } from "./setup-lock.js";
 const alreadyCompleted = () => new ApiError("setup.already_completed", "Deployment is already set up");
-/** 初始化向导与 CLI 建企业管理员。框架无关，由调用方注入依赖。 */
-export class SetupService {
+/**
+ * The setup wizard. The CLI's super admin creation (`createSuperAdmin`,
+ * `createSuperAdminIfNone`) is on `AccountsService`, under the same {@link SetupLock}.
+ */
+let SetupService = class SetupService {
     db;
+    txHost;
+    setupLock;
     accounts;
     orgs;
-    constructor(db, accounts, orgs) {
+    constructor(db, txHost, setupLock, accounts, orgs) {
         this.db = db;
+        this.txHost = txHost;
+        this.setupLock = setupLock;
         this.accounts = accounts;
         this.orgs = orgs;
     }
-    /** 不存在活跃企业管理员即需要初始化（每次实时查 PG，不缓存）。 */
+    /** 不存在活跃超级管理员即需要初始化（每次实时查 PG，不缓存）。 */
     async status() {
-        return { needsSetup: (await this.accounts.countEnterpriseAdmins()) === 0 };
+        return { needsSetup: (await this.accounts.countSuperAdmins()) === 0 };
     }
     /**
-     * 完成初始化：单个事务内先取咨询锁串行化并发的初始化请求，锁内再确认没有活跃企业管理员，
-     * 然后建企业管理员账号、（给了 `orgName` 时）建组织并以其为 owner。任一步失败整体回滚。
-     * 给了 `inTx` 时在同一事务的最后调用它（初始化向导用它建会话），结果放在 `extra`；它失败同样整体回滚。
+     * Completes the setup in one transaction: {@link SetupLock} serializes concurrent setups, and
+     * under it there must still be no active super admin; then creates the super admin
+     * and (with `orgName`) an org it owns. Any failure rolls everything back. `inTx` runs last in the
+     * same transaction (the wizard creates the session there), its result is `extra`; its failure
+     * rolls back too.
      */
     async complete(input, inTx) {
-        // 先做一次廉价的预检查（已初始化的部署不白跑 scrypt），再在 BEGIN 之前算好哈希：
-        // 不在持有咨询锁的事务里跑 scrypt；锁内仍会复核
-        if ((await this.accounts.countEnterpriseAdmins()) > 0)
+        // A cheap pre-check first (a set-up deployment does not run scrypt for nothing), then the hash
+        // before BEGIN: no scrypt inside the transaction holding the lock; the check runs again under it
+        if ((await this.accounts.countSuperAdmins()) > 0)
             throw alreadyCompleted();
         const passwordHash = await this.accounts.hashNewPassword(input.password);
-        return this.db.transaction().execute(async (trx) => {
-            await sql `SELECT pg_advisory_xact_lock(hashtext('capybara.setup'))`.execute(trx);
-            if ((await this.accounts.countEnterpriseAdmins(trx)) > 0)
-                throw alreadyCompleted();
-            const account = await this.accounts.createLocal({
-                login: input.login,
-                password: input.password,
-                displayName: input.displayName,
-                enterpriseAdmin: true,
-            }, trx, passwordHash);
-            const org = input.orgName !== undefined
-                ? await this.orgs.create({ name: input.orgName }, account, { trx })
-                : undefined;
-            await audit(trx, {
-                actorAccountId: account.id,
-                action: "deployment.setup_completed",
-                target: account.id,
-                ...(org && { orgId: org.id, detail: { orgId: org.id } }),
-            });
-            const extra = inTx ? await inTx(trx, account) : undefined;
-            return { account, ...(org && { org }), extra };
-        });
-    }
-    /** CLI 用：直接建企业管理员，不检查是否已初始化；登录名已存在 → `account.login_taken`。 */
-    async createEnterpriseAdmin(input) {
-        const passwordHash = await this.accounts.hashNewPassword(input.password);
-        return this.db
-            .transaction()
-            .execute((trx) => this.insertEnterpriseAdmin(trx, input, passwordHash));
+        return this.completeIn(input, passwordHash, inTx);
     }
-    /**
-     * CLI `admin create --if-none`: create an enterprise admin only when no active one exists. The
-     * check and the insert run in one transaction under the same advisory lock as {@link complete},
-     * so concurrent runs (and a concurrent web setup) create exactly one. Returns undefined when an
-     * active enterprise admin already exists; a taken login still throws `account.login_taken`.
-     */
-    async createEnterpriseAdminIfNone(input) {
-        const passwordHash = await this.accounts.hashNewPassword(input.password);
-        return this.db.transaction().execute(async (trx) => {
-            await sql `SELECT pg_advisory_xact_lock(hashtext('capybara.setup'))`.execute(trx);
-            if ((await this.accounts.countEnterpriseAdmins(trx)) > 0)
-                return undefined;
-            return this.insertEnterpriseAdmin(trx, input, passwordHash);
-        });
-    }
-    async insertEnterpriseAdmin(trx, input, passwordHash) {
+    async completeIn(input, passwordHash, inTx) {
+        await this.setupLock.lock();
+        if ((await this.accounts.countSuperAdmins()) > 0)
+            throw alreadyCompleted();
         const account = await this.accounts.createLocal({
             login: input.login,
             password: input.password,
             displayName: input.displayName,
-            enterpriseAdmin: true,
-            ...(input.email !== undefined && { email: input.email }),
-        }, trx, passwordHash);
-        await audit(trx, {
-            action: "account.created",
+            superAdmin: true,
+        }, passwordHash);
+        const org = input.orgName !== undefined
+            ? await this.orgs.create({ name: input.orgName }, account)
+            : undefined;
+        await audit(this.db.db, {
+            actorAccountId: account.id,
+            action: "deployment.setup_completed",
             target: account.id,
-            detail: { enterpriseAdmin: true, via: "cli" },
+            ...(org && { orgId: org.id, detail: { orgId: org.id } }),
         });
-        return account;
+        const extra = inTx ? await inTx(account) : undefined;
+        return { account, ...(org && { org }), extra };
     }
-}
+};
+__decorate([
+    Transactional()
+], SetupService.prototype, "completeIn", null);
+SetupService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SetupLock)),
+    __param(3, Inject(AccountsService)),
+    __param(4, Inject(OrgsService))
+], SetupService);
+export { SetupService };

package/dist/agents/agent-lookup.d.ts

@@ -0,0 +1,72 @@
+import { type ExpressionBuilder } from "kysely";
+import type { KernelDatabase, KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type AgentDefinition } from "./definition.js";
+import type { AgentProfile } from "./profile.js";
+export declare const AGENT_VISIBILITIES: readonly ["private", "org", "members"];
+export type AgentVisibility = (typeof AGENT_VISIBILITIES)[number];
+/** 对外的 agent 视图：当前版本的定义 + 元数据；`memberIds` 只在 visibility='members' 时为数组。 */
+export interface AgentView {
+    id: string;
+    orgId: string;
+    ownerAccountId: string;
+    visibility: AgentVisibility;
+    currentVersion: number;
+    definition: AgentDefinition;
+    /** Display data outside the versions (never model-visible). */
+    profile: AgentProfile;
+    memberIds: string[] | null;
+    /** 负责人离职后被转给组织所有者、等待管理员重新指派。 */
+    needsReassignment: boolean;
+    /**
+     * The template the agent was created from (ruling P4-8; set once, never versioned), null for an
+     * agent created otherwise. `name` and `version` are the snapshot taken at create.
+     */
+    createdFrom: AgentProvenance | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** {@link AgentView.createdFrom}. */
+export interface AgentProvenance {
+    templateId: string;
+    version: number;
+    name: string;
+    /**
+     * The template is still usable in the org (the agent page links it only then). Set on the
+     * agents API's responses only (`AgentsService.withTemplateLinks`), never on internal reads.
+     */
+    available?: boolean;
+}
+/**
+ * 可见性判定（`canUse`）的 SQL 条件：agent 未删除、所属组织未删除，且
+ * - viewer 为账号：仍是该组织成员（含访客），并且是负责人 / visibility='org' / 在 agent_members 名单中；
+ * - viewer 为 null（该组织的服务令牌）：只认 visibility='org'。
+ */
+export declare function visibleTo(viewerAccountId: string | null): (eb: ExpressionBuilder<KernelDatabase, "agents">) => import("kysely").ExpressionWrapper<KernelDatabase, "agents", import("kysely").SqlBool>;
+/**
+ * Whether the live agent `agentId` is visible to `accountId` under the normal visibility rule
+ * ({@link visibleTo}: owner, `visibility = 'org'`, or listed in `agent_members`, while a member of
+ * the live org). Deleted agents are never visible.
+ */
+export declare function isAgentVisibleTo(db: KernelSchemaDb, agentId: string, accountId: string): Promise<boolean>;
+/**
+ * Reads agents for a viewer (the visibility rule {@link visibleTo}): the part of `AgentsService`
+ * the conversations, the skill invoker and the attachments read, with no dependency on the
+ * services that write agents (it breaks the agents ↔ skills module cycle, spec §3 (a)). Reads go
+ * through `KernelDb`, so inside a transaction they see its writes.
+ */
+export declare class AgentLookup {
+    private readonly db;
+    constructor(db: KernelDb);
+    /** 取对 viewer 可见的 agent；`viewerAccountId = null` 表示该组织的服务令牌。不可见 → `agent.not_found`。 */
+    get(orgId: string, agentId: string, viewerAccountId: string | null): Promise<AgentView>;
+    /** 组织内对 viewer 可见的全部 agent（按创建时间）。 */
+    listVisible(orgId: string, viewerAccountId: string | null): Promise<AgentView[]>;
+    /** One agent's view (no visibility check: the caller did it); missing → `agent.not_found`. */
+    view(agentId: string): Promise<AgentView>;
+    /** 按给定 id 顺序组装视图（调用方已完成可见性判定）。 */
+    views(ids: string[]): Promise<AgentView[]>;
+}
+/** The one {@link AgentLookup} (database only). */
+export declare class AgentLookupModule {
+}

package/dist/agents/agent-lookup.js

@@ -0,0 +1,208 @@
+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, Module } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { loadLegacyScope } from "../tools/legacy-data.js";
+import { needsLegacyScope, normalizeStoredDefinition } from "./definition.js";
+export const AGENT_VISIBILITIES = ["private", "org", "members"];
+const notFound = () => new ApiError("agent.not_found", "Agent not found");
+/**
+ * 可见性判定（`canUse`）的 SQL 条件：agent 未删除、所属组织未删除，且
+ * - viewer 为账号：仍是该组织成员（含访客），并且是负责人 / visibility='org' / 在 agent_members 名单中；
+ * - viewer 为 null（该组织的服务令牌）：只认 visibility='org'。
+ */
+export function visibleTo(viewerAccountId) {
+    return (eb) => {
+        const orgLive = eb.exists(eb
+            .selectFrom("orgs")
+            .select(sql `1`.as("one"))
+            .whereRef("orgs.id", "=", "agents.org_id")
+            .where("orgs.deleted_at", "is", null));
+        if (viewerAccountId === null) {
+            return eb.and([orgLive, eb("agents.visibility", "=", "org")]);
+        }
+        return eb.and([
+            orgLive,
+            eb.exists(eb
+                .selectFrom("memberships")
+                .select(sql `1`.as("one"))
+                .whereRef("memberships.org_id", "=", "agents.org_id")
+                .where("memberships.account_id", "=", viewerAccountId)),
+            eb.or([
+                eb("agents.owner_account_id", "=", viewerAccountId),
+                eb("agents.visibility", "=", "org"),
+                eb.and([
+                    eb("agents.visibility", "=", "members"),
+                    eb.exists(eb
+                        .selectFrom("agent_members")
+                        .select(sql `1`.as("one"))
+                        .whereRef("agent_members.agent_id", "=", "agents.id")
+                        .where("agent_members.account_id", "=", viewerAccountId)),
+                ]),
+            ]),
+        ]);
+    };
+}
+/**
+ * Whether the live agent `agentId` is visible to `accountId` under the normal visibility rule
+ * ({@link visibleTo}: owner, `visibility = 'org'`, or listed in `agent_members`, while a member of
+ * the live org). Deleted agents are never visible.
+ */
+export async function isAgentVisibleTo(db, agentId, accountId) {
+    const row = await db
+        .selectFrom("agents")
+        .select("id")
+        .where("id", "=", agentId)
+        .where("deleted_at", "is", null)
+        .where(visibleTo(accountId))
+        .executeTakeFirst();
+    return row !== undefined;
+}
+/**
+ * Reads agents for a viewer (the visibility rule {@link visibleTo}): the part of `AgentsService`
+ * the conversations, the skill invoker and the attachments read, with no dependency on the
+ * services that write agents (it breaks the agents ↔ skills module cycle, spec §3 (a)). Reads go
+ * through `KernelDb`, so inside a transaction they see its writes.
+ */
+let AgentLookup = class AgentLookup {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** 取对 viewer 可见的 agent；`viewerAccountId = null` 表示该组织的服务令牌。不可见 → `agent.not_found`。 */
+    async get(orgId, agentId, viewerAccountId) {
+        const row = await this.db
+            .selectFrom("agents")
+            .select("id")
+            .where("id", "=", agentId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .where(visibleTo(viewerAccountId))
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        return this.view(agentId);
+    }
+    /** 组织内对 viewer 可见的全部 agent（按创建时间）。 */
+    async listVisible(orgId, viewerAccountId) {
+        const rows = await this.db
+            .selectFrom("agents")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .where(visibleTo(viewerAccountId))
+            .orderBy("created_at")
+            .orderBy("id")
+            .execute();
+        return this.views(rows.map((r) => r.id));
+    }
+    /** One agent's view (no visibility check: the caller did it); missing → `agent.not_found`. */
+    async view(agentId) {
+        const views = await this.views([agentId]);
+        const v = views[0];
+        if (!v)
+            throw notFound();
+        return v;
+    }
+    /** 按给定 id 顺序组装视图（调用方已完成可见性判定）。 */
+    async views(ids) {
+        if (ids.length === 0)
+            return [];
+        const db = this.db;
+        const rows = await db
+            .selectFrom("agents")
+            .innerJoin("agent_versions", (j) => j
+            .onRef("agent_versions.agent_id", "=", "agents.id")
+            .onRef("agent_versions.version", "=", "agents.current_version"))
+            .select([
+            "agents.id",
+            "agents.org_id",
+            "agents.owner_account_id",
+            "agents.visibility",
+            "agents.current_version",
+            "agents.needs_reassignment",
+            "agents.created_at",
+            "agents.updated_at",
+            "agents.profile_avatar",
+            "agents.profile_description",
+            "agents.profile_quick_actions",
+            "agents.profile_updated_at",
+            "agents.created_from_template_id",
+            "agents.created_from_template_version",
+            "agents.created_from_template_name",
+            "agent_versions.definition",
+        ])
+            .where("agents.id", "in", ids)
+            .execute();
+        const memberRows = await db
+            .selectFrom("agent_members")
+            .select(["agent_id", "account_id"])
+            .where("agent_id", "in", ids)
+            .orderBy("account_id")
+            .execute();
+        const byId = new Map(rows.map((r) => [r.id, r]));
+        // rc `<x>__<tool>` keys read with their org's scope, loaded once per org that needs it
+        const scopes = new Map();
+        for (const r of rows) {
+            if (!scopes.has(r.org_id) && needsLegacyScope(r.definition)) {
+                scopes.set(r.org_id, await loadLegacyScope(this.db.db, r.org_id));
+            }
+        }
+        return ids.flatMap((id) => {
+            const r = byId.get(id);
+            if (!r)
+                return [];
+            const fromId = r.created_from_template_id;
+            return [
+                {
+                    id: r.id,
+                    orgId: r.org_id,
+                    ownerAccountId: r.owner_account_id,
+                    visibility: r.visibility,
+                    currentVersion: r.current_version,
+                    definition: normalizeStoredDefinition(r.definition, scopes.get(r.org_id)),
+                    profile: {
+                        avatar: r.profile_avatar,
+                        description: r.profile_description,
+                        quickActions: r.profile_quick_actions,
+                        updatedAt: r.profile_updated_at.toISOString(),
+                    },
+                    memberIds: r.visibility === "members"
+                        ? memberRows.filter((m) => m.agent_id === id).map((m) => m.account_id)
+                        : null,
+                    needsReassignment: r.needs_reassignment,
+                    createdFrom: fromId === null
+                        ? null
+                        : {
+                            templateId: fromId,
+                            version: r.created_from_template_version ?? 1,
+                            name: r.created_from_template_name ?? "",
+                        },
+                    createdAt: r.created_at,
+                    updatedAt: r.updated_at,
+                },
+            ];
+        });
+    }
+};
+AgentLookup = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], AgentLookup);
+export { AgentLookup };
+/** The one {@link AgentLookup} (database only). */
+let AgentLookupModule = class AgentLookupModule {
+};
+AgentLookupModule = __decorate([
+    Module({ providers: [AgentLookup], exports: [AgentLookup] })
+], AgentLookupModule);
+export { AgentLookupModule };

package/dist/agents/agent-profile.service.d.ts

@@ -0,0 +1,31 @@
+import { AttachmentsService } from "../conversations/attachments.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { AgentLookup } from "./agent-lookup.js";
+import { AgentsService } from "./agents.service.js";
+import type { AgentProfile, ProfilePatch } from "./profile.js";
+/**
+ * Writes an agent's profile (avatar, quick actions): display data stored beside the agent, never
+ * model-visible, so a change creates no agent version. The description is part of the definition
+ * (run context spec §3.5). The permission is the one of
+ * `AgentsService.update` (owner or org admin, checked under the org row lock).
+ */
+export declare class AgentProfileService {
+    private readonly db;
+    private readonly lookup;
+    private readonly agents;
+    private readonly attachments;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, lookup: AgentLookup, agents: Pick<AgentsService, "lockForWrite">, attachments: Pick<AttachmentsService, "prepareAgentAvatar" | "consumeAgentAvatar">, txHost: TransactionHost);
+    /**
+     * Applies `patch` (only the given fields) when `expectedUpdatedAt` is still the profile's
+     * `updatedAt`, else 409 `agent.profile_conflict` (never a silent overwrite). Audit
+     * `agent.profile_updated` `{ fields, channel, ...auditDetail }`: `api` for a personal access
+     * token, `agent` for a write through the `Platform` tool (`auditDetail` given), else `web`.
+     * An `upload` avatar must be the actor's own upload that no other agent uses (else 404
+     * `attachment.not_found`): it is finalized first (outside the transaction, it reads the object
+     * store; 503 `storage.unavailable` without one) and bound to the agent inside it.
+     */
+    update(orgId: string, agentId: string, actorAccountId: string, patch: ProfilePatch, expectedUpdatedAt: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<AgentProfile>;
+    private updateIn;
+}