ruflo 3.5.2 → 3.5.3

package/src/ruvocal/src/lib/server/textGeneration/mcp/toolInvocation.ts

@@ -0,0 +1,349 @@
+import { randomUUID } from "crypto";
+import { logger } from "../../logger";
+import type { MessageUpdate } from "$lib/types/MessageUpdate";
+import { MessageToolUpdateType, MessageUpdateType } from "$lib/types/MessageUpdate";
+import { ToolResultStatus } from "$lib/types/Tool";
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+import type { McpToolMapping } from "$lib/server/mcp/tools";
+import type { McpServerConfig } from "$lib/server/mcp/httpClient";
+import {
+	callMcpTool,
+	getMcpToolTimeoutMs,
+	type McpToolTextResponse,
+} from "$lib/server/mcp/httpClient";
+import { getClient } from "$lib/server/mcp/clientPool";
+import { attachFileRefsToArgs, type FileRefResolver } from "./fileRefs";
+import type { Client } from "@modelcontextprotocol/sdk/client";
+
+export type Primitive = string | number | boolean;
+
+export type ToolRun = {
+	name: string;
+	parameters: Record<string, Primitive>;
+	output: string;
+};
+
+export interface NormalizedToolCall {
+	id: string;
+	name: string;
+	arguments: string;
+}
+
+export interface ExecuteToolCallsParams {
+	calls: NormalizedToolCall[];
+	mapping: Record<string, McpToolMapping>;
+	servers: McpServerConfig[];
+	parseArgs: (raw: unknown) => Record<string, unknown>;
+	resolveFileRef?: FileRefResolver;
+	toPrimitive: (value: unknown) => Primitive | undefined;
+	processToolOutput: (text: string) => {
+		annotated: string;
+		sources: { index: number; link: string }[];
+	};
+	abortSignal?: AbortSignal;
+	toolTimeoutMs?: number;
+}
+
+export interface ToolCallExecutionResult {
+	toolMessages: ChatCompletionMessageParam[];
+	toolRuns: ToolRun[];
+	finalAnswer?: { text: string; interrupted: boolean };
+}
+
+export type ToolExecutionEvent =
+	| { type: "update"; update: MessageUpdate }
+	| { type: "complete"; summary: ToolCallExecutionResult };
+
+const serverMap = (servers: McpServerConfig[]): Map<string, McpServerConfig> => {
+	const map = new Map<string, McpServerConfig>();
+	for (const server of servers) {
+		if (server?.name) {
+			map.set(server.name, server);
+		}
+	}
+	return map;
+};
+
+export async function* executeToolCalls({
+	calls,
+	mapping,
+	servers,
+	parseArgs,
+	resolveFileRef,
+	toPrimitive,
+	processToolOutput,
+	abortSignal,
+	toolTimeoutMs,
+}: ExecuteToolCallsParams): AsyncGenerator<ToolExecutionEvent, void, undefined> {
+	const effectiveTimeoutMs = toolTimeoutMs ?? getMcpToolTimeoutMs();
+	const toolMessages: ChatCompletionMessageParam[] = [];
+	const toolRuns: ToolRun[] = [];
+	const serverLookup = serverMap(servers);
+	// Pre-emit call + ETA updates and prepare tasks
+	type TaskResult = {
+		index: number;
+		output?: string;
+		structured?: unknown;
+		blocks?: unknown[];
+		error?: string;
+		uuid: string;
+		paramsClean: Record<string, Primitive>;
+	};
+
+	const prepared = calls.map((call) => {
+		const argsObj = parseArgs(call.arguments);
+		const paramsClean: Record<string, Primitive> = {};
+		for (const [k, v] of Object.entries(argsObj ?? {})) {
+			const prim = toPrimitive(v);
+			if (prim !== undefined) paramsClean[k] = prim;
+		}
+		// Attach any resolved image payloads _after_ computing paramsClean so that
+		// logging / status updates continue to show only the lightweight primitive
+		// arguments (e.g. "image_1") while the full data: URLs or image blobs are
+		// only sent to the MCP tool server.
+		attachFileRefsToArgs(argsObj, resolveFileRef);
+		return { call, argsObj, paramsClean, uuid: randomUUID() };
+	});
+
+	for (const p of prepared) {
+		yield {
+			type: "update",
+			update: {
+				type: MessageUpdateType.Tool,
+				subtype: MessageToolUpdateType.Call,
+				uuid: p.uuid,
+				call: { name: p.call.name, parameters: p.paramsClean },
+			},
+		};
+		yield {
+			type: "update",
+			update: {
+				type: MessageUpdateType.Tool,
+				subtype: MessageToolUpdateType.ETA,
+				uuid: p.uuid,
+				eta: 10,
+			},
+		};
+	}
+
+	// Preload clients per distinct server used in this batch
+	const distinctServerNames = Array.from(
+		new Set(prepared.map((p) => mapping[p.call.name]?.server).filter(Boolean) as string[])
+	);
+	const clientMap = new Map<string, Client>();
+	await Promise.all(
+		distinctServerNames.map(async (name) => {
+			const cfg = serverLookup.get(name);
+			if (!cfg) return;
+			try {
+				const client = await getClient(cfg, abortSignal);
+				clientMap.set(name, client);
+			} catch (e) {
+				logger.warn({ server: name, err: String(e) }, "[mcp] failed to connect client");
+			}
+		})
+	);
+
+	// Async queue to stream results in finish order
+	function createQueue<T>() {
+		const items: T[] = [];
+		const waiters: Array<(v: IteratorResult<T>) => void> = [];
+		let closed = false;
+		return {
+			push(item: T) {
+				const waiter = waiters.shift();
+				if (waiter) waiter({ value: item, done: false });
+				else items.push(item);
+			},
+			close() {
+				closed = true;
+				let waiter: ((v: IteratorResult<T>) => void) | undefined;
+				while ((waiter = waiters.shift())) {
+					waiter({ value: undefined as unknown as T, done: true });
+				}
+			},
+			async *iterator() {
+				for (;;) {
+					if (items.length) {
+						const first = items.shift();
+						if (first !== undefined) yield first as T;
+						continue;
+					}
+					if (closed) return;
+					const value: IteratorResult<T> = await new Promise((res) => waiters.push(res));
+					if (value.done) return;
+					yield value.value as T;
+				}
+			},
+		};
+	}
+
+	const updatesQueue = createQueue<MessageUpdate>();
+	const results: TaskResult[] = [];
+
+	const tasks = prepared.map(async (p, index) => {
+		// Check abort before starting each tool call
+		if (abortSignal?.aborted) {
+			const message = "Aborted by user";
+			results.push({
+				index,
+				error: message,
+				uuid: p.uuid,
+				paramsClean: p.paramsClean,
+			});
+			updatesQueue.push({
+				type: MessageUpdateType.Tool,
+				subtype: MessageToolUpdateType.Error,
+				uuid: p.uuid,
+				message,
+			});
+			return;
+		}
+
+		const mappingEntry = mapping[p.call.name];
+		if (!mappingEntry) {
+			const message = `Unknown MCP function: ${p.call.name}`;
+			results.push({
+				index,
+				error: message,
+				uuid: p.uuid,
+				paramsClean: p.paramsClean,
+			});
+			updatesQueue.push({
+				type: MessageUpdateType.Tool,
+				subtype: MessageToolUpdateType.Error,
+				uuid: p.uuid,
+				message,
+			});
+			return;
+		}
+		const serverCfg = serverLookup.get(mappingEntry.server);
+		if (!serverCfg) {
+			const message = `Unknown MCP server: ${mappingEntry.server}`;
+			results.push({
+				index,
+				error: message,
+				uuid: p.uuid,
+				paramsClean: p.paramsClean,
+			});
+			updatesQueue.push({
+				type: MessageUpdateType.Tool,
+				subtype: MessageToolUpdateType.Error,
+				uuid: p.uuid,
+				message,
+			});
+			return;
+		}
+		const client = clientMap.get(mappingEntry.server);
+		try {
+			logger.debug(
+				{ server: mappingEntry.server, tool: mappingEntry.tool, parameters: p.paramsClean },
+				"[mcp] invoking tool"
+			);
+			const toolResponse: McpToolTextResponse = await callMcpTool(
+				serverCfg,
+				mappingEntry.tool,
+				p.argsObj,
+				{
+					client,
+					signal: abortSignal,
+					timeoutMs: effectiveTimeoutMs,
+					onProgress: (progress) => {
+						updatesQueue.push({
+							type: MessageUpdateType.Tool,
+							subtype: MessageToolUpdateType.Progress,
+							uuid: p.uuid,
+							progress: progress.progress,
+							total: progress.total,
+							message: progress.message,
+						});
+					},
+				}
+			);
+			const { annotated } = processToolOutput(toolResponse.text ?? "");
+			logger.debug(
+				{ server: mappingEntry.server, tool: mappingEntry.tool },
+				"[mcp] tool call completed"
+			);
+			results.push({
+				index,
+				output: annotated,
+				structured: toolResponse.structured,
+				blocks: toolResponse.content,
+				uuid: p.uuid,
+				paramsClean: p.paramsClean,
+			});
+			updatesQueue.push({
+				type: MessageUpdateType.Tool,
+				subtype: MessageToolUpdateType.Result,
+				uuid: p.uuid,
+				result: {
+					status: ToolResultStatus.Success,
+					call: { name: p.call.name, parameters: p.paramsClean },
+					outputs: [
+						{
+							text: annotated ?? "",
+							structured: toolResponse.structured,
+							content: toolResponse.content,
+						} as unknown as Record<string, unknown>,
+					],
+					display: true,
+				},
+			});
+		} catch (err) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			const errName = err instanceof Error ? err.name : "";
+			const isAbortError =
+				abortSignal?.aborted ||
+				errName === "AbortError" ||
+				errName === "APIUserAbortError" ||
+				errMsg === "Request was aborted." ||
+				errMsg === "This operation was aborted";
+			const message = isAbortError ? "Aborted by user" : errMsg;
+
+			if (isAbortError) {
+				logger.debug(
+					{ server: mappingEntry.server, tool: mappingEntry.tool },
+					"[mcp] tool call aborted by user"
+				);
+			} else {
+				logger.warn(
+					{ server: mappingEntry.server, tool: mappingEntry.tool, err: message },
+					"[mcp] tool call failed"
+				);
+			}
+			results.push({ index, error: message, uuid: p.uuid, paramsClean: p.paramsClean });
+			updatesQueue.push({
+				type: MessageUpdateType.Tool,
+				subtype: MessageToolUpdateType.Error,
+				uuid: p.uuid,
+				message,
+			});
+		}
+	});
+
+	// kick off and stream as they finish
+	Promise.allSettled(tasks).then(() => updatesQueue.close());
+
+	for await (const update of updatesQueue.iterator()) {
+		yield { type: "update", update };
+	}
+
+	// Collate outputs in original call order
+	results.sort((a, b) => a.index - b.index);
+	for (const r of results) {
+		const name = prepared[r.index].call.name;
+		const id = prepared[r.index].call.id;
+		if (!r.error) {
+			const output = r.output ?? "";
+			toolRuns.push({ name, parameters: r.paramsClean, output });
+			// For the LLM follow-up call, we keep only the textual output
+			toolMessages.push({ role: "tool", tool_call_id: id, content: output });
+		} else {
+			// Communicate error to LLM so it doesn't hallucinate success
+			toolMessages.push({ role: "tool", tool_call_id: id, content: `Error: ${r.error}` });
+		}
+	}
+
+	yield { type: "complete", summary: { toolMessages, toolRuns } };
+}

