@steerable/agent-shell 0.6.15

package/dist/llm/sidecar-provider.js

@@ -0,0 +1,163 @@
+/**
+ * `LlmProvider` implementation that delegates to the steerable-sidecar's
+ * `agent.chat.stream` JSON-RPC method.
+ *
+ * Activation:
+ *   Default-on once the sidecar is supervised (see `llm/index.ts`);
+ *   `STEERABLE_USE_SIDECAR=0` opts back out to in-process providers.
+ *
+ * The sidecar must already be supervised by the main process (see
+ * `src/sidecar/supervisor.ts`); this provider just routes calls through the
+ * supplied supervisor handle and aggregates streamed chunks back into the
+ * existing `LlmGenerateResult` shape so the rest of the local backend (router,
+ * harness, transcript) keeps working unchanged.
+ *
+ * NOTE: this is the first half of P5-agent-refactor. Tools are still dispatched
+ * by the local TS `ToolRouter`; tool-call delegation to the sidecar's
+ * `tool.invoke` method is tracked under p5-agent-refactor-phase2.
+ */
+export class SidecarLlmProvider {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async listModels() {
+        // The sidecar serves the gateway's live catalog (`models.list`); the
+        // configured model stays as fallback for the offline state so callers
+        // of this plain-id interface never see an empty list.
+        try {
+            const catalog = await this.options.supervisor.listModels({
+                baseUrl: this.options.baseUrl,
+                apiKey: this.options.apiKey,
+                provider: this.options.provider,
+            });
+            if (catalog.models.length > 0) {
+                return catalog.models.map((entry) => entry.id);
+            }
+        }
+        catch {
+            // transport/timeout — fall through to the configured model
+        }
+        return [this.options.model];
+    }
+    async generate(request) {
+        return this._stream(request);
+    }
+    async generateStream(request) {
+        return this._stream(request);
+    }
+    async _stream(request) {
+        const callbacks = request.callbacks;
+        const signal = request.signal;
+        let assembled = '';
+        const toolCalls = [];
+        let tokensUsed;
+        if (signal?.aborted) {
+            throw new DOMException('The operation was aborted.', 'AbortError');
+        }
+        return await new Promise((resolve, reject) => {
+            let streamIdRef = null;
+            let settled = false;
+            // `streamChat` only starts rejecting `stream.chunk`/`stream.done` events
+            // once it has a `streamId`; if the caller aborts before that resolves
+            // there's nothing to cancel yet, so we forward the abort as soon as it's
+            // available instead of silently letting the sidecar keep generating.
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                if (streamIdRef) {
+                    void this.options.supervisor.cancelChat(streamIdRef);
+                }
+                reject(new DOMException('The operation was aborted.', 'AbortError'));
+            };
+            signal?.addEventListener('abort', onAbort);
+            const cleanup = () => signal?.removeEventListener('abort', onAbort);
+            void this.options.supervisor
+                .streamChat({
+                provider: this.options.provider,
+                model: request.model || this.options.model,
+                baseUrl: this.options.baseUrl,
+                apiKey: this.options.apiKey,
+                temperature: request.temperature ?? this.options.temperature,
+                messages: request.messages.map((m) => ({
+                    role: m.role,
+                    content: m.content,
+                    name: m.name,
+                    toolCallId: m.toolCallId,
+                    // 工具调用与推理必须随 assistant 消息回传：缺 toolCalls 时
+                    // 下一轮 role:'tool' 被判孤儿 400；thinking 模型（DeepSeek）
+                    // 缺 reasoningContent 同样 400。in-process openai-compat.ts
+                    // 的 mapMessage 是同一约束的参照实现。
+                    toolCalls: m.toolCalls?.map((c) => ({
+                        id: c.id,
+                        name: c.name,
+                        arguments: c.arguments,
+                    })),
+                    reasoningContent: m.reasoningContent,
+                })),
+                tools: request.tools?.map((t) => ({
+                    type: 'function',
+                    function: {
+                        name: t.name,
+                        description: t.description,
+                        parameters: t.inputSchema ?? { type: 'object', properties: {} },
+                    },
+                })),
+            }, {
+                onChunk: (chunk) => {
+                    if (chunk.delta) {
+                        assembled += chunk.delta;
+                        callbacks?.onToken?.(chunk.delta);
+                    }
+                    if (chunk.toolCall) {
+                        toolCalls.push({
+                            id: chunk.toolCall.id,
+                            name: chunk.toolCall.name,
+                            arguments: chunk.toolCall.arguments,
+                        });
+                    }
+                    if (chunk.usage) {
+                        tokensUsed = {
+                            prompt: chunk.usage.promptTokens,
+                            completion: chunk.usage.completionTokens,
+                            total: chunk.usage.totalTokens,
+                        };
+                    }
+                },
+                onDone: () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve({
+                        content: assembled,
+                        toolCalls,
+                        tokensUsed,
+                    });
+                },
+                onError: (err) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    reject(new Error(`sidecar chat stream failed: ${err.kind}: ${err.message}`));
+                },
+            })
+                .then((streamId) => {
+                streamIdRef = streamId;
+                // Abort arrived while `streamChat`'s initial RPC round-trip was
+                // still in flight — cancel it now that we finally have an id.
+                if (signal?.aborted && !settled)
+                    onAbort();
+            })
+                .catch((err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(err);
+            });
+        });
+    }
+}

