@semalt-ai/code 1.8.5 → 1.19.0

package/lib/commands/chat.js

@@ -0,0 +1,403 @@
+'use strict';
+
+// The interactive chat command (cmdChat) and its login flow, extracted from
+// lib/commands.js in Task 1.5. cmdChat builds the session `ctx` (the getter/
+// setter hub) and wires together the extracted chat modules: chat-session
+// (state + dashboard sync + pickers), chat-slash (slash handlers), and chat-turn
+// (the input/agent turn handler). Bodies are unchanged. Runtime-injected deps
+// (config/api/ui/permissions/agent) arrive via `deps`; leaf modules are required
+// directly here as cmdChat did before the split.
+
+const fs = require('fs');
+
+const { CONFIG_PATH, TAG_REGISTRY } = require('../constants');
+const { configShow, isNativeToolsActive } = require('../config');
+const { getSystemPrompt } = require('../prompts');
+const { SessionStorage } = require('../storage');
+const { setUIActive } = require('../tools');
+const { AUDIT_LOG } = require('../audit');
+const { formatToolLine } = require('../ui/format');
+const writerModule = require('../ui/writer');
+const msgs = require('../ui/messages');
+const dbg = require('../debug');
+const { resolveCommand, helpText, commandNames, registerCustomCommands, registerSkills } = require('./registry');
+const { discoverCustomCommands } = require('./custom');
+const { discoverSkills } = require('../skills');
+const { cleanOrphanedToolMessages, reconstructLoadedMessage } = require('./history-utils');
+const { createChatSession } = require('./chat-session');
+const { createSlashHandlers } = require('./chat-slash');
+const { createTurnHandler } = require('./chat-turn');
+const { createMcpManager } = require('../mcp/client');
+
+const LOGIN_POLL_INTERVAL_MS = 2000;
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+function createChatCommand(deps) {
+  const {
+    getConfig, setConfig, permissionManager, ui, apiClient,
+    runAgentLoop, readFileContext, agentExecShell,
+    resolveTokenLimit, ensureDefaultModel, confirmCatastrophicShell,
+    checkpointStore,
+  } = deps;
+  const {
+    BOLD, BG_SELECTED, FG_BLUE, FG_CYAN, FG_DARK, FG_GRAY, FG_GREEN, FG_RED, FG_TEAL, FG_YELLOW, RST,
+    approxTokens, getCols, boxLine, interactiveSelect, createUI,
+  } = ui;
+  const {
+    chatStream, chatSync, dashboardCreateChat, dashboardGetChat, dashboardGetModelForCli,
+    dashboardListChats, dashboardListModels, dashboardLogout, dashboardSaveMessages, dashboardWhoAmI,
+    estimateTokens, getCliLoginStatus, requestCliLogin, setActiveModelProfile,
+  } = apiClient;
+
+  async function cmdChat(opts) {
+    await ensureDefaultModel();
+
+    // Build the three end-of-session artifacts that teardown emits as
+    // scrollback. Returning them as a plain object lets both exit paths
+    // (/exit submit and Ctrl+C onInterrupt) route through writer.teardown,
+    // which is the only place that can append them below the erased live
+    // region in a single atomic write.
+    function buildExitArtifacts() {
+      return {
+        summary: sessionMetrics ? sessionMetrics.summary() : '',
+        resumeHint: currentChatId !== null
+          ? `  ${FG_DARK}Resume this chat: ${FG_CYAN}semalt-code --resume ${currentChatId}${RST}`
+          : '',
+        goodbye: `  ${FG_GRAY}Goodbye!${RST}`,
+      };
+    }
+
+    const { chatHistory, statusBar, inputField, layout, destroy, redrawFixed } = createUI({
+      showThink: opts.showThink || false,
+      onInterrupt: (destroyFn) => {
+        saveSession();
+        destroyFn(buildExitArtifacts());
+        process.exit(0);
+      },
+    });
+
+    setUIActive(true);
+
+    const writer = require('../ui/writer');
+    permissionManager.setUICallbacks({
+      onAddMessage:      (msg)     => chatHistory.addMessage(msg),
+      onRerenderMessage: (id)      => chatHistory.rerenderById(id),
+      onCollapseMessage: (id)      => chatHistory.collapseById(id),
+      onRemoveMessage:   (id)      => chatHistory.removeById(id),
+      // Modal-region API: setModal replaces the modal live band above the
+      // status region; clearModal drops it. Arrow-key redraws go through
+      // setModal only — no scrollback churn. When the picker resolves we
+      // clear the modal and push a single summary line to scrollback.
+      onShowModal: (lines) => writer.setModal(lines),
+      onCloseModal: (summary) => {
+        writer.clearModal();
+        if (summary) chatHistory.addMessage({ role: 'system', content: summary });
+      },
+      onCaptureNavigation: (handler) => {
+        inputField.captureNavigation(handler);
+        return () => inputField.releaseNavigation();
+      },
+      captureSelect: (menu) => inputField.captureSelect(menu),
+    });
+
+    inputField.on('expand', () => chatHistory.toggleLastExpand());
+
+    const cwd = process.cwd();
+    let currentModel = opts.model || getConfig().default_model;
+    let resolvedTokenLimit = await resolveTokenLimit(currentModel);
+    statusBar.setModel(currentModel);
+    // Seed the context indicator with the profile's limit up-front so it
+    // renders "0 / 200,000 tok (0%)" before the first API response, instead
+    // of appearing out of thin air once a turn completes.
+    statusBar.setContextLimit(resolvedTokenLimit);
+    let sessionMetrics = null;
+    // system prompt is prepended fresh on every API call in agent.js — never stored in history
+    let messages = [];
+    let currentChatId = null;
+    let savedUpTo = 0;
+    // The agent loop's per-iteration `formatDebugBlock` runs whenever any
+    // debug mode is active. In simple mode the block is rendered as a TUI
+    // chat bubble (cb.onDebug → addMessage). In file mode emitDebug routes
+    // the block to the debug file instead, keeping the TUI clean.
+    let debugMode = dbg.isActive();
+    // Plan mode (Task 2.5): /plan toggles it; while on, the agent loop withholds
+    // mutating tools until the user approves (toggles it back off). Seeded from
+    // the --plan flag for a plan-first session.
+    let planMode = !!opts.plan;
+
+    // Resolve system prompt override from --system-prompt file if provided
+    let resolvedSystemPrompt = null;
+    if (opts.systemPromptFile) {
+      try {
+        resolvedSystemPrompt = fs.readFileSync(opts.systemPromptFile, 'utf8');
+      } catch (err) {
+        // will be shown after UI initializes
+      }
+    }
+    const storage = new SessionStorage();
+    const sessionStart = Date.now();
+    let session = {
+      id: storage.generateId(),
+      created_at: sessionStart,
+      model: currentModel,
+      messages: [],
+      stats: { total_tokens: 0, duration_sec: 0 },
+    };
+    // Checkpoints & rewind (Task 4.3): align the per-process checkpoint store
+    // with this chat's session id so its checkpoint directory and `/rewind` view
+    // match the session. Done before any turn runs (no captures yet).
+    if (checkpointStore && typeof checkpointStore.setSession === 'function') {
+      checkpointStore.setSession(session.id);
+    }
+    let pendingAction = null;
+    const PAGE_SIZE = 5;
+
+    // MCP manager (Task 3.3). Connects to configured servers on startup and
+    // registers their tools into the shared registry so they dispatch through
+    // the agent loop like built-ins. Connection failures are isolated per-server
+    // and never block chat startup.
+    const mcpManager = createMcpManager({
+      getConfig,
+      logger: (m) => chatHistory.addMessage({ role: 'system', content: `⚠ ${m}` }),
+    });
+
+    // Shared chat-session context handed to the extracted chat modules. Mutable
+    // fields are exposed via getters/setters backed by the locals above, so the
+    // cmdChat shell keeps using bare names while moved module bodies read/write
+    // through ctx. The per-group functions are attached onto ctx below.
+    const ctx = {
+      get messages() { return messages; }, set messages(v) { messages = v; },
+      get currentModel() { return currentModel; }, set currentModel(v) { currentModel = v; },
+      get currentChatId() { return currentChatId; }, set currentChatId(v) { currentChatId = v; },
+      get savedUpTo() { return savedUpTo; }, set savedUpTo(v) { savedUpTo = v; },
+      get resolvedTokenLimit() { return resolvedTokenLimit; }, set resolvedTokenLimit(v) { resolvedTokenLimit = v; },
+      get resolvedSystemPrompt() { return resolvedSystemPrompt; }, set resolvedSystemPrompt(v) { resolvedSystemPrompt = v; },
+      get debugMode() { return debugMode; }, set debugMode(v) { debugMode = v; },
+      get planMode() { return planMode; }, set planMode(v) { planMode = v; },
+      get pendingAction() { return pendingAction; }, set pendingAction(v) { pendingAction = v; },
+      get sessionMetrics() { return sessionMetrics; }, set sessionMetrics(v) { sessionMetrics = v; },
+      get session() { return session; }, set session(v) { session = v; },
+      get resolveExit() { return resolveExit; },
+      // Multimodal image input (Task 5.4): images staged by /image, consumed and
+      // cleared by the next user turn (chat-turn.js).
+      pendingImages: [],
+      // stable handles / deps / helpers
+      opts, cwd, storage, sessionStart, PAGE_SIZE, mcpManager,
+      chatHistory, statusBar, inputField, writer, writerModule, destroy, redrawFixed, buildExitArtifacts,
+      getConfig, setConfig, permissionManager, runAgentLoop, readFileContext, agentExecShell, checkpointStore,
+      approxTokens, getCols, boxLine, interactiveSelect, msgs, dbg, fs,
+      resolveTokenLimit, ensureDefaultModel, confirmCatastrophicShell, loginFlow: _loginFlow,
+      helpText, resolveCommand, configShow, getSystemPrompt, isNativeToolsActive,
+      TAG_REGISTRY, formatToolLine, estimateTokens, AUDIT_LOG,
+      cleanOrphanedToolMessages, reconstructLoadedMessage,
+      chatStream, chatSync, dashboardCreateChat, dashboardGetChat, dashboardGetModelForCli,
+      dashboardListChats, dashboardListModels, dashboardLogout, dashboardWhoAmI, dashboardSaveMessages,
+      BOLD, BG_SELECTED, FG_BLUE, FG_CYAN, FG_DARK, FG_GRAY, FG_GREEN, FG_RED, FG_TEAL, FG_YELLOW, RST,
+    };
+
+    // Session/state management (local + dashboard history sync, pickers).
+    const chatSessionFns = createChatSession(ctx);
+    Object.assign(ctx, chatSessionFns);
+    const {
+      refreshInputSearchItems, saveSession,
+      displayLoadedMessages, seedContextFromMessages, emitCleanupWarning,
+    } = chatSessionFns;
+
+    refreshInputSearchItems();
+
+    // Banner — emit once as scrollback above the live region. In the
+    // bottom-anchored live-region TUI, scrollback flows into terminal
+    // scrollback naturally, so no absolute positioning or scroll-region
+    // trickery is needed here.
+    if (layout) {
+      const w = Math.min(getCols() - 4, 60);
+      const banner = [
+        ``,
+        `  ${FG_DARK}╭${'─'.repeat(w + 1)}╮${RST}`,
+        boxLine('', w),
+        boxLine(`${FG_TEAL}${BOLD}◆ Semalt.AI${RST}`, w),
+        boxLine(`${FG_GRAY}Self-hosted AI coding assistant${RST}`, w),
+        boxLine('', w),
+        `  ${FG_DARK}╰${'─'.repeat(w + 1)}╯${RST}`,
+        ``,
+      ].join('\n');
+      writer.scrollback(banner);
+      redrawFixed();
+    }
+
+    // Welcome message
+    chatHistory.addMessage({
+      role: 'system',
+      content: `◆ Semalt.AI  ·  ${currentModel}  ·  ${cwd}\nType /help for commands.`,
+    });
+
+    // Fail-loud (memory truncation): warn once at startup if a loaded project
+    // memory file (AGENTS.md/CLAUDE.md) was truncated at the cap — path, loaded
+    // vs original size, and dropped %. The content still loads normally; this is
+    // a user-facing chat system line only, never injected into the model prompt.
+    try {
+      const { loadProjectMemory, memoryTruncationWarnings } = require('../memory');
+      for (const w of memoryTruncationWarnings(loadProjectMemory({ cwd }))) {
+        chatHistory.addMessage({ role: 'system', content: w });
+      }
+    } catch { /* best-effort; never block chat startup */ }
+
+    // Discover & register Markdown-defined custom slash commands (Task 3.1). The
+    // registry stays the single source of truth — customs are registered into it
+    // so resolveCommand/completion/help see them. Built-ins win on collision;
+    // project overrides global (resolved in discoverCustomCommands). Invocation
+    // is handled inline by the turn handler: the rendered template is submitted
+    // to the agent as a user prompt, never executed as code.
+    try {
+      const discovered = discoverCustomCommands({ cwd });
+      const { registered, warnings } = registerCustomCommands(discovered);
+      for (const w of warnings) chatHistory.addMessage({ role: 'system', content: `⚠ ${w}` });
+      if (registered.length) {
+        chatHistory.addMessage({
+          role: 'system',
+          content: `✓ Loaded ${registered.length} custom command(s): ${registered.map((c) => c.name).join(', ')}`,
+        });
+      }
+    } catch { /* custom commands are best-effort; never block chat startup */ }
+
+    // Discover & register skills (Task 3.5). Only metadata (name + description)
+    // is registered here and injected into the system prompt — the body is read
+    // on demand when the skill is invoked (progressive disclosure), so the prompt
+    // stays lean. Built-ins win on collision; project overrides global (resolved
+    // in discoverSkills). Invocation is handled inline by the turn handler.
+    try {
+      const discovered = discoverSkills({ cwd });
+      const { registered, warnings } = registerSkills(discovered);
+      for (const w of warnings) chatHistory.addMessage({ role: 'system', content: `⚠ ${w}` });
+      if (registered.length) {
+        chatHistory.addMessage({
+          role: 'system',
+          content: `✓ Loaded ${registered.length} skill(s): ${registered.map((s) => s.name).join(', ')}`,
+        });
+      }
+    } catch { /* skills are best-effort; never block chat startup */ }
+
+    // Connect configured MCP servers and register their tools (Task 3.3). No-op
+    // when none are configured. Best-effort: a failure to load the SDK or reach a
+    // server is reported but never blocks chat startup.
+    try {
+      const cfgServers = (getConfig().mcp && getConfig().mcp.servers) || {};
+      if (Object.keys(cfgServers).length) {
+        const status = await mcpManager.connectAll();
+        const connected = status.filter((s) => s.state === 'connected');
+        const toolCount = connected.reduce((n, s) => n + s.tools.length, 0);
+        if (connected.length) {
+          chatHistory.addMessage({
+            role: 'system',
+            content: `✓ MCP: connected ${connected.length} server(s), ${toolCount} tool(s). Use /mcp for status.`,
+          });
+        }
+      }
+    } catch (err) {
+      chatHistory.addMessage({ role: 'system', content: `⚠ MCP init failed: ${err.message}`, isError: true });
+    }
+
+    if (opts.systemPromptFile && resolvedSystemPrompt === null) {
+      chatHistory.addMessage({ role: 'system', content: `✗ Could not read system prompt file: ${opts.systemPromptFile}`, isError: true });
+    } else if (opts.systemPromptFile && resolvedSystemPrompt !== null) {
+      chatHistory.addMessage({ role: 'system', content: `✓ Using system prompt from: ${opts.systemPromptFile}` });
+    }
+
+    // --resume: load previous chat
+    if (opts.resume) {
+      const resumeId = parseInt(opts.resume, 10);
+      if (!isNaN(resumeId)) {
+        try {
+          const chatData = await dashboardGetChat(resumeId);
+          const loaded = chatData && chatData.messages ? chatData.messages : [];
+          for (const m of loaded) messages.push(reconstructLoadedMessage(m));
+          const cleanup = cleanOrphanedToolMessages(messages);
+          messages = cleanup.messages;
+          currentChatId = resumeId;
+          savedUpTo = messages.length;
+          const title = chatData.chat && chatData.chat.title ? chatData.chat.title : `#${resumeId}`;
+          displayLoadedMessages(loaded);
+          chatHistory.addMessage({ role: 'system', content: `✓ Resumed: ${title} (${loaded.length} messages)` });
+          emitCleanupWarning(cleanup);
+          seedContextFromMessages();
+        } catch (error) {
+          chatHistory.addMessage({ role: 'system', content: `✗ Could not resume chat: ${error.message}`, isError: true });
+        }
+      }
+    }
+
+    let resolveExit;
+    const exitPromise = new Promise((r) => { resolveExit = r; });
+
+
+    statusBar.update('idle');
+
+    // Slash-command handlers (lib/commands/chat-slash.js), keyed by the canonical
+    // registry name. The parity check below guarantees registry ↔ handler stay
+    // in lockstep.
+    const slashHandlers = createSlashHandlers(ctx);
+
+    // Parity guard: every registry command must have a handler here, and every
+    // handler must correspond to a registry command. Adding a command is then a
+    // single registry entry + its handler — a missing pair fails loudly at startup.
+    {
+      const handlerNames = new Set(Object.keys(slashHandlers));
+      const registryNames = commandNames();
+      for (const name of registryNames) {
+        if (!handlerNames.has(name)) throw new Error(`Slash command "${name}" is in the registry but has no handler`);
+      }
+      for (const name of handlerNames) {
+        if (!registryNames.includes(name)) throw new Error(`Slash handler "${name}" has no registry entry`);
+      }
+    }
+
+    // The turn handler (picker text-fallback, slash dispatch, agent run + TUI
+    // callbacks) lives in lib/commands/chat-turn.js.
+    inputField.onSubmit(createTurnHandler(ctx, slashHandlers));
+
+    // Wait until user exits. The /exit submit handler already ran
+    // destroy(buildExitArtifacts()), so the session summary, resume hint,
+    // and goodbye have been emitted as scrollback inside teardown's
+    // single atomic write. Nothing more to print here.
+    await exitPromise;
+    setUIActive(false);
+    saveSession();
+    try { await mcpManager.shutdown(); } catch { /* best-effort cleanup */ }
+  }
+
+  async function _loginFlow(chatHistory, statusBar) {
+    let loginRequest;
+    try { loginRequest = await requestCliLogin(); }
+    catch (err) {
+      chatHistory.addMessage({ role: 'system', content: `✗ Login failed: ${err.message}`, isError: true });
+      return;
+    }
+    chatHistory.addMessage({ role: 'system', content: `Open this URL to authorize:\n  ${loginRequest.verification_url}\n\nWaiting for confirmation...` });
+    statusBar.update('waiting', 'Waiting for browser auth...');
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < LOGIN_TIMEOUT_MS) {
+      await new Promise((r) => setTimeout(r, LOGIN_POLL_INTERVAL_MS));
+      let status;
+      try { status = await getCliLoginStatus(loginRequest.id, loginRequest.hash); }
+      catch (err) {
+        if (err.statusCode === 404 || err.statusCode === 410) { chatHistory.addMessage({ role: 'system', content: '✗ Login token is no longer valid.', isError: true }); return; }
+        continue;
+      }
+      if (status.status === 'authorized') {
+        const config = getConfig();
+        setConfig({ ...config, dashboard_url: config.dashboard_url, auth_token: loginRequest.token });
+        chatHistory.addMessage({ role: 'system', content: `✓ CLI token saved to ${CONFIG_PATH}` });
+        return;
+      }
+      if (status.status === 'expired') {
+        chatHistory.addMessage({ role: 'system', content: '✗ Login token expired. Run /login again.', isError: true });
+        return;
+      }
+    }
+    chatHistory.addMessage({ role: 'system', content: '⚠ Login timed out.' });
+  }
+
+  return { cmdChat };
+}
+
+module.exports = { createChatCommand };

