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

package/dist/tools/org-tool-switches.js

@@ -0,0 +1,201 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from "node:crypto";
+import { extensionToolKey } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { extensionToolDisabled } from "../agents/definition.js";
+import { ApiError } from "../errors.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { extensionVisibleTo } from "../extensions/org-config.js";
+import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OrgLock } from "../orgs/org-lock.js";
+/** Model-visible (English): why a turned-off extension tool is not offered. */
+export const toolTurnedOffReason = (key) => `Tool ${key} is turned off in this organization`;
+/** The confirm hash of a switch-off preview. */
+function switchOffHash(orgId, plugin, tool, agents) {
+    return createHash("sha256")
+        .update(JSON.stringify({ orgId, plugin, tool, agents: agents.map((a) => a.id) }))
+        .digest("hex");
+}
+/**
+ * Per-org switches of single extension tools (layering spec A §7, table `org_tool_switches`): an
+ * org admin turns off one tool an extension registers (`ctx.tools.register`); it is then not
+ * offered to any agent of the org (`ToolRegistry.forAgent`) and refused if called
+ * (`ToolPipeline`). No row means on. A row of a tool the extension stops registering is kept and
+ * applies again if the tool comes back. Builtin and connector tools are out of scope. Read from PG
+ * on every use, no in-process state.
+ */
+let OrgToolSwitches = class OrgToolSwitches {
+    kdb;
+    txHost;
+    host;
+    orgLock;
+    constructor(kdb, txHost, host, 
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    orgLock) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.host = host;
+        this.orgLock = orgLock;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** The tool names `plugin` registers on this replica, in registration order. */
+    registered(plugin) {
+        return [
+            ...new Set(this.host
+                .tools()
+                .filter((t) => t.plugin === plugin)
+                .map((t) => t.spec.name)),
+        ];
+    }
+    /**
+     * The tools of an extension the org sees: running here and visible under plugin scope, else 404
+     * `extension.not_found` (an invisible one is answered like an unknown one). An extension that
+     * runs but registers no tools (a channel, a model provider) answers an empty list, not 404.
+     */
+    async toolsFor(orgId, plugin) {
+        if (!this.host.current(plugin) || !(await extensionVisibleTo(this.db, orgId, plugin))) {
+            throw new ApiError("extension.not_found", `Extension ${plugin} is not installed`);
+        }
+        return this.registered(plugin);
+    }
+    /** The stored switches of the org (all extensions, or one), `false` ones only matter. */
+    async offRows(orgId, plugin) {
+        let q = this.db
+            .selectFrom("org_tool_switches")
+            .select(["plugin", "tool"])
+            .where("org_id", "=", orgId)
+            .where("enabled", "=", false);
+        if (plugin !== undefined)
+            q = q.where("plugin", "=", plugin);
+        return q.execute();
+    }
+    /** Every tool the extension registers on this replica with its switch (default on). */
+    async list(orgId, plugin) {
+        const tools = await this.toolsFor(orgId, plugin);
+        const off = new Set((await this.offRows(orgId, plugin)).map((r) => r.tool));
+        return tools.map((tool) => ({ tool, enabled: !off.has(tool) }));
+    }
+    /**
+     * What turning one tool off would affect (nothing written): the agents selecting it and the
+     * confirm hash {@link set} takes, or null when it is off already. Unknown tool -> 404
+     * `extension.tool_not_found`.
+     */
+    async previewOff(orgId, plugin, tool) {
+        const tools = await this.toolsFor(orgId, plugin);
+        if (!tools.includes(tool)) {
+            throw new ApiError("extension.tool_not_found", `Extension ${plugin} does not register a tool named ${tool}`);
+        }
+        if (await this.isToolOff(orgId, plugin, tool))
+            return null;
+        const affectedAgents = await this.agentsSelecting(orgId, plugin, tool);
+        return { affectedAgents, confirm: switchOffHash(orgId, plugin, tool, affectedAgents) };
+    }
+    /** The model-visible keys (`plugin__<extension>__<tool>`) of the tools turned off in the org. */
+    async offKeys(orgId) {
+        return new Set((await this.offRows(orgId)).map((r) => extensionToolKey(r.plugin, r.tool)));
+    }
+    /** Whether the org turned off this tool. */
+    async isToolOff(orgId, plugin, tool) {
+        const row = await this.db
+            .selectFrom("org_tool_switches")
+            .select("enabled")
+            .where("org_id", "=", orgId)
+            .where("plugin", "=", plugin)
+            .where("tool", "=", tool)
+            .executeTakeFirst();
+        return row?.enabled === false;
+    }
+    /**
+     * Switches one tool in the org. On applies at once. Off, while the tool is on: without
+     * `confirm` the preview (the org's agents whose current version does not turn it off) and its hash,
+     * with the current hash the switch is written (a changed preview -> 409 `plugin.switch_stale`).
+     * A tool the extension does not register -> 404 `extension.tool_not_found`. A change writes the
+     * audit row `extension.tool_switched`.
+     */
+    async set(orgId, plugin, tool, enabled, actor, confirm) {
+        await this.orgLock.lockAndAuthorize(orgId, actor.accountId, "org.extensions.manage");
+        const tools = await this.toolsFor(orgId, plugin);
+        if (!tools.includes(tool)) {
+            throw new ApiError("extension.tool_not_found", `Extension ${plugin} does not register a tool named ${tool}`);
+        }
+        const from = !(await this.isToolOff(orgId, plugin, tool));
+        if (from === enabled)
+            return { applied: true };
+        if (!enabled) {
+            const affectedAgents = await this.agentsSelecting(orgId, plugin, tool);
+            const hash = switchOffHash(orgId, plugin, tool, affectedAgents);
+            if (confirm === undefined)
+                return { applied: false, affectedAgents, confirm: hash };
+            if (confirm !== hash) {
+                throw new ApiError("plugin.switch_stale", "What switching this tool off affects has changed; review it and confirm again");
+            }
+        }
+        await this.db
+            .insertInto("org_tool_switches")
+            .values({ org_id: orgId, plugin, tool, enabled, updated_by: actor.accountId })
+            .onConflict((oc) => oc.columns(["org_id", "plugin", "tool"]).doUpdateSet({
+            enabled,
+            updated_by: actor.accountId,
+            updated_at: sql `now()`,
+        }))
+            .execute();
+        await audit(this.db, {
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+            orgId,
+            action: "extension.tool_switched",
+            target: extensionToolKey(plugin, tool),
+            detail: { plugin, tool, from, to: enabled, ...actor.auditDetail },
+        });
+        return { applied: true };
+    }
+    /**
+     * The org's live agents whose current version has extension tool `tool` of `plugin` on: tools
+     * are on by default (tools default-on spec §4), so every agent that does not turn it off.
+     */
+    async agentsSelecting(orgId, plugin, tool) {
+        const rows = await this.db
+            .selectFrom("agents as a")
+            .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
+            .select(["a.id", "v.definition"])
+            .where("a.org_id", "=", orgId)
+            .where("a.deleted_at", "is", null)
+            .orderBy("a.id")
+            .execute();
+        const out = [];
+        for (const r of rows) {
+            const def = r.definition;
+            const off = Array.isArray(def?.disabledTools)
+                ? extensionToolDisabled(def.disabledTools, plugin, tool)
+                : false;
+            if (!off)
+                out.push({ id: r.id, name: typeof def?.name === "string" ? def.name : r.id });
+        }
+        return out;
+    }
+};
+__decorate([
+    Transactional()
+], OrgToolSwitches.prototype, "set", null);
+OrgToolSwitches = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(ExtensionHost)),
+    __param(3, Inject(OrgLock))
+], OrgToolSwitches);
+export { OrgToolSwitches };

