shmakk 1.1.0

package/docs/voice.md

@@ -0,0 +1,181 @@
+# shmakk voice
+
+Always-on speech-to-speech mode for shmakk. Speak naturally — shmakk listens, transcribes, responds, and reads its answer aloud. No push-to-talk, no hotkeys.
+
+## How it works
+
+- **STT** — Whisper-base ONNX via `@huggingface/transformers`. Runs fully in-process, no Python, no server, no API key. Model (~75MB) auto-downloads on first use.
+- **VAD** — `sox` silence detection. Recording starts when you speak, stops automatically after 1 second of silence. No button to push.
+- **TTS** — Kokoro-82M ONNX via `kokoro-js`. Runs fully in-process. Model (~165MB) auto-downloads on first use. Sentences stream sentence-by-sentence so the first words play immediately.
+- **Voice rotation** — All 28 Kokoro voices rotate on a deterministic daily schedule (changes every 2–5 hours, varied per day). Feels random, fully reproducible.
+
+## Requirements
+
+### System packages
+
+**Arch / EndeavourOS:**
+```bash
+sudo pacman -S sox
+```
+
+**Debian / Ubuntu:**
+```bash
+sudo apt install sox
+```
+
+**macOS:**
+```bash
+brew install sox
+```
+
+Sox provides the `rec` command used for VAD-based microphone capture. A working PulseAudio or PipeWire setup is also required (standard on any modern Linux desktop).
+
+### Node.js optional dependencies
+
+Voice deps are optional — base shmakk works without them.
+
+```bash
+npm install --include=optional
+```
+
+Or use the setup script which installs deps and runs a full preflight check:
+
+```bash
+npm run setup:voice
+```
+
+## Usage
+
+```bash
+shmakk --sts          # speech-to-speech: always-on mic + TTS responses
+shmakk --stt          # mic input only, text responses
+shmakk --tts          # text input, spoken responses
+```
+
+Just speak. shmakk will:
+1. Detect your voice via VAD
+2. Transcribe it (shown in cyan on stderr)
+3. Send it as input
+4. Speak the response aloud, sentence by sentence
+
+## Interrupting
+
+Say any of these to stop TTS mid-sentence:
+
+> stop · quiet · shut up · silence · enough · cancel
+
+The current playback stops immediately and shmakk goes back to listening.
+
+## Tuning VAD for your microphone
+
+The default settings work well for USB headsets with a clean noise floor. If speech is cut off or recordings don't stop, tune these env vars:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SHMAKK_VOICE_SILENCE_SEC` | `1.0` | Seconds of silence before stopping |
+| `SHMAKK_VOICE_SILENCE_THRESHOLD` | `1%` | Amplitude threshold for silence |
+| `SHMAKK_VOICE_SILENCE_START_SEC` | `0.5` | Seconds of sound before starting |
+| `SHMAKK_VOICE_PAD_START_SEC` | `0.3` | Padding added to start of recording |
+| `SHMAKK_VOICE_MAX_SEC` | `30` | Hard maximum recording duration |
+
+Add to your `.env`:
+```bash
+SHMAKK_VOICE_SILENCE_SEC=1.5
+SHMAKK_VOICE_SILENCE_THRESHOLD=2%
+```
+
+To find your microphone's noise floor:
+```bash
+rec -q -r 16000 -c 1 /tmp/silence.wav trim 0 3 && sox /tmp/silence.wav -n stat 2>&1 | grep RMS
+```
+
+Set `SHMAKK_VOICE_SILENCE_THRESHOLD` to roughly 3× the RMS amplitude percentage.
+
+## Voice settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SHMAKK_TTS_VOICE` | *(scheduled)* | Pin a specific voice (e.g. `am_michael`) |
+| `SHMAKK_TTS_DTYPE` | `fp16` | Model precision: `fp32`, `fp16`, `q8`, `q4` |
+
+**Available voices (28 total):**
+
+| ID | Language | Gender |
+|----|----------|--------|
+| `af_bella`, `af_sarah`, `af_sky`, `af_nicole`, `af_heart`, `af_aoede`, `af_river` | American English | Female |
+| `am_adam`, `am_michael`, `am_echo`, `am_liam` | American English | Male |
+| `bf_emma`, `bf_isabella` | British English | Female |
+| `bm_george`, `bm_lewis`, `bm_daniel` | British English | Male |
+| `jf_alpha`, `jf_gongitsune`, `jf_nezumi`, `jf_tebukuro` | Japanese | Female |
+| `jm_kumo` | Japanese | Male |
+| `zf_xiaobei`, `zf_xiaoni`, `zf_xiaoxiao`, `zf_xiaoyi` | Chinese | Female |
+| `zm_yunjian`, `zm_yunxia` | Chinese | Male |
+
+To see today's voice schedule:
+```bash
+node -e "
+const tts = require('./src/services/tts');
+tts.listVoices().then(voices => {
+  const now = new Date();
+  const day = now.getFullYear() * 10000 + (now.getMonth()+1)*100 + now.getDate();
+  const daySeed = (day * 2654435761) >>> 0;
+  let t = 0, b = 0, seed = daySeed;
+  const ids = voices.map(v => v.id);
+  console.log('Today schedule:');
+  while (t < 1440) {
+    seed = (seed * 1664525 + 1013904223) >>> 0;
+    const mins = 120 + (seed % 180);
+    const voiceSeed = (daySeed ^ (b * 2246822519)) >>> 0;
+    const v = ids[voiceSeed % ids.length];
+    const h = String(Math.floor(t/60)).padStart(2,'0');
+    const m = String(t%60).padStart(2,'0');
+    console.log(h+':'+m, '->', v, '('+Math.round(mins/60*10)/10+'h)');
+    t += mins; b++;
+  }
+});
+"
+```
+
+## Language
+
+STT defaults to English. Override:
+```bash
+shmakk --sts --voice-language sv    # Swedish
+shmakk --sts --voice-language de    # German
+```
+
+Or set permanently:
+```bash
+export SHMAKK_VOICE_LANGUAGE=en
+```
+
+## Troubleshooting
+
+**Voice not detected / recording doesn't start**
+```bash
+# Check mic level
+rec -q -r 16000 -c 1 /tmp/test.wav trim 0 3 && sox /tmp/test.wav -n stat 2>&1 | grep RMS
+# Lower the start threshold if RMS is low
+export SHMAKK_VOICE_SILENCE_THRESHOLD=0.5%
+```
+
+**Recording doesn't stop**
+```bash
+# Raise the stop threshold — background noise is above it
+export SHMAKK_VOICE_SILENCE_THRESHOLD=3%
+```
+
+**No TTS sound**
+```bash
+# Check player
+which paplay aplay
+pactl info
+```
+
+**Slow first response**
+Models download on first use. After that they're cached in `~/.cache/huggingface`. Subsequent starts load from cache in seconds.
+
+**Run the full preflight check:**
+```bash
+npm run setup:voice
+```

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "shmakk",
+  "version": "1.1.0",
+  "description": "AI-supervised terminal wrapper — command correction, tool-driven tasks, safety controls",
+  "license": "MIT",
+  "keywords": [
+    "terminal",
+    "ai",
+    "pty",
+    "developer-tools",
+    "cli",
+    "voice",
+    "speech-to-text",
+    "text-to-speech"
+  ],
+  "bin": {
+    "shmakk": "bin/shmakk.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "main": "src/index.js",
+  "type": "commonjs",
+  "scripts": {
+    "postinstall": "node scripts/patch-onnxruntime.js",
+    "start": "node bin/shmakk.js",
+    "dev": "node bin/shmakk.js --debug",
+    "test": "node test/units.js",
+    "check": "node -e \"require('./src/index'); require('./src/agent'); require('./src/orchestrator'); console.log('check-ok')\"",
+    "mock-llm": "node test/mock-llm.js",
+    "global:setup": "node src/global-setup.js",
+    "global:link": "npm link && npm run global:setup",
+    "global:unlink": "npm unlink -g shmakk",
+    "global:install": "npm install -g . && npm run global:setup",
+    "global:reinstall": "npm uninstall -g shmakk && npm install -g . && npm run global:setup",
+    "setup": "npm install && npm run check && npm run test",
+    "setup:voice": "npm install --include=optional && node src/setup-voice.js",
+    "global:doctor": "node src/global-doctor.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "node-pty": "^1.0.0",
+    "openai": "^4.77.0",
+    "wavefile": "^11.0.0"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "kokoro-js": "^1.2.1"
+  }
+}