package/dist/llm/tool-choice.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OpenAI 兼容网关上的 tool_choice 能力适配。
+ *
+ * 多家长的 thinking / reasoner 模型会拒 `tool_choice: "required"`
+ * （以及指定函数名的 object 形式），返回 400。这不是某一家的特例：
+ * DeepSeek V4、OpenAI o-series、Anthropic extended thinking 的兼容网关
+ * 都出现过。这里按**能力**处理，不绑厂商：
+ *
+ *   1. 模型名自我声明 thinking/reasoner/o-series → 出网前把 required 降成 auto
+ *   2. 未知模型仍发 required；若 400 报 tool_choice 不支持，降级重试并记住
+ */
+import type { LlmGenerateRequest } from './types.js';
+export type OpenAiToolChoice = NonNullable<LlmGenerateRequest['toolChoice']>;
+/** 去掉网关前缀（`openai/deepseek-v4-flash` → `deepseek-v4-flash`）。 */
+export declare function canonicalizeModelId(model: string | undefined): string;
+/**
+ * 模型 id 是否自我声明为 thinking / reasoner。
+ * 只看能力词和 OpenAI o-series 形态，不写厂商白名单。
+ * 名字里看不出来的（如 deepseek-v4-flash）走 400 降级重试。
+ */
+export declare function modelLikelyRejectsForcedToolChoice(model: string | undefined): boolean;
+/** 该模型是否已经（启发式或上次 400）判定不支持 forced tool_choice。 */
+export declare function rejectsForcedToolChoice(model: string | undefined): boolean;
+export declare function rememberForcedToolChoiceRejected(model: string | undefined): void;
+export declare function resetForcedToolChoiceCompatForTests(): void;
+/**
+ * 400 响应是否表示「当前 thinking/reasoner 模式不接受这个 tool_choice」。
+ * 按错误语义匹配，不绑某一家的文案。
+ */
+export declare function isForcedToolChoiceRejected(status: number, body: string): boolean;
+/**
+ * 把 harness 的 tool_choice 意图映射成当前模型吃得下的值。
+ * thinking/reasoner 上把 `required` 降成 `auto`；tools 仍照常下发。
+ */
+export declare function resolveOpenAiToolChoice(model: string | undefined, requested: LlmGenerateRequest['toolChoice']): OpenAiToolChoice;

package/dist/llm/tool-choice.js

