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

package/dist/platform/ops/connectors.ops.js

@@ -0,0 +1,126 @@
+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 { z } from "zod";
+import { ComponentScopeService } from "../../catalog/component-scope.service.js";
+import { ConnectorsService, } from "../../tools/connectors.service.js";
+import { publicEndpoint } from "../../tools/endpoint.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { asToolError } from "./errors.js";
+import { Cursor, pageOf, startOf } from "./paging.js";
+const PAGE = 50;
+/**
+ * A connector without anything secret: the auth method and who holds the credential (the org or
+ * each person), never the auth preset's fields or a credential. The endpoint is always the public
+ * one (origin only, header names only), as the route shows readers without `connectors.manage`,
+ * whatever the actor's role: the result enters a log other people read.
+ */
+const summary = (c) => ({
+    id: c.id,
+    slug: c.slug,
+    name: c.name,
+    connector: c.connector,
+    endpoint: publicEndpoint(c.endpoint),
+    auth: {
+        type: c.auth.type,
+        ownership: "ownership" in c.auth ? (c.auth.ownership ?? null) : null,
+    },
+    status: c.status,
+    platformTemplateId: c.platformTemplateId,
+    updatedAt: c.updatedAt,
+});
+/** A connector's detail: its tools (name, description, state, default policy) and your credential state. */
+const detail = (c) => ({
+    ...summary(c),
+    credential: c.credential,
+    tools: c.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        status: t.status,
+        defaultPolicy: t.defaultPolicy,
+        missing: t.missing,
+        pendingReview: t.pending !== null,
+    })),
+});
+/**
+ * Connector operations of the `Platform` tool (spec §7): read only. Creating a connector or
+ * entering a credential stays on the web (a person types credentials, spec §6.4).
+ */
+let ConnectorsOperations = class ConnectorsOperations {
+    registry;
+    connectors;
+    components;
+    constructor(registry, connectors, components) {
+        this.registry = registry;
+        this.connectors = connectors;
+        this.components = components;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "connectors.list",
+                description: "List the org's connectors: name, protocol, endpoint, auth method and status, never credentials. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { orgAction: "connectors.use" },
+                mirrors: ["GET /api/v1/orgs/:orgId/connectors"],
+                confirm: "read",
+                run: async (input, ctx) => pageOf((await this.connectors.list(ctx.orgId)).map(summary), startOf(input.cursor), PAGE),
+            }),
+            defineOperation({
+                id: "connectors.get",
+                description: "Read one connector: its tools with their state and default policy, and whether your credential for it is connected. Credentials are never returned; a person enters them on the connector's web page.",
+                input: z.object({ connectorId: z.string().min(1).max(100) }).strict(),
+                example: { connectorId: "5d2e8f1a-0b3c-4d5e-8f9a-1b2c3d4e5f60" },
+                authz: { orgAction: "connectors.use" },
+                mirrors: ["GET /api/v1/orgs/:orgId/connectors/:connectorId"],
+                confirm: "read",
+                errors: [
+                    { code: "connector.not_found", next: "Check the connector id with connectors.list." },
+                ],
+                run: async (input, ctx) => asToolError(async () => ({
+                    connector: detail(await this.connectors.get(ctx.orgId, input.connectorId, ctx.actorAccountId)),
+                })),
+            }),
+            defineOperation({
+                id: "connectors.templates",
+                description: "List the platform connector templates offered to this org, with whether each is on here: the templates the web's create-from-template flow offers. Creating a connector from one needs credentials, so it is done on the web. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/components"],
+                confirm: "read",
+                run: async (input, ctx) => {
+                    const all = await this.components.orgList(ctx.orgId, { kind: "connector_template" });
+                    const templates = all.map((t) => ({
+                        id: t.id,
+                        name: t.name,
+                        description: t.description,
+                        plugin: t.plugin,
+                        itemId: t.itemId,
+                        version: t.version,
+                        on: t.on,
+                        switchable: t.switchable,
+                        owner: t.owner,
+                    }));
+                    return pageOf(templates, startOf(input.cursor), PAGE);
+                },
+            }),
+        ]);
+    }
+};
+ConnectorsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(ConnectorsService)),
+    __param(2, Inject(ComponentScopeService))
+], ConnectorsOperations);
+export { ConnectorsOperations };

