The all-in-one local AI studio for your desktop: chat, image and video generation and a coding agent in one free, open source app. Windows and Linux. No Docker, no terminal, no cloud required.
TypeScript agentai-chatai-studioall-in-onecoding-agentdesktop-appfluximage-generationlinuxllmlocal-ailocal-llmopen-sourceprivacyself-hostedstable-diffusionuncensoreduncensored-aivideo-generationwindows
/**
* Intelligent Tool Selection — reduce token usage by only including relevant tools.
*
* Instead of sending all 13 tools in every request (wasting context),
* analyze the user message and only include tools likely to be needed.
* Saves up to 80% of tool-definition tokens.
*/
import type { MCPToolDefinition, PermissionMap } from '../api/mcp/types'
interface ToolGroup {
keywords: string[]
tools: string[]
}
// Creative image/video. Surface BOTH generators for any creative request so
// the model can chain image → video in one conversation (the owner: "ein Video
// aus dem Bild soll die LLM auch machen können"). Without video_generate
// here the keyword path dropped it (it was in no group + not ALWAYS_INCLUDE),
// so a "now animate it" follow-up had no tool to call.
//
// Named constants rather than inline literals because gateCreateTools() below
// has to ask the SAME question on the cloud path. Two copies of this list would
// drift, and the failure mode of a drifted copy is a model that is told it can
// draw and then gets "unknown tool".
//
// The nouns beyond image/video (logo, icon, banner…) were added 2026-08-12 with
// the gate: on the local path a missed keyword only meant a slightly leaner
// list, on the cloud path it means a capability the user had yesterday is gone.
// A false positive here costs tokens, a false negative costs the feature, so
// the list leans generous.
// 'photo' and 'graphic' were missing next to their German twins 'foto' and
// 'grafik' (review 2026-08-14). The match is a substring test, so 'foto' does
// not cover 'photo' and 'grafik' does not cover 'graphic': the two commonest
// English words for the thing lost the capability on the paid path.
const MEDIA_KEYWORDS = [
'image', 'picture', 'photo', 'generate image', 'draw', 'create image', 'bild', 'foto', 'zeichne',
'logo', 'icon', 'thumbnail', 'banner', 'illustration', 'avatar', 'artwork', 'graphic', 'grafik', 'poster',
'video', 'animate', 'animation', 'clip', 'mp4', 'make a video', 'turn into a video', 'movie', 'gif', 'animiere',
]
const WORKFLOW_KEYWORDS = ['workflow', 'run workflow', 'automate']
// A6: the two remaining ride-alongs. pr_resume only ever fires on a PR link or
// a "continue this PR", delegate_task only on an explicit fan-out, and both
// carry a schema on every step of every coding run that never asks for either.
// Same words the TOOL_GROUPS router already uses, so the local and the cloud
// path answer the question identically.
const PR_KEYWORDS = [
'pull request', 'pull-request', 'open a pr', 'create a pr', 'the pr', 'this pr',
'github', 'gh pr', '/resume', 'pick up review', '/pull/',
]
/**
* Die Woerter, die `delegate_task` und seine zwei Begleiter ins Werkzeugregal
* holen.
*
* ZWEI Befunde vom 02.09.2026 stecken in dieser Liste, beide von einem
* Fable-Urteil gegen die Claude-Code-Desktop-App gefunden:
*
* 1. Sie war rein ENGLISCH. Der Nutzer schreibt Deutsch — „nutze 5 glm 5.2
* agenten" haette das Tor nicht geoeffnet, und das Werkzeug waere dem
* Modell nie angeboten worden. MEDIA_KEYWORDS hat aus genau diesem Grund
* am 14.08.2026 'bild', 'foto', 'zeichne' bekommen; hier ist es
* nachgeholt.
* 2. Das blosse Wort „agent" fehlte. Wer „starte 3 agenten" sagt, sagt
* nicht „delegate" und nicht „fan out". Es ist das nachliegendste Wort
* ueberhaupt und war das einzige, das nicht drinstand.
*/
const DELEGATE_KEYWORDS = [
// Englisch
'delegate', 'sub-agent', 'subagent', 'sub agent', 'fan out', 'fan-out',
'in parallel', 'parallel', 'parallelize', 'parallelise', 'split the work',
'agents', 'agent',
// Deutsch
'agenten', 'unteragent', 'aufteilen', 'aufteilung', 'nebenlaeufig',
'nebenläufig', 'gleichzeitig', 'im hintergrund', 'hintergrundaufgabe',
]
/**
* The words that bring get_settings and set_setting along (A11). Settings in
* general, in both languages, plus the names of the settings people ask for
* most. A false positive costs ~200 tokens on one turn; nothing changes
* without the user's yes on the card.
*/
export const SETTINGS_KEYWORDS = [
'setting', 'einstellung', 'preference', 'get_settings', 'set_setting',
'auto compact', 'auto-compact', 'autocompact', 'compact at', 'compact threshold',
'dark mode', 'light mode', 'darkmode', 'dark theme', 'light theme', 'dunkelmodus', 'dunklen modus', 'hellen modus', 'app theme',
'temperature', 'temperatur', 'top p', 'top_p', 'top k', 'top_k', 'max tokens',
'context window', 'kontextfenster', 'num_ctx', 'timeout', 'zeitlimit',
'reasoning effort', 'thinking budget', 'think budget', 'denkbudget', 'thinking mode',
'caveman', 'small model mode', 'small-model mode', 'emoji',
'search provider', 'suchanbieter', 'user agent', 'user-agent',
'gpu layers', 'flash attention', 'kv cache', 'download limit', 'repo map', 'review mode', 'architect mode',
]
/** True when a chat message is about LU's own settings. */
export function asksAboutSettings(userMessage: string): boolean {
const msg = (userMessage || '').toLowerCase()
return SETTINGS_KEYWORDS.some((k) => msg.includes(k))
}
/**
* The three tools that draw, film and automate. Everything else in the coding
* catalog earns its place on every turn; these three cost 1.963 of the 6.186
* tokens a coding step sends (measured 2026-08-12 through the real registry
* against the model's own tokenizer) and a coding turn almost never wants them.
*/
export const CREATE_TOOLS = ['image_generate', 'video_generate', 'run_workflow']
/**
* Every keyword-gated tool and the words that open its gate (A6).
*
* CREATE_TOOLS stays its own exported list because the Codex asset line keys
* off exactly those three; this map is the superset the filter walks.
*/
// C59 A6/A8: the words that bring memory and session_search (TOOL_GROUPS
// below) also open them on a cloud coding step (gateCreateTools).
const MEMORY_KEYWORDS: string[] = ['merk dir', 'merke dir', 'merk es', 'merk euch', 'remember', 'vergiss', 'forget that', 'notier dir',
'für später', 'for later', 'from now on', 'ab jetzt', 'in zukunft', 'in future', 'my preference', 'meine vorliebe']
const SESSION_KEYWORDS: string[] = ['früheren chat', 'frueheren chat', 'anderen chat', 'letzten chat', 'alten chat', 'in welchem chat', 'previous chat',
'earlier chat', 'other chat', 'earlier conversation', 'last time we', 'letztes mal', 'neulich', 'besprochen', 'we discussed',
'wir hatten', 'we talked', 'we decided', 'hatten wir', 'haben wir festgelegt']
/** The C59 tools that ride along only on their own words (see GATE_KEYWORDS). */
const ON_DEMAND_TOOLS = new Set(['memory', 'session_search', 'skill_view', 'skill_save'])
const GATE_KEYWORDS: Record<string, readonly string[]> = {
// C59 A6–A8: on demand only. Every step of a cloud coding run would pay
// ~2.5k characters for four tools a refactor never calls. memory and
// session_search open on their words; the skill tools are added by
// withSkillTools (lib/skill-tools.ts) when there are skills or the run may
// propose one, never by the catalog itself.
memory: MEMORY_KEYWORDS,
session_search: SESSION_KEYWORDS,
skill_view: [],
skill_save: [],
image_generate: MEDIA_KEYWORDS,
video_generate: MEDIA_KEYWORDS,
run_workflow: WORKFLOW_KEYWORDS,
pr_resume: PR_KEYWORDS,
delegate_task: DELEGATE_KEYWORDS,
// Dieselben Woerter wie delegate_task, und das ist keine Sparsamkeit,
// sondern die Bedeutung: beide Werkzeuge sprechen UEBER eine Delegation.
// Ohne eine gibt es nichts nachzusehen und niemanden anzureden.
//
// Der Deckel in tool-catalog-tokens.test.ts hat das erzwungen: die zwei
// Werkzeuge kosteten einen gewoehnlichen Refactor-Zug 844 Zeichen extra
// (+11 %), obwohl auf demselben Zug delegate_task laengst nicht mitfaehrt.
// Eine Sperre, die ein Budget haelt, hat hier einen Entwurfsfehler
// gefunden, nicht nur eine Zahl.
//
// Der Selbstheilungspfad traegt mit: ruft ein Lauf im sechsten Schritt doch
// delegate_task, oeffnet GATE_OPENING_TOOLS das Tor fuer den Rest des
// Laufs — und dann kommen diese beiden mit, genau wenn sie gebraucht werden.
check_tasks: DELEGATE_KEYWORDS,
message_agent: DELEGATE_KEYWORDS,
// A11: in Code only on a message about settings, like everywhere else.
// C60: all self-control tools (settings, models, services, downloads) on
// the wider gate generated from the settings catalog.
...Object.fromEntries(SELF_CONTROL_TOOL_NAMES.map((n) => [n, settingsGateWords()])),
// Watchers: only on a message about a later time or a repeat. A clock
// time alone ("um 18:00") is no word; Agent and chat add the tools by the
// full check (asksAboutWatchers), Code by withSelfControlTools.
...Object.fromEntries(WATCHER_TOOL_NAMES.map((n) => [n, WATCHER_GATE_WORDS])),
}
/**
* The names whose first real call must reopen the gate for the rest of the run
* (the createGateOpened self-heal). A run that discovers at step six that it
* needs a sub-agent, or that the task is a PR after all, gets the schema back
* from the next step instead of calling blind for the remaining twenty.
*/
export const GATE_OPENING_TOOLS: readonly string[] = Object.keys(GATE_KEYWORDS)
/** True when this tool only ships when the turn asked for it. */
export function isGatedTool(name: string): boolean {
return name in GATE_KEYWORDS
}
const TOOL_GROUPS: ToolGroup[] = [
{
// C59 A6: the user asks the agent to keep or drop something for later.
keywords: MEMORY_KEYWORDS,
tools: ['memory'],
},
{
// C59 A8: the user points at an earlier chat.
keywords: SESSION_KEYWORDS,
tools: ['session_search'],
},
{
// Web search intents. Only EXPLICIT web cues route here. Bare 'search',
// 'latest', 'current', 'aktuell', 'neueste', 'suche' were removed: they
// collide head-on with coding intents ("search the codebase", "fix the
// current bug", "the latest changes"), which used to pull web_search+
// web_fetch, inflate the selection past 3, and silently skip the file-tool
// booster below — leaving a coding turn with no file_search/file_list.
// German phrases kept as multi-word cues ("such im internet", "im internet")
// so a real "such im internet nach…" still surfaces web_search.
keywords: ['find online', 'look up', 'look it up', 'google', 'bing', 'duckduckgo', 'internet',
'news', 'web search', 'websearch', 'search online', 'search the web', 'browse', 'website', 'webseite',
'url', 'http://', 'https://', 'weather', 'wetter',
'such nach', 'such im', 'im internet', 'recherch', 'nachrichten', 'neueste'],
tools: ['web_research', 'web_fetch'],
},
{
// P-L (3.1.0): the LU browser, only when the user asks for a browser.
keywords: ['browser', 'im browser', 'in the browser', 'browse to', 'open the page', 'oeffne die seite', 'zeig mir die seite', 'show me the page'],
tools: ['browser_open', 'browser_scroll', 'browser_click_link'],
},
{
keywords: ['read', 'open', 'show', 'cat', 'content of', 'what does', 'look at', 'check file'],
tools: ['file_read'],
},
{
keywords: ['write', 'create', 'save', 'make a file', 'put', 'generate file', 'output to',
'edit', 'modify', 'change', 'replace', 'update', 'refactor', 'rename', 'fix', 'patch'],
// file_edit (surgical) is preferred for changing existing files; file_write
// for new files / full rewrites. Both surfaced so the model can pick.
tools: ['file_write', 'file_edit'],
},
{
keywords: ['list', 'ls', 'dir', 'files in', 'directory', 'folder', 'what files', 'tree'],
tools: ['file_list'],
},
{
keywords: ['search file', 'grep', 'find in', 'contains', 'where is', 'which file'],
tools: ['file_search'],
},
{
// Since the 2.6.6 merge shell_execute IS git, tests, background tasks
// and scaffolding, so every keyword that used to route a typed wrapper
// routes the one shell now (plan E4 point 7).
keywords: ['run', 'execute', 'command', 'shell', 'terminal', 'bash', 'powershell', 'npm', 'pip', 'node', 'python', 'install', 'build', 'compile',
'git', 'commit', 'push', 'branch', 'merge', 'rebase', 'stage', 'staged', 'diff', 'changelog', 'version control',
'test', 'tests', 'spec', 'vitest', 'jest', 'pytest', 'cargo test', 'failing', 'make it green', 'suite',
'background', 'long running', 'long-running', 'dataset', 'refactor everything', 'task status', 'still running',
'scaffold', 'new project', 'init a', 'initialize', 'bootstrap', 'starter'],
tools: ['shell_execute'],
},
{
keywords: ['pull request', 'pull-request', 'open a pr', 'create a pr', 'the pr', 'github', 'gh pr'],
tools: ['pr_resume', 'shell_execute'],
},
{
// EINE Liste, nicht zwei. Hier stand bis 2.6.8 eine abgeschriebene Kopie,
// und sie war schon auseinandergelaufen: 'sub agent', 'fan-out' und
// 'parallelise' fehlten, obwohl der Kommentar bei DELEGATE_KEYWORDS
// ausdruecklich verspricht, dass beide Wege „identisch antworten". Genau
// so entsteht der Fehler, den niemand sieht — der lokale Pfad oeffnet das
// Tor, der Cloud-Pfad nicht, und es haengt am Wort.
keywords: DELEGATE_KEYWORDS,
tools: ['delegate_task', 'check_tasks', 'message_agent'],
},
{
// system_info / process_list retired (2.6.6): the environment block in
// the system prompt covers OS and clock, the shell covers the rest.
keywords: ['system', 'os', 'cpu', 'ram', 'memory', 'process', 'running', 'hostname'],
tools: ['shell_execute'],
},
{
keywords: ['screenshot', 'screen', 'desktop', 'capture', 'see my screen'],
tools: ['screenshot'],
},
{
keywords: MEDIA_KEYWORDS,
tools: ['image_generate', 'video_generate'],
},
{
keywords: WORKFLOW_KEYWORDS,
tools: ['run_workflow'],
},
{
// C60: the self-control tools on the gate generated from the catalog.
keywords: settingsGateWords(),
tools: [...SELF_CONTROL_TOOL_NAMES],
},
{
keywords: [...WATCHER_GATE_WORDS],
tools: [...WATCHER_TOOL_NAMES],
},
]
// Tools that should always be available regardless of the prompt — they're
// cheap to include, commonly useful, and often needed mid-run (e.g. after
// a tool result reveals the user really wanted a file read). The clock lives
// in the system prompt's environment block now, so no time tool is needed.
// `todo_write` is here rather than in a keyword group on purpose: the moment a
// task turns out to need a plan is usually mid-run, several tool results after
// the prompt that routed the catalog. Keyword-gating it would mean the agent
// can only plan when the user happened to say "plan".
/**
* Die Werkzeuge, deren Gruppe "die Nachricht handelt von diesem Rechner" sagt.
*
* Nicht dieselbe Liste wie ALWAYS_INCLUDE, und der Unterschied ist der Punkt:
* hier steht, WORAN man ein Projektanliegen erkennt, dort, was ein Zug immer
* dabei hat. Trifft eine Gruppe mit einem dieser Werkzeuge, ist die Nachricht
* kein "erklaer mir das mal" mehr, sondern eine Arbeit an Dateien — und dann
* gehoert das Web-Paar nicht ungefragt in einen Deckel mit zwei freien Plaetzen.
*
* `screenshot` fehlt bewusst: ein Bildschirmfoto sagt nichts darueber, ob es um
* das Projekt geht. `pr_resume` steht drin, weil ein PR immer einer ueber
* diesen Baum ist.
*/
const LOKALE_WERKZEUGE = new Set<string>([
'file_read', 'file_write', 'file_edit', 'file_list', 'file_search',
'shell_execute', 'pr_resume',
])
export const ALWAYS_INCLUDE = ['file_read', 'file_write', 'file_edit', 'todo_write']
/**
* The tool cap Small-Model Mode sends to a 3B-8B model.
*
* Derived, not typed: ALWAYS_INCLUDE is a floor the cap cannot cut into, so a
* fixed number silently shrinks the router every time that set grows. It was
* 6 against 4 always-included tools, which left the semantic router 2 slots.
* Adding todo_write (2026-08-05) cut that to 1 without anyone touching the
* cap, and a coding turn with exactly one routed tool loses file_list AND
* file_search AND shell_execute. Two free slots is the number the research
* behind this mode was tuned on, so that is what is preserved.
*/
export const SMALL_MODEL_MAX_TOOLS = ALWAYS_INCLUDE.length + 2
/** Tool count at which embedding-based routing becomes worth the round trip. */
export const EMBEDDING_ROUTING_THRESHOLD = 15
import type { EmbeddingFn } from '../api/agents/embedding-router'
import { REA_SERVER_ID, reaToolsFor } from './plugins/rea-tools'
import { SELF_CONTROL_TOOL_NAMES, settingsGateWords } from './settings-tool-names'
import { WATCHER_TOOL_NAMES, WATCHER_GATE_WORDS } from './watcher-tool-names'
import { selectToolsByEmbedding } from '../api/agents/embedding-router'
import { isMobile } from './device-kind'
/**
* Select relevant tools based on user message content.
* Returns a filtered list of tool names.
*/
export function selectRelevantTools(
userMessage: string,
allTools: MCPToolDefinition[],
permissions: PermissionMap,
maxTools?: number,
/** What REA's tools are routed on, when the caller knows the conversation
* (rea-tools reaRoutingText). Falls back to this message alone. */
reaText?: string,
): MCPToolDefinition[] {
const msg = userMessage.toLowerCase()
const selectedNames = new Set<string>(ALWAYS_INCLUDE)
// Match tool groups by keywords
//
// `lokaleArbeit` haelt fest, ob eine der getroffenen Gruppen von Dateien
// oder der Shell handelt. Ohne diese Notiz ist das eine Zeile weiter unten
// nicht mehr erkennbar: die Gruppe fuer 'fix'/'refactor'/'edit' fuehrt
// file_write und file_edit, und beide stehen ohnehin in ALWAYS_INCLUDE. Ein
// Treffer dieser Gruppe aendert die MENGE also nicht — "fix the current bug
// in auth.ts" kommt am Rueckfall unten mit genau vier Namen an und ist von
// "erklaer mir das mal" nicht mehr zu unterscheiden. Genau daran hing der
// Fehler, den dieser Block behebt.
let lokaleArbeit = false
for (const group of TOOL_GROUPS) {
if (group.keywords.some(kw => msg.includes(kw))) {
if (group.tools.some(t => LOKALE_WERKZEUGE.has(t))) lokaleArbeit = true
group.tools.forEach(t => selectedNames.add(t))
}
}
// External (MCP) tools can never match TOOL_GROUPS — the groups only know
// the builtin names, so on this path a connected server's tools were
// unreachable no matter what the user typed. Connecting the server is
// itself the signal that its tools are wanted: always offer them.
// REA (lib/plugins/rea-tools.ts) is the exception: its 207 tools would fill
// a local model's context, so a turn gets the ones its words point at.
for (const t of allTools) {
if (t.source === 'external' && t.serverId !== REA_SERVER_ID) selectedNames.add(t.name)
}
const reaNames = allTools.filter((t) => t.serverId === REA_SERVER_ID).map((t) => t.name)
if (reaNames.length > 0) for (const n of reaToolsFor(reaText ?? userMessage, reaNames)) selectedNames.add(n)
// A tool the user names verbatim is always offered, builtin or external.
for (const t of allTools) {
if (msg.includes(t.name.toLowerCase())) selectedNames.add(t.name)
}
// If nothing beyond the always-included tools matched, include a broad set
// (model might need flexibility). Handles generic messages like "help me with
// this project". Threshold is ALWAYS_INCLUDE.length so adding an always-tool
// (e.g. file_edit) doesn't silently disable this fallback.
if (selectedNames.size <= ALWAYS_INCLUDE.length) {
// Include common tools for generic requests
selectedNames.add('shell_execute')
selectedNames.add('file_list')
selectedNames.add('file_search')
// Web nur fuer Nachrichten, die NICHT erkennbar vom Projekt handeln — und
// dann als PAAR. Beide Haelften dieser Bedingung sind gemessen:
//
// Halb (web_search allein) war der Zustand bis 02.09.2026. "was ist die
// hauptstadt von frankreich" bekam eine Suche und keinen Weg, die Treffer
// zu lesen. Schwerer wiegt, dass der Hermes-Systemprompt seine Warnung an
// das PAAR haengt (`has('web_search') && has('web_fetch')`): "web_search
// returns ONLY short snippets, NOT real data." Ohne web_fetch verschwindet
// genau der Satz, der erklaert, warum Schnipsel keine Antwort sind.
//
// Ungefragt (das Paar auch fuer Coding-Zuege) war der erste Versuch, das
// zu beheben, und er kostete mehr, als er brachte. Unter dem
// Small-Model-Deckel (SMALL_MODEL_MAX_TOOLS = 6, davon vier belegt) bleiben
// zwei Plaetze. Gemessen fuer "fix the current bug in auth.ts":
//
// vorher … web_search, file_list
// Paar ungefragt … web_search, web_fetch ← file_list weg
//
// Der Coding-Zug verlor damit sein letztes Werkzeug, um Dateien zu finden
// — dieselbe Regression, gegen die die Sperren in tool-selection.test.ts
// ("coding intent routing") gebaut wurden.
// P-L (3.1.0): web_research takes the place of web_search here. It
// searches AND reads in one call, so a small model under the cap gets
// real page text without a second round, and the pair still costs only
// two places.
if (!lokaleArbeit) {
selectedNames.add('web_research')
selectedNames.add('web_fetch')
}
}
// Coding-discovery safety net (independent of the total count above). Any
// message that surfaced a shell / code / file tool but lacks the file-
// discovery pair cannot actually explore the codebase: "run the tests and
// find the failing spec" matches shell_execute, pushes the count past 3, and
// would otherwise skip the booster — leaving no file_search/file_list. Add
// the discovery trio (never web_search) so coding intents can always locate
// files, which is exactly what CODEX_SYSTEM_PROMPT tells the model to do.
const hasCodeSignal =
selectedNames.has('shell_execute') ||
selectedNames.has('file_search') ||
selectedNames.has('file_list')
if (hasCodeSignal) {
selectedNames.add('shell_execute')
selectedNames.add('file_list')
selectedNames.add('file_search')
}
// Das Web-Paar bleibt zusammen — die zweite Sicherung.
//
// Der Rueckfall oben legt das Paar schon vollstaendig ab, diese Zeile faengt
// die anderen Wege: die Verbatim-Erwaehnung ("nimm web_search dafuer") nennt
// eine Haelfte, und jeder kuenftige Pfad, der das wieder tut, laeuft hier
// hinein statt am Nutzer. Der Grund ist derselbe wie oben — der Hermes-Prompt
// haengt seine Snippet-Warnung an `has('web_search') && has('web_fetch')`.
//
// NUR in diese Richtung: web_fetch kommt zu web_search, nicht umgekehrt. Wer
// eine URL hat, braucht keine Suche, und unter dem Small-Model-Deckel kostet
// jedes ungefragte Werkzeug einen von zwei freien Plaetzen.
if (selectedNames.has('web_search') || selectedNames.has('web_research')) selectedNames.add('web_fetch')
// A catalog without web_research (a surface that does not register it)
// keeps the old pair. So does the phone: its ordered search ("Websuche:
// …") pins web_search, and web_research was not checked on a phone yet.
if (selectedNames.has('web_research') && (isMobile() || !allTools.some((t) => t.name === 'web_research'))) {
selectedNames.delete('web_research')
selectedNames.add('web_search')
}
// Filter by permissions (blocked categories excluded)
const available = allTools.filter(t => permissions[t.category] !== 'blocked')
// Return only selected tools that are available
const selected = available.filter(t => selectedNames.has(t.name))
// Safety: if nothing matched at all, return all available tools
if (selected.length === 0) return applyMaxTools(available, maxTools)
// Small-Model Mode (Knob 1): cap the catalog when maxTools is set. No-op
// (returns `selected` unchanged) when unset — default behaviour preserved.
return applyMaxTools(selected, maxTools, undefined, mentionedToolNames(userMessage, allTools))
}
/**
* Drop the create tools unless this instruction actually asks for them.
*
* The keyword router already does this for local models. A CLOUD model gets
* the coding catalog untouched (useCodex.ts: a hosted model handles 25+ tools
* fine, and guessing its toolbox from message one starved long runs of
* git_commit mid-way), so image_generate + video_generate + run_workflow rode
* along on every step of every paid coding run: 2.160 tokens per step for
* three tools a refactor never calls. This closes exactly that gap and leaves
* the rest of the catalog alone.
*
* Gated per tool, not as a block, so the behaviour matches TOOL_GROUPS above:
* a creative intent surfaces the two generators, a workflow intent surfaces
* run_workflow, and naming a tool verbatim always wins.
*
* The decision starts from the run's instruction, and `opened` reopens it for
* the rest of the run. That second half is not a nicety: "build me a landing
* page for my bakery" hits no keyword, and at step six the model wants a hero
* image. Before the gate it simply called image_generate and it worked, because
* toolRegistry.execute resolves by name and never consults the offered list.
* Without a way back the model instead writes a reference to a file that will
* never exist and reports success. So the first real call is honoured, and from
* the next step the schemas ride along openly.
*/
export function gateCreateTools<T extends { name: string }>(
defs: T[],
userMessage: string,
opened: boolean | Iterable<string> = false,
): T[] {
// A caller that tracks WHICH tool reopened the gate may pass the names; the
// boolean form stays the run-wide "everything is open again" it always was,
// for the create tools. The C59 tools stay on their own words: a creative
// run has no more use for them than a refactor.
const reopened = opened === false || opened === true ? null : new Set(opened)
const msg = userMessage.toLowerCase()
return defs.filter((t) => {
const words = GATE_KEYWORDS[t.name]
if (!words) return true
if (opened === true && !ON_DEMAND_TOOLS.has(t.name)) return true
if (reopened?.has(t.name)) return true
if (msg.includes(t.name)) return true
return words.some((k) => msg.includes(k))
})
}
/** True when the instruction asks for a picture or a clip. Drives the asset
* line in the Codex system prompt so the prompt and the tool list agree. */
export function wantsMediaTools(userMessage: string): boolean {
const msg = userMessage.toLowerCase()
return (
MEDIA_KEYWORDS.some((k) => msg.includes(k)) ||
msg.includes('image_generate') ||
msg.includes('video_generate')
)
}
/** Names of tools the message mentions verbatim (case-insensitive). */
function mentionedToolNames(userMessage: string, tools: MCPToolDefinition[]): string[] {
const msg = userMessage.toLowerCase()
return tools.filter((t) => msg.includes(t.name.toLowerCase())).map((t) => t.name)
}
/**
* Hard-cap a tool list to `maxTools` entries (Small-Model Mode, Knob 1).
* ALWAYS_INCLUDE tools are kept first (cheap + often needed mid-run); the
* remainder fills from the incoming order, or from `rankOrder` when supplied
* (the embedding-ranked names from the async path) so the most semantically
* relevant tools survive the cut. Strict no-op when `maxTools` is unset or
* the list already fits — big models keep the exact original list + order.
*
* Evidence: tool-catalog length is the confirmed killer for small models
* (LongFuncEval arXiv 2505.10570 — 8B models lose 7.6-85.6% as the catalog
* grows). Fewer tools is the single biggest fine-tuning-free win.
*/
export function applyMaxTools(
defs: MCPToolDefinition[],
maxTools?: number,
rankOrder?: string[],
pinned?: string[],
): MCPToolDefinition[] {
if (!maxTools || maxTools <= 0 || defs.length <= maxTools) return defs
// Pinned tools (named verbatim by the user) rank with ALWAYS_INCLUDE and
// may push past maxTools: an explicit mention outranks the budget.
const keep = (t: MCPToolDefinition) =>
ALWAYS_INCLUDE.includes(t.name) || (pinned?.includes(t.name) ?? false)
const always = defs.filter(keep)
let rest = defs.filter((t) => !keep(t))
if (rankOrder && rankOrder.length > 0) {
const idx = (name: string) => {
const i = rankOrder.indexOf(name)
return i === -1 ? Number.MAX_SAFE_INTEGER : i
}
rest = [...rest].sort((a, b) => idx(a.name) - idx(b.name))
}
const out = [...always]
for (const t of rest) {
if (out.length >= maxTools) break
out.push(t)
}
return out
}
/**
* Embedding-aware variant (Phase 9 v2.4.0). When `embed` is provided AND
* the permission-filtered tool count exceeds EMBEDDING_ROUTING_THRESHOLD,
* rank tools by semantic similarity to the user message and union the
* result with the keyword-based selection (belt + braces). When `embed`
* is absent, throws, or fails, silently falls back to the keyword-only
* path.
*/
/**
* Wie eng ein Small-Model-Zug die Werkzeugliste zieht.
*
* `topN` ist, wie viele der semantische Router hoechstens vorschlaegt;
* `embeddingThreshold` ist die Katalogroesse, ab der ueberhaupt semantisch
* geroutet statt nur nach Stichworten gefiltert wird. Beide standen bis
* 2026-09-02 als nackte Zahlen im Aufruf in useAgentChat.ts — 5 und 6, ohne
* Namen, ohne Begruendung, an genau einer von zwei Stellen, die sie brauchen.
*/
const SMALL_MODEL_TOP_N = 5
const SMALL_MODEL_EMBEDDING_THRESHOLD = 6
/**
* Die Stellschrauben der Werkzeug-Vorauswahl, an EINER Stelle.
*
* ── WARUM DAS EINE FUNKTION IST UND KEIN OBJEKTLITERAL AM AUFRUF ───────────
*
* Weil die Abweichung, die sie behebt, genau so entstanden ist. Bis
* 2026-09-02 stand dieses Objekt ausgeschrieben im NATIVEN Zweig von
* useAgentChat.ts — und nur dort. Der hermes_xml-Zweig derselben Datei nahm
* stattdessen `toolRegistry.toHermesToolDefs(permissions)`, also den ganzen
* Katalog, ohne Vorauswahl und ohne Deckel.
*
* Nichts an dieser Auslassung war sichtbar: kein Fehler, kein Test, keine
* Warnung. Sie fiel erst auf, als jemand nachrechnete. Gemessen an dem Tag:
* 17 Werkzeuge ergaben einen Hermes-Prompt von 19.459 Zeichen (≈ 4.866 Token),
* bei einem Sendefenster von 4.096 Token fuer die Modelle, die auf diesem
* Rueckfallweg ueberhaupt landen — die Liste allein war 119 % des Fensters.
*
* Zwei Objektliterale koennen wieder auseinanderlaufen. Eine Funktion, die
* beide Zweige rufen, kann es nicht. Eine Sperrklinke in
* lib/__tests__/hermes-werkzeugauswahl.test.ts haelt fest, dass keiner der
* beiden Zweige die Zahlen wieder selbst ausbuchstabiert.
*/
export function toolSelectionOpts(
smallModelMode: boolean,
embed?: EmbeddingFn,
): { embed?: EmbeddingFn; embeddingThreshold?: number; topN?: number; maxTools?: number } {
return smallModelMode
? {
embed,
topN: SMALL_MODEL_TOP_N,
embeddingThreshold: SMALL_MODEL_EMBEDDING_THRESHOLD,
maxTools: SMALL_MODEL_MAX_TOOLS,
}
: { embed }
}
export async function selectRelevantToolsAsync(
userMessage: string,
allTools: MCPToolDefinition[],
permissions: PermissionMap,
opts?: {
embed?: EmbeddingFn; embeddingThreshold?: number; topN?: number; maxTools?: number; reaText?: string
/** Keyword picks that go ahead of the semantic ranking under the cap
* (agent-profile COMPACT_PREFER). Unset: the ranking alone, as before. */
prefer?: readonly string[]
},
): Promise<MCPToolDefinition[]> {
const threshold = opts?.embeddingThreshold ?? EMBEDDING_ROUTING_THRESHOLD
const available = allTools.filter((t) => permissions[t.category] !== 'blocked')
const pinned = mentionedToolNames(userMessage, available)
if (!opts?.embed || available.length <= threshold) {
return applyMaxTools(selectRelevantTools(userMessage, allTools, permissions, undefined, opts?.reaText), opts?.maxTools, opts?.prefer ? [...opts.prefer] : undefined, pinned)
}
try {
const semanticNames = await selectToolsByEmbedding(
userMessage,
available.map((t) => ({ name: t.name, description: t.description })),
opts.embed,
{ topN: opts.topN ?? 10, alwaysInclude: ALWAYS_INCLUDE },
)
const keyword = selectRelevantTools(userMessage, allTools, permissions, undefined, opts?.reaText)
const union = new Set<string>([...semanticNames, ...keyword.map((t) => t.name)])
const selected = available.filter((t) => union.has(t.name))
const keywordNames = new Set(keyword.map((t) => t.name))
const rank = opts.prefer
? [...opts.prefer.filter((n) => keywordNames.has(n)), ...semanticNames]
: semanticNames
// Small-Model Mode (Knob 1): cap the union to maxTools, filling from
// embedding-rank order so the most relevant tools survive. No-op when
// maxTools is unset → `selected` (and its original order) is returned
// byte-identical, so big-model behaviour is unchanged. Verbatim-named
// tools are pinned past the cap on both paths.
return applyMaxTools(selected, opts.maxTools, rank, pinned)
} catch {
return applyMaxTools(selectRelevantTools(userMessage, allTools, permissions, undefined, opts?.reaText), opts?.maxTools, opts?.prefer ? [...opts.prefer] : undefined, pinned)
}
}