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

package/dist/agents/definition.d.ts

@@ -1,5 +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;
@@ -13,32 +14,48 @@ export type ModelRef = z.infer<typeof ModelRef>;
 export declare const ModelParams: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
 export type ModelParams = z.infer<typeof ModelParams>;
 /**
- * 改名前（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 declare function normalizeToolRef(v: unknown): unknown;
-/**
- * agent 定义里对工具的引用：内置工具按名字；插件工具按插件名 + 工具名；连接器工具按连接器 id，
- * `tools: "all"` = 该连接器当前所有启用的工具。旧形 `{ kind: "app", appId }` 仍可解析（见 {@link normalizeToolRef}）。
- */
-export declare const AgentToolRef: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const DisabledToolRef: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"builtin">;
     name: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"plugin">;
     plugin: z.ZodString;
-    name: z.ZodString;
+    tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"connector">;
     connectorId: z.ZodString;
     tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
-}, z.core.$strict>], "kind">, unknown>;
-export type AgentToolRef = z.output<typeof AgentToolRef>;
+}, z.core.$strict>], "kind">;
+export type DisabledToolRef = z.output<typeof DisabledToolRef>;
+/** Is builtin `name` turned off by `disabled`? */
+export declare const builtinDisabled: (disabled: readonly DisabledToolRef[] | undefined, name: string) => boolean;
+/** Is tool `name` of extension `plugin` turned off by `disabled`? */
+export declare const extensionToolDisabled: (disabled: readonly DisabledToolRef[] | undefined, plugin: string, name: string) => boolean;
+/** Is tool `name` of connector `connectorId` turned off by `disabled`? */
+export declare const connectorToolDisabled: (disabled: readonly DisabledToolRef[] | undefined, connectorId: string, name: string) => boolean;
 /**
- * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
- * 只用于创建请求；修改与读出旧版本都不注入默认值。
+ * `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 declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
+export declare function canonicalDisabledTools(disabled: readonly DisabledToolRef[]): DisabledToolRef[];
+/**
+ * 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 declare const SubagentToolsSchema: z.ZodObject<{
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type SubagentTools = z.infer<typeof SubagentToolsSchema>;
 /** Roster names of inline templates and allowlisted org agents (the template name rule). */
 export declare const SUBAGENT_NAME_RE: RegExp;
 /**
@@ -75,7 +92,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<{
@@ -115,11 +132,43 @@ export declare const SubagentsSchema: z.ZodObject<{
     dispatchable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type Subagents = z.infer<typeof SubagentsSchema>;
+/** The key rule of a pending connector (`[a-z0-9-]`, URL-safe: it names the bind route). */
+export declare const PENDING_CONNECTOR_KEY_RE: RegExp;
+/** Pending connectors an agent may carry (the template's `connectors` limit). */
+export declare const PENDING_CONNECTORS_MAX = 16;
+export declare const PendingConnectorSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        template: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        needs: z.ZodObject<{
+            protocol: z.ZodEnum<{
+                mcp: "mcp";
+                openapi: "openapi";
+            }>;
+            endpoint: z.ZodString;
+            tools: z.ZodArray<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    policies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        ask: "ask";
+        deny: "deny";
+    }>>>;
+}, z.core.$strict>;
+export type PendingConnector = z.infer<typeof PendingConnectorSchema>;
 /** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
 export declare const AgentDefinitionSchema: z.ZodObject<{
     name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
     avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
     instructions: z.ZodDefault<z.ZodString>;
+    instructionFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strict>>>;
     model: z.ZodObject<{
         provider: z.ZodString;
         model: z.ZodString;
@@ -130,19 +179,24 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     modelParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     fallbackParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
-    tools: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    disabledTools: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"builtin">;
         name: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
         plugin: z.ZodString;
-        name: z.ZodString;
+        tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
     }, z.core.$strict>, z.ZodObject<{
         kind: z.ZodLiteral<"connector">;
         connectorId: z.ZodString;
         tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
-    }, z.core.$strict>], "kind">, unknown>>>;
+    }, z.core.$strict>], "kind">>>;
+    subagentTools: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     toolPolicies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        allow: "allow";
         ask: "ask";
         deny: "deny";
     }>>>;
@@ -190,13 +244,79 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         dispatchable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    pendingConnectors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        source: z.ZodUnion<readonly [z.ZodObject<{
+            template: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            needs: z.ZodObject<{
+                protocol: z.ZodEnum<{
+                    mcp: "mcp";
+                    openapi: "openapi";
+                }>;
+                endpoint: z.ZodString;
+                tools: z.ZodArray<z.ZodString>;
+                label: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>]>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        policies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            ask: "ask";
+            deny: "deny";
+        }>>>;
+    }, 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;
+/** The fields {@link withoutRemovedBuiltinPolicies} reads. */
+interface AgentDefinitionLike {
+    toolPolicies?: Record<string, string> | undefined;
+    subagents?: {
+        inline?: readonly {
+            toolPolicies?: Record<string, string> | undefined;
+        }[] | undefined;
+    } | undefined;
+}
+/**
+ * `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 declare function withoutRemovedBuiltinPolicies<T extends AgentDefinitionLike>(definition: T): T;
+/**
+ * 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）。其余字段原样保留；没有旧形引用时返回原对象。
+ * 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 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;
@@ -204,3 +324,4 @@ export declare function paramIssues(field: string, decl: ModelParameter[], param
 }[];
 /** Roster entries an agent may list (spec §4.3), general-purpose included. */
 export declare const SUBAGENT_ROSTER_MAX = 20;
+export {};