backend-manager 5.2.8 → 5.2.9

package/CHANGELOG.md

@@ -14,6 +14,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.2.9] - 2026-05-25
+
+### Added
+
+- **OpenAI provider: multi-role prompt array support.** `options.prompt` now accepts either the legacy object form (`{ path|content, settings }`, auto-wrapped as a single `system`-role segment per the OpenAI Model Spec) OR an array form (`[{ role, path|content, settings }, ...]`) where each segment becomes its own message with its declared role. Valid roles: `system`, `developer`, `user`, `assistant`; order is preserved; role defaults to `system` if omitted; invalid roles throw. New internal helpers `normalizePrompt()` + `VALID_PROMPT_ROLES` canonicalize input; the request pipeline threads `promptSegments` end-to-end (per-segment load, per-role logging, per-segment error surfacing, `formatHistory` unshifts segments in declared order). `module.exports._internals` exposes `normalizePrompt`, `formatHistory`, `VALID_PROMPT_ROLES` for unit tests — not part of the public API. Backwards compatible: existing callers passing `prompt: { content: '...' }` are auto-wrapped as a single `system` segment with no consumer changes.
+- **`test/helpers/ai-request-payload.js`** — 16 standalone tests covering the BEM → OpenAI payload transformation with no network and no assistant. Exercises `normalizePrompt` (undefined/null/empty handling, legacy object → single system segment, array-form role preservation, role-defaulting, invalid-role throw, full OpenAI Model Spec role coverage) and `formatHistory` (single-system emit, multi-segment order, empty-array → user-only, prompt+history+new-user interleaving, assistant `output_text` typing, history limit, `dedupeConsecutiveRoles` trailing-user drop, content trim/strip).
+
+### Changed
+
+- **Default OpenAI model bumped to `gpt-5.4-mini`** (was `gpt-5-mini`). Updated in `src/manager/libraries/ai/providers/openai.js` (`DEFAULT_MODEL`), `src/manager/libraries/ai/index.js` (usage example in JSDoc), and `src/manager/libraries/infer-contact.js` (`inferContactWithAI`). The pricing table in the OpenAI provider already includes `gpt-5.4-mini`, so no further config changes are required.
+- **`inferContactWithAI` maxTokens doubled to 2048** (was 1024). Gives the model headroom for the richer multi-field contact response without truncation.
+
 # [5.2.8] - 2026-05-25
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.2.8",
+  "version": "5.2.9",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

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

@@ -3,7 +3,7 @@
  *
  * Usage:
  *   const ai = Manager.AI(assistant);
- *   const result = await ai.request({ provider: 'openai', model: 'gpt-5-mini', ... });
+ *   const result = await ai.request({ provider: 'openai', model: 'gpt-5.4-mini', ... });
  *   const result = await ai.request({ provider: 'anthropic', model: 'claude-sonnet-4-6', ... });
  *
  * Each provider returns { content, output, tokens, raw } with a consistent shape.

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

@@ -7,7 +7,7 @@ const path = require('path');
 const mimeTypes = require('mime-types');
 
 // Constants
-const DEFAULT_MODEL = 'gpt-5-mini';
+const DEFAULT_MODEL = 'gpt-5.4-mini';
 const MODERATION_MODEL = 'omni-moderation-latest';
 
 // OpenAI model pricing table (per 1M tokens)
