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

package/dist/agents/definition.js

@@ -1,5 +1,8 @@
 import { validateParams } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+import { isRemovedBuiltinKey } from "../tools/builtin-names.js";
+import { isLegacyBuiltinKey, isLegacyPrefixedKey, legacyToolKey, } from "../tools/legacy-keys.js";
+import { InstructionFilesSchema } from "./instruction-files.js";
 /** 模型引用：供应商插件名 + 模型 id。 */
 export const ModelRef = z.object({ provider: z.string(), model: z.string() });
 /**
@@ -8,43 +11,74 @@ export const ModelRef = z.object({ provider: z.string(), model: z.string() });
  */
 export const ModelParams = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
 /**
- * 改名前（D17）保存的连接器引用 `{ kind: "app", appId, tools }` 规范化为 `{ kind: "connector", connectorId, tools }`
- * （C27：已存 agent 版本不改写，读入时规范化；新保存只写 connector 形）。其余值原样返回。
+ * A tool an agent turns off (tools default-on spec §2): agents have every builtin, every tool of
+ * the extensions enabled in the org and every tool of the org's connectors, minus these. A builtin
+ * by name; an extension's or a connector's tools by name, or `"all"` to turn it off as a unit
+ * (tools it gains later included). Connectors by id, so a renamed connector stays off.
  */
-export function normalizeToolRef(v) {
-    if (typeof v !== "object" || v === null || Array.isArray(v))
-        return v;
-    const r = v;
-    if (r.kind !== "app")
-        return v;
-    const { kind: _kind, appId, ...rest } = r;
-    return { kind: "connector", connectorId: appId, ...rest };
-}
-/**
- * agent 定义里对工具的引用：内置工具按名字；插件工具按插件名 + 工具名；连接器工具按连接器 id，
- * `tools: "all"` = 该连接器当前所有启用的工具。旧形 `{ kind: "app", appId }` 仍可解析（见 {@link normalizeToolRef}）。
- */
-export const AgentToolRef = z.preprocess(normalizeToolRef, z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("builtin"), name: z.string().min(1) }).strict(),
+export const DisabledToolRef = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("builtin"), name: z.string().min(1).max(200) }).strict(),
     z
-        .object({ kind: z.literal("plugin"), plugin: z.string().min(1), name: z.string().min(1) })
+        .object({
+        kind: z.literal("plugin"),
+        plugin: z.string().min(1).max(200),
+        tools: z.union([z.literal("all"), z.array(z.string().min(1).max(256)).min(1).max(500)]),
+    })
         .strict(),
     z
         .object({
         kind: z.literal("connector"),
-        connectorId: z.string().min(1),
-        tools: z.union([z.literal("all"), z.array(z.string().min(1)).min(1)]),
+        connectorId: z.string().min(1).max(100),
+        tools: z.union([z.literal("all"), z.array(z.string().min(1).max(256)).min(1).max(500)]),
     })
         .strict(),
-]));
+]);
+/** Is builtin `name` turned off by `disabled`? */
+export const builtinDisabled = (disabled, name) => (disabled ?? []).some((r) => r.kind === "builtin" && r.name === name);
+/** Is tool `name` of extension `plugin` turned off by `disabled`? */
+export const extensionToolDisabled = (disabled, plugin, name) => (disabled ?? []).some((r) => r.kind === "plugin" && r.plugin === plugin && (r.tools === "all" || r.tools.includes(name)));
+/** Is tool `name` of connector `connectorId` turned off by `disabled`? */
+export const connectorToolDisabled = (disabled, connectorId, name) => (disabled ?? []).some((r) => r.kind === "connector" &&
+    r.connectorId === connectorId &&
+    (r.tools === "all" || r.tools.includes(name)));
+/**
+ * `disabled` in its canonical form: one entry per builtin, extension and connector (in first-seen
+ * order), names deduplicated and sorted, `"all"` absorbing names. Saving stores this form, so two
+ * lists that turn off the same tools compare equal.
+ */
+export function canonicalDisabledTools(disabled) {
+    const out = [];
+    const merge = (cur, add) => cur === "all" || add === "all" ? "all" : [...new Set([...cur, ...add])].sort();
+    for (const r of disabled) {
+        if (r.kind === "builtin") {
+            if (!builtinDisabled(out, r.name))
+                out.push({ kind: "builtin", name: r.name });
+            continue;
+        }
+        const prev = out.find((x) => x.kind === r.kind &&
+            (r.kind === "plugin"
+                ? x.plugin === r.plugin
+                : x.connectorId === r.connectorId));
+        if (prev)
+            prev.tools = merge(prev.tools, r.tools);
+        else
+            out.push({ ...r, tools: r.tools === "all" ? "all" : [...new Set(r.tools)].sort() });
+    }
+    return out;
+}
 /**
- * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
- * 只用于创建请求；修改与读出旧版本都不注入默认值。
+ * A sub-agent's tool filter by tool key (tools default-on spec §4): written only into a child's
+ * effective definition at dispatch (never accepted on save). `deny` removes keys (the child-removed
+ * tools, `Agent` at the depth limit, a template's `disallowedTools`); `allow`, when set, keeps only
+ * its keys (a template's `tools` allowlist). Registry-managed tools (`Skill`, `ToolSearch`,
+ * `SendMessage`, `SubagentHandback`) are not filtered.
  */