package/src/ruvocal/src/lib/server/textGeneration/reasoning.ts

@@ -0,0 +1,23 @@
+import { generateFromDefaultEndpoint } from "$lib/server/generateFromDefaultEndpoint";
+import { MessageUpdateType } from "$lib/types/MessageUpdate";
+
+export async function generateSummaryOfReasoning(
+	reasoning: string,
+	modelId: string | undefined,
+	locals: App.Locals | undefined
+): Promise<string> {
+	const prompt = `Summarize concisely the following reasoning for the user. Keep it short (one short paragraph).\n\n${reasoning}`;
+	const summary = await (async () => {
+		const it = generateFromDefaultEndpoint({
+			messages: [{ from: "user", content: prompt }],
+			modelId,
+			locals,
+		});
+		let out = "";
+		for await (const update of it) {
+			if (update.type === MessageUpdateType.Stream) out += update.token;
+		}
+		return out;
+	})();
+	return summary.trim();
+}

package/src/ruvocal/src/lib/server/textGeneration/title.ts

@@ -0,0 +1,83 @@
+import { config } from "$lib/server/config";
+import { generateFromDefaultEndpoint } from "$lib/server/generateFromDefaultEndpoint";
+import { logger } from "$lib/server/logger";
+import { MessageUpdateType, type MessageUpdate } from "$lib/types/MessageUpdate";
+import type { Conversation } from "$lib/types/Conversation";
+import { getReturnFromGenerator } from "$lib/utils/getReturnFromGenerator";
+
+export async function* generateTitleForConversation(
+	conv: Conversation,
+	locals: App.Locals | undefined
+): AsyncGenerator<MessageUpdate, undefined, undefined> {
+	try {
+		const userMessage = conv.messages.find((m) => m.from === "user");
+		// HACK: detect if the conversation is new
+		if (conv.title !== "New Chat" || !userMessage) return;
+
+		const prompt = userMessage.content;
+		const modelForTitle = config.TASK_MODEL?.trim() ? config.TASK_MODEL : conv.model;
+		const title = (await generateTitle(prompt, modelForTitle, locals)) ?? "New Chat";
+
+		yield {
+			type: MessageUpdateType.Title,
+			title,
+		};
+	} catch (cause) {
+		logger.error(cause, "Failed while generating title for conversation");
+	}
+}
+
+async function generateTitle(
+	prompt: string,
+	modelId: string | undefined,
+	locals: App.Locals | undefined
+) {
+	if (config.LLM_SUMMARIZATION !== "true") {
+		// When summarization is disabled, use the first five words without adding emojis
+		return prompt.split(/\s+/g).slice(0, 5).join(" ");
+	}
+
+	// Tools removed: no tool-based title path
+
+	return await getReturnFromGenerator(
+		generateFromDefaultEndpoint({
+			messages: [{ from: "user", content: `User message: "${prompt}"` }],
+			preprompt: `You are a chat thread titling assistant.
+Goal: Produce a very short, descriptive title (2–4 words) that names the topic of the user's first message.
+
+Rules:
+- Output ONLY the title text. No prefixes, labels, quotes, emojis, hashtags, or trailing punctuation.
+- Use the user's language.
+- Write a noun phrase that names the topic. Do not write instructions.
+- Never output just a pronoun (me/you/I/we/us/myself/yourself). Prefer a neutral subject (e.g., "Assistant", "model", or the concrete topic).
+- Never include meta-words: Summarize, Summary, Title, Prompt, Topic, Subject, About, Question, Request, Chat.
+
+Examples:
+User: "Summarize hello" -> Hello
+User: "How do I reverse a string in Python?" -> Python string reversal
+User: "help me plan a NYC weekend" -> NYC weekend plan
+User: "请解释Transformer是如何工作的" -> Transformer 工作原理
+User: "tell me more about you" -> About the assistant
+Return only the title text.`,
+			generateSettings: {
+				max_tokens: 24,
+				temperature: 0,
+			},
+			modelId,
+			locals,
+		})
+	)
+		.then((summary) => {
+			const firstFive = prompt.split(/\s+/g).slice(0, 5).join(" ");
+			const trimmed = String(summary ?? "").trim();
+			// Fallback: if empty, return first five words only (no emoji)
+			return trimmed || firstFive;
+		})
+		.catch((e) => {
+			logger.error(e, "Error generating title");
+			const firstFive = prompt.split(/\s+/g).slice(0, 5).join(" ");
+			return firstFive;
+		});
+}
+
+// No post-processing: rely solely on prompt instructions above

