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

package/dist/tools/builtins/platform.d.ts

@@ -1,6 +1,8 @@
+import type { KernelLogger } from "../../log.js";
 import type { OrgSettings } from "../../orgs/settings.service.js";
 import type { ActorFacts } from "../../platform/actor.js";
 import type { AgentDocTopic } from "../../platform/agent-docs.js";
+import { type PlatformOperation } from "../../platform/operation.js";
 import type { PlatformOperations } from "../../platform/registry.js";
 import type { BuiltinTool, CallPolicyContext } from "../registry.js";
 /**
@@ -9,8 +11,12 @@ import type { BuiltinTool, CallPolicyContext } from "../registry.js";
  * - `browse` / `search` / `describe` / `read` only read; their policy is the tool's `allow`.
  * - `call` gets a per-call policy key `Platform:<operation>` ({@link BuiltinTool.callPolicy}): a
  *   read runs, a write asks (remembered only for `personal`), an operation that cannot run now is
- *   denied with its reason. Right before `op.run` the availability is checked again on fresh facts
- *   (the actor may have lost the role while the confirmation waited).
+ *   denied with its reason, and so is a write whose `precheck` knows it would fail (spec §14.2
+ *   item 2: no card). The policy is derived again when an approved call resumes, so a precheck
+ *   that fails by then returns its error and nothing runs. Right before `op.run` the availability
+ *   is checked again on fresh facts (the actor may have lost the role while the confirmation
+ *   waited).
+ * - An `ApiError` gets the next step the operation declares for its code and the actor's role.
  * - The actor, the agent and the conversation come from the runtime context, never from input.
  * - Results are JSON text; a list an operation returns is capped at {@link LIST_MAX} entries.
  */
@@ -30,5 +36,16 @@ export interface PlatformToolDeps {
     };
     /** The org setting `platformTool`. */
     setting(orgId: string): Promise<OrgSettings["platformTool"]>;
+    /** How long a precheck may take; default {@link PRECHECK_TIMEOUT_MS} (a test seam). */
+    precheckTimeoutMs?: number;
+    /** A precheck that throws is logged (warn) and one that times out (debug), with the op id. */
+    log?: Pick<KernelLogger, "warn"> & Partial<Pick<KernelLogger, "debug">>;
 }
+/**
+ * An operation's input keys as `browse` and `search` show them, so a call needs no guess:
+ * `"itemId"`, `"agentId, updatedAt, avatar?, quickActions?"` (`?` = optional), `""` when it takes
+ * none. A union input lists the keys of every branch; a key is required when every branch requires
+ * it. Types, bounds and an example stay in `describe`.
+ */
+export declare function paramsLine(op: PlatformOperation): string;
 export declare function platformTool(deps: PlatformToolDeps): BuiltinTool;

package/dist/tools/builtins/platform.js

@@ -1,9 +1,9 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { availability } from "../../platform/availability.js";
-import { toToolError } from "../../platform/errors.js";
+import { errorRoleOf, errorsFor, nextStepFor, OPERATION_ERROR_NEXT, resolveNext, sentence, toToolError, } from "../../platform/errors.js";
 import { PLATFORM_METHOD } from "../../platform/method.js";
-import { OPERATION_ID, operationDomain, } from "../../platform/operation.js";
+import { OPERATION_ID, operationDomain, PRECHECK_TIMEOUT_MS, } from "../../platform/operation.js";
 import { BUILTIN } from "../builtin-names.js";
 /**
  * The `Platform` builtin (Platform tool spec §3–§6): one tool through which an agent discovers and
@@ -11,8 +11,12 @@ import { BUILTIN } from "../builtin-names.js";
  * - `browse` / `search` / `describe` / `read` only read; their policy is the tool's `allow`.
  * - `call` gets a per-call policy key `Platform:<operation>` ({@link BuiltinTool.callPolicy}): a
  *   read runs, a write asks (remembered only for `personal`), an operation that cannot run now is
- *   denied with its reason. Right before `op.run` the availability is checked again on fresh facts
- *   (the actor may have lost the role while the confirmation waited).
+ *   denied with its reason, and so is a write whose `precheck` knows it would fail (spec §14.2
+ *   item 2: no card). The policy is derived again when an approved call resumes, so a precheck
+ *   that fails by then returns its error and nothing runs. Right before `op.run` the availability
+ *   is checked again on fresh facts (the actor may have lost the role while the confirmation
+ *   waited).
+ * - An `ApiError` gets the next step the operation declares for its code and the actor's role.
  * - The actor, the agent and the conversation come from the runtime context, never from input.
  * - Results are JSON text; a list an operation returns is capped at {@link LIST_MAX} entries.
  */
