shmakk 1.2.0 → 1.2.1

package/src/agent.js

@@ -7,13 +7,23 @@
 
 const fs = require('fs');
 const path = require('path');
-const { makeClient, modelFor, isConfigured } = require('./llm');
+const { makeClient, modelFor, isConfigured, getDeepSeekOptions } = require('./llm');
+const {
+  sanitizeAssistantContent,
+  isLeakedToolMarkup,
+  mightBecomeInternalMarkup,
+  MUTATION_TOOLS,
+  isMutationTool,
+  hashArgs,
+  DSML_RETRY_USER_MESSAGE,
+} = require('./guard');
 const { buildOrRefreshIndex, relevantSubgraph } = require('./workspace-index');
 const { renderActiveSkillForPrompt } = require('./skills');
 const { renderRulesForPrompt } = require('./rules');
 const { renderMemoryForPrompt } = require('./memory');
 const sessionSearch = require('./session-search');
 const promptCache = require('./prompt-cache');
+const audit = require('./audit');
 const { buildSystemPrompt } = require('./system-prompt');
 const {
   TOOLS,
@@ -74,6 +84,8 @@ function clearTaskJournal(root) {
   try { fs.rmSync(journalPath(root), { force: true }); } catch {}
 }
 
+const { renderBlock } = require('./markdown');
+
 // Tiny spinner so the user sees "the agent is thinking" while we wait on
 // the model. Erased when stop() is called.
 function startSpinner(write, label = 'thinking') {
@@ -94,19 +106,9 @@ function startSpinner(write, label = 'thinking') {
 
 function dim(s, enabled = true) { return enabled ? `\x1b[2m${s}\x1b[0m` : s; }
 
-function highlightCodeBlocks(text, enabled = true) {
-  const src = String(text || '');
-  if (!enabled) return src;
-  return src.replace(/```([a-zA-Z0-9_-]*)\n([\s\S]*?)```/g, (_m, lang, code) => {
-    const head = `\x1b[36m\x1b[1m${lang || 'code'}\x1b[0m`;
-    const body = `\x1b[90m${code.replace(/\n$/, '')}\x1b[0m`;
-    return `${head}\n${body}`;
-  }).replace(/\u0000\u0000\u0000/g, '```');
-}
-
 // ── Main agent entry point ──────────────────────────────────────────────────
 
-async function runAgent({ input, roots, glossary, confirmTool, write, signal, history = [], profile = 'balanced', colors = true, voiceMode = false, specialistHint = null, mcpManager = null, requireToolUse = false }) {
+async function runAgent({ input, roots, glossary, confirmTool, write, signal, history = [], profile = 'balanced', colors = true, markdown = true, voiceMode = false, specialistHint = null, mcpManager = null, requireToolUse = false }) {
   // roots: array of allowed workspace roots (first is the primary cwd).
   // history: prior conversation turns (assistant/user/tool). System prompt
   // is rebuilt fresh each call so the current cwd is always accurate.
@@ -140,6 +142,40 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
 
   persistJournal('running');
   const promptCacheEnabled = String(process.env.SHMAKK_PROMPT_CACHE || '1') !== '0';
+
+  // ── Per-turn mutation-approval state ───────────────────────────────────
+  // Every mutation tool call must be individually approved.  If the user
+  // denies ANY mutation in a turn, ALL pending mutations from that turn are
+  // invalidated.  This prevents the agent from executing an edit after the
+  // user said no.
+  const turnApprovals = new Map();   // toolCallId → { approved, argsHash, expiresAt }
+  let turnDenied = false;
+
+  function clearTurnApprovals() {
+    turnApprovals.clear();
+    turnDenied = false;
+  }
+
+  function wrapConfirmTool(baseConfirm) {
+    if (!baseConfirm) return null;
+    return async ({ name, args, safety, description }) => {
+      // If this turn has already been denied, reject all mutation tools.
+      if (turnDenied && isMutationTool(name)) {
+        return false;
+      }
+      const ok = await baseConfirm({ name, args, safety, description });
+      if (!ok && isMutationTool(name)) {
+        turnDenied = true;
+        // Invalidate any pre-approved mutation calls from this turn.
+        for (const [id, a] of turnApprovals) {
+          if (isMutationTool(a.toolName)) a.approved = false;
+        }
+      }
+      return ok;
+    };
+  }
+
+  const guardedConfirm = wrapConfirmTool(confirmTool);
   const maxDiscoveryCallsPerRound = Math.max(
     1,
     Number(process.env.SHMAKK_MAX_DISCOVERY_CALLS_PER_ROUND)
@@ -152,8 +188,44 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     const graph = relevantSubgraph(idx, input, 12, 1);
     if (graph.length) {
       indexHint = `\n\nCompact relevant subgraph for this task:\n${graph.map((n) => `- ${n.path} [role=${n.role}] symbols=${n.symbols.slice(0, 4).join(', ') || '-'} edges=${n.edges.slice(0, 4).join(', ') || '-'} snippet=${(n.snippet || []).slice(0, 3).join(' | ') || '-'}`).join('\n')}\nStart with these files and their immediate dependencies before broad exploration. Prefer these snippet cues before reading full files.`;
+    } else {
+      // Fallback: no query hits — give the agent a top-level map so it can
+      // start exploring without waiting for the user to say "read the dir".
+      const files = idx.files || {};
+      const configHints = [];
+      const topDirs = new Set();
+      const topFiles = new Set();
+      const allKeys = Object.keys(files);
+      // Determine which top-level names are directories vs files by checking
+      // whether they appear as a prefix for deeper entries.
+      const hasSlash = new Map(); // topName -> true if dir, false if top-level file
+      for (const rel of allKeys) {
+        const top = rel.split('/')[0];
+        if (!top || top.startsWith('.') || top === 'node_modules') continue;
+        if (rel === top) {
+          // A top-level file (no / in path) — only mark if not already known as dir
+          if (!hasSlash.has(top)) hasSlash.set(top, false);
+        } else {
+          // e.g. "src/agent.js" — top="src", this is a directory
+          hasSlash.set(top, true);
+        }
+        const base = rel.split('/').pop();
+        if (base === 'package.json' || base === 'README.md' || base === 'tsconfig.json') {
+          const f = files[rel];
+          configHints.push(`- ${rel} [role=${f.role}] snippet=${(f.snippet || []).slice(0, 1).join(' | ') || '-'}`);
+        }
+      }
+      for (const [name, isDir] of hasSlash) {
+        if (isDir) topDirs.add(name); else topFiles.add(name);
+      }
+      const topLines = [];
+      if (topDirs.size) topLines.push(`Top-level dirs: ${[...topDirs].sort().join(', ')}`);
+      if (topFiles.size) topLines.push(`Top-level files: ${[...topFiles].sort().join(', ')}`);
+      indexHint = `\n\nWorkspace structure (no query hits — start by exploring relevant directories):\n${topLines.join('\n')}${configHints.length ? '\n' + configHints.join('\n') : ''}\nUse list_dir to explore further.`;
     }
-  } catch {}
+  } catch (e) {
+    indexHint = `\n\nWorkspace index unavailable (${e.message || 'unknown error'}). Start with list_dir of the root directory to discover the project structure.`;
+  }
 
   // Build MCP tool hint for system prompt if MCP tools are available
   let mcpToolHint = null;
@@ -219,6 +291,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
 
   // Tool loop. Streams content as it arrives; prints each tool call.
   let producedAnything = false;
+  const runState = { _dsmlLeakRetries: 0 };
   for (let i = 0; i < dynamicToolBudget; i++) {
     if (signal && signal.aborted) return messages.slice(1);
 
@@ -248,6 +321,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
         model: modelFor('agent'),
         messages, tools: allTools, tool_choice: toolChoiceForThisIter,
         temperature: 0, stream: true,
+        ...getDeepSeekOptions('tool_loop'),
       }, { signal });
     } catch (e) {
       stop();
@@ -258,12 +332,39 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     let reasoningContent = '';
     const toolCalls = []; // [{id, type:'function', function:{name, arguments}}]
     let spinnerStopped = false;
+    let streamingContentOk = true;  // flipped to false on leak
     try {
       for await (const chunk of stream) {
+        // Check for abort between chunks.
+        if (signal && signal.aborted) {
+          streamingContentOk = false;
+          break;
+        }
         const delta = chunk.choices?.[0]?.delta;
         if (!delta) continue;
         if (delta.content) {
-          content += delta.content;
+          // ── Streaming guard: buffer tokens before flushing ──────────
+          // We never append tokens directly to visible chat state.
+          // Small lookbehind buffer so partial strings like "<｜｜DSML"
+          // are not flushed before we can detect them.
+          const token = delta.content;
+          content += token;
+
+          // Check the trailing portion for partial DSML prefixes.
+          // Only check the last ~80 chars — enough to catch any prefix.
+          const tail = content.slice(-80);
+          if (mightBecomeInternalMarkup(tail)) {
+            // Hold back — don't flush yet, the next token may complete
+            // a benign string or reveal leaked markup.
+            continue;
+          }
+
+          // If we have accumulated content and there's no dangerous
+          // prefix in the tail, flush it now.
+          if (content.length > 0 && !mightBecomeInternalMarkup(content.slice(-80))) {
+            // Nothing to flush separately here — the spinner handles
+            // the "thinking" display.  We just keep accumulating.
+          }
         }
         if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length) {
           reasoningContent += delta.reasoning_content;
@@ -284,6 +385,54 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
       if (!spinnerStopped) stop();
     }
 
+    // ── DSML leak detection (after stream completes) ────────────────────
+    if (content && isLeakedToolMarkup(content)) {
+      const sanitized = sanitizeAssistantContent(content);
+      // Log the leak but do NOT persist raw content.
+      audit.append({
+        kind: 'dsml-leak',
+        model: modelFor('agent'),
+        leakedMarkupDetected: true,
+        retried: false,
+      });
+
+      // If this is the first leak in this turn, retry once with safer settings.
+      // We inject a user message telling the model not to emit DSML and re-run
+      // the current iteration.
+      const RETRY_MAX = 1;
+      if (!runState._dsmlLeakRetries) runState._dsmlLeakRetries = 0;
+
+      if (runState._dsmlLeakRetries < RETRY_MAX) {
+        runState._dsmlLeakRetries += 1;
+
+        // Remove the last user message (the one that triggered this turn)
+        // and replace it with the retry instruction so we don't grow history.
+        // Find the last user message index.
+        let lastUserIdx = -1;
+        for (let mi = messages.length - 1; mi >= 0; mi--) {
+          if (messages[mi].role === 'user') { lastUserIdx = mi; break; }
+        }
+        if (lastUserIdx >= 0) {
+          messages.splice(lastUserIdx, 1);
+        }
+        messages.push(DSML_RETRY_USER_MESSAGE);
+
+        // Disable thinking for this retry.
+        process.env._SHMAKK_FORCE_NO_THINKING = '1';
+        i--; // re-spend this iteration
+        audit.append({ kind: 'dsml-leak-retry', model: modelFor('agent') });
+        continue; // re-enter the tool loop
+      }
+
+      // Max retries exceeded — strip and show what we can.
+      content = sanitized.visibleText;
+      if (!content) {
+        write(dim('[shmakk] response contained only leaked tool markup — blocked.', colors) + '\n');
+        clearTaskJournal(roots[0]);
+        return messages.slice(1);
+      }
+    }
+
     const fallbackActions = toolCalls.length ? [] : [
       ...parseFallbackActions(content),
       ...parseXmlFallbackActions(content),
@@ -329,7 +478,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     // No tools → done.
     if (!normalizedToolCalls.length) {
       if (content) {
-        write(highlightCodeBlocks(content, colors));
+        write(renderBlock(content, { enabled: markdown, colors }));
         if (!content.endsWith('\n')) write('\n');
         producedAnything = true;
         if (promptCacheEnabled && cacheKey) {
@@ -368,7 +517,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
       if (canUseCache && toolResultCache.has(cacheKey)) {
         result = toolResultCache.get(cacheKey);
       } else {
-        result = await dispatchTool(c.function.name, args, roots, confirmTool, signal, mcpManager);
+        result = await dispatchTool(c.function.name, args, roots, guardedConfirm, signal, mcpManager);
         if (canUseCache && !result?.error) toolResultCache.set(cacheKey, result);
         iterProgress = true;
       }
@@ -419,11 +568,22 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
       temperature: 0,
       tool_choice: 'none',
       stream: false,
+      ...getDeepSeekOptions('tool_loop'),
     }, { signal });
     const finalText = final.choices?.[0]?.message?.content || '';
     if (finalText) {
-      write(finalText);
-      if (!finalText.endsWith('\n')) write('\n');
+      // ── DSML leak guard (same as the main loop) ──────────────────────
+      const finalSanitized = sanitizeAssistantContent(finalText);
+      const displayText = finalSanitized.hadInternalLeak
+        ? finalSanitized.visibleText
+        : finalText;
+      if (displayText) {
+        write(renderBlock(displayText, { enabled: markdown, colors }));
+        if (!displayText.endsWith('\n')) write('\n');
+      }
+      if (finalSanitized.hadInternalLeak) {
+        audit.append({ kind: 'dsml-leak-finalize', model: modelFor('agent'), leakedMarkupDetected: true });
+      }
       clearTaskJournal(roots[0]);
       return messages.slice(1);
     }

package/src/cli.js

@@ -27,7 +27,9 @@ function parseArgs(argv) {
     profile: null,
     profileSet: null,
     colors: null,
+    markdown: null,
     endpoint: null,
+    modelRecommendation: false,
     voice: false,
     stt: false,
     tts: false,
@@ -39,6 +41,7 @@ function parseArgs(argv) {
     voiceSilenceStartSec: null,
     voicePadStartSec: null,
     ttsVoice: null,
+    notify: false,
     completion: null,
     unknown: [],
   };
@@ -93,9 +96,12 @@ function parseArgs(argv) {
       case '--voice-silence-start-sec': opts.voiceSilenceStartSec = argv[++i] || null; break;
       case '--voice-pad-start-sec': opts.voicePadStartSec = argv[++i] || null; break;
       case '--tts-voice': opts.ttsVoice = argv[++i] || null; break;
+      case '--notify': opts.notify = true; break;
       case '--completion': opts.completion = argv[++i] || null; break;
       case '--colors': opts.colors = argv[++i] || null; break;
+      case '--markdown': opts.markdown = argv[++i] || null; break;
       case '--endpoint': opts.endpoint = argv[++i] || null; break;
+      case '--model-recommendation': opts.modelRecommendation = true; break;
       default: opts.unknown.push(a);
     }
   }
@@ -104,95 +110,196 @@ function parseArgs(argv) {
 
 const HELP = `shmakk - AI-supervised terminal wrapper
 
-Usage:
-  shmakk                          Launch in auto mode
-  shmakk --review                 Launch in review mode (confirm every AI action)
-  shmakk --yes-files              Auto-accept AI file writes, edits, and directory creation
-  shmakk --update-command-glossary
-                                  Scan PATH and build local command glossary
-  shmakk --help                   Show this help
-  shmakk --build-history [files...]
-                                  Parse shell history files and build command
-                                  frequency map for better corrections.
-                                  Auto-detects bash/zsh/fish history if no
-                                  files given.
-
-Control (run from inside an shmakk session):
-  shmakk --status                 Show whether this terminal is inside shmakk
-  shmakk --stats                  Show session/task stats (journal, audit, active skill)
-  shmakk --compact                Compact context by clearing conversation + task journal
-  shmakk --load-skill <name>      Load a Claude/Codex-style skill into shmakk workspace state
-  shmakk --install-skill <url>    Download skill markdown from URL, validate, and load
-  shmakk -G, --global             With --load-skill or --install-skill, use global (~/.config/shmakk) instead of workspace
-  shmakk --list-skills            List all registered skills (workspace + global)
-  shmakk --skill-status           Show active skill and registry status (workspace + global)
-  shmakk --unload-skill <name>    Remove skill from whichever registry has it
-  shmakk --show-plan              Show current plan status (tasks and progress)
-  shmakk --mcp-status             Show configured MCP servers and their tools
-  shmakk --resume-status          Show task journal summary for resume continuity
-  shmakk --exit                   Cleanly exit the parent shmakk
-  shmakk --restart                Restart the inner shell (preserves window)
-  shmakk --reset                  Clear the AI conversation history (keep session)
-  shmakk --profile-set <name>     Switch profile and restart (tiny|balanced|deep|builder|large-app)
-  shmakk --colors <true|false>    Enable or disable ANSI colors + code highlighting
-
-Optional:
-  --no-ai                         Disable AI entirely (pure passthrough)
-  --no-correction                 Disable command correction
-  --yes-files                     Auto-accept write_file, edit_file, and make_dir in auto mode
-  --workspace <path>              Override workspace root
-  --profile <name>                Startup profile: tiny|balanced|deep|builder|large-app
-  --endpoint <name>               Use endpoint preset from ~/.config/shmakk/endpoints.js
-  --colors <true|false>           Toggle colored logs and code-block highlighting
-  --debug                         Verbose logging to stderr
-  --print-config                  Print resolved configuration and exit
-
-Speech-to-Text / Text-to-Speech (VAD-based, no hotkeys):
-  --sts                           Speech-to-Speech: always-on mic + TTS responses
-  --stt                           Speech-to-Text: mic → text input (no TTS)
-  --tts                           Text-to-Speech: text input → spoken responses
-  --voice-language <code>         Language hint (e.g., en, es, fr)
-  --voice-max-sec <sec>           Max recording duration (default: 30)
-  --voice-silence-sec <sec>       VAD silence before stopping (default: 1.0)
-  --voice-silence-threshold <%>   VAD amplitude threshold (default: 1%)
-  --voice-silence-start-sec <sec> Seconds of sound before starting (default: 0.5)
-  --voice-pad-start-sec <sec>     Padding added to start of recording (default: 0.3)
-  --tts-voice <name>              Override rotated voice schedule (default: af_heart)
-  --completion <bash|zsh|fish>    Output shell tab-completion script
-
-Browser Automation:
-  The agent has a built-in browser tool (navigate, click, type, read_page,
-  screenshot, evaluate, select, wait, scroll, close). Requires playwright:
-    npm install playwright && npx playwright install chromium
+  Launch shmakk, then type commands as usual. shmakk watches the shell, catches
+  failures, and calls an LLM to fix them, plan tasks, and edit files.
+
+  You can also type natural-language self-commands directly into the session
+  (e.g. "list skills", "agent overview", "compact"). See SELF-COMMANDS below.
+
+  Type "help" inside a session to see this same text.
+
+═══════════════════════════════════════════════════════════════════════════
+  LAUNCH OPTIONS
+═══════════════════════════════════════════════════════════════════════════
+
+  shmakk                           Launch in auto mode (AI acts on failures)
+  shmakk --review                  Launch in review mode (confirm every AI action)
+  shmakk --yes-files               Auto-accept file writes, edits, mkdir
+
+  shmakk --help                    Show this help
+  shmakk --build-history [files]   Parse shell history for better corrections
+  shmakk --update-command-glossary Scan PATH and build local command glossary
+
+  --no-ai                          Disable AI entirely (pure passthrough)
+  --no-correction                  Disable command correction
+  --debug                          Verbose logging to stderr
+  --print-config                   Print resolved configuration and exit
+
+  --workspace <path>               Override workspace root
+  --profile <name>                 Startup profile: tiny|balanced|deep|builder|large-app
+  --colors <true|false>            Enable or disable ANSI colors
+  --markdown <true|false>          Enable or disable markdown rendering
+  --notify                         Desktop notifications for Y/n prompts
+
+═══════════════════════════════════════════════════════════════════════════
+  MODEL PROVIDERS
+═══════════════════════════════════════════════════════════════════════════
+
+  --endpoint <name>                Use model preset from ~/.config/shmakk/endpoints.json
+  --model-recommendation           Main model chooses best model per call
+
+  Providers: openai-compatible | codex | anthropic | google
+  Configure in ~/.config/shmakk/endpoints.json:
+    {
+      "main": "claude",
+      "models": {
+        "claude":       { "provider":"anthropic", "model":"claude-sonnet-4-5-...", "api_key":"..." },
+        "gpt5":         { "provider":"codex",     "model":"gpt-5-codex",        "api_key":"..." },
+        "local-qwen":   { "provider":"openai-compatible", "base_url":"http://127.0.0.1:1234/v1",
+                          "model":"qwen/qwen3.5-9b" }
+      }
+    }
+
+═══════════════════════════════════════════════════════════════════════════
+  SESSION CONTROL  (shmakk --flag  from another terminal)
+═══════════════════════════════════════════════════════════════════════════
+
+  shmakk --status                  Is this terminal inside shmakk?
+  shmakk --stats                   Session/task stats (journal, audit, skill)
+  shmakk --show-plan               Current plan: tasks and progress
+  shmakk --resume-status           Task journal summary for continuity
+  shmakk --mcp-status              MCP servers and their tools
+
+  shmakk --compact                 Clear conversation + task journal
+  shmakk --reset                   Clear AI conversation history (keep session)
+  shmakk --restart                 Restart the inner shell (keeps window)
+  shmakk --exit                    Cleanly exit the parent shmakk
+
+  shmakk --profile-set <name>      Switch profile and restart
+
+  shmakk --load-skill <name>       Load a skill into workspace state
+  shmakk --install-skill <url>     Download skill markdown from URL, validate, load
+  shmakk -G, --global              Use global (~/.config/shmakk) with --load-skill / --install-skill
+  shmakk --list-skills             List all registered skills (workspace + global)
+  shmakk --skill-status            Active skill and registry status
+  shmakk --unload-skill <name>     Remove skill from whichever registry has it
+
+═══════════════════════════════════════════════════════════════════════════
+  SELF-COMMANDS  (type inside an shmakk session)
+═══════════════════════════════════════════════════════════════════════════
+
+  ── Skills ──
+  list skills                      List all registered skills
+  list skills <category>           List skills in a specific category
+  list skill categories            Show available skill categories
+  find skills <query>              Search skills by name/description
+  load skill <name>                Load a skill into the active workspace
+  unload skill <name>              Remove a skill from its registry
+  skill status                     Show active skill and registry state
 
-MCP (Model Context Protocol):
-  shmakk --mcp-status             Show configured MCP servers and their tools
-  Configure in ~/.config/shmakk/mcp.json or .shmakk/mcp.json:
+  ── Agents & Team ──
+  agent overview                   Show all agents and their specialisms
+  agent skills                     List all agent skills
+  agent <name>                     Show detail for a specific agent
+  list agents                      Alias for agent overview
+
+  ── Context & Session ──
+  status                           Show session status
+  stats                            Show session/task statistics
+  resume status                    Show task journal for resume continuity
+  show plan                        Display current plan and progress
+  compact                          Clear conversation + task journal
+  reset                            Clear AI conversation history
+
+  ── Memory & Search ──
+  recall <query>                   Search past sessions by content
+  find session <query>             Find a session by topic
+  last sessions                    Show recent sessions
+  search db status                 Display session search DB info
+  show memory                      List stored memories
+  forget <query>                   Remove matching memories
+
+  ── Configuration ──
+  show config                      Print resolved configuration
+  mcp status                       Show MCP servers and tools
+  show rules                       Display active workspace rules
+  list endpoints                   List configured model endpoints
+  use endpoint <name>              Switch to a named model endpoint
+  set model to <name>              Change the active model
+  set url to <url>                 Change the base URL
+  set api key to <key>             Change the API key
+
+  ── Toggles ──
+  enable review  |  disable review
+  enable correction  |  disable correction
+  enable yes-files  |  disable yes-files
+  enable colors  |  disable colors
+  enable debug  |  disable debug
+
+  ── Workflows ──
+  list workflows                   Show available automation workflows
+  run workflow <name>              Execute a named workflow
+
+  ── Edits ──
+  review edits                     Step through pending file changes
+
+  ── Meta ──
+  sidebar <query>                  Out-of-band agent query (not added to history)
+  help                             Show this help
+
+═══════════════════════════════════════════════════════════════════════════
+  VOICE  (Speech-to-Text / Text-to-Speech)
+═══════════════════════════════════════════════════════════════════════════
+
+  --sts                            Speech-to-Speech: always-on mic + TTS
+  --stt                            Speech-to-Text: mic input, text output
+  --tts                            Text-to-Speech: text input, spoken output
+
+  --voice-language <code>          Language hint (e.g. en, es, fr)
+  --voice-max-sec <sec>            Max recording seconds (default: 30)
+  --voice-silence-sec <sec>        Silence before stopping (default: 1.0)
+  --voice-silence-threshold <%>    VAD amplitude threshold (default: 1%)
+  --voice-silence-start-sec <sec>  Sound required before start (default: 0.5)
+  --voice-pad-start-sec <sec>      Padding at start of recording (default: 0.3)
+  --tts-voice <name>               Override daily voice rotation
+
+  STT: Whisper-base ONNX in-process. No Python, no server, no API key.
+  TTS: kokoro-js (Kokoro-82M ONNX, ~334MB fp16). Auto-download on first use.
+  Requires aplay, paplay, or afplay for audio. 28 voices, rotated daily.
+
+═══════════════════════════════════════════════════════════════════════════
+  ENVIRONMENT
+═══════════════════════════════════════════════════════════════════════════
+
+  SHMAKK_BASE_URL                  OpenAI-compatible base URL
+  SHMAKK_API_KEY                   API key
+  SHMAKK_MODEL                     Default model
+  SHMAKK_PROVIDER                  Provider: openai-compatible|codex|anthropic|google
+  SHMAKK_HEADERS                   Extra headers: k=v,k=v
+  SHMAKK_REGISTRY                  Model registry filter (comma-separated)
+  SHMAKK_MODEL_RECOMMENDATION      Set to 1 to let main model choose per call
+
+  SHMAKK_HF_CACHE                  HuggingFace cache directory (voice models)
+  SHMAKK_TTS_VOICE                 Pin a specific TTS voice
+  SHMAKK_TTS_DTYPE                 Kokoro dtype: fp32|fp16|q8|q4|q4f16 (default: fp16)
+  SHMAKK_VOICE_LANGUAGE            Language hint for STT
+  SHMAKK_VOICE_MAX_SEC             Max recording seconds
+  SHMAKK_VOICE_SILENCE_SEC         VAD silence threshold seconds
+  SHMAKK_VOICE_SILENCE_THRESHOLD   VAD amplitude threshold
+  SHMAKK_VOICE_PAD_START_SEC       Start-of-recording padding
+
+═══════════════════════════════════════════════════════════════════════════
+  MCP & BROWSER
+═══════════════════════════════════════════════════════════════════════════
+
+  MCP servers: configure in ~/.config/shmakk/mcp.json or .shmakk/mcp.json
     { "mcpServers": { "name": { "command": "...", "args": [...] } } }
 
-  Voice uses Whisper-base ONNX in-process. No Python, no server, no API key.
-  Model auto-downloads on first use.
-
-  TTS uses kokoro-js (Kokoro-82M ONNX, ~334MB fp16). Model auto-downloads on first use.
-  Requires: aplay, paplay, or afplay for audio playback.
-  All 28 Kokoro voices rotate automatically on a daily schedule.
-
-Voice environment:
-  SHMAKK_HF_CACHE                 HuggingFace cache directory override
-  SHMAKK_TTS_VOICE                Pin a specific TTS voice (default: auto-rotated)
-  SHMAKK_TTS_DTYPE                Kokoro dtype: fp32, fp16, q8, q4, q4f16 (default: fp16)
-  SHMAKK_VOICE_LANGUAGE           Language hint for STT (e.g., en, es, fr)
-  SHMAKK_VOICE_MAX_SEC            Max recording seconds (default: 30)
-  SHMAKK_VOICE_SILENCE_SEC        VAD silence threshold seconds (default: 1.0)
-  SHMAKK_VOICE_SILENCE_THRESHOLD  VAD amplitude threshold (default: 1%)
-  SHMAKK_VOICE_PAD_START_SEC      Padding added to start of recording (default: 0.3)
-
-Environment:
-  SHMAKK_BASE_URL                 OpenAI-compatible base URL
-  SHMAKK_API_KEY                  API key
-  SHMAKK_MODEL                    Default model
-  SHMAKK_HEADERS                  Comma-separated extra headers (k=v,k=v)
-  SHMAKK_REGISTRY                 Comma-separated model registry filter (for makkorch)
+  Browser automation: requires playwright
+    npm install playwright && npx playwright install chromium
+  Tools: navigate, click, type, read_page, screenshot, evaluate, select,
+  wait, scroll, close.
+
 `;
 
 module.exports = { parseArgs, HELP };

package/src/completions.js

@@ -33,12 +33,13 @@ const FLAGS = [
   { flag: '--tts', arg: false, desc: 'Text-to-Speech: spoken responses' },
   { flag: '--sts', arg: false, desc: 'Speech-to-Speech: always-on mic + TTS' },
   { flag: '--voice', arg: false, desc: 'Enable voice input (stt shortcut)' },
+  { flag: '--model-recommendation', arg: false, desc: 'Route each model call via main model recommendation' },
 
   // flags with arguments
   { flag: '--workspace', arg: '<path>', desc: 'Override workspace root' },
   { flag: '--profile', arg: '<name>', desc: 'Startup profile (tiny|balanced|deep|builder|large-app)' },
   { flag: '--profile-set', arg: '<name>', desc: 'Switch profile and restart' },
-  { flag: '--endpoint', arg: '<name>', desc: 'Use endpoint preset from ~/.config/shmakk/endpoints.js' },
+  { flag: '--endpoint', arg: '<name>', desc: 'Use model preset from ~/.config/shmakk/endpoints.json' },
   { flag: '--colors', arg: '<true|false>', desc: 'Toggle ANSI colors' },
   { flag: '--load-skill', arg: '<name>', desc: 'Load a skill into workspace state' },
   { flag: '--unload-skill', arg: '<name>', desc: 'Remove skill from registry' },
@@ -53,6 +54,7 @@ const FLAGS = [
   { flag: '--voice-silence-start-sec', arg: '<sec>', desc: 'Sound before recording starts' },
   { flag: '--voice-pad-start-sec', arg: '<sec>', desc: 'Padding before recording' },
   { flag: '--tts-voice', arg: '<name>', desc: 'Override Kokoro voice' },
+  { flag: '--notify', arg: false, desc: 'Send desktop notifications when shmakk needs your attention' },
 ];
 
 function bash() {