winter-super-cli 2026.5.25 → 2026.5.27

package/src/cli/conversation-format.js

@@ -0,0 +1,253 @@
+export function formatAnswerFooter(startedAt, usage = {}, now = Date.now()) {
+  const elapsedMs = Math.max(0, now - startedAt);
+  const seconds = (elapsedMs / 1000).toFixed(elapsedMs < 10000 ? 1 : 0);
+  const tokenText = formatUsage(usage);
+  return tokenText ? `Time: ${seconds}s · Tokens: ${tokenText}` : `Time: ${seconds}s · Tokens: n/a`;
+}
+
+export function addUsage(totalUsage, usage = {}) {
+  if (!usage || typeof usage !== 'object') return totalUsage;
+
+  const prompt = usage.prompt_tokens ?? usage.input_tokens;
+  const completion = usage.completion_tokens ?? usage.output_tokens;
+  const total = usage.total_tokens ?? (
+    typeof prompt === 'number' || typeof completion === 'number'
+      ? (prompt || 0) + (completion || 0)
+      : undefined
+  );
+
+  if (typeof prompt === 'number') {
+    totalUsage.prompt_tokens = (totalUsage.prompt_tokens || 0) + prompt;
+  }
+  if (typeof completion === 'number') {
+    totalUsage.completion_tokens = (totalUsage.completion_tokens || 0) + completion;
+  }
+  if (typeof total === 'number') {
+    totalUsage.total_tokens = (totalUsage.total_tokens || 0) + total;
+  }
+
+  return totalUsage;
+}
+
+export function formatUsage(usage = {}) {
+  const prompt = usage.prompt_tokens;
+  const completion = usage.completion_tokens;
+  const total = usage.total_tokens;
+
+  if (typeof total === 'number' && typeof prompt === 'number' && typeof completion === 'number') {
+    return `${total} total (${prompt} in, ${completion} out)`;
+  }
+  if (typeof total === 'number') return `${total} total`;
+  if (typeof prompt === 'number' || typeof completion === 'number') {
+    return `${prompt || 0} in, ${completion || 0} out`;
+  }
+  return '';
+}
+
+export function buildToolFallbackAnswer(toolSummaries, errorMessage = '') {
+  const lines = ['I used the requested tools but could not get a final model response.'];
+  if (errorMessage) lines.push(`Final answer request failed: ${errorMessage}`);
+  if (toolSummaries.length) {
+    lines.push('Tool results:');
+    lines.push(...toolSummaries.map(summary => `- ${summary}`));
+  }
+  return lines.join('\n');
+}
+
+export function formatToolResultForConsole(toolName, result) {
+  if (!result) return '';
+  if (result.success === false) {
+    return `Tool failed: ${result.error || 'unknown error'}`;
+  }
+
+  switch (toolName) {
+    case 'Read':
+      return `Read ${result.path} (${result.lines} lines, ${result.size} chars)`;
+    case 'Write':
+      return result.diff ? `Wrote ${result.path}\n${result.diff}` : `Wrote ${result.path} (${result.size} chars)`;
+    case 'Edit':
+      return result.diff ? `Edited ${result.path}\n${result.diff}` : `Edited ${result.path} (${result.replacements} replacements)`;
+    case 'Glob':
+      return `Found ${result.count} file(s)`;
+    case 'Grep':
+      return `Found ${result.count} match(es)`;
+    case 'Bash': {
+      const output = (result.stdout || result.stderr || '').trim();
+      return output.length > 1200 ? `${output.slice(0, 1200)}\n... truncated` : output;
+    }
+    case 'WebFetch':
+      return `Fetched ${result.url} (${result.length} chars)`;
+    case 'WebSearch':
+      return `Found ${result.count} result(s)`;
+    default:
+      return result.message || '';
+  }
+}
+
+export function normalizeToolCalls(toolCalls, parseArguments = parseToolArguments) {
+  if (!Array.isArray(toolCalls)) return [];
+
+  return toolCalls.map((tc, index) => {
+    const fn = tc.function || {};
+    const rawArgs = fn.arguments ?? tc.arguments ?? tc.input ?? {};
+
+    return {
+      ...tc,
+      id: tc.id || `call-${index}`,
+      toolName: fn.name || tc.name || tc.tool_name || tc.type,
+      toolArgs: parseArguments(rawArgs),
+    };
+  });
+}
+
+export function extractInlineToolCalls(content, idFactory = index => `inline-${Date.now()}-${index}`) {
+  const text = String(content || '');
+  const toolCalls = [];
+  let cleaned = text;
+  const callPattern = /<minimax:tool_call>\s*<invoke\s+name=["']([^"']+)["']>([\s\S]*?)<\/invoke>\s*<\/minimax:tool_call>/gi;
+
+  cleaned = cleaned.replace(callPattern, (_match, name, body) => {
+    const args = {};
+    const paramPattern = /<parameter\s+name=["']([^"']+)["']>([\s\S]*?)<\/parameter>/gi;
+    let param;
+    while ((param = paramPattern.exec(body))) {
+      args[param[1]] = decodeXmlEntities(param[2].trim());
+    }
+    toolCalls.push({
+      id: idFactory(toolCalls.length),
+      type: 'function',
+      function: {
+        name,
+        arguments: JSON.stringify(args),
+      },
+    });
+    return '';
+  }).trim();
+
+  return { content: cleaned, toolCalls };
+}
+
+export function decodeXmlEntities(value) {
+  return String(value || '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+export function parseToolArguments(rawArgs) {
+  if (!rawArgs) return {};
+  if (typeof rawArgs === 'object') return rawArgs;
+  if (typeof rawArgs !== 'string') return {};
+
+  const text = rawArgs.trim();
+  if (!text) return {};
+
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const extracted = extractFirstJsonObject(text);
+    if (extracted && extracted !== text) {
+      try {
+        return JSON.parse(extracted);
+      } catch {}
+    }
+
+    return {
+      __toolArgParseError: error.message,
+      __rawToolArgs: text.length > 800 ? `${text.slice(0, 800)}...` : text,
+    };
+  }
+}
+
+export function extractFirstJsonObject(text) {
+  const start = text.indexOf('{');
+  if (start === -1) return null;
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === '{') depth++;
+    if (ch === '}') {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+
+  return null;
+}
+
+export function formatToolCallsForMessage(toolCalls) {
+  return toolCalls.map((tc) => ({
+    id: tc.id,
+    type: 'function',
+    function: {
+      name: tc.toolName || tc.function?.name || 'unknown',
+      arguments: JSON.stringify(tc.toolArgs || {}),
+    },
+  }));
+}
+
+export function buildToolCallSignature(toolCalls, normalizeToolName = name => name) {
+  if (!Array.isArray(toolCalls) || toolCalls.length === 0) return '';
+
+  return toolCalls.map((tc) => {
+    const rawName = tc.toolName || tc.function?.name || tc.type || '';
+    const toolName = normalizeToolName(rawName) || rawName;
+    const toolArgs = tc.toolArgs && typeof tc.toolArgs === 'object' ? tc.toolArgs : {};
+    return `${toolName}:${JSON.stringify(toolArgs)}`;
+  }).join(' | ');
+}
+
+export function compactText(text, maxChars = 1200, label = 'text') {
+  const value = String(text ?? '');
+  if (value.length <= maxChars) return value;
+
+  const headChars = Math.max(0, Math.floor(maxChars * 0.7));
+  const tailChars = Math.max(0, Math.floor(maxChars * 0.2));
+  const head = value.slice(0, headChars);
+  const tail = tailChars > 0 ? value.slice(-tailChars) : '';
+  const omitted = Math.max(0, value.length - head.length - tail.length);
+
+  return [
+    head,
+    `[${label} truncated: ${omitted} chars omitted]`,
+    tail,
+  ].filter(Boolean).join('\n');
+}
+
+export function summarizePromptList(items, { limit = 8, maxEntryChars = 220, maxTotalChars = 1600, mapper = value => value?.text ?? String(value ?? '') } = {}) {
+  const selected = [];
+  let total = 0;
+
+  for (const item of items.slice(-limit)) {
+    const raw = compactText(mapper(item), maxEntryChars, 'entry').trim();
+    if (!raw) continue;
+    if (total + raw.length > maxTotalChars && selected.length > 0) break;
+    selected.push(`- ${raw}`);
+    total += raw.length;
+  }
+
+  if (items.length > selected.length) {
+    selected.push(`- ... (${items.length - selected.length} items omitted)`);
+  }
+
+  return selected.join('\n');
+}