@@ -0,0 +1,85 @@
+/**
+ * OpenAI 兼容网关上的 tool_choice 能力适配。
+ *
+ * 多家长的 thinking / reasoner 模型会拒 `tool_choice: "required"`
+ * （以及指定函数名的 object 形式），返回 400。这不是某一家的特例：
+ * DeepSeek V4、OpenAI o-series、Anthropic extended thinking 的兼容网关
+ * 都出现过。这里按**能力**处理，不绑厂商：
+ *
+ *   1. 模型名自我声明 thinking/reasoner/o-series → 出网前把 required 降成 auto
+ *   2. 未知模型仍发 required；若 400 报 tool_choice 不支持，降级重试并记住
+ */
+/** 本进程里已经确认拒 forced tool_choice 的模型（规范化 id）。 */
+const modelsRejectingForcedToolChoice = new Set();
+/** 去掉网关前缀（`openai/deepseek-v4-flash` → `deepseek-v4-flash`）。 */
+export function canonicalizeModelId(model) {
+    if (!model)
+        return '';
+    const trimmed = model.trim().toLowerCase();
+    const slash = trimmed.lastIndexOf('/');
+    return slash >= 0 ? trimmed.slice(slash + 1) : trimmed;
+}
+/**
+ * 模型 id 是否自我声明为 thinking / reasoner。
+ * 只看能力词和 OpenAI o-series 形态，不写厂商白名单。
+ * 名字里看不出来的（如 deepseek-v4-flash）走 400 降级重试。
+ */
+export function modelLikelyRejectsForcedToolChoice(model) {
+    const id = canonicalizeModelId(model);
+    if (!id)
+        return false;
+    if (id.includes('reasoner') ||
+        id.includes('reasoning') ||
+        id.includes('thinking')) {
+        return true;
+    }
+    // o1 / o3 / o4 / o1-mini / o3-pro —— 不要误伤 gpt-4o、grok
+    if (/(^|[^a-z0-9])o[1-9]([.-]|$)/.test(id))
+        return true;
+    return false;
+}
+/** 该模型是否已经（启发式或上次 400）判定不支持 forced tool_choice。 */
+export function rejectsForcedToolChoice(model) {
+    const id = canonicalizeModelId(model);
+    if (!id)
+        return false;
+    return modelsRejectingForcedToolChoice.has(id) || modelLikelyRejectsForcedToolChoice(id);
+}
+export function rememberForcedToolChoiceRejected(model) {
+    const id = canonicalizeModelId(model);
+    if (id)
+        modelsRejectingForcedToolChoice.add(id);
+}
+export function resetForcedToolChoiceCompatForTests() {
+    modelsRejectingForcedToolChoice.clear();
+}
+/**
+ * 400 响应是否表示「当前 thinking/reasoner 模式不接受这个 tool_choice」。
+ * 按错误语义匹配，不绑某一家的文案。
+ */
+export function isForcedToolChoiceRejected(status, body) {
+    if (status !== 400)
+        return false;
+    const text = body.toLowerCase();
+    if (!text.includes('tool_choice') && !text.includes('tool choice'))
+        return false;
+    return (text.includes('thinking') ||
+        text.includes('reason') ||
+        text.includes('does not support') ||
+        text.includes('not support') ||
+        text.includes('not supported') ||
+        text.includes('unsupported') ||
+        text.includes('cannot be used') ||
+        text.includes('incompatible'));
+}
+/**
+ * 把 harness 的 tool_choice 意图映射成当前模型吃得下的值。
+ * thinking/reasoner 上把 `required` 降成 `auto`；tools 仍照常下发。
+ */
+export function resolveOpenAiToolChoice(model, requested) {
+    const choice = requested ?? 'auto';
+    if (choice === 'required' && rejectsForcedToolChoice(model)) {
+        return 'auto';
+    }
+    return choice;
+}