package/scripts/patch-onnxruntime.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Patches the kokoro-js nested onnxruntime-node so its SONAME doesn't conflict
+ * with the project-level onnxruntime-node (@huggingface/transformers).
+ *
+ * Problem:
+ *   - @huggingface/transformers → onnxruntime-node 1.24.3 (napi-v6)
+ *   - kokoro-js → @huggingface/transformers 3.x → onnxruntime-node 1.21.0 (napi-v3)
+ *   - Both ship libonnxruntime.so.1 with the same SONAME
+ *   - Whichever loads first "wins"; the second fails with symbol version errors
+ *
+ * Fix:
+ *   - Rename SONAME of the napi-v3 lib to libkokoro_ort.so.1
+ *   - Update the napi-v3 binding.node's NEEDED reference accordingly
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const KOKORO_ORT_DIR = path.join(
+  __dirname, '..', 'node_modules', 'kokoro-js', 'node_modules',
+  'onnxruntime-node', 'bin', 'napi-v3', 'linux', 'x64'
+);
+
+const ORIG_SO = 'libonnxruntime.so.1';
+const NEW_SO = 'libkokoro_ort.so.1';
+
+function patchelf(...args) {
+  return execSync(`patchelf ${args.join(' ')}`, { encoding: 'utf8', stdio: 'pipe' });
+}
+
+function main() {
+  // Check if patchelf is available
+  try {
+    execSync('which patchelf', { stdio: 'ignore' });
+  } catch {
+    console.error('[shmakk] patchelf not found. Install it for voice+TTS coexistence.');
+    console.error('  pacman -S patchelf   # Arch');
+    console.error('  apt install patchelf # Debian/Ubuntu');
+    console.error('  brew install patchelf # macOS');
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(KOKORO_ORT_DIR)) {
+    // kokoro-js or its onnxruntime-node not installed — nothing to patch
+    return;
+  }
+
+  const soPath = path.join(KOKORO_ORT_DIR, ORIG_SO);
+  const newSoPath = path.join(KOKORO_ORT_DIR, NEW_SO);
+  const bindingPath = path.join(KOKORO_ORT_DIR, 'onnxruntime_binding.node');
+
+  // Already patched?
+  if (fs.existsSync(newSoPath)) {
+    // Verify it was done correctly
+    const soname = execSync(`patchelf --print-soname "${newSoPath}"`, { encoding: 'utf8' }).trim();
+    if (soname === NEW_SO) {
+      return; // Already patched, nothing to do
+    }
+    // Otherwise, re-apply from scratch
+    fs.unlinkSync(newSoPath);
+  }
+
+  if (!fs.existsSync(soPath)) {
+    console.error('[shmakk] Expected onnxruntime library not found:', soPath);
+    process.exit(1);
+  }
+
+  // 1. Change SONAME of the .so file
+  patchelf('--set-soname', NEW_SO, soPath);
+
+  // 2. Rename the file
+  fs.renameSync(soPath, newSoPath);
+
+  // 3. Update the binding.node's NEEDED reference
+  patchelf('--replace-needed', ORIG_SO, NEW_SO, bindingPath);
+
+  console.log('[shmakk] Patched kokoro-js onnxruntime SONAME →', NEW_SO);
+}
+
+main();

