@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/agents/definition.d.ts

@@ -1,4 +1,6 @@
+import { type ModelParameter } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+import { type LegacyScope } from "../tools/legacy-keys.js";
 /** 模型引用：供应商插件名 + 模型 id。 */
 export declare const ModelRef: z.ZodObject<{
     provider: z.ZodString;
@@ -33,11 +35,7 @@ export declare const AgentToolRef: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.Zo
     tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
 }, z.core.$strict>], "kind">, unknown>;
 export type AgentToolRef = z.output<typeof AgentToolRef>;
-/**
- * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
- * 只用于创建请求；修改与读出旧版本都不注入默认值。
- */
-export declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
+export { DEFAULT_AGENT_TOOLS } from "../tools/builtin-names.js";
 /** Roster names of inline templates and allowlisted org agents (the template name rule). */
 export declare const SUBAGENT_NAME_RE: RegExp;
 /**
@@ -74,7 +72,7 @@ export declare const InlineAgentTemplate: z.ZodObject<{
 }, z.core.$strict>;
 export type InlineAgentTemplate = z.infer<typeof InlineAgentTemplate>;
 /**
- * Sub-agents this agent may dispatch with the builtin `agent` tool (phase C, spec §5.2). No
+ * Sub-agents this agent may dispatch with the builtin `Agent` tool (phase C, spec §5.2). No
  * default: definitions without it are unchanged and gain no version.
  */
 export declare const SubagentsSchema: z.ZodObject<{
@@ -191,8 +189,41 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
+/** The connectors and extensions a definition's own tool refs name (to read an ambiguous rc key). */
+interface OwnRefs {
+    connectors: ReadonlySet<string>;
+    extensions: ReadonlySet<string>;
+}
+/**
+ * Release-candidate tool keys in a stored definition, read as current keys (tool naming spec
+ * §8.3), the way {@link normalizeToolRef} reads the app -> connector rename: builtin refs in
+ * `tools`, the keys of `toolPolicies`, and the `tools` / `disallowedTools` / `toolPolicies` of a
+ * template, the agent's inline sub-agent templates included. Works on an agent definition and on
+ * an agent template alike. Old builtin names map without `scope`; an rc `<x>__<tool>` key maps
+ * only with one (the org's connector slugs and their ids, the deployment's extension names). When
+ * `x` is both a slug and an extension name, the definition's own tool refs decide; when they
+ * cannot, a policy or a deny list keeps the restriction on both candidate keys (a deny is never
+ * lost) and an allowlist keeps the old key (inert). An unknown key stays as it is. Keys in the
+ * current format are never touched. Returns the same object when nothing changes. Saving never
+ * goes through this: a new definition with an old key is refused (`AgentsService`).
+ */
+export declare function normalizeToolKeys(definition: unknown, scope?: LegacyScope, inherited?: OwnRefs): unknown;
+/**
+ * Does a stored definition or template hold an rc `<x>__<tool>` key, which only a
+ * {@link LegacyScope} can map? (Callers load the scope only then.)
+ */
+export declare function needsLegacyScope(definition: unknown): boolean;
 /**
  * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
- * connector 形（C27）。其余字段原样保留；没有旧形引用时返回原对象。
+ * connector 形（C27），and rc tool keys to current keys ({@link normalizeToolKeys}: builtins
+ * always, `<x>__<tool>` keys with `scope`). Other fields are kept; without old forms the same
+ * object is returned.
  */
-export declare function normalizeStoredDefinition(def: unknown): AgentDefinition;
+export declare function normalizeStoredDefinition(def: unknown, scope?: LegacyScope): AgentDefinition;
+/** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
+export declare function paramIssues(field: string, decl: ModelParameter[], params: Record<string, unknown>): {
+    path: string;
+    message: string;
+}[];
+/** Roster entries an agent may list (spec §4.3), general-purpose included. */
+export declare const SUBAGENT_ROSTER_MAX = 20;

package/dist/agents/definition.js

@@ -1,4 +1,6 @@
+import { validateParams } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+import { isLegacyBuiltinKey, isLegacyPrefixedKey, legacyToolKey, } from "../tools/legacy-keys.js";
 /** 模型引用：供应商插件名 + 模型 id。 */
 export const ModelRef = z.object({ provider: z.string(), model: z.string() });
 /**
@@ -36,14 +38,7 @@ export const AgentToolRef = z.preprocess(normalizeToolRef, z.discriminatedUnion(
     })
         .strict(),
 ]));
-/**
- * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
- * 只用于创建请求；修改与读出旧版本都不注入默认值。
- */
-export const DEFAULT_AGENT_TOOLS = [
-    { kind: "builtin", name: "ask_user" },
-    { kind: "builtin", name: "read_tool_output" },
-];
+export { DEFAULT_AGENT_TOOLS } from "../tools/builtin-names.js";
 /** Roster names of inline templates and allowlisted org agents (the template name rule). */
 export const SUBAGENT_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 /**
@@ -67,7 +62,7 @@ export const InlineAgentTemplate = z
 })
     .strict();
 /**
- * Sub-agents this agent may dispatch with the builtin `agent` tool (phase C, spec §5.2). No
+ * Sub-agents this agent may dispatch with the builtin `Agent` tool (phase C, spec §5.2). No
  * default: definitions without it are unchanged and gain no version.
  */
 export const SubagentsSchema = z
@@ -117,7 +112,7 @@ export const AgentDefinitionSchema = z.object({
      * 技能（M5 T13）：`orgSkills` 是引用的组织技能 id（保存时校验属于本组织且未删除，不可重复）。
      * agent 自己的技能（`scope=agent`）自动对它生效，不进定义。可省略（较早保存的定义也没有），按空处理；
      * 不给默认值：没用技能的定义保存前后不变，不会因此多出一个版本。
-     * `writePolicy`（M6 T27，D10）：私有 agent 的 `skill_write` 是否固定确认，缺省按 `allow`（不写进定义）；
+     * `writePolicy`（M6 T27，D10）：私有 agent 的 `SkillWrite` 是否固定确认，缺省按 `allow`（不写进定义）；
      * 共享 agent 不论取值都走 R3 + R4。
      */
     skills: z
@@ -135,18 +130,207 @@ export const AgentDefinitionSchema = z.object({
     })
         .strict()
         .optional(),
-    /** Sub-agents (phase C); offered only when the builtin `agent` tool is in `tools`. */
+    /** Sub-agents (phase C); offered only when the builtin `Agent` tool is in `tools`. */
     subagents: SubagentsSchema.optional(),
 });
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The connector slugs and extension names `definition`'s `tools` name: connector refs (through
+ * `scope.connectorSlugById`), plugin refs, and current-format keys of a template's `tools`;
+ * `inherited` (the parent agent's, for an inline template) is added.
+ */
+function ownRefs(definition, scope, inherited) {
+    const connectors = new Set(inherited?.connectors);
+    const extensions = new Set(inherited?.extensions);
+    const tools = Array.isArray(definition.tools) ? definition.tools : [];
+    for (const r of tools) {
+        if (typeof r === "string") {
+            const m = /^(mcp|plugin)__([^_].*?)__./.exec(r);
+            if (m)
+                (m[1] === "mcp" ? connectors : extensions).add(m[2]);
+        }
+        else if (isRecord(r) && r.kind === "connector" && typeof r.connectorId === "string") {
+            const slug = scope.connectorSlugById?.get(r.connectorId);
+            if (slug !== undefined)
+                connectors.add(slug);
+        }
+        else if (isRecord(r) && r.kind === "plugin" && typeof r.plugin === "string") {
+            extensions.add(r.plugin);
+        }
+    }
+    return { connectors, extensions };
+}
+/**
+ * The current key(s) of a stored key. A builtin and an unambiguous `<x>__<tool>` map to one key
+ * ({@link legacyToolKey}). When `x` is both a connector slug and an extension name, the
+ * definition's own refs decide (only connector `x` -> `mcp__…`, only extension `x` ->
+ * `plugin__…`); when they name both or neither, both candidates are returned and the caller
+ * decides (a policy keeps a deny / ask on both: it must never be lost). Anything else: as is.
+ */
+function currentKeys(key, scope, own) {
+    const one = legacyToolKey(key, scope);
+    if (one !== null)
+        return [one];
+    if (scope === undefined || !isLegacyPrefixedKey(key))
+        return [key];
+    const head = key.slice(0, key.indexOf("__"));
+    if (!scope.connectorSlugs.has(head) || !scope.extensionNames.has(head))
+        return [key];
+    const c = own?.connectors.has(head) === true;
+    const e = own?.extensions.has(head) === true;
+    if (c && !e)
+        return [`mcp__${key}`];
+    if (e && !c)
+        return [`plugin__${key}`];
+    return [`mcp__${key}`, `plugin__${key}`];
+}
+/**
+ * A list of tool keys (a template's `tools` / `disallowedTools`) in current keys, deduplicated.
+ * A still-ambiguous key becomes both candidates in a deny list (`widen`), and stays as is (inert,
+ * so narrower) in an allowlist.
+ */
+function keyList(v, scope, own, widen) {
+    if (!Array.isArray(v))
+        return v;
+    let changed = false;
+    const out = [];
+    for (const x of v) {
+        let next = [x];
+        if (typeof x === "string") {
+            const keys = currentKeys(x, scope, own);
+            next = keys.length > 1 && !widen ? [x] : keys;
+        }
+        if (next.length !== 1 || next[0] !== x)
+            changed = true;
+        for (const n of next) {
+            if (typeof n === "string" && out.includes(n)) {
+                changed = true;
+                continue;
+            }
+            out.push(n);
+        }
+    }
+    return changed ? out : v;
+}
+/**
+ * `toolPolicies` in current keys; keys that become one keep the stricter policy, and a
+ * still-ambiguous key keeps its `ask` / `deny` on both candidates (anything else is dropped).
+ */
+function policyKeys(v, scope, own) {
+    if (!isRecord(v))
+        return v;
+    const mapped = Object.entries(v).map(([k, p]) => [k, p, currentKeys(k, scope, own)]);
+    if (mapped.every(([k, , keys]) => keys.length === 1 && keys[0] === k))
+        return v;
+    const rank = (p) => (p === "deny" ? 2 : p === "ask" ? 1 : 0);
+    const out = {};
+    for (const [, p, keys] of mapped) {
+        if (keys.length > 1 && rank(p) === 0)
+            continue;
+        for (const next of keys) {
+            if (!Object.hasOwn(out, next) || rank(p) > rank(out[next]))
+                out[next] = p;
+        }
+    }
+    return out;
+}
+/** An agent definition's `tools`: builtin refs by their current names (connector and plugin refs name tools, not keys). */
+function toolRefs(v, scope, own) {
+    if (!Array.isArray(v))
+        return v;
+    // template-shaped (`tools: string[]`): an allowlist
+    if (v.some((x) => typeof x === "string"))
+        return keyList(v, scope, own, false);
+    if (!v.some((r) => isRecord(r) &&
+        r.kind === "builtin" &&
+        typeof r.name === "string" &&
+        isLegacyBuiltinKey(r.name))) {
+        return v;
+    }
+    return v.map((r) => isRecord(r) && r.kind === "builtin" && typeof r.name === "string"
+        ? { ...r, name: legacyToolKey(r.name) ?? r.name }
+        : r);
+}
+/**
+ * Release-candidate tool keys in a stored definition, read as current keys (tool naming spec
+ * §8.3), the way {@link normalizeToolRef} reads the app -> connector rename: builtin refs in
+ * `tools`, the keys of `toolPolicies`, and the `tools` / `disallowedTools` / `toolPolicies` of a
+ * template, the agent's inline sub-agent templates included. Works on an agent definition and on
+ * an agent template alike. Old builtin names map without `scope`; an rc `<x>__<tool>` key maps
+ * only with one (the org's connector slugs and their ids, the deployment's extension names). When
+ * `x` is both a slug and an extension name, the definition's own tool refs decide; when they
+ * cannot, a policy or a deny list keeps the restriction on both candidate keys (a deny is never
+ * lost) and an allowlist keeps the old key (inert). An unknown key stays as it is. Keys in the
+ * current format are never touched. Returns the same object when nothing changes. Saving never
+ * goes through this: a new definition with an old key is refused (`AgentsService`).
+ */
+export function normalizeToolKeys(definition, scope, inherited) {
+    if (!isRecord(definition))
+        return definition;
+    const own = scope === undefined ? undefined : ownRefs(definition, scope, inherited);
+    const next = { ...definition };
+    let changed = false;
+    const put = (field, value) => {
+        if (value === definition[field])
+            return;
+        next[field] = value;
+        changed = true;
+    };
+    if ("tools" in definition)
+        put("tools", toolRefs(definition.tools, scope, own));
+    if ("disallowedTools" in definition) {
+        put("disallowedTools", keyList(definition.disallowedTools, scope, own, true));
+    }
+    if ("toolPolicies" in definition) {
+        put("toolPolicies", policyKeys(definition.toolPolicies, scope, own));
+    }
+    const sub = definition.subagents;
+    if (isRecord(sub) && Array.isArray(sub.inline)) {
+        const inline = sub.inline.map((t) => normalizeToolKeys(t, scope, own));
+        if (inline.some((t, i) => t !== sub.inline[i])) {
+            put("subagents", { ...sub, inline });
+        }
+    }
+    return changed ? next : definition;
+}
+/**
+ * Does a stored definition or template hold an rc `<x>__<tool>` key, which only a
+ * {@link LegacyScope} can map? (Callers load the scope only then.)
+ */
+export function needsLegacyScope(definition) {
+    if (!isRecord(definition))
+        return false;
+    const lists = [definition.tools, definition.disallowedTools];
+    for (const l of lists) {
+        if (Array.isArray(l) && l.some((x) => typeof x === "string" && isLegacyPrefixedKey(x))) {
+            return true;
+        }
+    }
+    if (isRecord(definition.toolPolicies)) {
+        if (Object.keys(definition.toolPolicies).some(isLegacyPrefixedKey))
+            return true;
+    }
+    const sub = definition.subagents;
+    return isRecord(sub) && Array.isArray(sub.inline) && sub.inline.some(needsLegacyScope);
+}
 /**
  * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
- * connector 形（C27）。其余字段原样保留；没有旧形引用时返回原对象。
+ * connector 形（C27），and rc tool keys to current keys ({@link normalizeToolKeys}: builtins
+ * always, `<x>__<tool>` keys with `scope`). Other fields are kept; without old forms the same
+ * object is returned.
  */
-export function normalizeStoredDefinition(def) {
-    const d = def;
+export function normalizeStoredDefinition(def, scope) {
+    let d = def;
     const tools = d.tools;
-    if (!Array.isArray(tools) || !tools.some((t) => t?.kind === "app")) {
-        return d;
+    if (Array.isArray(tools) && tools.some((t) => t?.kind === "app")) {
+        d = { ...d, tools: tools.map(normalizeToolRef) };
     }
-    return { ...d, tools: tools.map(normalizeToolRef) };
+    return normalizeToolKeys(d, scope);
+}
+/** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
+export function paramIssues(field, decl, params) {
+    const r = validateParams(decl, params);
+    return r.ok ? [] : r.issues.map((i) => ({ path: `${field}.${i.key}`, message: i.message }));
 }
+/** Roster entries an agent may list (spec §4.3), general-purpose included. */
+export const SUBAGENT_ROSTER_MAX = 20;

package/dist/agents/models.controller.d.ts

@@ -1,5 +1,5 @@
 import type { ModelInfo } from "@capybara-hq/plugin-sdk";
-import type { ProviderRegistry } from "../runtime/providers.js";
+import { ProviderRegistry } from "../runtime/providers.js";
 /** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
 export declare class ModelsController {
     private readonly registry;

package/dist/agents/models.controller.js

@@ -8,8 +8,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, Inject } from "@nestjs/common";
-import { PROVIDER_REGISTRY } from "../http/tokens.js";
 import { OrgAction } from "../orgs/org.guard.js";
+import { ProviderRegistry } from "../runtime/providers.js";
 /** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
 let ModelsController = class ModelsController {
     registry;
@@ -26,6 +26,6 @@ __decorate([
 ], ModelsController.prototype, "list", null);
 ModelsController = __decorate([
     Controller("api/v1/orgs/:orgId/models"),
-    __param(0, Inject(PROVIDER_REGISTRY))
+    __param(0, Inject(ProviderRegistry))
 ], ModelsController);
 export { ModelsController };

package/dist/agents/templates.controller.d.ts

@@ -1,5 +1,5 @@
 import { type OrgContext } from "../orgs/org.guard.js";
-import type { AgentTemplatesService, AgentTemplateView } from "./templates.js";
+import { AgentTemplatesService, type AgentTemplateView } from "./templates.js";
 /**
  * The org's agent templates installed from plugins (`/api/v1/orgs/:orgId/agent-templates`, phase C
  * spec §17): the agent page lists them to select as sub-agents. Read with `agents.create`, the

package/dist/agents/templates.controller.js

@@ -8,8 +8,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, Inject } from "@nestjs/common";
-import { AGENT_TEMPLATES } from "../http/tokens.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { AgentTemplatesService } from "./templates.js";
 /**
  * The org's agent templates installed from plugins (`/api/v1/orgs/:orgId/agent-templates`, phase C
  * spec §17): the agent page lists them to select as sub-agents. Read with `agents.create`, the
@@ -32,6 +32,6 @@ __decorate([
 ], AgentTemplatesController.prototype, "list", null);
 AgentTemplatesController = __decorate([
     Controller("api/v1/orgs/:orgId/agent-templates"),
-    __param(0, Inject(AGENT_TEMPLATES))
+    __param(0, Inject(AgentTemplatesService))
 ], AgentTemplatesController);
 export { AgentTemplatesController };

package/dist/agents/templates.d.ts

@@ -1,7 +1,6 @@
 import type { AgentTemplate, AgentTemplateTier } from "@capybara-hq/plugin-sdk";
-import type { Transaction } from "kysely";
-import type { KernelDatabase, KernelDb, SourceFormat } from "../db/kernel-schema.js";
-type Trx = Transaction<KernelDatabase>;
+import type { KernelSchemaDb, SourceFormat } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 /**
  * Agent templates installed in an org from plugins (sub-agents spec §16): `agent_templates` (one
  * live row per org, plugin and name) and `agent_template_versions` (the parsed template). Plugin
@@ -35,7 +34,7 @@ export interface TemplateRow {
     catalogVersion: string | null;
 }
 /** The live templates of `ids` in the org (deleted and foreign ids are left out), by id. */
-export declare function loadTemplates(db: KernelDb | Trx, orgId: string, ids: readonly string[]): Promise<Map<string, TemplateRow>>;
+export declare function loadTemplates(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Map<string, TemplateRow>>;
 /** Reads the org's agent templates (consumed by the roster, the agent page and Task 19's API). */
 export declare class AgentTemplatesService {
     private readonly db;
@@ -63,7 +62,7 @@ export interface TemplateSource {
  * caller holds the org row lock): a new template (version 1, `created`), a new version of the live
  * one when its definition differs (`changed`, the version added), or nothing when it is equal.
  */
-export declare function putTemplateVersionIn(t: Trx, s: TemplateSource, template: AgentTemplate): Promise<{
+export declare function putTemplateVersionIn(t: KernelSchemaDb, s: TemplateSource, template: AgentTemplate): Promise<{
     id: string;
     version: number;
     created: boolean;
@@ -74,10 +73,9 @@ export declare function putTemplateVersionIn(t: Trx, s: TemplateSource, template
  * rolled back): the version row goes and the template is back at the version before. Returns
  * whether anything changed.
  */
-export declare function revertTemplateVersionIn(t: Trx, orgId: string, id: string, version: number): Promise<boolean>;
+export declare function revertTemplateVersionIn(t: KernelSchemaDb, orgId: string, id: string, version: number): Promise<boolean>;
 /**
  * Removes a template (soft delete: sub-agents already started keep their frozen definition, and
  * the roster skips it). Returns whether it was live.
  */
-export declare function softDeleteTemplateIn(t: Trx, orgId: string, id: string): Promise<boolean>;
-export {};
+export declare function softDeleteTemplateIn(t: KernelSchemaDb, orgId: string, id: string): Promise<boolean>;

package/dist/agents/templates.js

@@ -1,5 +1,18 @@
+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 { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { loadLegacyScope } from "../tools/legacy-data.js";
 import { canonicalJson } from "../tools/registry.js";
+import { needsLegacyScope, normalizeToolKeys } from "./definition.js";
 const baseQuery = (db, orgId) => db
     .selectFrom("agent_templates as t")
     .innerJoin("agent_template_versions as v", (j) => j.onRef("v.template_id", "=", "t.id").onRef("v.version", "=", "t.current_version"))
@@ -15,16 +28,27 @@ const baseQuery = (db, orgId) => db
 ])
     .where("t.org_id", "=", orgId)
     .where("t.deleted_at", "is", null);
-const rowOf = (r) => ({
+/**
+ * A stored template row; its tool keys read as current keys (tool naming spec §8.3): old builtin
+ * names always, rc `<x>__<tool>` keys with `scope` (see {@link scopedRows}).
+ */
+const rowOf = (r, scope) => ({
     id: r.id,
     name: r.name,
     plugin: r.plugin_name,
     version: r.current_version,
-    template: r.definition,
+    template: normalizeToolKeys(r.definition, scope),
     sourceFormat: r.source_format,
     catalogItemId: r.catalog_item_id,
     catalogVersion: r.catalog_version,
 });
+/** The rows of one org as {@link TemplateRow}s, reading the org's legacy scope once when needed. */
+async function scopedRows(db, orgId, rows) {
+    const scope = rows.some((r) => needsLegacyScope(r.definition))
+        ? await loadLegacyScope(db, orgId)
+        : undefined;
+    return rows.map((r) => rowOf(r, scope));
+}
 /** The live templates of `ids` in the org (deleted and foreign ids are left out), by id. */
 export async function loadTemplates(db, orgId, ids) {
     if (ids.length === 0)
@@ -32,17 +56,17 @@ export async function loadTemplates(db, orgId, ids) {
     const rows = await baseQuery(db, orgId)
         .where("t.id", "in", [...ids])
         .execute();
-    return new Map(rows.map((r) => [r.id, rowOf(r)]));
+    return new Map((await scopedRows(db, orgId, rows)).map((t) => [t.id, t]));
 }
 /** Reads the org's agent templates (consumed by the roster, the agent page and Task 19's API). */
-export class AgentTemplatesService {
+let AgentTemplatesService = class AgentTemplatesService {
     db;
     constructor(db) {
         this.db = db;
     }
     /** Every live template of the org, by plugin then name. */
     async listForOrg(orgId) {
-        const rows = await baseQuery(this.db, orgId)
+        const rows = await baseQuery(this.db.db, orgId)
             .orderBy("t.plugin_name")
             .orderBy("t.name")
             .execute();
@@ -65,7 +89,7 @@ export class AgentTemplatesService {
     /** A live template by id or by `<plugin>:<name>`; null when there is none. */
     async resolve(orgId, ref) {
         const i = ref.indexOf(":");
-        let q = baseQuery(this.db, orgId);
+        let q = baseQuery(this.db.db, orgId);
         q =
             i < 0
                 ? q.where("t.id", "=", ref)
@@ -73,10 +97,17 @@ export class AgentTemplatesService {
         const r = await q.executeTakeFirst();
         if (!r)
             return null;
-        const t = rowOf(r);
+        const [t] = await scopedRows(this.db.db, orgId, [r]);
+        if (!t)
+            return null;
         return { id: t.id, version: t.version, plugin: t.plugin, template: t.template };
     }
-}
+};
+AgentTemplatesService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], AgentTemplatesService);
+export { AgentTemplatesService };
 /**
  * Writes `template` as the org's live template `<plugin>:<name>` in the caller's transaction (the
  * caller holds the org row lock): a new template (version 1, `created`), a new version of the live

package/dist/app.d.ts

@@ -0,0 +1,93 @@
+import "reflect-metadata";
+import type { BootstrapManifest } from "@capybara-hq/plugin-sdk";
+import type { INestApplicationContext } from "@nestjs/common";
+import type { NestFastifyApplication } from "@nestjs/platform-fastify";
+import type { ConfigSource } from "./config/load.js";
+import type { KernelConfig } from "./config/schema.js";
+import type { ConfigSourceKind } from "./config/sources.js";
+import { type KernelHttp } from "./http/app.js";
+import { type ShutdownSignalOptions } from "./infra/lifecycle/shutdown-signals.js";
+import type { KernelLogger } from "./log.js";
+import type { KernelOverride } from "./overrides.js";
+/** What {@link createKernelApp} takes besides the config. */
+export interface KernelAppOptions {
+    /** 配置来源；提供 `watch` 时启用热更新。 */
+    source?: ConfigSource;
+    /** 解析插件裸包名的目录，默认 `process.cwd()`；相对路径按当前 cwd 解析。 */
+    resolveFrom?: string;
+    /** Defaults to a logger built from `config.log` and `config.roles` (createConfiguredLogger). */
+    logger?: KernelLogger;
+    /** 热更新时与来源原始值合并的环境变量，默认 `process.env`。 */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The bootstrap step (package ecosystem spec §7, startup bootstrap spec). When given, the start
+     * runs it (see `extensions/bootstrap.ts`) before loading extensions unless it is already done for
+     * the manifest, and refuses to start when it cannot complete a required entry. `dir`: the
+     * optional offline directory whose `*.tgz` files are matched to the entries by sha512 (a missing
+     * directory is an empty one); entries without a matching file are downloaded from
+     * `packages.npmRegistry`. Omitted: no bootstrap step (tests, unless they ask for it).
+     */
+    bootstrap?: {
+        dir?: string;
+    };
+    /** The bootstrap manifest; default the `bootstrap.json` shipped with the kernel package. */
+    bootstrapManifest?: BootstrapManifest;
+    /**
+     * Where each extension deployment config field of the startup config comes from (the
+     * `extensionConfigSources` returned by `loadConfigWithSources`); these fields are read-only in the
+     * admin console (D8). When omitted it is derived from `config.extensionConfig`: fields present in
+     * the environment are `env`, the rest take the `CAPYBARA_CONFIG_SOURCE` kind (file / nacos).
+     */
+    extensionConfigSources?: Record<string, Record<string, ConfigSourceKind>>;
+    /**
+     * The kernel's own tests' seams: values for the named seam tokens ({@link KernelOverride} lists
+     * every one), registered in a global module so the domain modules that resolve these optional
+     * tokens get them. Any other token is refused when the application is built.
+     */
+    overrides?: readonly KernelOverride[];
+}
+/**
+ * Builds the kernel application (one Nest application, root module {@link KernelModule}) and sets
+ * up its HTTP side, without initializing it: nothing connects and nothing starts. A failure
+ * releases what was created (Redis connections, the pool) before it is thrown. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start; everything else uses {@link createKernelApp}.
+ */
+export declare function buildKernelApp(config: KernelConfig, options?: KernelAppOptions): Promise<NestFastifyApplication>;
+/**
+ * Closes a kernel application once (later calls get the same promise): the stop phases begin at
+ * once (`KernelLifecycle.stop`: readiness 503, the start aborted at its next checkpoint), next to
+ * `app.close()`, which runs the shutdown hooks (the stop phases are the same promise, then Redis
+ * and the pool). Use it to stop an application from {@link createKernelApp} /
+ * {@link startKernelApp} (tests, `@capybara-hq/testing`), so the stop begins before Nest's
+ * `onModuleDestroy` hooks run.
+ */
+export declare function closeKernelApp(app: NestFastifyApplication): Promise<void>;
+/**
+ * Creates the kernel application and runs its start sequence (nest kernel spec §4): Redis,
+ * migrations, the official marketplace, the bootstrap step, the extension load, the role parts,
+ * extension routes, the lifecycle reconcile and the config watch. Does not listen and installs no
+ * process-wide handler.
+ */
+export declare function createKernelApp(config: KernelConfig, options?: KernelAppOptions): Promise<NestFastifyApplication>;
+/**
+ * Builds the kernel application, installs the SIGTERM / SIGINT handlers
+ * ({@link handleShutdownSignals}), runs the start sequence and listens on `config.http.port`:
+ * nothing is served before the start sequence finished. The handlers are installed before the
+ * start, so a signal during it aborts the start at its next checkpoint and closes the application
+ * cleanly; this function then rejects once the signal path has exited (with 0). A second signal
+ * exits with 1 at once. A failed build or start is logged (`kernel start failed`) before it is
+ * thrown.
+ */
+export declare function startKernelApp(config: KernelConfig, options?: KernelAppOptions, signalOptions?: ShutdownSignalOptions): Promise<NestFastifyApplication>;
+/**
+ * The start half of {@link startKernelApp} for an application from {@link buildKernelApp}: installs
+ * the signal handlers, runs the start sequence and listens on `config.http.port`. Internal (not
+ * exported from the package): {@link startKernelApp} and the kernel's own tests that need the
+ * application before its start.
+ */
+export declare function startBuiltKernelApp(app: NestFastifyApplication, config: KernelConfig, signalOptions?: ShutdownSignalOptions): Promise<void>;
+/** The in-process HTTP of a kernel application (`inject`, the route list). */
+export declare function kernelAppHttp(app: INestApplicationContext): KernelHttp;
+/** The port a kernel application listens on; undefined before it listens and after the stop. */
+export declare function kernelAppPort(app: INestApplicationContext): number | undefined;