Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
feat(core): discover optional tool schemas on demand
Seth Wilson0951cb571d3f
diff --git a/.env.example b/.env.exampleindex 15b18ddf..f00747cf 100644--- a/.env.example+++ b/.env.example@@ -155,3 +155,6 @@ GITHUB_DEFAULT_REPO=SPOTIFY_CLIENT_ID=SPOTIFY_CLIENT_SECRET=SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback++# Opt in to on-demand plugin/MCP schemas in the main agent (default: false).+MERCURY_TOOL_DISCOVERY=falsediff --git a/src/core/agent.ts b/src/core/agent.tsindex 9c802c2b..b4e30740 100644--- a/src/core/agent.ts+++ b/src/core/agent.ts@@ -104,6 +104,7 @@ import { verbPoolFor } from '../ui/status-word.js';import { StallWatchdog } from './stall-watchdog.js';import { setProgressPulse } from './progress-pulse.js';import { selectActiveTools } from './tool-exposure.js';+import { ToolDiscovery } from './tool-discovery.js';import { createTaskSurface, type DoneInput } from './task-surface.js';import { buildFileChangePreview } from '../utils/file-preview.js';import { whatsNewText } from '../utils/whats-new.js';@@ -2197,6 +2198,7 @@ export class Agent {channelId: string;/** Mechanically force the first step to contain a tool call. */forceFirstTool?: boolean;+ toolDiscovery: ToolDiscovery;onStep: (toolCalls: any[] | undefined, toolResults: any[] | undefined) => void | Promise<void>;}): Promise<{ text: string; usage: any; reasoning?: any; finishReason?: string }> {this.markProgress(`Resuming with ${opts.provider.name}...`);@@ -2207,14 +2209,9 @@ export class Agent {// opting in stops the SDK printing a warning on every call.allowSystemInMessages: true,messages: this.withCachedSystem(opts.systemPrompt, opts.messages, opts.volatileSystem),- tools: this.capabilities.getTools(),+ ...opts.toolDiscovery.request(undefined, { forceFirstTool: opts.forceFirstTool }),maxOutputTokens: opts.maxOutputTokens,stopWhen: stepCountIs(opts.maxSteps),- // forceFirstTool: the first step MUST contain a tool call — narration- // rounds are converted into action rounds mechanically.- prepareStep: opts.forceFirstTool- ? ({ steps }) => (steps.length === 0 ? { toolChoice: 'required' as const } : {})- : undefined,// Live tool-step UI during continuation rounds: forced/verification// rounds land file writes, and the user must SEE which file is being// written at the bottom, exactly as in the main loop.@@ -3223,6 +3220,10 @@ export class Agent {this.capabilities.setChannelContext(msg.channelId, msg.channelType);this.capabilities.permissions.setCurrentChannelType(msg.channelType);this.capabilities.permissions.setCurrentSenderRole(msg.senderRole);+ const toolDiscovery = new ToolDiscovery(+ () => this.programmingMode.isPlan() ? this.capabilities.getPlanTools() : this.capabilities.getTools(),+ this.config.toolDiscovery?.enabled === true,+ );const providerContextId = msg.sessionId ?? (typeof msg.metadata?.sessionId === 'string' ? msg.metadata.sessionId : msg.channelId);const channelOverride = this.channelProviderOverrides.get(providerContextId);@@ -3808,9 +3809,8 @@ export class Agent {// opting in stops the SDK printing a warning on every call.allowSystemInMessages: true,messages: this.withCachedSystem(systemPrompt, providerMessages, volatileSystem),- tools: this.programmingMode.isPlan() ? this.capabilities.getPlanTools() : this.capabilities.getTools(),+ ...toolDiscovery.request(activeTools),maxOutputTokens: providerMaxOutputTokens,- ...(activeTools ? { activeTools } : {}),stopWhen: stepCountIs(effectiveMaxSteps),abortSignal: loopAbortController.signal,// Memory: the SDK retains a structuredClone of the whole@@ -3934,7 +3934,7 @@ export class Agent {? toolTruncationContinuationPrompt(msg.content): truncationContinuationPrompt(msg.content) },], volatileSystem),- tools: this.capabilities.getTools(),+ ...toolDiscovery.request(),maxOutputTokens: effectiveMaxOutputTokens,// FULL budget: a one-step round can only read files — the// model could never reach the write, which is exactly the@@ -3979,9 +3979,8 @@ export class Agent {// opting in stops the SDK printing a warning on every call.allowSystemInMessages: true,messages: this.withCachedSystem(systemPrompt, providerMessages, volatileSystem),- tools: this.programmingMode.isPlan() ? this.capabilities.getPlanTools() : this.capabilities.getTools(),+ ...toolDiscovery.request(activeTools),maxOutputTokens: providerMaxOutputTokens,- ...(activeTools ? { activeTools } : {}),stopWhen: stepCountIs(effectiveMaxSteps),abortSignal: loopAbortController.signal,// Same O(N²) step retention as streamText (see comment above).@@ -4334,14 +4333,13 @@ export class Agent {// opting in stops the SDK printing a warning on every call.allowSystemInMessages: true,messages: this.withCachedSystem(systemPrompt, messages, volatileSystem),- tools: this.capabilities.getTools(),+ ...toolDiscovery.request(undefined, { forceFirstTool: true, firstStepTools: FORCED_ACTION_TOOLS }),maxOutputTokens: effectiveMaxOutputTokens,stopWhen: stepCountIs(effectiveMaxSteps),// Mechanical enforcement, not a polite nudge: the first step of// this round MUST contain a tool call. Text nudges alone let// narration-only models loop for every round; a provider-enforced// toolChoice converts "describing the work" into doing it.- prepareStep: ({ steps }) => (steps.length === 0 ? { toolChoice: 'required' as const, activeTools: FORCED_ACTION_TOOLS } : {}),experimental_onToolCallStart: ({ toolCall }) => {const tc = toolCall as any;this.markProgress(formatToolStep(tc.toolName, tc.input as Record<string, any> || {}));@@ -4499,6 +4497,7 @@ export class Agent {abortController: loopAbortController,channel,channelId: msg.channelId,+ toolDiscovery,onStep: continuationStepHandler,});if (round.text.trim()) result = { text: round.text, usage: round.usage, reasoning: round.reasoning, finishReason: round.finishReason };@@ -4562,6 +4561,7 @@ export class Agent {channelId: msg.channelId,// Verification must produce evidence, not prose about evidence.forceFirstTool: true,+ toolDiscovery,onStep: continuationStepHandler,});if (round.text.trim()) result = { text: round.text, usage: round.usage, reasoning: round.reasoning, finishReason: round.finishReason };diff --git a/src/core/tool-discovery.test.ts b/src/core/tool-discovery.test.tsnew file mode 100644index 00000000..7902314f--- /dev/null+++ b/src/core/tool-discovery.test.ts@@ -0,0 +1,97 @@+import { describe, expect, it, vi } from 'vitest';+import { asSchema, tool, zodSchema, type Tool } from 'ai';+import { z } from 'zod';+import { DISCOVER_TOOLS, ToolDiscovery } from './tool-discovery.js';++function capability(description: string, execute = vi.fn(async () => 'ok')): Tool {+ return tool({ description, inputSchema: zodSchema(z.object({ query: z.string() })), execute });+}+const execute = async (t: Tool, input: unknown) => t.execute!(input, { toolCallId: 'test', messages: [] });+const active = (request: ReturnType<ToolDiscovery['request']>) => request.prepareStep!({ stepNumber: 0 }).activeTools!;+const search = (request: ReturnType<ToolDiscovery['request']>, input: Record<string, unknown>) => execute(request.tools[DISCOVER_TOOLS], input);++function schemaBytes(tools: Record<string, Tool>, names = Object.keys(tools)): number {+ return Buffer.byteLength(JSON.stringify(names.map((name) => ({ name, description: tools[name].description, inputSchema: asSchema(tools[name].inputSchema).jsonSchema }))));+}++describe('optional tool discovery', () => {+ it('leaves exposure and tool identity unchanged when off, or no integrations exist', () => {+ const tools = { read_file: capability('Read files'), demo__search: capability('Search docs') };+ const off = new ToolDiscovery(() => tools, false).request(['read_file']);+ expect(off.tools).toEqual(tools);+ expect(off.tools.demo__search).toBe(tools.demo__search);+ expect(off.activeTools).toEqual(['read_file']);+ expect(off.prepareStep).toBeUndefined();+ expect(new ToolDiscovery(() => ({ read_file: tools.read_file }), true).request().prepareStep).toBeUndefined();+ });++ it('searches names and descriptions, loads exact schemas next step, and retains built-ins', async () => {+ const tools = { read_file: capability('Read files'), calendar__events: capability('Find appointments'), mail__search: capability('Search inbox messages') };+ const discovery = new ToolDiscovery(() => tools, true);+ const request = discovery.request();+ expect(active(request)).toEqual(['read_file', DISCOVER_TOOLS]);+ expect(JSON.parse(await search(request, { query: 'appointments' }) as string).tools[0].name).toBe('calendar__events');+ expect(active(request)).toEqual(['read_file', 'calendar__events', DISCOVER_TOOLS]);+ expect(request.tools.calendar__events.inputSchema).toBe(tools.calendar__events.inputSchema);+ expect(active(discovery.request())).toContain('calendar__events'); // fallback/continuation+ expect(active(new ToolDiscovery(() => tools, true).request())).not.toContain('calendar__events'); // next turn+ });++ it('supports bounded browsing, exact names, unknown names and no-match recovery', async () => {+ const tools = Object.fromEntries(Array.from({ length: 12 }, (_, i) => [`docs__tool_${String(i).padStart(2, '0')}`, capability('Read docs')])) as Record<string, Tool>;+ const request = new ToolDiscovery(() => tools, true).request();+ const first = JSON.parse(await search(request, {}) as string);+ expect(first.tools).toHaveLength(5);+ expect(first.nextOffset).toBe(5);+ const second = JSON.parse(await search(request, { offset: 5 }) as string);+ expect(second.tools[0].name).toBe('docs__tool_05');+ expect(JSON.parse(await search(request, { query: 'unfindable' }) as string).tools).toEqual([]);+ const exact = JSON.parse(await search(request, { names: ['docs__tool_11', 'unknown__tool'] }) as string);+ expect(exact.tools.map((t: { name: string }) => t.name)).toEqual(['docs__tool_11']);+ expect(exact.unavailable).toEqual(['unknown__tool']);+ });++ it('refuses guessed calls before discovery and tools removed or forbidden after discovery', async () => {+ const run = vi.fn(async () => 'ok');+ let tools: Record<string, Tool> = { demo__search: capability('Search docs', run) };+ const request = new ToolDiscovery(() => tools, true).request();+ expect(await execute(request.tools.demo__search, { query: 'x' })).toMatch(/^Error: Tool .* is not available/);+ expect(run).not.toHaveBeenCalled();+ await search(request, { query: 'docs' });+ expect(await execute(request.tools.demo__search, { query: 'x' })).toBe('ok');+ tools = {}; // role downgrade, general access, plan restriction, or plugin disabled+ expect(active(request)).toEqual([]);+ expect(await execute(request.tools.demo__search, { query: 'x' })).toMatch(/^Error:/);+ expect(JSON.parse(await search(request, {}) as string).tools).toEqual([]);+ expect(run).toHaveBeenCalledTimes(1);+ });++ it('cannot widen an existing active-tool restriction and composes forced action rounds', async () => {+ const tools = { read_file: capability('Read files'), demo__search: capability('Search docs'), denied__write: capability('Write docs') };+ const discovery = new ToolDiscovery(() => tools, true);+ const request = discovery.request(['read_file', 'demo__search'], { forceFirstTool: true, firstStepTools: ['read_file', 'denied__write'] });+ expect(request.prepareStep!({ stepNumber: 0 })).toEqual({ activeTools: ['read_file'], toolChoice: 'required' });+ expect(JSON.parse(await search(request, { names: ['denied__write'] }) as string).tools).toEqual([]);+ await search(request, { names: ['demo__search'] });+ expect(request.prepareStep!({ stepNumber: 1 })).toEqual({ activeTools: ['read_file', 'demo__search', DISCOVER_TOOLS] });+ });++ it('measures schema bytes for 100 optional tools before and after loading five', async () => {+ const tools: Record<string, Tool> = { read_file: capability('Read a file') };+ for (let i = 0; i < 100; i++) {+ tools[`docs__tool_${String(i).padStart(3, '0')}`] = tool({+ description: `Search documents in collection ${i}. ` + 'Returns matching documents with their source links. '.repeat(3),+ inputSchema: zodSchema(z.object(Object.fromEntries(Array.from({ length: 10 }, (_, n) => [`filter_${n}`, z.string().optional().describe(`Optional document filter ${n}`)])))),+ execute: async () => 'ok',+ });+ }+ const request = new ToolDiscovery(() => tools, true).request();+ const eagerBytes = schemaBytes(tools);+ const initialBytes = schemaBytes(request.tools, active(request));+ await search(request, { query: 'documents' });+ const loadedBytes = schemaBytes(request.tools, active(request));+ expect(initialBytes / eagerBytes).toBeLessThan(0.05);+ expect(loadedBytes / eagerBytes).toBeLessThan(0.10);+ console.info(`Discovery schema benchmark: eager=${eagerBytes} B; initial=${initialBytes} B; five loaded=${loadedBytes} B (synthetic JSON bytes, not model tokens or task success).`);+ });+});diff --git a/src/core/tool-discovery.ts b/src/core/tool-discovery.tsnew file mode 100644index 00000000..4d81157b--- /dev/null+++ b/src/core/tool-discovery.ts@@ -0,0 +1,118 @@+/** Optional per-turn schema discovery for owner-installed plugin and MCP tools. */+import { tool, zodSchema, type Tool } from 'ai';+import { z } from 'zod';++export const DISCOVER_TOOLS = 'discover_tools';+const DESCRIPTION_CHARS = 240;+const MAX_RESULTS = 10;++/** Built-ins have no namespace; keep their existing exposure and behavior. */+function optionalTool(name: string): boolean {+ return name.includes('__');+}++interface RequestOptions {+ forceFirstTool?: boolean;+ firstStepTools?: string[];+}++/** Create one instance for a user turn; retain it through fallback and continuation. */+export class ToolDiscovery {+ private loaded = new Set<string>();++ constructor(+ private readonly getTools: () => Record<string, Tool>,+ private readonly enabled: boolean,+ ) {}++ request(activeTools?: string[], options: RequestOptions = {}) {+ const source = this.getTools();+ const deferred = Object.keys(source).filter(optionalTool);+ const discover = this.enabled && deferred.length > 0;+ const tools = { ...source };+ const allowed = activeTools ? new Set(activeTools) : undefined;+ // Never enumerate a tool that wasn't in this SDK request or is no longer+ // available in the current role/mode/channel (including disconnected plugins).+ const available = () => {+ const current = this.getTools();+ return deferred.filter((name) => Object.hasOwn(current, name) && (!allowed || allowed.has(name)));+ };+ const active = () => {+ const current = this.getTools();+ return Object.keys(tools).filter((name) => {+ if (name === DISCOVER_TOOLS && discover) return available().length > 0;+ return Object.hasOwn(current, name) && (!allowed || allowed.has(name))+ && (!discover || !optionalTool(name) || this.loaded.has(name));+ });+ };++ if (discover) {+ // activeTools controls schemas, not authorization. Reject guessed calls to+ // unloaded tools and re-resolve live wrappers so discovery grants nothing.+ for (const name of deferred) {+ const original = source[name];+ tools[name] = {+ ...original,+ execute: async (input, execution) => {+ if (!this.loaded.has(name) || !available().includes(name)) {+ return `Error: Tool ${name} is not available. Use ${DISCOVER_TOOLS} to find available tools.`;+ }+ const live = this.getTools()[name];+ if (!live?.execute) return `Error: Tool ${name} is no longer available.`;+ return live.execute(input, execution);+ },+ };+ }+ const services = [...new Set(deferred.map((name) => name.startsWith('mcp__')+ ? `MCP ${name.split('__')[1]}` : name.split('__')[0]))].sort().join(', ').slice(0, 1000);+ tools[DISCOVER_TOOLS] = tool({+ description: 'Search optional integrations by service, tool name, or task keywords before using them. '+ + 'Matching tools are loaded with their full input schemas on the NEXT model step. '+ + 'This only discovers tools; calling them still requires the usual permissions. '+ + 'Use an empty query and offset to browse, or names to load exact names from earlier results. '+ + `Connected integrations: ${services}.`,+ inputSchema: zodSchema(z.object({+ query: z.string().max(200).optional().describe('Task or service keywords; empty lists available tools'),+ names: z.array(z.string().max(200)).max(MAX_RESULTS).optional().describe('Exact tool names to load'),+ limit: z.number().int().min(1).max(MAX_RESULTS).default(5),+ offset: z.number().int().min(0).max(100_000).default(0),+ })),+ execute: async ({ query = '', names, limit = 5, offset = 0 }) => {+ const current = this.getTools();+ const terms = [...new Set(query.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? [])];+ const ranked = available().map((name) => {+ const title = name.toLowerCase();+ const description = (current[name].description ?? '').toLowerCase();+ const score = terms.reduce((sum, term) => sum + (title.includes(term) ? 3 : description.includes(term) ? 1 : 0), 0);+ return { name, score };+ }).filter(({ name, score }) => names ? names.includes(name) : terms.length === 0 || score > 0)+ .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));+ const selected = ranked.slice(offset, offset + limit);+ for (const { name } of selected) this.loaded.add(name);+ return JSON.stringify({+ tools: selected.map(({ name }) => ({ name, description: (current[name].description ?? '').slice(0, DESCRIPTION_CHARS) })),+ total: ranked.length,+ nextOffset: offset + selected.length < ranked.length ? offset + selected.length : null,+ ...(names ? { unavailable: names.filter((name) => !available().includes(name)) } : {}),+ note: selected.length ? 'These tool schemas are available on the next step. Discovery does not grant permission to execute them.'+ : 'No matching tools. Try a service name, fewer keywords, or an empty query to browse.',+ });+ },+ });+ }++ return {+ tools,+ ...(activeTools ? { activeTools } : {}),+ prepareStep: discover || options.forceFirstTool+ ? ({ stepNumber }: { stepNumber: number }) => ({+ ...(discover ? { activeTools: active() } : {}),+ ...(options.forceFirstTool && stepNumber === 0 ? {+ toolChoice: 'required' as const,+ ...(options.firstStepTools ? { activeTools: options.firstStepTools.filter((name) => active().includes(name)) } : {}),+ } : {}),+ })+ : undefined,+ };+ }+}diff --git a/src/eval/scenarios/tool-discovery.test.ts b/src/eval/scenarios/tool-discovery.test.tsnew file mode 100644index 00000000..317315df--- /dev/null+++ b/src/eval/scenarios/tool-discovery.test.ts@@ -0,0 +1,142 @@+import '../env.js';+import { afterAll, afterEach, describe, expect, it, vi } from 'vitest';+import { EvalHarness, runScenario } from '../runner.js';+import { call, textStep, toolStep } from '../fixture.js';+import { publishTool, resetToolBridge } from '../../plugins/tool-bridge.js';+import { buildMcpTool } from '../../capabilities/mcp/tool.js';+import type { McpManager } from '../../capabilities/mcp/manager.js';+import { jsonSchema } from 'ai';+import { ToolDiscovery } from '../../core/tool-discovery.js';++function publish(readOnly = true) {+ const invoke = vi.fn(async () => 'Team meeting at 09:00. Source: https://example.test/calendar/event/42');+ publishTool({ pluginId: 'calendar', pluginName: 'Calendar', name: 'events', description: 'Find upcoming appointments',+ inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'], additionalProperties: false },+ readOnly, timeoutMs: 1000, invoke });+ return invoke;+}++afterEach(() => { resetToolBridge(); vi.unstubAllEnvs(); });+afterAll(async () => { (await import('../env.js')).removeEvalRoot(); });++describe('eval · on-demand tool schemas in the real agent loop', () => {+ it.each([true, false])('loads and executes a discovered plugin through the SDK and bridge (streaming=%s)', async (streaming) => {+ vi.stubEnv('MERCURY_TOOL_DISCOVERY', 'true');+ const invoke = publish();+ const result = await runScenario({ name: `discovery-${streaming}`, channel: { streaming }, turns: [+ { message: 'Find my appointments.', steps: [+ toolStep([call('discover_tools', { query: 'appointments' })]),+ toolStep([call('calendar__events', { query: 'today' })]),+ textStep('Your team meeting is at 09:00.'),+ ], expect: { deliveredCount: 1, providerCalls: 3, finalTextIncludes: ['09:00'] } },+ { message: 'Thanks.', steps: [textStep('You are welcome.')] },+ ] });+ expect(result.failures).toEqual([]);+ const calls = result.turns[0].providerCalls;+ expect(calls[0].toolNames).toContain('discover_tools');+ expect(calls[0].toolNames).not.toContain('calendar__events');+ expect(calls[1].toolNames).toContain('calendar__events');+ expect(JSON.stringify(calls[2].prompt)).toContain('https://example.test/calendar/event/42');+ expect(result.turns[1].providerCalls[0].toolNames).not.toContain('calendar__events');+ expect(invoke).toHaveBeenCalledTimes(1);+ });++ it('rejects malformed discovery input and refuses the still-unloaded tool', async () => {+ vi.stubEnv('MERCURY_TOOL_DISCOVERY', 'true');+ const invoke = publish();+ const result = await runScenario({ name: 'discovery-validation', turns: [{ message: 'Find appointments.', steps: [+ toolStep([call('discover_tools', { query: 42 })]),+ toolStep([call('calendar__events', { query: 'today' })]),+ textStep('The calendar arguments were invalid.'),+ ] }] });+ expect(invoke).not.toHaveBeenCalled();+ expect(JSON.stringify(result.turns[0].providerCalls[2].prompt)).toContain('Invalid input');+ });++ it('keeps schema discovery inside role, channel, plan, and scheduled grant boundaries', async () => {+ publish(false);+ const harness = await EvalHarness.create({ name: 'discovery-boundaries', turns: [] });+ const caps = harness.capabilities;+ const execute = (tool: import('ai').Tool, input: unknown) => tool.execute!(input, { toolCallId: 'boundary', messages: [] });+ try {+ const request = new ToolDiscovery(() => caps.getTools(), true).request();+ await execute(request.tools.discover_tools, { query: 'calendar' });+ caps.permissions.setCurrentSenderRole('member');+ expect(new ToolDiscovery(() => caps.getTools(), true).request().tools.discover_tools).toBeUndefined();+ expect(await execute(request.tools.calendar__events, { query: 'today' })).toMatch(/^Error:/);+ caps.permissions.setCurrentSenderRole('admin');+ caps.setToolsDisabled(true);+ expect(new ToolDiscovery(() => caps.getTools(), true).request().tools).toEqual({});+ expect(await execute(request.tools.calendar__events, { query: 'today' })).toMatch(/^Error:/);+ caps.setToolsDisabled(false);+ expect(new ToolDiscovery(() => caps.getPlanTools(), true).request().tools.calendar__events).toBeUndefined();+ caps.permissions.setCurrentContext('internal', 'schedule');+ caps.permissions.setAutoApproveAll(false);+ expect(await execute(request.tools.calendar__events, { query: 'today' })).toContain('was not approved');+ caps.permissions.setTurnPluginGrants(['calendar__events']);+ expect(await execute(request.tools.calendar__events, { query: 'today' })).toContain('09:00');+ caps.permissions.setTurnPluginGrants([]);+ expect(await execute(request.tools.calendar__events, { query: 'today' })).toContain('was not approved');+ } finally { await harness.dispose(); }+ });++ it('keeps eager exposure by default', async () => {+ vi.stubEnv('MERCURY_TOOL_DISCOVERY', 'false');+ const invoke = publish();+ const result = await runScenario({ name: 'discovery-off', turns: [{ message: 'Find appointments.', steps: [+ toolStep([call('calendar__events', { query: 'today' })]), textStep('Team meeting at 09:00.'),+ ] }] });+ expect(result.turns[0].providerCalls[0].toolNames).toContain('calendar__events');+ expect(result.turns[0].providerCalls[0].toolNames).not.toContain('discover_tools');+ expect(invoke).toHaveBeenCalledTimes(1);+ });++ it('preserves plugin approval and denial after discovery', async () => {+ vi.stubEnv('MERCURY_TOOL_DISCOVERY', 'true');+ const invoke = publish(false);+ const harness = await EvalHarness.create({ name: 'discovery-denial', turns: [] });+ const ask = vi.fn(async () => 'no');+ harness.capabilities.permissions.setAutoApproveAll(false);+ harness.capabilities.permissions.onAsk(ask);+ try {+ const result = await harness.runTurn({ message: 'Update my calendar.', steps: [+ toolStep([call('discover_tools', { query: 'calendar' })]),+ toolStep([call('calendar__events', { query: 'change meeting' })]),+ textStep('The calendar action was not approved.'),+ ] });+ expect(ask).toHaveBeenCalledTimes(1);+ expect(invoke).not.toHaveBeenCalled();+ expect(JSON.stringify(result.providerCalls[2].prompt)).toContain('was not approved');+ } finally { await harness.dispose(); }+ });++ it('preserves MCP permission gates even under Allow All', async () => {+ vi.stubEnv('MERCURY_TOOL_DISCOVERY', 'true');+ const harness = await EvalHarness.create({ name: 'discovery-mcp-denial', turns: [] });+ const ask = vi.fn(async () => 'no');+ harness.capabilities.permissions.onAsk(ask);+ const invoke = vi.fn(async () => ({ content: [{ type: 'text', text: 'done' }] }));+ const mcpTool = buildMcpTool({ serverId: 'docs', toolName: 'search', exposedName: 'mcp__docs__search', description: 'Search documents',+ inputSchema: jsonSchema({ type: 'object', properties: {}, additionalProperties: false }), autoApprove: false,+ gate: (request) => harness.capabilities.permissions.checkMcpTool(request), call: invoke });+ harness.capabilities.attachMcp({ getTools: () => ({ mcp__docs__search: mcpTool }) } as unknown as McpManager);+ try {+ const result = await harness.runTurn({ message: 'Search the documents.', steps: [+ toolStep([call('discover_tools', { query: 'documents' })]),+ toolStep([call('mcp__docs__search', {})]),+ textStep('The document search was denied.'),+ ] });+ expect(ask).toHaveBeenCalledTimes(1);+ expect(invoke).not.toHaveBeenCalled();+ expect(JSON.stringify(result.providerCalls[2].prompt)).toContain('User denied MCP tool');+ } finally { await harness.dispose(); }+ });++ it('does not expose mutating plugins in plan mode', async () => {+ vi.stubEnv('MERCURY_TOOL_DISCOVERY', 'true');+ publish(false);+ const result = await runScenario({ name: 'discovery-plan', programmingMode: 'plan', turns: [{ message: 'Plan a calendar update.', steps: [textStep('I will plan the update.')] }] });+ expect(result.turns[0].providerCalls[0].toolNames).not.toContain('calendar__events');+ expect(result.turns[0].providerCalls[0].toolNames).not.toContain('discover_tools');+ });+});diff --git a/src/utils/config.ts b/src/utils/config.tsindex 1ddf5923..591afa0e 100644--- a/src/utils/config.ts+++ b/src/utils/config.ts@@ -301,6 +301,8 @@ export interface MercuryConfig {allowedHosts?: string[];};mcp?: McpConfig;+ /** Opt-in: discover plugin and MCP schemas on demand in the main agent's tool loop. */+ toolDiscovery?: { enabled?: boolean };/** Where the files Mercury makes go (default ~/mercury-artifacts): Research/ and one folder per chat. */artifacts?: {outputDir?: string;@@ -613,6 +615,7 @@ export function getDefaultConfig(): MercuryConfig {accountId: '',product: '',},+ toolDiscovery: { enabled: getEnvBool('MERCURY_TOOL_DISCOVERY', false) },web: {enabled: getEnvBool('MERCURY_WEB_ENABLED', false),port: getEnvNum('MERCURY_PORT', 6174),diff --git a/website/docs/reference/configuration.mdx b/website/docs/reference/configuration.mdxindex 278fba8d..f8d1abc0 100644--- a/website/docs/reference/configuration.mdx+++ b/website/docs/reference/configuration.mdx@@ -30,4 +30,21 @@ web:The sign-in password is set during `mercury setup` (or `mercury web-reset-password`) and stored as a bcrypt hash, never in this file. The port can also come from `MERCURY_PORT`.-Remote access (other devices, the IP allow-list, device limits) is managed with `/server` in the terminal or `mercury server`.\ No newline at end of file+Remote access (other devices, the IP allow-list, device limits) is managed with `/server` in the terminal or `mercury server`.++## Optional tool discovery++If you have many plugin or MCP tools, you can load their schemas only when the main agent needs them. Add this to `~/.mercury/mercury.yaml` and restart Mercury:++```yaml+toolDiscovery:+ enabled: true+```++Or set `MERCURY_TOOL_DISCOVERY=true` when no YAML override is present. It is **off by default**. Built-in tools retain their existing exposure; bots and sub-agents keep their existing tool behavior.++When enabled, the main agent gets a `discover_tools` tool instead of every optional integration schema. It searches tool names and descriptions by service or task keywords, then loads up to ten matching schemas for the next model step (five by default). An empty search browses the catalog with pagination; exact tool names can also be loaded. Loaded tools stay available through provider fallback and continuation in the current turn, then reset on the next user turn. Integrations connected during a model request become discoverable in the next request.++Discovery does not approve an action. MCP allow/deny rules, plugin approvals, scheduled grants, sender roles, plan mode, and channels with no tool access still apply. Disabling a plugin also prevents execution of its previously loaded tool. Results and schemas from integrations remain untrusted content.++This option trades an extra discovery step for smaller repeated tool schemas. It uses keyword search, so a model may need to rephrase a query or browse when its first query misses. Scripted real-agent tests verify search → schema loading → execution and permission denial. The synthetic schema benchmark in `src/core/tool-discovery.test.ts` measures JSON bytes; it does not estimate model tokens, latency, cost, or live-model task success. Try it with your own model and integrations before enabling it broadly; set `enabled: false` to restore eager exposure.