package/dist/platform/ops/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runs a service call for an operation: an {@link ApiError} (the service's refusal: forbidden,
+ * not found, a stale preview) becomes a {@link ToolError} naming its code, so the model reads what
+ * to do next instead of a generic failure. Anything else is a bug and propagates.
+ */
+export declare function asToolError<T>(call: () => Promise<T>): Promise<T>;
+/** The audit detail of a write made through the tool (spec §6): who, where and which operation. */
+export declare function viaAgent(operation: string, ctx: {
+    conversationId: string;
+    runId: string | null;
+}): Record<string, unknown>;

package/dist/platform/ops/errors.js

@@ -0,0 +1,22 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../../errors.js";
+/**
+ * Runs a service call for an operation: an {@link ApiError} (the service's refusal: forbidden,
+ * not found, a stale preview) becomes a {@link ToolError} naming its code, so the model reads what
+ * to do next instead of a generic failure. Anything else is a bug and propagates.
+ */
+export async function asToolError(call) {
+    try {
+        return await call();
+    }
+    catch (e) {
+        if (e instanceof ApiError) {
+            throw new ToolError(`${e.code}: ${e.message}`);
+        }
+        throw e;
+    }
+}
+/** The audit detail of a write made through the tool (spec §6): who, where and which operation. */
+export function viaAgent(operation, ctx) {
+    return { via: "agent", conversationId: ctx.conversationId, runId: ctx.runId, operation };
+}

package/dist/platform/ops/extensions.ops.d.ts

@@ -0,0 +1,19 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { ExtensionDisplayNames } from "../../extensions/display-name.js";
+import { OrgExtensionConfigs } from "../../extensions/org-config.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Extension operations of the `Platform` tool (spec §7): read only, and state only. The org config,
+ * the secrets' state, the config schema and the permission list are never returned (the member
+ * projection of `GET /orgs/:orgId/extensions`, whatever the actor's role); configuring an
+ * extension is done on the web.
+ */
+export declare class ExtensionsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly configs;
+    private readonly displayNames;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, configs: OrgExtensionConfigs, displayNames: ExtensionDisplayNames, kdb: KernelDb);
+    onModuleInit(): void;
+}

package/dist/platform/ops/extensions.ops.js

