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

package/dist/tools/policy.d.ts

@@ -34,7 +34,7 @@ export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" |
  * - a sub-agent (template or general-purpose): `agentDef` is its frozen effective definition (the
  *   parent's policies with the template's on top) and `ctx.agentId` is the parent's agent, so the
  *   parent's current version still tightens it (sub-agents spec §5.3, §9); its "this conversation"
- *   grants are the parent conversation's; an org agent sub-agent (§5.5): `ctx.agentId` is the
+ *   grants are the root conversation's (agent map spec §7); an org agent sub-agent (§5.5): `ctx.agentId` is the
  *   dispatched agent (its current version, its "always" grants) and the parent agent's current
  *   policies apply on top ({@link parentAgentOverride});
  * - 授权表（`conversation_tool_grants` / `tool_grants`），`spec_hash` 与当前定义不一致视为无效（D8），

package/dist/tools/policy.js

@@ -36,6 +36,17 @@ export function isFixedAsk(tool, visibility, skillWritePolicy) {
     return !(builtinOnly && visibility === "private" && skillWritePolicy !== "ask");
 }
 const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
+/**
+ * An agent's tightening for a call: its policy on the tool key and, for a per-call key
+ * (`Platform:<operation>`), on that key, the stricter of the two (a policy can only tighten).
+ */
+function overrideOf(policies, toolKey, policyKey) {
+    const own = asOverride(policies?.[toolKey]);
+    if (policyKey === toolKey)
+        return own;
+    const s = stricter(own ?? "allow", asOverride(policies?.[policyKey]));
+    return s === "allow" ? undefined : s;
+}
 /**
  * 执行时的策略判定（spec 3.6 R5：在动作执行那一刻判定）。每次调用都实时读取：
  * - 沙箱工具（bash / write / edit / deliver）的组织设置 `sandboxToolPolicy`（为 ask 时组织默认至少 ask）；
@@ -45,7 +56,7 @@ const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
  * - a sub-agent (template or general-purpose): `agentDef` is its frozen effective definition (the
  *   parent's policies with the template's on top) and `ctx.agentId` is the parent's agent, so the
  *   parent's current version still tightens it (sub-agents spec §5.3, §9); its "this conversation"
- *   grants are the parent conversation's; an org agent sub-agent (§5.5): `ctx.agentId` is the
+ *   grants are the root conversation's (agent map spec §7); an org agent sub-agent (§5.5): `ctx.agentId` is the
  *   dispatched agent (its current version, its "always" grants) and the parent agent's current
  *   policies apply on top ({@link parentAgentOverride});
  * - 授权表（`conversation_tool_grants` / `tool_grants`），`spec_hash` 与当前定义不一致视为无效（D8），
@@ -57,7 +68,11 @@ const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
  */
 export function createDecidePolicy(db) {
     return async (tool, agentDef, ctx) => {
-        let connectorDefault = tool.defaultPolicy;
+        // a per-call policy (Platform tool spec §6.2): its key replaces the tool key for policies,
+        // grants and approvals, and its policy replaces the tool's default
+        const call = ctx.callPolicy ?? null;
+        const policyKey = call?.key ?? tool.key;
+        let connectorDefault = call?.policy ?? tool.defaultPolicy;
         let connectorId = null;
         let hashCurrent = true;
         if (tool.source.kind === "connector") {
@@ -101,7 +116,7 @@ export function createDecidePolicy(db) {
             }
         }
         // 运行所用版本可能是加 toolPolicies 字段之前保存的：缺省为空
-        const runOverride = asOverride(agentDef.toolPolicies?.[tool.key]);
+        const runOverride = overrideOf(agentDef.toolPolicies, tool.key, policyKey);
         const current = await db
             .selectFrom("agents")
             .innerJoin("agent_versions", (j) => j
@@ -115,10 +130,10 @@ export function createDecidePolicy(db) {
             ? undefined
             : await normalizeStoredDefinitionIn(db, ctx.orgId, current.definition);
         const currentPolicies = currentDef?.toolPolicies;
-        const currentOverride = asOverride(currentPolicies?.[tool.key]);
+        const currentOverride = overrideOf(currentPolicies, tool.key, policyKey);
         let strictest = stricter(runOverride ?? "allow", currentOverride);
         if (ctx.parentConversationId !== undefined && ctx.parentAgentDiffers !== false) {
-            strictest = stricter(strictest, await parentAgentOverride(db, tool.key, ctx));
+            strictest = stricter(strictest, await parentAgentOverride(db, tool.key, policyKey, ctx));
         }
         const agentOverride = strictest === "allow" ? undefined : strictest;
         let escalateTo = null;
@@ -137,7 +152,10 @@ export function createDecidePolicy(db) {
         // 可见性实时读（R5）：共享 agent 的 SkillWrite 固定 ask，私有 agent 不问（见 R3_SHARED_AGENT_ONLY_TOOL_KEYS）
         // 当前版本的 skills.writePolicy 同样实时读（R5）：运行中改为 ask，下一次调用即生效；固定 ask 时授权不放行
         const writePolicy = currentDef?.skills?.writePolicy;
-        const fixedAsk = isFixedAsk(tool, current?.visibility, writePolicy);
+        // `remember: false` on a call that is not a plain allow (an org / platform operation, or a read
+        // an agent tightened to ask): every call asks, grants never apply. A read (`allow`) never asks.
+        const fixedAsk = isFixedAsk(tool, current?.visibility, writePolicy) ||
+            (call !== null && !call.remember && (call.policy !== "allow" || agentOverride !== undefined));
         const input = {
             connectorDefault,
             ...(agentOverride !== undefined && { agentOverride }),
@@ -148,7 +166,7 @@ export function createDecidePolicy(db) {
         if (pre === "deny")
             return "deny";
         if (pre === "ask" && !fixedAsk && escalateTo === null && hashCurrent) {
-            input.grant = await findGrant(db, tool, connectorId, ctx);
+            input.grant = await findGrant(db, tool, policyKey, connectorId, ctx);
         }
         const result = decide(input);
         if (result === "allow" && escalateTo === null) {
@@ -156,7 +174,7 @@ export function createDecidePolicy(db) {
             return pre === "ask" && input.grant !== null ? { grant: input.grant } : "allow";
         }
         const ask = {
-            toolKey: tool.key,
+            toolKey: policyKey,
             specHash: tool.specHash,
             connectorId,
             requestedFor: escalateTo === null ? ctx.accountId : null,
@@ -185,7 +203,7 @@ export function createDecidePolicy(db) {
  * policy for the same key applies on top, so the parent's owner can tighten a running child too.
  * For a template or general-purpose child the parent conversation has the same agent, already read.
  */
-async function parentAgentOverride(db, toolKey, ctx) {
+async function parentAgentOverride(db, toolKey, policyKey, ctx) {
     const row = await db
         .selectFrom("conversations as c")
         .innerJoin("agents as a", "a.id", "c.agent_id")
@@ -198,21 +216,23 @@ async function parentAgentOverride(db, toolKey, ctx) {
     // stored raw: an rc version's keys read as current keys, so its deny keeps applying (§8.3)
     const policies = (await normalizeStoredDefinitionIn(db, ctx.orgId, row.definition))
         .toolPolicies;
-    return asOverride(policies?.[toolKey]);
+    return overrideOf(policies, toolKey, policyKey);
 }
 /**
- * A grant matching the current definition hash and source connector: this conversation's first,
+ * A grant matching the current definition hash and source connector, keyed by the call's policy key
+ * (the tool key, or a per-call key such as `Platform:<operation>`): this conversation's first,
  * then "always". `connectorId` is the tool's source connector (null for plugin and builtin tools,
  * which match only grants without a connector). A sub-agent's "this conversation" grants live on
- * its parent conversation (sub-agents spec §9), so parallel children are approved once.
+ * the root conversation of its tree (agent map spec §7), so the root and every sub-agent at any
+ * depth are approved once.
  */
-async function findGrant(db, tool, connectorId, ctx) {
+async function findGrant(db, tool, policyKey, connectorId, ctx) {
     const sameConnector = sql `connector_id IS NOT DISTINCT FROM ${connectorId}`;
     const session = await db
         .selectFrom("conversation_tool_grants")
         .select("spec_hash")
-        .where("conversation_id", "=", ctx.parentConversationId ?? ctx.conversationId)
-        .where("tool_key", "=", tool.key)
+        .where("conversation_id", "=", ctx.rootConversationId ?? ctx.conversationId)
+        .where("tool_key", "=", policyKey)
         .where(sameConnector)
         .executeTakeFirst();
     if (session?.spec_hash === tool.specHash)
@@ -223,7 +243,7 @@ async function findGrant(db, tool, connectorId, ctx) {
         .where("org_id", "=", ctx.orgId)
         .where("account_id", "=", ctx.accountId)
         .where("agent_id", "=", ctx.agentId)
-        .where("tool_key", "=", tool.key)
+        .where("tool_key", "=", policyKey)
         .where(sameConnector)
         .executeTakeFirst();
     return always?.spec_hash === tool.specHash ? "always" : null;

package/dist/tools/registry.d.ts

@@ -1,6 +1,7 @@
 import type { Connector, HookParentScope, InputRequired, ToolAnnotations, ToolCallContext, ToolResult, ToolSpec } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } 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";
@@ -8,6 +9,7 @@ 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";
 /** 保存 agent 时引用校验的问题（`path` 为 `tools.<i>`）。 */
@@ -29,12 +31,18 @@ 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
@@ -79,6 +87,50 @@ export interface BuiltinTool {
     unavailable?: (ctx: {
         orgId: string;
     }) => 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;
+}
+/** {@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）。
@@ -129,6 +181,8 @@ export interface ResolvedTool {
      * （推给持有该角色的人）。M3 的内置与连接器工具都不设。
      */
     requiredRole?: OrgRole;
+    /** A builtin's per-call policy key (see {@link BuiltinTool.callPolicy}). */
+    callPolicy?: CallPolicyFn;
 }
 /** 不可用的引用：`ref` 尽量写成模型认识的工具 key（`mcp__docs__search`、`mcp__docs__*`），否则 `app:<id>`。 */
 export interface UnavailableTool {
@@ -174,9 +228,11 @@ export interface AgentTools {
  *
  * Availability:
  * - builtin: in `builtins`;
- * - extension tools: the extension is loaded and registered the tool, and this org enabled the
+ * - 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`);
+ *   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
@@ -191,6 +247,13 @@ export declare class ToolRegistry {
     /** The installed connectors (`connector@1`, from the extension registry). */
     private readonly extensions;
     private readonly builtinTools;
+    /**
+     * 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.
@@ -201,6 +264,13 @@ export declare class ToolRegistry {
     host: Pick<ExtensionHost, "tools" | "enabledPlugins">, 
     /** The installed connectors (`connector@1`, from the extension registry). */
     extensions: Pick<ExtensionRegistry, "list">, builtinTools: Pick<BuiltinTools, "list">, 
+    /**
+     * 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.
@@ -229,6 +299,17 @@ export declare class ToolRegistry {
     }[];
     /** 已安装连接器的 kind 列表（去重，按加载顺序）。 */
     connectorKinds(): string[];
+    /**
+     * 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.
+     */
+    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>;
     /**
      * 保存 agent 时校验工具引用（只看「存在」，停用 / 待复核 / 插件未启用等运行时状态不拒绝，由 `forAgent` 报不可用）：
      * - 内置：名字在 {@link BUILTIN_TOOL_NAMES} 中；
@@ -253,17 +334,29 @@ export declare class ToolRegistry {
         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).
+         */
+        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;
     }): Promise<AgentTools>;
     /** 是否启用 `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;

package/dist/tools/registry.js

@@ -10,6 +10,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { createHash } from "node:crypto";
 import { connectorToolKey, extensionToolKey } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
+import { EffectiveConfigs, NEEDS_CONFIG_REASON } 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";
@@ -18,12 +19,13 @@ import { readOrgSettings } from "../orgs/settings.service.js";
 import { estimateTokens } from "../runtime/context/tokens.js";
 import { SUBAGENT_LIMIT_DEFAULTS, subagentLimits } from "../runtime/subagents/limits.js";
 import { resolveRoster } from "../runtime/subagents/roster.js";
-import { AGENT_TOOL, BASH_COMPANION_TOOLS, BUILTIN, BUILTIN_TOOL_NAMES, SKILL_LOAD, TOOL_SEARCH, } from "./builtin-names.js";
+import { AGENT_TOOL, BASH_COMPANION_TOOLS, BUILTIN, BUILTIN_TOOL_NAMES, SEND_MESSAGE, SKILL_LOAD, SUBAGENT_HANDBACK, SUBAGENT_MESSAGE_TOOLS, TOOL_SEARCH, } from "./builtin-names.js";
 import { agentToolSpec } from "./builtins/agent.js";
 import { BuiltinTools } from "./builtins/builtin-tools.js";
 import { canonicalJson } from "./canonical-json.js";
 import { legacyKeySaveText } from "./legacy-keys.js";
 import { toolKeyIssue } from "./naming.js";
+import { OrgToolSwitches, toolTurnedOffReason } from "./org-tool-switches.js";
 export { BUILTIN_TOOL_NAMES } from "./builtin-names.js";
 export { canonicalJson } from "./canonical-json.js";
 /** The first 16 hex digits of sha256(canonicalJson(v)): a fingerprint independent of key order. */
@@ -80,6 +82,7 @@ const builtinTool = (b, spec) => ({
     defaultPolicy: b.defaultPolicy,
     ...(b.timeoutMs !== undefined && { timeoutMs: b.timeoutMs }),
     ...(b.spillChars !== undefined && { spillChars: b.spillChars }),
+    ...(b.callPolicy !== undefined && { callPolicy: b.callPolicy }),
 });
 /**
  * Tool registry: resolves the references in an agent definition into the tools available for this
@@ -88,9 +91,11 @@ const builtinTool = (b, spec) => ({
  *
  * Availability:
  * - builtin: in `builtins`;
- * - extension tools: the extension is loaded and registered the tool, and this org enabled the
+ * - 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`);
+ *   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
@@ -103,12 +108,21 @@ let ToolRegistry = class ToolRegistry {
     host;
     extensions;
     builtinTools;
+    effective;
+    switches;
     config;
     constructor(db, 
     /** Extension tools and the organization's enabled extensions. */
     host, 
     /** The installed connectors (`connector@1`, from the extension registry). */
     extensions, builtinTools, 
+    /**
+     * 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, 
+    /** The org's switches of single extension tools (layering spec A §7). */
+    switches, 
     /**
      * `tools.searchThreshold*` and the sub-agent limits. Absent (some tests): `ToolSearch` is never
      * offered and the sub-agent limits are the schema defaults.
@@ -118,6 +132,8 @@ let ToolRegistry = class ToolRegistry {
         this.host = host;
         this.extensions = extensions;
         this.builtinTools = builtinTools;
+        this.effective = effective;
+        this.switches = switches;
         this.config = config;
     }
     /** The kernel's builtin tools (`ToolSearch` is added by {@link forAgent}, not by definitions). */
@@ -173,6 +189,29 @@ let ToolRegistry = class ToolRegistry {
     connectorKinds() {
         return [...new Set(this.extensions.list("connector").map((e) => e.impl.kind))];
     }
+    /**
+     * 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.
+     */
+    async connectorKindsFor(orgId) {
+        const enabled = await this.enabledPlugins(orgId);
+        const out = new Map();
+        for (const e of this.extensions.list("connector")) {
+            const kind = e.impl?.kind;
+            if (typeof kind !== "string" || out.has(kind))
+                continue;
+            out.set(kind, e.plugin);
+        }
+        return [...out]
+            .filter(([, plugin]) => enabled.has(plugin))
+            .map(([kind, plugin]) => ({ kind, plugin }))
+            .sort((a, b) => a.kind.localeCompare(b.kind));
+    }
+    /** True when `kind` is one of {@link connectorKindsFor}: loaded here and enabled in the org. */
+    async connectorKindAvailable(orgId, kind) {
+        return (await this.connectorKindsFor(orgId)).some((k) => k.kind === kind);
+    }
     /**
      * 保存 agent 时校验工具引用（只看「存在」，停用 / 待复核 / 插件未启用等运行时状态不拒绝，由 `forAgent` 报不可用）：
      * - 内置：名字在 {@link BUILTIN_TOOL_NAMES} 中；
@@ -260,6 +299,18 @@ let ToolRegistry = class ToolRegistry {
      */
     async forAgent(orgId, def) {
         const { tools, unavailable, hidden } = await this.resolve(orgId, def);
+        // `SendMessage` to an agent that has `Agent` (to reach its sub-agents) or a parent;
+        // `SubagentHandback` to a sub-agent only; a fork invocation's child reports by its reply
+        const toParent = def.child === true && def.forkChild !== true;
+        const messageTools = [
+            ...(toParent || tools.some((t) => t.key === AGENT_TOOL) ? [SEND_MESSAGE] : []),
+            ...(toParent ? [SUBAGENT_HANDBACK] : []),
+        ];
+        for (const name of messageTools) {
+            const b = this.builtins.find((x) => x.spec.name === name);
+            if (b)
+                tools.push(builtinTool(b, b.spec));
+        }
         const sl = def.skillLoad === true && this.builtins.find((x) => x.spec.name === SKILL_LOAD);
         if (sl) {
             tools.push({
@@ -314,18 +365,30 @@ let ToolRegistry = class ToolRegistry {
                 });
             }
         };
-        const enabledPlugins = def.tools.some((r) => r.kind === "plugin")
-            ? await this.enabledPlugins(orgId)
-            : new Set();
+        const [enabledPlugins, offKeys] = def.tools.some((r) => r.kind === "plugin")
+            ? await Promise.all([this.enabledPlugins(orgId), this.switches.offKeys(orgId)])
+            : [new Set(), new Set()];
         const connectorIds = [
             ...new Set(def.tools.flatMap((r) => (r.kind === "connector" ? [r.connectorId] : []))),
         ];
         const apps = await this.loadConnectors(orgId, connectorIds);
         const pluginTools = this.host.tools();
+        // one effective config read per extension and resolution, however many of its tools are named
+        const configured = new Map();
+        const configuredIn = (plugin) => {
+            let ok = configured.get(plugin);
+            if (!ok) {
+                ok = this.effective.get(orgId, plugin).then((e) => e.ok);
+                configured.set(plugin, ok);
+            }
+            return ok;
+        };
         for (const ref of def.tools) {
             if (ref.kind === "builtin") {
                 if (ref.name === TOOL_SEARCH || ref.name === SKILL_LOAD)
                     continue;
+                if (SUBAGENT_MESSAGE_TOOLS.has(ref.name))
+                    continue;
                 const b = this.builtins.find((x) => x.spec.name === ref.name);
                 if (!b) {
                     unavailable.push({ ref: ref.name, reason: "Built-in tool does not exist" });
@@ -369,6 +432,15 @@ let ToolRegistry = class ToolRegistry {
                     });
                     continue;
                 }
+                // the pipeline refuses such calls too (a resumed step), this keeps them from the model
+                if (offKeys.has(key)) {
+                    unavailable.push({ ref: key, reason: toolTurnedOffReason(key) });
+                    continue;
+                }
+                if (!(await configuredIn(ref.plugin))) {
+                    unavailable.push({ ref: key, reason: `Plugin ${ref.plugin} ${NEEDS_CONFIG_REASON}` });
+                    continue;
+                }
                 const issue = toolKeyIssue(key);
                 if (issue) {
                     unavailable.push({ ref: key, reason: issue });
@@ -447,7 +519,7 @@ let ToolRegistry = class ToolRegistry {
         return { tools, unavailable, hidden };
     }
     /**
-     * `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.
@@ -455,7 +527,11 @@ let ToolRegistry = class ToolRegistry {
     async maxConcurrentSubagents(orgId) {
         const cfg = this.config;
         const config = cfg ?? { get: () => ({ subagents: SUBAGENT_LIMIT_DEFAULTS }) };
-        return (await subagentLimits(this.db.db, config, orgId)).maxConcurrentPerRun;
+        return (await subagentLimits(this.db.db, config, orgId)).maxConcurrentPerConversation;
+    }
+    /** The extensions enabled in the org (`extensions/enabled.ts`, through the host). */
+    async enabledExtensions(orgId) {
+        return this.host.enabledPlugins(orgId);
     }
     /** Plugins the organization enabled (built-in plugins always count as enabled, C14). */
     async enabledPlugins(orgId) {
@@ -519,6 +595,8 @@ ToolRegistry = __decorate([
     __param(1, Inject(ExtensionHost)),
     __param(2, Inject(ExtensionRegistry)),
     __param(3, Inject(BuiltinTools)),
-    __param(4, Inject(KernelConfigService))
+    __param(4, Inject(EffectiveConfigs)),
+    __param(5, Inject(OrgToolSwitches)),
+    __param(6, Inject(KernelConfigService))
 ], ToolRegistry);
 export { ToolRegistry };

package/dist/tools/tools.module.js

@@ -9,10 +9,12 @@ import { BackgroundModule } from "../background/background.module.js";
 import { ConversationAccessModule } from "../conversations/access.js";
 import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
+import { EnvironmentsModule } from "../environments/environments.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { ModelsModule } from "../models/models.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
+import { PlatformModule } from "../platform/platform.module.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { StepLogModule } from "../runtime/step-log.js";
 import { SubagentsModule } from "../runtime/subagents/subagents.service.js";
@@ -28,8 +30,9 @@ import { ConnectorContent } from "./connector-content.js";
 import { ConnectorsService } from "./connectors.service.js";
 import { Credentials } from "./credentials.js";
 import { ToolDrift } from "./drift.js";
-import { ConversationToolInfo } from "./info.js";
+import { ConversationToolInfo, OrgExtensionTools } from "./info.js";
 import { OAuthFlow } from "./oauth/flow.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
 import { ToolOutputs } from "./outputs.js";
 import { ToolPipeline } from "./pipeline.js";
 import { QuestionsService } from "./questions.service.js";
@@ -55,8 +58,9 @@ ToolsModule = __decorate([
             OrgLockModule,
             // the `Agent` tool's dispatch
             SubagentsModule,
-            // the builtin sandbox and skill tools run in the conversation's sandbox
+            // the builtin sandbox and skill tools run in the conversation's environment
             SandboxModule,
+            EnvironmentsModule,
             // `Bash` with run_in_background records its task; TaskOutput / TaskStop finish and stop it
             BackgroundModule,
             // the conversation page's tool metadata reads only what the viewer may see
@@ -65,6 +69,8 @@ ToolsModule = __decorate([
             ModelsModule,
             UsageReportModule,
             StepLogModule,
+            // the `Platform` tool's operations, actor facts and agent docs (imports no domain module)
+            PlatformModule,
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
         providers: [
@@ -82,6 +88,8 @@ ToolsModule = __decorate([
             ConnectorsService,
             OAuthFlow,
             ConversationToolInfo,
+            OrgExtensionTools,
+            OrgToolSwitches,
         ],
         exports: [
             Credentials,
@@ -97,6 +105,8 @@ ToolsModule = __decorate([
             ConnectorsService,
             OAuthFlow,
             ConversationToolInfo,
+            OrgExtensionTools,
+            OrgToolSwitches,
         ],
     })
 ], ToolsModule);

package/dist/ui/views.d.ts

@@ -1,6 +1,7 @@
 import { type FormAnswer, type Logger, type UiActionResult, type UiContribution, type UiIcon, type UiView } from "@capybara-hq/plugin-sdk";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { PreviewerRegistry } from "../files/previewers.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -78,7 +79,7 @@ export declare function dropForeignOpens(view: UiView, panels: ReadonlySet<strin
  */
 export declare class UiViews {
     private readonly d;
-    constructor(host: ExtensionHost, conversations: ConversationsService, previewers: PreviewerRegistry, db: KernelDb, log: Pick<Logger, "warn">);
+    constructor(host: ExtensionHost, conversations: ConversationsService, previewers: PreviewerRegistry, db: KernelDb, log: Pick<Logger, "warn">, effective: Pick<EffectiveConfigs, "get">);
     /** 该组织、该角色可见的界面贡献：插件已启用且已加载；kind view 的要求插件注册了 render；组织页面要 member 以上。 */
     contributions(orgId: string, role: OrgRole): Promise<UiContributionItem[]>;
     /**