tity to carry multiple audiences without compromising safety, performance, or upgrade funnel design.

Core Solution

The wrapper architecture replaces fragile prompt constraints with a deterministic routing and middleware pipeline. The system operates in four distinct phases: request ingestion, mode routing, safety/context isolation, and foundation model invocation.

Architecture Decisions

1. Stateless Mode Router: Mode selection is resolved at the gateway level using explicit flags, not inferred from conversation history. This prevents accidental mode drift during long sessions.
2. Isolated Context Stores: Each mode maintains a separate conversation buffer. Switching modes resets the active context window, eliminating cross-mode contamination.
3. Middleware Safety Layer: Content filtering, tone enforcement, and tier limits are applied before the request reaches the foundation model. This shifts safety enforcement from probabilistic prompt compliance to deterministic code execution.
4. Capability Passthrough: The foundation model (Grok 4) receives full tool-use permissions. The wrapper does not downgrade model capabilities; it only constrains output tone and enforces access controls.

Implementation (TypeScript)

import { Grok4Client } from './clients/grok4';
import { ContextStore } from './storage/context';
import { SafetyMiddleware } from './middleware/safety';
import { TierManager } from './billing/tiers';

export interface PersonaMode {
  id: 'narrative' | 'unfiltered';
  label: string;
  maxContextTokens: number;
  safetyThreshold: 'strict' | 'standard';
}

export interface CompanionRequest {
  userId: string;
  mode: PersonaMode['id'];
  input: string;
  tier: 'free' | 'super';
}

export class PersonaGateway {
  private grokClient: Grok4Client;
  private contextStore: ContextStore;
  private safetyMiddleware: SafetyMiddleware;
  private tierManager: TierManager;

  constructor() {
    this.grokClient = new Grok4Client();
    this.contextStore = new ContextStore();
    this.safetyMiddleware = new SafetyMiddleware();
    this.tierManager = new TierManager();
  }

  async processRequest(req: CompanionRequest): Promise<string> {
    // 1. Validate tier limits before processing
    const tierCheck = await this.tierManager.validateSession(req.userId, req.tier, req.mode);
    if (!tierCheck.allowed) {
      throw new Error(`Tier limit reached: ${tierCheck.reason}`);
    }

    // 2. Resolve mode configuration
    const modeConfig = this.resolveMode(req.mode);

    // 3. Isolate context per mode
    const contextKey = `${req.userId}:${req.mode}`;
    const conversationHistory = await this.contextStore.get(contextKey);

    // 4. Apply safety middleware before model invocation
    const sanitizedInput = await this.safetyMiddleware.process(
      req.input,
      modeConfig.safetyThreshold
    );

    // 5. Invoke foundation model with full capabilities
    const response = await this.grokClient.generate({
      prompt: sanitizedInput,
      history: conversationHistory,
      tools: ['web_search', 'reasoning', 'image_generation'],
      maxTokens: modeConfig.maxContextTokens,
      temperature: req.mode === 'narrative' ? 0.7 : 0.9
    });

    // 6. Store updated context
    await this.contextStore.append(contextKey, {
      role: 'user', content: req.input
    }, {
      role: 'assistant', content: response.text
    });

    return response.text;
  }

  private resolveMode(modeId: PersonaMode['id']): PersonaMode {
    const modes: Record<PersonaMode['id'], PersonaMode> = {
      narrative: {
        id: 'narrative',
        label: 'Guided Storytelling',
        maxContextTokens: 4096,
        safetyThreshold: 'strict'
      },
      unfiltered: {
        id: 'unfiltered',
        label: 'Open Interaction',
        maxContextTokens: 8192,
        safetyThreshold: 'standard'
      }
    };
    return modes[modeId];
  }
}

Why This Structure Works

• Deterministic Routing: Mode flags are explicit. The system never guesses intent from user input, preventing accidental exposure to restricted modes.
• Context Isolation: By namespacing conversation history with ${userId}:${mode}, switching modes guarantees a clean slate. This eliminates prompt injection across behavioral boundaries.
• Middleware-First Safety: Safety rules execute before the foundation model receives the request. This reduces token waste on filtered outputs and ensures compliance even when the base model's default guardrails are permissive.
• Capability Preservation: The Grok 4 client receives full tool arrays. The wrapper does not strip reasoning or web access; it only applies tone constraints and tier limits at the edges.

Pitfall Guide

1. Prompt Contamination Across Modes

Explanation: Relying solely on system prompts to enforce mode boundaries causes behavioral bleed. Long conversations gradually overwrite initial constraints, especially when users test edge cases. Fix: Implement explicit context isolation per mode. Never share conversation buffers between behavioral states. Use middleware to rewrite or reject inputs that violate mode-specific tone rules before they reach the model.