@@ -0,0 +1,116 @@
+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 { EXTENSION_POINTS, parseExtensionPoint } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { ExtensionDisplayNames } from "../../extensions/display-name.js";
+import { OrgExtensionConfigs, providesOf } from "../../extensions/org-config.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { can } from "../../orgs/roles.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { Cursor, pageOf, startOf } from "./paging.js";
+import { roleOf } from "./role.js";
+const NoInput = z.object({}).strict();
+/**
+ * Extension operations of the `Platform` tool (spec §7): read only, and state only. The org config,
+ * the secrets' state, the config schema and the permission list are never returned (the member
+ * projection of `GET /orgs/:orgId/extensions`, whatever the actor's role); configuring an
+ * extension is done on the web.
+ */
+let ExtensionsOperations = class ExtensionsOperations {
+    registry;
+    configs;
+    displayNames;
+    kdb;
+    constructor(registry, configs, displayNames, kdb) {
+        this.registry = registry;
+        this.configs = configs;
+        this.displayNames = displayNames;
+        this.kdb = kdb;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "extensions.list",
+                description: "List the extensions installed on the platform as this org sees them: whether each is enabled here, available on the platform, required, which plugin brings it and which extension points it provides. State only: configuring one is done on the web. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { orgAction: "org.extensions.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/extensions"],
+                confirm: "read",
+                run: async (input, ctx) => {
+                    const views = await this.configs.list(ctx.orgId);
+                    const names = await this.displayNames.many(views.map((v) => v.plugin));
+                    return pageOf(views.map((v) => ({
+                        plugin: v.plugin,
+                        displayName: names.get(v.plugin) ?? null,
+                        version: v.version,
+                        enabled: v.enabled,
+                        available: v.available,
+                        required: v.required,
+                        configurable: v.configurable,
+                        switchable: v.switchable,
+                        catalogItem: v.catalogItem,
+                        provides: providesOf(v),
+                    })), startOf(input.cursor), 50);
+                },
+            }),
+            defineOperation({
+                id: "extensions.points",
+                description: "List the extension points of the platform (the contracts extensions implement, such as channel@1 or model-provider@2): what each is for, whether it takes one provider or several, and whether an extension enabled in this org provides it (org admins also get the providers' plugin names).",
+                input: NoInput,
+                example: {},
+                authz: { orgAction: "org.extensions.read" },
+                mirrors: [],
+                confirm: "read",
+                run: async (_input, ctx) => {
+                    const providers = new Map();
+                    for (const v of await this.configs.list(ctx.orgId)) {
+                        if (!v.enabled || !v.available)
+                            continue;
+                        for (const ref of providesOf(v)) {
+                            let name;
+                            try {
+                                name = parseExtensionPoint(ref).name;
+                            }
+                            catch {
+                                continue;
+                            }
+                            providers.set(name, [...(providers.get(name) ?? []), v.plugin]);
+                        }
+                    }
+                    // provider names only for those who manage extensions, as `GET extension-points` (the
+                    // members' `available` route gives no names)
+                    const role = await roleOf(this.kdb.db, ctx.orgId, ctx.actorAccountId);
+                    const names = role !== null && can(role, "org.extensions.manage");
+                    return {
+                        points: Object.entries(EXTENSION_POINTS).map(([name, p]) => ({
+                            name,
+                            description: p.description,
+                            cardinality: p.cardinality,
+                            ...(names
+                                ? { providers: providers.get(name) ?? [] }
+                                : { hasProvider: providers.has(name) }),
+                        })),
+                    };
+                },
+            }),
+        ]);
+    }
+};
+ExtensionsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(OrgExtensionConfigs)),
+    __param(2, Inject(ExtensionDisplayNames)),
+    __param(3, Inject(KernelDb))
+], ExtensionsOperations);
+export { ExtensionsOperations };

package/dist/platform/ops/marketplaces.ops.d.ts

@@ -0,0 +1,16 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { MarketplacesService } from "../../catalog/marketplaces.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Marketplace operations of the `Platform` tool (spec §7): the super admin's sources (list, add)
+ * and the org admins' read-only browse of the entries (deployment setting `orgMarketplaceBrowse`),
+ * from which they request an import (`requests.create-import`).
+ */
+export declare class MarketplacesOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly marketplaces;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, marketplaces: MarketplacesService, kdb: KernelDb);
+    onModuleInit(): void;
+}

package/dist/platform/ops/marketplaces.ops.js

