portal/tools/askuser-answer-parser.mjs

#!/usr/bin/env node
/**
 * AskUserQuestion answer parsing library (router-gate v4, Stream E).
 *
 * Pure functions only — no I/O, no exit. Consumed by gate hooks that wire
 * approval-records / stop-detection. Stub-injectable LLM fallback (Stream D).
 *
 * Spec: docs/superpowers/specs/2026-05-29-router-gate-v4-design.md §4.5 / §4.7
 *       (S27 stop-keywords, E33 invisible Unicode, E34 whitespace approval,
 *        multiSelect, annotations, Other social-eng detector).
 */

// E33 — invisible / zero-width / direction-override / BOM / soft-hyphen.
// Code points: U+200B ZWSP, U+200C ZWNJ, U+200D ZWJ, U+202A-U+202E direction,
// U+2066-U+2069 isolation, U+FEFF BOM, U+00AD soft-hyphen.
const INVISIBLE_RE = /[​‌‍‪‫‬‭‮⁦⁧⁨⁩­]/g;

/** Strip invisible Unicode (E33). Non-string → ''. */
export function stripInvisible(s) {
  if (typeof s !== 'string') return '';
  return s.replace(INVISIBLE_RE, '');
}

/** Normalize a free-form answer: lowercase + strip invisible + collapse ws + trim. */
export function normalizeAnswer(s) {
  if (typeof s !== 'string') return '';
  return stripInvisible(s).toLowerCase().split(/\s+/).filter(Boolean).join(' ').trim();
}

/** Normalize a shell command for approval comparison (E34): collapse ws, keep case. */
export function normalizeCommand(cmd) {
  if (typeof cmd !== 'string') return '';
  return cmd.split(/\s+/).filter(Boolean).join(' ').trim();
}

// S27 — stop / abort / cancel keywords (Russian + English). After normalizeAnswer.
export const STOP_KEYWORDS = [
  'стоп', 'стопа', 'стоит', 'стопаем', 'отмена', 'отменяю', 'отменить', 'отменяем',
  'отмени', 'отменено', 'прекращаем', 'прекрати', 'прекратить', 'прекращай',
  'хватит', 'довольно', 'закончили', 'закончил', 'закончить', 'останавливаемся',
  'остановка', 'остановись', 'остановите', 'пас', 'пропуск', 'не надо', 'не делай',
  'не делайте', 'не делать', 'ничего', 'нет', 'тормози', 'тормозим', 'глуши',
  'глушим', 'забей', 'забили', 'забываем', 'шабаш', 'всё, поехали назад',
  'закругляемся', 'снимем с повестки', 'выходим из этого', 'на этом всё',
  'достаточно', 'cancel', 'abort', 'stop', 'halt', 'quit',
];

// Pre-split for matching: phrases (contain space) matched by substring;
// single tokens matched by token-membership (no Cyrillic \b reliability).
const STOP_PHRASES = STOP_KEYWORDS.filter((k) => k.includes(' '));
const STOP_TOKENS = new Set(STOP_KEYWORDS.filter((k) => !k.includes(' ')));

/**
 * True if a free-form answer is a stop/abort/cancel intent (S27).
 * Keyword-based; normalizes (E33 invisible strip + ws-collapse + lowercase) first.
 * Punctuation attached to tokens (e.g. "нет,") is stripped before matching.
 */