package/src/ruvocal/src/lib/server/textGeneration/types.ts

@@ -0,0 +1,26 @@
+import type { ProcessedModel } from "../models";
+import type { Endpoint } from "../endpoints/endpoints";
+import type { Conversation } from "$lib/types/Conversation";
+import type { Message } from "$lib/types/Message";
+import type { Assistant } from "$lib/types/Assistant";
+
+export interface TextGenerationContext {
+	model: ProcessedModel;
+	endpoint: Endpoint;
+	conv: Conversation;
+	messages: Message[];
+	assistant?: Pick<Assistant, "dynamicPrompt" | "generateSettings">;
+	promptedAt: Date;
+	ip: string;
+	username?: string;
+	/** Force-enable multimodal handling for endpoints that support it */
+	forceMultimodal?: boolean;
+	/** Force-enable tool calling even if model does not advertise support */
+	forceTools?: boolean;
+	/** Inference provider preference: "auto", "fastest", "cheapest", or a specific provider name */
+	provider?: string;
+	locals: App.Locals | undefined;
+	abortController: AbortController;
+	/** Autopilot mode — auto-continue tool calls up to 30 iterations */
+	autopilot?: boolean;
+}

package/src/ruvocal/src/lib/server/textGeneration/utils/prepareFiles.ts

