backend-manager 5.2.8 → 5.2.10

package/CHANGELOG.md

@@ -14,6 +14,30 @@ 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.10] - 2026-05-26
+
+### Added
+
+- **`POST /admin/post`: resize images at ingest.** Downloaded post images are now checked against `IMAGE_MAX_DIMENSION` (4096px on the long edge) in `src/manager/routes/admin/post/post.js` and re-encoded as progressive JPEG at `IMAGE_JPEG_QUALITY` (80) when oversized. Prevents downstream Jekyll/imagemin pipelines from stalling on huge sources (a real 16384×10576 source decoded to ~520MB raw and silently broke 4 StudyMonkey posts on production). `resizeImage`, `IMAGE_MAX_DIMENSION`, and `IMAGE_JPEG_QUALITY` are exported for tests. Adds `sharp` as a dependency.
+- **`test/routes/admin/post-resize-image.js`** — 7 unit tests covering the resize contract (pass-through under the limit, boundary at exact limit, landscape/portrait/square scaling, the 16384×10576 case, on-disk overwrite). No network, no auth, no GitHub.
+- **`test/routes/admin/create-post.js`**: extended `create-post-rewrites-body-images` to submit a 5000×3000 header image, plus new `verify-oversized-header-image-was-resized` step that fetches the committed image back from GitHub and asserts long edge ≤ 4096px.
+
+### Changed
+
+- **Dependency bumps**: `sharp` ^0.34.4 → ^0.34.5, `sanitize-html` ^2.17.3 → ^2.17.4 (auto-bumped at install).
+
+# [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/CLAUDE.md

@@ -119,7 +119,7 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 
 ### Built-in Routes
 
-- [docs/admin-post-route.md](docs/admin-post-route.md) — `POST/PUT /admin/post` blog creation via GitHub (image extraction + `@post/` rewriting)
+- [docs/admin-post-route.md](docs/admin-post-route.md) — `POST/PUT /admin/post` blog creation via GitHub (image extraction + resize at ingest + `@post/` rewriting)
 - [docs/payment-system.md](docs/payment-system.md) — full payment pipeline: Intent → Webhook → On-Write → Transition; subscription model, statuses, `resolveSubscription()`, transition handlers, processor interface, product config, test processor
 - [docs/marketing-campaigns.md](docs/marketing-campaigns.md) — campaign CRUD routes, recurring campaigns, generator pipeline (newsletter), template-owned schemas, asset hosting, seed campaigns
 - [docs/consent.md](docs/consent.md) — marketing consent capture: canonical `consent.{legal,marketing}` user-doc shape, signup-form capture, account-page toggle, HMAC unsub link, SendGrid+Beehiiv webhook receivers, parent forwarder (`/marketing/webhook/forward`), migration script template

package/docs/admin-post-route.md

@@ -1,24 +1,46 @@
 # Admin Post Route
 
-The `POST /admin/post` route creates blog posts via GitHub's API. It handles image extraction, upload, and body rewriting.
+The `POST /admin/post` route creates blog posts via GitHub's API. It handles image extraction, resize, upload, and body rewriting.
 
 ## Image Processing Flow
 
 1. Receives markdown body with external image URLs (e.g., `![alt](https://images.unsplash.com/...)`)
 2. Extracts all `![alt](url)` patterns from the body using regex
