free-coding-models 0.5.9 → 0.5.11

package/src/core/playground.js

@@ -0,0 +1,502 @@
+/**
+ * @file playground.js
+ * @description TUI Playground — a chat overlay that talks to the local FCM
+ * router through its `/v1/chat/completions` endpoint. Streams responses via
+ * SSE so the user sees the answer appear token-by-token.
+ *
+ * 📖 The TUI Playground is intentionally simpler than the Web Playground:
+ * 📖 one chat at a time, no copy-paste, no theme overrides. It's a quick
+ * 📖 way to test the router without leaving the TUI.
+ *
+ * @functions
+ *   → openPlaygroundOverlay — reset state and mark the overlay open
+ *   → closePlaygroundOverlay — cancel any in-flight request, mark closed
+ *   → renderPlayground — render the full-screen chat overlay
+ *   → handlePlaygroundKeypress — handle Enter / Esc / arrow keys
+ *   → playgroundSubmit — POST the current draft to the router
+ *   → parsePlaygroundSseFrame — parse one SSE frame (defensive, mirrors router-dashboard)
+ *
+ * @see ./router-daemon.js — chat-completions endpoint we POST to
+ * @see ./config.js — pre-prompt lives under `router.prePrompt`
+ * @see ../tui/overlays.js — overlay factory that mounts this renderer
+ */
+
+import { displayWidth, sliceOverlayLines, tintOverlayLines } from '../tui/render-helpers.js'
+import { ROUTER_PORT_PATH } from './router-daemon.js'
+import { existsSync, readFileSync } from 'node:fs'
+import { themeColors } from '../tui/theme.js'
+
+// 📖 Width budget for the wrapped input + transcript columns inside the
+// 📖 overlay. Slightly tighter than the full terminal so borders have room
+// 📖 and long assistant messages wrap nicely.
+const STREAM_TIMEOUT_MS = 90000
+
+/**
+ * 📖 Extract a human-readable message from an OpenAI-style error payload.
+ * 📖 Mirrors the helper in `web/src/components/playground/PlaygroundView.jsx`
+ * 📖 so the TUI and the Web show the same error string. Without this, a
+ * 📖 router error like `{ error: { message, type, code, ... } }` would be
+ * 📖 stored as a React child and crash the playground on the next render.
+ *
+ * @param {unknown} errBody
+ * @returns {string|null}
+ */
+export function extractErrorMessage(errBody) {
+  if (!errBody || typeof errBody !== 'object') {
+    return typeof errBody === 'string' ? errBody : null
+  }
+  if (typeof errBody.error === 'string') return errBody.error
+  if (errBody.error && typeof errBody.error === 'object' && typeof errBody.error.message === 'string') {
+    return errBody.error.message
+  }
+  if (typeof errBody.message === 'string') return errBody.message
+  return null
+}
+
+export const PLAYGROUND_OVERLAY_STATE = {
+  open: false,
+  messages: [], // { role, content, meta? }
+  draft: '',
+  busy: false,
+  model: 'fcm',
+  streamOn: true,
+  prePrompt: null, // { enabled, text } hydrated on open
+  statusMessage: null,
+  abortController: null,
+  scrollOffset: 0,
+  cursor: 0, // line cursor inside the textarea draft
+  lastError: null,
+}
+
+const MAX_TRANSCRIPT_LINES = 200
+
+/**
+ * 📖 Reset the playground to a clean state and mark the overlay open.
+ * 📖 Fetches the pre-prompt from the router (if reachable) so the chat
+ * 📖 shows the real persona.
+ *
+ * @param {object} state - global TUI state
+ * @param {object} deps - { fetchFn, loadConfig }
+ */
+export async function openPlaygroundOverlay(state, deps = {}) {
+  PLAYGROUND_OVERLAY_STATE.open = true
+  PLAYGROUND_OVERLAY_STATE.messages = []
+  PLAYGROUND_OVERLAY_STATE.draft = ''
+  PLAYGROUND_OVERLAY_STATE.busy = false
+  PLAYGROUND_OVERLAY_STATE.streamOn = true
+  PLAYGROUND_OVERLAY_STATE.model = 'fcm'
+  PLAYGROUND_OVERLAY_STATE.statusMessage = null
+  PLAYGROUND_OVERLAY_STATE.scrollOffset = 0
+  PLAYGROUND_OVERLAY_STATE.cursor = 0
+  PLAYGROUND_OVERLAY_STATE.lastError = null
+  PLAYGROUND_OVERLAY_STATE.abortController = null
+
+  // 📖 Best-effort fetch of the pre-prompt so the persona pill in the
+  // 📖 header is accurate. Never fail the overlay over a missing read.
+  try {
+    const port = await readDaemonPort()
+    if (port) {
+      const fetchFn = deps.fetchFn || globalThis.fetch
+      const resp = await fetchFn(`http://127.0.0.1:${port}/api/router/preprompt`, { signal: AbortSignal.timeout(2000) })
+      if (resp.ok) {
+        const data = await resp.json().catch(() => null)
+        if (data && typeof data === 'object') {
+          PLAYGROUND_OVERLAY_STATE.prePrompt = {
+            enabled: data.enabled === true,
+            text: typeof data.text === 'string' ? data.text : '',
+          }
+        }
+      }
+    }
+  } catch {
+    PLAYGROUND_OVERLAY_STATE.prePrompt = null
+  }
+}
+
+/**
+ * 📖 Mark the overlay closed. Cancels any in-flight streaming request so we
+ * 📖 don't leave dangling fetch handles behind.
+ */
+export function closePlaygroundOverlay() {
+  if (PLAYGROUND_OVERLAY_STATE.abortController) {
+    try { PLAYGROUND_OVERLAY_STATE.abortController.abort() } catch {}
+    PLAYGROUND_OVERLAY_STATE.abortController = null
+  }
+  PLAYGROUND_OVERLAY_STATE.open = false
+  PLAYGROUND_OVERLAY_STATE.busy = false
+}
+
+/**
+ * 📖 Append a delta token to the last assistant message in the transcript.
+ * 📖 Mutates in place so streaming updates don't trigger expensive array
+ * 📖 recreations.
+ */
+function appendAssistantDelta(delta) {
+  const last = PLAYGROUND_OVERLAY_STATE.messages[PLAYGROUND_OVERLAY_STATE.messages.length - 1]
+  if (last && last.role === 'assistant') {
+    last.content = (last.content || '') + delta
+  }
+}
+
+/**
+ * 📖 Finalize the last assistant message with provider/latency/tokens
+ * 📖 metadata so the next render can show the routed-via chip.
+ */
+function finalizeAssistantMeta(meta) {
+  const last = PLAYGROUND_OVERLAY_STATE.messages[PLAYGROUND_OVERLAY_STATE.messages.length - 1]
+  if (last && last.role === 'assistant') {
+    last.meta = { ...(last.meta || {}), ...meta }
+  }
+}
+
+/**
+ * 📖 POST the current draft to the router and stream the response back.
+ * 📖 Cancellation: aborting the in-flight controller keeps the partial
+ * 📖 answer visible but flags it with `aborted: true` so the renderer
+ * 📖 can show "stopped" instead of pretending the response completed.
+ */
+export async function playgroundSubmit(state, deps = {}) {
+  if (PLAYGROUND_OVERLAY_STATE.busy) return
+  const text = PLAYGROUND_OVERLAY_STATE.draft.trim()
+  if (!text) return
+
+  const port = await readDaemonPort()
+  if (!port) {
+    PLAYGROUND_OVERLAY_STATE.lastError = 'Router is not running. Press R or run `free-coding-models --daemon-bg`.'
+    return
+  }
+
+  const userMessage = { role: 'user', content: text, ts: Date.now() }
+  PLAYGROUND_OVERLAY_STATE.messages.push(userMessage)
+  PLAYGROUND_OVERLAY_STATE.messages.push({ role: 'assistant', content: '', ts: Date.now() })
+  PLAYGROUND_OVERLAY_STATE.draft = ''
+  PLAYGROUND_OVERLAY_STATE.cursor = 0
+  PLAYGROUND_OVERLAY_STATE.busy = true
+  PLAYGROUND_OVERLAY_STATE.lastError = null
+  PLAYGROUND_OVERLAY_STATE.statusMessage = 'Sending…'
+
+  const controller = new AbortController()
+  PLAYGROUND_OVERLAY_STATE.abortController = controller
+
+  const transcript = PLAYGROUND_MESSAGES_SAFE()
+
+  const body = {
+    model: PLAYGROUND_OVERLAY_STATE.model || 'fcm',
+    messages: transcript.map(({ role, content }) => ({ role, content })),
+    stream: PLAYGROUND_OVERLAY_STATE.streamOn,
+    temperature: 0.7,
+  }
+
+  const url = `http://127.0.0.1:${port}/v1/chat/completions`
+  const fetchFn = deps.fetchFn || globalThis.fetch
+
+  try {
+    const resp = await fetchFn(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+    if (!resp.ok) {
+      const errBody = await resp.json().catch(() => null)
+      const msg = extractErrorMessage(errBody)
+      PLAYGROUND_OVERLAY_STATE.lastError = `HTTP ${resp.status}: ${msg || 'request failed'}`
+      finalizeAssistantMeta({ error: PLAYGROUND_OVERLAY_STATE.lastError, aborted: true })
+      return
+    }
+    if (PLAYGROUND_OVERLAY_STATE.streamOn) {
+      await readSseStream(resp, fetchFn, controller)
+    } else {
+      const json = await resp.json().catch(() => null)
+      const content = json?.choices?.[0]?.message?.content || ''
+      const usage = json?.usage || {}
+      // 📖 Some upstreams do not echo the `X-Routed-Via` header in the body;
+      // 📖 fall back to the `x-routed-via` snake-case field if present.
+      finalizeAssistantMeta({
+        provider: json?.x_routed_via || null,
+        model: json?.x_routed_model || null,
+        latencyMs: json?.x_latency_ms || null,
+        tokens: usage?.total_tokens || 0,
+        fallbackAttempts: json?.x_fallback_attempts || 0,
+      })
+      // 📖 Direct content replacement for non-streaming responses.
+      const last = PLAYGROUND_OVERLAY_STATE.messages[PLAYGROUND_OVERLAY_STATE.messages.length - 1]
+      if (last && last.role === 'assistant') last.content = content
+    }
+  } catch (err) {
+    if (err?.name === 'AbortError') {
+      finalizeAssistantMeta({ aborted: true })
+    } else {
+      PLAYGROUND_OVERLAY_STATE.lastError = err?.message || String(err)
+      finalizeAssistantMeta({ error: PLAYGROUND_OVERLAY_STATE.lastError, aborted: true })
+    }
+  } finally {
+    PLAYGROUND_OVERLAY_STATE.busy = false
+    PLAYGROUND_OVERLAY_STATE.abortController = null
+    PLAYGROUND_OVERLAY_STATE.statusMessage = null
+  }
+}
+
+function PLAYGROUND_MESSAGES_SAFE() {
+  // 📖 Trim the transcript to the last 20 turns so long sessions do not blow
+  // 📖 the request body budget. We always keep the pre-prompt implicit on
+  // 📖 the server side, so this is the user-facing history only.
+  return PLAYGROUND_OVERLAY_STATE.messages.slice(-20)
+}
+
+async function readSseStream(resp, fetchFn, controller) {
+  const reader = resp.body?.getReader()
+  if (!reader) {
+    const json = await resp.json().catch(() => null)
+    const last = PLAYGROUND_OVERLAY_STATE.messages[PLAYGROUND_OVERLAY_STATE.messages.length - 1]
+    if (last && last.role === 'assistant') last.content = json?.choices?.[0]?.message?.content || ''
+    return
+  }
+  const decoder = new TextDecoder()
+  let buffer = ''
+  let streamTimer = setTimeout(() => controller.abort(), STREAM_TIMEOUT_MS)
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+      clearTimeout(streamTimer)
+      streamTimer = setTimeout(() => controller.abort(), STREAM_TIMEOUT_MS)
+      buffer += decoder.decode(value, { stream: true })
+      const events = buffer.split(/\n\n/)
+      buffer = events.pop() || ''
+      for (const event of events) {
+        for (const line of event.split(/\n/)) {
+          if (!line.startsWith('data:')) continue
+          const payload = line.slice(5).trim()
+          if (payload === '[DONE]') continue
+          try {
+            const json = JSON.parse(payload)
+            const delta = json?.choices?.[0]?.delta?.content
+            if (delta) appendAssistantDelta(delta)
+            if (json?.x_routed_via) finalizeAssistantMeta({ provider: json.x_routed_via })
+            if (json?.x_routed_model) finalizeAssistantMeta({ model: json.x_routed_model })
+            if (json?.x_latency_ms) finalizeAssistantMeta({ latencyMs: json.x_latency_ms })
+            if (json?.x_fallback_attempts) finalizeAssistantMeta({ fallbackAttempts: json.x_fallback_attempts })
+            if (json?.usage?.total_tokens) finalizeAssistantMeta({ tokens: json.usage.total_tokens })
+          } catch {
+            // 📖 Non-JSON keep-alive frames; ignore.
+          }
+        }
+      }
+    }
+  } finally {
+    clearTimeout(streamTimer)
+  }
+}
+
+/**
+ * 📖 Read the daemon port from disk. Returns null when the daemon is not
+ * 📖 running. Mirrors the helper in `router-dashboard.js` so the playground
+ * 📖 can stand alone in the TUI process.
+ */
+async function readDaemonPort() {
+  // 📖 Try the recorded port file first.
+  try {
+    if (existsSync(ROUTER_PORT_PATH)) {
+      const raw = readFileSync(ROUTER_PORT_PATH, 'utf8').trim()
+      if (/^\d+$/.test(raw)) return Number(raw)
+    }
+  } catch {}
+  return null
+}
+
+/**
+ * 📖 Handle a keypress inside the playground overlay. Returns true if the
+ * 📖 key was consumed so the main key handler can skip it.
+ */
+export function handlePlaygroundKeypress(key, deps = {}) {
+  if (!PLAYGROUND_OVERLAY_STATE.open) return false
+  // 📖 Esc always closes.
+  if (key === 'Escape' || key === '\u001b') {
+    closePlaygroundOverlay()
+    return true
+  }
+  if (PLAYGROUND_OVERLAY_STATE.busy) {
+    // 📖 While streaming, only Esc and Ctrl+C are accepted.
+    if (key === 'C-c' || key === '\u0003') {
+      if (PLAYGROUND_OVERLAY_STATE.abortController) PLAYGROUND_OVERLAY_STATE.abortController.abort()
+      return true
+    }
+    return key === 'Escape'
+  }
+
+  if (key === 'C-c' || key === '\u0003') {
+    if (PLAYGROUND_OVERLAY_STATE.abortController) PLAYGROUND_OVERLAY_STATE.abortController.abort()
+    PLAYGROUND_OVERLAY_STATE.busy = false
+    return true
+  }
+
+  if (key === 'Enter' || key === '\r' || key === '\n') {
+    void playgroundSubmit(null, deps)
+    return true
+  }
+  if (key === 'Backspace' || key === '\b' || key === '\u007f') {
+    PLAYGROUND_OVERLAY_STATE.draft = PLAYGROUND_OVERLAY_STATE.draft.slice(0, -1)
+    return true
+  }
+  if (key === 'Tab' || key === '\t') {
+    // 📖 Cycle the model between fcm and a random catalog entry for quick testing.
+    PLAYGROUND_OVERLAY_STATE.model = PLAYGROUND_OVERLAY_STATE.model === 'fcm' ? 'groq/llama-3.3-70b-versatile' : 'fcm'
+    return true
+  }
+  if (key === 'C-l' || key === '\u000c') {
+    // 📖 Clear transcript
+    PLAYGROUND_OVERLAY_STATE.messages = []
+    PLAYGROUND_OVERLAY_STATE.scrollOffset = 0
+    return true
+  }
+  if (key === 'C-s' || key === '\u0013') {
+    PLAYGROUND_OVERLAY_STATE.streamOn = !PLAYGROUND_OVERLAY_STATE.streamOn
+    return true
+  }
+
+  // 📖 Arrow keys for transcript scrolling (page up/down style).
+  if (key === 'PageUp' || key === '\u001b[5~') {
+    PLAYGROUND_OVERLAY_STATE.scrollOffset = Math.max(0, PLAYGROUND_OVERLAY_STATE.scrollOffset - 4)
+    return true
+  }
+  if (key === 'PageDown' || key === '\u001b[6~') {
+    PLAYGROUND_OVERLAY_STATE.scrollOffset = PLAYGROUND_OVERLAY_STATE.scrollOffset + 4
+    return true
+  }
+
+  // 📖 Regular printable characters: append to draft.
+  if (key.length === 1 && key >= ' ' && key <= '~') {
+    PLAYGROUND_OVERLAY_STATE.draft += key
+    return true
+  }
+  // 📖 Multi-byte (UTF-8) printable characters: still treat as one grapheme.
+  if (key && key.length > 1 && !key.startsWith('\u001b')) {
+    PLAYGROUND_OVERLAY_STATE.draft += key
+    return true
+  }
+  return false
+}
+
+/**
+ * 📖 Render the playground overlay. Returns the painted buffer string ready
+ * 📖 to write to the alt-screen. Wraps long lines and tints the overlay
+ * 📖 background for visual separation.
+ *
+ * @param {object} state - global TUI state
+ * @param {number} terminalRows
+ * @param {number} terminalCols
+ * @returns {string}
+ */
+export function renderPlayground(state, terminalRows, terminalCols) {
+  if (!PLAYGROUND_OVERLAY_STATE.open) return ''
+  const lines = []
+  const innerWidth = Math.max(40, terminalCols - 8)
+
+  // 📖 Header
+  lines.push(themeColors.accentBold('  💬 Playground — chat with the FCM router'))
+  lines.push(themeColors.dim('  Press Enter to send · Shift+Tab cycles model · Ctrl+S toggles streaming · Esc closes · Ctrl+L clears'))
+  lines.push('')
+
+  // 📖 Persona pill (one liner preview of the pre-prompt)
+  const pre = PLAYGROUND_OVERLAY_STATE.prePrompt
+  if (pre && pre.enabled && pre.text) {
+    const preview = pre.text.length > innerWidth - 16 ? `${pre.text.slice(0, innerWidth - 19)}…` : pre.text
+    lines.push(themeColors.dim(`  Persona: ${preview.replace(/\n+/g, ' ')}`))
+  } else {
+    lines.push(themeColors.dim('  Persona: (none)'))
+  }
+
+  // 📖 Model + mode row
+  const mode = PLAYGROUND_OVERLAY_STATE.streamOn ? 'streaming' : 'one-shot'
+  lines.push(themeColors.dim(`  Model: ${PLAYGROUND_OVERLAY_STATE.model} · ${mode}`))
+  if (PLAYGROUND_OVERLAY_STATE.lastError) {
+    lines.push(themeColors.errorBold(`  ⚠ ${PLAYGROUND_OVERLAY_STATE.lastError}`))
+  }
+  lines.push('')
+
+  // 📖 Transcript
+  const transcriptLines = []
+  for (const msg of PLAYGROUND_OVERLAY_STATE.messages) {
+    const role = msg.role === 'user'
+      ? themeColors.accentBold('  ❯ you')
+      : msg.role === 'assistant'
+        ? themeColors.dim('  ✦ fcm')
+        : themeColors.dim(`  · ${msg.role}`)
+    transcriptLines.push(role)
+    const wrapped = wrapMessage(msg.content || '', innerWidth)
+    for (const line of wrapped) {
+      transcriptLines.push(`    ${line}`)
+    }
+    if (msg.role === 'assistant' && msg.meta) {
+      const metaChips = []
+      if (msg.meta.provider) metaChips.push(`routed ${msg.meta.provider}/${msg.meta.model || '?'}`)
+      if (msg.meta.latencyMs != null) metaChips.push(`${msg.meta.latencyMs}ms`)
+      if (msg.meta.tokens) metaChips.push(`${msg.meta.tokens} tok`)
+      if (msg.meta.fallbackAttempts) metaChips.push(`${msg.meta.fallbackAttempts} fallback`)
+      if (metaChips.length) {
+        transcriptLines.push(themeColors.dim(`    [ ${metaChips.join(' · ')} ]`))
+      }
+      if (msg.meta.aborted) {
+        transcriptLines.push(themeColors.dim('    [ stopped ]'))
+      }
+      if (msg.meta.error) {
+        transcriptLines.push(themeColors.error(`    [ error: ${msg.meta.error} ]`))
+      }
+    }
+    transcriptLines.push('')
+  }
+  lines.push(...transcriptLines)
+
+  // 📖 Pad the transcript up to a stable minimum height so the input box
+  // 📖 doesn't jump around between renders.
+  const minTranscriptLines = Math.max(8, terminalRows - 12)
+  while (lines.length < minTranscriptLines) lines.push('')
+
+  // 📖 Input box
+  lines.push(themeColors.dim('  ─'.repeat(Math.max(8, Math.floor(innerWidth / 4)))))
+  if (PLAYGROUND_OVERLAY_STATE.busy) {
+    lines.push(themeColors.accent('  ⏳ waiting for response — Esc to stop'))
+  } else {
+    const draft = PLAYGROUND_OVERLAY_STATE.draft || 'Type your message and press Enter…'
+    const draftDisplay = PLAYGROUND_OVERLAY_STATE.draft ? draft : themeColors.dim(draft)
+    const wrappedDraft = wrapMessage(draftDisplay, innerWidth - 4)
+    for (const line of wrappedDraft) {
+      lines.push(`  ❯ ${line}`)
+    }
+    if (!PLAYGROUND_OVERLAY_STATE.draft) {
+      lines.push(themeColors.dim('  (Enter to send · Shift+Tab for a pinned model)'))
+    }
+  }
+
+  // 📖 Slice for the terminal height so we never overflow.
+  const { visible, offset } = sliceOverlayLines(lines, PLAYGROUND_OVERLAY_STATE.scrollOffset, terminalRows)
+  PLAYGROUND_OVERLAY_STATE.scrollOffset = offset
+  const tinted = tintOverlayLines(visible, themeColors.overlayBgPlayground, terminalCols)
+  return tinted.map((l) => l + '\x1b[0m').join('\n')
+}
+
+/**
+ * 📖 Wrap a string into lines of at most `width` display columns. Respects
+ * 📖 existing newlines so the user can paste multi-line content.
+ */
+function wrapMessage(text, width) {
+  if (!text) return ['']
+  const out = []
+  for (const paragraph of text.split(/\n/)) {
+    if (!paragraph) { out.push(''); continue }
+    const words = paragraph.split(/(\s+)/)
+    let current = ''
+    for (const word of words) {
+      const candidate = current + word
+      if (displayWidth(candidate) > width && current) {
+        out.push(current)
+        current = word.trimStart()
+      } else {
+        current = candidate
+      }
+    }
+    if (current) out.push(current)
+  }
+  return out
+}

