minimal-agent 0.13.0 → 0.15.0

package/src/team/toolPolicy.js

@@ -0,0 +1,36 @@
+import { ONLINE_TOOL_CATEGORY_BY_NAME, onlineToolCategory as sharedOnlineToolCategory, } from './onlineToolContract.js';
+const TOOL_SECURITY_METADATA = Object.fromEntries(Object.entries(ONLINE_TOOL_CATEGORY_BY_NAME).map(([name, category]) => [
+    name,
+    {
+        name,
+        category,
+        mayTransmitLocalData: category === 'workspace' || category === 'computer',
+    },
+]));
+export function onlineToolCategory(name) {
+    return sharedOnlineToolCategory(name);
+}
+export function toolSecurityMetadata(name) {
+    return TOOL_SECURITY_METADATA[name];
+}
+/** Applies the remote model's maximum category boundary before schemas leave
+ * the device. Local providers retain their original complete tool set. */
+export function filterToolsForProvider(tools, provider) {
+    if (provider.source !== 'gateway')
+        return [...tools];
+    return filterToolsForCategories(tools, 
+    // The server maximum is the non-negotiable upper bound. The compatibility
+    // field is only a fallback for old descriptors that lack the explicit
+    // max/default split; it must never override the maximum with defaults.
+    provider.gatewayMaxToolCategories ?? provider.gatewayToolCategories);
+}
+/** Applies the per-Session switch inside the server/model upper bound. */
+export function filterToolsForCategories(tools, categories) {
+    if (!categories)
+        return [...tools];
+    const allowed = new Set(categories);
+    return tools.filter((tool) => {
+        const category = onlineToolCategory(tool.name);
+        return category !== undefined && allowed.has(category);
+    });
+}

package/src/team/toolPolicy.ts

@@ -0,0 +1,75 @@
+import type { Provider, Tool } from '../types.js';
+import {
+  ONLINE_TOOL_CATEGORY_BY_NAME,
+  type OnlineToolCategory,
+  onlineToolCategory as sharedOnlineToolCategory,
+} from './onlineToolContract.js';
+
+/**
+ * Categories shared with minimal-server.  They are a server-enforced upper
+ * bound when a remote model is selected.  Unknown/dynamic tools fail closed:
+ * a plugin cannot silently gain remote-model visibility just by registering a
+ * new tool name.
+ */
+export type { OnlineToolCategory } from './onlineToolContract.js';
+
+export interface ToolSecurityMetadata {
+  name: string;
+  category: OnlineToolCategory;
+  /** Reserved for the privacy UI and future per-tool redaction policy. */
+  mayTransmitLocalData: boolean;
+}
+
+const TOOL_SECURITY_METADATA: Readonly<Record<string, ToolSecurityMetadata>> =
+  Object.fromEntries(
+    Object.entries(ONLINE_TOOL_CATEGORY_BY_NAME).map(([name, category]) => [
+      name,
+      {
+        name,
+        category,
+        mayTransmitLocalData:
+          category === 'workspace' || category === 'computer',
+      },
+    ]),
+  ) as Readonly<Record<string, ToolSecurityMetadata>>;
+
+export function onlineToolCategory(
+  name: string,
+): OnlineToolCategory | undefined {
+  return sharedOnlineToolCategory(name);
+}
+
+export function toolSecurityMetadata(
+  name: string,
+): ToolSecurityMetadata | undefined {
+  return TOOL_SECURITY_METADATA[name];
+}
+
+/** Applies the remote model's maximum category boundary before schemas leave
+ * the device. Local providers retain their original complete tool set. */
+export function filterToolsForProvider(
+  tools: readonly Tool[],
+  provider: Provider,
+): Tool[] {
+  if (provider.source !== 'gateway') return [...tools];
+  return filterToolsForCategories(
+    tools,
+    // The server maximum is the non-negotiable upper bound. The compatibility
+    // field is only a fallback for old descriptors that lack the explicit
+    // max/default split; it must never override the maximum with defaults.
+    provider.gatewayMaxToolCategories ?? provider.gatewayToolCategories,
+  );
+}
+
+/** Applies the per-Session switch inside the server/model upper bound. */
+export function filterToolsForCategories(
+  tools: readonly Tool[],
+  categories?: readonly string[],
+): Tool[] {
+  if (!categories) return [...tools];
+  const allowed = new Set(categories as OnlineToolCategory[]);
+  return tools.filter((tool) => {
+    const category = onlineToolCategory(tool.name);
+    return category !== undefined && allowed.has(category);
+  });
+}