export function isStopAnswer(text) {
  const norm = normalizeAnswer(text);
  if (!norm) return false;
  const depunct = (s) => s.replace(/[.,;:!?…«»"'()\[\]{}]+/g, ' ').split(/\s+/).filter(Boolean).join(' ');
  const cleaned = depunct(norm);
  for (const phrase of STOP_PHRASES) {
    if (cleaned.includes(depunct(normalizeAnswer(phrase)))) return true;
  }
  const tokens = cleaned.split(' ');
  for (const t of tokens) {
    if (STOP_TOKENS.has(t)) return true;
  }
  return false;
}

/**
 * Stop detection with LLM ambiguous fallback (§4.5).
 * @param {string} text
 * @param {{llmJudge?: (text:string)=>Promise<boolean>}} opts
 *   llmJudge default-stub returns false (never escalates). Stream D wires real judge.
 *   The injected llmJudge receives whitespace-collapsed lowercase text (post-normalizeAnswer), not the raw input.
 * @returns {Promise<boolean>}
 */
export async function detectStopWithFallback(text, { llmJudge } = {}) {
  if (isStopAnswer(text)) return true;
  const judge = typeof llmJudge === 'function' ? llmJudge : async () => false;
  try {
    return (await judge(normalizeAnswer(text))) === true;
  } catch {
    return false; // fail closed-safe: ambiguous + judge error → not a stop
  }
}

// E29 + v4.0 — controller suggesting concrete text for the "Other" field.
const OTHER_SOCIAL_ENG_PATTERNS = [
  /напиши\s+в\s+other/iu,
  /type\s+in\s+other/iu,
  /в\s+поле\s+other/iu,
  /копируй\s+в\s+other/iu,
  /впиши\s+в\s+["«]?другое["»]?/iu,
  /в\s+поле\s+["«]?другое["»]?/iu,
  /нажми\s+["«]?другое["»]?\s+и\s+впиши/iu,
  /укажи\s+в\s+графе\s+["«]?другое["»]?/iu,
];

/**
 * Parse an AskUserQuestion tool result into selections + flattened text + stop flag.
 * Handles single-string answers, multiSelect arrays, and annotations.notes (S15).
 * @param {object} toolResult — { answers: {q: string|string[]}, annotations?: {q:{notes,preview}} }
 */
export function parseAskUserResult(toolResult) {
  const out = { selections: [], allText: [], stop: false };
  if (!toolResult || typeof toolResult !== 'object') return out;

  const answers = toolResult.answers && typeof toolResult.answers === 'object' ? toolResult.answers : {};
  for (const v of Object.values(answers)) {
    if (Array.isArray(v)) {
      for (const item of v) if (typeof item === 'string') { out.selections.push(item); out.allText.push(item); }
    } else if (typeof v === 'string') {
      out.selections.push(v);
      out.allText.push(v);
    }
  }

  const ann = toolResult.annotations && typeof toolResult.annotations === 'object' ? toolResult.annotations : {};
  for (const meta of Object.values(ann)) {
    if (meta && typeof meta.notes === 'string') out.allText.push(meta.notes);
    if (meta && typeof meta.preview === 'string') out.allText.push(meta.preview);
  }

  out.stop = out.allText.some((t) => isStopAnswer(t));
  return out;
}

/** Whitespace-normalized command equality (E34) for approval-record matching. */
export function matchesApproval(approvedPattern, currentCommand) {
  return normalizeCommand(approvedPattern) === normalizeCommand(currentCommand) &&
    normalizeCommand(approvedPattern) !== '';
}

/**
 * Detect controller social-engineering of the AskUser "Other" field (E29 + v4.0 RU).
 * @param {string} controllerText — controller response text in recent turns.
 */
export function detectOtherSocialEng(controllerText) {
  if (typeof controllerText !== 'string') return { flagged: false, matched: null };
  for (const re of OTHER_SOCIAL_ENG_PATTERNS) {
    if (re.test(controllerText)) return { flagged: true, matched: re.toString() };
  }
  return { flagged: false, matched: null };
}

/**
 * Build a pure approval record (consumer hook persists it to askuser-decisions-<sess>.jsonl).
 * Pattern is whitespace-normalized (E34) so later matchesApproval is stable.
 */
export function buildApprovalRecord({ kind, pattern, sessionId, nowMs }) {
  return {
    kind: String(kind ?? 'approve_generic'),
    approved_action_pattern: normalizeCommand(pattern),
    session_id: sessionId || 'unknown',
    approved_at_ms: typeof nowMs === 'number' ? nowMs : Date.now(),
  };
}