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.6 KB
Raw Blame
/**
 * Mercury Code's dynamic status verbs — the LLM layer over the keyword
 * engine (consumers live in core/agent.ts, channels/cli.ts + ui/App.tsx).
 * One tiny generateText call per session: after the session has progressed
 * enough to see the project's persona, the agent asks the model for a pool
 * of short -ing phrases describing the ACTUAL work ("Extracting the
 * parser", "Rerouting the auth flow") — never generic filler like
 * "building" or "noodling" for work that isn't happening.
 *
 * Cadence is deliberately rare (the user's explicit concern): first refresh
 * after the 2nd completed turn, then at most one per 5 turns. One failure
 * disables the LLM layer for the session (the keyword fallback is pushed
 * once) — no retry churn. The keyword engine remains the fallback and never
 * gets replaced by anything less specific.
 */

/** Completed turns before the first refresh (turn 1 is too thin a signal). */
export const FIRST_REFRESH_AFTER_TURNS = 2;

/** Minimum turns between two refreshes — the pool must not churn. */
export const REFRESH_INTERVAL_TURNS = 5;

const MIN_VERBS = 6;
const MAX_VERBS = 10;

export interface StatusVerbGateInput {
  /** Completed Mercury Code turns so far (1-based count, incremented before the call). */
  turnCount: number;
  /** A refresh is currently in flight. */
  inFlight: boolean;
  /** A previous refresh failed — the LLM layer is off for the session. */
  disabled: boolean;
}

export interface StatusVerbGate {
  refresh: boolean;
  reason: 'disabled' | 'too-early' | 'in-flight' | 'not-due' | 'due';
}

/**
 * Decide whether this turn's end should fire the one-shot LLM verb refresh.
 * Pure — the agent owns the counters; this only encodes the cadence.
 */
export function shouldRefreshStatusVerbs(input: StatusVerbGateInput): StatusVerbGate {
  if (input.disabled) return { refresh: false, reason: 'disabled' };
  if (input.inFlight) return { refresh: false, reason: 'in-flight' };
  if (input.turnCount < FIRST_REFRESH_AFTER_TURNS) return { refresh: false, reason: 'too-early' };
  // First refresh at exactly FIRST_REFRESH_AFTER_TURNS, then every REFRESH_INTERVAL_TURNS.
  const sinceAnchor = (input.turnCount - FIRST_REFRESH_AFTER_TURNS) % REFRESH_INTERVAL_TURNS;
  if (sinceAnchor !== 0) return { refresh: false, reason: 'not-due' };
  return { refresh: true, reason: 'due' };
}

export interface StatusVerbPromptInput {
  /** The last few user requests — the project's persona lives here. */
  userRequests: string[];
  /** Project directory name (e.g. "download-manager"). */
  projectName: string;
  /** Labels of recent tool steps, if any (what the agent has been doing). */
  recentActivity?: string[];
}

/**
 * Build the one-shot verb-generation prompt. The system prompt hard-codes the
 * contract; the user prompt carries only the session evidence (≤ a few
 * hundred tokens).
 */
export function buildStatusVerbPrompt(input: StatusVerbPromptInput): { system: string; prompt: string } {
  const system = [
    'You write the live status labels for an AI coding agent working in a project.',
    'Given the recent requests in the session, produce a pool of short status phrases describing what the agent is ACTUALLY doing in this session.',
    'Rules:',
    '- Each phrase: a present-participle verb (+ short object), 2-6 words, e.g. "Extracting the parser", "Rerouting the auth flow".',
    '- Only work that is actually happening in these requests. If nothing is being built, do NOT write "building" or "crafting" or "noodling".',
    '- Specific to this project and these requests — no generic filler, no metaphors, no emoji.',
    `- Exactly ${MIN_VERBS}-${MAX_VERBS} distinct phrases.`,
    '- Output ONLY a JSON array of strings, nothing else.',
  ].join('\n');
  const requests = input.userRequests.map((r, i) => `${i + 1}. ${r.slice(0, 240)}`).join('\n');
  const activity = input.recentActivity && input.recentActivity.length > 0
    ? `\nRecent activity: ${input.recentActivity.slice(-5).join('; ').slice(0, 300)}`
    : '';
  const prompt = `Project: ${input.projectName}\nRecent requests:\n${requests}${activity}`;
  return { system, prompt };
}

/**
 * Parse and validate the model output. Returns the verb pool, or null when
 * unusable (wrong shape, too few usable phrases, or generic/off-work words).
 * The pool is small (a few hundred bytes), so the caller pushes it verbatim.
 */
export function parseStatusVerbs(raw: string): string[] | null {
  const text = (raw ?? '').trim();
  const start = text.indexOf('[');
  const end = text.lastIndexOf(']');
  if (start === -1 || end === -1 || end <= start) return null;
  let parsed: unknown;
  try {
    parsed = JSON.parse(text.slice(start, end + 1));
  } catch {
    return null;
  }
  if (!Array.isArray(parsed)) return null;
  const verbs = parsed
    .filter((v): v is string => typeof v === 'string')
    .map((v) => v.trim().replace(/\.$/, ''))
    .filter((v) => {
      if (v.length < 4 || v.length > 48) return false;
      if (v.split(/\s+/).length > 6) return false; // ≤ 6 words per phrase
      return true;
    })
    .filter((v) => {
      const first = v.split(/\s+/)[0].toLowerCase();
      return first.endsWith('ing') && !GENERIC_FORBIDDEN.has(first);
    })
    // Case-insensitive dedupe, keep the first occurrence.
    .filter((v, i, all) => all.findIndex((o) => o.toLowerCase() === v.toLowerCase()) === i)
    .slice(0, MAX_VERBS);
  return verbs.length >= MIN_VERBS ? verbs : null;
}

/** Leading verbs that are exactly the generic filler the prompt forbids. */
const GENERIC_FORBIDDEN = new Set(['building', 'crafting', 'noodling', 'doodling', 'cooking', 'brewing', 'working', 'processing']);