package/src/tools/advisor/advisor.js

@@ -4,7 +4,7 @@
  * ------------------------------------------------------------
  *  独立配置的第二个 LLM，供主循环的模型在关键判断点（方案/诊断成型后动手写改之前、
  *  受阻或要改方向时、收尾汇报之前）主动调用，拿到一个不同模型的第二意见。
- *  时机规则的真身在 `prompts/promptAssembly.ts` 的 Advisor 工具规则 + 本文件的
+ *  时机规则的真身在 `prompts/policyRegistry.ts` 的 `capability.advisor` 能力块 + 本文件的
  *  `description`；配额曲线在 `loop.ts::advisorQuotaFor`。
  *
  *  设计要点（吸收自 Claude Code 官方 /advisor 的架构，但按 minimal-agent
@@ -25,6 +25,7 @@
 import { z } from 'zod';
 import { configService } from '../../config/configService.js';
 import { CONFIG_LIMITS, normalizeLimited } from '../../config/numericLimits.js';
+import { DEFAULT_ADVISOR_CONFIG } from '../../config/configDefaults.js';
 import { countMessagesTokens } from '../../context/tokenCounter.js';
 import { chat } from '../../llm/client.js';
 import { derivePromptCacheContext } from '../../llm/promptCache.js';
@@ -34,31 +35,21 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 const inputSchema = z.object({
     note: z
         .string()
-        .max(2000, 'note 太长（>2000 字）')
+        // 上限只做护栏，不做实用约束：note 是顾问唯一能看到的「模型主动强调的证据」，
+        // 卡太低（曾经 2000 字符）会让完整方案+关键代码原文根本塞不进去。真正的预算
+        // 闸门在 buildAdvisorMessages -> fitAdvisorBudget（inputTokenBudget 配置 +
+        // 顾问 contextWindow 推导），note 超预算只会挤掉历史消息，不会炸请求。
+        .max(100_000, 'note 太长（>100000 字符）')
         .optional()
-        .describe('可选。大多数情况下不需要填——你此前说过的方案/诊断已经在会话历史里，顾问会自动看到。' +
+        .describe('可选。大多数情况下不需要填--你此前说过的方案/诊断已经在会话历史里，顾问会自动看到。' +
         '只有需要额外强调、历史里没体现的点时才填一句话。'),
 });
 const parameters = toToolParameters(inputSchema);
 // ---------------- 2. Description（给 LLM 看的工具说明） ----------------
-const description = `- Consults an independent, separately-configured second LLM ("顾问模型" / advisor) for a second opinion on your current plan, diagnosis, or progress.
-- Call with no arguments in most cases — the advisor receives a bounded, relevant view of the current session (the original request, recent discussion, current plan/diagnosis, and key tool results). Always pass key evidence (original code snippets, raw data, full plan text) in \`note\`, not just your summary — the advisor cannot verify things you never wrote down.
-- Exception: if your current plan/diagnosis relies on things you saw in images (screenshots, photos, diagrams), summarize the key visual facts in \`note\` in 1-2 sentences (what each image shows and what you concluded from it) — the advisor may not be able to see the images themselves.
-- **Call it BEFORE substantive work, not after things go wrong.** The advisor is worth the most before an approach hardens — once you have written the code, the plan is expensive to abandon.
-  - Orientation is NOT substantive work: finding files, reading code, running a command to see the current state. Do that first, then consult.
-  - Substantive work IS: writing or editing files, committing to an interpretation, building on an assumption, declaring an answer.
-- **MUST call Advisor in all 5 of these situations — do not wait for errors or user prompts:**
-  1. After a plan / development plan is finalized, **before** executing it (get critique first, avoid discovering wrong direction halfway)
-  2. **Before** submitting final results to the user (before PresentResult): code reviews, assessment reports, technical selections, refactoring plans — any time you "deliver a conclusion"
-  3. The same error occurs 2+ times in a row, or fixes are not converging (early sign of infinite loop — switch approach immediately)
-  4. The user gives unsatisfied feedback a **second time** in the same turn (stop spinning in place, get a fresh perspective first)
-  5. Decisions involving security, data loss, or irreversible operations (advisor double-check)
-- **Make your work durable BEFORE calling in situation 2.** Write the file, save the result. This call takes time; if the turn ends during it, a written file survives and an unwritten answer does not.
-- On a long task, consult at least twice: once before the approach is locked in, once before you declare it done. On a short reactive task whose next step is dictated by output you just read, one call is enough — the advisor adds most of its value early.
-- **Take the advice seriously, but do not obey it blindly.** Adapt if you follow a step and it empirically fails, or you hold primary-source evidence contradicting a specific claim (the file says X, the test output says Y). A passing self-test is NOT evidence the advice is wrong — it is evidence your test does not check what the advice checks.
-- **If the advisor contradicts evidence you already gathered, do not silently switch.** Call Advisor once more stating the conflict outright ("I measured X, you advise Y — which constraint breaks the tie?"). The advisor saw your evidence but may have underweighted it; one reconciling call is far cheaper than committing to the wrong branch.
-- The advisor has no tool access and does a single read-only pass over the transcript — it cannot verify anything itself, only reason about what it's shown.
-- If this tool errors (advisor not configured in shared settings, disabled, manual-only, or a call failure), that's not a signal to stop — treat it as "no second opinion available this time" and continue with your own judgment, but **explicitly note "not cross-verified by advisor" in your final output**. Do not block or retry in a loop.`;
+const description = `Consult an independently configured, read-only advisor model for a second opinion.
+The advisor receives a bounded view of the current session. Usually omit note; use it only for decisive evidence or visual facts that are absent or easy to miss in history.
+The result includes a full consultationId. After a successful automatic consultation, record the main Agent's evidence-based accept/partial/reject judgment with AdvisorDecision.
+The advisor is neither a fact source nor an authority. If it is unavailable or fails, follow the returned degradation guidance and do not retry in a loop.`;
 // ---------------- 3. 顾问 persona system prompt ----------------
 const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
 你的职责：技术方案评估、代码评审、疑难问题的根因定位与解决方向判断。
@@ -104,8 +95,19 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
  * 和 TUI 的 ephemeral 提示消息（两者都是 role:'system'），换成顾问自己的 persona。
  */
 const MAX_TOOL_RESULT_CHARS = 12_000;
+/**
+ * 工具调用参数与思维链的截断上限——与 `fitAdvisorBudget` 的预算裁剪是两回事：
+ * 那个只在总量超预算时才生效、按消息整条丢弃；这两个是每条消息内部无条件应用的
+ * 字段级上限，不看当前预算是否宽裕。思维链截得比正文更狠：重思考模型的
+ * reasoning 常比 content 长几倍，不设限会把预算吃光、挤掉更该保留的工具结果原文。
+ * 未发现过当前取值导致顾问漏判的实例，因此只命名、不改值——真出现具体案例
+ * 再调，不做没有证据支撑的预防性放宽。
+ */
+const ADVISOR_TOOL_ARGS_TRUNCATE_CHARS = 2_000;
+const ADVISOR_REASONING_TRUNCATE_CHARS = 2_000;
 /** 归一化后的工具结果前缀；裁剪统计要靠它反查，两处必须共用同一常量。 */
 const TOOL_RESULT_PREFIX = '[工具结果 ';
+const CONTEXT_PACKET_PREFIX = '[Advisor 结构化上下文包]';
 function truncateMiddle(value, limit = MAX_TOOL_RESULT_CHARS) {
     if (value.length <= limit)
         return value;
@@ -190,18 +192,16 @@ function normalizeAdvisorMessage(message, supportsVision, allowImages, imageBudg
         return { role: 'user', content: `${TOOL_RESULT_PREFIX}${message.tool_call_id}]\n${truncateMiddle(message.content)}` };
     }
     if (message.role === 'assistant') {
-        const calls = message.tool_calls?.map((call) => `[调用工具 ${call.function.name}] ${truncateMiddle(call.function.arguments, 2000)}`).join('\n');
+        const calls = message.tool_calls?.map((call) => `[调用工具 ${call.function.name}] ${truncateMiddle(call.function.arguments, ADVISOR_TOOL_ARGS_TRUNCATE_CHARS)}`).join('\n');
         // 思维链一并送给顾问：评审「方案对不对」很大程度上要看**它是怎么想到这个方案的**——
         // 推理里的跳跃（把推断当已验证、跳过一个没排除的可能）在最终结论文本里往往看不出来。
-        // 截断比正文更狠（2000）：重思考模型的 reasoning 常比 content 长几倍，不设限会把
-        // 预算吃光、反而挤掉更该保留的工具结果原文。
         // reasoning_details（结构化数组）不传：结构因 provider 而异，既无法可靠脱敏也无法
         // 稳定转成文本，传过去只会变成噪声。
         const thinking = typeof message.reasoning_content === 'string' && message.reasoning_content.length > 0
             ? message.reasoning_content
             : (typeof message.reasoning === 'string' ? message.reasoning : '');
         const thinkingLine = thinking.length > 0
-            ? `[思考过程]\n${truncateMiddle(thinking, 2000)}`
+            ? `[思考过程]\n${truncateMiddle(thinking, ADVISOR_REASONING_TRUNCATE_CHARS)}`
             : '';
         return {
             role: 'assistant',
@@ -224,13 +224,18 @@ function fitAdvisorBudget(messages, inputBudget) {
     const system = messages[0];
     const closing = messages[messages.length - 1];
     const body = messages.slice(1, -1);
-    const firstUserIndex = body.findIndex((message) => message.role === 'user');
+    const packetIndex = body.findIndex((message) => message.role === 'user'
+        && typeof message.content === 'string'
+        && message.content.startsWith(CONTEXT_PACKET_PREFIX));
+    const firstUserIndex = body.findIndex((message, index) => index !== packetIndex && message.role === 'user');
     const selected = [];
     let used = countMessagesTokens([system, closing]);
-    if (firstUserIndex >= 0) {
-        const first = body[firstUserIndex];
-        selected.push(first);
-        used += countMessagesTokens([first]);
+    for (const index of [packetIndex, firstUserIndex]) {
+        if (index < 0)
+            continue;
+        const pinned = body[index];
+        selected.push(pinned);
+        used += countMessagesTokens([pinned]);
     }
     // 从最近往前收，**装不下就停**（break，不是 continue）。
     //
@@ -241,7 +246,7 @@ function fitAdvisorBudget(messages, inputBudget) {
     // 宁可少给，不可给错：连续的尾部 + 如实说明从哪里开始省略。
     const recent = [];
     for (let index = body.length - 1; index >= 0; index--) {
-        if (index === firstUserIndex)
+        if (index === firstUserIndex || index === packetIndex)
             continue;
         const message = body[index];
         const cost = countMessagesTokens([message]);
@@ -284,12 +289,18 @@ export function buildAdvisorMessages(history, note, options = {}) {
         .join('\n');
     const messages = [
         { role: 'system', content: ADVISOR_SYSTEM_PROMPT },
+        ...(options.contextPacket
+            ? [{
+                    role: 'user',
+                    content: `${CONTEXT_PACKET_PREFIX}\n${JSON.stringify(options.contextPacket, null, 2)}`,
+                }]
+            : []),
         ...nonSystem,
         { role: 'user', content: closing },
     ];
     const contextWindow = options.contextWindow ?? 128_000;
     const maxTokens = options.maxTokens ?? 4096;
-    const configuredBudget = normalizeLimited(options.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, 128_000);
+    const configuredBudget = normalizeLimited(options.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, DEFAULT_ADVISOR_CONFIG.inputTokenBudget);
     const providerBudget = Math.max(CONFIG_LIMITS.advisorInputTokenBudget.min, contextWindow - maxTokens - 4096);
     const inputBudget = Math.min(configuredBudget, providerBudget);
     return fitAdvisorBudget(messages, inputBudget);
@@ -318,40 +329,88 @@ function classifyAdvisorError(e) {
  * `chatFn: typeof chat = chat` 模式），不需要 mock.module。
  */
 export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}) {
+    const consultation = ctx?.advisorInvocation === 'agent'
+        ? ctx.advisorRuntime?.beginConsultation()
+        : undefined;
+    const finish = (result) => {
+        if (!consultation || !ctx?.advisorRuntime)
+            return result;
+        const metadata = ctx.advisorRuntime.finishConsultation(consultation, result.ok);
+        return {
+            ...result,
+            ...(result.ok
+                ? {
+                    content: `consultationId: ${metadata.consultationId}\n调用 AdvisorDecision 时必须原样使用上面的完整 consultationId。\n\n${result.content}`,
+                }
+                : {}),
+            metadata,
+        };
+    };
     const advisor = await configService.advisor();
     if (!advisor) {
-        return {
+        return finish({
             ok: false,
             error: '顾问模型未配置。请在设置 → 模型中完成专家顾问配置。' +
                 '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
-        };
+        });
     }
     if (!advisor.enabled) {
-        return {
+        return finish({
             ok: false,
             error: '顾问模型当前已关闭（/advisor on 开启）。' +
                 '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
-        };
+        });
     }
     if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
-        return {
+        return finish({
             ok: false,
             error: '顾问模型当前为"仅手动"模式；请使用 /advisor ask 发起咨询。' +
                 '本回合后续不要再次尝试自动调用 Advisor。',
-        };
+        });
     }
-    if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
+    // 复核豁免：有一个已成功、还没被 AdvisorDecision 结清的咨询时，这次调用是对它
+    // 的复核而不是一次新检查点的咨询——工具说明书要求"顾问意见与证据冲突时再问一次"，
+    // 若复核也照常计费/受配额拦截，短任务（配额恒为 1）会在第二次调用直接撞墙，
+    // 而配额耗尽的处理是把这次咨询标记失败并**顺带结清 #pending 指向的检查点**——
+    // 模型想认真复核，反而因为差一点配额把本该把关的高风险检查点悄悄放行了。
+    // 豁免只覆盖第一次复核：协调器按 checkpoint 记录成功咨询次数，完成一次复核后
+    // canReconcileConsultation 会变为 false，后续调用重新受正常配额约束。
+    const isReconcile = ctx?.advisorInvocation === 'agent'
+        && Boolean(ctx.advisorRuntime?.pendingConsultationId)
+        && ctx.advisorRuntime?.canReconcileConsultation === true;
+    // 检查点强制咨询 vs 自愿咨询分池计费：宿主主动拦下模型、强制它咨询的这一次
+    // 调用（hasActiveGate === true）走独立的 mandatoryUsed/mandatoryMax 池，
+    // 永远不会被自愿/复核性质的咨询挤占配额。旧版只有一个共享池，配额起点为 1
+    // 时一个回合里第二个检查点几乎必然撞墙——这不是顾问后端配置问题，是结构性的。
+    const isMandated = ctx?.advisorInvocation === 'agent'
+        && ctx.advisorRuntime?.hasActiveGate === true;
+    const quota = ctx?.advisorCalls;
+    const usesMandatoryPool = isMandated && quota?.mandatoryMax !== undefined;
+    const quotaUsed = usesMandatoryPool ? (quota.mandatoryUsed ?? 0) : quota?.used;
+    const quotaMax = usesMandatoryPool ? quota.mandatoryMax : quota?.max;
+    if (!isReconcile && quota && quotaUsed !== undefined && quotaMax !== undefined && quotaUsed >= quotaMax) {
         // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
         // 若这里只说「已达上限」，模型会当成本回合的硬上限而不再尝试 —— 那样长回合里
         // 「批次做完再复核一次」的配额永远不会被用到，增长机制等于没做。
-        return {
+        // ⚠️ 只有确实存在一个待结清的咨询（pendingConsultationId）时才能说"按已有
+        // 意见继续"——否则这一步可能压根没有产生过任何意见，那句话就是误导。
+        const hasPendingAdvice = ctx?.advisorRuntime?.pendingConsultationId !== undefined;
+        const poolLabel = usesMandatoryPool ? '检查点强制咨询配额' : '顾问咨询配额';
+        const guidance = hasPendingAdvice
+            ? '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。'
+            : '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；这一步目前没有可参考的顾问意见，' +
+                '请基于代码、测试等一手证据自行判断，并在汇报时如实说明这一步未获得第二意见背书。';
+        return finish({
             ok: false,
-            error: `本回合顾问咨询配额暂时用完（当前 ${ctx.advisorCalls.max} 次）。` +
-                '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。',
-        };
+            error: `本回合${poolLabel}暂时用完（当前 ${quotaMax} 次）。${guidance}`,
+        });
+    }
+    if (!isReconcile && quota) {
+        if (usesMandatoryPool)
+            quota.mandatoryUsed = (quota.mandatoryUsed ?? 0) + 1;
+        else
+            quota.used++;
     }
-    if (ctx?.advisorCalls)
-        ctx.advisorCalls.used++;
     const provider = advisor.provider;
     const snapshot = await configService.getSnapshot();
     const secrets = [
@@ -370,6 +429,9 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
         contextWindow: provider.contextWindow,
         maxTokens: provider.maxTokens,
         inputTokenBudget: advisor.inputTokenBudget,
+        ...(ctx?.advisorRuntime
+            ? { contextPacket: ctx.advisorRuntime.contextPacket(input.note) }
+            : {}),
     });
     // Advisor 是可降级的第二意见：使用独立、可配置的总时限，不影响主模型的流式时限。
     // 默认 180 秒，直接使用所选模型的上下文窗口配置。
@@ -431,22 +493,25 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
                 contextWindow: provider.contextWindow,
                 maxTokens: provider.maxTokens,
                 inputTokenBudget: advisor.inputTokenBudget,
+                ...(ctx?.advisorRuntime
+                    ? { contextPacket: ctx.advisorRuntime.contextPacket(input.note) }
+                    : {}),
             }));
             degradedWithoutImages = true;
         }
     }
     catch (e) {
         if (timeoutController.signal.aborted && !signal?.aborted) {
-            return {
+            return finish({
                 ok: false,
                 error: `顾问模型响应超过 ${Math.round(timeoutMs / 1000)}s 未完成，已跳过。` +
                     '可继续凭自己判断推进，不必等待顾问。',
-            };
+            });
         }
-        return {
+        return finish({
             ok: false,
             error: `${classifyAdvisorError(e)} 可继续凭自己判断推进，不必等待顾问。`,
-        };
+        });
     }
     finally {
         clearTimeout(timer);
@@ -460,7 +525,7 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
             content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
                 `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
     }
-    return { ok: true, content };
+    return finish({ ok: true, content });
 }
 // 无宿主上下文的调用视为用户手动咨询；生产主循环使用 callWithContext。
 async function call(input, signal) {