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

package/dist/tools/registry.d.ts

@@ -1,27 +1,37 @@
-import type { Connector, InputRequired, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
-import type { AgentDefinition } from "../agents/definition.js";
+import type { Connector, HookParentScope, InputRequired, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
+import { type AgentDefinition, type DisabledToolRef, type SubagentTools } from "../agents/definition.js";
 import type { ToolView } from "../conversations/events.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import type { OrgRole } from "../orgs/roles.js";
+import type { ConversationKindForHooks } from "../runtime/hook-calls.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
+export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
 export { canonicalJson } from "./canonical-json.js";
 /**
- * 内核内置工具的名字（Task 10 / Task 19 实现；M5 T8 加沙箱工具）。保存 agent 时内置工具引用按这份清单校验，
- * 不依赖当前是否已注册，避免实现落地顺序影响已保存的定义；运行时未注册的照常报不可用。
- * `skill_write`（M5 T15）由 agent 定义显式引用才可用（负责人决定 agent 能否改自己的技能）。
+ * What a tool's `unavailable` is asked with: the org, and for a run's listing the root
+ * conversation (`conversationId`; the sandbox tools follow its device, ruling R8), whether
+ * the run is an eval replay (`replay`: its tool calls are never executed), and a `memo` shared by
+ * the tools of one listing (one answer per question per listing).
  */
-export declare const BUILTIN_TOOL_NAMES: readonly ["ask_user", "read_tool_output", "tool_search", "skill_load", "skill_write", "sandbox_bash", "sandbox_read", "sandbox_write", "sandbox_edit", "sandbox_glob", "sandbox_grep", "sandbox_deliver", "agent"];
-/** 保存 agent 时引用校验的问题（`path` 为 `tools.<i>`）。 */
+export interface ToolListingScope {
+    orgId: string;
+    conversationId?: string;
+    replay?: boolean;
+    memo?: Map<string, unknown>;
+}
+/** A problem of a saved definition's `disabledTools` (`path` is `disabledTools.<i>`). */
 export interface ToolRefIssue {
     path: string;
     message: string;
 }
 /**
  * 内置工具处理函数的上下文：在 SDK 的 `ToolCallContext` 之上，管线额外传入本步解析出的工具
- * （`tool_search` 据此搜索）。插件处理函数收到的仍是 `ToolCallContext`。
+ * （`ToolSearch` 据此搜索）。插件处理函数收到的仍是 `ToolCallContext`。
  */
 export interface BuiltinCallContext extends ToolCallContext {
     tools?: readonly ResolvedTool[];
@@ -33,13 +43,31 @@ export interface BuiltinCallContext extends ToolCallContext {
      */
     runDeadline?: number;
     /**
-     * The conversation whose sandbox this call uses (sub-agents spec §10.1): the parent conversation
-     * for a sub-agent's call, the conversation itself otherwise (the default when absent).
+     * The conversation whose sandbox this call uses (sub-agents spec §10.1, agent map spec §6): the
+     * root conversation for a sub-agent's call at any depth, the conversation itself otherwise (the
+     * default when absent).
      */
     sandboxConversationId?: string;
+    /** The parent run of a sub-agent's run (absent for a top-level run). */
+    parentRunId?: string;
+    /**
+     * A sub-agent's run: the tree's budget window of this run (`SubagentParent.budgetRunId`), which
+     * a builtin's own model call (the `WebFetch` extraction) counts its tokens on.
+     */
+    budgetRunId?: string;
+    /**
+     * The rest of the run's hook scope, for a builtin that makes a model call of its own (the
+     * `WebFetch` extraction fires `model.request` / `model.response`): the step of the call, the
+     * agent version of the run, the conversation kind (hooks fire for `chat` and `subagent` only)
+     * and, for a sub-agent, where it was dispatched from.
+     */
+    step?: number;
+    agentVersion?: number;
+    conversationKind?: ConversationKindForHooks;
+    parent?: HookParentScope;
 }
 /**
- * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`tool_search` 加载的工具 key，
+ * 内置工具的结果：`ToolResult` 之外可带 `loadedTools`（`ToolSearch` 加载的工具 key，
  * 管线写进 `tool_result.loadedTools`）。
  */
 export type BuiltinResult = (ToolResult & {
@@ -52,7 +80,7 @@ export type BuiltinResult = (ToolResult & {
 }) | InputRequired;
 /** 内置工具的处理函数（插件的 `ToolHandler` 可直接赋给它）。 */
 export type BuiltinHandler = (input: unknown, ctx: BuiltinCallContext) => Promise<BuiltinResult>;
-/** 内核内置工具（`ask_user` 等，Task 10 实现具体工具）；key 就是 `spec.name`。 */
+/** 内核内置工具（`AskUserQuestion` 等，Task 10 实现具体工具）；key 就是 `spec.name`。 */
 export interface BuiltinTool {
     spec: ToolSpec;
     defaultPolicy: "allow" | "ask";
@@ -63,25 +91,59 @@ export interface BuiltinTool {
     timeoutMs?: (input: unknown) => number;
     /** 结果转存阈值（字符）：与 `tools.outputSpillChars` 取小者。缺省只用配置。 */
     spillChars?: number;
-    /** 本部署当前不可用时返回事实原因（英文、可执行，进「工具不可用」提醒）；可用返回 null。 */
-    unavailable?: () => string | null;
+    /**
+     * The factual reason this tool is unavailable for the org right now (English, actionable; it goes
+     * into the "tool unavailable" reminder), or null when it is available. May be async (e.g. a
+     * per-org extension-point default). See {@link ToolListingScope} for what a listing passes.
+     */
+    unavailable?: (ctx: ToolListingScope) => Promise<string | null> | string | null;
+    /**
+     * A policy key derived from the validated input (Platform tool spec §6.2), or null to use the
+     * tool key. With a key, agent and parent policies, grants and approvals are keyed by it (an
+     * agent's policy on the tool key still applies on top); the model-visible key stays the tool key.
+     * May be async (the `Platform` tool reads the actor's facts); it never throws for bad input:
+     * an input that cannot run is a `deny` with a `denyReason`.
+     */
+    callPolicy?: CallPolicyFn;
+}
+/** Where a call happens, for {@link BuiltinTool.callPolicy}: the runtime's context, never input. */
+export interface CallPolicyContext {
+    orgId: string;
+    /** The run's trigger account. */
+    accountId: string;
+    agentId: string;
+    conversationId: string;
+    /** Null outside a run (a builtin called directly). */
+    runId: string | null;
+    /**
+     * The call's input as the model sent it, before `{"$output": id}` references were resolved
+     * (the approval card shows this form). Absent outside the pipeline.
+     */
+    rawInput?: unknown;
+    /** The run's abort signal (a precheck stops with it). Absent outside the pipeline. */
+    signal?: AbortSignal;
+}
+/** {@link BuiltinTool.callPolicy}. */
+export type CallPolicyFn = (input: unknown, ctx: CallPolicyContext) => CallPolicy | null | Promise<CallPolicy | null>;
+/** What {@link BuiltinTool.callPolicy} returns for one call. */
+export interface CallPolicy {
+    /** The policy key, e.g. `Platform:skills.create`. */
+    key: string;
+    /** The default for this call (it replaces the tool's `defaultPolicy`). */
+    policy: ToolPolicy;
+    /**
+     * False: always confirm, only "once": the approval offers only "once" and remembered grants
+     * never apply.
+     */
+    remember: boolean;
+    /** The bilingual summary shown on the approval (rendered by the kernel, never by the model). */
+    summary?: {
+        zh: string;
+        en: string;
+    };
+    /** With `policy: "deny"`: the actionable English reason returned as the tool error. */
+    denyReason?: string;
 }
-/**
- * agent 定义里对工具的引用（Task 6 在 `AgentDefinitionSchema` 中落地同形的 zod schema）。
- * 连接器工具按连接器 id 引用，`tools: "all"` = 该连接器当前所有启用的工具。
- */
-export type AgentToolRef = {
-    kind: "builtin";
-    name: string;
-} | {
-    kind: "plugin";
-    plugin: string;
-    name: string;
-} | {
-    kind: "connector";
-    connectorId: string;
-    tools: "all" | readonly string[];
-};
 export type ToolPolicy = "allow" | "ask" | "deny";
 export interface ResolvedTool {
     /** 模型可见名。 */
@@ -115,8 +177,10 @@ export interface ResolvedTool {
      * （推给持有该角色的人）。M3 的内置与连接器工具都不设。
      */
     requiredRole?: OrgRole;
+    /** A builtin's per-call policy key (see {@link BuiltinTool.callPolicy}). */
+    callPolicy?: CallPolicyFn;
 }
-/** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`docs__search`、`docs__*`），否则 `app:<id>`。 */
+/** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`mcp__docs__search`、`mcp__docs__*`），否则 `app:<id>`。 */
 export interface UnavailableTool {
     ref: string;
     reason: string;
@@ -143,32 +207,35 @@ export interface AgentTools {
     tools: ResolvedTool[];
     unavailable: UnavailableTool[];
     /**
-     * `tools: "all"` 引用的连接器里未启用的工具（待复核 / 停用 / 已消失）及事实原因。不进 `unavailable`
-     * （那会让每步都写「工具不可用」提醒），只在模型点名调用时用来给事实说明（spec 6.3）。缺省视为空。
+     * Tools the agent would have that cannot be offered now, with the facts (a builtin with no
+     * sandbox, an extension that needs config or a tool the org switched off, a connector tool off,
+     * pending review or gone). Not in `unavailable` (that would remind the model every step of tools
+     * it never asked for, tools default-on spec §4); used only to explain a call the model makes by
+     * name (spec 6.3). Absent = empty.
      */
     hidden?: UnavailableTool[];
     /**
-     * 本步是否启用 `tool_search`（spec 5.5）：启用时 `tools` 末尾含 `tool_search`，构建请求时只放内置工具
+     * 本步是否启用 `ToolSearch`（spec 5.5）：启用时 `tools` 末尾含 `ToolSearch`，构建请求时只放内置工具
      * 与已加载工具的完整定义，其余进目录。缺省视为未启用。
      */
     toolSearch?: boolean;
 }
 /**
- * Tool registry: resolves the references in an agent definition into the tools available for this
- * run. Not cached (reads PG and the host live every time), so changes take effect right away across
- * replicas.
+ * Tool registry: resolves what an agent has for this run (tools default-on spec §4): everything
+ * the org offers minus the definition's `disabledTools`. Not cached (reads PG and the host live
+ * every time), so changes take effect right away across replicas.
  *
- * Availability:
- * - builtin: in `builtins`;
- * - extension tools: the extension is loaded and registered the tool, and this org enabled the
- *   extension (`extension_org_configs.enabled`, spec 2.2 "installed at deployment level, enabled at
- *   org level"; required bootstrap plugins are enabled in every org, `enabled.ts`);
- * - connector tools: the connector belongs to this org, is not deleted or disabled, the connector is
- *   installed, the tool status is `enabled` and the key is valid.
- *   `tools: "all"` takes only enabled tools; disabled / pending-review ones count as deliberately
- *   turned off by an admin and are not reported; named tools report their reason one by one.
- * Only the first of a key is kept; the same source referenced twice is deduplicated silently,
- * different sources with the same key report a duplicate.
+ * What is offered:
+ * - builtins: every {@link AGENT_BUILTIN_NAMES} entry registered here that can run (`unavailable`
+ *   says why not), `TaskOutput` / `TaskStop` with `Bash`, `Agent` while its roster is not empty;
+ * - extension tools: every tool registered by an extension loaded on this replica and enabled in
+ *   the org (`extension_org_configs.enabled`; required bootstrap plugins are enabled in every org,
+ *   `enabled.ts`), whose effective config for the org is valid (layering spec A §6) and that the
+ *   org did not switch off (§7: the org's switch wins);
+ * - connector tools: every enabled tool of every live, active connector of the org whose
+ *   connector extension is installed, with a valid key.
+ * What cannot be offered goes to `hidden` with the reason; nothing is reported to the model as
+ * unavailable except two sources with one key (the first wins).
  */
 export declare class ToolRegistry {
     private readonly db;
@@ -178,7 +245,14 @@ export declare class ToolRegistry {
     private readonly extensions;
     private readonly builtinTools;
     /**
-     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `tool_search` is never
+     * The extensions' effective config per org (layering spec A §6): an extension tool is
+     * unavailable in an org whose effective config is not valid.
+     */
+    private readonly effective;
+    /** The org's switches of single extension tools (layering spec A §7). */
+    private readonly switches;
+    /**
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
      * offered and the sub-agent limits are the schema defaults.
      */
     private readonly config?;
@@ -188,11 +262,18 @@ export declare class ToolRegistry {
     /** The installed connectors (`connector@1`, from the extension registry). */
     extensions: Pick<ExtensionRegistry, "list">, builtinTools: Pick<BuiltinTools, "list">, 
     /**
-     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `tool_search` is never
+     * The extensions' effective config per org (layering spec A §6): an extension tool is
+     * unavailable in an org whose effective config is not valid.
+     */
+    effective: Pick<EffectiveConfigs, "get">, 
+    /** The org's switches of single extension tools (layering spec A §7). */
+    switches: Pick<OrgToolSwitches, "offKeys">, 
+    /**
+     * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
      * offered and the sub-agent limits are the schema defaults.
      */
     config?: Pick<KernelConfigService, "get"> | undefined);
-    /** The kernel's builtin tools (`tool_search` is added by {@link forAgent}, not by definitions). */
+    /** The kernel's builtin tools (`ToolSearch` is added by {@link forAgent}, not by definitions). */
     private get builtins();
     /** `host.list("connector")` 中 `kind` 匹配的第一个实现；未安装返回 undefined。 */
     findConnector(kind: string): Connector | undefined;
@@ -216,41 +297,81 @@ export declare class ToolRegistry {
     /** 已安装连接器的 kind 列表（去重，按加载顺序）。 */
     connectorKinds(): string[];
     /**
-     * 保存 agent 时校验工具引用（只看「存在」，停用 / 待复核 / 插件未启用等运行时状态不拒绝，由 `forAgent` 报不可用）：
-     * - 内置：名字在 {@link BUILTIN_TOOL_NAMES} 中；
-     * - 插件：插件已加载且注册了该工具，key 合法；
-     * - 连接器：连接器属于本组织且未删除；点名的工具必须在连接器的工具快照中。
-     * 不同来源拼出同一个 key 也报出来（不截断、不猜）。
-     * 返回 `keys`：这些引用可能产生的全部工具 key（`"all"` 含连接器当前所有工具，不论状态），供校验 `toolPolicies`。
+     * The connector kinds `orgId` can create connectors of: the `connector@1` implementations loaded
+     * on this replica whose extension is enabled in the org (the first implementation of a kind, as
+     * {@link findConnector} picks it), sorted by kind.
      */
-    checkRefs(orgId: string, refs: readonly AgentToolRef[]): Promise<{
+    connectorKindsFor(orgId: string): Promise<{
+        kind: string;
+        plugin: string;
+    }[]>;
+    /** True when `kind` is one of {@link connectorKindsFor}: loaded here and enabled in the org. */
+    connectorKindAvailable(orgId: string, kind: string): Promise<boolean>;
+    /**
+     * Checks a definition's `disabledTools` on save (existence only): a builtin an agent can turn off
+     * ({@link AGENT_BUILTIN_NAMES}), an extension loaded here and the tools it registered, a live
+     * connector of the org and tools of its snapshot. An entry equal to one of `kept` (the current
+     * version's) is not re-checked: a connector deleted or an extension uninstalled later never
+     * blocks other edits. Returns `keys`: every tool key the agent could have, on or turned off (all
+     * its builtins, every loaded extension's tools, every tool of the org's live connectors in any
+     * status), the keys `toolPolicies` may use.
+     */
+    checkDisabled(orgId: string, disabled: readonly DisabledToolRef[], kept?: readonly DisabledToolRef[]): Promise<{
         keys: Set<string>;
         issues: ToolRefIssue[];
     }>;
     /**
-     * 解析 agent 引用的工具（见类注释），再判定是否启用 `tool_search`：组织设置 `toolSearch === "on"`，且
-     * 可用工具数 > `tools.searchThresholdTools` 或其定义的估算 token > `tools.searchThresholdTokens`。
-     * 启用时把内置 `tool_search` 追加到末尾。定义里显式引用的 `tool_search` 忽略（由这里按设置管理）。
-     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `skill_load`（始终完整加载）；
-     * 定义里显式引用的 `skill_load` 同样忽略。
+     * Resolves what the agent has (see the class comment), then decides on `ToolSearch`: the org
+     * setting `toolSearch === "on"` and more than `tools.searchThresholdTools` tools or more than
+     * `tools.searchThresholdTokens` estimated definition tokens; when on, the builtin `ToolSearch` is
+     * appended. `skillLoad`: the log has a skills catalog snapshot (`skills_catalog`, Ruling M17) →
+     * the builtin `Skill` is added (always fully loaded).
      */
     forAgent(orgId: string, def: {
-        tools: readonly AgentToolRef[];
+        disabledTools?: readonly DisabledToolRef[] | undefined;
+        /** A sub-agent's key filter (frozen at dispatch); registry-managed tools are not filtered. */
+        subagentTools?: SubagentTools | undefined;
         skillLoad?: boolean;
-        /** The definition's sub-agent roster source: the `agent` tool's description lists it. */
+        /** The definition's sub-agent roster source: the `Agent` tool's description lists it. */
         subagents?: AgentDefinition["subagents"];
+        /**
+         * The run is a sub-agent's (it has a parent): it gets `SendMessage` (to reach its parent)
+         * and `SubagentHandback` whatever its definition says (agent map spec §4.2, §4.3).
+         */
+        child?: boolean;
+        /**
+         * The run is a fork invocation's child (phase D): its final reply is the skill's report, so
+         * it reaches its parent with neither tool (`SendMessage` only to its own sub-agents).
+         */
+        forkChild?: boolean;
+        /**
+         * The root conversation of the run (a sub-agent's tree root): tools whose availability
+         * depends on the conversation's device (the sandbox tools) are listed by it.
+         */
+        sandboxConversationId?: string;
+        /** An eval replay's listing: its calls are never executed (the sandbox tools are listed). */
+        replay?: boolean;
     }): Promise<AgentTools>;
-    /** 是否启用 `tool_search`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
+    /** 是否启用 `ToolSearch`（见 {@link forAgent}）；先比阈值，超过才读组织设置。 */
     private searchActive;
     private resolve;
     /**
-     * `subagents.maxConcurrentPerRun` with the organization's override, for the `agent` tool's
+     * `subagents.maxConcurrentPerConversation` with the organization's override, for the `Agent` tool's
      * description (§4.3). A change of the limit changes the tool's spec hash; replays read the
      * definition logged by hash, so no drift reason is involved. Without config (some tests): the
      * schema default.
      */
     private maxConcurrentSubagents;
+    /** The extensions enabled in the org (`extensions/enabled.ts`, through the host). */
+    enabledExtensions(orgId: string): Promise<Set<string>>;
     /** Plugins the organization enabled (built-in plugins always count as enabled, C14). */
     private enabledPlugins;
-    private loadConnectors;
+    /** The org's connectors (live ones, sorted by slug) with their tool snapshots (by name). */
+    private loadOrgConnectors;
 }
+/**
+ * `tools` narrowed by a sub-agent's key filter (tools default-on spec §4): `deny` keys removed,
+ * and with `allow` only its keys kept. `TaskOutput` / `TaskStop` follow `Bash`, as they come with
+ * it. Without a filter the list is returned as it is.
+ */
+export declare function filterSubagentTools(tools: ResolvedTool[], filter: SubagentTools | undefined): ResolvedTool[];