package/src/audit.js

@@ -0,0 +1,18 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function logPath() {
+  const base = process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+  return path.join(base, 'shmakk', 'audit.log');
+}
+
+function append(entry) {
+  try {
+    const p = logPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify({ t: new Date().toISOString(), ...entry }) + '\n');
+  } catch { /* never let audit failures bubble */ }
+}
+
+module.exports = { append, logPath };

package/src/cli.js

@@ -0,0 +1,177 @@
+function parseArgs(argv) {
+  const opts = {
+    review: false,
+    yesFiles: false,
+    updateGlossary: false,
+    help: false,
+    debug: false,
+    workspace: null,
+    noAi: false,
+    noCorrection: false,
+    printConfig: false,
+    status: false,
+    buildHistory: null,
+    stats: false,
+    compact: false,
+    loadSkill: null,
+    listSkills: false,
+    skillStatus: false,
+    unloadSkill: null,
+    installSkill: null,
+    resumeStatus: false,
+    exitNow: false,
+    restart: false,
+    profile: null,
+    profileSet: null,
+    colors: null,
+    endpoint: null,
+    voice: false,
+    stt: false,
+    tts: false,
+    sts: false,
+    voiceLanguage: null,
+    voiceMaxDuration: null,
+    voiceSilenceSec: null,
+    voiceSilenceThreshold: null,
+    voiceSilenceStartSec: null,
+    voicePadStartSec: null,
+    ttsVoice: null,
+    completion: null,
+    unknown: [],
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--review': opts.review = true; break;
+      case '--yes-files': opts.yesFiles = true; break;
+      case '--update-command-glossary': opts.updateGlossary = true; break;
+      case '-h':
+      case '--help': opts.help = true; break;
+      case '--debug': opts.debug = true; break;
+      case '--no-ai': opts.noAi = true; break;
+      case '--no-correction': opts.noCorrection = true; break;
+      case '--print-config': opts.printConfig = true; break;
+      case '--workspace': opts.workspace = argv[++i] || null; break;
+      case '--status': opts.status = true; break;
+      case '--stats': opts.stats = true; break;
+      case '--compact': opts.compact = true; break;
+      case '--load-skill': opts.loadSkill = argv[++i] || null; break;
+      case '--list-skills': opts.listSkills = true; break;
+      case '--skill-status': opts.skillStatus = true; break;
+      case '--unload-skill': opts.unloadSkill = argv[++i] || null; break;
+      case '--install-skill': opts.installSkill = argv[++i] || null; break;
+      case '--resume-status': opts.resumeStatus = true; break;
+      case '--exit': opts.exitNow = true; break;
+      case '--restart': opts.restart = true; break;
+      case '--reset': opts.reset = true; break;
+      case '--profile': opts.profile = argv[++i] || null; break;
+      case '--profile-set': opts.profileSet = argv[++i] || null; break;
+      case '--build-history':
+        opts.buildHistory = [];
+        // Collect remaining args as file paths until next flag
+        while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+          opts.buildHistory.push(argv[++i]);
+        }
+        if (!opts.buildHistory.length) opts.buildHistory = null; // flag with no files = auto-detect
+        break;
+      case '--stt': opts.stt = true; opts.voice = true; break;
+      case '--tts': opts.tts = true; break;
+      case '--sts': opts.sts = true; opts.stt = true; opts.tts = true; opts.voice = true; break;
+      case '--voice': opts.stt = true; opts.voice = true; break;
+      case '--voice-language': opts.voiceLanguage = argv[++i] || null; break;
+      case '--voice-max-sec': opts.voiceMaxDuration = parseInt(argv[++i], 10) || null; break;
+      case '--voice-silence-sec': opts.voiceSilenceSec = argv[++i] || null; break;
+      case '--voice-silence-threshold': opts.voiceSilenceThreshold = argv[++i] || null; break;
+      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 '--completion': opts.completion = argv[++i] || null; break;
+      case '--colors': opts.colors = argv[++i] || null; break;
+      case '--endpoint': opts.endpoint = argv[++i] || null; break;
+      default: opts.unknown.push(a);
+    }
+  }
+  return opts;
+}
+
+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 --list-skills            List registered local skills
+  shmakk --skill-status           Show active skill and registry status
+  shmakk --unload-skill <name>    Remove skill from registry/local cache
+  shmakk --install-skill <url>    Download skill markdown from URL, validate, and load
+  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 .shmakk/endpoints.json
+  --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
+
+  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)
+`;
+
+module.exports = { parseArgs, HELP };