-3. Downloads each image and uploads it to `src/assets/images/blog/post-{id}/` on GitHub
-4. **Rewrites the body** to replace external URLs with `@post/{filename}` format
-5. The `@post/` prefix is resolved at Jekyll build time by `jekyll-uj-powertools` to the full path
+3. Downloads each image to a tmp dir
+4. **Resizes** each image in place if its long edge exceeds `IMAGE_MAX_DIMENSION` (see below)
+5. Commits all images to `src/assets/images/blog/post-{id}/` on GitHub (single commit via Git Trees API)
+6. **Rewrites the body** to replace external URLs with `@post/{filename}` format
+7. The `@post/` prefix is resolved at Jekyll build time by `jekyll-uj-powertools` to the full path
+
+## Image resize
+
+Sources from guest-post submissions can be enormous (16384×10576 has been seen in the wild — ~520MB raw RGB). Sources that large stall downstream Jekyll/imagemin pipelines on the consumer site, which silently ship the site missing those images.
+
+To prevent this, every downloaded image is checked against `IMAGE_MAX_DIMENSION` (4096px on the long edge) and re-encoded as a progressive JPEG at `IMAGE_JPEG_QUALITY` (80) if it exceeds the limit. Images already at or below the limit pass through untouched.
+
+The resize happens in `downloadImage()` (after the `.jpg` extension check, before returning to the caller), so:
+- The base64 content that gets committed to GitHub is the resized version
+- The consumer repo never sees the giant source
+- Future downstream optimization (UJM imagemin, etc.) starts from a sane source size
+
+Constants live in `src/manager/routes/admin/post/post.js`:
+```js
+const IMAGE_MAX_DIMENSION = 4096;
+const IMAGE_JPEG_QUALITY = 80;
+```
+
+If these need to become configurable later, promote to `backend-manager-config.json` rather than env vars (deploy-environment-specific overrides aren't a real use case — the values are algorithm constants).
 
 ## Key Details
 
 - Image filenames are derived from `hyphenate(alt_text)` + downloaded extension
+- Only `.jpg` is accepted; other formats reject with a 400
 - Header image (`headerImageURL`) is uploaded but NOT rewritten in the body (it's in frontmatter)
 - Failed image downloads are skipped — the original external URL stays in the body
-- The `extractImages()` function returns a URL mapping used for body rewriting
+- All images + the post markdown are committed in a single commit via the Git Trees API
 
 ## Files
 
-- `src/manager/routes/admin/post/post.js` — POST handler (create)
-- `src/manager/routes/admin/post/put.js` — PUT handler (edit)
+- `src/manager/routes/admin/post/post.js` — POST handler (create), includes `downloadImage()` + `resizeImage()` helpers
+- `src/manager/routes/admin/post/put.js` — PUT handler (edit) — does NOT download images, just edits frontmatter/body in place
 - `src/manager/routes/admin/post/templates/post.html` — Post template

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.2.8",
+  "version": "5.2.10",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
@@ -49,18 +49,18 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.140",
-    "@anthropic-ai/sdk": "^0.95.2",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.152",
+    "@anthropic-ai/sdk": "^0.99.0",
     "@firebase/rules-unit-testing": "^5.0.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/pubsub": "^5.3.0",
     "@google-cloud/storage": "^7.19.0",
-    "@inquirer/prompts": "^8.4.3",
+    "@inquirer/prompts": "^8.5.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@octokit/rest": "^22.0.1",
     "@resvg/resvg-js": "^2.6.2",
     "@sendgrid/mail": "^8.1.6",
-    "@sentry/node": "^10.53.1",
+    "@sentry/node": "^10.54.0",
     "body-parser": "^2.2.2",
     "busboy": "^1.6.0",
     "chalk": "^5.6.2",
@@ -76,15 +76,16 @@
     "lodash": "^4.18.1",
     "lowdb": "^7.0.1",
     "mailchimp-api-v3": "^1.15.0",
-    "markdown-it": "^14.1.1",
+    "markdown-it": "^14.2.0",
     "mime-types": "^3.0.2",
-    "mjml": "^5.2.1",
+    "mjml": "^5.3.0",
     "moment": "^2.30.1",
     "nanoid": "^5.1.11",
     "node-powertools": "^3.0.0",
     "npm-api": "^1.0.1",
     "pushid": "^1.0.0",
-    "sanitize-html": "^2.17.3",
+    "sanitize-html": "^2.17.4",
+    "sharp": "^0.34.5",
     "stripe": "^22.1.1",
     "uid-generator": "^2.0.0",
     "uuid": "^14.0.0",
@@ -98,7 +99,7 @@
     "prepare-package": "^2.1.0"
   },
   "peerDependencies": {
-    "firebase-admin": "^13.9.0",
+    "firebase-admin": "^13.10.0",
     "firebase-functions": "^7.2.5"
   }
 }

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/email/data/disposable-domains.json

@@ -3081,6 +3081,7 @@
   "mannawo.com",
   "mansiondev.com",
   "maohe.cloud",
+  "marineso.com",
   "mark-compressoren.ru",
   "marketlink.info",
   "markmurfin.com",

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/src/manager/routes/admin/post/post.js

@@ -17,6 +17,13 @@ const POST_TEMPLATE = jetpack.read(`${__dirname}/templates/post.html`);
 const IMAGE_PATH_SRC = `src/assets/images/blog/post-{id}/`;
 const IMAGE_REGEX = /(?:!\[(.*?)\]\((.*?)\))/img;
 
+// Max dimension (px) for downloaded post images on the long edge, and JPEG
+// re-encode quality. Sources above the max cause downstream Jekyll/imagemin
+// pipelines to stall on huge decodes (e.g. a 16384×10576 source decodes to
+// ~520MB raw), so resize at ingest time.
+const IMAGE_MAX_DIMENSION = 4096;
+const IMAGE_JPEG_QUALITY = 80;
+
 module.exports = async ({ assistant, Manager, user, settings, analytics }) => {
 
   // Require authentication
@@ -218,9 +225,47 @@ async function downloadImage(assistant, src, alt) {
     throw new Error(`Images must be .jpg (not ${result.ext})`);
   }
 
+  // Resize in place if the long edge exceeds IMAGE_MAX_DIMENSION
+  await resizeImage(assistant, result.path);
+
   return result;
 }
 