-export const DEFAULT_AGENT_TOOLS = [
-    { kind: "builtin", name: "ask_user" },
-    { kind: "builtin", name: "read_tool_output" },
-];
+export const SubagentToolsSchema = z
+    .object({
+    allow: z.array(z.string().min(1).max(300)).max(500).optional(),
+    deny: z.array(z.string().min(1).max(300)).max(500).optional(),
+})
+    .strict();
 /** 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}$/;
 /**
@@ -68,7 +102,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
@@ -96,30 +130,99 @@ export const SubagentsSchema = z
     dispatchable: z.boolean().optional(),
 })
     .strict();
+/** The key rule of a pending connector (`[a-z0-9-]`, URL-safe: it names the bind route). */
+export const PENDING_CONNECTOR_KEY_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Pending connectors an agent may carry (the template's `connectors` limit). */
+export const PENDING_CONNECTORS_MAX = 16;
+/**
+ * A connector the template the agent was created from needs and the org has not bound yet
+ * (ruling P4-6): `source.template` is the platform connector template's id, `source.needs` a
+ * hand-configured connector described by protocol, endpoint and tools (P4-11). `tools` are the
+ * tool names to enable once bound (absent = all of a template's tools), `policies` the template's
+ * tightened policies by tool name, applied by the bind. Never model-visible: tools are built from
+ * `tools` only, and a pending connector has none. Text limits are twice the template's (which
+ * counts code points) so any parsed template fits (this schema counts UTF-16 units).
+ */
+const PendingToolName = z.string().min(1).max(256);
+export const PendingConnectorSchema = z
+    .object({
+    key: z.string().regex(PENDING_CONNECTOR_KEY_RE),
+    label: z.string().min(1).max(160),
+    source: z.union([
+        z.object({ template: z.string().min(1).max(100) }).strict(),
+        z
+            .object({
+            needs: z
+                .object({
+                protocol: z.enum(["mcp", "openapi"]),
+                endpoint: z.string().min(1).max(4096),
+                tools: z.array(PendingToolName).max(200),
+                label: z.string().min(1).max(160),
+            })
+                .strict(),
+        })
+            .strict(),
+    ]),
+    tools: z.array(PendingToolName).max(200).optional(),
+    policies: z
+        .record(PendingToolName, z.enum(["ask", "deny"]))
+        .refine((p) => Object.keys(p).length <= 200, "at most 200 policies")
+        .optional(),
+})
+    .strict();
 /** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
 export const AgentDefinitionSchema = z.object({
     name: z.string().min(1).max(80),
+    /**
+     * What the agent is for, one short paragraph (run context spec §3.5): shown on the agent's
+     * cards (copied to `agents.profile_description`) and given to the model in the run context. No
+     * default: older versions are unchanged and gain no version. A save without it keeps the
+     * current version's; `""` removes it.
+     */
+    description: z.string().max(500).optional(),
     avatarUrl: z.url().nullable().default(null),
+    /**
+     * The model-visible system prompt. Derived on save from `instructionFiles` when they are given
+     * (`deriveInstructions`); every reader (build.ts, the sub-agent copy, evals, replay) reads this.
+     */
     instructions: z.string().max(100_000).default(""),
+    /**
+     * The prompt files, the authoring form of `instructions` (spec 2026-11-04 §3.3). No default:
+     * definitions without it (every older version) read as one `AGENTS.md` and gain no version.
+     */
+    instructionFiles: InstructionFilesSchema.optional(),
     model: ModelRef,
     fallback: ModelRef.nullable().default(null),
     /** 主模型的参数（按主模型的声明校验）。 */
     modelParams: ModelParams.default({}),
     /** 兜底模型自己的参数（按兜底模型的声明校验）；兜底尝试只用这一份。 */
     fallbackParams: ModelParams.default({}),
-    /** 引用的工具（M2 保存的 `tools: []` 仍然合法）；保存时校验引用存在，运行时由注册表解析。 */
-    tools: z.array(AgentToolRef).default([]),
     /**
-     * 按工具 key 收紧策略（只能收紧：`ask` / `deny`，不接受 `allow`）；键必须是该 agent 引用的工具的 key。
-     * 较早保存的定义没有该字段，按空处理。
+     * The tools this agent turns off (tools default-on spec §2); everything else the org offers is
+     * on. Saved in canonical form ({@link canonicalDisabledTools}); checked on save.
+     */
+    disabledTools: z.array(DisabledToolRef).max(500).default([]),
+    /**
+     * A sub-agent's key filter, set only on a child's effective definition at dispatch (see
+     * {@link SubagentToolsSchema}); a save that carries it is refused.
+     */
+    subagentTools: SubagentToolsSchema.optional(),
+    /**
+     * Policies by tool key; keys are tools the agent could have (on or turned off). `ask` / `deny`
+     * tighten any tool. `allow` is accepted only on a connector tool key and counts only for a
+     * personal-credential connector's tool (decision 2026-11-09): it overrides the org default and
+     * the member's own 询问, never the org's or the member's 禁止 (`tools/policy.ts`
+     * `connectorPolicy`); on any other tool it changes nothing. Older definitions without it read as
+     * empty.
      */
-    toolPolicies: z.record(z.string(), z.enum(["ask", "deny"])).default({}),
+    toolPolicies: z.record(z.string(), z.enum(["allow", "ask", "deny"])).default({}),
     /**
      * 技能（M5 T13）：`orgSkills` 是引用的组织技能 id（保存时校验属于本组织且未删除，不可重复）。
      * agent 自己的技能（`scope=agent`）自动对它生效，不进定义。可省略（较早保存的定义也没有），按空处理；
      * 不给默认值：没用技能的定义保存前后不变，不会因此多出一个版本。
-     * `writePolicy`（M6 T27，D10）：私有 agent 的 `skill_write` 是否固定确认，缺省按 `allow`（不写进定义）；
-     * 共享 agent 不论取值都走 R3 + R4。
+     * `writePolicy`: whether registering a skill on a private agent (`agents.register-skill`) needs
+     * the person's confirmation; absent means `allow` (not stored in the definition). On a shared
+     * agent a registration is always confirmed at the org level.
      */
     skills: z
         .object({
@@ -136,20 +239,263 @@ 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 unless the builtin `Agent` tool is turned off. */
     subagents: SubagentsSchema.optional(),
+    /**
+     * Connectors still to configure (ruling P4-6), written only by creating from a template. No
+     * default: definitions without it are unchanged. Model-invisible.
+     */
+    pendingConnectors: z.array(PendingConnectorSchema).max(PENDING_CONNECTORS_MAX).optional(),
 });
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The connector slugs and extension names `definition` names: connector refs (through
+ * `scope.connectorSlugById`) and plugin refs of a frozen definition's `tools` or of
+ * `disabledTools`, 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 : []),
+        ...(Array.isArray(definition.disabledTools) ? definition.disabledTools : []),
+    ];
+    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}`];
+}
 /**
- * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
- * connector 形（C27）。其余字段原样保留；没有旧形引用时返回原对象。
+ * 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.
  */
-export function normalizeStoredDefinition(def) {
-    const d = def;
+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;
+}
+/**
+ * A definition's `tools`: a template's allowlist of keys, or the refs of a definition frozen into
+ * history before tools were on by default (builtin refs by their current names).
+ */
+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;
+}
+/**
+ * `definition` without the `toolPolicies` keys (its own and its inline sub-agents') of builtins
+ * that no longer exist ({@link isRemovedBuiltinKey}): applied to a definition being saved, so a
+ * key left over from a removed builtin never blocks the save. Returns the same object when
+ * nothing is dropped.
+ */
+export function withoutRemovedBuiltinPolicies(definition) {
+    const strip = (p) => {
+        if (p === undefined || !Object.keys(p).some(isRemovedBuiltinKey))
+            return p;
+        return Object.fromEntries(Object.entries(p).filter(([k]) => !isRemovedBuiltinKey(k)));
+    };
+    let next = definition;
+    const policies = strip(definition.toolPolicies);
+    if (policies !== definition.toolPolicies)
+        next = { ...next, toolPolicies: policies };
+    const inline = definition.subagents?.inline;
+    if (inline !== undefined) {
+        const stripped = inline.map((t) => {
+            const p = strip(t.toolPolicies);
+            return p === t.toolPolicies ? t : { ...t, toolPolicies: p };
+        });
+        if (stripped.some((t, i) => t !== inline[i])) {
+            next = { ...next, subagents: { ...definition.subagents, inline: stripped } };
+        }
+    }
+    return next;
+}
+/**
+ * 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);
+}
+/**
+ * A tool ref of a definition frozen into history (logs, eval case snapshots) before tools were on
+ * by default (tools default-on spec §2): `{ kind: "app", appId }` (before D17) reads as a
+ * connector ref. Other values are returned as they are.
+ */
+function normalizeToolRef(v) {
+    if (!isRecord(v) || v.kind !== "app")
+        return v;
+    const { kind: _kind, appId, ...rest } = v;
+    return { kind: "connector", connectorId: appId, ...rest };
+}
+/**
+ * A definition read from the database or from history (not parsed by zod): rc tool keys read as
+ * current keys ({@link normalizeToolKeys}: builtins always, `<x>__<tool>` keys with `scope`), and
+ * a definition from before tools were on by default (an enabled `tools` list, history only: the
+ * migration rewrote stored versions) reads as nothing turned off, which is what the migration
+ * writes (tools default-on spec §2, §3). Other fields are kept; without old forms the same object
+ * is returned.
+ */
+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) => isRecord(t) && t.kind === "app")) {
+        d = { ...d, tools: tools.map(normalizeToolRef) };
+    }
+    d = normalizeToolKeys(d, scope);
+    if ("tools" in d) {
+        const { tools: _enabled, ...rest } = d;
+        d = { ...rest, disabledTools: Array.isArray(d.disabledTools) ? d.disabledTools : [] };
+    }
+    else if (!Array.isArray(d.disabledTools)) {
+        d = { ...d, disabledTools: [] };
     }
-    return { ...d, tools: tools.map(normalizeToolRef) };
+    return d;
 }
 /** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
 export function paramIssues(field, decl, params) {

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

@@ -0,0 +1,106 @@
+import { type ModelParameter } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { type ModelParams, type ModelRef } from "./definition.js";
+import { type AgentDefinitionInput } from "./instruction-files.js";
+import { type QuickAction } from "./profile.js";
+import { type TemplateRow } from "./templates.js";
+/** What the preview lists (P4-5): 带入 / 待配置 / 不可用. */
+export type PlanItemState = "carried" | "pending" | "unavailable";
+export type PlanItemKind = "instruction_file" | "description" | "quick_action" | "tool" | "skill" | "connector" | "subagent";
+/**
+ * One line of the preview. `reason` (a code) says why an item is pending or unavailable, and
+ * qualifies some carried ones:
+ * - instruction_file: unavailable `invalid_name`, `duplicate`, `too_many`, `too_long` (the joined
+ *   files exceed the agent's limit);
+ * - tool (the template's `tools` allowlist): `subagents` (`Agent` kept on because the template
+ *   describes sub-agents, though its allowlist leaves it out); unavailable `plugin_unavailable`
+ *   (its plugin is not enabled in the org or not loaded), `unknown_tool`, `connector_key` (a
+ *   connector tool key: connectors carry over only through `connectors` entries);
+ * - skill: `pinned`, `not_pinned_manual_only`, `not_pinned_too_large`, `subagent` (named only by an
+ *   inline sub-agent); unavailable `not_found`;
+ * - connector: `several` (the first of several connectors made from the template was bound);
+ *   pending `no_connector`, `tools_missing` (the connector made from the template lacks every
+ *   named tool), `needs`; unavailable `template_not_found` (also for a template the org may not
+ *   see, named by the entry's reference only), `disallowed` (`disallowedTools` left none of its
+ *   tools), `invalid_endpoint` (a `needs` endpoint that is no http(s) URL);
+ * - subagent: unavailable `type_not_found`, `type_taken`, `too_many`.
+ */
+export interface PlanItem {
+    kind: PlanItemKind;
+    name: string;
+    state: PlanItemState;
+    reason?: string;
+}
+/** Where the chosen model comes from (P4-4). */
+export type ModelSource = "modelRef" | "tier" | "default" | "chosen";
+export interface PlannedModel {
+    ref: ModelRef;
+    params: ModelParams;
+    source: ModelSource;
+}
+/** The template's agent definition, without its model (chosen separately, P4-4). */
+export type PlannedDefinition = Omit<AgentDefinitionInput, "model" | "modelParams">;
+export interface TemplatePlan {
+    definition: PlannedDefinition;
+    /** The profile's description and quick actions. */
+    profile: {
+        description: string;
+        quickActions: QuickAction[];
+    };
+    /** The model the new agent gets (`opts.model` when given); null when the org has none. */
+    model: PlannedModel | null;
+    /** The automatic choice (P4-4), whatever `opts.model` is; what the dialog preselects. */
+    auto: PlannedModel | null;
+    items: PlanItem[];
+    /**
+     * What has no place in the agent or was cut to its limits: `maxSteps`, `effort` when the model
+     * does not declare it, `description` / `instructions` / `quickActions.<i>.title|body` /
+     * `instructionFiles.<i>.content` / `subagents.inline.<name>.description|instructions` when cut to
+     * the kernel's limits (UTF-16 units), `subagents.inline.<name>.tools.<key>` for a key the agent
+     * does not have, `connectors.<key>.tools.<name>` / `connectors.<key>.policies.<name>` for a tool
+     * the bound connector does not offer.
+     */
+    dropped: string[];
+    /** sha256 of the template id and version and everything resolved except the model. */
+    baseHash: string;
+    /** The first 16 hex digits of sha256 of the automatic model choice (ref and params). */
+    modelHash: string;
+    /** The preview hash: `<baseHash>.<modelHash>`. */
+    hash: string;
+}
+export interface PlanOptions {
+    /** Extension tools loaded on this replica (`ExtensionHost.tools()`). */
+    pluginTools: readonly {
+        plugin: string;
+        name: string;
+    }[];
+    /** Extensions enabled in the org. */
+    enabledPlugins: ReadonlySet<string>;
+    /** The model's parameter declarations, or null when the deployment cannot use it. */
+    resolveModel(ref: ModelRef): Promise<ModelParameter[] | null>;
+    /** The org's target of a model purpose, or null when unmapped. */
+    purpose(purpose: string): Promise<{
+        model: ModelRef;
+        params: ModelParams;
+    } | null>;
+    /**
+     * The org's default chat model. There is no such setting today: the first model of the first
+     * provider listed, as the agent form preselects (ruling P4-T3-2).
+     */
+    defaultModel(): Promise<ModelRef | null>;
+    /** The model the person chose (the automatic choice keeps its params when it is the same). */
+    model?: ModelRef;
+}
+/**
+ * `s` cut to `max` UTF-16 units (what the kernel's zod schemas count), never splitting a
+ * surrogate pair.
+ */
+export declare function cutUtf16(s: string, max: number): string;
+/** The pending connector key of the template's `connectors[i]` (stable per entry). */
+export declare const pendingKeyOf: (i: number) => string;
+/**
+ * Resolves what `row`'s template carries into a new agent of `orgId` (P4-4, P4-5, P4-6). Never
+ * throws for the org's state: what does not resolve is listed and left out, and text is cut to
+ * the kernel's limits; the result is checked against the agent and profile schemas.
+ */
+export declare function planFromTemplate(db: KernelSchemaDb, orgId: string, row: TemplateRow, opts: PlanOptions): Promise<TemplatePlan>;