@@ -396,10 +396,25 @@ OpenAI.prototype.request = function (options) {
     options.reasoning = options.reasoning || undefined;
 
     // Format prompt
-    options.prompt = options.prompt || {};
-    options.prompt.path = options.prompt.path || '';
-    options.prompt.content = options.prompt.content || options.prompt.content || '';
-    options.prompt.settings = options.prompt.settings || {};
+    //
+    // Accepts two forms:
+    //
+    //   1) Object form (legacy / single-role):
+    //        prompt: { path|content, settings }
+    //      Auto-wrapped to a single 'system'-role segment per the OpenAI Model
+    //      Spec — unlabeled prompts represent the platform's authoritative
+    //      instruction.
+    //
+    //   2) Array form (multi-role):
+    //        prompt: [
+    //          { role: 'system',    path|content, settings },
+    //          { role: 'developer', path|content, settings },
+    //          ...
+    //        ]
+    //      Each segment becomes its own message with the declared role. Order
+    //      is preserved. Valid roles: 'system', 'developer', 'user',
+    //      'assistant'. Segments default to 'system' if role is omitted.
+    options.prompt = normalizePrompt(options.prompt);
 
     // Format message
     options.message = options.message || {};
@@ -428,19 +443,26 @@ OpenAI.prototype.request = function (options) {
     _log('Starting', options);
 
 
-    // Load prompt
-    const prompt = loadContent(options.prompt, _log);
+    // Load prompt segments (one entry per role) and the user message
+    const promptSegments = options.prompt.map((segment) => ({
+      role: segment.role,
+      content: loadContent(segment, _log),
+    }));
     const message = loadContent(options.message, _log);
     const user = options.user?.auth?.uid || assistant.request.geolocation.ip || 'unknown';
 
     // Log
-    _log('Prompt', prompt);
+    for (const segment of promptSegments) {
+      _log(`Prompt[${segment.role}]`, segment.content);
+    }
     _log('Message', message);
     _log('User', user);
 
     // Check for errors
-    if (prompt instanceof Error) {
-      return reject(assistant.errorify(`Error loading prompt: ${prompt}`, {code: 400}));
+    for (const segment of promptSegments) {
+      if (segment.content instanceof Error) {
+        return reject(assistant.errorify(`Error loading prompt[${segment.role}]: ${segment.content}`, {code: 400}));
+      }
     }
 
     if (message instanceof Error) {
@@ -450,7 +472,7 @@ OpenAI.prototype.request = function (options) {
     // Moderate if needed
     let moderation = null;
     if (options.moderate) {
-      moderation = await makeRequest('moderations', options, self, prompt, message, user, _log)
+      moderation = await makeRequest('moderations', options, self, promptSegments, message, user, _log)
       .then(async (r) => {
         // {
         //   id: 'modr-8205',
@@ -481,7 +503,7 @@ OpenAI.prototype.request = function (options) {
 
 
     // Make attempt
-    attemptRequest(options, self, prompt, message, user, moderation, attempt, assistant, resolve, reject, _log);
+    attemptRequest(options, self, promptSegments, message, user, moderation, attempt, assistant, resolve, reject, _log);
   });
 }
 
@@ -493,6 +515,39 @@ function tryParse(content) {
   }
 }
 
+// Roles permitted in the `options.prompt` array. Order is canonical per the
+// OpenAI Model Spec authority hierarchy (system > developer > user > assistant).
+const VALID_PROMPT_ROLES = new Set(['system', 'developer', 'user', 'assistant']);
+
+// Normalize the `options.prompt` input into a canonical array of segments:
+//   [{ role, path, content, settings }, ...]
+//
+// Accepts:
+//   - undefined/null/empty → []
+//   - object: { path|content, settings } → wrapped as a single 'system' segment
+//   - array: [{ role, path|content, settings }, ...] → role defaults to 'system'
+//     if omitted; invalid roles throw.
+function normalizePrompt(input) {
+  const segments = Array.isArray(input)
+    ? input
+    : (input && (input.path || input.content || input.settings)) ? [input] : [];
+
+  return segments.map((segment) => {
+    const role = segment.role || 'system';
+
+    if (!VALID_PROMPT_ROLES.has(role)) {
+      throw new Error(`Invalid prompt role: ${role}. Valid roles: ${[...VALID_PROMPT_ROLES].join(', ')}`);
+    }
+
+    return {
+      role: role,
+      path: segment.path || '',
+      content: segment.content || '',
+      settings: segment.settings || {},
+    };
+  });
+}
+
 function loadContent(input, _log) {
   // console.log('*** input!!!', input.content.slice(0, 50), input.path);
   // console.log('*** input.content', input.content.slice(0, 50));
@@ -674,16 +729,20 @@ function formatMessageContent(content, attachments, _log, mode = 'responses', ro
 }
 
 
-function formatHistory(options, prompt, message, _log) {
+function formatHistory(options, promptSegments, message, _log) {
   // Get history with respect to the message limit
   const history = options.history.messages.slice(-options.history.limit);
 
-  // Add prompt to beginning of history
-  history.unshift({
-    role: 'developer',
-    content: prompt,
-    attachments: [],
-  });
+  // Add prompt segments to the beginning of history, in the order provided
+  // (each segment becomes its own message with the declared role)
+  for (let i = promptSegments.length - 1; i >= 0; i--) {
+    const segment = promptSegments[i];
+    history.unshift({
+      role: segment.role,
+      content: segment.content,
+      attachments: [],
+    });
+  }
 
   // Get last history item
   const lastHistory = history[history.length - 1];
@@ -722,7 +781,7 @@ function formatHistory(options, prompt, message, _log) {
   return formatted;
 }
 
-function attemptRequest(options, self, prompt, message, user, moderation, attempt, assistant, resolve, reject, _log) {
+function attemptRequest(options, self, promptSegments, message, user, moderation, attempt, assistant, resolve, reject, _log) {
   const retries = options.retries;
   const triggers = options.retryTriggers;
 
@@ -733,7 +792,7 @@ function attemptRequest(options, self, prompt, message, user, moderation, attemp
   _log(`Request ${attempt.count}/${retries}`);
 
   // Request
-  makeRequest('responses', options, self, prompt, message, user, _log)
+  makeRequest('responses', options, self, promptSegments, message, user, _log)
   .then((r) => {
     // Example
     // {
@@ -834,7 +893,7 @@ function attemptRequest(options, self, prompt, message, user, moderation, attemp
 
       // Retry
       if (attempt.count < retries && triggers.includes('parse')) {
-        return attemptRequest(options, self, prompt, message, user, moderation, attempt, assistant, resolve, reject, _log);
+        return attemptRequest(options, self, promptSegments, message, user, moderation, attempt, assistant, resolve, reject, _log);
       }
 
       // Return
@@ -856,7 +915,7 @@ function attemptRequest(options, self, prompt, message, user, moderation, attemp
 
     // Retry
     if (attempt.count < retries && triggers.includes('network')) {
-      return attemptRequest(options, self, prompt, message, user, moderation, attempt, assistant, resolve, reject, _log);
+      return attemptRequest(options, self, promptSegments, message, user, moderation, attempt, assistant, resolve, reject, _log);
     }
 
     // Return
@@ -864,7 +923,7 @@ function attemptRequest(options, self, prompt, message, user, moderation, attemp
   });
 }
 
-function makeRequest(mode, options, self, prompt, message, user, _log) {
+function makeRequest(mode, options, self, promptSegments, message, user, _log) {
   return new Promise(async function(resolve, reject) {
     const request = {
       url: '',
@@ -895,7 +954,7 @@ function makeRequest(mode, options, self, prompt, message, user, _log) {
       }
     } else if (mode === 'responses') {
       // Format history for responses API
-      const history = formatHistory(options, prompt, message, _log);
+      const history = formatHistory(options, promptSegments, message, _log);
 
       // Set request
       request.url = 'https://api.openai.com/v1/responses';
@@ -1007,3 +1066,11 @@ function resolveReasoning(options) {
 }
 
 module.exports = OpenAI;
+
+// Exposed for unit tests. Not part of the public API — do not rely on these
+// from consumer code.
+module.exports._internals = {
+  normalizePrompt,
+  formatHistory,
+  VALID_PROMPT_ROLES,
+};

package/src/manager/libraries/infer-contact.js

@@ -45,9 +45,9 @@ async function inferContactWithAI(email, assistant) {
   try {
     const ai = assistant.Manager.AI(assistant, process.env.BACKEND_MANAGER_OPENAI_API_KEY);
     const result = await ai.request({
-      model: 'gpt-5-mini',
+      model: 'gpt-5.4-mini',
       timeout: 60000,
-      maxTokens: 1024,
+      maxTokens: 1024 * 2,
       moderate: false,
       response: 'json',
       prompt: {

package/test/helpers/ai-request-payload.js

@@ -0,0 +1,300 @@
+/**
+ * Test: AI request payload shape (libraries/ai/providers/openai.js)
+ *
+ * Verifies the transformation from the BEM-facing `ai.request()` options
+ * (specifically `options.prompt` in either legacy object form or array form)
+ * into the eventual OpenAI HTTP payload (the `input: [...]` array).
+ *
+ * These tests exercise the pure helpers `normalizePrompt` and `formatHistory`
+ * directly — no network, no assistant required.
+ */
+const OpenAI = require('../../src/manager/libraries/ai/providers/openai.js');
+const { normalizePrompt, formatHistory, VALID_PROMPT_ROLES } = OpenAI._internals;
+
+function noopLog() {}
+
+function baseOptions(overrides = {}) {
+  return {
+    dedupeConsecutiveRoles: true,
+    history: { messages: [], limit: 5 },
+    message: { attachments: [] },
+    ...overrides,
+  };
+}
+
+module.exports = {
+  description: 'AI request payload shape (system/developer/user roles)',
+  type: 'group',
+  tests: [
+    // ─── normalizePrompt ───
+
+    {
+      name: 'normalize-undefined-returns-empty-array',
+      async run({ assert }) {
+        assert.deepEqual(normalizePrompt(undefined), [], 'undefined → []');
+      },
+    },
+
+    {
+      name: 'normalize-null-returns-empty-array',
+      async run({ assert }) {
+        assert.deepEqual(normalizePrompt(null), [], 'null → []');
+      },
+    },
+
+    {
+      name: 'normalize-empty-object-returns-empty-array',
+      async run({ assert }) {
+        assert.deepEqual(normalizePrompt({}), [], 'empty object → []');
+      },
+    },
+
+    {
+      name: 'normalize-legacy-object-form-wraps-as-system-segment',
+      async run({ assert }) {
+        const result = normalizePrompt({ path: '/tmp/example.md', settings: { foo: 'bar' } });
+
+        assert.equal(result.length, 1, 'one segment');
+        assert.equal(result[0].role, 'system', 'legacy object defaults to system role');
+        assert.equal(result[0].path, '/tmp/example.md', 'path preserved');
+        assert.deepEqual(result[0].settings, { foo: 'bar' }, 'settings preserved');
+      },
+    },
+
+    {
+      name: 'normalize-legacy-object-with-content-only',
+      async run({ assert }) {
+        const result = normalizePrompt({ content: 'inline prompt text' });
+
+        assert.equal(result.length, 1, 'one segment');
+        assert.equal(result[0].role, 'system', 'defaults to system');
+        assert.equal(result[0].content, 'inline prompt text', 'content preserved');
+        assert.equal(result[0].path, '', 'no path');
+      },
+    },
+
+    {
+      name: 'normalize-array-form-preserves-roles-and-order',
+      async run({ assert }) {
+        const result = normalizePrompt([
+          { role: 'system',    content: 'platform rules' },
+          { role: 'developer', content: 'operator config' },
+        ]);
+
+        assert.equal(result.length, 2, 'two segments');
+        assert.equal(result[0].role, 'system', 'first is system');
+        assert.equal(result[0].content, 'platform rules', 'first content');
+        assert.equal(result[1].role, 'developer', 'second is developer');
+        assert.equal(result[1].content, 'operator config', 'second content');
+      },
+    },
+
+    {
+      name: 'normalize-array-segment-without-role-defaults-to-system',
+      async run({ assert }) {
+        const result = normalizePrompt([
+          { content: 'rule 1' },
+          { role: 'developer', content: 'rule 2' },
+        ]);
+
+        assert.equal(result[0].role, 'system', 'missing role → system');
+        assert.equal(result[1].role, 'developer', 'explicit role preserved');
+      },
+    },
+
+    {
+      name: 'normalize-array-with-invalid-role-throws',
+      async run({ assert }) {
+        let threw = false;
+        try {
+          normalizePrompt([{ role: 'admin', content: 'bad' }]);
+        } catch (e) {
+          threw = true;
+          assert.equal(
+            String(e.message).includes('Invalid prompt role'),
+            true,
+            'error mentions Invalid prompt role',
+          );
+        }
+        assert.equal(threw, true, 'should throw on invalid role');
+      },
+    },
+
+    {
+      name: 'normalize-valid-roles-set-matches-openai-model-spec',
+      async run({ assert }) {
+        const expected = ['system', 'developer', 'user', 'assistant'];
+        const actual = [...VALID_PROMPT_ROLES].sort();
+
+        assert.deepEqual(actual, expected.sort(), 'valid roles per OpenAI Model Spec');
+      },
+    },
+
+    {
+      name: 'normalize-all-valid-roles-accepted',
+      async run({ assert }) {
+        const segments = ['system', 'developer', 'user', 'assistant'].map((role) => ({
+          role,
+          content: `content for ${role}`,
+        }));
+
+        const result = normalizePrompt(segments);
+
+        assert.equal(result.length, 4, 'all four segments accepted');
+        result.forEach((segment, i) => {
+          assert.equal(segment.role, segments[i].role, `segment ${i} role preserved`);
+        });
+      },
+    },
+
+    // ─── formatHistory → OpenAI Responses API payload shape ───
+
+    {
+      name: 'format-single-system-prompt-emits-system-then-user',
+      async run({ assert }) {
+        const promptSegments = normalizePrompt({ content: 'You are a helpful assistant.' });
+        const formatted = formatHistory(baseOptions(), promptSegments, 'Hello!', noopLog);
+
+        assert.equal(formatted.length, 2, 'two messages: system + user');
+        assert.equal(formatted[0].role, 'system', 'first message is system');
+        assert.equal(formatted[0].content[0].type, 'input_text', 'system uses input_text');
+        assert.equal(formatted[0].content[0].text, 'You are a helpful assistant.', 'system text');
+        assert.equal(formatted[1].role, 'user', 'second message is user');
+        assert.equal(formatted[1].content[0].text, 'Hello!', 'user text');
+      },
+    },
+
+    {
+      name: 'format-system-plus-developer-emits-three-messages-in-order',
+      async run({ assert }) {
+        const promptSegments = normalizePrompt([
+          { role: 'system',    content: 'Platform rules go here.' },
+          { role: 'developer', content: 'Operator config goes here.' },
+        ]);
+        const formatted = formatHistory(baseOptions(), promptSegments, 'Customer email body.', noopLog);
+
+        assert.equal(formatted.length, 3, 'three messages');
+        assert.equal(formatted[0].role, 'system', 'order: system');
+        assert.equal(formatted[1].role, 'developer', 'order: developer');
+        assert.equal(formatted[2].role, 'user', 'order: user');
+        assert.equal(formatted[0].content[0].text, 'Platform rules go here.', 'system content');
+        assert.equal(formatted[1].content[0].text, 'Operator config goes here.', 'developer content');
+        assert.equal(formatted[2].content[0].text, 'Customer email body.', 'user content');
+      },
+    },
+
+    {
+      name: 'format-empty-prompt-array-emits-only-user-message',
+      async run({ assert }) {
+        const formatted = formatHistory(baseOptions(), [], 'Just a user message.', noopLog);
+
+        assert.equal(formatted.length, 1, 'only the user message');
+        assert.equal(formatted[0].role, 'user', 'role: user');
+        assert.equal(formatted[0].content[0].text, 'Just a user message.', 'text preserved');
+      },
+    },
+
+    {
+      name: 'format-interleaves-prompt-history-and-new-user-message',
+      async run({ assert }) {
+        const promptSegments = normalizePrompt([
+          { role: 'system',    content: 'system rules' },
+          { role: 'developer', content: 'developer rules' },
+        ]);
+        const options = baseOptions({
+          history: {
+            messages: [
+              { role: 'user',      content: 'first user msg' },
+              { role: 'assistant', content: 'first ai reply' },
+            ],
+            limit: 5,
+          },
+        });
+        const formatted = formatHistory(options, promptSegments, 'second user msg', noopLog);
+
+        const roleSequence = formatted.map((m) => m.role);
+        assert.deepEqual(
+          roleSequence,
+          ['system', 'developer', 'user', 'assistant', 'user'],
+          'prompts → history → new user message',
+        );
+      },
+    },
+
+    {
+      name: 'format-assistant-history-uses-output_text-type',
+      async run({ assert }) {
+        const options = baseOptions({
+          history: {
+            messages: [{ role: 'assistant', content: 'previous reply' }],
+            limit: 5,
+          },
+        });
+        const formatted = formatHistory(options, [], 'new message', noopLog);
+
+        const assistantMsg = formatted.find((m) => m.role === 'assistant');
+        assert.equal(assistantMsg.content[0].type, 'output_text', 'assistant uses output_text');
+      },
+    },
+
+    {
+      name: 'format-respects-history-limit',
+      async run({ assert }) {
+        const options = baseOptions({
+          history: {
+            messages: [
+              { role: 'user',      content: 'msg 1' },
+              { role: 'assistant', content: 'msg 2' },
+              { role: 'user',      content: 'msg 3' },
+              { role: 'assistant', content: 'msg 4' },
+              { role: 'user',      content: 'msg 5' },
+              { role: 'assistant', content: 'msg 6' },
+            ],
+            limit: 2,
+          },
+        });
+        const formatted = formatHistory(options, normalizePrompt({ content: 'sys' }), 'now', noopLog);
+
+        // Expected: 1 system + 2 history + 1 user = 4 messages
+        assert.equal(formatted.length, 4, 'system + 2 history + new user');
+        assert.equal(formatted[1].content[0].text, 'msg 5', 'second-to-last history kept');
+        assert.equal(formatted[2].content[0].text, 'msg 6', 'last history kept');
+        assert.equal(formatted[3].content[0].text, 'now', 'new user message appended');
+      },
+    },
+
+    {
+      name: 'format-dedupes-trailing-user-history-when-flag-set',
+      async run({ assert }) {
+        const options = baseOptions({
+          dedupeConsecutiveRoles: true,
+          history: {
+            messages: [
+              { role: 'assistant', content: 'reply' },
+              { role: 'user',      content: 'should be dropped' },
+            ],
+            limit: 5,
+          },
+        });
+        const formatted = formatHistory(options, [], 'real new message', noopLog);
+
+        // history's trailing 'user' is dropped, then the real new message is appended
+        assert.equal(formatted.length, 2, 'assistant + new user only');
+        assert.equal(formatted[0].role, 'assistant', 'kept assistant');
+        assert.equal(formatted[1].role, 'user', 'new user');
+        assert.equal(formatted[1].content[0].text, 'real new message', 'new user content');
+      },
+    },
+
+    {
+      name: 'format-strips-and-trims-content',
+      async run({ assert }) {
+        const promptSegments = normalizePrompt({ content: '  padded system content  \n' });
+        const formatted = formatHistory(baseOptions(), promptSegments, '  padded user content  ', noopLog);
+
+        assert.equal(formatted[0].content[0].text, 'padded system content', 'system trimmed');
+        assert.equal(formatted[1].content[0].text, 'padded user content', 'user trimmed');
+      },
+    },
+  ],
+};