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

package/dist/tools/registry.d.ts

@@ -1,5 +1,5 @@
 import type { Connector, HookParentScope, InputRequired, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
-import type { AgentDefinition } from "../agents/definition.js";
+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";
@@ -12,7 +12,7 @@ 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";
-/** 保存 agent 时引用校验的问题（`path` 为 `tools.<i>`）。 */
+/** A problem of a saved definition's `disabledTools` (`path` is `disabledTools.<i>`). */
 export interface ToolRefIssue {
     path: string;
     message: string;
@@ -110,6 +110,8 @@ export interface CallPolicyContext {
      * (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>;
@@ -132,22 +134,6 @@ export interface CallPolicy {
     /** 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 {
     /** 模型可见名。 */
@@ -211,8 +197,11 @@ 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[];
     /**
@@ -222,23 +211,21 @@ export interface AgentTools {
     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, 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`), and the
- *   extension's effective config for the org is valid (layering spec A §6) and the org did not
- *   turn the tool off (§7);
- * - 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;
@@ -311,32 +298,35 @@ export declare class ToolRegistry {
     /** True when `kind` is one of {@link connectorKindsFor}: loaded here and enabled in the org. */
     connectorKindAvailable(orgId: string, kind: string): Promise<boolean>;
     /**
-     * 保存 agent 时校验工具引用（只看「存在」，停用 / 待复核 / 插件未启用等运行时状态不拒绝，由 `forAgent` 报不可用）：
-     * - 内置：名字在 {@link BUILTIN_TOOL_NAMES} 中；
-     * - 插件：插件已加载且注册了该工具，key 合法；
-     * - 连接器：连接器属于本组织且未删除；点名的工具必须在连接器的工具快照中。
-     * 不同来源拼出同一个 key 也报出来（不截断、不猜）。
-     * 返回 `keys`：这些引用可能产生的全部工具 key（`"all"` 含连接器当前所有工具，不论状态），供校验 `toolPolicies`。
+     * 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.
      */
-    checkRefs(orgId: string, refs: readonly AgentToolRef[]): Promise<{
+    checkDisabled(orgId: string, disabled: readonly DisabledToolRef[], kept?: readonly DisabledToolRef[]): Promise<{
         keys: Set<string>;
         issues: ToolRefIssue[];
     }>;
     /**
-     * 解析 agent 引用的工具（见类注释），再判定是否启用 `ToolSearch`：组织设置 `toolSearch === "on"`，且
-     * 可用工具数 > `tools.searchThresholdTools` 或其定义的估算 token > `tools.searchThresholdTokens`。
-     * 启用时把内置 `ToolSearch` 追加到末尾。定义里显式引用的 `ToolSearch` 忽略（由这里按设置管理）。
-     * `skillLoad`：对话日志里有技能目录快照（`skills_catalog`，Ruling M17）→ 加入内置 `Skill`（始终完整加载）；
-     * 定义里显式引用的 `Skill` 同样忽略。
+     * 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. */
         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 names (agent map spec §4.2, §4.3).
+         * and `SubagentHandback` whatever its definition says (agent map spec §4.2, §4.3).
          */
         child?: boolean;
         /**
@@ -359,5 +349,12 @@ export declare class ToolRegistry {
     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[];