@@ -0,0 +1,157 @@
+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 { z } from "zod";
+import { MarketplacesService, } from "../../catalog/marketplaces.service.js";
+import { itemsSeenBy } from "../../catalog/scope-state.js";
+import { ApiError } from "../../errors.js";
+import { readOrgMarketplaceBrowse } from "../../identity/settings.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { asToolError, viaAgent } from "./errors.js";
+import { Cursor, pageOf, startOf } from "./paging.js";
+const PAGE = 50;
+/** A marketplace source as the list shows it: no token, etag or skip list. */
+const source = (m) => ({
+    id: m.id,
+    name: m.name,
+    url: m.url,
+    form: m.form,
+    ref: m.ref,
+    builtin: m.builtin,
+    enabled: m.enabled,
+    disabledByConfig: m.disabledByConfig,
+    lastStatus: m.lastStatus,
+    lastError: m.lastError,
+    lastRefreshedAt: m.lastRefreshedAt,
+    entryCount: m.entryCount,
+});
+/** One marketplace entry (one version of a plugin) as the browse list shows it. */
+const entry = (e) => ({
+    marketplaceId: e.sourceId,
+    marketplace: e.sourceName,
+    name: e.name,
+    version: e.version,
+    displayName: e.displayName,
+    summary: e.summary,
+    format: e.format,
+    compatible: e.compatible,
+    importable: e.importable,
+    ...(e.reason !== undefined && { reason: e.reason }),
+    deprecated: e.deprecated,
+    permissions: e.permissions,
+    importedAs: e.adopted,
+    newerAvailable: e.newerAvailable,
+});
+/**
+ * Marketplace operations of the `Platform` tool (spec §7): the super admin's sources (list, add)
+ * and the org admins' read-only browse of the entries (deployment setting `orgMarketplaceBrowse`),
+ * from which they request an import (`requests.create-import`).
+ */
+let MarketplacesOperations = class MarketplacesOperations {
+    registry;
+    marketplaces;
+    kdb;
+    constructor(registry, marketplaces, kdb) {
+        this.registry = registry;
+        this.marketplaces = marketplaces;
+        this.kdb = kdb;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "marketplaces.list",
+                description: "List the marketplace sources of the platform (super admin): the official one and the custom ones, with whether each is enabled, its last refresh and how many entries it has. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ cursor: Cursor.optional() }).strict(),
+                example: {},
+                authz: { superAdmin: true },
+                mirrors: ["GET /api/v1/admin/marketplaces"],
+                confirm: "read",
+                run: async (input) => pageOf((await this.marketplaces.list()).map(source), startOf(input.cursor), PAGE),
+            }),
+            defineOperation({
+                id: "marketplaces.entries",
+                description: "Browse the plugins the enabled marketplaces offer (org admins, when the platform lets orgs browse): name, version, summary, whether it can be imported and whether it is in the catalog already. Filter by marketplaceId or a search text q. Pages by 50: pass the returned next as params.cursor. To get one imported, use requests.create-import.",
+                input: z
+                    .object({
+                    marketplaceId: z.string().min(1).max(100).optional(),
+                    q: z.string().min(1).max(200).optional(),
+                    cursor: Cursor.optional(),
+                })
+                    .strict(),
+                example: { q: "github" },
+                authz: { orgAction: "catalog.decide" },
+                mirrors: ["GET /api/v1/orgs/:orgId/marketplaces/entries"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "not_found",
+                        next: "The platform does not let orgs browse the marketplaces; ask the super admin.",
+                    },
+                ],
+                run: async (input, ctx) => asToolError(async () => {
+                    if (!(await readOrgMarketplaceBrowse(this.kdb.db))) {
+                        throw new ApiError("not_found", "Marketplace browsing is off for organizations");
+                    }
+                    const r = await this.marketplaces.entries({
+                        ...(input.marketplaceId !== undefined && { marketplaceId: input.marketplaceId }),
+                        ...(input.q !== undefined && { q: input.q }),
+                    });
+                    // as the route: an item the org can neither see nor request reads as not imported
+                    const seen = await itemsSeenBy(this.kdb.db, ctx.orgId, r.items.flatMap((e) => (e.adopted ? [e.adopted.itemId] : [])));
+                    const items = r.items.map((e) => e.adopted === null || seen.has(e.adopted.itemId)
+                        ? e
+                        : { ...e, adopted: null, newerAvailable: false, contentChanged: false });
+                    return pageOf(items.map(entry), startOf(input.cursor), PAGE);
+                }),
+            }),
+            defineOperation({
+                id: "marketplaces.add",
+                description: "Add a custom marketplace source to the platform (super admin): a name and an https URL of a marketplace.json, or a git repository (…/*.git or owner/repo) with an optional ref. Sources that need a token or mirrors are added on the web.",
+                input: z
+                    .object({
+                    name: z.string().min(1).max(100),
+                    url: z.string().min(1).max(2000),
+                    ref: z.string().min(1).max(200).optional(),
+                })
+                    .strict(),
+                example: { name: "Team plugins", url: "https://plugins.example.com/marketplace.json" },
+                authz: { superAdmin: true },
+                mirrors: ["POST /api/v1/admin/marketplaces"],
+                confirm: "platform",
+                errors: [
+                    {
+                        code: "validation_failed",
+                        next: "Fix the name or URL as the message says (https, no user info), then call again.",
+                    },
+                ],
+                summary: (i) => ({
+                    zh: `添加市场源「${i.name}」${i.url}`,
+                    en: `Add marketplace source "${i.name}" ${i.url}`,
+                }),
+                run: async (input, ctx) => asToolError(async () => ({
+                    marketplace: source(await this.marketplaces.add(ctx.actorAccountId, {
+                        name: input.name,
+                        url: input.url,
+                        ...(input.ref !== undefined && { ref: input.ref }),
+                    }, { auditDetail: viaAgent("marketplaces.add", ctx) })),
+                })),
+            }),
+        ]);
+    }
+};
+MarketplacesOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(MarketplacesService)),
+    __param(2, Inject(KernelDb))
+], MarketplacesOperations);
+export { MarketplacesOperations };

