Open-source AI browser agent for Chrome and Firefox (monorepo) ðŸ§
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
// Compatibility shims for local OpenAI-compatible servers whose chat templates
// accept only a subset of OpenAI message roles.
export function getChatTemplateCompat({ model, value } = {}) {
const explicit = normalizeCompatValue(value ?? process.env.LLM_CHAT_TEMPLATE_COMPAT);
if (explicit) return explicit;
// LM Studio's Molmo templates commonly reject `system` and `tool` roles with
// "Conversation roles must alternate user/assistant/user/assistant/...".
if (/molmo/i.test(model || '')) {
return { mode: 'alternating', source: 'auto:molmo', omitStructuredTools: false };
}
return { mode: 'off', source: 'default' };
}
export function chatTemplateCompatLabel(compat) {
if (!compat || compat.mode === 'off') return 'off';
const details = [
compat.source,
compat.omitStructuredTools ? 'text tool calls' : 'structured tools',
].filter(Boolean).join(', ');
return `${compat.mode}${details ? ` (${details})` : ''}`;
}
export function prepareMessagesForChatTemplate(messages, compat, { tools = [] } = {}) {
if (!compat || compat.mode === 'off') return messages;
if (compat.mode === 'fold-system') return foldSystemMessages(messages);
if (compat.mode === 'alternating') {
return withTextToolCallInstruction(toAlternatingMessages(messages), compat, tools);
}
return messages;
}
export function prepareToolsForChatTemplate(tools, compat) {
return compat?.omitStructuredTools ? undefined : tools;
}
function normalizeCompatValue(value) {
if (value == null || value === '') return null;
const key = String(value).trim().toLowerCase();
if (['0', 'false', 'off', 'none', 'no'].includes(key)) {
return { mode: 'off', source: 'explicit' };
}
if (['1', 'true', 'fold', 'fold-system', 'system'].includes(key)) {
return { mode: 'fold-system', source: 'explicit' };
}
if (['alternating', 'strict-alternating', 'molmo'].includes(key)) {
return { mode: 'alternating', source: 'explicit', omitStructuredTools: true };
}
if (['alternating-tools', 'alternating-structured', 'molmo-tools', 'molmo-structured'].includes(key)) {
return { mode: 'alternating', source: 'explicit', omitStructuredTools: false };
}
throw new Error(
`Bad LLM_CHAT_TEMPLATE_COMPAT value: ${value}. Expected off, fold-system, alternating, or alternating-tools.`,
);
}
function foldSystemMessages(messages) {
const out = [];
let pendingSystem = [];
for (const msg of messages) {
if (isInstructionRole(msg.role)) {
pendingSystem.push(contentToText(msg.content));
continue;
}
if (pendingSystem.length && msg.role === 'user') {
out.push({ ...msg, content: withInstructions(pendingSystem, contentToText(msg.content)) });
pendingSystem = [];
continue;
}
if (pendingSystem.length) {
out.push({ role: 'user', content: formatInstructions(pendingSystem) });
pendingSystem = [];
}
out.push(msg);
}
if (pendingSystem.length) {
const last = out[out.length - 1];
if (last?.role === 'user') {
last.content = `${contentToText(last.content)}\n\n${formatInstructions(pendingSystem)}`;
} else {
out.push({ role: 'user', content: formatInstructions(pendingSystem) });
}
}
return out;
}
function toAlternatingMessages(messages) {
const out = [];
let pendingSystem = [];
for (const msg of messages) {
if (isInstructionRole(msg.role)) {
pendingSystem.push(contentToText(msg.content));
continue;
}
if (msg.role === 'user') {
pushAlternating(out, 'user', withInstructions(pendingSystem, contentToText(msg.content)));
pendingSystem = [];
continue;
}
if (msg.role === 'assistant') {
flushPendingSystem(out, pendingSystem);
pendingSystem = [];
pushAlternating(out, 'assistant', assistantMessageToText(msg));
continue;
}
if (msg.role === 'tool') {
pushAlternating(out, 'user', withInstructions(pendingSystem, toolMessageToText(msg)));
pendingSystem = [];
continue;
}
pushAlternating(
out,
'user',
withInstructions(pendingSystem, `${msg.role || 'message'}:\n${contentToText(msg.content)}`),
);
pendingSystem = [];
}
flushPendingSystem(out, pendingSystem);
if (out[0]?.role === 'assistant') {
out.unshift({ role: 'user', content: 'Continue the prior task.' });
}
return out;
}
function flushPendingSystem(out, pendingSystem) {
if (pendingSystem.length) {
pushAlternating(out, 'user', formatInstructions(pendingSystem));
}
}
function pushAlternating(out, role, content) {
const text = contentToText(content).trim();
if (!text) return;
const last = out[out.length - 1];
if (last?.role === role) {
last.content = `${contentToText(last.content)}\n\n${text}`;
} else {
out.push({ role, content: text });
}
}
function withTextToolCallInstruction(messages, compat, tools) {
if (!compat?.omitStructuredTools || !Array.isArray(tools) || !tools.length) return messages;
const names = tools.map((tool) => tool?.function?.name).filter(Boolean);
if (!names.length) return messages;
const instruction =
'Tool-call compatibility mode: this server is not receiving OpenAI structured tool schemas. ' +
'When the next action should be a tool call, reply with exactly one raw tool call and no prose, ' +
'using this format: <tool_call>{"name":"tool_name","arguments":{...}}</tool_call>. ' +
`Available tool names: ${names.join(', ')}.`;
const out = messages.map((m) => ({ ...m }));
for (let i = out.length - 1; i >= 0; i--) {
if (out[i].role === 'user') {
out[i].content = `${contentToText(out[i].content)}\n\n${instruction}`;
return out;
}
}
out.push({ role: 'user', content: instruction });
return out;
}
function assistantMessageToText(msg) {
const parts = [];
const content = contentToText(msg.content).trim();
if (content) parts.push(content);
if (Array.isArray(msg.tool_calls) && msg.tool_calls.length) {
const calls = msg.tool_calls.map((tc) => {
const name = tc?.function?.name || tc?.name || 'tool';
const args = tc?.function?.arguments ?? tc?.arguments ?? tc?.args ?? {};
return `- ${name}(${stringifyArgs(args)})`;
});
parts.push(`Assistant tool call(s):\n${calls.join('\n')}`);
}
return parts.join('\n\n');
}
function toolMessageToText(msg) {
const name = msg.name || 'tool';
const id = msg.tool_call_id ? ` ${msg.tool_call_id}` : '';
return `Tool result from ${name}${id}:\n${contentToText(msg.content)}`;
}
function withInstructions(instructions, body) {
if (!instructions.length) return body;
return `${formatInstructions(instructions)}\n\n${body || ''}`.trim();
}
function formatInstructions(instructions) {
return `System/developer instructions:\n${instructions.map((s) => s.trim()).filter(Boolean).join('\n\n')}`;
}
function isInstructionRole(role) {
return role === 'system' || role === 'developer';
}
function contentToText(content) {
if (content == null) return '';
if (typeof content === 'string') return content;
if (Array.isArray(content)) {
return content.map((part) => {
if (typeof part === 'string') return part;
if (part?.type === 'text') return part.text || '';
if (part?.type === 'image_url') return '[image_url omitted]';
return JSON.stringify(part);
}).filter(Boolean).join('\n');
}
return JSON.stringify(content);
}
function stringifyArgs(args) {
if (typeof args === 'string') return args;
try {
return JSON.stringify(args ?? {});
} catch {
return '{}';
}
}