@@ -0,0 +1,88 @@
+import type { MessageFile } from "$lib/types/Message";
+import type { EndpointMessage } from "$lib/server/endpoints/endpoints";
+import type { OpenAI } from "openai";
+import { TEXT_MIME_ALLOWLIST } from "$lib/constants/mime";
+import type { makeImageProcessor } from "$lib/server/endpoints/images";
+
+/**
+ * Prepare chat messages for OpenAI-compatible multimodal payloads.
+ * - Processes images via the provided imageProcessor (resize/convert) when multimodal is enabled.
+ * - Injects text-file content into the user message text.
+ * - Leaves messages untouched when no files or multimodal disabled.
+ */
+export async function prepareMessagesWithFiles(
+	messages: EndpointMessage[],
+	imageProcessor: ReturnType<typeof makeImageProcessor>,
+	isMultimodal: boolean
+): Promise<OpenAI.Chat.Completions.ChatCompletionMessageParam[]> {
+	return Promise.all(
+		messages.map(async (message) => {
+			if (message.from === "user" && message.files && message.files.length > 0) {
+				const { imageParts, textContent } = await prepareFiles(
+					imageProcessor,
+					message.files,
+					isMultimodal
+				);
+
+				let messageText = message.content;
+				if (textContent.length > 0) {
+					messageText = textContent + "\n\n" + message.content;
+				}
+
+				if (imageParts.length > 0 && isMultimodal) {
+					const parts = [{ type: "text" as const, text: messageText }, ...imageParts];
+					return { role: message.from, content: parts };
+				}
+
+				return { role: message.from, content: messageText };
+			}
+			return { role: message.from, content: message.content };
+		})
+	);
+}
+
+async function prepareFiles(
+	imageProcessor: ReturnType<typeof makeImageProcessor>,
+	files: MessageFile[],
+	isMultimodal: boolean
+): Promise<{
+	imageParts: OpenAI.Chat.Completions.ChatCompletionContentPartImage[];
+	textContent: string;
+}> {
+	const imageFiles = files.filter((file) => file.mime.startsWith("image/"));
+	const textFiles = files.filter((file) => {
+		const mime = (file.mime || "").toLowerCase();
+		const [fileType, fileSubtype] = mime.split("/");
+		return TEXT_MIME_ALLOWLIST.some((allowed) => {
+			const [type, subtype] = allowed.toLowerCase().split("/");
+			const typeOk = type === "*" || type === fileType;
+			const subOk = subtype === "*" || subtype === fileSubtype;
+			return typeOk && subOk;
+		});
+	});
+
+	let imageParts: OpenAI.Chat.Completions.ChatCompletionContentPartImage[] = [];
+	if (isMultimodal && imageFiles.length > 0) {
+		const processedFiles = await Promise.all(imageFiles.map(imageProcessor));
+		imageParts = processedFiles.map((file) => ({
+			type: "image_url" as const,
+			image_url: {
+				url: `data:${file.mime};base64,${file.image.toString("base64")}`,
+				detail: "auto",
+			},
+		}));
+	}
+
+	let textContent = "";
+	if (textFiles.length > 0) {
+		const textParts = await Promise.all(
+			textFiles.map(async (file) => {
+				const content = Buffer.from(file.value, "base64").toString("utf-8");
+				return `<document name="${file.name}" type="${file.mime}">\n${content}\n</document>`;
+			})
+		);
+		textContent = textParts.join("\n\n");
+	}
+
+	return { imageParts, textContent };
+}

