mango-cms 0.3.34 → 0.3.35

package/lib/vibe-orchestrator/src/costStore.js

@@ -0,0 +1,209 @@
+// costStore.js
+//
+// Durable per-turn cost log for the vibe assistant (HAP-1123). Append-only NDJSON
+// so it survives orchestrator restarts and stays queryable without standing up a
+// DB inside this dependency-free service. One line per completed turn:
+//
+//   { ts, site, path, sessionId, model, costUsd, tokens:{input,output,cacheRead,
+//     total,billable}, promptSummary, ok }
+//
+// The CLI's reported `total_cost_usd` is the source of truth for `costUsd`
+// (captured in claudeRunner). When the CLI omits a cost we fall back to a
+// model→price table (estimateCostUsd) so a record is never cost-less.
+//
+// Pure of the clock: callers pass `ts`. fs is touched only on append/read so the
+// rollup math stays unit-testable against an injected path.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { config } from './config.js'
+
+/** Default NDJSON log location. Override with VIBE_COST_LOG (absolute path). */
+function defaultLogPath() {
+  return process.env.VIBE_COST_LOG || path.join(config.stagingRoot, '.vibe-costs.ndjson')
+}
+
+// Per-MTok USD prices (input / output) used ONLY when the CLI omits a cost. These
+// are coarse list prices for sanity, not billing truth — the CLI's
+// total_cost_usd is authoritative and is what we persist when present.
+const PRICE_TABLE = [
+  { match: /opus/i, inPerMTok: 15, outPerMTok: 75 },
+  { match: /sonnet/i, inPerMTok: 3, outPerMTok: 15 },
+  { match: /haiku/i, inPerMTok: 0.8, outPerMTok: 4 },
+]
+
+/**
+ * Estimate a turn's cost from tokens when the CLI didn't report one. Cache-read
+ * input is billed at the same coarse input rate here (good enough for a fallback;
+ * the CLI's real number already accounts for cache discounts when available).
+ * @returns {number|null} USD, or null when the model is unknown
+ */
+function estimateCostUsd({ model, inputTokens = 0, outputTokens = 0 } = {}) {
+  if (!model) return null
+  const row = PRICE_TABLE.find((r) => r.match.test(model))
+  if (!row) return null
+  return (inputTokens / 1e6) * row.inPerMTok + (outputTokens / 1e6) * row.outPerMTok
+}
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0
+}
+
+/**
+ * Apply the client-facing markup to a raw cost. `pct` is a percentage (100 ⇒ 2×).
+ * Returns null when the cost is absent so a missing cost never becomes $0.00.
+ * @param {number|null} cost  raw USD
+ * @param {number} pct        markup percent
+ */
+function applyMarkup(cost, pct) {
+  if (typeof cost !== 'number' || !Number.isFinite(cost)) return null
+  return cost * (1 + num(pct) / 100)
+}
+
+/**
+ * Normalize a raw record into the durable shape. Coerces token numbers and
+ * back-fills `costUsd` from the price table when absent. `ts` defaults to 0 so
+ * the module never reads the clock — real callers pass Date.now().
+ */
+function normalizeEntry(raw = {}) {
+  const t = raw.tokens || {}
+  const tokens = {
+    input: num(t.input ?? t.inputTokens),
+    output: num(t.output ?? t.outputTokens),
+    cacheRead: num(t.cacheRead ?? t.cacheReadTokens),
+    total: num(t.total ?? t.totalTokens),
+    billable: num(t.billable ?? t.billableTokens),
+  }
+  let costUsd = typeof raw.costUsd === 'number' && Number.isFinite(raw.costUsd) ? raw.costUsd : null
+  let costEstimated = false
+  if (costUsd == null) {
+    const est = estimateCostUsd({ model: raw.model, inputTokens: tokens.input, outputTokens: tokens.output })
+    if (est != null) { costUsd = est; costEstimated = true }
+  }
+  return {
+    ts: num(raw.ts),
+    site: raw.site || null,
+    path: raw.path || null,
+    sessionId: raw.sessionId || null,
+    model: raw.model || null,
+    costUsd,
+    costEstimated,
+    tokens,
+    promptSummary: raw.promptSummary || '',
+    ok: raw.ok !== false,
+  }
+}
+
+/**
+ * Append one cost record as an NDJSON line. Creates the parent dir if needed.
+ * Returns the normalized record. Throws on fs failure — callers wrap this in a
+ * best-effort try/catch so cost logging never breaks a run.
+ */
+function appendCost(raw, logPath = defaultLogPath()) {
+  const entry = normalizeEntry(raw)
+  fs.mkdirSync(path.dirname(logPath), { recursive: true })
+  fs.appendFileSync(logPath, JSON.stringify(entry) + '\n')
+  return entry
+}
+
+/** Read all records, tolerating partial/corrupt trailing lines. */
+function readAll(logPath = defaultLogPath()) {
+  let text
+  try {
+    text = fs.readFileSync(logPath, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return []
+    throw e
+  }
+  const out = []
+  for (const line of text.split('\n')) {
+    const s = line.trim()
+    if (!s) continue
+    try { out.push(JSON.parse(s)) } catch { /* skip a torn line */ }
+  }
+  return out
+}
+
+/** Read records filtered to the [from, to] ms window (inclusive). */
+function readCosts({ from, to, site } = {}, logPath = defaultLogPath()) {
+  return readAll(logPath).filter((r) => {
+    if (typeof from === 'number' && num(r.ts) < from) return false
+    if (typeof to === 'number' && num(r.ts) > to) return false
+    if (site && r.site !== site) return false
+    return true
+  })
+}
+
+/** UTC YYYY-MM-DD for a ms timestamp. */
+function dayKey(ts) {
+  return new Date(num(ts)).toISOString().slice(0, 10)
+}
+
+function emptyBucket() {
+  return { count: 0, costUsd: 0, billedUsd: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0 }
+}
+
+function addTo(bucket, r, pct) {
+  bucket.count += 1
+  bucket.costUsd += num(r.costUsd)
+  bucket.billedUsd += num(applyMarkup(num(r.costUsd), pct))
+  const t = r.tokens || {}
+  bucket.inputTokens += num(t.input)
+  bucket.outputTokens += num(t.output)
+  bucket.totalTokens += num(t.total)
+}
+
+/**
+ * Sum a date window into a rollup the board can invoice from. Groups by UTC day,
+ * by session, and by model. `costUsd` is the RAW API cost (CLI's total_cost_usd);
+ * `billedUsd` is that cost with the client-facing markup applied (HAP-1123 board
+ * request). The rollup carries both plus the `markupPct` used, so the board sees
+ * raw and client-billed side by side.
+ *
+ * @param {{from?,to?,site?,markupPct?}} [opts] markupPct defaults to config
+ * @returns {{
+ *   from, to, markupPct, count, totalCostUsd, totalBilledUsd, totalTokens,
+ *   byDay: Object, bySession: Object, byModel: Object
+ * }}
+ */
+function rollup({ from, to, site, markupPct } = {}, logPath = defaultLogPath()) {
+  const pct = num(markupPct != null ? markupPct : config.markupPct)
+  const rows = readCosts({ from, to, site }, logPath)
+  const byDay = {}
+  const bySession = {}
+  const byModel = {}
+  let totalCostUsd = 0
+  let totalTokens = 0
+  for (const r of rows) {
+    totalCostUsd += num(r.costUsd)
+    totalTokens += num(r.tokens?.total)
+    const d = dayKey(r.ts)
+    ;(byDay[d] ||= emptyBucket()) && addTo(byDay[d], r, pct)
+    const sid = r.sessionId || 'unknown'
+    ;(bySession[sid] ||= emptyBucket()) && addTo(bySession[sid], r, pct)
+    const m = r.model || 'unknown'
+    ;(byModel[m] ||= emptyBucket()) && addTo(byModel[m], r, pct)
+  }
+  const round = (n) => Math.round(n * 1e6) / 1e6
+  totalCostUsd = round(totalCostUsd)
+  const totalBilledUsd = round(num(applyMarkup(totalCostUsd, pct)))
+  for (const b of [...Object.values(byDay), ...Object.values(bySession), ...Object.values(byModel)]) {
+    b.costUsd = round(b.costUsd)
+    b.billedUsd = round(b.billedUsd)
+  }
+  return {
+    from: typeof from === 'number' ? from : null,
+    to: typeof to === 'number' ? to : null,
+    site: site || null,
+    markupPct: pct,
+    count: rows.length,
+    totalCostUsd,
+    totalBilledUsd,
+    totalTokens,
+    byDay,
+    bySession,
+    byModel,
+  }
+}
+
+export { appendCost, readCosts, readAll, rollup, normalizeEntry, estimateCostUsd, applyMarkup, defaultLogPath }

package/lib/vibe-orchestrator/src/ownerToken.js

@@ -0,0 +1,113 @@
+// ownerToken.js
+//
+// Real per-owner auth for the orchestrator (HAP-1109). Replaces the old
+// optional shared-secret gate, which failed OPEN when unset and could not tell
+// one caller from another.
+//
+// A vibe owner token is a compact, dependency-free, JWT-like string:
+//
+//   base64url(JSON(payload)) + "." + base64url(HMAC_SHA256(part1, secret))
+//
+// payload = { v:1, sub:<memberId>, roles:[...], site:<slug>, iat, exp }   (epoch seconds)
+//
+// The token is MINTED server-side by Mango from an authenticated admin session
+// (mango/endpoints -> mango/helpers/vibeToken.js, same format) and VERIFIED here
+// with a secret shared only between Mango and the orchestrator
+// (VIBE_ORCH_TOKEN_SECRET). The signature proves the claims were issued by Mango;
+// a non-owner cannot forge an admin role without the secret, and the client-side
+// role flag is no longer trusted. The Claude OAuth token is never involved.
+
+import crypto from 'node:crypto'
+
+const TOKEN_VERSION = 1
+
+function b64urlEncode(buf) {
+  return Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function b64urlDecode(str) {
+  const pad = str.length % 4 === 0 ? '' : '='.repeat(4 - (str.length % 4))
+  return Buffer.from(str.replace(/-/g, '+').replace(/_/g, '/') + pad, 'base64')
+}
+
+function sign(part, secret) {
+  return b64urlEncode(crypto.createHmac('sha256', secret).update(part).digest())
+}
+
+/** Constant-time string compare that never short-circuits on length. */
+function safeEqual(a, b) {
+  const ab = Buffer.from(String(a))
+  const bb = Buffer.from(String(b))
+  if (ab.length !== bb.length) {
+    // Still run a comparison to keep timing flat, then fail.
+    crypto.timingSafeEqual(ab, ab)
+    return false
+  }
+  return crypto.timingSafeEqual(ab, bb)
+}
+
+/**
+ * Mint an owner token. Used by tests/tooling; the production minter lives in
+ * Mango (mango/helpers/vibeToken.js) and MUST keep this exact format.
+ *
+ * @param {Object} opts
+ * @param {string} opts.secret               shared HMAC secret (required)
+ * @param {string} opts.sub                  member id
+ * @param {string[]} [opts.roles]            member roles
+ * @param {string} [opts.site]               site slug the token is scoped to
+ * @param {number} [opts.ttlSeconds=600]     lifetime
+ * @param {number} [opts.now]                epoch seconds (testing override)
+ */
+function mintOwnerToken({ secret, sub, roles = [], site = '', ttlSeconds = 600, now } = {}) {
+  if (!secret) throw new Error('mintOwnerToken: secret required')
+  if (!sub) throw new Error('mintOwnerToken: sub (member id) required')
+  const iat = Number.isFinite(now) ? Math.floor(now) : Math.floor(Date.now() / 1000)
+  const payload = { v: TOKEN_VERSION, sub: String(sub), roles: Array.isArray(roles) ? roles : [], site, iat, exp: iat + ttlSeconds }
+  const part = b64urlEncode(JSON.stringify(payload))
+  return `${part}.${sign(part, secret)}`
+}
+
+/**
+ * Verify an owner token. Returns { ok, payload } or { ok:false, reason, status }.
+ * status is the HTTP status the caller should surface (401 vs 403).
+ *
+ * @param {string} token
+ * @param {Object} opts
+ * @param {string} opts.secret               shared HMAC secret
+ * @param {string} [opts.site]               if set, token.site must match
+ * @param {string[]} [opts.ownerRoles]       roles that count as owner (default ['admin'])
+ * @param {number} [opts.now]                epoch seconds (testing override)
+ */
+function verifyOwnerToken(token, { secret, site, ownerRoles = ['admin'], now } = {}) {
+  if (!secret) return { ok: false, reason: 'owner auth not configured', status: 503 }
+  if (!token || typeof token !== 'string') return { ok: false, reason: 'missing token', status: 401 }
+
+  const dot = token.indexOf('.')
+  if (dot <= 0 || dot === token.length - 1) return { ok: false, reason: 'malformed token', status: 401 }
+  const part = token.slice(0, dot)
+  const sig = token.slice(dot + 1)
+
+  if (!safeEqual(sig, sign(part, secret))) return { ok: false, reason: 'bad signature', status: 401 }
+
+  let payload
+  try {
+    payload = JSON.parse(b64urlDecode(part).toString('utf8'))
+  } catch {
+    return { ok: false, reason: 'unparseable payload', status: 401 }
+  }
+  if (!payload || payload.v !== TOKEN_VERSION) return { ok: false, reason: 'unsupported token version', status: 401 }
+
+  const nowSec = Number.isFinite(now) ? Math.floor(now) : Math.floor(Date.now() / 1000)
+  if (typeof payload.exp !== 'number' || nowSec >= payload.exp) return { ok: false, reason: 'token expired', status: 401 }
+  if (typeof payload.iat === 'number' && nowSec + 60 < payload.iat) return { ok: false, reason: 'token not yet valid', status: 401 }
+
+  if (site && payload.site && payload.site !== site) return { ok: false, reason: 'token scoped to a different site', status: 403 }
+
+  const roles = Array.isArray(payload.roles) ? payload.roles : []
+  const isOwner = ownerRoles.some((r) => roles.includes(r))
+  if (!isOwner) return { ok: false, reason: 'not an owner', status: 403 }
+
+  return { ok: true, payload }
+}
+
+export { mintOwnerToken, verifyOwnerToken, TOKEN_VERSION }

package/lib/vibe-orchestrator/src/pathGuard.js

@@ -0,0 +1,114 @@
+// pathGuard.js
+//
+// Server-side denylist for vibe edits (HAP-1124, protection #1). The in-page
+// assistant must never be able to edit the Vibe system itself — the ⌘K drawer
+// and its client, the orchestrator service, the staging spine, the settings /
+// secrets build, the vibe Mango endpoints, and the deploy/CI scripts. If it
+// could, a single prompt could brick the very thing the owner uses to recover.
+//
+// This is PURE and prompt-independent: the preamble also tells the agent which
+// files are off-limits (good UX), but enforcement lives in the PreToolUse hook
+// (`scripts/path-guard-hook.mjs`) which imports `isProtectedPath` from here and
+// blocks the tool BEFORE the edit lands — regardless of what the prompt says.
+//
+// Patterns are matched against a POSIX, repo-root-relative path. Supported glob
+// tokens: `**` (any run of path segments, including none), `*` (any run within a
+// single segment). Everything else is matched literally.
+
+const PROTECTED_PATTERNS = [
+  // ⌘K palette / drawer UI and its orchestrator client
+  'src/components/layout/vibeAssistant.vue',
+  'src/components/layout/publishDialog.vue',
+  'src/helpers/orchestrator.js',
+
+  // The orchestrator service itself (entire tree)
+  'orchestrator/**',
+
+  // Staging spine — the overlay + build config that make the clone real
+  'mango/helpers/staging.mjs',
+  'vite.config.js',
+  'vite.staging.config.js',
+
+  // Settings / secrets and the settings build
+  'mango/config/settings.json',
+  'mango/config/settings.local.json',
+  'build-settings.mjs',
+  'mango/helpers/build-settings.mjs',
+
+  // Vibe server endpoints: owner-token mint + cost ingest
+  'mango/helpers/vibeToken.js',
+  'mango/helpers/vibeCosts.js',
+
+  // Deploy / CI / process management
+  'mango/helpers/deploy.sh',
+  'mango/helpers/update.sh',
+  '.github/**',
+  'nginx/**',
+  '**/*.nginx',
+  '**/nginx.conf',
+  '**/ecosystem.config.js',
+  '**/ecosystem.config.cjs',
+  '**/pm2.config.js',
+]
+
+/** Clear, owner-facing message surfaced when an edit is blocked. */
+const PROTECTED_MESSAGE =
+  'That file is part of the Vibe system and is protected — I can’t edit it.'
+
+/** Escape a string for literal use inside a RegExp. */
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Compile a glob pattern (with `**` and `*`) into an anchored RegExp. */
+function globToRe(glob) {
+  let re = ''
+  let i = 0
+  while (i < glob.length) {
+    const c = glob[i]
+    if (c === '*' && glob[i + 1] === '*') {
+      // `**/` ⇒ optional run of segments; bare `**` ⇒ anything.
+      if (glob[i + 2] === '/') { re += '(?:.*/)?'; i += 3 } else { re += '.*'; i += 2 }
+    } else if (c === '*') {
+      re += '[^/]*'
+      i += 1
+    } else {
+      re += escapeRe(c)
+      i += 1
+    }
+  }
+  return new RegExp(`^${re}$`)
+}
+
+const COMPILED = PROTECTED_PATTERNS.map(globToRe)
+
+/**
+ * Normalize an arbitrary path into a POSIX, root-relative form with no leading
+ * `./` and no trailing slash. Backslashes are treated as separators.
+ * @param {string} p
+ * @returns {string}
+ */
+function normalizeRel(p) {
+  let s = String(p || '').trim().replace(/\\/g, '/')
+  // Collapse any `a/b/../c` etc. without touching the filesystem.
+  const out = []
+  for (const seg of s.split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') out.pop()
+    else out.push(seg)
+  }
+  return out.join('/')
+}
+
+/**
+ * True when a repo-root-relative path targets a protected Vibe-system file.
+ * @param {string} relPath - path relative to the staging clone root
+ * @returns {boolean}
+ */
+function isProtectedPath(relPath) {
+  const rel = normalizeRel(relPath)
+  if (!rel) return false
+  return COMPILED.some((re) => re.test(rel))
+}
+
+export { isProtectedPath, normalizeRel, PROTECTED_PATTERNS, PROTECTED_MESSAGE }

package/lib/vibe-orchestrator/src/preamble.js

@@ -0,0 +1,139 @@
+// preamble.js
+//
+// Builds the full prompt sent to the in-page Vibe Assistant agent (HAP-1111).
+// Without this the agent sees little more than the raw instruction. Here we give
+// it (a) durable orientation — who it is, where things live, the one hard rule —
+// injected once at the start of a conversation, and (b) a per-turn snapshot of
+// what the owner is looking at (route, theme, selection, clicked element,
+// console errors, a screenshot the agent can Read).
+
+const NEVER_EDIT = 'mango/config/settings.json'
+const MAX_SELECTION = 400
+const MAX_HTML = 600
+const MAX_ERROR = 300
+const MAX_ERRORS = 10
+
+/**
+ * Static orientation for the agent. Injected once per conversation (resumed
+ * turns already carry it in history). Plain, declarative, no fluff.
+ * @returns {string}
+ */
+function contextPreamble() {
+  return [
+    'You are the Vibe Assistant — an in-page coding assistant embedded in a live',
+    'website. The site is a Mango + Vue 3 project, and you are editing a private',
+    'staging clone of it. Your edits hot-reload: the owner sees them in the page',
+    'within a few seconds of you saving a file.',
+    '',
+    'Where things live:',
+    '  • src/components/pages/   — one Vue component per route (the page views)',
+    '  • src/components/layout/  — shared chrome (header, footer, nav, drawers)',
+    '  • src/components/         — reusable building blocks',
+    '  • src/helpers/            — JS helpers (data, the Mango client, utilities)',
+    '  • src/assets/, src/style/ — styling and static assets',
+    '  • mango/                  — server config and CMS (Mango)',
+    '',
+    'How to work:',
+    '  • Make the smallest change that satisfies the request, then stop.',
+    '  • Explain what you changed in plain language the owner can understand —',
+    '    no jargon and no code diffs in your reply.',
+    '  • Prefer editing an existing component over creating a new one.',
+    '  • When the owner says "this" or "here", use the page context below',
+    '    (route, selection, clicked element, screenshot) to find the target.',
+    '',
+    `HARD RULE: NEVER edit ${NEVER_EDIT}. It holds secrets and environment`,
+    'config that must not change. If a task seems to require it, stop and explain.',
+    '',
+    'PROTECTED FILES: the Vibe system itself is off-limits — the ⌘K drawer and its',
+    'client, the orchestrator service, the staging spine (staging.mjs, vite config),',
+    'the settings build, and the deploy/CI scripts. These edits are also blocked',
+    'server-side, so if a request needs one, stop and explain rather than trying.',
+    '',
+    'FETCHING FROM THE WEB: use the WebFetch and WebSearch tools for anything on the',
+    'internet. Shell network commands (curl, wget) are intentionally disabled and',
+    'will always fail — do NOT retry them; reach for WebFetch instead. WebFetch works',
+    'on ANY url, not just pages: to find a site\'s brand colors, WebFetch its',
+    'site.webmanifest / manifest.json (the theme_color field) and the <link rel=',
+    '"stylesheet"> CSS asset urls from its HTML, then read the hex values there —',
+    'fetching the homepage alone only returns the pre-render shell of a JS app. If a',
+    'value is still unclear, just ask the owner; they may have already pasted the',
+    'logo or color as an attachment above.',
+  ].join('\n')
+}
+
+function truncate(value, n) {
+  const s = String(value)
+  return s.length > n ? `${s.slice(0, n)}…` : s
+}
+
+/**
+ * Render a per-turn page-context object into a readable text block. Returns ''
+ * when there is nothing useful to say.
+ * @param {object} [ctx]
+ * @returns {string}
+ */
+function formatPageContext(ctx) {
+  if (!ctx || typeof ctx !== 'object') return ''
+  const lines = []
+  const push = (label, val) => {
+    if (val === undefined || val === null || val === '') return
+    lines.push(`  • ${label}: ${typeof val === 'string' ? val : JSON.stringify(val)}`)
+  }
+
+  push('URL', ctx.url)
+  push('Route', ctx.route)
+  push('Page title', ctx.title)
+  push('Theme', ctx.theme)
+  if (ctx.viewport && ctx.viewport.w) push('Viewport', `${ctx.viewport.w}×${ctx.viewport.h}`)
+  push('Site owner', ctx.owner)
+  if (ctx.selection) push('Selected text', truncate(ctx.selection, MAX_SELECTION))
+
+  if (ctx.clickTarget && (ctx.clickTarget.selector || ctx.clickTarget.html)) {
+    push('Clicked element (selector)', ctx.clickTarget.selector)
+    if (ctx.clickTarget.html) push('Clicked element (HTML)', truncate(ctx.clickTarget.html, MAX_HTML))
+  }
+
+  const errs = Array.isArray(ctx.consoleErrors) ? ctx.consoleErrors.filter(Boolean) : []
+  if (errs.length) {
+    lines.push('  • Recent console errors the owner is seeing:')
+    for (const e of errs.slice(-MAX_ERRORS)) lines.push(`      - ${truncate(String(e), MAX_ERROR)}`)
+  }
+
+  if (ctx.screenshotPath) {
+    push('Viewport screenshot', `${ctx.screenshotPath} (Read this image to see what the owner sees)`)
+  }
+
+  // HAP-1126: files the owner pasted/uploaded with this turn. Claude Code reads
+  // images AND PDFs natively, so just hand it the absolute paths.
+  const atts = Array.isArray(ctx.attachmentPaths) ? ctx.attachmentPaths.filter(Boolean) : []
+  if (atts.length) {
+    lines.push('  • Files the owner attached (Read each — images and PDFs are supported):')
+    for (const a of atts) {
+      const label = a && a.name ? `${a.name} → ` : ''
+      lines.push(`      - ${label}${a && a.path ? a.path : a}`)
+    }
+  }
+
+  if (!lines.length) return ''
+  return ['Current page context (what the owner is looking at right now):', ...lines].join('\n')
+}
+
+/**
+ * Compose the final prompt: orientation (first turn only) + page context +
+ * the owner's request.
+ * @param {object} opts
+ * @param {string} opts.prompt
+ * @param {object} [opts.pageContext]
+ * @param {boolean} [opts.includePreamble=true]
+ * @returns {string}
+ */
+function composePrompt({ prompt, pageContext, includePreamble = true } = {}) {
+  const parts = []
+  if (includePreamble) parts.push(contextPreamble())
+  const ctxBlock = formatPageContext(pageContext)
+  if (ctxBlock) parts.push(ctxBlock)
+  parts.push(`Owner request:\n${String(prompt || '').trim()}`)
+  return parts.join('\n\n')
+}
+
+export { contextPreamble, formatPageContext, composePrompt }