+// Helper: Resize image in place if the long edge exceeds IMAGE_MAX_DIMENSION.
+// Re-encodes as progressive JPEG at IMAGE_JPEG_QUALITY. Short-circuits when the
+// source is already within the limit.
+async function resizeImage(assistant, filepath) {
+  const sharp = assistant.Manager.require('sharp');
+
+  const meta = await sharp(filepath).metadata();
+  const longEdge = Math.max(meta.width, meta.height);
+
+  if (longEdge <= IMAGE_MAX_DIMENSION) {
+    assistant.log(`resizeImage(): No resize needed (${meta.width}x${meta.height})`);
+    return { resized: false, width: meta.width, height: meta.height };
+  }
+
+  // Resize to a buffer (cannot read+write the same path in one sharp pipeline)
+  const buffer = await sharp(filepath)
+    .resize({
+      width: IMAGE_MAX_DIMENSION,
+      height: IMAGE_MAX_DIMENSION,
+      fit: 'inside',
+      withoutEnlargement: true,
+    })
+    .jpeg({ quality: IMAGE_JPEG_QUALITY, progressive: true })
+    .toBuffer();
+
+  // Overwrite the file on disk
+  jetpack.write(filepath, buffer);
+
+  // Read the resized dimensions back for the log
+  const resizedMeta = await sharp(filepath).metadata();
+  assistant.log(`resizeImage(): Resized ${meta.width}x${meta.height} -> ${resizedMeta.width}x${resizedMeta.height} (max ${IMAGE_MAX_DIMENSION}px, q${IMAGE_JPEG_QUALITY})`);
+
+  return { resized: true, width: resizedMeta.width, height: resizedMeta.height };
+}
+
 // Helper: Commit all files (images + post) in a single commit using Git Trees API
 async function commitAll(assistant, octokit, settings, files) {
   const owner = settings.githubUser;
@@ -326,3 +371,8 @@ function formatClone(payload) {
   return payload;
 }
 
+// Expose helpers + constants for tests
+module.exports.resizeImage = resizeImage;
+module.exports.IMAGE_MAX_DIMENSION = IMAGE_MAX_DIMENSION;
+module.exports.IMAGE_JPEG_QUALITY = IMAGE_JPEG_QUALITY;
+

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');
+      },
+    },
+  ],
+};

package/test/routes/admin/create-post.js

@@ -5,6 +5,9 @@
  * Requires admin/blogger role, GitHub API key, and repo_website config
  */
 const { Octokit } = require('@octokit/rest');