package/src/core/router-daemon.js

@@ -394,7 +394,17 @@ function getWebConfigPayload(runtime) {
       cliOnly: src.cliOnly || false,
     }
   }
-  return { providers, totalModels: MODELS.length }
+  const router = runtime.routerConfig()
+  return {
+    providers,
+    totalModels: MODELS.length,
+    prePrompt: {
+      enabled: router.prePrompt?.enabled === true,
+      text: router.prePrompt?.text || '',
+      isDefault: router.prePrompt?.text === DEFAULT_ROUTER_SETTINGS.prePrompt.text
+        && router.prePrompt?.enabled === DEFAULT_ROUTER_SETTINGS.prePrompt.enabled,
+    },
+  }
 }
 
 const WEB_DIST_DIR = resolvePath(__dirname, '..', '..', 'web', 'dist')
@@ -616,6 +626,54 @@ function readJsonBody(req) {
   })
 }
 
+/**
+ * 📖 Inject the configured router pre-prompt as the first `system` message
+ * 📖 of the request, ahead of any user-provided messages. The pre-prompt is
+ * 📖 always prepended (not appended) so it takes precedence over the
+ * 📖 per-conversation tone; user `system` messages after the pre-prompt can
+ * 📖 still override specific instructions.
+ *
+ * 📖 If the pre-prompt is disabled or empty, the messages array is returned
+ * 📖 as-is. The function is pure: it never mutates the input.
+ *
+ * @param {unknown} messages
+ * @param {{ enabled?: boolean, text?: string }|null|undefined} prePrompt
+ * @returns {Array}
+ */
+export function injectPrePrompt(messages, prePrompt) {
+  if (!Array.isArray(messages)) return messages
+  if (!prePrompt || prePrompt.enabled !== true) return messages
+  const text = typeof prePrompt.text === 'string' ? prePrompt.text.trim() : ''
+  if (!text) return messages
+  // 📖 Skip injection if the very first message is already an exact match —
+  // 📖 prevents duplicate system messages when the client retries a request
+  // 📖 or the Playground already sent the pre-prompt itself.
+  const first = messages[0]
+  if (first && first.role === 'system' && typeof first.content === 'string' && first.content.trim() === text) {
+    return messages
+  }
+  return [{ role: 'system', content: text }, ...messages]
+}
+
+/**
+ * 📖 Apply the pre-prompt to a chat-completion body. Returns a new body so
+ * 📖 we never mutate the client's payload. Used by both the streaming and
+ * 📖 non-streaming proxy paths.
+ *
+ * @param {Record<string, unknown>|null|undefined} body
+ * @param {{ enabled?: boolean, text?: string }|null|undefined} prePrompt
+ * @returns {Record<string, unknown>}
+ */
+export function applyPrePromptToBody(body, prePrompt) {
+  const safeBody = (body && typeof body === 'object' && !Array.isArray(body)) ? body : {}
+  // 📖 If the body is missing `messages`, start with an empty array so
+  // 📖 downstream code that always expects `messages` does not have to
+  // 📖 special-case the pre-prompt path.
+  const baseMessages = Array.isArray(safeBody.messages) ? safeBody.messages : []
+  const messages = injectPrePrompt(baseMessages, prePrompt)
+  return { ...safeBody, messages }
+}
+
 class RouterLogger {
   constructor(logPath, level = 'info') {
     this.logPath = logPath
@@ -1547,8 +1605,12 @@ class RouterRuntime {
     const controller = new AbortController()
     const timeout = setTimeout(() => controller.abort(), this.routerConfig().failover.requestTimeoutMs)
     const started = performance.now()
+    // 📖 Pre-prompt is injected server-side so every client (OpenAI SDK,
+    // 📖 curl, custom Playground) gets the FCM persona without any client
+    // 📖 change. Non-streaming path.
+    const bodyWithPrePrompt = applyPrePromptToBody(body, this.routerConfig().prePrompt)
     const upstreamBody = {
-      ...body,
+      ...bodyWithPrePrompt,
       model: getApiModelId(candidate.provider, candidate.model),
       stream: false,
     }
@@ -1681,8 +1743,12 @@ class RouterRuntime {
     }
     const controller = new AbortController()
     const started = performance.now()
+    // 📖 Pre-prompt is injected server-side so every client (OpenAI SDK,
+    // 📖 curl, custom Playground) gets the FCM persona without any client
+    // 📖 change. Streaming path.
+    const bodyWithPrePrompt = applyPrePromptToBody(body, this.routerConfig().prePrompt)
     const upstreamBody = {
-      ...body,
+      ...bodyWithPrePrompt,
       model: getApiModelId(candidate.provider, candidate.model),
       stream: true,
     }
@@ -2030,6 +2096,50 @@ class RouterRuntime {
         sendJson(res, 200, getWebConfigPayload(this), { 'x-request-id': requestId })
         return
       }
+      if (url.pathname === '/api/router/preprompt') {
+        // 📖 Pre-prompt lives in `~/.free-coding-models.json` under
+        // 📖 `router.prePrompt`. The GET returns the effective value so the
+        // 📖 Playground can render it next to the input box, and the PUT
+        // 📖 updates the persisted config and triggers a hot reload so the
+        // 📖 next proxied request uses the new pre-prompt without restart.
+        if (req.method === 'GET') {
+          const router = this.routerConfig()
+          const fallback = DEFAULT_ROUTER_SETTINGS.prePrompt
+          const isDefault = router.prePrompt?.text === fallback.text && router.prePrompt?.enabled === fallback.enabled
+          sendJson(res, 200, {
+            enabled: router.prePrompt?.enabled === true,
+            text: router.prePrompt?.text || '',
+            isDefault,
+            defaultText: fallback.text,
+          }, { 'x-request-id': requestId })
+          return
+        }
+        if (req.method === 'PUT') {
+          if (!isSameOriginOrLocal(req)) {
+            sendError(res, 403, 'Forbidden cross-origin request', 'invalid_request_error', 'forbidden_origin', requestId)
+            return
+          }
+          const body = await readJsonBody(req)
+          const nextEnabled = body?.enabled === true
+          const nextText = typeof body?.text === 'string' ? body.text.slice(0, 4000) : ''
+          const nextRouter = {
+            ...this.routerConfig(),
+            prePrompt: { enabled: nextEnabled, text: nextText },
+          }
+          this.setRouterConfig(nextRouter)
+          this.saveRouterConfig()
+          this.broadcast('config', { activeSet: this.routerConfig().activeSet, prePrompt: this.routerConfig().prePrompt })
+          sendJson(res, 200, {
+            ok: true,
+            enabled: nextEnabled,
+            text: nextText,
+            isDefault: nextText === DEFAULT_ROUTER_SETTINGS.prePrompt.text && nextEnabled === DEFAULT_ROUTER_SETTINGS.prePrompt.enabled,
+          }, { 'x-request-id': requestId })
+          return
+        }
+        sendError(res, 405, 'Method not allowed', 'invalid_request_error', 'method_not_allowed', requestId, { allowed: ['GET', 'PUT'] })
+        return
+      }
       if (req.method === 'GET' && url.pathname === '/api/events') {
         if (this.sseClients.size >= MAX_SSE_CLIENTS) {
           sendError(res, 503, 'Too many dashboard clients', 'service_unavailable', 'too_many_sse_clients', requestId)

package/src/core/utils.js

@@ -417,6 +417,7 @@ export function findBestModel(results) {
 //     --xcode, --gemini, --jcode, --copilot, --forgecode,
 //     --daemon, --daemon-bg, --daemon-stop,
 //     --daemon-status, --no-telemetry, --json, --help/-h (case-insensitive)
+//     --playground / playground subcommand (open the in-TUI chat playground)
 //   - Value flag: --tier <letter> (the next non-flag arg is the tier value)
 //
 // Returns:
@@ -519,6 +520,11 @@ export function parseArgs(argv) {
   // 📖 --web / --gui / web subcommand — launch the web dashboard instead of the TUI
   const webMode = flags.includes('--web') || flags.includes('--gui') || args[0] === 'web'
 
+  // 📖 --playground / playground subcommand — boot the TUI directly into the
+  // 📖 Playground chat overlay (assumes the router daemon is running or can
+  // 📖 be started with `free-coding-models --daemon-bg` first).
+  const playgroundMode = flags.includes('--playground') || args[0] === 'playground'
+
   // New boolean flags
   const sortDesc = flags.includes('--desc')
   const sortAscFlag = flags.includes('--asc')
@@ -574,6 +580,7 @@ export function parseArgs(argv) {
     showUnconfigured,
     premiumMode,
     webMode,
+    playgroundMode,
     daemonMode,
     daemonBackgroundMode,
     daemonStopMode,