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

package/dist/agents/from-template.service.d.ts

@@ -0,0 +1,60 @@
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { ModelPurposesService } from "../models/purposes.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService, type AgentView, type AgentVisibility } from "./agents.service.js";
+import type { ModelRef } from "./definition.js";
+import { type ModelSource, type PlanItem } from "./from-template.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
+import type { ProfileInput } from "./profile.js";
+/** The preview of creating an agent from a template (`POST …/agents/from-template/preview`). */
+export interface TemplatePreview {
+    items: PlanItem[];
+    /** The automatic choice the dialog preselects (P4-4); null when the org has no usable model. */
+    model: (ModelRef & {
+        source: ModelSource;
+    }) | null;
+    dropped: string[];
+    previewHash: string;
+}
+export interface CreateFromTemplateRequest {
+    templateId: string;
+    name: string;
+    visibility?: AgentVisibility;
+    members?: string[];
+    model?: ModelRef;
+    avatar?: ProfileInput["avatar"];
+    previewHash: string;
+}
+/**
+ * Creating agents from templates (rulings P4-3…P4-8): the preview and the create both resolve the
+ * template with {@link planFromTemplate}; the create refuses a plan whose hash differs from the
+ * preview's (409 `agent.template_preview_stale`: the base part, and the automatic model's part when
+ * no model is chosen), writes the agent through
+ * {@link AgentsService.createFromTemplate}, and after the commit opens the pending connector request
+ * when the creator cannot configure connectors.
+ */
+export declare class AgentsFromTemplate {
+    private readonly db;
+    private readonly agents;
+    /** Extension tools loaded here and the org's enabled extensions. */
+    private readonly host;
+    private readonly providers;
+    /** The tier's purpose mapping (`subagent_<tier>`, P4-4). */
+    private readonly purposes;
+    private readonly requests;
+    private readonly log;
+    constructor(db: KernelDb, agents: AgentsService, 
+    /** Extension tools loaded here and the org's enabled extensions. */
+    host: Pick<ExtensionHost, "tools" | "enabledPlugins">, providers: Pick<ProviderRegistry, "resolve" | "list">, 
+    /** The tier's purpose mapping (`subagent_<tier>`, P4-4). */
+    purposes: Pick<ModelPurposesService, "resolve">, requests: PendingConnectorRequests, log: Pick<KernelLogger, "warn">);
+    /** The template, when usable in the org (P4-3); otherwise 404 `component.not_found`. */
+    private template;
+    private plan;
+    preview(orgId: string, templateId: string): Promise<TemplatePreview>;
+    create(orgId: string, actorAccountId: string, req: CreateFromTemplateRequest, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<{
+        agent: AgentView;
+    }>;
+}

package/dist/agents/from-template.service.js

@@ -0,0 +1,161 @@
+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 { ExtensionHost } from "../extensions/host.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ModelPurposesService } from "../models/purposes.js";
+import { can } from "../orgs/roles.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService } from "./agents.service.js";
+import { planFromTemplate, } from "./from-template.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
+import { loadTemplates } from "./templates.js";
+/**
+ * Creating agents from templates (rulings P4-3…P4-8): the preview and the create both resolve the
+ * template with {@link planFromTemplate}; the create refuses a plan whose hash differs from the
+ * preview's (409 `agent.template_preview_stale`: the base part, and the automatic model's part when
+ * no model is chosen), writes the agent through
+ * {@link AgentsService.createFromTemplate}, and after the commit opens the pending connector request
+ * when the creator cannot configure connectors.
+ */
+let AgentsFromTemplate = class AgentsFromTemplate {
+    db;
+    agents;
+    host;
+    providers;
+    purposes;
+    requests;
+    log;
+    constructor(db, agents, 
+    /** Extension tools loaded here and the org's enabled extensions. */
+    host, providers, 
+    /** The tier's purpose mapping (`subagent_<tier>`, P4-4). */
+    purposes, requests, log) {
+        this.db = db;
+        this.agents = agents;
+        this.host = host;
+        this.providers = providers;
+        this.purposes = purposes;
+        this.requests = requests;
+        this.log = log;
+    }
+    /** The template, when usable in the org (P4-3); otherwise 404 `component.not_found`. */
+    async template(orgId, templateId) {
+        const row = (await loadTemplates(this.db.db, orgId, [templateId])).get(templateId);
+        if (!row) {
+            throw new ApiError("component.not_found", "The agent template does not exist or is not available in this organization");
+        }
+        return row;
+    }
+    async plan(orgId, row, model) {
+        const opts = {
+            pluginTools: this.host.tools().map((t) => ({ plugin: t.plugin, name: t.spec.name })),
+            enabledPlugins: await this.host.enabledPlugins(orgId),
+            resolveModel: async (ref) => {
+                try {
+                    return (await this.providers.resolve(ref)).info.parameters;
+                }
+                catch {
+                    return null;
+                }
+            },
+            purpose: async (purpose) => {
+                try {
+                    return await this.purposes.resolve(orgId, purpose);
+                }
+                catch (e) {
+                    if (e instanceof ApiError)
+                        return null;
+                    throw e;
+                }
+            },
+            defaultModel: async () => {
+                for (const p of await this.providers.list()) {
+                    const m = p.models[0];
+                    if (m)
+                        return { provider: p.provider, model: m.id };
+                }
+                return null;
+            },
+            ...(model !== undefined && { model }),
+        };
+        return planFromTemplate(this.db.db, orgId, row, opts);
+    }
+    async preview(orgId, templateId) {
+        const plan = await this.plan(orgId, await this.template(orgId, templateId));
+        return {
+            items: plan.items,
+            model: plan.auto === null ? null : { ...plan.auto.ref, source: plan.auto.source },
+            dropped: plan.dropped,
+            previewHash: plan.hash,
+        };
+    }
+    async create(orgId, actorAccountId, req, actorTokenId, auditDetail) {
+        const row = await this.template(orgId, req.templateId);
+        const plan = await this.plan(orgId, row, req.model);
+        // the base part always; the automatic model's part only when the person chose none, so a
+        // silently changed choice is stale while an explicit one never is
+        const [base, auto] = req.previewHash.split(".");
+        if (base !== plan.baseHash || (req.model === undefined && auto !== plan.modelHash)) {
+            throw new ApiError("agent.template_preview_stale", "The template or the organization changed since the preview; preview it again");
+        }
+        if (plan.model === null) {
+            throw new ApiError("agent.model_unavailable", "No model is available for the new agent");
+        }
+        const { agent, role } = await this.agents.createFromTemplate(orgId, actorAccountId, {
+            definition: {
+                ...plan.definition,
+                name: req.name,
+                model: plan.model.ref,
+                modelParams: plan.model.params,
+            },
+            visibility: req.visibility ?? "private",
+            ...(req.members !== undefined && { memberIds: req.members }),
+            profile: {
+                description: plan.profile.description,
+                quickActions: plan.profile.quickActions,
+                ...(req.avatar != null && { avatar: req.avatar }),
+            },
+        }, { id: req.templateId, version: row.version, name: row.name }, actorTokenId, auditDetail);
+        const keys = (agent.definition.pendingConnectors ?? []).map((c) => c.key);
+        if (keys.length > 0 && !can(role, "connectors.manage")) {
+            try {
+                await this.requests.openFor({
+                    orgId,
+                    agentId: agent.id,
+                    ownerAccountId: agent.ownerAccountId,
+                    keys,
+                });
+            }
+            catch (err) {
+                // the agent stands; its 待配置 notice offers the request again (ruling P4-7)
+                this.log.warn("cannot open the pending connector request of a new agent", {
+                    orgId,
+                    agentId: agent.id,
+                    err,
+                });
+            }
+        }
+        return { agent };
+    }
+};
+AgentsFromTemplate = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AgentsService)),
+    __param(2, Inject(ExtensionHost)),
+    __param(3, Inject(ProviderRegistry)),
+    __param(4, Inject(ModelPurposesService)),
+    __param(5, Inject(PendingConnectorRequests)),
+    __param(6, Inject(KERNEL_LOGGER))
+], AgentsFromTemplate);
+export { AgentsFromTemplate };