package/dist/tools/outputs.js

@@ -194,7 +194,7 @@ export async function spillIfLarge(text, opts, save) {
     return {
         content: `${text.slice(0, opts.previewChars)}\n…\n` +
             `[Output truncated: ${saved.sizeChars} chars, ${saved.lineCount} lines. Full output id: ${id}. ` +
-            `Use read_tool_output to page through it, or pass {"$output":"${id}"} as a tool argument.]`,
+            `Use ReadToolOutput to page through it, or pass {"$output":"${id}"} as a tool argument.]`,
         outputId: id,
     };
 }

package/dist/tools/pipeline.d.ts

@@ -1,7 +1,8 @@
 import { type FormAnswer, type InputForm, type Logger } from "@capybara-hq/plugin-sdk";
-import { type AgentDefinition } from "../agents/definition.js";
+import type { AgentDefinition } from "../agents/definition.js";
 import { EventLog } from "../conversations/event-log.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -9,16 +10,17 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { OrgRole } from "../orgs/roles.js";
 import { type ConversationKindForHooks, type HookRunner } from "../runtime/hook-calls.js";
 import { type SubagentParent, type WaitingFor } from "../runtime/loop.js";
-import type { DispatchOutcome } from "../runtime/subagents/dispatch.js";
+import type { DispatchArgs, DispatchOutcome } from "../runtime/subagents/dispatch.js";
+import { SubagentMessages } from "../runtime/subagents/messages.js";
 import { SubagentsService } from "../runtime/subagents/subagents.service.js";
 import { ApprovalsService } from "./approvals.service.js";
 import { Breaker } from "./breaker.js";