2. Shared Session State Bleeding

Explanation: Storing all interactions in a single session object allows mode switches to inherit previous context, creating safety and UX inconsistencies. Fix: Namespace context keys by mode. Clear or archive buffers on mode transition. Maintain separate vector stores or memory layers if long-term recall is required per mode.

3. Misaligned Visual-Content Signaling

Explanation: A warm, child-friendly visual identity paired with an unfiltered mode creates cognitive dissonance and trust violations. Users expect visual cues to match content boundaries. Fix: Apply visual state changes (color shifts, UI overlays, explicit mode badges) when switching to restricted modes. Document the visual-language mapping in your design system and enforce it at the client level.

4. Friction Placement in Freemium Tiers

Explanation: Capping voice or narrative sessions mid-flow triggers disproportionate emotional friction compared to standard chatbot limits. Users perceive the interruption as a character failure, not a billing event. Fix: Place tier limits at natural narrative breakpoints. Use predictive session tracking to prompt upgrades before the cutoff occurs. Offer graceful degradation (e.g., text fallback) instead of hard termination.

5. Over-Reliance on Base Model Guardrails

Explanation: Assuming the foundation model's default safety filters will compensate for permissive persona definitions is a critical production error. Wrapper architectures concentrate safety responsibility in the middleware layer. Fix: Implement explicit safety middleware that validates tone, content boundaries, and age-appropriateness before model invocation. Treat base model guardrails as a secondary defense, not the primary control.

6. Ignoring Regulatory Hooks for Engagement Mechanics

Explanation: Affection scores, streak counters, and attachment-building mechanics face scrutiny under GDPR-K and youth safety frameworks. Deploying them without compliance hooks triggers audit failures. Fix: Expose configuration flags for engagement mechanics. Implement opt-in toggles, session duration limits, and data retention policies. Log engagement events separately from core conversation data to simplify compliance reporting.

Production Bundle

Action Checklist

• Define explicit mode configurations with safety thresholds and context limits
• Implement namespaced context storage to prevent cross-mode bleeding
• Build middleware layer for tone enforcement and tier validation
• Map visual UI states to behavioral modes at the client level
• Place freemium friction at natural narrative breakpoints, not mid-flow
• Expose compliance flags for engagement mechanics and data retention
• Test mode switching under adversarial inputs and long-session conditions
• Document safety responsibility boundaries between wrapper and foundation model

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Single-audience commercial app	Monolithic Prompt Wrapper	Simpler stack, lower infra overhead	Low
Multi-audience with strict safety separation	Structured Persona Gateway	Isolates context, enforces middleware rules	Medium
Regulated/children-focused product	Structured Persona Gateway + Device-Level Controls	Meets GDPR-K/UK Online Safety Act requirements	High
High-throughput/low-latency requirement	Dual-Model Routing	Predictable performance, no runtime prompt rewriting	High

Configuration Template

persona_gateway:
  modes:
    narrative:
      label: "Guided Storytelling"
      safety_threshold: "strict"
      max_context_tokens: 4096
      temperature: 0.7
      engagement_mechanics:
        affection_score: true
        streak_tracking: false
        data_retention_days: 30
    unfiltered:
      label: "Open Interaction"
      safety_threshold: "standard"
      max_context_tokens: 8192
      temperature: 0.9
      engagement_mechanics:
        affection_score: true
        streak_tracking: true
        data_retention_days: 90

  tiers:
    free:
      voice_session_limit_seconds: 120
      chat_length_multiplier: 1.0
      agent_capacity: "standard"
      media_generation: "restricted"
    super:
      voice_session_limit_seconds: null
      chat_length_multiplier: 5.0
      agent_capacity: "expert"
      media_generation: "full"

  safety_middleware:
    tone_enforcement: true
    prompt_injection_detection: true
    age_gate_verification: "ui_layer"
    compliance_hooks:
      gdpr_k: true
      uk_online_safety: true

Quick Start Guide

1. Initialize the Gateway: Deploy the PersonaGateway class with your foundation model client (Grok 4 or equivalent). Configure mode definitions and tier limits using the YAML template.
2. Set Up Context Storage: Provision a namespaced key-value store (Redis, DynamoDB, or PostgreSQL) for conversation buffers. Ensure keys follow the ${userId}:${mode} pattern.
3. Deploy Safety Middleware: Implement tone validation, prompt injection detection, and tier limit checks. Route all inbound requests through this layer before model invocation.
4. Connect Client UI: Expose mode-switching endpoints and visual state indicators. Implement breakpoint-based tier prompts instead of hard session cuts.
5. Validate with Adversarial Testing: Run cross-mode injection tests, long-session context drift checks, and tier limit boundary validations. Verify compliance hooks log engagement events separately from core data.