package/dist/agents/org-templates.d.ts

@@ -0,0 +1,176 @@
+import { type AgentTemplate } from "@capybara-hq/plugin-sdk";
+import { type Owner } from "../catalog/ownership.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { AgentLookup, type AgentView } from "./agent-lookup.js";
+import { type AgentTemplateView } from "./templates.js";
+/** A template with its definition, as `GET orgs/:orgId/agent-templates/:id` answers. */
+export interface AgentTemplateDetail extends AgentTemplateView {
+    /** The current definition (the served version). */
+    definition: AgentTemplate;
+    /** Who owns it: the platform, or the org that created it (P3-14's shape). */
+    owner: Owner;
+    /**
+     * The org's own template (an org template, promoted or not; rulings P3-6, P4-12): its admins
+     * edit, delete and set 可共享 on it. Always false for a plugin's template.
+     */
+    owned: boolean;
+    /** 可共享 (only meaningful when `owned`). */
+    shareable: boolean;
+    /** Shared already: the platform row it was promoted to on share (ruling P3-3). */
+    promoted: boolean;
+    /**
+     * In the org's usable set (agents can be created from it here). False only when the owner reads
+     * its own template while it is not usable in its org (a promoted one switched off there).
+     */
+    usable: boolean;
+}
+/**
+ * What 另存为模板 left out (ruling P4-10), listed to the person: `kind` names the part of the
+ * agent, `name` the item (roster name, skill or connector name), `id` its id when it has one, and
+ * `reason`:
+ * - `org_agent`: an allowlisted org agent in the roster (an agent, not a template);
+ * - `unavailable`: a skill, sub-agent template or connector the org can no longer use;
+ * - `agent_skill`: one of the agent's own skills (not in the org library, so no other agent could
+ *   resolve it);
+ * - `no_endpoint`: a hand-configured connector without a URL to record (an inline OpenAPI document);
+ * - `unsupported_protocol`: a hand-configured connector of a kind other than MCP or OpenAPI;
+ * - `limit`: past a template limit (connectors 16, sub-agent types and inline 16, tools 200, a
+ *   connector entry's tools and policy keys 200 together: kind `tool_policy`, `name` the tool,
+ *   `id` the connector);
+ * - `connector_tool`: a policy on a tool of a connector the template does not carry (kind
+ *   `tool_policy`, `name` its key; carried connectors take their policies in `policies`), or a
+ *   connector tool key in an inline sub-agent's allowlist (kind `subagent_inline`,
+ *   `field: "tools"`, `name` the sub-agent): connector keys embed this org's connector slug;
+ * - `unsupported_field`: a field of an inline sub-agent a template's inline entry cannot hold
+ *   (kind `subagent_inline`, `field`: `disallowedTools`, `toolPolicies`, `effort` or `maxSteps`);
+ * - `model_param`: a model parameter other than a valid `effort` (kind `model_param`, `name` its
+ *   key): a template records only the effort (P4-10);
+ * - `fallback`: the fallback model and its parameters (kind `fallback_model`, `name`
+ *   `provider/model`): a template has no fallback;
+ * - `empty_text`: whitespace-only text a template requires (kind `subagent_inline` with `field`
+ *   `description` or `instructions`: the sub-agent is left out; kind `quick_action`, `name` its
+ *   title: the quick action is left out).
+ * An inline sub-agent's skills that are the agent's own (`agent_skill`), gone (`unavailable`) or
+ * past the 3 a template holds (`limit`) are listed as kind `skill`.
+ */
+export interface SaveAsOmission {
+    kind: "subagent_agent" | "subagent_template" | "subagent_inline" | "skill" | "connector" | "tool" | "tool_policy" | "model_param" | "fallback_model" | "quick_action";
+    name: string;
+    id?: string;
+    /** The field of an inline sub-agent left out (`connector_tool`, `unsupported_field`). */
+    field?: string;
+    reason: "org_agent" | "unavailable" | "agent_skill" | "no_endpoint" | "unsupported_protocol" | "limit" | "connector_tool" | "unsupported_field" | "model_param" | "fallback" | "empty_text";
+}
+/**
+ * Roster names no template may take (ruling T4-R15): `general-purpose`, always the roster's first
+ * entry. Claude Code's other built-in types (`Explore`, `Plan`) are capitalized, which the
+ * template name rule already refuses.
+ */
+export declare const RESERVED_TEMPLATE_NAMES: ReadonlySet<string>;
+/**
+ * A connector's URL as a template may record it (ruling P4-11): userinfo, query and fragment
+ * removed (they may carry credentials). Null when it is no absolute http(s) URL.
+ */
+export declare function sanitizeEndpoint(raw: string): string | null;
+/**
+ * Validates a template definition the way an `agents/<name>.md` file is (the SDK parser, so the
+ * two never drift): the definition minus `instructions` as the frontmatter (JSON is YAML), then
+ * the instructions as the body. Problems -> 400 `validation_failed` naming each.
+ */
+export declare function parseTemplateDefinition(definition: Record<string, unknown>): AgentTemplate;
+/**
+ * Ruling P4-11 on an edit: a `connectors[].needs.endpoint` that carries userinfo, a query or a
+ * fragment, or is no http(s) URL of at most 2048 characters, is refused with 400
+ * `validation_failed` naming the field and what it carries (an edit is never stripped silently).
+ * One that differs only by normalization (a trailing slash, the host's case) is accepted:
+ * returns the template with each such endpoint in its canonical {@link sanitizeEndpoint} form.
+ */
+export declare function canonicalEndpoints(template: AgentTemplate): AgentTemplate;
+/**
+ * The template an agent is saved as (rulings P4-10, P4-11), with what was left out. Pure reads of
+ * the org's state through `db`.
+ */
+export declare function templateFromAgent(db: KernelSchemaDb, orgId: string, agent: AgentView, meta: {
+    name: string;
+    description: string;
+}): Promise<{
+    template: AgentTemplate;
+    omitted: SaveAsOmission[];
+}>;
+/**
+ * The org's agent templates beyond the plugin ones (rulings P4-9 to P4-12): 另存为模板, the detail
+ * of a usable template and the owner's new versions. Writes run under the org row lock, with
+ * `agents.manage` re-checked there.
+ */
+export declare class OrgAgentTemplates {
+    private readonly kdb;
+    private readonly orgLock;
+    private readonly agents;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, orgLock: Pick<OrgLock, "lockAndAuthorize">, agents: Pick<AgentLookup, "view">, txHost: TransactionHost);
+    private get db();
+    /**
+     * 另存为模板 (ruling P4-9): the org's live agent `agentId` (any one: an org admin may edit every
+     * agent of the org) saved as the org template `name` (version 1, `plugin_name` null), mapped
+     * by {@link templateFromAgent}. The bare name must be free in the org (rule 10): a usable
+     * template of that type, one of the org's own rows of that name, or a live platform template
+     * the org created under that name -> 409 `agent_template.name_taken` naming its owner (details
+     * `[{ owner, templateId }]`). Audits `agent_template.created`.
+     */
+    saveAs(orgId: string, actor: string, agentId: string, meta: {
+        name: string;
+        description: string;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<{
+        template: AgentTemplateDetail;
+        omitted: SaveAsOmission[];
+    }>;
+    /**
+     * Rule 10 for a new org template named `name` (a bare type): refused for a reserved roster name
+     * (details `[{ reserved: true }]`), and while the org's usable set has that type, the org has a
+     * live row of that name without a plugin (an unusable copy too: the live-name index), a
+     * plugin-less platform template of that name is offered to the org (ruling P2-3's alignment),
+     * or the platform has a live template the org created under that name (promotion would clash).
+     */
+    private assertNameFree;
+    /**
+     * A template usable in the org by id ({@link loadTemplates}: an org row, a linked copy, a
+     * platform template on in the org), or the org's own template whatever its switch, with its
+     * definition, owner and the org's flags. Otherwise -> 404 `component.not_found`.
+     */
+    detail(orgId: string, id: string): Promise<AgentTemplateDetail>;
+    /**
+     * A new version of the org's own template `id` (ruling P4-12; `agents.manage` re-checked under
+     * the org row lock): `definition` is validated like a template file and keeps its name;
+     * `expectedVersion` must be the version the editor read (else 409
+     * `agent_template.version_conflict`). An unshared template gets a new version of its org row; a
+     * promoted one a new version of its platform row (ruling P3-4), which the org row then serves
+     * (ruling P3-43), and the orgs using it are told (`shared_item_updated`). An unchanged
+     * definition writes nothing. Not the org's own -> 409 `catalog.not_owned`; missing -> 404.
+     * Agents created earlier are never touched. Audits `agent_template.updated`.
+     */
+    update(orgId: string, actor: string, id: string, body: {
+        definition: Record<string, unknown>;
+        expectedVersion: number;
+    }, actorTokenId?: string): Promise<AgentTemplateDetail>;
+    /**
+     * The org's own template `id` ({@link readOwnTemplate}, the predicate `OwnedItems` shares), or
+     * undefined: another org's, a plugin's, or a copy of a platform template it does not own.
+     */
+    private ownRow;
+    /**
+     * What the org's own template serves, read directly (its usable-set entry is missing while the
+     * org switched its promoted template off): the platform row's current version when it is newer
+     * than the org row's (ruling P3-43), else the org row's.
+     */
+    private ownServed;
+    /** 409 `catalog.not_owned` for a template the org has but does not own, else 404. */
+    private notOwnedOrMissing;
+    /**
+     * The owner of a usable template the org does not own itself: a platform template's (or a
+     * linked copy's) `owner_org_id`, a plugin template's catalog item owner, else the platform.
+     */
+    private ownerOfRow;
+}