@@ -25,11 +29,13 @@ export const PLATFORM_UNAVAILABLE_OFF = "The org turned the Platform tool off; a
 const ACTIONS = ["browse", "search", "describe", "call", "read"];
 const SPEC = {
     name: BUILTIN.Platform,
-    description: "Discover and use the platform's own operations (skills, agents, templates, plugins, " +
-        "marketplaces, requests, connectors, extensions) and its documentation, as the person you are " +
-        'working for. Start with action "browse", then "describe" an operation before you "call" it; ' +
-        'never guess parameters. Writes ask the person to confirm. Use "read" for how-to documentation ' +
-        "(plugin format, skills, extension points).",
+    description: "Discover and use the platform's own operations (agents, skills, templates, plugins, " +
+        "connectors, extensions, conversations, environments, models, evals, channels, requests, " +
+        "approvals and the inbox, org settings, and for admins accounts, orgs and the admin console) " +
+        'and its documentation, as the person you are working for. Start with action "browse", which ' +
+        'lists every domain, then "describe" an operation before you "call" it; never guess ' +
+        'parameters. Writes ask the person to confirm. Use "read" for how-to documentation (plugin ' +
+        "format, skills, extension points).",
     inputSchema: {
         type: "object",
         properties: {
@@ -86,11 +92,43 @@ const firstSentence = (text) => {
 };
 const kindOf = (op) => op.confirm === "read" ? "read" : "write";
 const availabilityFields = (a) => a.ok ? { available: true } : { available: false, reason: a.reason };
+/** The most input keys a `params` line names before it ends in `…`. */
+const PARAMS_MAX = 8;
+const paramsCache = new WeakMap();
+/**
+ * An operation's input keys as `browse` and `search` show them, so a call needs no guess:
+ * `"itemId"`, `"agentId, updatedAt, avatar?, quickActions?"` (`?` = optional), `""` when it takes
+ * none. A union input lists the keys of every branch; a key is required when every branch requires
+ * it. Types, bounds and an example stay in `describe`.
+ */
+export function paramsLine(op) {
+    const cached = paramsCache.get(op);
+    if (cached !== undefined)
+        return cached;
+    const schema = z.toJSONSchema(op.input, {
+        io: "input",
+        unrepresentable: "any",
+    });
+    const branches = schema.anyOf ?? schema.oneOf ?? [schema];
+    const keys = [];
+    for (const b of branches) {
+        for (const k of Object.keys(b.properties ?? {}))
+            if (!keys.includes(k))
+                keys.push(k);
+    }
+    const required = (k) => branches.every((b) => b.required?.includes(k) ?? false);
+    const ordered = [...keys.filter(required), ...keys.filter((k) => !required(k))];
+    const names = ordered.map((k) => (required(k) ? k : `${k}?`));
+    const text = names.length > PARAMS_MAX ? `${names.slice(0, PARAMS_MAX).join(", ")}, …` : names.join(", ");
+    paramsCache.set(op, text);
+    return text;
+}
 /** One operation as `browse` and `search` list it. */
 const line = (op, facts) => ({
     id: op.id,
     description: firstSentence(op.description),
     kind: kindOf(op),
+    params: paramsLine(op),
     ...availabilityFields(availability(op, facts)),
 });
 const capped = (items) => ({
@@ -115,6 +153,7 @@ const unknownOperationText = (id) => `Unknown operation "${id}". Use browse or s
 const missingText = (action, field, what) => `Action ${action} needs "${field}": pass ${what}.`;
 const invalidParamsText = (id, problems) => `Invalid params for ${id}: ${problems}. Call describe with operation "${id}" for its input schema and an example, then call again.`;
 const unavailableOpText = (id, reason) => `Operation ${id} is unavailable, so do not call it again as is: ${reason}`;
+const precheckText = (id, code, message, next) => `Operation ${id} cannot run now: ${code}: ${sentence(message)} ${next ?? OPERATION_ERROR_NEXT}`;
 const outputRefText = (id) => `Operation ${id} writes, and its params hold a {"$output": ...} reference, which the person confirming would see instead of the content. Pass the content inline in params and call again.`;
 /** Whether a value holds a `{"$output": …}` reference anywhere (the pipeline's form). */
 function hasOutputRef(v) {
@@ -157,13 +196,14 @@ function paramsOf(op, params) {
  * The operation context of a confirmation (`confirmFor`, `summary`): the runtime's ids, never
  * input. Nothing aborts it; it only reads.
  */
-const confirmCtx = (ctx) => ({
+const confirmCtx = (ctx, errorRole) => ({
     orgId: ctx.orgId,
     actorAccountId: ctx.accountId,
     agentId: ctx.agentId,
     conversationId: ctx.conversationId,
     runId: ctx.runId,
     signal: new AbortController().signal,
+    errorRole,
 });
 const factsCtx = (ctx) => ({
     orgId: ctx.orgId,
@@ -198,7 +238,8 @@ export function platformTool(deps) {
                 return deny(e.message);
             throw e;
         }
-        const verdict = availability(op, await facts(ctx));
+        const f = await facts(ctx);
+        const verdict = availability(op, f);
         if (!verdict.ok)
             return deny(unavailableOpText(op.id, verdict.reason));
         if (op.confirm === "read")
@@ -207,7 +248,13 @@ export function platformTool(deps) {
         if (hasOutputRef(ctx.rawInput?.params)) {
             return deny(outputRefText(op.id));
         }
-        const octx = confirmCtx(ctx);
+        const role = errorRoleOf(f);
+        const failed = await precheckOf(op, params, ctx, role, deps.precheckTimeoutMs ?? PRECHECK_TIMEOUT_MS, deps.log);
+        if (failed !== null) {
+            const next = resolveNext(failed.next, role) ?? nextStepFor(op.errors, failed.code, role);
+            return deny(precheckText(op.id, failed.code, failed.message, next));
+        }
+        const octx = confirmCtx(ctx, role);
         const [cls, summary] = await Promise.all([
             classOf(op, params, octx),
             summaryOf(op, params, octx),
@@ -216,7 +263,7 @@ export function platformTool(deps) {
             key,
             policy: "ask",
             // org / platform writes are confirmed every time (spec §6.2)
-            remember: cls === "personal",
+            remember: cls === "personal" && op.rememberable !== false,
             summary,
         };
     }
@@ -280,7 +327,8 @@ export function platformTool(deps) {
             confirm: op.confirm,
             inputSchema: z.toJSONSchema(op.input, { io: "input", unrepresentable: "any" }),
             example: op.example,
-            ...(op.errors !== undefined && op.errors.length > 0 && { errors: op.errors }),
+            ...(op.errors !== undefined &&
+                op.errors.length > 0 && { errors: errorsFor(op.errors, errorRoleOf(f)) }),
             ...availabilityFields(availability(op, f)),
             related: deps.ops
                 .inDomain(operationDomain(op.id))
@@ -292,9 +340,11 @@ export function platformTool(deps) {
         const op = operationOf(deps, "call", input.operation);
         const params = paramsOf(op, input.params);
         // fresh facts right before running: the role may be gone since the confirmation (Review Focus 3)
-        const verdict = availability(op, await facts(factsCtx(ctx)));
+        const f = await facts(factsCtx(ctx));
+        const verdict = availability(op, f);
         if (!verdict.ok)
             throw new ToolError(unavailableOpText(op.id, verdict.reason));
+        const role = errorRoleOf(f);
         let result;
         try {
             result = await op.run(params, {
@@ -303,11 +353,15 @@ export function platformTool(deps) {
                 agentId: ctx.agentId,
                 conversationId: ctx.conversationId,
                 runId: ctx.runId ?? null,
+                callId: ctx.callId,
                 signal: ctx.signal,
+                errorRole: role,
             });
         }
         catch (e) {
-            throw toToolError(e);
+            // a service refusal after the approval (a race the precheck could not see) still names the
+            // next step for this actor (Review Focus 2)
+            throw toToolError(e, (code) => nextStepFor(op.errors, code, role));
         }
         return json(asResult(result), { zh: `调用平台操作 ${op.id}`, en: `Called ${op.id}` });
     }
@@ -348,6 +402,41 @@ async function classOf(op, params, ctx) {
         return "org";
     }
 }
+/**
+ * The operation's precheck, bounded by `ms`: the failure it found, or null (none, passed, timed
+ * out, or threw: the write's own errors speak then; a throw is logged as a warning, a timeout at
+ * debug). Its signal aborts at the timeout or when the run's signal aborts.
+ */
+async function precheckOf(op, params, ctx, role, ms, log) {
+    if (op.precheck === undefined)
+        return null;
+    const ac = new AbortController();
+    const signal = ctx.signal === undefined ? ac.signal : AbortSignal.any([ac.signal, ctx.signal]);
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ac.abort();
+            log?.debug?.("platform precheck timed out; the card is shown", { operation: op.id, ms });
+            resolve(null);
+        }, ms);
+    });
+    try {
+        const r = await Promise.race([
+            op.precheck(params, { ...confirmCtx(ctx, role), signal }),
+            timeout,
+        ]);
+        if (r === null || r.ok)
+            return null;
+        return { code: r.code, message: r.message, ...(r.next !== undefined && { next: r.next }) };
+    }
+    catch (err) {
+        log?.warn("platform precheck failed; the card is shown", { operation: op.id, err });
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** The card summary of a write, rendered from the validated params and kernel reads. */
 async function summaryOf(op, params, ctx) {
     try {

package/dist/tools/connectors.controller.d.ts

@@ -1,9 +1,8 @@
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { CredentialValue } from "./connectors.schemas.js";
 import { type ConnectorDetail, type ConnectorPreview, type ConnectorSummary, ConnectorsService, type ToolIssue } from "./connectors.service.js";
-/** 凭据值：形状由 `Credentials.validate` 按认证方式校验（不回显值）；这里只限大小。 */
-export declare const CredentialValue: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 declare const CreateBody: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;

package/dist/tools/connectors.controller.js

@@ -15,6 +15,7 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { can } from "../orgs/roles.js";
+import { CredentialValue } from "./connectors.schemas.js";
 import { ConnectorsService, } from "./connectors.service.js";
 import { publicEndpoint } from "./endpoint.js";
 /**
@@ -34,10 +35,6 @@ function forViewer(org, c) {
     }
     return view;
 }
-/** 凭据值：形状由 `Credentials.validate` 按认证方式校验（不回显值）；这里只限大小。 */
-export const CredentialValue = z
-    .record(z.string().max(100), z.unknown())
-    .refine((v) => JSON.stringify(v).length <= 16_384, { message: "Credential is too large" });
 const CreateBody = z
     .object({
     name: z.string().trim().min(1).max(80),

package/dist/tools/connectors.schemas.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/**
+ * A credential value: `Credentials.validate` checks its shape by auth method (values are never
+ * echoed); this only bounds its size.
+ */
+export declare const CredentialValue: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** `:connectorId` as the routes take it (`@Param`). */
+export declare const ConnectorPathParams: z.ZodObject<{
+    connectorId: z.ZodString;
+}, z.core.$strip>;
+export declare const CONNECTOR_ROUTES: readonly RouteSchemas[];

package/dist/tools/connectors.schemas.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * A credential value: `Credentials.validate` checks its shape by auth method (values are never
+ * echoed); this only bounds its size.
+ */
+export const CredentialValue = z
+    .record(z.string().max(100), z.unknown())
+    .refine((v) => JSON.stringify(v).length <= 16_384, { message: "Credential is too large" });
+/** `:connectorId` as the routes take it (`@Param`). */
+export const ConnectorPathParams = z.object({ connectorId: z.string().min(1) });
+export const CONNECTOR_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/connectors" },
+    { route: "GET /api/v1/orgs/:orgId/connectors/:connectorId", params: ConnectorPathParams },
+    { route: "DELETE /api/v1/orgs/:orgId/connectors/:connectorId", params: ConnectorPathParams },
+    {
+        route: "POST /api/v1/orgs/:orgId/connectors/:connectorId/refresh",
+        params: ConnectorPathParams,
+    },
+];

package/dist/tools/connectors.service.d.ts

@@ -309,14 +309,16 @@ export declare class ConnectorsService {
     /** 改名、启停连接器、工具启停与默认策略、批量把无注解工具改为 allow（`connectors.manage`）。 */
     update(orgId: string, connectorId: string, actorAccountId: string, patch: UpdateConnectorInput, actorTokenId?: string): Promise<ConnectorDetail>;
     /** 软删除，并删除该连接器的全部凭据（`connectors.manage`）。 */
-    remove(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    remove(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
     /**
      * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
      * 审计 `connector.deleted`（`reason` 并进 detail）。已删除 / 不存在 → `connector.not_found`。
      */
     removeIn(orgId: string, connectorId: string, 
     /** null: the kernel itself (the plugin scope sync uninstalling a plugin). */
-    actorAccountId: string | null, actorTokenId?: string, reason?: string): Promise<void>;
+    actorAccountId: string | null, actorTokenId?: string, reason?: string, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail?: Record<string, unknown>): Promise<void>;
     /**
      * 重新 listTools 并按漂移检测的规则比对写入（见 drift.ts）：新增 / 定义变化的工具待复核（旧定义保留供对比），
      * 消失的工具停用；连接器从未拍过快照时首个快照直接启用。
@@ -326,6 +328,7 @@ export declare class ConnectorsService {
      */
     refresh(orgId: string, connectorId: string, actorAccountId: string, actorTokenId?: string, opts?: {
         trigger?: "first_connect";
+        auditDetail?: Record<string, unknown>;
     }): Promise<{
         connector: ConnectorDetail;
         issues: ToolIssue[];

package/dist/tools/connectors.service.js

@@ -960,9 +960,9 @@ let ConnectorsService = class ConnectorsService {
         return this.detail(t, orgId, connectorId, actorAccountId);
     }
     /** 软删除，并删除该连接器的全部凭据（`connectors.manage`）。 */
-    async remove(orgId, connectorId, actorAccountId, actorTokenId) {
+    async remove(orgId, connectorId, actorAccountId, actorTokenId, auditDetail) {
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "connectors.manage");
-        await this.removeIn(orgId, connectorId, actorAccountId, actorTokenId);
+        await this.removeIn(orgId, connectorId, actorAccountId, actorTokenId, undefined, auditDetail);
     }
     /**
      * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
@@ -970,7 +970,9 @@ let ConnectorsService = class ConnectorsService {
      */
     async removeIn(orgId, connectorId, 
     /** null: the kernel itself (the plugin scope sync uninstalling a plugin). */
-    actorAccountId, actorTokenId, reason) {
+    actorAccountId, actorTokenId, reason, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
         const t = this.db;
         const app = await this.row(t, orgId, connectorId, true);
         await t
@@ -991,7 +993,7 @@ let ConnectorsService = class ConnectorsService {
             orgId,
             action: "connector.deleted",
             target: connectorId,
-            detail: { slug: app.slug, ...(reason !== undefined && { reason }) },
+            detail: { slug: app.slug, ...(reason !== undefined && { reason }), ...auditDetail },
         });
     }
     /**
@@ -1033,7 +1035,7 @@ let ConnectorsService = class ConnectorsService {
             orgId,
             action: "connector.tools_refreshed",
             target: connectorId,
-            detail: { ...changes, ...(opts.trigger && { trigger: opts.trigger }) },
+            detail: { ...changes, ...(opts.trigger && { trigger: opts.trigger }), ...opts.auditDetail },
         });
         return {
             connector: await this.detail(t, orgId, connectorId, actorAccountId),

package/dist/tools/org-tool-switches.d.ts

@@ -54,13 +54,22 @@ export declare class OrgToolSwitches {
     private offRows;
     /** Every tool the extension registers on this replica with its switch (default on). */
     list(orgId: string, plugin: string): Promise<OrgToolSwitch[]>;
+    /**
+     * 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`.
+     */
+    previewOff(orgId: string, plugin: string, tool: string): Promise<{
+        affectedAgents: AffectedAgent[];
+        confirm: string;
+    } | null>;
     /** The model-visible keys (`plugin__<extension>__<tool>`) of the tools turned off in the org. */
     offKeys(orgId: string): Promise<Set<string>>;
     /** Whether the org turned off this tool. */
     isToolOff(orgId: string, plugin: string, tool: string): Promise<boolean>;
     /**
      * 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 selects the tool) and its hash,
+     * `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`.
@@ -68,7 +77,12 @@ export declare class OrgToolSwitches {
     set(orgId: string, plugin: string, tool: string, enabled: boolean, actor: {
         accountId: string;
         tokenId?: string | undefined;
+        /** Merged into the audit detail (a write made through the Platform tool). */
+        auditDetail?: Record<string, unknown>;
     }, confirm?: string): Promise<OrgToolSwitchResult>;
-    /** The org's live agents whose current version selects `{kind:"plugin", plugin, name: tool}`. */
+    /**
+     * 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.
+     */
     private agentsSelecting;
 }

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

@@ -11,6 +11,7 @@ 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";
@@ -88,6 +89,21 @@ let OrgToolSwitches = class OrgToolSwitches {
         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)));