package/src/ruvocal/src/lib/server/textGeneration/utils/routing.ts

@@ -0,0 +1,21 @@
+import type { EndpointMessage } from "../../endpoints/endpoints";
+
+const ROUTER_REASONING_REGEX = /<think>[\s\S]*?(?:<\/think>|$)/g;
+
+export function stripReasoningBlocks(text: string): string {
+	const stripped = text.replace(ROUTER_REASONING_REGEX, "");
+	return stripped === text ? text : stripped.trim();
+}
+
+export function stripReasoningFromMessageForRouting(message: EndpointMessage): EndpointMessage {
+	const clone = { ...message } as EndpointMessage & { reasoning?: string };
+	if ("reasoning" in clone) {
+		delete clone.reasoning;
+	}
+	const content =
+		typeof message.content === "string" ? stripReasoningBlocks(message.content) : message.content;
+	return {
+		...clone,
+		content,
+	};
+}

package/src/ruvocal/src/lib/server/textGeneration/utils/toolPrompt.ts

@@ -0,0 +1,49 @@
+import type { OpenAiTool } from "$lib/server/mcp/tools";
+
+export function buildToolPreprompt(tools: OpenAiTool[], autopilot?: boolean): string {
+	if (!Array.isArray(tools) || tools.length === 0) return "";
+	const names = tools
+		.map((t) => (t?.function?.name ? String(t.function.name) : ""))
+		.filter((s) => s.length > 0);
+	if (names.length === 0) return "";
+	const now = new Date();
+	const currentDate = now.toLocaleDateString("en-US", {
+		year: "numeric",
+		month: "long",
+		day: "numeric",
+	});
+	const isoDate = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+	const lines = [
+		`You have access to these tools: ${names.join(", ")}.`,
+		`Today's date: ${currentDate} (${isoDate}).`,
+	];
+
+	if (autopilot) {
+		lines.push(
+			`AUTOPILOT MODE ENABLED — PARALLEL SWARM EXECUTION. Follow these rules STRICTLY:`,
+			`1. NEVER ask for confirmation. Make reasonable assumptions. Proceed immediately.`,
+			`2. ALWAYS call MULTIPLE tools in parallel. If a task needs search + memory + routing, call ALL THREE at once in a single response — not sequentially.`,
+			`3. For complex tasks: spawn a SWARM of parallel tool calls. Example: call search, web_research, memory_search, and hooks_route ALL in one response.`,
+			`4. After getting results, immediately call the NEXT BATCH of tools in parallel. Keep chaining until done.`,
+			`5. If a tool fails, try alternatives immediately — do not report failure and stop.`,
+			`6. Only provide a final text response when ALL work is done and you have nothing left to execute.`,
+			`7. NEVER explain what you plan to do. Just DO IT by calling tools.`,
+			`8. Maximize parallel execution: if you can call 3+ tools at once, DO IT. Sequential is only for dependencies.`,
+		);
+	} else {
+		lines.push(
+			`IMPORTANT: Do NOT call a tool unless the user's request requires capabilities you lack (e.g., real-time data, image generation, code execution) or external information you do not have. For tasks like writing code, creative writing, math, or building apps, respond directly without tools. When in doubt, do not use a tool.`,
+		);
+	}
+
+	lines.push(
+		`PARALLEL TOOL CALLS: When multiple tool calls are needed and they are independent of each other (i.e., one does not need the result of another), call them all at once in a single response instead of one at a time. Only chain tool calls sequentially when a later call depends on an earlier call's output.`,
+		`SEARCH: Use 3-6 precise keywords. For historical events, include the year the event occurred. For recent or current topics, use today's year (${now.getFullYear()}). When a tool accepts date-range parameters (e.g., startPublishedDate, endPublishedDate), always use today's date (${isoDate}) as the end date unless the user specifies otherwise. For multi-part questions, search each part separately.`,
+		`ANSWER: State only facts explicitly in the results. If info is missing or results conflict, say so. Never fabricate URLs or facts.`,
+		`INTERACTIVE APPS: When asked to build an interactive application, game, or visualization without a specific language/framework preference, create a single self-contained HTML file with embedded CSS and JavaScript.`,
+		`If a tool generates an image, you can inline it directly: ![alt text](image_url).`,
+		`If a tool needs an image, set its image field ("input_image", "image", or "image_url") to a reference like "image_1", "image_2", etc. (ordered by when the user uploaded them).`,
+		`Default to image references; only use a full http(s) URL when the tool description explicitly asks for one, or reuse a URL a previous tool returned.`,
+	);
+	return lines.join(" ");
+}