package/dist/llm/types.d.ts

@@ -0,0 +1,122 @@
+export type LlmRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * W6-3: an image attached to a message, carried as base64 bytes. Produced
+ * host-side (see `image-attachment.ts`, which enforces byte/dimension caps
+ * and downscales) and serialized per-provider — OpenAI-compat as an
+ * `image_url` data-URL content part, the sidecar CoreLoop as a wire
+ * `ContentPart` (`{type:'image', data, mediaType}`).
+ */
+export interface LlmImage {
+    /** base64-encoded image bytes (no `data:` prefix). */
+    data: string;
+    /** MIME type, e.g. `image/png` / `image/jpeg`. */
+    mediaType: string;
+}
+export interface LlmMessage {
+    role: LlmRole;
+    content: string;
+    /**
+     * W6-3: images attached to this message (typically the current user
+     * turn). Kept out of `content` so the text projection stays clean for
+     * persistence/compaction; providers that support vision serialize these
+     * alongside the text.
+     */
+    images?: LlmImage[];
+    /** 仅 `role: 'tool'` 用，指向被回应的 assistant tool_call 的 id。 */
+    toolCallId?: string;
+    /** 仅 `role: 'tool'` 用，工具名（Ollama 兼容字段，OpenAI 严格协议忽略）。 */
+    name?: string;
+    /**
+     * 仅 `role: 'assistant'` 用：本轮 LLM 触发的工具调用。
+     *
+     * 为什么必须显式带：OpenAI 严格协议要求 `role: 'tool'` 消息**必须**紧跟在
+     * 一个带 `tool_calls` 字段的 assistant 消息之后；否则报
+     *   `Messages with role 'tool' must be a response to a preceding message with 'tool_calls'`
+     * （400）。早期实现只在 messages 里 push 一条 `{role:'assistant', content:''}`
+     * 占位 + 一条 `{role:'tool', ...}`，丢了 tool_calls 字段——Ollama 容忍这种
+     * 不规范序列，DeepSeek/OpenAI 严格校验直接拒。
+     */
+    toolCalls?: LlmToolCall[];
+    /**
+     * 仅 `role: 'assistant'` 用：DeepSeek thinking 模式 (deepseek-reasoner /
+     * deepseek-v4-*) 在 response.message 里会带一个 `reasoning_content` 字段
+     * 表示"思考链"。下一轮 API 调用时必须把它**原样塞回去**，否则报
+     *   "The `reasoning_content` in the thinking mode must be passed back to the API."
+     * （400）。非 thinking 模型（deepseek-chat / 通用 OpenAI 模型）此字段为空，
+     * provider 会跳过不发，不影响兼容。
+     */
+    reasoningContent?: string;
+}
+export interface LlmToolSchema {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+}
+export interface LlmToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface LlmGenerateRequest {
+    messages: LlmMessage[];
+    model: string;
+    temperature?: number;
+    tools?: LlmToolSchema[];
+    /**
+     * 工具选择约束（OpenAI 兼容 API 的 tool_choice）：
+     *   - 'auto'（默认）：模型自行决定是否调用工具；
+     *   - 'required'：本轮**必须**至少发起一个工具调用——用于 harness 路由判定
+     *     "该问题需要本轮新数据"后，从机制上保证模型先调工具再作答，
+     *     让"零工具编造数据"在生成阶段就不可能发生。
+     *   - 'none'：禁止调用工具。
+     * 仅 OpenAI 兼容 provider 支持；Ollama / sidecar 目前忽略此字段。
+     *
+     * thinking / reasoner 模型普遍不接受 `required`。OpenAICompatProvider 会
+     * 按能力启发式或 400 降级把它改成 `auto`，tools 仍照常下发。
+     */
+    toolChoice?: 'auto' | 'none' | 'required';
+    /**
+     * Cancellation signal. The router checks `signal.aborted` *between* turns
+     * and tool calls, but without threading it into the actual HTTP request,
+     * cancelling mid-generation didn't stop the in-flight LLM call — it just
+     * kept streaming tokens (and burning provider quota) until the response
+     * finished on its own, only then noticing the abort before the *next*
+     * turn. Providers should pass this straight into `fetch()`'s `signal`
+     * option (or the sidecar-RPC equivalent) so aborting actually tears down
+     * the underlying request.
+     */
+    signal?: AbortSignal;
+}
+export interface LlmGenerateResult {
+    content: string;
+    toolCalls: LlmToolCall[];
+    /**
+     * DeepSeek thinking 模式响应里的 `reasoning_content`（思考链文本）。
+     * 非 thinking 模型 / 非 DeepSeek 服务返回 undefined。需要在下一轮请求时
+     * 原样回传，见 LlmMessage.reasoningContent。
+     */
+    reasoningContent?: string;
+    tokensUsed?: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+    raw?: unknown;
+}
+export interface LlmStreamCallbacks {
+    /** 每收到一个新的文本片段时回调，可能多次。tool-call 阶段不回调。 */
+    onToken?: (token: string) => void;
+}
+export interface LlmGenerateStreamRequest extends LlmGenerateRequest {
+    callbacks?: LlmStreamCallbacks;
+}
+export interface LlmProvider {
+    listModels(): Promise<string[]>;
+    generate(request: LlmGenerateRequest): Promise<LlmGenerateResult>;
+    /**
+     * 真正的流式生成。Provider 内部建议走原生 SSE / NDJSON，
+     * 在每个增量到达时触发 `callbacks.onToken`，最后再返回聚合结果。
+     * 默认实现可以转调 generate（无流式）。
+     */
+    generateStream?(request: LlmGenerateStreamRequest): Promise<LlmGenerateResult>;
+}