+const sharp = require('sharp');
+
+const { IMAGE_MAX_DIMENSION } = require('../../../src/manager/routes/admin/post/post');
 
 module.exports = {
   description: 'Admin create post on GitHub',
@@ -130,12 +133,15 @@ module.exports = {
 
         // Use a real public .jpg for the inline image
         const inlineImageURL = 'https://picsum.photos/id/10/200/200.jpg';
+        // Oversized header image (long edge 5000px > IMAGE_MAX_DIMENSION 4096px) to
+        // verify the resize step runs end-to-end and the committed file is clamped.
+        const headerImageURL = 'https://picsum.photos/id/1/5000/3000.jpg';
 
         const response = await http.post('admin/post', {
           title: 'BEM Test Create Post',
           url: 'bem-test-create-post',
           description: 'Test post created by BEM test suite to verify @post/ body rewriting.',
-          headerImageURL: 'https://picsum.photos/id/1/400/300.jpg',
+          headerImageURL: headerImageURL,
           body: `# BEM Test Create Post\n\nSome intro text.\n\n![Test inline image](${inlineImageURL})\n\nMore text after the image.`,
           postPath: 'guest',
         });
@@ -186,6 +192,53 @@ module.exports = {
       },
     },
 
+    {
+      name: 'verify-oversized-header-image-was-resized',
+      auth: 'admin',
+      timeout: 30000,
+      skip: !process.env.TEST_EXTENDED_MODE ? 'TEST_EXTENDED_MODE env var not set' : false,
+
+      async run({ assert, state }) {
+        if (!state.postId) {
+          return; // Previous test didn't run
+        }
+
+        const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+        const imageDir = `src/assets/images/blog/post-${state.postId}/`;
+
+        // List committed images and pick the header (matches the slugified URL "bem-test-create-post")
+        const { data: dirData } = await octokit.rest.repos.getContent({
+          owner: state.owner,
+          repo: state.repo,
+          path: imageDir,
+        });
+
+        const headerFile = dirData.find((f) => f.name === 'bem-test-create-post.jpg');
+        assert.ok(headerFile, 'Header image should be committed at expected slug');
+
+        // Fetch the raw bytes and read dimensions
+        const { data: blob } = await octokit.rest.git.getBlob({
+          owner: state.owner,
+          repo: state.repo,
+          file_sha: headerFile.sha,
+        });
+
+        const buffer = Buffer.from(blob.content, 'base64');
+        const meta = await sharp(buffer).metadata();
+
+        // The source we requested was 5000x3000 (over the 4096 limit).
+        // After resize, the long edge should be clamped to IMAGE_MAX_DIMENSION.
+        const longEdge = Math.max(meta.width, meta.height);
+        assert.ok(
+          longEdge <= IMAGE_MAX_DIMENSION,
+          `Committed header image long edge (${meta.width}x${meta.height}) should be <= IMAGE_MAX_DIMENSION (${IMAGE_MAX_DIMENSION})`,
+        );
+
+        // And the resize should actually have happened (source was 5000x3000 → expect width=4096)
+        assert.equal(meta.width, IMAGE_MAX_DIMENSION, 'Resized width should equal IMAGE_MAX_DIMENSION');
+      },
+    },
+
     // --- Auth rejection tests ---
 
     {

package/test/routes/admin/post-resize-image.js

@@ -0,0 +1,187 @@
+/**
+ * Test: routes/admin/post/post.resizeImage
+ * Unit tests for the in-place image resize used by the admin/post route.
+ *
+ * Run: npx mgr test routes/admin/post-resize-image
+ *
+ * Contract:
+ *   - Images with both dimensions <= IMAGE_MAX_DIMENSION pass through untouched.
+ *   - Images with either dimension > IMAGE_MAX_DIMENSION are resized in place,
+ *     preserving aspect ratio, with the long edge clamped to IMAGE_MAX_DIMENSION.
+ *   - Resize re-encodes as JPEG at IMAGE_JPEG_QUALITY (lossy is expected).
+ *   - The file at the original path is overwritten with the resized bytes.
+ */
+const os = require('os');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const sharp = require('sharp');
+
+const post = require('../../../src/manager/routes/admin/post/post');
+
+const { resizeImage, IMAGE_MAX_DIMENSION, IMAGE_JPEG_QUALITY } = post;
+
+// Generate a synthetic JPEG of the given dimensions and write it to a tmp path.
+// Returns the absolute path on disk.
+async function makeJpeg(width, height) {
+  const filepath = path.join(os.tmpdir(), `bem-test-resize-${Date.now()}-${width}x${height}.jpg`);
+  const buffer = await sharp({
+    create: {
+      width: width,
+      height: height,
+      channels: 3,
+      background: { r: 128, g: 128, b: 128 },
+    },
+  })
+    .jpeg({ quality: 90 })
+    .toBuffer();
+
+  jetpack.write(filepath, buffer);
+  return filepath;
+}
+
+// Minimal assistant stub — resizeImage only uses Manager.require + log.
+function makeAssistant() {
+  return {
+    log: () => {},
+    Manager: {
+      require: (mod) => require(mod),
+    },
+  };
+}
+
+module.exports = {
+  description: 'routes/admin/post/post.resizeImage',
+  type: 'group',
+
+  tests: [
+    // ─── Constants exposed ───
+
+    {
+      name: 'exports-constants',
+      async run({ assert }) {
+        assert.equal(IMAGE_MAX_DIMENSION, 4096, 'IMAGE_MAX_DIMENSION should be 4096');
+        assert.equal(IMAGE_JPEG_QUALITY, 80, 'IMAGE_JPEG_QUALITY should be 80');
+        assert.isType(resizeImage, 'function', 'resizeImage should be exported as a function');
+      },
+    },
+
+    // ─── Pass-through: image already within bounds ───
+
+    {
+      name: 'small-image-passes-through-untouched',
+      async run({ assert }) {
+        const filepath = await makeJpeg(800, 600);
+        const sizeBefore = jetpack.inspect(filepath).size;
+
+        const result = await resizeImage(makeAssistant(), filepath);
+
+        assert.equal(result.resized, false, 'Small image should not be resized');
+        assert.equal(result.width, 800, 'Width should be reported as-is');
+        assert.equal(result.height, 600, 'Height should be reported as-is');
+
+        const sizeAfter = jetpack.inspect(filepath).size;
+        assert.equal(sizeAfter, sizeBefore, 'File on disk should be byte-identical (no re-encode)');
+
+        jetpack.remove(filepath);
+      },
+    },
+
+    {
+      name: 'image-exactly-at-max-passes-through',
+      async run({ assert }) {
+        // Long edge exactly === IMAGE_MAX_DIMENSION → no resize (boundary condition)
+        const filepath = await makeJpeg(IMAGE_MAX_DIMENSION, 2000);
+
+        const result = await resizeImage(makeAssistant(), filepath);
+
+        assert.equal(result.resized, false, 'Image exactly at the limit should not be resized');
+        assert.equal(result.width, IMAGE_MAX_DIMENSION, 'Width unchanged');
+
+        jetpack.remove(filepath);
+      },
+    },
+
+    // ─── Resize: landscape (width > height) ───
+
+    {
+      name: 'landscape-oversized-is-resized-to-max-width',
+      async run({ assert }) {
+        // 8000x4000 landscape → long edge is width → clamp width to 4096, scale height proportionally to 2048
+        const filepath = await makeJpeg(8000, 4000);
+
+        const result = await resizeImage(makeAssistant(), filepath);
+
+        assert.equal(result.resized, true, 'Oversized landscape should be resized');
+        assert.equal(result.width, IMAGE_MAX_DIMENSION, 'Width clamped to IMAGE_MAX_DIMENSION');
+        assert.equal(result.height, IMAGE_MAX_DIMENSION / 2, 'Height scaled proportionally (8000:4000 → 4096:2048)');
+
+        // Verify the file on disk was actually overwritten
+        const meta = await sharp(filepath).metadata();
+        assert.equal(meta.width, IMAGE_MAX_DIMENSION, 'On-disk width matches reported width');
+        assert.equal(meta.height, IMAGE_MAX_DIMENSION / 2, 'On-disk height matches reported height');
+        assert.equal(meta.format, 'jpeg', 'On-disk format is JPEG');
+
+        jetpack.remove(filepath);
+      },
+    },
+
+    // ─── Resize: portrait (height > width) ───
+
+    {
+      name: 'portrait-oversized-is-resized-to-max-height',
+      async run({ assert }) {
+        // 4000x8000 portrait → long edge is height → clamp height to 4096, width proportionally to 2048
+        const filepath = await makeJpeg(4000, 8000);
+
+        const result = await resizeImage(makeAssistant(), filepath);
+
+        assert.equal(result.resized, true, 'Oversized portrait should be resized');
+        assert.equal(result.width, IMAGE_MAX_DIMENSION / 2, 'Width scaled proportionally');
+        assert.equal(result.height, IMAGE_MAX_DIMENSION, 'Height clamped to IMAGE_MAX_DIMENSION');
+
+        jetpack.remove(filepath);
+      },
+    },
+
+    // ─── Resize: huge image (the bug we are guarding against) ───
+
+    {
+      name: 'huge-image-is-resized-down',
+      async run({ assert }) {
+        // 16384x10576 — the actual size from post-1779087609 (the-importance-of-feedback-loops).
+        // Raw RGB this size is ~520MB, which is what stalled UJM's imagemin stream.
+        const filepath = await makeJpeg(16384, 10576);
+        const sizeBefore = jetpack.inspect(filepath).size;
+
+        const result = await resizeImage(makeAssistant(), filepath);
+
+        assert.equal(result.resized, true, 'Huge image should be resized');
+        assert.equal(result.width, IMAGE_MAX_DIMENSION, 'Long edge clamped to IMAGE_MAX_DIMENSION');
+        // 16384:10576 ratio → height = 4096 * (10576/16384) = 2644
+        assert.inRange(result.height, 2643, 2645, 'Height scaled proportionally (within rounding)');
+
+        const sizeAfter = jetpack.inspect(filepath).size;
+        assert.ok(sizeAfter < sizeBefore, 'Resized file on disk should be smaller than original');
+
+        jetpack.remove(filepath);
+      },
+    },
+
+    // ─── Square images ───
+
+    {
+      name: 'square-oversized-is-resized-to-square',
+      async run({ assert }) {
+        const filepath = await makeJpeg(8000, 8000);
+
+        const result = await resizeImage(makeAssistant(), filepath);
+
+        assert.equal(result.resized, true, 'Oversized square should be resized');
+        assert.equal(result.width, IMAGE_MAX_DIMENSION, 'Width clamped');
+        assert.equal(result.height, IMAGE_MAX_DIMENSION, 'Height clamped');
+
+        jetpack.remove(filepath);
+      },
+    },
+  ],
+};