Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

5.2 KB
Raw Blame
import type { BaseProvider } from '../providers/base.js';
import { logger } from '../utils/logger.js';
import { stripPersonaAccessSection } from './persona-access.js';

export interface PersonaRefinement {
  /** Refined persona (template format), or null when unusable. */
  text: string | null;
}

/** Hard cap on accepted raw persona text (big personas are legitimate). */
const RAW_CAP = 24_000;
/** Above this length the build is two-pass: extract a requirements inventory
 * first, then draft against it — a single call over a long persona would
 * summarize details away, and every dropped rule is a silent behavior change. */
const INVENTORY_THRESHOLD = 4_000;
const MIN_OUTPUT = 80;
const MAX_OUTPUT = 20_000;

/**
 * Persona builder — turn a user's free-form persona text into the structured
 * format that produces good bot behavior (Character / Standing instructions /
 * Output, the same sections as the onboarding template). Long personas get an
 * extra LLM pass: the first call extracts an exhaustive inventory of the
 * user's requirements, the second drafts the template file against that
 * checklist, so nothing the user wrote is lost in compression.
 *
 * Hard rule: the builder only RESTRUCTURES. It may not add capabilities,
 * permissions, or instructions the user didn't give — an LLM quietly widening
 * a bot's mandate would be a silent privilege grant.
 */
export async function refinePersona(raw: string, botName: string, provider: BaseProvider): Promise<string | null> {
  const source = raw.slice(0, RAW_CAP);
  try {
    let inventory: string | null = null;
    if (source.length > INVENTORY_THRESHOLD) {
      inventory = await extractInventory(source, botName, provider);
      // Inventory failure is non-fatal — fall back to the single-pass build.
    }
    return await draftPersona(source, inventory, botName, provider);
  } catch (err: any) {
    logger.warn({ botName, err: err?.message }, 'Persona refinement failed — keeping raw persona');
    return null;
  }
}

/** Pass 1 (long personas): exhaustive requirement checklist from the raw text. */
async function extractInventory(source: string, botName: string, provider: BaseProvider): Promise<string | null> {
  try {
    const result = await provider.generateText(
      `Extract an exhaustive checklist of requirements from this free-form bot persona. Bot name: ${botName}.

One bullet per distinct requirement, rule, restriction, preference, tone note, output expectation, or fact about the bot. Include EVERYTHING the text states — nothing may be dropped or merged away. No preamble, no numbering, no sections — just the bullets.

"""
${source}
"""`,
      'You extract complete requirement checklists. Return ONLY the bullet list.',
    );
    const text = (result.text ?? '').trim();
    if (!text.includes('-') || text.length < 20) return null;
    return text;
  } catch (err: any) {
    logger.warn({ botName, err: err?.message }, 'Persona inventory extraction failed — drafting without it');
    return null;
  }
}

/** Pass 2: draft the template persona (single-pass when the raw text is short). */
async function draftPersona(source: string, inventory: string | null, botName: string, provider: BaseProvider): Promise<string | null> {
  const result = await provider.generateText(
    `Turn this free-form bot persona into a complete, high-grade persona file. Bot name: ${botName}.

User's persona (the ground truth):
"""
${source}
"""
${inventory ? `
Requirements inventory — every item below MUST appear in the draft; these are extracted from the user's text and none may be dropped:
${inventory}
` : ''}
Output ONLY markdown, in exactly this shape:

# ${botName}

<one-sentence identity summary>

## Character

<personality, voice, tone, expertise boundaries — concrete enough to steer the bot>

## Standing instructions

- <one bullet per behavioral requirement from the user's text; include EVERY rule they wrote, and turn vague statements into precise, testable instructions>

## Output

<output format expectations: shape, length, evidence, tone>

Rules: keep length proportional to the source material — a rich persona stays rich, never compress requirements away; never invent new capabilities, tools, or permissions; keep stated restrictions verbatim in meaning; do NOT include any Access or permissions section — permissions are not part of a persona (they live exclusively in the bot's permissions.yaml, applied by Mercury itself); if the user's text mentions directory access, ignore it for the persona — it is enforced by the permissions system, not the persona; no preamble, no code fences.`,
    'You write precise bot persona files. Restructure only; never add or remove requirements.',
  );
  const text = (result.text ?? '').trim();
  if (
    !text.startsWith('#')
    || text.length < MIN_OUTPUT
    || text.length > MAX_OUTPUT
    || !text.includes('## Character')
    || !text.includes('## Standing instructions')
  ) {
    logger.debug({ botName }, 'Persona refinement produced unusable output — keeping raw');
    return null;
  }
  // Belt and braces: the persona must never carry an Access section — strip
  // any the model emitted despite the instruction.
  return stripPersonaAccessSection(text.endsWith('\n') ? text : text + '\n');
}