package/dist/llm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/local-backend/agent-capability.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 智能体能力面解析（技能 + 工具准入）。
+ *
+ * 智能体在「智能体管理」页配置三件事，本模块把它们解析成本轮可执行的形态：
+ *
+ *   - `skillIds`            勾选的技能 → 正文无条件常驻注入（钉进 eager 层）
+ *   - `allowExternalSkills` false 时把勾选集变成硬白名单
+ *   - `toolPolicy`          模型可见工具的 allowlist / denylist
+ *
+ * 全是纯函数（不碰 electron / sqlite / sidecar），因为同一份解析结果要喂给
+ * 三个互相独立的执行点，任何一处漂移都会让「限制」变成假象：
+ *
+ *   1. 系统提示词注入   —— prompt-builder 的 `excludeSkillNames` / `pinnedSkillNames`
+ *   2. sidecar 技能目录 —— `SkillTurnContext.exclude`
+ *   3. 工具面           —— 每轮 `turnTools`、`tool_search` 结果、反向通道分发复检
+ *
+ * `@提及` 多个智能体的回合按「最宽松」合并：提及额外专家是为了叠加能力，
+ * 不应该反而让对话失去工具或技能（与 personaPreamble 的「同时具备以下 N 个
+ * 角色的能力」一致）。
+ */
+export type AgentToolPolicyMode = 'all' | 'allowlist' | 'denylist';
+export interface AgentToolPolicy {
+    mode: AgentToolPolicyMode;
+    tools: string[];
+}
+/** 一个智能体的技能/工具配置（{@link ChatAgentRecord} 的相关子集）。 */
+export interface AgentCapabilityInput {
+    skillIds: string[];
+    allowExternalSkills: boolean;
+    loadAllSkills: boolean;
+    toolPolicy: AgentToolPolicy;
+}
+/** 本轮生效的能力面（可能是多个被提及智能体的合并结果）。 */
+export interface AgentCapability {
+    /** 正文无条件注入的技能别名（dirName / name / displayName 皆可）。 */
+    pinnedSkills: string[];
+    /** false = 只允许 {@link pinnedSkills}（硬白名单）。 */
+    allowExternalSkills: boolean;
+    /** true = 无视技能触发条件全量加载。 */
+    loadAllSkills: boolean;
+    toolPolicy: AgentToolPolicy;
+}
+/** 无智能体绑定（或未配置）的回合：不钉技能、不限制。 */
+export declare const UNRESTRICTED_CAPABILITY: AgentCapability;
+/**
+ * 归一化外部传入（API payload / 旧库行）的工具策略。
+ *
+ * 空 `tools` 一律降级为 `all`：denylist 空集本就等于不限制，而「allowlist
+ * 空集」会让智能体一个工具都调不到——那不是任何人想要的配置，把它当作未
+ * 配置处理，避免用户在 UI 上手滑就把智能体废掉。
+ *
+ * @param raw 任意来源的候选值。
+ * @returns 合法的 {@link AgentToolPolicy}；无法识别时为 `{ mode: 'all', tools: [] }`。
+ */
+export declare function normalizeToolPolicy(raw: unknown): AgentToolPolicy;
+/**
+ * 单个工具是否被策略放行。
+ *
+ * @param policy 归一化后的策略。
+ * @param toolName 一等工具名（含 `mcp__<server>__<tool>` 全名）。
+ * @returns 放行为 true。
+ */
+export declare function isToolAllowed(policy: AgentToolPolicy, toolName: string): boolean;
+/**
+ * 按策略过滤一批工具 schema（保持入参顺序）。
+ *
+ * @param schemas 待过滤的 schema 列表。
+ * @param policy 归一化后的策略。
+ * @returns 放行的 schema 子集；`mode: 'all'` 时原样返回。
+ */
+export declare function filterToolsByPolicy<T extends {
+    name: string;
+}>(schemas: readonly T[], policy: AgentToolPolicy): T[];
+/**
+ * 合并本轮涉及的全部智能体的能力面，取最宽松。
+ *
+ * @param agents 按提及顺序排列的智能体配置；空数组表示无绑定。
+ * @returns 本轮生效的能力面；空数组时为 {@link UNRESTRICTED_CAPABILITY}。
+ */
+export declare function mergeAgentCapabilities(agents: readonly AgentCapabilityInput[]): AgentCapability;
+/** 技能的可匹配别名（与 `findSkill` 接受的 "/" 触发别名一致）。 */
+export interface SkillIdentity {
+    name: string;
+    dirName: string;
+    displayName?: string;
+}
+/** 技能是否在勾选集里。 */
+export declare function isSkillPinned(skill: SkillIdentity, pinnedSkills: readonly string[]): boolean;
+/**
+ * 解析本轮的技能排除清单——注入、sidecar 目录、`/技能名` 显式触发三处共用
+ * 同一份结果，所以「限制」不会在某一条路径上漏掉。
+ *
+ * `allowExternalSkills` 为 true（默认）时只有模式级排除生效，未勾选的技能
+ * 照旧按触发条件或目录按需加载；为 false 时未勾选的技能全部进排除清单。
+ *
+ * @param capability 本轮生效的能力面。
+ * @param allSkills 全部已安装技能（无视条件加载的结果）。
+ * @param modeExcludes 模式级排除（如 plan 模式排掉执行类技能），始终生效。
+ * @returns 去重后的技能排除清单。
+ */
+export declare function resolveSkillExcludes(capability: AgentCapability, allSkills: readonly SkillIdentity[], modeExcludes: readonly string[]): string[];

