codemini-cli 0.1.11 → 0.1.13

package/src/core/chat-runtime.js

@@ -26,6 +26,7 @@ import {
   estimateMessagesTokens,
   parseCompactArgs
 } from './context-compact.js';
+import { buildSystemPromptWithReplyLanguage } from './reply-language.js';
 import { buildSystemPromptWithSoul } from './soul.js';
 
 function toOpenAIMessages(sessionMessages) {
@@ -60,6 +61,46 @@ function nowStamp() {
   return new Date().toISOString().replace(/[:.]/g, '-');
 }
 
+function prioritizeByPreferredOrder(items, preferredOrder) {
+  const source = Array.isArray(items) ? items : [];
+  const priorities = new Map((Array.isArray(preferredOrder) ? preferredOrder : []).map((value, index) => [value, index]));
+  return [...source].sort((left, right) => {
+    const leftRank = priorities.has(left) ? priorities.get(left) : Number.MAX_SAFE_INTEGER;
+    const rightRank = priorities.has(right) ? priorities.get(right) : Number.MAX_SAFE_INTEGER;
+    if (leftRank !== rightRank) return leftRank - rightRank;
+    return source.indexOf(left) - source.indexOf(right);
+  });
+}
+
+function describeConfigKey(key, mode = 'set') {
+  const labelMap = {
+    'gateway.base_url': 'gateway base URL',
+    'gateway.api_key': 'gateway API key',
+    'gateway.timeout_ms': 'gateway timeout in milliseconds',
+    'gateway.max_retries': 'gateway retry count',
+    'model.name': 'active model name',
+    'model.max_context_tokens': 'model context token limit',
+    'ui.reply_language': 'reply language',
+    'execution.mode': 'execution mode',
+    'execution.always_allow_tools': 'always-allowed tools',
+    'execution.max_steps': 'maximum tool steps',
+    'context.preflight_trigger_pct': 'preflight compact threshold',
+    'context.hard_limit_pct': 'hard compact threshold',
+    'context.tool_result_max_chars': 'tool result character limit',
+    'context.read_file_default_lines': 'default read_file line window',
+    'context.read_file_max_chars': 'read_file character limit',
+    'sessions.max_sessions': 'stored session limit',
+    'sessions.retention_days': 'session retention days',
+    'shell.default': 'default shell',
+    'shell.timeout_ms': 'shell timeout in milliseconds',
+    'context.max_tokens': 'context token budget',
+    'policy.safe_mode': 'safe mode switch',
+    'policy.allow_dangerous_commands': 'dangerous command allowance'
+  };
+  const label = labelMap[key] || key;
+  return mode === 'get' ? `show the ${label}` : `set the ${label}`;
+}
+
 const SUB_AGENT_ROLES = ['planner', 'coder', 'reviewer', 'tester'];
 const SUB_AGENT_CONTEXT_MAX_MESSAGES = 4;
 const SUB_AGENT_CONTEXT_MAX_CHARS = 1200;
@@ -76,6 +117,8 @@ function getSubAgentRolePrompt(role) {
       'You are a review sub-agent. Focus on bugs, regressions, edge cases, and missing tests.',
       'Start with the focused files or directories handed to you. Do not roam unrelated parts of the repo unless the handed-off evidence is insufficient.',
       'Use this exact output structure:',
+      'Acceptance Status:',
+      '- <met|unmet|unverified> :: <acceptance checklist item or "none">',
       'Findings:',
       '- <bug, regression, risk, or "none">',
       'Verified:',
@@ -92,6 +135,8 @@ function getSubAgentRolePrompt(role) {
       'Prefer running concrete verification commands over only suggesting them.',
       'Start with the focused files or directories handed to you. Verify those artifacts first before scanning the wider repo.',
       'Use this exact output structure:',
+      'Acceptance Status:',
+      '- <met|unmet|unverified> :: <acceptance checklist item or "none">',
       'Verified:',
       '- <commands run and evidence>',
       'Not Verified:',
@@ -277,6 +322,114 @@ function buildFocusedTaskNote(role, focusPaths) {
   return '';
 }
 
+function normalizeGoalClauseText(value) {
+  return String(value || '')
+    .replace(/^[\s\-*0-9.)、，,:;]+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function sentenceCaseRequirement(value) {
+  const text = normalizeGoalClauseText(value);
+  if (!text) return '';
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function deriveGoalRequirements(goal) {
+  const rawGoal = String(goal || '').trim();
+  if (!rawGoal) return [];
+
+  const normalized = rawGoal
+    .replace(/\r\n?/g, '\n')
+    .replace(/[；。]/g, ',')
+    .replace(/\band then\b/gi, ',')
+    .replace(/\bthen\b/gi, ',')
+    .replace(/\bplus\b/gi, ',')
+    .replace(/\s+(?:and|并且|而且|以及)\s+/gi, ', ')
+    .replace(/\n+/g, ', ');
+
+  const roughParts = normalized
+    .split(/\s*,\s*/)
+    .map((part) => normalizeGoalClauseText(part))
+    .filter(Boolean);
+
+  const requirements = [];
+  const seen = new Set();
+
+  for (const part of roughParts) {
+    const lowered = part.toLowerCase();
+    if (/\btrim\b/.test(lowered) && !/\bwhitespace\b/.test(lowered)) {
+      const label = 'Trim whitespace in the returned greeting';
+      if (!seen.has(label)) {
+        seen.add(label);
+        requirements.push(label);
+      }
+      continue;
+    }
+    if (/\btrim\b/.test(lowered) && /\bwhitespace\b/.test(lowered)) {
+      const label = 'Trim whitespace in the returned greeting';
+      if (!seen.has(label)) {
+        seen.add(label);
+        requirements.push(label);
+      }
+      continue;
+    }
+    if (/(exclamation mark|感叹号|!)/i.test(part)) {
+      const label = 'Preserve the exclamation mark';
+      if (!seen.has(label)) {
+        seen.add(label);
+        requirements.push(label);
+      }
+      continue;
+    }
+    const label = sentenceCaseRequirement(part);
+    if (!label || seen.has(label)) continue;
+    seen.add(label);
+    requirements.push(label);
+  }
+
+  if (requirements.length === 0) {
+    return [sentenceCaseRequirement(rawGoal)].filter(Boolean);
+  }
+  return requirements.slice(0, 6);
+}
+
+function isLightweightAutoPlanGoal(goal, requirements = []) {
+  const text = String(goal || '').trim();
+  if (!text) return false;
+  if (requirements.length !== 1) return false;
+  if (text.length > 140) return false;
+  if (/\b(plan|spec|design|architecture|roadmap|strategy|migration|refactor)\b/i.test(text)) return false;
+  if (/\b(ensure|verify|review|test|validate|make sure|confirm)\b/i.test(text)) return false;
+  if (/[；。]/.test(text)) return false;
+  return /\b(add|update|fix|rename|trim|export|create|remove|change|implement)\b/i.test(text);
+}
+
+function buildGoalRequirementPacket(goal, role) {
+  const rawGoal = trimInlineText(goal, 800);
+  if (!rawGoal) return '';
+  const requirements = deriveGoalRequirements(goal);
+  const lines = ['Original goal:', rawGoal];
+  if (requirements.length > 0) {
+    lines.push('Acceptance checklist:');
+    for (const requirement of requirements) {
+      lines.push(`- ${requirement}`);
+    }
+  }
+  if (role === 'reviewer') {
+    lines.push('Review against the original goal, not just local code quality.');
+    lines.push('Check each acceptance item explicitly before deciding there are no findings.');
+    lines.push('If any requested behavior is missing, incorrect, or only partially implemented, report it in Findings.');
+  } else if (role === 'tester') {
+    lines.push('Verify the implementation against the original goal, not just syntax or smoke checks.');
+    lines.push('Check each acceptance item explicitly before calling the work verified.');
+    lines.push('If any requested behavior is unverified or contradicted by evidence, list it under Not Verified or Failures.');
+  } else if (role === 'coder') {
+    lines.push('Implement against the acceptance checklist, not only the broad wording of the goal.');
+  }
+  return lines.join('\n');
+}
+
 async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -466,7 +619,16 @@ function normalizeAutoPlan(parsed, goal) {
 
 function enforceAutoPlanGuardrailSteps(plan, goal) {
   const source = Array.isArray(plan?.steps) ? plan.steps : [];
+  const requirements = deriveGoalRequirements(goal);
+  const lightweightGoal = isLightweightAutoPlanGoal(goal, requirements);
   const implementationSteps = source.filter((step) => step.role !== 'reviewer' && step.role !== 'tester');
+  const primaryImplementationStep =
+    implementationSteps.find((step) => step.role === 'coder') ||
+    implementationSteps[0] || {
+      title: 'Implement requested change',
+      role: 'coder',
+      task: `Implement the requested change for: ${goal}`
+    };
   const reviewerStep = source.find((step) => step.role === 'reviewer') || {
     title: 'Review implementation',
     role: 'reviewer',
@@ -478,6 +640,13 @@ function enforceAutoPlanGuardrailSteps(plan, goal) {
     task: `Test and verify the completed work for: ${goal}. Start with the artifacts produced by earlier implementation steps, run the most relevant checks available, report concrete evidence, and call out anything still unverified.`
   };
 
+  if (lightweightGoal) {
+    return {
+      summary: String(plan?.summary || `Auto plan for: ${goal}`).trim(),
+      steps: [primaryImplementationStep, testerStep]
+    };
+  }
+
   return {
     summary: String(plan?.summary || `Auto plan for: ${goal}`).trim(),
     steps: [...implementationSteps.slice(0, 6), reviewerStep, testerStep]
@@ -487,18 +656,75 @@ function enforceAutoPlanGuardrailSteps(plan, goal) {
 function looksLikeSuccessfulStepOutput(text = '') {
   const value = String(text || '').trim();
   if (!value) return false;
-  if (/(^|\n)\s*(error|failures?)\s*:\s*(?!none\b)/i.test(value)) return false;
-  if (/(^|\n)\s*next action\s*:\s*-\s*retry\b/i.test(value)) return false;
+  const failureBullet = extractSectionFirstBullet(value, 'Failures');
+  const errorBullet = extractSectionFirstBullet(value, 'Error');
+  const nextActionBullet = extractSectionFirstBullet(value, 'Next Action');
+  const acceptanceFailures = extractAcceptanceStatusItems(value).filter((item) => item.status !== 'met');
+  if (errorBullet && !/^none\b/i.test(errorBullet)) return false;
+  if (failureBullet && !/^none\b/i.test(failureBullet)) return false;
+  if (acceptanceFailures.length > 0) return false;
+  if (nextActionBullet && /^retry\b/i.test(nextActionBullet)) return false;
   return true;
 }
 
+function stepOutputHasFailureSignals(role, text = '') {
+  const value = String(text || '').trim();
+  if (!value) return true;
+  const errorBullet = extractSectionFirstBullet(value, 'Error');
+  const failureBullet = extractSectionFirstBullet(value, 'Failures');
+  const findingsBullet = extractSectionFirstBullet(value, 'Findings');
+  const nextActionBullet = extractSectionFirstBullet(value, 'Next Action');
+  const acceptanceFailures = extractAcceptanceStatusItems(value).filter((item) => item.status !== 'met');
+  if (errorBullet && !/^none\b/i.test(errorBullet)) return true;
+  if (failureBullet && !/^none\b/i.test(failureBullet)) return true;
+  if (acceptanceFailures.length > 0) return true;
+  if (role === 'reviewer' && findingsBullet && !/^none\b/i.test(findingsBullet)) return true;
+  if (nextActionBullet && /^(fix|retry|correct|repair)\b/i.test(nextActionBullet)) return true;
+  return false;
+}
+
+function extractSectionFirstBullet(text = '', heading = '') {
+  const escaped = String(heading || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = String(text || '').match(new RegExp(String.raw`(^|\n)\s*${escaped}\s*:\s*(?:\n|\r\n?)+\s*-\s*([^\n\r]+)`, 'i'));
+  return String(match?.[2] || '').trim();
+}
+
+function extractSectionBullets(text = '', heading = '') {
+  const escaped = String(heading || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const value = String(text || '');
+  const headingMatch = value.match(new RegExp(String.raw`(^|\n)\s*${escaped}\s*:\s*(?:\n|\r\n?)`, 'i'));
+  if (!headingMatch || headingMatch.index == null) return [];
+  const start = headingMatch.index + headingMatch[0].length;
+  const after = value.slice(start);
+  const nextHeading = after.search(/\n\s*[A-Za-z][A-Za-z ]+\s*:\s*(?:\n|\r\n?)/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+  return section
+    .split(/\r?\n/)
+    .map((line) => line.match(/^\s*-\s*(.+)$/)?.[1]?.trim() || '')
+    .filter(Boolean);
+}
+
+function extractAcceptanceStatusItems(text = '') {
+  return extractSectionBullets(text, 'Acceptance Status')
+    .map((item) => {
+      const match = String(item).match(/^(met|unmet|unverified)\s*::\s*(.+)$/i);
+      if (!match) return null;
+      return {
+        status: String(match[1] || '').toLowerCase(),
+        label: String(match[2] || '').trim()
+      };
+    })
+    .filter(Boolean);
+}
+
 function buildAutoPlanSystemSummary(auto) {
   const statusTitle =
     auto.failedCount > 0 ? 'Auto plan finished with failures' : auto.warningCount > 0 ? 'Auto plan finished with warnings' : 'Auto plan finished';
   const lines = [
     statusTitle,
     `File: ${auto.filePath}`,
-    `Summary: ${auto.summary || '-'}`,
+    `Plan Summary: ${auto.summary || '-'}`,
+    `Final Summary: ${auto.finalSummary || auto.summary || '-'}`,
     `Steps: ${auto.steps.length} total`,
     `Completed: ${auto.completedCount}`,
     `Warnings: ${auto.warningCount}`,
@@ -513,6 +739,99 @@ function buildAutoPlanSystemSummary(auto) {
   return lines.join('\n');
 }
 
+function buildAutoPlanFinalSummaryUserPrompt({ goal, autoPlan, runItems, planningError }) {
+  const lines = [];
+  lines.push('Create a final execution summary for an auto-generated implementation/test plan.');
+  lines.push('Keep it concise, high-signal, and outcome-focused.');
+  lines.push('Include: overall result, what was verified, what is still pending, and the best next action.');
+  lines.push('Use plain text only. Do not use markdown fences.');
+  lines.push('');
+  lines.push(`Goal: ${goal}`);
+  lines.push(`Plan Summary: ${autoPlan?.summary || `Auto plan for: ${goal}`}`);
+  if (planningError) {
+    lines.push(`Planning Error: ${planningError}`);
+  }
+  lines.push('');
+  lines.push('Executed Steps:');
+  runItems.forEach((item, idx) => {
+    lines.push(`${idx + 1}. [${item.role}] ${item.title}`);
+    if (item.failed) {
+      lines.push(`Status: failed`);
+    } else if (item.warning) {
+      lines.push(`Status: warning`);
+    } else {
+      lines.push(`Status: completed`);
+    }
+    if (item.error) {
+      lines.push(`Error: ${item.error}`);
+    }
+    if (item.warning) {
+      lines.push(`Warning: ${item.warning}`);
+    }
+    lines.push(`Output: ${trimInlineText(item.output || '(empty)', 500)}`);
+    if (Array.isArray(item.artifactPaths) && item.artifactPaths.length > 0) {
+      lines.push(`Artifacts: ${item.artifactPaths.slice(0, 5).join(', ')}`);
+    }
+    lines.push('');
+  });
+  return lines.join('\n').trim();
+}
+
+async function buildAutoPlanFinalSummary({
+  goal,
+  autoPlan,
+  runItems,
+  planningError,
+  config,
+  model,
+  systemPrompt
+}) {
+  const fallbackParts = [];
+  if (runItems.some((item) => item.failed || item.error)) {
+    fallbackParts.push('Execution finished with failed steps.');
+  } else if (runItems.some((item) => item.warning)) {
+    fallbackParts.push('Execution finished with warnings.');
+  } else {
+    fallbackParts.push('Execution finished successfully.');
+  }
+  const verifiedTitles = runItems.filter((item) => !item.failed).map((item) => item.title);
+  const pendingTitles = runItems.filter((item) => item.failed || item.warning).map((item) => item.title);
+  if (verifiedTitles.length > 0) {
+    fallbackParts.push(`Completed: ${verifiedTitles.slice(0, 4).join(', ')}.`);
+  }
+  if (pendingTitles.length > 0) {
+    fallbackParts.push(`Needs follow-up: ${pendingTitles.slice(0, 4).join(', ')}.`);
+  }
+  const fallbackSummary = fallbackParts.join(' ');
+
+  if (runItems.some((item) => item.failed || item.error)) {
+    return fallbackSummary;
+  }
+
+  try {
+    const result = await createChatCompletion({
+      baseUrl: config.gateway.base_url,
+      apiKey: config.gateway.api_key,
+      model: model || config.model.name,
+      messages: [
+        {
+          role: 'system',
+          content: `${systemPrompt}\nYou are writing the final execution summary for a completed auto plan. Focus on closure, verification status, and the next action.`
+        },
+        {
+          role: 'user',
+          content: buildAutoPlanFinalSummaryUserPrompt({ goal, autoPlan, runItems, planningError })
+        }
+      ],
+      timeoutMs: config.gateway.timeout_ms || 90000,
+      maxRetries: config.gateway.max_retries ?? 2
+    });
+    return trimInlineText(result.text || '', 600) || fallbackSummary;
+  } catch {
+    return fallbackSummary;
+  }
+}
+
 async function writeMarkdownInCoderDir(subDir, title, body, fallbackName, sessionId) {
   const parts = [process.cwd(), '.coder', subDir];
   if (sessionId) parts.push(String(sessionId));
@@ -943,6 +1262,7 @@ async function askModel({
 async function runSubAgentTask({
   role,
   task,
+  goal = '',
   priorSteps = [],
   parentSession,
   config,
@@ -957,8 +1277,18 @@ async function runSubAgentTask({
   const handoffPacket = buildStepArtifactPacket(priorSteps, role);
   const handoffFocusPaths = collectStepArtifacts(priorSteps, role)?.focusPaths || [];
   const focusedTaskNote = buildFocusedTaskNote(role, handoffFocusPaths);
+  const goalRequirementPacket = buildGoalRequirementPacket(goal, role);
   const verificationPacket = role === 'tester' ? await buildTesterVerificationPacket(handoffFocusPaths) : '';
-  const scopedTask = [contextPacket, evidencePacket, handoffPacket, verificationPacket, focusedTaskNote, 'Task:', task]
+  const scopedTask = [
+    contextPacket,
+    goalRequirementPacket,
+    evidencePacket,
+    handoffPacket,
+    verificationPacket,
+    focusedTaskNote,
+    'Task:',
+    task
+  ]
     .filter(Boolean)
     .join('\n\n');
   let blockedCount = 0;
@@ -1015,6 +1345,7 @@ async function buildAutoPlanAndRun({
   onAgentEvent,
   sessionId
 }) {
+  const requirementPacket = buildGoalRequirementPacket(goal, 'planner');
   const plannerPrompt =
     'Return strict JSON only with shape {"summary":"...","steps":[{"title":"...","role":"planner|coder|reviewer|tester","task":"..."}]}. No markdown. Always include final reviewer and tester steps.';
   let autoPlan = {
@@ -1037,7 +1368,13 @@ async function buildAutoPlanAndRun({
         { role: 'system', content: `${systemPrompt}\n${plannerPrompt}` },
         {
           role: 'user',
-          content: `Create an execution plan and assign best sub-agent role for each step.\nGoal: ${goal}\nThe final steps must include review and testing/verification.`
+          content: [
+            'Create an execution plan and assign best sub-agent role for each step.',
+            requirementPacket,
+            'The final steps must include review and testing/verification unless the goal is a tiny single-change task, in which case you may keep only one implementation step plus one testing/verification step.'
+          ]
+            .filter(Boolean)
+            .join('\n')
         }
       ],
       timeoutMs: config.gateway.timeout_ms || 90000,
@@ -1050,18 +1387,20 @@ async function buildAutoPlanAndRun({
   }
 
   const runItems = [];
+  const totalPlanSteps = autoPlan.steps.length + 1;
   for (let i = 0; i < autoPlan.steps.length; i += 1) {
     const step = autoPlan.steps[i];
     if (onAgentEvent) {
       onAgentEvent({
         type: 'assistant:delta',
-        text: `\n[plan] Step ${i + 1}/${autoPlan.steps.length} -> ${step.role}: ${step.title}\n`
+        text: `\n[plan] Step ${i + 1}/${totalPlanSteps} -> ${step.role}: ${step.title}\n`
       });
     }
     try {
       const stepResult = await runSubAgentTask({
         role: step.role,
         task: step.task,
+        goal,
         priorSteps: runItems,
         parentSession: session,
         config,
@@ -1070,14 +1409,20 @@ async function buildAutoPlanAndRun({
         onAgentEvent
       });
       const outputLooksSuccessful = looksLikeSuccessfulStepOutput(stepResult.text);
+      const outputHasFailureSignals = stepOutputHasFailureSignals(step.role, stepResult.text);
       const warningParts = [];
       if (stepResult.blockedCount > 0) warningParts.push(`${stepResult.blockedCount} blocked tool call(s)`);
       if (stepResult.toolErrorCount > 0) warningParts.push(`${stepResult.toolErrorCount} tool error(s)`);
       const warning = warningParts.length > 0 ? `sub-agent recovered after ${warningParts.join(', ')}` : '';
-      const failed = stepResult.hasErrorLine || (!outputLooksSuccessful && (stepResult.blockedCount > 0 || stepResult.toolErrorCount > 0));
+      const failed =
+        stepResult.hasErrorLine ||
+        outputHasFailureSignals ||
+        (!outputLooksSuccessful && (stepResult.blockedCount > 0 || stepResult.toolErrorCount > 0));
       let error = '';
       if (stepResult.hasErrorLine) {
         error = 'sub-agent output contains error line(s)';
+      } else if (outputHasFailureSignals) {
+        error = 'sub-agent output reports unmet requirements or failed verification';
       } else if (failed && stepResult.blockedCount > 0) {
         error = `sub-agent ended with ${stepResult.blockedCount} blocked tool call(s)`;
       } else if (failed && stepResult.toolErrorCount > 0) {
@@ -1106,11 +1451,30 @@ async function buildAutoPlanAndRun({
   const warningItems = runItems.filter((s) => !s.failed && s.warning);
   const completedItems = runItems.filter((s) => !s.failed);
 
+  if (onAgentEvent) {
+    onAgentEvent({
+      type: 'assistant:delta',
+      text: `\n[plan] Step ${totalPlanSteps}/${totalPlanSteps} -> summarizer: Final summary\n`
+    });
+  }
+  const finalSummary = await buildAutoPlanFinalSummary({
+    goal,
+    autoPlan,
+    runItems,
+    planningError,
+    config,
+    model,
+    systemPrompt
+  });
+
   const lines = [];
   lines.push(`# Auto Plan: ${goal}`);
   lines.push('');
   lines.push(`## Summary`);
   lines.push(autoPlan.summary || `Auto plan for: ${goal}`);
+  lines.push('');
+  lines.push('## Final Summary');
+  lines.push(finalSummary || '(empty)');
   if (planningError) {
     lines.push('');
     lines.push(`Planning Error: ${planningError}`);
@@ -1152,6 +1516,7 @@ async function buildAutoPlanAndRun({
   return {
     filePath,
     summary: autoPlan.summary,
+    finalSummary,
     steps: autoPlan.steps,
     completedCount: completedItems.length,
     warningCount: warningItems.length,
@@ -1213,11 +1578,13 @@ export async function createChatRuntime({
   const configKeyHints = [
     'gateway.base_url',
     'gateway.api_key',
+    'model.name',
+    'ui.reply_language',
+    'execution.mode',
+    'shell.default',
     'gateway.timeout_ms',
     'gateway.max_retries',
-    'model.name',
     'model.max_context_tokens',
-    'execution.mode',
     'execution.always_allow_tools',
     'execution.max_steps',
     'context.preflight_trigger_pct',
@@ -1227,13 +1594,34 @@ export async function createChatRuntime({
     'context.read_file_max_chars',
     'sessions.max_sessions',
     'sessions.retention_days',
-    'shell.default',
     'shell.timeout_ms',
     'context.max_tokens',
     'policy.safe_mode',
     'policy.allow_dangerous_commands'
   ];
 
+  const commandPriorityOrder = [
+    '/help',
+    '/status',
+    '/config',
+    '/mode',
+    '/plan',
+    '/tasks',
+    '/history',
+    '/checkpoint',
+    '/agents',
+    '/compact',
+    '/debug',
+    '/retry'
+  ];
+  const configSubcommandPriority = ['/config set', '/config get', '/config list', '/config reset'];
+  const configSubcommandDescriptions = {
+    '/config set': 'update a config value',
+    '/config get': 'show a config value',
+    '/config list': 'print the full config',
+    '/config reset': 'reset config to defaults'
+  };
+
   const listCommandNames = () => {
     const builtins = [
       { name: 'help', description: 'show chat help' },
@@ -1312,10 +1700,23 @@ export async function createChatRuntime({
     '/status'
   ];
   const compactKey = (value) => String(value || '').toLowerCase().replace(/[\/\s<>?]/g, '');
+  const commandDescriptions = new Map();
+  const registerSuggestion = (value, description = '') => {
+    commandDescriptions.set(value, description);
+    return { value, description };
+  };
+  const materializeSuggestions = (items) =>
+    (Array.isArray(items) ? items : []).map((item) => {
+      if (item && typeof item === 'object' && 'value' in item) return item;
+      const value = String(item || '');
+      return { value, description: commandDescriptions.get(value) || '' };
+    });
   const matchCompactTemplates = (value) => {
     const needle = compactKey(value);
     if (!needle) return [];
-    return slashTemplates.filter((template) => compactKey(template).startsWith(needle));
+    return materializeSuggestions(
+      slashTemplates.filter((template) => compactKey(template).startsWith(needle))
+    );
   };
 
   const getCompletionOptions = (rawInput) => {
@@ -1327,26 +1728,53 @@ export async function createChatRuntime({
     const tokens = body.trim().split(/\s+/).filter(Boolean);
     const commandPart = tokens[0] || '';
 
-    const allCommands = listCommandNames().map((c) => c.name);
+    const allCommandEntries = listCommandNames();
+    const allCommands = allCommandEntries.map((c) => c.name);
+    for (const entry of allCommandEntries) {
+      registerSuggestion(`/${entry.name}`, entry.description || '');
+    }
+    for (const template of configTemplates) {
+      registerSuggestion(template, configSubcommandDescriptions[template] || 'config command');
+    }
+    for (const template of historyTemplates) registerSuggestion(template, 'history command');
+    for (const template of modeTemplates) registerSuggestion(template, 'switch execution mode');
+    for (const template of taskTemplates) registerSuggestion(template, 'task board command');
+    for (const template of checkpointTemplates) registerSuggestion(template, 'checkpoint command');
+    for (const template of specTemplates) registerSuggestion(template, 'create a spec file');
+    for (const template of planTemplates) registerSuggestion(template, 'planning command');
+    for (const template of agentTemplates) registerSuggestion(template, 'sub-agent command');
+    for (const template of debugTemplates) registerSuggestion(template, 'debug command');
+    for (const template of compactTemplates) registerSuggestion(template, 'context compaction command');
+    registerSuggestion('/retry', 'retry the last user request');
+    registerSuggestion('/status', 'show runtime status');
 
     if (!commandPart) {
-      return allCommands.map((name) => `/${name}`);
+      return materializeSuggestions(prioritizeByPreferredOrder(
+        allCommands.map((name) => `/${name}`),
+        commandPriorityOrder
+      ));
     }
 
     if (tokens.length === 1 && !hasTrailingSpace) {
-      const direct = allCommands
-        .filter((name) => name.startsWith(commandPart))
-        .map((name) => `/${name}`);
-      if (direct.length > 0) return direct;
+      const direct = prioritizeByPreferredOrder(
+        allCommands
+          .filter((name) => name.startsWith(commandPart))
+          .map((name) => `/${name}`),
+        commandPriorityOrder
+      );
+      if (direct.length > 0) return materializeSuggestions(direct);
       return matchCompactTemplates(input);
     }
 
     if (commandPart === 'config') {
       if (tokens.length === 1 || (tokens.length === 2 && !hasTrailingSpace)) {
         const sub = tokens[1] || '';
-        return ['list', 'get', 'set', 'reset']
-          .filter((s) => s.startsWith(sub))
-          .map((s) => `/config ${s}`);
+        return materializeSuggestions(prioritizeByPreferredOrder(
+          ['set', 'get', 'list', 'reset']
+            .filter((s) => s.startsWith(sub))
+            .map((s) => registerSuggestion(`/config ${s}`, configSubcommandDescriptions[`/config ${s}`] || 'config command').value),
+          configSubcommandPriority
+        ));
       }
 
       const sub = tokens[1] || '';
@@ -1354,96 +1782,98 @@ export async function createChatRuntime({
         const keyPrefix = tokens[2] || '';
         return configKeyHints
           .filter((k) => k.startsWith(keyPrefix))
-          .map((k) => `/config get ${k}`);
+          .map((k) => registerSuggestion(`/config get ${k}`, describeConfigKey(k, 'get')));
       }
       if (sub === 'set') {
         const keyPrefix = tokens[2] || '';
         return configKeyHints
           .filter((k) => k.startsWith(keyPrefix))
-          .map((k) => `/config set ${k} `);
+          .map((k) => registerSuggestion(`/config set ${k} `, describeConfigKey(k, 'set')));
       }
 
-      return configTemplates;
+      return materializeSuggestions(configTemplates);
     }
 
     if (commandPart === 'compact') {
       const joined = tokens.slice(1).join(' ');
       return compactOptions
         .filter((opt) => opt.includes(joined) || joined === '')
-        .map((opt) => `/compact ${opt}`);
+        .map((opt) => registerSuggestion(`/compact ${opt}`, 'context compaction command'));
     }
 
     if (commandPart === 'retry') {
-      return ['/retry'];
+      return [registerSuggestion('/retry', 'retry the last user request')];
     }
     if (commandPart === 'status') {
-      return ['/status'];
+      return [registerSuggestion('/status', 'show runtime status')];
     }
     if (commandPart === 'mode') {
       if (tokens.length === 1 || (tokens.length === 2 && !hasTrailingSpace)) {
         const sub = tokens[1] || '';
         return ['normal', 'auto', 'plan']
           .filter((m) => m.startsWith(sub))
-          .map((m) => `/mode ${m}`);
+          .map((m) => registerSuggestion(`/mode ${m}`, 'switch execution mode'));
       }
-      return modeTemplates;
+      return materializeSuggestions(modeTemplates);
     }
     if (commandPart === 'tasks') {
       if (tokens.length <= 2 && !hasTrailingSpace) {
         const sub = tokens[1] || '';
         return ['add', 'start', 'done', 'remove', 'rm', 'clear']
           .filter((s) => s.startsWith(sub))
-          .map((s) => `/tasks ${s}`);
+          .map((s) => registerSuggestion(`/tasks ${s}`, 'task board command'));
       }
-      return taskTemplates;
+      return materializeSuggestions(taskTemplates);
     }
     if (commandPart === 'checkpoint') {
       if (tokens.length <= 2 && !hasTrailingSpace) {
         const sub = tokens[1] || '';
         return ['create', 'list', 'load']
           .filter((s) => s.startsWith(sub))
-          .map((s) => `/checkpoint ${s}`);
+          .map((s) => registerSuggestion(`/checkpoint ${s}`, 'checkpoint command'));
       }
       if (tokens[1] === 'list') {
         const hint = tokens[2] || '';
-        return ['--all'].filter((v) => v.startsWith(hint)).map((v) => `/checkpoint list ${v}`);
+        return ['--all']
+          .filter((v) => v.startsWith(hint))
+          .map((v) => registerSuggestion(`/checkpoint list ${v}`, 'checkpoint command'));
       }
       if (tokens[1] === 'load') {
         if (tokens.length >= 3) {
           const hint = tokens[3] || '';
           return ['--all']
             .filter((v) => v.startsWith(hint))
-            .map((v) => `/checkpoint load ${tokens[2]} ${v}`);
+            .map((v) => registerSuggestion(`/checkpoint load ${tokens[2]} ${v}`, 'checkpoint command'));
         }
       }
-      return checkpointTemplates;
+      return materializeSuggestions(checkpointTemplates);
     }
     if (commandPart === 'spec') {
-      return specTemplates;
+      return materializeSuggestions(specTemplates);
     }
     if (commandPart === 'plan') {
       if (tokens.length === 1 || (tokens.length === 2 && !hasTrailingSpace)) {
         const sub = tokens[1] || '';
         return ['auto', 'from-spec']
           .filter((s) => s.startsWith(sub))
-          .map((s) => `/plan ${s}`);
+          .map((s) => registerSuggestion(`/plan ${s}`, 'planning command'));
       }
-      return planTemplates;
+      return materializeSuggestions(planTemplates);
     }
     if (commandPart === 'agents') {
       if (tokens.length === 1 || (tokens.length === 2 && !hasTrailingSpace)) {
         const sub = tokens[1] || '';
         return ['list', 'run']
           .filter((s) => s.startsWith(sub))
-          .map((s) => `/agents ${s}`);
+          .map((s) => registerSuggestion(`/agents ${s}`, 'sub-agent command'));
       }
       if (tokens[1] === 'run') {
         const rolePrefix = tokens[2] || '';
         return ['planner', 'coder', 'reviewer', 'tester']
           .filter((r) => r.startsWith(rolePrefix))
-          .map((r) => `/agents run ${r} `);
+          .map((r) => registerSuggestion(`/agents run ${r} `, 'sub-agent command'));
       }
-      return agentTemplates;
+      return materializeSuggestions(agentTemplates);
     }
 
     if (commandPart === 'history') {
@@ -1460,12 +1890,13 @@ export async function createChatRuntime({
           .filter((session) => String(session.id || '').startsWith(idPrefix))
           .map((session) => ({
             value: `/history resume ${session.id}`,
-            display: `/history resume ${session.id}  ·  ${Number(session.messageCount || 0)} msgs`
+            display: `/history resume ${session.id}  ·  ${Number(session.messageCount || 0)} msgs`,
+            description: 'resume a saved session'
           }));
         if (dynamic.length > 0) return dynamic;
-        return historyTemplates;
+        return materializeSuggestions(historyTemplates);
       }
-      return historyTemplates;
+      return materializeSuggestions(historyTemplates);
     }
 
     if (commandPart === 'debug') {
@@ -1475,9 +1906,9 @@ export async function createChatRuntime({
         const action = tokens[2] || '';
         return ['on', 'off', 'status']
           .filter((v) => v.startsWith(action))
-          .map((v) => `/debug keys ${v}`);
+          .map((v) => registerSuggestion(`/debug keys ${v}`, 'keyboard debug command'));
       }
-      return debugTemplates;
+      return materializeSuggestions(debugTemplates);
     }
 
     return [];
@@ -1519,7 +1950,7 @@ export async function createChatRuntime({
   };
 
   const submit = async (line, onAgentEvent) => {
-    const activeBaseSystemPrompt = baseSystemPrompt;
+    const activeBaseSystemPrompt = buildSystemPromptWithReplyLanguage(baseSystemPrompt, config);
     const activeReplySystemPrompt = await buildSystemPromptWithSoul(baseSystemPrompt, config);
     try {
       await appendInputHistory(line);