@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/agents/admin-agents.js

@@ -0,0 +1,170 @@
+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 { sql } from "kysely";
+import { escapeLike } from "../conversations/conversations.service.js";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { selectedSkills } from "../skills/usable.js";
+import { AgentLookup } from "./agent-lookup.js";
+const notFound = () => new ApiError("agent.not_found", "Agent not found");
+/**
+ * Cross-org agent reads for the super admin (admin agents spec §3.2, §3.3): every org's live
+ * agents, private ones included. Agents of a deleted org and soft-deleted agents are never listed
+ * and read as `agent.not_found`. The caller checks the super admin (`@SuperAdmin()`).
+ */
+let AdminAgents = class AdminAgents {
+    db;
+    lookup;
+    constructor(db, lookup) {
+        this.db = db;
+        this.lookup = lookup;
+    }
+    /** Live agents of live orgs by id, `limit` per page; `next` is the last id when more follow. */
+    async list(q) {
+        let query = this.rows();
+        if (q.orgId !== undefined)
+            query = query.where("agents.org_id", "=", q.orgId);
+        if (q.q !== undefined && q.q !== "") {
+            query = query.where(sql `agent_versions.definition->>'name' ILIKE ${`%${escapeLike(q.q)}%`} ESCAPE '\\'`);
+        }
+        if (q.after !== undefined)
+            query = query.where("agents.id", ">", q.after);
+        const rows = await query
+            .orderBy("agents.id")
+            .limit(q.limit + 1)
+            .execute();
+        const page = rows.slice(0, q.limit).map(toRow);
+        return { agents: page, next: rows.length > q.limit ? (page.at(-1)?.id ?? null) : null };
+    }
+    /** One live agent of a live org; otherwise `agent.not_found`. */
+    async get(agentId) {
+        const row = await this.rows().where("agents.id", "=", agentId).executeTakeFirst();
+        if (!row)
+            throw notFound();
+        const [view, versions] = await Promise.all([
+            this.lookup.view(agentId),
+            this.db
+                .selectFrom("agent_versions")
+                .select((eb) => eb.fn.countAll().as("n"))
+                .where("agent_id", "=", agentId)
+                .executeTakeFirstOrThrow(),
+        ]);
+        const [skills, connectors] = await Promise.all([
+            selectedSkills(this.db.db, {
+                orgId: row.org_id,
+                agentId,
+                orgSkills: view.definition.skills?.orgSkills ?? [],
+            }),
+            this.connectorsOf(row.org_id, view.definition.disabledTools),
+        ]);
+        return {
+            ...toRow(row),
+            skills: skills
+                .map((s) => ({ id: s.id, name: s.name, scope: s.scope }))
+                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+            connectors,
+            profile: {
+                description: view.profile.description === "" ? null : view.profile.description,
+                quickActions: view.profile.quickActions.map((a) => ({ label: a.title })),
+            },
+            memberIds: view.memberIds,
+            definition: view.definition,
+            versions: Number(versions.n),
+            createdAt: view.createdAt,
+        };
+    }
+    /**
+     * The org's live connectors by name, minus those the agent turns off as a whole: `tools: "all"`,
+     * or a list naming every tool the connector has (a connector without tools stays listed).
+     */
+    async connectorsOf(orgId, disabled) {
+        const rows = await this.db
+            .selectFrom("connectors as c")
+            .select(["c.id", "c.name", "c.slug", "c.status"])
+            .select(sql `coalesce((SELECT array_agg(t.name) FROM capybara.connector_tools t
+          WHERE t.connector_id = c.id), '{}')`.as("tools"))
+            .where("c.org_id", "=", orgId)
+            .where("c.deleted_at", "is", null)
+            .orderBy("c.name")
+            .orderBy("c.id")
+            .execute();
+        const offByConnector = new Map();
+        for (const r of disabled ?? []) {
+            if (r.kind !== "connector")
+                continue;
+            const prev = offByConnector.get(r.connectorId);
+            if (prev === "all" || r.tools === "all")
+                offByConnector.set(r.connectorId, "all");
+            else
+                offByConnector.set(r.connectorId, new Set([...(prev ?? []), ...r.tools]));
+        }
+        const allOff = (id, tools) => {
+            const off = offByConnector.get(id);
+            if (off === undefined)
+                return false;
+            if (off === "all")
+                return true;
+            return tools.length > 0 && tools.every((t) => off.has(t));
+        };
+        return rows
+            .filter((r) => !allOff(r.id, r.tools))
+            .map((r) => ({ id: r.id, name: r.name, slug: r.slug, status: r.status }));
+    }
+    /** The list columns of live agents in live orgs. */
+    rows() {
+        return this.db
+            .selectFrom("agents")
+            .innerJoin("orgs", "orgs.id", "agents.org_id")
+            .innerJoin("accounts", "accounts.id", "agents.owner_account_id")
+            .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",
+            "orgs.name as org_name",
+            sql `agent_versions.definition->>'name'`.as("name"),
+            "agents.profile_avatar",
+            "agents.owner_account_id",
+            "accounts.display_name as owner_name",
+            "agents.needs_reassignment",
+            "agents.visibility",
+            "agents.created_from_template_id",
+            "agents.created_from_template_name",
+            "agents.updated_at",
+        ])
+            .where("agents.deleted_at", "is", null)
+            .where("orgs.deleted_at", "is", null);
+    }
+};
+AdminAgents = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AgentLookup))
+], AdminAgents);
+export { AdminAgents };
+function toRow(r) {
+    return {
+        id: r.id,
+        orgId: r.org_id,
+        orgName: r.org_name,
+        name: r.name,
+        avatar: (r.profile_avatar ?? null),
+        ownerAccountId: r.owner_account_id,
+        ownerName: r.owner_name,
+        needsReassignment: r.needs_reassignment,
+        visibility: r.visibility,
+        createdFrom: r.created_from_template_id === null
+            ? null
+            : { templateId: r.created_from_template_id, name: r.created_from_template_name ?? null },
+        updatedAt: r.updated_at,
+    };
+}

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

