backend-manager 5.6.3 → 5.7.0

package/src/cli/commands/test.js

@@ -237,6 +237,11 @@ class TestCommand extends BaseCommand {
       process.env.BACKEND_MANAGER_WEBHOOK_KEY = process.env.BACKEND_MANAGER_WEBHOOK_KEY || cfg.backend_manager?.webhookKey;
     } catch (_) { /* fixture config unreadable — let the normal key check report it */ }
 
+    // Anonymous HMAC unsubscribe tests sign links with this shared secret; the
+    // emulated functions inherit it from this process env (same mechanism as the
+    // webhook key above). Test-only value — production sets its own env var.
+    process.env.UNSUBSCRIBE_HMAC_KEY = process.env.UNSUBSCRIBE_HMAC_KEY || '_test-unsubscribe-hmac-key';
+
     this.ensureFixtureServiceAccount(fixture);
     this.linkFixtureDeps(fixture);
     this.log(chalk.cyan(`  Self-test: booting bundled fixture project (${fixture})`));
@@ -437,6 +442,14 @@ class TestCommand extends BaseCommand {
    *   - `test.log`     — the test-runner subprocess stdout/stderr (managed here)
    */
   async runEmulatorTests(testCommand, functionsDir) {
+    try {
+      await powertools.execute('java -version', { log: false });
+    } catch (e) {
+      this.logError(`Java is required to run tests (Firebase emulators depend on it).`);
+      this.logError(`Install with: brew install openjdk`);
+      process.exit(1);
+    }
+
     this.log(chalk.gray('  Starting Firebase emulator...\n'));
 
     const emulatorCmd = new EmulatorCommand(this.main);

package/src/cli/index.js

@@ -194,6 +194,20 @@ Main.prototype.test = async function(name, fn, fix, args) {
     return;
   }
 
+  // A check that returns 'warn' is a non-blocking failure — reported in the
+  // summary but does not halt setup. The warning details come from args.details
+  // (an array of pre-formatted lines) set by the caller.
+  if (passed === 'warn') {
+    self.testTotal++;
+    printLine(self.testTotal, 'warn', '');
+    const details = (args && typeof args.details === 'function') ? args.details() : (args && args.details) || [];
+    for (const line of details) {
+      ui.status('warn', chalk.yellow(line), { level: 3 });
+    }
+    if (self.setupSummary) { self.setupSummary.warn(name, details.map(d => chalk.yellow(d))); }
+    return;
+  }
+
   if (passed) {
     self.testCount++;
     self.testTotal++;

package/src/cli/utils/ui.js

@@ -164,6 +164,7 @@ class Summary {
   constructor() {
     this.startTime = null;
     this.passes = 0;
+    this.warns = [];
     this.fails = [];
   }
 
@@ -176,6 +177,14 @@ class Summary {
     this.passes++;
   }
 
+  /**
+   * @param {string} name - Check name.
+   * @param {string[]} [details] - Pre-formatted detail lines to show under the warning.
+   */
+  warn(name, details = []) {
+    this.warns.push({ name, details });
+  }
+
   /**
    * @param {string} name - Check name.
    * @param {string[]} [details] - Pre-formatted detail lines to show under the failure.
@@ -185,7 +194,7 @@ class Summary {
   }
 
   get total() {
-    return this.passes + this.fails.length;
+    return this.passes + this.warns.length + this.fails.length;
   }
 
   /**
@@ -214,6 +223,7 @@ class Summary {
    */
   print(opts = {}) {
     const hasErrors = this.fails.length > 0;
+    const hasWarnings = this.warns.length > 0;
     const headerColor = hasErrors ? chalk.yellow : chalk.green;
     const icon = hasErrors ? SYMBOLS.warn : SYMBOLS.done;
     const elapsed = this.startTime ? this._formatDuration(Date.now() - this.startTime) : '0s';
@@ -226,10 +236,22 @@ class Summary {
     blank();
     field('Checks', String(this.total), { pad: 11 });
     field('Duration', elapsed, { pad: 11 });
-    const failText = hasErrors
-      ? chalk.red(`${this.fails.length} failed`)
-      : chalk.dim('0 failed');
-    field('Results', `${chalk.green(`${this.passes} passed`)}${chalk.dim(', ')}${failText}`, { pad: 11 });
+    const parts = [chalk.green(`${this.passes} passed`)];
+    if (hasWarnings) {
+      parts.push(chalk.yellow(`${this.warns.length} warned`));
+    }
+    parts.push(hasErrors ? chalk.red(`${this.fails.length} failed`) : chalk.dim('0 failed'));
+    field('Results', parts.join(chalk.dim(', ')), { pad: 11 });
+
+    if (hasWarnings) {
+      blank();
+      for (const { name, details } of this.warns) {
+        console.log(`${indent(1)}${chalk.yellow(SYMBOLS.warn)} ${chalk.bold(name)}`);
+        for (const line of details) {
+          console.log(`${indent(3)}${line}`);
+        }
+      }
+    }
 
     if (hasErrors) {
       blank();

package/src/manager/index.js

@@ -254,9 +254,11 @@ Manager.prototype.init = function (exporter, options) {
     // to localhost. NOTE: getParentApiUrl/getParentUrl are intentionally NOT changed —
     // the parent is a real remote server with no localhost equivalent.
     const isDev = env === 'development' || (!env && (self.isDevelopment() || self.isTesting()));
-    return isDev
-      ? 'http://localhost:5002'
-      : `https://api.${(self.config.brand?.url || '').replace(/^https?:\/\//, '')}`;
+    if (isDev) {
+      const httpsPort = process.env.BEM_HTTPS_PORT;
+      return httpsPort ? `https://localhost:${httpsPort}` : 'http://localhost:5002';
+    }
+    return `https://api.${(self.config.brand?.url || '').replace(/^https?:\/\//, '')}`;
   };
 
   self.getWebsiteUrl = function(env) {
@@ -1352,6 +1354,9 @@ function resolveMcpRoutePath(routePath) {
   if (routePath === 'token') {
     return 'mcp/token';
   }
+  if (routePath === 'register') {
+    return 'mcp/register';
+  }
 
   return null;
 }

package/src/manager/libraries/ai/index.js

@@ -13,6 +13,7 @@
 const OpenAI = require('./providers/openai.js');
 const Anthropic = require('./providers/anthropic.js');
 const ClaudeCode = require('./providers/claude-code.js');
+const TestProvider = require('./providers/test.js');
 
 const DEFAULT_PROVIDER = 'openai';
 
@@ -153,6 +154,25 @@ AI.prototype._getProvider = function (provider, apiKey) {
  */
 function normalizeOptions(opts) {
   const out = { ...opts };
+  const rules = SYSTEM_PROMPT_INJECTIONS.join('\n');
+
+  // Structured conversations (tool-call turns, tool results, raw content
+  // blocks) must NOT be flattened into prompt/message — the provider consumes
+  // messages[] directly. Only the system turn gets the universal rules.
+  if (isStructuredMessages(opts.messages)) {
+    const systemIdx = opts.messages.findIndex((m) => m.role === 'system');
+
+    if (systemIdx >= 0 && typeof opts.messages[systemIdx].content === 'string') {
+      const existing = opts.messages[systemIdx].content;
+      out.messages = opts.messages.map((m, i) => i === systemIdx
+        ? { ...m, content: existing ? `${rules}\n\n${existing}` : rules }
+        : m);
+    } else if (systemIdx < 0) {
+      out.messages = [{ role: 'system', content: rules }, ...opts.messages];
+    }
+
+    return out;
+  }
 
   if (Array.isArray(opts.messages) && opts.messages.length) {
     const system = opts.messages.find((m) => m.role === 'system');
@@ -170,7 +190,6 @@ function normalizeOptions(opts) {
 
   // Prepend universal rules to the system prompt. Patches both representations
   // (prompt.content and messages[]) since providers read from one or the other.
-  const rules = SYSTEM_PROMPT_INJECTIONS.join('\n');
   const existing = stringifyContent(out.prompt?.content || '');
   const merged = existing ? `${rules}\n\n${existing}` : rules;
 
@@ -186,6 +205,21 @@ function normalizeOptions(opts) {
   return out;
 }
 
+// A messages[] array is "structured" when it carries turns that cannot survive
+// string-flattening: tool results, assistant tool-call turns, or raw
+// provider content blocks (tool_use / tool_result)
+function isStructuredMessages(messages) {
+  if (!Array.isArray(messages) || !messages.length) {
+    return false;
+  }
+
+  return messages.some((m) =>
+    m.role === 'tool'
+    || (Array.isArray(m.toolCalls) && m.toolCalls.length)
+    || (Array.isArray(m.content) && m.content.some((c) => c && typeof c === 'object' && (c.type === 'tool_use' || c.type === 'tool_result')))
+  );
+}
+
 function stringifyContent(content) {
   if (typeof content === 'string') {
     return content;
@@ -205,6 +239,7 @@ const PROVIDERS = {
   openai: OpenAI,
   anthropic: Anthropic,
   'claude-code': ClaudeCode,
+  test: TestProvider,
 };
 
 // Expose the underlying provider classes for advanced callers
@@ -212,5 +247,14 @@ AI.providers = PROVIDERS;
 AI.OpenAI = OpenAI;
 AI.Anthropic = Anthropic;
 AI.ClaudeCode = ClaudeCode;
+AI.TestProvider = TestProvider;
 
 module.exports = AI;
+
+// Exposed for unit tests. Not part of the public API — do not rely on these
+// from consumer code.
+AI._internals = {
+  normalizeOptions,
+  isStructuredMessages,
+  SYSTEM_PROMPT_INJECTIONS,
+};

package/src/manager/libraries/ai/providers/anthropic-format.js

@@ -0,0 +1,234 @@
+/**
+ * Shared pure formatting helpers for the two Claude providers (anthropic,
+ * claude-code). Both hit the same Claude Messages API — only auth differs — so
+ * the option-shape → request-body mapping lives here once.
+ *
+ * Handles the unified cross-provider message conventions:
+ *   - { role: 'system'|'developer'|'user'|'assistant', content: string }
+ *   - { role: 'assistant', content?, toolCalls: [{ id, name, arguments }] }
+ *     → assistant turn with tool_use blocks
+ *   - { role: 'tool', toolCallId, content } → tool_result block; consecutive
+ *     tool turns merge into ONE user turn (the Messages API requires all
+ *     results for an assistant turn in a single following user message)
+ *   - raw Anthropic block arrays (content: [{ type, ... }]) pass through untouched
+ *
+ * All functions are pure — no network, no SDK — so they're unit-testable
+ * without an assistant.
+ */
+
+/**
+ * Map normalized function-tool definitions to Anthropic tool definitions.
+ *
+ * Accepts entries shaped { name, description, parameters } (optionally with
+ * type: 'function'). Provider-specific hosted tools (any other `type`, e.g.
+ * OpenAI's { type: 'web_search' }) have no Anthropic equivalent — throw with a
+ * clear message instead of silently dropping them.
+ *
+ * @param {Array} list - options.tools.list
+ * @returns {Array<{name, description, input_schema}>}
+ */
+function buildToolDefs(list) {
+  if (!Array.isArray(list) || !list.length) {
+    return [];
+  }
+
+  return list.map((tool) => {
+    if (!tool || !tool.name || (tool.type && tool.type !== 'function')) {
+      throw new Error(`Anthropic tools must be function tools ({ name, description, parameters }) — got ${JSON.stringify(tool && (tool.type || tool.name) || tool)}`);
+    }
+
+    return {
+      name: tool.name,
+      description: tool.description || '',
+      input_schema: tool.parameters || { type: 'object', properties: {} },
+    };
+  });
+}
+
+/**
+ * Map the unified tools.choice value to Anthropic's tool_choice.
+ *
+ * 'auto' → { type: 'auto' }, 'required' → { type: 'any' },
+ * 'none' → { type: 'none' }, { name } → { type: 'tool', name }
+ */
+function buildToolChoice(choice) {
+  if (!choice) {
+    return undefined;
+  }
+
+  if (choice === 'auto') {
+    return { type: 'auto' };
+  }
+
+  if (choice === 'required') {
+    return { type: 'any' };
+  }
+
+  if (choice === 'none') {
+    return { type: 'none' };
+  }
+
+  if (typeof choice === 'object' && choice.name) {
+    return { type: 'tool', name: choice.name };
+  }
+
+  return undefined;
+}
+
+/**
+ * Build Anthropic { system, messages } from the unified option shape.
+ *
+ * Accepts either:
+ *   - options.messages: unified turns (see module header)
+ *   - options.prompt.content (system) + options.message.content (user)
+ */
+function buildMessages(options) {
+  if (!Array.isArray(options.messages) || !options.messages.length) {
+    return {
+      system: stringifyContent(options.prompt?.content || ''),
+      messages: [{ role: 'user', content: stringifyContent(options.message?.content || '') }],
+    };
+  }
+
+  // System: collect system + developer turns (Anthropic has no developer role —
+  // fold it into the system prompt, preserving order)
+  const system = options.messages
+    .filter((m) => m.role === 'system' || m.role === 'developer')
+    .map((m) => stringifyContent(m.content))
+    .filter(Boolean)
+    .join('\n\n');
+
+  const messages = [];
+
+  for (const m of options.messages) {
+    if (m.role === 'system' || m.role === 'developer') {
+      continue;
+    }
+
+    // Tool result turn → tool_result block; merge into the previous user turn
+    // if that turn is already a tool-result carrier (consecutive results)
+    if (m.role === 'tool') {
+      const block = {
+        type: 'tool_result',
+        tool_use_id: m.toolCallId,
+        content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content || ''),
+      };
+
+      const last = messages[messages.length - 1];
+
+      if (last && last.role === 'user' && Array.isArray(last.content) && last.content.every((c) => c.type === 'tool_result')) {
+        last.content.push(block);
+      } else {
+        messages.push({ role: 'user', content: [block] });
+      }
+
+      continue;
+    }
+
+    // Raw Anthropic block arrays pass through untouched (callers may replay
+    // raw.content from a prior response verbatim)
+    if (Array.isArray(m.content) && m.content.some((c) => c && typeof c === 'object' && c.type)) {
+      messages.push({ role: m.role, content: m.content });
+      continue;
+    }
+
+    // Assistant turn with tool calls → text block (if any) + tool_use blocks
+    if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length) {
+      const content = [];
+      const text = stringifyContent(m.content || '');
+
+      if (text) {
+        content.push({ type: 'text', text });
+      }
+
+      for (const call of m.toolCalls) {
+        content.push({
+          type: 'tool_use',
+          id: call.id,
+          name: call.name,
+          input: parseArguments(call.arguments),
+        });
+      }
+
+      messages.push({ role: 'assistant', content });
+      continue;
+    }
+
+    // Plain text turn
+    messages.push({ role: m.role, content: stringifyContent(m.content) });
+  }
+
+  return { system, messages };
+}
+
+/**
+ * Extract normalized tool calls from a response's content blocks.
+ *
+ * @param {Array} content - raw.content from the Messages API
+ * @returns {Array<{id, name, arguments}>} arguments is the parsed input object
+ */
+function extractToolCalls(content) {
+  return (content || [])
+    .filter((c) => c.type === 'tool_use')
+    .map((c) => ({ id: c.id, name: c.name, arguments: c.input || {} }));
+}
+
+/**
+ * Map Anthropic stop_reason to the normalized stopReason.
+ */
+function mapStopReason(stopReason) {
+  if (stopReason === 'tool_use') {
+    return 'tool_use';
+  }
+
+  if (stopReason === 'max_tokens') {
+    return 'max_tokens';
+  }
+
+  return 'end';
+}
+
+function parseArguments(args) {
+  if (args && typeof args === 'object') {
+    return args;
+  }
+
+  if (typeof args === 'string' && args.trim()) {
+    try {
+      return JSON.parse(args);
+    } catch (e) {
+      return {};
+    }
+  }
+
+  return {};
+}
+
+function stringifyContent(content) {
+  if (!content) {
+    return '';
+  }
+
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  // OpenAI sometimes uses [{ type: 'input_text', text: '...' }] — flatten to string
+  if (Array.isArray(content)) {
+    return content
+      .filter((c) => c.type === 'input_text' || c.type === 'text')
+      .map((c) => c.text || '')
+      .join('\n');
+  }
+
+  return String(content);
+}
+
+module.exports = {
+  buildToolDefs,
+  buildToolChoice,
+  buildMessages,
+  extractToolCalls,
+  mapStopReason,
+  stringifyContent,
+};

package/src/manager/libraries/ai/providers/anthropic.js

@@ -9,6 +9,7 @@
  */
 const _ = require('lodash');
 const JSON5 = require('json5');
+const format = require('./anthropic-format.js');
 
 const DEFAULT_MODEL = 'claude-sonnet-4-6';
 
@@ -58,8 +59,9 @@ Anthropic.prototype.request = async function (options) {
   const SDK = require('@anthropic-ai/sdk');
   const client = new SDK({ apiKey: self.key });
 
-  // Build messages from the OpenAI-style option shape (prompt + message) or pass-through messages
-  const { system, messages } = buildMessages(options);
+  // Build messages from the OpenAI-style option shape (prompt + message) or
+  // unified messages turns (incl. assistant toolCalls + role:'tool' results)
+  const { system, messages } = format.buildMessages(options);
 
   // JSON output via system prompt instruction (Anthropic's structured output is via prompt, not a flag)
   let systemFinal = system;
@@ -82,6 +84,20 @@ Anthropic.prototype.request = async function (options) {
     requestBody.temperature = options.temperature;
   }
 
+  // Native tool calling — normalized function tools only ({ name, description,
+  // parameters }); provider-specific hosted tools throw in buildToolDefs
+  const toolDefs = format.buildToolDefs(options.tools?.list);
+
+  if (toolDefs.length) {
+    requestBody.tools = toolDefs;
+
+    const toolChoice = format.buildToolChoice(options.tools?.choice);
+
+    if (toolChoice) {
+      requestBody.tool_choice = toolChoice;
+    }
+  }
+
   let raw;
 
   try {
@@ -91,13 +107,17 @@ Anthropic.prototype.request = async function (options) {
     throw e;
   }
 
-  // Extract text from content blocks (concatenate text blocks; ignore tool_use/etc for now)
+  // Extract text from content blocks (concatenate text blocks) and tool calls
+  // from tool_use blocks — a tool-call turn legitimately has content: ''
   const outputText = (raw.content || [])
     .filter((c) => c.type === 'text')
     .map((c) => c.text.trim())
     .join('\n')
     .trim();
 
+  const toolCalls = format.extractToolCalls(raw.content);
+  const stopReason = format.mapStopReason(raw.stop_reason);
+
   // Update token counters
   const modelConfig = MODEL_TABLE[options.model] || MODEL_TABLE[DEFAULT_MODEL];
 
@@ -108,10 +128,11 @@ Anthropic.prototype.request = async function (options) {
   self.tokens.output.price  = (self.tokens.output.count * modelConfig.output) / 1_000_000;
   self.tokens.total.price   = self.tokens.input.price + self.tokens.output.price;
 
-  // Parse JSON if requested
+  // Parse JSON if requested — but never on a tool-call turn, where empty/partial
+  // text is the normal intermediate state (the caller continues the loop)
   let parsed = outputText;
 
-  if (options.response === 'json') {
+  if (options.response === 'json' && !toolCalls.length) {
     parsed = parseJsonLoose(outputText);
   }
 
@@ -120,53 +141,11 @@ Anthropic.prototype.request = async function (options) {
     content: parsed,
     tokens: self.tokens,
     raw,
+    toolCalls,
+    stopReason,
   };
 };
 
-/**
- * Build Anthropic system + messages from the unified option shape.
- *
- * Accepts either:
- *   - options.messages: [{ role: 'system'|'user'|'assistant', content: string }]
- *   - options.prompt.content (system) + options.message.content (user)
- */
-function buildMessages(options) {
-  // If caller passed `messages` directly (OpenAI-style), translate it
-  if (Array.isArray(options.messages) && options.messages.length) {
-    const system = options.messages.find((m) => m.role === 'system')?.content;
-    const messages = options.messages
-      .filter((m) => m.role !== 'system')
-      .map((m) => ({ role: m.role, content: stringifyContent(m.content) }));
-
-    return { system, messages };
-  }
-
-  // Otherwise build from prompt/message
-  const system = options.prompt?.content || '';
-  const userContent = stringifyContent(options.message?.content || '');
-
-  return {
-    system,
-    messages: [{ role: 'user', content: userContent }],
-  };
-}
-
-function stringifyContent(content) {
-  if (typeof content === 'string') {
-    return content;
-  }
-
-  // OpenAI sometimes uses [{ type: 'input_text', text: '...' }] — flatten to string
-  if (Array.isArray(content)) {
-    return content
-      .filter((c) => c.type === 'input_text' || c.type === 'text')
-      .map((c) => c.text || '')
-      .join('\n');
-  }
-
-  return String(content || '');
-}
-
 /**
  * Parse JSON from Claude output. Claude usually obeys the "JSON only" instruction
  * but occasionally wraps responses in ```json fences or adds a sentence before.

package/src/manager/libraries/ai/providers/claude-code.js

@@ -24,6 +24,7 @@
  */
 const _ = require('lodash');
 const JSON5 = require('json5');
+const format = require('./anthropic-format.js');
 
 const DEFAULT_MODEL = 'claude-opus-4-7';
 const OAUTH_BETA = 'oauth-2025-04-20';
@@ -80,7 +81,7 @@ ClaudeCode.prototype.request = async function (options) {
     defaultHeaders: { 'anthropic-beta': OAUTH_BETA },
   });
 
-  const { system, messages } = buildMessages(options);
+  const { system, messages } = format.buildMessages(options);
 
   let systemFinal = system;
 
@@ -102,6 +103,19 @@ ClaudeCode.prototype.request = async function (options) {
     requestBody.temperature = options.temperature;
   }
 
+  // Native tool calling — same normalized interface as the anthropic provider
+  const toolDefs = format.buildToolDefs(options.tools?.list);
+
+  if (toolDefs.length) {
+    requestBody.tools = toolDefs;
+
+    const toolChoice = format.buildToolChoice(options.tools?.choice);
+
+    if (toolChoice) {
+      requestBody.tool_choice = toolChoice;
+    }
+  }
+
   let raw;
 
   try {
@@ -117,6 +131,9 @@ ClaudeCode.prototype.request = async function (options) {
     .join('\n')
     .trim();
 
+  const toolCalls = format.extractToolCalls(raw.content);
+  const stopReason = format.mapStopReason(raw.stop_reason);
+
   const modelConfig = MODEL_TABLE[options.model] || MODEL_TABLE[DEFAULT_MODEL];
 
   self.tokens.input.count  += raw.usage?.input_tokens || 0;
@@ -128,7 +145,7 @@ ClaudeCode.prototype.request = async function (options) {
 
   let parsed = outputText;
 
-  if (options.response === 'json') {
+  if (options.response === 'json' && !toolCalls.length) {
     parsed = parseJsonLoose(outputText);
   }
 
@@ -137,54 +154,11 @@ ClaudeCode.prototype.request = async function (options) {
     content: parsed,
     tokens: self.tokens,
     raw,
+    toolCalls,
+    stopReason,
   };
 };
 
-/**
- * Build Anthropic system + messages from the unified option shape.
- *
- * Accepts either:
- *   - options.messages: [{ role: 'system'|'user'|'assistant', content: string }]
- *   - options.prompt.content (system) + options.message.content (user)
- */
-function buildMessages(options) {
-  if (Array.isArray(options.messages) && options.messages.length) {
-    const system = options.messages.find((m) => m.role === 'system')?.content;
-    const messages = options.messages
-      .filter((m) => m.role !== 'system')
-      .map((m) => ({ role: m.role, content: stringifyContent(m.content) }));
-
-    return { system: stringifyContent(system), messages };
-  }
-
-  const system = stringifyContent(options.prompt?.content || '');
-  const userContent = stringifyContent(options.message?.content || '');
-
-  return {
-    system,
-    messages: [{ role: 'user', content: userContent }],
-  };
-}
-
-function stringifyContent(content) {
-  if (!content) {
-    return '';
-  }
-
-  if (typeof content === 'string') {
-    return content;
-  }
-
-  if (Array.isArray(content)) {
-    return content
-      .filter((c) => c.type === 'input_text' || c.type === 'text')
-      .map((c) => c.text || '')
-      .join('\n');
-  }
-
-  return String(content);
-}
-
 function parseJsonLoose(text) {
   let cleaned = (text || '').trim();