package/dist/local-backend/agent-capability.js

@@ -0,0 +1,174 @@
+/**
+ * 智能体能力面解析（技能 + 工具准入）。
+ *
+ * 智能体在「智能体管理」页配置三件事，本模块把它们解析成本轮可执行的形态：
+ *
+ *   - `skillIds`            勾选的技能 → 正文无条件常驻注入（钉进 eager 层）
+ *   - `allowExternalSkills` false 时把勾选集变成硬白名单
+ *   - `toolPolicy`          模型可见工具的 allowlist / denylist
+ *
+ * 全是纯函数（不碰 electron / sqlite / sidecar），因为同一份解析结果要喂给
+ * 三个互相独立的执行点，任何一处漂移都会让「限制」变成假象：
+ *
+ *   1. 系统提示词注入   —— prompt-builder 的 `excludeSkillNames` / `pinnedSkillNames`
+ *   2. sidecar 技能目录 —— `SkillTurnContext.exclude`
+ *   3. 工具面           —— 每轮 `turnTools`、`tool_search` 结果、反向通道分发复检
+ *
+ * `@提及` 多个智能体的回合按「最宽松」合并：提及额外专家是为了叠加能力，
+ * 不应该反而让对话失去工具或技能（与 personaPreamble 的「同时具备以下 N 个
+ * 角色的能力」一致）。
+ */
+/** 无智能体绑定（或未配置）的回合：不钉技能、不限制。 */
+export const UNRESTRICTED_CAPABILITY = {
+    pinnedSkills: [],
+    allowExternalSkills: true,
+    loadAllSkills: false,
+    toolPolicy: { mode: 'all', tools: [] },
+};
+/**
+ * 归一化外部传入（API payload / 旧库行）的工具策略。
+ *
+ * 空 `tools` 一律降级为 `all`：denylist 空集本就等于不限制，而「allowlist
+ * 空集」会让智能体一个工具都调不到——那不是任何人想要的配置，把它当作未
+ * 配置处理，避免用户在 UI 上手滑就把智能体废掉。
+ *
+ * @param raw 任意来源的候选值。
+ * @returns 合法的 {@link AgentToolPolicy}；无法识别时为 `{ mode: 'all', tools: [] }`。
+ */
+export function normalizeToolPolicy(raw) {
+    const source = (raw ?? {});
+    const tools = Array.isArray(source.tools)
+        ? Array.from(new Set(source.tools
+            .map((item) => String(item).trim())
+            .filter((item) => item.length > 0)))
+        : [];
+    const mode = source.mode === 'allowlist' || source.mode === 'denylist' ? source.mode : 'all';
+    if (mode === 'all' || tools.length === 0)
+        return { mode: 'all', tools: [] };
+    return { mode, tools };
+}
+/**
+ * 单个工具是否被策略放行。
+ *
+ * @param policy 归一化后的策略。
+ * @param toolName 一等工具名（含 `mcp__<server>__<tool>` 全名）。
+ * @returns 放行为 true。
+ */
+export function isToolAllowed(policy, toolName) {
+    switch (policy.mode) {
+        case 'all':
+            return true;
+        case 'allowlist':
+            return policy.tools.includes(toolName);
+        case 'denylist':
+            return !policy.tools.includes(toolName);
+    }
+}
+/**
+ * 按策略过滤一批工具 schema（保持入参顺序）。
+ *
+ * @param schemas 待过滤的 schema 列表。
+ * @param policy 归一化后的策略。
+ * @returns 放行的 schema 子集；`mode: 'all'` 时原样返回。
+ */
+export function filterToolsByPolicy(schemas, policy) {
+    if (policy.mode === 'all')
+        return [...schemas];
+    return schemas.filter((schema) => isToolAllowed(policy, schema.name));
+}
+/**
+ * 合并两个工具策略，取「任一放行即放行」。
+ *
+ * allowlist A 与 denylist D 混合时结果是 `denylist(D \ A)`：被拒的只剩
+ * 「D 里拒了、A 里也没放行」的工具。
+ */
+function mergeToolPolicies(a, b) {
+    if (a.mode === 'all' || b.mode === 'all')
+        return { mode: 'all', tools: [] };
+    if (a.mode === 'allowlist' && b.mode === 'allowlist') {
+        return normalizeToolPolicy({
+            mode: 'allowlist',
+            tools: [...a.tools, ...b.tools],
+        });
+    }
+    if (a.mode === 'denylist' && b.mode === 'denylist') {
+        const both = a.tools.filter((tool) => b.tools.includes(tool));
+        return normalizeToolPolicy({ mode: 'denylist', tools: both });
+    }
+    const [allow, deny] = a.mode === 'allowlist' ? [a, b] : [b, a];
+    const stillDenied = deny.tools.filter((tool) => !allow.tools.includes(tool));
+    return normalizeToolPolicy({ mode: 'denylist', tools: stillDenied });
+}
+/**
+ * 合并本轮涉及的全部智能体的能力面，取最宽松。
+ *
+ * @param agents 按提及顺序排列的智能体配置；空数组表示无绑定。
+ * @returns 本轮生效的能力面；空数组时为 {@link UNRESTRICTED_CAPABILITY}。
+ */
+export function mergeAgentCapabilities(agents) {
+    if (agents.length === 0)
+        return UNRESTRICTED_CAPABILITY;
+    const pinned = new Set();
+    let allowExternalSkills = false;
+    let loadAllSkills = false;
+    // 折叠起点取最严（allowlist 空集经归一化即 `all`，所以这里显式从第一个
+    // 智能体的策略起步，而不是造一个「空允许集」的中间值）。
+    let toolPolicy = normalizeToolPolicy(agents[0].toolPolicy);
+    for (const agent of agents) {
+        for (const id of agent.skillIds) {
+            const trimmed = id.trim();
+            if (trimmed)
+                pinned.add(trimmed);
+        }
+        if (agent.allowExternalSkills)
+            allowExternalSkills = true;
+        if (agent.loadAllSkills)
+            loadAllSkills = true;
+        toolPolicy = mergeToolPolicies(toolPolicy, normalizeToolPolicy(agent.toolPolicy));
+    }
+    return {
+        pinnedSkills: Array.from(pinned),
+        allowExternalSkills,
+        loadAllSkills,
+        toolPolicy,
+    };
+}
+/** 技能在 `exclude` / `skillIds` 里的规范写法。 */
+function skillKey(skill) {
+    return skill.dirName || skill.name;
+}
+function matchesAlias(skill, alias) {
+    const key = alias.toLowerCase().trim();
+    if (!key)
+        return false;
+    return (skill.name.toLowerCase() === key ||
+        skill.dirName.toLowerCase() === key ||
+        (!!skill.displayName && skill.displayName.toLowerCase() === key));
+}
+/** 技能是否在勾选集里。 */
+export function isSkillPinned(skill, pinnedSkills) {
+    return pinnedSkills.some((alias) => matchesAlias(skill, alias));
+}
+/**
+ * 解析本轮的技能排除清单——注入、sidecar 目录、`/技能名` 显式触发三处共用
+ * 同一份结果，所以「限制」不会在某一条路径上漏掉。
+ *
+ * `allowExternalSkills` 为 true（默认）时只有模式级排除生效，未勾选的技能
+ * 照旧按触发条件或目录按需加载；为 false 时未勾选的技能全部进排除清单。
+ *
+ * @param capability 本轮生效的能力面。
+ * @param allSkills 全部已安装技能（无视条件加载的结果）。
+ * @param modeExcludes 模式级排除（如 plan 模式排掉执行类技能），始终生效。
+ * @returns 去重后的技能排除清单。
+ */
+export function resolveSkillExcludes(capability, allSkills, modeExcludes) {
+    const excludes = new Set(modeExcludes);
+    if (!capability.allowExternalSkills) {
+        for (const skill of allSkills) {
+            if (!isSkillPinned(skill, capability.pinnedSkills)) {
+                excludes.add(skillKey(skill));
+            }
+        }
+    }
+    return Array.from(excludes);
+}