package/src/cli/markdown-format.js

@@ -0,0 +1,143 @@
+import { highlight } from 'cli-highlight';
+
+import { colors } from './snowflake-logo.js';
+import { renderBox, terminalWidth, visibleWidth, wrapText, padVisible } from './terminal-ui.js';
+
+export function formatMarkdown(text) {
+  if (!text) return '';
+  let formatted = text;
+
+  formatted = formatted.replace(/```(\w*)\n([\s\S]*?)```/g, (match, lang, code) => {
+    const label = lang || 'code';
+    let coloredCode = code.trimEnd();
+    try {
+      coloredCode = highlight(coloredCode, { language: lang || 'javascript', ignoreIllegals: true });
+    } catch {
+      // Keep raw code when the highlighter cannot parse a language.
+    }
+
+    const boxWidth = Math.max(60, Math.min(terminalWidth(60, 100, 80), 100));
+    const body = wrapText(coloredCode, boxWidth - 4);
+
+    return `\n${renderBox({
+      title: label,
+      width: boxWidth,
+      borderColor: colors.dim,
+      titleColor: colors.dim,
+      body,
+    })}\n${colors.white}`;
+  });
+
+  formatted = formatMarkdownTables(formatted);
+  formatted = formatted.replace(/\*\*(.*?)\*\*/g, `${colors.bright}$1${colors.reset}${colors.white}`);
+  formatted = formatted.replace(/(?<!\*)\*([^*\n]+)\*(?!\*)/g, `${colors.italic || colors.dim}$1${colors.reset}${colors.white}`);
+  formatted = formatted.replace(/`([^`\n]+)`/g, `${colors.cyan}$1${colors.reset}${colors.white}`);
+  formatted = formatted.replace(/^### (.+)$/gm, `${colors.cyan}   $1${colors.reset}`);
+  formatted = formatted.replace(/^## (.+)$/gm, `${colors.cyan}${colors.bright}  $1${colors.reset}`);
+  formatted = formatted.replace(/^# (.+)$/gm, `\n${colors.bright}${colors.cyan}━━ $1${colors.reset}\n`);
+  formatted = formatted.replace(/^---+$/gm, `${colors.dim}${'─'.repeat(50)}${colors.reset}`);
+  formatted = formatted.replace(/^(\s*)[-*] /gm, `$1${colors.cyan}•${colors.reset} `);
+  formatted = formatted.replace(/^(\s*)(\d+)\. /gm, `$1${colors.cyan}$2.${colors.reset} `);
+
+  return formatted;
+}
+
+export function formatMarkdownTables(text) {
+  const lines = String(text ?? '').split(/\r?\n/);
+  const output = [];
+
+  for (let index = 0; index < lines.length;) {
+    const currentLine = lines[index];
+    const nextLine = lines[index + 1];
+
+    if (isMarkdownTableRow(currentLine) && isMarkdownTableSeparator(nextLine)) {
+      const block = [currentLine, nextLine];
+      index += 2;
+
+      while (index < lines.length && isMarkdownTableRow(lines[index])) {
+        block.push(lines[index]);
+        index++;
+      }
+
+      output.push(renderMarkdownTableBlock(block));
+      continue;
+    }
+
+    output.push(currentLine);
+    index++;
+  }
+
+  return output.join('\n');
+}
+
+function isMarkdownTableRow(line) {
+  return /^\s*\|.*\|\s*$/.test(String(line || ''));
+}
+
+function isMarkdownTableSeparator(line) {
+  if (!isMarkdownTableRow(line)) return false;
+  const cells = splitMarkdownTableRow(line);
+  return cells.length > 0 && cells.every(cell => /^:?-{3,}:?$/.test(cell.replace(/\s+/g, '')));
+}
+
+function splitMarkdownTableRow(line) {
+  return String(line || '')
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map(cell => cell.trim());
+}
+
+function renderMarkdownTableBlock(tableLines) {
+  const rows = tableLines
+    .filter((line, index) => index !== 1)
+    .map(splitMarkdownTableRow)
+    .filter(row => row.length > 0);
+
+  const columnCount = Math.max(...rows.map(row => row.length), 0);
+  if (columnCount === 0) return tableLines.join('\n');
+
+  const boxWidth = Math.max(60, Math.min(terminalWidth(60, 100, 84), 100));
+  const innerWidth = boxWidth - 4;
+  const separatorWidth = (columnCount - 1) * 3;
+  const availableWidth = Math.max(columnCount * 8, innerWidth - separatorWidth);
+
+  const widestCells = Array.from({ length: columnCount }, (_, columnIndex) => {
+    return Math.max(8, ...rows.map(row => visibleWidth(row[columnIndex] || '')));
+  });
+
+  const widestTotal = widestCells.reduce((sum, width) => sum + width, 0);
+  const scale = widestTotal > availableWidth ? availableWidth / widestTotal : 1;
+  const columnWidths = widestCells.map(width => Math.max(8, Math.floor(width * scale)));
+
+  const renderRow = (cells) => {
+    const wrappedCells = cells.map((cell, index) => wrapText(cell || '', columnWidths[index]));
+    const lineCount = Math.max(...wrappedCells.map(lines => lines.length), 1);
+    const rendered = [];
+
+    for (let lineIndex = 0; lineIndex < lineCount; lineIndex++) {
+      const parts = [];
+      for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+        const cellLine = wrappedCells[columnIndex][lineIndex] || '';
+        parts.push(padVisible(cellLine, columnWidths[columnIndex]));
+      }
+      rendered.push(parts.join(' │ '));
+    }
+
+    return rendered;
+  };
+
+  const renderedRows = [];
+  for (const row of rows) {
+    renderedRows.push(...renderRow(row));
+  }
+
+  return renderBox({
+    title: 'TABLE',
+    width: boxWidth,
+    borderColor: colors.dim,
+    titleColor: colors.dim,
+    body: renderedRows,
+  });
+}

package/src/cli/prompt-builder.js

@@ -0,0 +1,189 @@
+/**
+ * PromptBuilder — Builds system prompts for Winter CLI agents.
+ * Extracted from WinterREPL to reduce repl.js size.
+ */
+export class PromptBuilder {
+  constructor({ session, tools, projectPath, sessionPermissionGrants, compactText, summarizePrompts } = {}) {
+    this.session = session;
+    this.tools = tools;
+    this.projectPath = projectPath;
+    this.sessionPermissionGrants = sessionPermissionGrants;
+    this._compactText = compactText;
+    this._summarizePrompts = summarizePrompts;
+  }
+
+  buildSessionSignalsPrompt() {
+    const activeProvider = this.session?.ai?.getActiveProvider?.() || 'unavailable';
+    const activeModel = this.session?.ai?.providers?.[activeProvider]?.model || 'unavailable';
+    const sessionContext = this.session?.getContext?.() || {};
+    const activeSkills = sessionContext.activeSkills?.value || [];
+    const toolAllowlist = [...(this.sessionPermissionGrants || [])];
+
+    return [
+      '## Session Signals',
+      `- Project path: ${this.projectPath}`,
+      `- Active provider: ${activeProvider}`,
+      `- Active model: ${activeModel}`,
+      `- Tool allowlist: ${toolAllowlist.length > 0 ? toolAllowlist.join(', ') : 'none'}`,
+      `- Active skills: ${Array.isArray(activeSkills) && activeSkills.length > 0 ? activeSkills.join(', ') : 'none'}`,
+    ].join('\n');
+  }
+
+  buildSystemPrompt(context = '') {
+    const memories = this.session?.getMemory?.() || [];
+    const plans = this.session?.getPlans?.() || [];
+    const sessionContext = this.session?.getContext?.() || {};
+    const environmentSummary = this.tools?.getRuntimeEnvironmentSummary?.() || this._defaultEnvironmentSummary();
+
+    const memoryStr = memories.length > 0
+      ? this._formatMemories(memories)
+      : '';
+    const plansStr = plans.length > 0
+      ? this._formatPlans(plans)
+      : '';
+    const skillsStr = Array.isArray(sessionContext.activeSkills) && sessionContext.activeSkills.length > 0
+      ? `\n## Auto-applied Skills\n${sessionContext.activeSkills.slice(0, 12).map(skill => `- ${skill}`).join('\n')}${sessionContext.activeSkills.length > 12 ? '\n- ...' : ''}`
+      : '';
+    const startupPlanStr = sessionContext.bootstrapPlan?.title
+      ? `\n## Startup Plan\n- ${sessionContext.bootstrapPlan.title}: ${sessionContext.bootstrapPlan.description}`
+      : '';
+    const sessionSignalsStr = `\n${this.buildSessionSignalsPrompt()}`;
+
+    return [
+      `You are Winter, an expert AI coding assistant.`,
+      ``,
+      `## Runtime Environment`,
+      environmentSummary,
+      ``,
+      `## Core Principles`,
+      `1. Think Before Coding — State assumptions, ask when uncertain, surface tradeoffs.`,
+      `2. Simplicity First — Minimum code that solves the problem. Nothing speculative.`,
+      `3. Surgical Changes — Touch only what you must. Clean up only your own mess.`,
+      `4. Goal-Driven Execution — Define success criteria. Loop until verified.`,
+      ``,
+      `## Tool Usage`,
+      `You have access to various tools (Read, Write, Edit, Bash, Glob, Grep, etc.).`,
+      `Use tools proactively. If you need information, look it up — don't guess.`,
+      ``,
+      `## Session`,
+      `Working directory: ${this.projectPath}`,
+      `Current session: ${this.session?.getSessionId?.()?.substring(0, 8) || 'unknown'}`,
+      `${memoryStr}${plansStr}${skillsStr}${startupPlanStr}${sessionSignalsStr}`,
+      context ? `\n## Project Context\n${this._compactText(context, 6000, 'project context')}` : '',
+      ``,
+      `Be helpful, be precise, and get things done. Always respond in Vietnamese.`,
+    ].join('\n');
+  }
+
+  buildFastSystemPrompt() {
+    const memories = this.session?.getMemory?.() || [];
+    const memoryStr = memories.length > 0
+      ? `\nContext nhớ ngắn:\n${this._summarizePrompts(memories.slice(-8), {
+          limit: 8,
+          maxEntryChars: 160,
+          maxTotalChars: 1200,
+          mapper: memory => memory.text,
+        })}`
+      : '';
+
+    return [
+      'Bạn là Winter, trợ lý AI trả lời ngắn gọn bằng tiếng Việt.',
+      'Ưu tiên dùng tool và context khi cần; không bịa thông tin.',
+      'Nếu người dùng yêu cầu sửa file/chạy lệnh/đọc dự án thì hãy gọi tool tương ứng thay vì chỉ nói chung chung.',
+      memoryStr,
+    ].filter(Boolean).join('\n');
+  }
+
+  buildAgentSystemPrompt(role, context = '') {
+    const memories = this.session?.getMemory?.() || [];
+    const plans = this.session?.getPlans?.() || [];
+    const sessionContext = this.session?.getContext?.() || {};
+
+    const memoryStr = memories.length > 0 ? this._formatMemories(memories) : '';
+    const plansStr = plans.length > 0 ? this._formatPlans(plans) : '';
+    const skillsStr = Array.isArray(sessionContext.activeSkills) && sessionContext.activeSkills.length > 0
+      ? `\n## Auto-applied Skills\n${sessionContext.activeSkills.slice(0, 12).map(skill => `- ${skill}`).join('\n')}${sessionContext.activeSkills.length > 12 ? '\n- ...' : ''}`
+      : '';
+    const startupPlanStr = sessionContext.bootstrapPlan?.title
+      ? `\n## Startup Plan\n- ${sessionContext.bootstrapPlan.title}: ${sessionContext.bootstrapPlan.description}`
+      : '';
+
+    const rolePrompts = {
+      plan: 'You are a Winter planning subagent. Break the request into a concise step-by-step plan, note dependencies, and keep the response short.',
+      review: 'You are a Winter review subagent. Critique the request or implementation with specific issues, edge cases, and concrete improvements.',
+      debug: 'You are a Winter debugging subagent. Focus on root cause, reproduction, and the smallest fix.',
+      research: 'You are a Winter research subagent. Gather the important facts, compare options, and summarize only what matters.',
+      browser: `You are a Winter browser subagent. Bạn CÓ QUYỀN sử dụng tool 'BrowserDebug' để tương tác với trình duyệt. Hãy dùng nó để mở URL, chụp ảnh màn hình (nếu cần), hoặc chạy JS để kiểm tra trang web.`,
+    };
+
+    const rolePrompt = rolePrompts[role] || 'You are a Winter coding subagent. Solve the task directly, use tools when needed, and return a concise result.';
+
+    const osInfo = process.platform === 'win32'
+      ? 'Windows; Bash auto-detects PowerShell and cmd.exe syntax. Use shell="powershell" or shell="cmd" when needed.'
+      : process.platform;
+
+    return [
+      '## CRITICAL AI RULES (MUST FOLLOW STRICTLY):',
+      '1. [THINKING BEFORE CODING]: State assumptions, constraints, and a brief plan before making changes. Be thorough enough to be useful, and do not invent facts.',
+      '2. [DESIGN EXCELLENCE]: Use rich aesthetics. Default to modern UI frameworks if applicable. Never output plain, ugly HTML/CSS. Ensure responsive, premium feel with micro-animations.',
+      '3. [CODE QUALITY]: Write clean, modular, SOLID code. Check for syntax errors carefully. Do not generate incomplete code blocks.',
+      '4. [NO HALLUCINATION]: If you don\'t know, use tools (Grep/Read/Web) to find out. Do not guess file paths or APIs.',
+      '5. [TOOL EXECUTION FIRST]: You DO have file tools. Use Write to create/overwrite files and Edit to patch files. Never say there is no write tool.',
+      '',
+      rolePrompt,
+      '',
+      '## Tool Rules',
+      '- Canonical tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, BrowserDebug, WebFetch, WebSearch.',
+      '- Treat skills, memories, bundled resources, local project rules, and the tool list as operational context. Use them proactively when relevant.',
+      `- Current OS is ${osInfo}.`,
+      '- Prefer Write/Edit for writing files. Bash accepts both PowerShell and cmd.exe on Windows, but do not use long echo chains for code files.',
+      '- If a tool call fails because of an unknown alias, call the canonical tool name next.',
+      '- Always start with a brief plan, then refine it when new facts appear.',
+      '',
+      '## Project',
+      `Working directory: ${this.projectPath}`,
+      `Current session: ${this.session?.getSessionId?.()?.substring(0, 8) || 'unknown'}`,
+      `${memoryStr}${plansStr}${skillsStr}${startupPlanStr}`,
+      context ? `\n## Project Context\n${this._compactText(context, 6000, 'project context')}` : '',
+    ].join('\n');
+  }
+
+  /** @private */
+  _formatMemories(memories) {
+    return `\n## Memories (Important Context)\n${this._summarizePrompts(memories, {
+      limit: 8,
+      maxEntryChars: 220,
+      maxTotalChars: 1600,
+      mapper: memory => memory.text,
+    })}`;
+  }
+
+  /** @private */
+  _formatPlans(plans) {
+    return `\n## Active Plans & Tasks\n${this._summarizePrompts(plans, {
+      limit: 6,
+      maxEntryChars: 260,
+      maxTotalChars: 1600,
+      mapper: plan => `[${plan.status}] ${plan.title}: ${plan.description}`,
+    })}`;
+  }
+
+  /** @private */
+  _defaultEnvironmentSummary() {
+    return [
+      `Host OS: ${process.platform === 'win32' ? 'Windows' : process.platform === 'darwin' ? 'macOS' : process.platform === 'linux' ? 'Linux' : process.platform}`,
+      `Node platform: ${process.platform}`,
+      `Current shell hint: ${process.platform === 'win32' ? 'powershell-capable or cmd/unknown' : (process.env.SHELL || 'bash/sh')}`,
+      process.platform === 'win32'
+        ? 'Shell rule: Use shell:"powershell" for PowerShell cmdlets, shell:"cmd" for cmd.exe syntax, and shell:"auto" when unsure.'
+        : 'Shell rule: Use the native POSIX shell on non-Windows hosts and leave shell unspecified unless a specific shell is required.',
+    ].join('\n');
+  }
+
+  /** @private */
+  _compactText(text, maxChars = 1000, label = 'text') {
+    if (this._compactText) return this._compactText(text, maxChars, label);
+    if (!text || text.length <= maxChars) return text || '';
+    return text.slice(0, maxChars) + `\n\n[... ${label} truncated at ${maxChars} chars]`;
+  }
+}