package/dist/platform/ops/paging.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/** `params.cursor` of a paged operation: the `next` of the previous page (an opaque string). */
+export declare const Cursor: z.ZodString;
+/** The offset a cursor stands for (0 without one). */
+export declare const startOf: (cursor: string | undefined) => number;
+/**
+ * One page of `items` from `start` (ruling: lists that can exceed 50 entries page themselves):
+ * `next` is the cursor of the following page, null on the last one.
+ */
+export declare function pageOf<T>(items: readonly T[], start: number, size: number): {
+    items: T[];
+    total: number;
+    next: string | null;
+};

package/dist/platform/ops/paging.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+/** `params.cursor` of a paged operation: the `next` of the previous page (an opaque string). */
+export const Cursor = z
+    .string()
+    .regex(/^\d{1,7}$/, "pass the next value of the previous page")
+    .describe("The next value of the previous page; omit for the first page.");
+/** The offset a cursor stands for (0 without one). */
+export const startOf = (cursor) => cursor === undefined ? 0 : Number(cursor);
+/**
+ * One page of `items` from `start` (ruling: lists that can exceed 50 entries page themselves):
+ * `next` is the cursor of the following page, null on the last one.
+ */
+export function pageOf(items, start, size) {
+    const end = start + size;
+    return {
+        items: items.slice(start, end),
+        total: items.length,
+        next: end < items.length ? String(end) : null,
+    };
+}

package/dist/platform/ops/platform.ops.d.ts

@@ -0,0 +1,23 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { AgentsService } from "../../agents/agents.service.js";
+import { OrgSettingsService } from "../../orgs/settings.service.js";
+import { ToolRegistry } from "../../tools/registry.js";
+import { PlatformActor } from "../actor.js";
+import { PlatformOperations } from "../registry.js";
+/** The `platform` domain: orientation, and what this agent is (spec §7). Synthetic, no route. */
+export declare class PlatformOperationsProvider implements OnModuleInit {
+    private readonly registry;
+    private readonly actor;
+    private readonly agents;
+    private readonly settings;
+    private readonly tools;
+    constructor(registry: PlatformOperations, actor: PlatformActor, agents: AgentsService, settings: OrgSettingsService, tools: ToolRegistry);
+    /**
+     * The agent's tools by the keys the model sees: builtins by name, plugin tools as
+     * `plugin__<plugin>__<tool>`, and each connector reference expanded to its live tools'
+     * `mcp__<slug>__<tool>` keys as the registry resolves them for a run; connector tools that
+     * cannot load now are listed with the registry's reason.
+     */
+    private toolKeys;
+    onModuleInit(): void;
+}