-import { type AgentToolInputT } from "./builtins/agent.js";
 import { Credentials } from "./credentials.js";
 import { ToolDrift } from "./drift.js";
+import { OrgToolSwitches } from "./org-tool-switches.js";
 import { ToolOutputs } from "./outputs.js";
 import { QuestionsService } from "./questions.service.js";
-import { type ResolvedTool, ToolRegistry } from "./registry.js";
+import { type CallPolicy, type ResolvedTool, ToolRegistry } from "./registry.js";
 /** 审批被拒绝。 */
 export declare const APPROVAL_DENIED_TEXT = "The user denied this tool call.";
 /**
@@ -33,6 +35,13 @@ export declare const approvalExpiredText: (hours: number) => string;
 export declare const APPROVAL_CANCELLED_TEXT = "The run was stopped while waiting for approval.";
 /** 等待用户输入期间 run 被中止。 */
 export declare const INPUT_CANCELLED_TEXT = "The run was stopped while waiting for user input.";
+/**
+ * The result of an `AskUserQuestion` call whose question the user skipped by sending a message
+ * (reply-while-question spec §7.1): the message follows in the log as an ordinary user message.
+ */
+export declare const QUESTION_SKIPPED_TEXT = "The user did not answer this question and sent a message instead; read it below and continue.";
+/** The result of any other tool's input request (extension `input_required`, MCP elicitation) skipped by a message. */
+export declare const INPUT_SKIPPED_TEXT = "The user did not provide the requested input and sent a message instead; read it below and continue. Call the tool again only if it is still needed.";
 /** 同一调用连续请求输入超过上限。 */
 export declare const TOO_MANY_INPUT_REQUESTS_TEXT = "Tool requested user input too many times.";
 /** run 已被中止 / 到达截止时间，调用尚未开始执行。 */
@@ -63,7 +72,7 @@ export interface AskRequest {
  * policy, a fixed ask (R3, `requiresUserInteraction`), the org's `sandboxToolPolicy`, or the tool's
  * own default. `org` and `fixed` were added after the first B events (older logs say `default`).
  */
-export type ApprovalPolicySource = "agent" | "connector" | "default" | "role" | "org" | "fixed";
+export type ApprovalPolicySource = "agent" | "connector" | "member" | "default" | "role" | "org" | "fixed";
 /**
  * `unavailable`：调用那一刻工具已不可用（连接器 / 工具不存在、停用、删除、待审核），值为事实原因；
  * 管线写「工具不可用」说明，而不是「策略拒绝」。
@@ -85,16 +94,26 @@ export interface PolicyContext {
     conversationId: string;
     runId: string;
     /**
-     * A sub-agent's call: its parent conversation, where "approve for this conversation" grants are
-     * looked up (sub-agents spec §9).
+     * A sub-agent's call: its parent conversation, whose agent's current policies apply on top
+     * (sub-agents spec §5.5).
      */
     parentConversationId?: string;
+    /**
+     * A sub-agent's call: the root conversation of its tree, where "approve for this conversation"
+     * grants are stored and looked up (agent map spec §7), so every agent of the tree uses them.
+     */
+    rootConversationId?: string;
     /**
      * False when the sub-agent runs its parent conversation's agent (a template or general-purpose
      * child): the parent agent's policies were already read as its own, so no second read. Unset:
      * read and compare.
      */
     parentAgentDiffers?: boolean;
+    /**
+     * The call's per-call policy ({@link ResolvedTool.callPolicy} of the validated input), or
+     * null / unset: policies, grants and approvals use the tool key.
+     */
+    callPolicy?: CallPolicy | null;
 }
 /** 管线第 3 阶段：策略判定。 */
 export type DecidePolicy = (tool: ResolvedTool, agentDef: AgentDefinition, ctx: PolicyContext) => Promise<PolicyDecision>;