package/lib/commands/custom.js

@@ -0,0 +1,157 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Custom slash commands from Markdown (Task 3.1).
+// ---------------------------------------------------------------------------
+//
+// Users define workflows as Markdown files — no code. The filename is the
+// command name (`review.md` → `/review`). Optional YAML-ish frontmatter
+// (`description`, `argument-hint`, `aliases`) configures the command; the body
+// is the prompt template. Discovered commands are registered into the existing
+// slash-command registry (lib/commands/registry.js) so resolution, completion,
+// and /help all see them through one source of truth.
+//
+// Discovery scans two locations, lowest precedence first:
+//   1. global   ~/.semalt-ai/commands/*.md
+//   2. project  <nearest>/.semalt/commands/*.md  (upward from cwd, bounded by
+//               the repo root — the .git holder — mirroring Task 2.2 config
+//               discovery)
+// On a name collision project wins over global. Built-ins always win over both
+// (enforced at registration time in registry.js).
+//
+// Rendering substitutes `$ARGUMENTS` (the full argument string) and `$1`/`$2`/…
+// (whitespace-split positionals). The rendered text is submitted to the agent
+// as an ordinary user prompt — never executed as code.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Walk up from startDir for the nearest `.semalt/commands` directory, bounded
+// by the repo root (the directory holding `.git` is the last one checked).
+// Mirrors Task 2.2's findProjectConfigPath. Returns the directory path or null.
+function findProjectCommandsDir(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(dir, '.semalt', 'commands');
+    try { if (fs.statSync(candidate).isDirectory()) return candidate; } catch {}
+    let atRepoRoot = false;
+    try { atRepoRoot = fs.existsSync(path.join(dir, '.git')); } catch {}
+    if (atRepoRoot) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+// Split a frontmatter alias value into a list. Accepts an inline YAML flow list
+// (`[a, b]`) or a comma-separated string (`a, b`), with optional quotes.
+function parseAliasList(val) {
+  if (!val) return [];
+  let s = val.trim();
+  if (s.startsWith('[') && s.endsWith(']')) s = s.slice(1, -1);
+  return s
+    .split(',')
+    .map((a) => a.trim().replace(/^['"]|['"]$/g, '').trim())
+    .filter(Boolean);
+}
+
+// Parse optional frontmatter delimited by `---` lines at the very top of the
+// file. Only `description`, `argument-hint`, and `aliases` are recognized;
+// unknown keys are ignored. Returns { meta, body }. With no frontmatter the
+// whole text is the body. Pure.
+function parseFrontmatter(text) {
+  const meta = { description: '', argumentHint: '', aliases: [] };
+  if (typeof text !== 'string') return { meta, body: '' };
+  const src = text.replace(/^/, '').replace(/\r\n/g, '\n');
+  const m = /^---\n([\s\S]*?)\n---[ \t]*\n?/.exec(src);
+  if (!m) return { meta, body: src };
+  const fmBody = m[1];
+  const body = src.slice(m[0].length);
+  for (const rawLine of fmBody.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim().toLowerCase();
+    let val = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, '');
+    if (key === 'description') meta.description = val;
+    else if (key === 'argument-hint' || key === 'argument_hint') meta.argumentHint = val;
+    else if (key === 'aliases' || key === 'alias') meta.aliases = parseAliasList(line.slice(idx + 1).trim());
+  }
+  return { meta, body };
+}
+
+// Substitute `$ARGUMENTS` (full argument string) and `$1`/`$2`/… (whitespace-
+// split positionals) into a template. Done in a single pass so text injected by
+// `$ARGUMENTS` is never re-expanded. Unprovided positionals render as empty.
+// Pure.
+function renderTemplate(template, argString) {
+  const args = String(argString == null ? '' : argString).trim();
+  const positionals = args.length ? args.split(/\s+/) : [];
+  return String(template == null ? '' : template).replace(
+    /\$ARGUMENTS\b|\$(\d+)/g,
+    (match, digits) => {
+      if (digits === undefined) return args; // $ARGUMENTS
+      const i = parseInt(digits, 10) - 1;
+      return i >= 0 && i < positionals.length ? positionals[i] : '';
+    },
+  );
+}
+
+// Read every *.md command file in `dir` into a spec list. Filenames are sorted
+// for deterministic order. Unreadable / non-file entries are skipped.
+function loadCommandsFromDir(dir, source) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return out; }
+  for (const entry of entries.slice().sort()) {
+    if (!/\.md$/i.test(entry)) continue;
+    const filePath = path.join(dir, entry);
+    let raw;
+    try {
+      if (!fs.statSync(filePath).isFile()) continue;
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch { continue; }
+    const base = entry.replace(/\.md$/i, '');
+    if (!base) continue;
+    const { meta, body } = parseFrontmatter(raw);
+    const aliases = meta.aliases.map((a) => (a.startsWith('/') ? a : '/' + a));
+    out.push({
+      name: '/' + base,
+      aliases,
+      description: meta.description,
+      argumentHint: meta.argumentHint,
+      template: body,
+      source,
+      filePath,
+    });
+  }
+  return out;
+}
+
+// Discover Markdown-defined commands for a (home, cwd). Global commands load
+// first, then the nearest project commands; on a name collision project wins.
+// Returns an ordered, de-duplicated spec list (project entries first so they
+// take precedence). fs reads only; home/cwd are injectable for tests.
+function discoverCustomCommands(opts = {}) {
+  const home = opts.home || os.homedir();
+  const cwd = opts.cwd || process.cwd();
+  const global = loadCommandsFromDir(path.join(home, '.semalt-ai', 'commands'), 'global');
+  const projectDir = findProjectCommandsDir(cwd);
+  const project = projectDir ? loadCommandsFromDir(projectDir, 'project') : [];
+  const byName = new Map();
+  for (const c of project) if (!byName.has(c.name)) byName.set(c.name, c);
+  for (const c of global) if (!byName.has(c.name)) byName.set(c.name, c);
+  return Array.from(byName.values());
+}
+
+module.exports = {
+  findProjectCommandsDir,
+  parseAliasList,
+  parseFrontmatter,
+  renderTemplate,
+  loadCommandsFromDir,
+  discoverCustomCommands,
+};

package/lib/commands/history-utils.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// Pure helpers for loading / sanitising saved-chat message history. No I/O, no
+// UI, no config — extracted from lib/commands.js in Task 1.5 so they can be unit
+// tested and reused. Bodies are unchanged.
+
+// Drop assistant.tool_calls and role:tool messages whose ids don't pair up.
+// A loaded chat may contain role:tool with empty/missing tool_call_id (legacy
+// rows, dropped fields in transit) or assistant.tool_calls without a matching
+// tool response (truncated turn). Either side without its partner produces a
+// 400 from strict providers like MiniMax — the validator in api.js will throw
+// — so we strip both sides of the orphan pair before sending.
+function cleanOrphanedToolMessages(msgs) {
+  const calledIds = new Set();
+  const respondedIds = new Set();
+  for (const m of msgs) {
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls)) {
+      for (const tc of m.tool_calls) {
+        if (tc && tc.id) calledIds.add(tc.id);
+      }
+    } else if (m.role === 'tool' && m.tool_call_id) {
+      respondedIds.add(m.tool_call_id);
+    }
+  }
+  const paired = new Set();
+  for (const id of calledIds) if (respondedIds.has(id)) paired.add(id);
+
+  let droppedTool = 0;
+  let droppedAssistantCalls = 0;
+  let droppedAssistantMsgs = 0;
+  const out = [];
+  for (const m of msgs) {
+    if (m.role === 'tool') {
+      if (!m.tool_call_id || !paired.has(m.tool_call_id)) { droppedTool++; continue; }
+      out.push(m);
+    } else if (m.role === 'assistant' && Array.isArray(m.tool_calls)) {
+      const kept = m.tool_calls.filter((tc) => tc && tc.id && paired.has(tc.id));
+      droppedAssistantCalls += m.tool_calls.length - kept.length;
+      const hasContent = typeof m.content === 'string' && m.content.trim().length > 0;
+      if (kept.length === 0 && !hasContent) { droppedAssistantMsgs++; continue; }
+      const next = { ...m };
+      if (kept.length > 0) next.tool_calls = kept;
+      else delete next.tool_calls;
+      out.push(next);
+    } else {
+      out.push(m);
+    }
+  }
+  return { messages: out, droppedTool, droppedAssistantCalls, droppedAssistantMsgs };
+}
+
+function reconstructLoadedMessage(m) {
+  const msg = { role: m.role, content: m.content };
+  if (m.tool_call_id !== undefined && m.tool_call_id !== null && m.tool_call_id !== '') {
+    msg.tool_call_id = m.tool_call_id;
+  }
+  if (Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+    msg.tool_calls = m.tool_calls;
+  }
+  return msg;
+}
+
+module.exports = {
+  cleanOrphanedToolMessages,
+  reconstructLoadedMessage,
+};