@@ -105,7 +121,7 @@ let OrgToolSwitches = class OrgToolSwitches {
     }
     /**
      * 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 selects the tool) and its hash,
+     * `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`.
@@ -143,11 +159,14 @@ let OrgToolSwitches = class OrgToolSwitches {
             orgId,
             action: "extension.tool_switched",
             target: extensionToolKey(plugin, tool),
-            detail: { plugin, tool, from, to: enabled },
+            detail: { plugin, tool, from, to: enabled, ...actor.auditDetail },
         });
         return { applied: true };
     }
-    /** The org's live agents whose current version selects `{kind:"plugin", plugin, name: tool}`. */
+    /**
+     * 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")
@@ -160,12 +179,10 @@ let OrgToolSwitches = class OrgToolSwitches {
         const out = [];
         for (const r of rows) {
             const def = r.definition;
-            const refs = Array.isArray(def?.tools) ? def.tools : [];
-            const selects = refs.some((x) => {
-                const ref = x;
-                return ref?.kind === "plugin" && ref.plugin === plugin && ref.name === tool;
-            });
-            if (selects)
+            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;

package/dist/tools/pipeline.js

@@ -243,7 +243,8 @@ let ToolPipeline = class ToolPipeline {
                 // skill invocation in the log → Skill is offered (see skillLoadOffered)
                 const skillLoad = await skillLoadOfferedIn(this.deps.db, this.deps.eventLog, ctx.conversationId);
                 resolved = await this.deps.registry.forAgent(ctx.orgId, {
-                    tools: ctx.agent.tools ?? [],
+                    disabledTools: ctx.agent.disabledTools,
+                    subagentTools: ctx.agent.subagentTools,
                     skillLoad,
                     subagents: ctx.agent.subagents,
                     child: ctx.parent !== undefined,
@@ -384,6 +385,7 @@ let ToolPipeline = class ToolPipeline {
             conversationId: ctx.conversationId,
             runId: ctx.runId,
             rawInput,
+            signal: ctx.signal,
         })) ?? null;
         // a deny with a reason (e.g. an unavailable operation): the reason is the tool error
         if (callPolicy?.policy === "deny" && callPolicy.denyReason !== undefined) {