@@ -2,6 +2,7 @@ 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' 时为数组。 */
@@ -12,12 +13,30 @@ export interface AgentView {
     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 名单中；
@@ -30,6 +49,11 @@ export declare function visibleTo(viewerAccountId: string | null): (eb: Expressi
  * the live org). Deleted agents are never visible.
  */
 export declare function isAgentVisibleTo(db: KernelSchemaDb, agentId: string, accountId: string): Promise<boolean>;
+/**
+ * {@link isAgentVisibleTo} for an agent of `orgId` only: an agent the account can read in another
+ * org is not visible here (UI slots spec R6, the `agent.detail.section` scope rule).
+ */
+export declare function isAgentVisibleIn(db: KernelSchemaDb, orgId: string, 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

package/dist/agents/agent-lookup.js

@@ -11,7 +11,8 @@ 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 { normalizeStoredDefinition } from "./definition.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");
 /**
@@ -66,6 +67,21 @@ export async function isAgentVisibleTo(db, agentId, accountId) {
         .executeTakeFirst();
     return row !== undefined;
 }
+/**
+ * {@link isAgentVisibleTo} for an agent of `orgId` only: an agent the account can read in another
+ * org is not visible here (UI slots spec R6, the `agent.detail.section` scope rule).
+ */
+export async function isAgentVisibleIn(db, orgId, agentId, accountId) {
+    const row = await db
+        .selectFrom("agents")
+        .select("id")
+        .where("id", "=", agentId)
+        .where("org_id", "=", orgId)
+        .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
@@ -131,6 +147,13 @@ let AgentLookup = class AgentLookup {
             "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)
@@ -142,10 +165,18 @@ let AgentLookup = class AgentLookup {
             .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,
@@ -153,11 +184,24 @@ let AgentLookup = class AgentLookup {
                     ownerAccountId: r.owner_account_id,
                     visibility: r.visibility,
                     currentVersion: r.current_version,
-                    definition: normalizeStoredDefinition(r.definition),
+                    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,
                 },

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;
+}

package/dist/agents/agent-profile.service.js

@@ -0,0 +1,122 @@
+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 { sql } from "kysely";
+import { AttachmentsService } from "../conversations/attachments.service.js";
+import { ApiError } from "../errors.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 { AgentLookup } from "./agent-lookup.js";
+import { AgentsService } from "./agents.service.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).
+ */
+let AgentProfileService = class AgentProfileService {
+    db;
+    lookup;
+    agents;
+    attachments;
+    txHost;
+    constructor(db, lookup, agents, attachments, txHost) {
+        this.db = db;
+        this.lookup = lookup;
+        this.agents = agents;
+        this.attachments = attachments;
+        this.txHost = txHost;
+    }
+    /**
+     * 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.
+     */
+    async update(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId, auditDetail) {
+        if (patch.avatar?.kind === "upload") {
+            await this.attachments.prepareAgentAvatar(orgId, actorAccountId, patch.avatar.uploadId, agentId);
+        }
+        return this.updateIn(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId, auditDetail);
+    }
+    async updateIn(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId, auditDetail) {
+        const t = this.db.db;
+        await this.agents.lockForWrite(orgId, agentId, actorAccountId);
+        const current = await t
+            .selectFrom("agents")
+            .select(sql `to_char(profile_updated_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`.as("at"))
+            .where("id", "=", agentId)
+            .executeTakeFirstOrThrow();
+        if (current.at !== expectedUpdatedAt) {
+            throw new ApiError("agent.profile_conflict", "The profile was changed by someone else; reload it and apply your changes again");
+        }
+        if (patch.avatar?.kind === "upload") {
+            await this.attachments.consumeAgentAvatar(orgId, actorAccountId, patch.avatar.uploadId, agentId);
+        }
+        const fields = ["avatar", "quickActions"].filter((f) => patch[f] !== undefined);
+        // nothing to write: no timestamp bump, no audit row
+        if (fields.length === 0)
+            return (await this.lookup.view(agentId)).profile;
+        await t
+            .updateTable("agents")
+            .set({
+            ...(patch.avatar !== undefined && {
+                profile_avatar: patch.avatar === null ? sql `null` : JSON.stringify(patch.avatar),
+            }),
+            ...(patch.quickActions !== undefined && {
+                profile_quick_actions: JSON.stringify(patch.quickActions),
+            }),
+            profile_updated_at: sql `greatest(date_trunc('milliseconds', now()), profile_updated_at + interval '1 millisecond')`,
+        })
+            .where("id", "=", agentId)
+            .execute();
+        if (patch.avatar !== undefined) {
+            // the avatar changed: every other upload bound to this agent is garbage; the cleanup job
+            // deletes it (and its object) once expired. Re-saving the same upload keeps it.
+            await t
+                .updateTable("attachments")
+                .set({ expires_at: sql `now()` })
+                .where("agent_id", "=", agentId)
+                .where("purpose", "=", "agent-avatar")
+                .$if(patch.avatar?.kind === "upload", (q) => q.where("id", "<>", patch.avatar.uploadId))
+                .execute();
+        }
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "agent.profile_updated",
+            target: agentId,
+            detail: {
+                fields,
+                channel: actorTokenId !== undefined ? "api" : auditDetail !== undefined ? "agent" : "web",
+                ...auditDetail,
+            },
+        });
+        return (await this.lookup.view(agentId)).profile;
+    }
+};
+__decorate([
+    Transactional()
+], AgentProfileService.prototype, "updateIn", null);
+AgentProfileService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AgentLookup)),
+    __param(2, Inject(AgentsService)),
+    __param(3, Inject(AttachmentsService)),
+    __param(4, Inject(TransactionHost))
+], AgentProfileService);
+export { AgentProfileService };