@@ -132,8 +151,16 @@ interface PipelineDeps {
      */
     readonly pluginHooks: HookRunner | undefined;
     /**
-     * Ids of an extension's `inline` ui contributions (read live, no alias): a plugin tool's
-     * `ToolResult.card` must name one of them, otherwise it is dropped with a warning.
+     * The effective deployment config of an extension for an org (layering spec A §6): a plugin
+     * tool's handler gets it as `ToolCallContext.config`, and is not called when it is not valid.
+     */
+    readonly effective: Pick<EffectiveConfigs, "get">;
+    /** The org's switches of single extension tools: a turned-off one is not called (spec A §7). */
+    readonly switches: Pick<OrgToolSwitches, "isToolOff">;
+    /**
+     * Ids of an extension's `conversation.tool-result.card` contributions of any kind (view, embed
+     * or component; read live, no alias): a plugin tool's `ToolResult.card` must name one of them,
+     * otherwise it is dropped with a warning.
      */
     inlineViews(plugin: string): ReadonlySet<string>;
     /**
@@ -142,16 +169,17 @@ interface PipelineDeps {
      */
     onToolsChanged(orgId: string, connectorId: string): void;
     /**
-     * Dispatches the sub-agent of an `agent` call (sub-agents spec §7.1; `dispatchSubagent`). Without
-     * it, `agent` calls reach the builtin's guard, which refuses them.
+     * Dispatches the sub-agent of an `Agent` call (sub-agents spec §7.1; `dispatchSubagent`). Without
+     * it, `Agent` calls reach the builtin's guard, which refuses them.
      */
     readonly subagents: {
-        dispatch(a: {
-            ctx: ToolStepContext;
-            callId: string;
-            input: AgentToolInputT;
-        }): Promise<DispatchOutcome>;
+        dispatch(a: DispatchArgs): Promise<DispatchOutcome>;
     } | undefined;
+    /**
+     * `SendMessage` and `SubagentHandback` (agent map spec §4.2, §4.3; `SubagentMessages`). Without
+     * it, their calls reach the builtins' guards, which refuse them.
+     */
+    readonly messages: Pick<SubagentMessages, "toChild" | "toParent"> | undefined;
 }
 /** The sub-agent dispatch the pipeline calls (`SubagentsService.dispatch`). */
 export type SubagentDispatch = NonNullable<PipelineDeps["subagents"]>["dispatch"];
@@ -174,8 +202,8 @@ export interface ToolStepContext {
     /** Hooks fire only for `chat` conversations. */
     conversationKind?: ConversationKindForHooks;
     /**
-     * Set when the run is a sub-agent's: its builtin tools use the parent conversation's sandbox
-     * (spec §10.1) and it cannot dispatch sub-agents.
+     * Set when the run is a sub-agent's: its builtin tools use the root conversation's sandbox
+     * (spec §10.1, agent map spec §6), and it dispatches sub-agents only below `subagents.maxDepth`.
      */
     parent?: SubagentParent;
 }
@@ -229,10 +257,12 @@ export declare class ToolPipeline {
     private readonly decide;
     private readonly deps;
     constructor(kdb: KernelDb, eventLog: EventLog, 
-    /** The `agent` tool's sub-agent dispatch; absent (tests): `agent` calls are refused. */
-    subagents: Pick<SubagentsService, "dispatch"> | undefined, registry: Pick<ToolRegistry, "forAgent" | "findConnector" | "handler">, credentials: Pick<Credentials, "injection" | "onUnauthorized">, breaker: Pick<Breaker, "check" | "failure" | "success">, outputs: Pick<ToolOutputs, "save" | "load">, approvals: Pick<ApprovalsService, "request" | "forCall">, questions: Pick<QuestionsService, "ask" | "forCall">, config: Pick<KernelConfigService, "get">, log: Logger, 
+    /** The `Agent` tool's sub-agent dispatch; absent (tests): `Agent` calls are refused. */
+    subagents: Pick<SubagentsService, "dispatch"> | undefined, 
+    /** The message tools between agents; absent (tests): their calls are refused. */
+    messages: Pick<SubagentMessages, "toChild" | "toParent"> | undefined, registry: Pick<ToolRegistry, "forAgent" | "findConnector" | "handler">, credentials: Pick<Credentials, "injection" | "onUnauthorized">, breaker: Pick<Breaker, "check" | "failure" | "success">, outputs: Pick<ToolOutputs, "save" | "load">, approvals: Pick<ApprovalsService, "request" | "forCall">, questions: Pick<QuestionsService, "ask" | "forCall">, config: Pick<KernelConfigService, "get">, log: Logger, 
     /** Plugin hooks and inline ui contributions; absent (tests): no hooks, cards dropped. */
-    host: Pick<ExtensionHost, "hooks" | "current"> | undefined, drift: Pick<ToolDrift, "onToolsChanged"> | undefined, txHost: TransactionHost, hooks?: ToolPipelineHooks);
+    host: Pick<ExtensionHost, "hooks" | "current"> | undefined, drift: Pick<ToolDrift, "onToolsChanged"> | undefined, effective: Pick<EffectiveConfigs, "get">, switches: Pick<OrgToolSwitches, "isToolOff">, txHost: TransactionHost, hooks?: ToolPipelineHooks);
     /**
      * tools 节点：按顺序处理本步 assistant 消息里的全部 `tool_call`，每个调用都以一条 `tool_result` 结束
      * （之后才回到 prepare 构建下一次请求，保持「已记录调用、未记录结果之间不构建请求」的不变式）。
@@ -242,32 +272,14 @@ export declare class ToolPipeline {
      */
     runStep(ctx: ToolStepContext): Promise<ToolStepOutcome>;
     /**
-     * An `agent` call that was dispatched (spec §7.1 "already dispatched"): when its child run is
-     * terminal, writes the parent's `subagent_finished` (if the child's finisher did not) and the
-     * call's `tool_result` from the child's log, and returns true; else false (still open).
-     *
-     * The call ran like any tool, so the result is audited `tool.called` (duration = the child's;
-     * the authorization is known only when an approval let it run: a policy or remembered grant at
-     * dispatch time is not recorded, so nothing is guessed) and fires `tool.postExecute` with the
-     * result, from the replica that writes it (spec §11).
+     * Writes, in the caller's transaction (`mandatory`), what a run that is being stopped (a person,
+     * its deadline, a failure, the wait sweep) still owes its log: the report of its fork invocation
+     * (phase D, `pairStoppedForks`; a still active fork child is stopped by the caller after its
+     * commit). An `Agent` call has its result from its dispatch (agent map spec §4.1), so there is
+     * nothing to write for it. Returns the fork's call id (the caller must not write a "not executed"
+     * result for it), the highest seq written, and `fire`, a no-op kept for the callers' hook phase.
      */
-    private finishAgentCall;
-    /** {@link stopOpenAgentCalls} in a transaction of its own (a stop seen by the tools node). */
-    private stopOpenAgentCallsNow;
-    /**
-     * Writes, in the caller's transaction (`mandatory`), the `tool_result` of every open `agent` call
-     * of a run that is being stopped
-     * (sub-agents spec §12: a person stopped it while it waited on sub-agents, or its deadline or a
-     * stop hit its tools node after a dispatch). A call whose child already ended gets the child's
-     * result (and the missing `subagent_finished`); one whose child is still active gets
-     * {@link AGENT_STOPPED_WITH_RUN_TEXT}. The caller stops those children after its commit.
-     *
-     * Like every `agent` result (see {@link finishAgentCall}), each is audited `tool.called` in it
-     * (duration: the child's, or the time since the dispatch) and fires `tool.postExecute`, through
-     * `fire()`, which the caller runs after its commit. Returns the steps and calls written (the
-     * caller must not write a "not executed" result for them) and the highest seq written.
-     */
-    stopOpenAgentCalls(runId: string, agent?: AgentDefinition): Promise<{
+    stopOpenAgentCalls(runId: string): Promise<{
         steps: number[];
         callIds: Set<string>;
         toSeq: number | null;
@@ -280,9 +292,17 @@ export declare class ToolPipeline {
      */
     private processCall;
     private runCall;
+    /** Appends a sub-agent's connect card to its root conversation ({@link rootSurfaceOf}). */
+    private surfaceConnectInRoot;
+    /**
+     * Every tool key the request that issued this step's calls offered (`request.tools` plus the
+     * `catalog` keys), in any mode; null when its model_call is not found. Used to tell a call to an
+     * old key that was offered (in flight across the rename) from one that never was.
+     */
+    private requestToolKeys;
     /**
      * 发出本步调用的请求里带了完整定义的工具 key：本步最后一次尝试的 `model_call.request.tools`
-     * （`assistant_message` 来自最后一次尝试）。该请求不在 tool_search 模式（没有 `catalog`，工具全部发送）
+     * （`assistant_message` 来自最后一次尝试）。该请求不在 ToolSearch 模式（没有 `catalog`，工具全部发送）
      * 或找不到 model_call 时返回 null（不做加载检查）。已加载集合由此从日志得出，不放进程内存。
      */
     private sentTools;