@idl3/claude-control 0.1.20 → 0.1.22

package/lib/config.js

@@ -6,6 +6,13 @@
  * overridable to a shell alias like `yolo` or `claude --flags`) and the
  * default cwd new sessions start in.
  *
+ * Also holds prompt-optimiser settings:
+ *  - optimizeModel: the Claude model used for LLM-based prompt optimisation
+ *    (default 'claude-haiku-4-5').
+ *  - claudeBin: optional absolute path to the claude CLI binary. Empty string
+ *    means auto-resolve (resolveClaudeBin() in lib/claude-cli.js tries PATH,
+ *    then common install locations).
+ *
  * Persisted at ~/.claude-control/config.json (honour CLAUDE_CONTROL_DATA when
  * set, matching server.js's env-override convention). Reads never throw —
  * defaults are merged over whatever's on disk. Writes validate strictly and
@@ -15,6 +22,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { detectMachine, recommendMlxModel, recommendClaudeModel } from './models.js';
 
 // Env lookup mirrors server.js: prefer CLAUDE_CONTROL_<X>, fall back to the
 // legacy COCKPIT_<X> so existing launchers keep working.
@@ -32,12 +40,23 @@ function configPath() {
 }
 
 const LAUNCH_MAX = 500;
+const OPTIMIZE_MODEL_MAX = 200;
+const CLAUDE_BIN_MAX = 500;
+const MLX_MODEL_MAX = 200;
+const OPTIMIZE_BACKENDS = ['mlx', 'claude', 'rules'];
 
 /** Defaults, recomputed each call so a changed HOME/env is honoured. */
 function defaults() {
   return {
     launchCommand: 'claude',
     defaultCwd: os.homedir(),
+    optimizeModel: recommendClaudeModel(),
+    claudeBin: '',
+    // Prompt-enhancer backend: 'mlx' (local model → claude → rules chain),
+    // 'claude' (claude -p → rules), or 'rules' (deterministic, offline).
+    optimizeBackend: 'mlx',
+    // Default MLX model auto-picked for this machine's unified memory.
+    mlxModel: recommendMlxModel(detectMachine().ramGB),
   };
 }
 
@@ -45,7 +64,7 @@ function defaults() {
  * Read the persisted config, merged over defaults. Never throws — a missing,
  * empty, or corrupt file falls back to defaults. Only known keys are surfaced.
  *
- * @returns {{ launchCommand: string, defaultCwd: string }}
+ * @returns {{ launchCommand: string, defaultCwd: string, optimizeModel: string, claudeBin: string, optimizeBackend: string, mlxModel: string }}
  */
 export function readConfig() {
   const base = defaults();
@@ -65,6 +84,23 @@ export function readConfig() {
       typeof parsed.defaultCwd === 'string' && parsed.defaultCwd.trim()
         ? parsed.defaultCwd
         : base.defaultCwd,
+    optimizeModel:
+      typeof parsed.optimizeModel === 'string' && parsed.optimizeModel.trim()
+        ? parsed.optimizeModel
+        : base.optimizeModel,
+    claudeBin:
+      typeof parsed.claudeBin === 'string'
+        ? parsed.claudeBin
+        : base.claudeBin,
+    optimizeBackend:
+      typeof parsed.optimizeBackend === 'string' &&
+      OPTIMIZE_BACKENDS.includes(parsed.optimizeBackend)
+        ? parsed.optimizeBackend
+        : base.optimizeBackend,
+    mlxModel:
+      typeof parsed.mlxModel === 'string' && parsed.mlxModel.trim()
+        ? parsed.mlxModel
+        : base.mlxModel,
   };
 }
 
@@ -75,9 +111,12 @@ export function readConfig() {
  * Validation:
  *  - launchCommand: non-empty string, ≤500 chars.
  *  - defaultCwd: a path that exists and is a directory.
+ *  - optimizeModel: non-empty string, ≤200 chars.
+ *  - claudeBin: string ≤500 chars; empty string is allowed (means auto-resolve).
+ *    Existence is NOT verified at write time (path may differ across hosts).
  *
- * @param {{ launchCommand?: unknown, defaultCwd?: unknown }} partial
- * @returns {{ launchCommand: string, defaultCwd: string }} the saved config
+ * @param {{ launchCommand?: unknown, defaultCwd?: unknown, optimizeModel?: unknown, claudeBin?: unknown }} partial
+ * @returns {{ launchCommand: string, defaultCwd: string, optimizeModel: string, claudeBin: string, optimizeBackend: string, mlxModel: string }} the saved config
  */
 export function writeConfig(partial = {}) {
   const current = readConfig();
@@ -111,6 +150,47 @@ export function writeConfig(partial = {}) {
     next.defaultCwd = cwd;
   }
 
+  if (partial.optimizeModel !== undefined) {
+    const model = partial.optimizeModel;
+    if (typeof model !== 'string' || !model.trim()) {
+      throw new Error('optimizeModel must be a non-empty string');
+    }
+    if (model.length > OPTIMIZE_MODEL_MAX) {
+      throw new Error(`optimizeModel must be ≤${OPTIMIZE_MODEL_MAX} characters`);
+    }
+    next.optimizeModel = model;
+  }
+
+  if (partial.claudeBin !== undefined) {
+    const bin = partial.claudeBin;
+    if (typeof bin !== 'string') {
+      throw new Error('claudeBin must be a string');
+    }
+    if (bin.length > CLAUDE_BIN_MAX) {
+      throw new Error(`claudeBin must be ≤${CLAUDE_BIN_MAX} characters`);
+    }
+    next.claudeBin = bin;
+  }
+
+  if (partial.optimizeBackend !== undefined) {
+    const b = partial.optimizeBackend;
+    if (typeof b !== 'string' || !OPTIMIZE_BACKENDS.includes(b)) {
+      throw new Error(`optimizeBackend must be one of: ${OPTIMIZE_BACKENDS.join(', ')}`);
+    }
+    next.optimizeBackend = b;
+  }
+
+  if (partial.mlxModel !== undefined) {
+    const m = partial.mlxModel;
+    if (typeof m !== 'string' || !m.trim()) {
+      throw new Error('mlxModel must be a non-empty string');
+    }
+    if (m.length > MLX_MODEL_MAX) {
+      throw new Error(`mlxModel must be ≤${MLX_MODEL_MAX} characters`);
+    }
+    next.mlxModel = m;
+  }
+
   const dir = dataDir();
   fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(configPath(), JSON.stringify(next, null, 2), { mode: 0o600 });

package/lib/match.js

@@ -123,10 +123,23 @@ export function assignTranscripts(panes, candidates, opts = {}) {
   }
 
   // Pass 3 — most-recently-active remaining candidate.
+  // Gate: when the pane's process start time is known, only consider candidates
+  // whose last known activity (lastActivityMs, falling back to file mtime or
+  // birthtime) is at or after the pane started (minus startSlackMs). A transcript
+  // that was never touched after the pane launched cannot belong to it — that is
+  // the "fresh pane inherits old transcript" bug. When procStartMs is unknown,
+  // skip the gate so we don't regress panes with missing timing data.
+  // NOTE: --resume is safe: Claude appends a record to the old transcript on
+  // resume, bumping its mtime/lastActivityMs above the pane's start time.
   for (const pane of ordered) {
     if (result.has(pane.target)) continue;
     let best = null;
     for (const c of available(pane)) {
+      // Apply temporal gate only when pane start time is known.
+      if (pane.procStartMs != null) {
+        const candActive = c.lastActivityMs ?? c.mtime ?? c.birthtimeMs ?? null;
+        if (candActive != null && candActive < pane.procStartMs - startSlackMs) continue;
+      }
       if (!best || (c.lastActivityMs ?? 0) > (best.lastActivityMs ?? 0)) best = c;
     }
     if (best) claim(pane, best);

package/lib/mlx.js

@@ -0,0 +1,260 @@
+/**
+ * lib/mlx.js — local LLM backend via a managed mlx_lm.server (Apple Silicon).
+ *
+ * Spawns a singleton OpenAI-compatible MLX server on first use, keeps it warm,
+ * and shuts it down after an idle period. No API key, no network — fully local.
+ * Used by the prompt enhancer as the first link in the mlx → claude → rules
+ * chain (server.js handleOptimize).
+ *
+ * Exports:
+ *  - resolveMlxPython() → string | null      (venv python that has mlx_lm)
+ *  - serverBase(port) → string               (pure)
+ *  - buildChatBody(prompt, model, maxTokens) → object  (pure)
+ *  - parseChatContent(json) → string         (pure; throws on bad/empty shape)
+ *  - complete(prompt, { model, port, maxTokens }) → Promise<string>
+ *  - shutdown()                              (kill the child; for exit/tests)
+ *
+ * Config/env: model from config.mlxModel (default below); port via
+ * CLAUDE_CONTROL_MLX_PORT (default 8080); python via CLAUDE_CONTROL_MLX_PYTHON
+ * else ~/.claude-control/mlx-venv/bin/python else a PATH python3 with mlx_lm.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawn, execFileSync } from 'node:child_process';
+import { readConfig } from './config.js';
+
+export const DEFAULT_MODEL = 'mlx-community/Llama-3.2-3B-Instruct-4bit';
+// Dedicated port for OUR managed sidecar. NOT 8080 — that's a very common port
+// (LM Studio, other local LLM/TTS servers) and colliding makes us POST our model
+// to a foreign server that can't serve it → hang. Overridable via env.
+const DEFAULT_PORT = Number(process.env.CLAUDE_CONTROL_MLX_PORT) || 4319;
+// How long a SINGLE request waits for the server to be ready before giving up
+// and letting the caller fall back (to claude -p). The spawned server keeps
+// loading in the background, so the next request finds it warm (~1s). Cold
+// model load can take ~30-90s under launchd, so we never block a request that
+// long — we fail over fast and warm up for next time.
+const REQUEST_READY_MS = Number(process.env.CLAUDE_CONTROL_MLX_TIMEOUT_MS) || 8_000;
+const IDLE_MS = 15 * 60_000; // free ~2GB after 15 min idle
+const MAX_TOKENS = 700;
+
+/** @param {number} [port] */
+export function serverBase(port = DEFAULT_PORT) {
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * Resolve a python interpreter that can `import mlx_lm`.
+ * @returns {string | null}
+ */
+export function resolveMlxPython() {
+  const envPy = process.env.CLAUDE_CONTROL_MLX_PYTHON;
+  const venvPy = path.join(os.homedir(), '.claude-control', 'mlx-venv', 'bin', 'python');
+  for (const p of [envPy, venvPy]) {
+    if (p && fs.existsSync(p)) return p;
+  }
+  try {
+    const p = execFileSync('which', ['python3'], { encoding: 'utf8' }).trim();
+    if (p) {
+      execFileSync(p, ['-c', 'import mlx_lm'], { stdio: 'ignore' });
+      return p;
+    }
+  } catch {
+    /* no mlx_lm on PATH python */
+  }
+  return null;
+}
+
+// ── server singleton ────────────────────────────────────────────────────────
+let child = null;
+let childModel = null; // model id the current child was spawned with
+let idleTimer = null;
+
+function bumpIdle() {
+  if (idleTimer) clearTimeout(idleTimer);
+  idleTimer = setTimeout(() => shutdown(), IDLE_MS);
+  if (idleTimer.unref) idleTimer.unref();
+}
+
+/** Kill the managed server (no-op if none / external). */
+export function shutdown() {
+  if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+  if (child) {
+    try { child.kill('SIGTERM'); } catch { /* ignore */ }
+    child = null;
+  }
+  childModel = null;
+}
+
+async function ping(port) {
+  try {
+    const r = await fetch(serverBase(port) + '/v1/models', { signal: AbortSignal.timeout(1500) });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
+// The model id a server on `port` is currently serving (via /v1/models), or null.
+async function servedModel(port) {
+  try {
+    const r = await fetch(serverBase(port) + '/v1/models', { signal: AbortSignal.timeout(1500) });
+    if (!r.ok) return null;
+    const j = await r.json();
+    const id = j?.data?.[0]?.id;
+    return typeof id === 'string' ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+// Best-effort: kill whatever process holds `port` (used to reclaim the port from
+// an orphaned mlx server that's serving the wrong model). No-op if lsof/kill fail.
+function freePort(port) {
+  try {
+    const out = execFileSync('lsof', ['-ti', `tcp:${port}`], { encoding: 'utf8' }).trim();
+    for (const pid of out.split('\n').filter(Boolean)) {
+      try { process.kill(Number(pid), 'SIGTERM'); } catch { /* already gone */ }
+    }
+  } catch {
+    /* nothing on the port, or lsof unavailable */
+  }
+}
+
+/**
+ * Is the model already in the local HuggingFace cache (so selecting it won't
+ * trigger a multi-GB download)? Checks `~/.cache/huggingface/hub/models--…`.
+ * @param {string} id @returns {boolean}
+ */
+export function isModelCached(id) {
+  const dir = path.join(
+    process.env.HF_HOME || path.join(os.homedir(), '.cache', 'huggingface'),
+    'hub',
+    `models--${String(id).replace(/\//g, '--')}`,
+  );
+  try {
+    const snaps = path.join(dir, 'snapshots');
+    if (!fs.existsSync(snaps)) return false;
+    return fs.readdirSync(snaps).some((s) => {
+      try {
+        return fs.readdirSync(path.join(snaps, s)).length > 0;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
+// Spawn the mlx_lm.server child (once). Logs to ~/.claude-control/logs so a
+// failed/slow start is diagnosable. Sets HOME explicitly (launchd may not).
+function spawnServer(model, port) {
+  const py = resolveMlxPython();
+  if (!py) {
+    throw new Error(
+      'mlx_lm not installed — create ~/.claude-control/mlx-venv and `pip install mlx-lm`',
+    );
+  }
+  let out = 'ignore';
+  try {
+    const logPath = path.join(os.homedir(), '.claude-control', 'logs', 'mlx-server.log');
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    out = fs.openSync(logPath, 'a');
+  } catch {
+    /* fall back to ignored stdio */
+  }
+  child = spawn(
+    py,
+    ['-m', 'mlx_lm.server', '--model', model, '--host', '127.0.0.1', '--port', String(port)],
+    { stdio: ['ignore', out, out], env: { ...process.env, HOME: os.homedir() } },
+  );
+  childModel = model;
+  child.on('exit', () => { child = null; childModel = null; });
+}
+
+// Ensure a server serving EXACTLY `model` is answering on `port`. Reuses our
+// warm child or any server already serving the right model; otherwise restarts
+// — killing a wrong-model child and reclaiming the port from a wrong-model
+// orphan, so swapping models never POSTs a model the running server lacks (which
+// would trigger an in-request download and hang). Waits only REQUEST_READY_MS;
+// if the (new) model is still loading/downloading, throws so the caller falls
+// back while it finishes in the background.
+async function ensureServer(model, port) {
+  if (child && childModel === model && (await ping(port))) return;
+  const served = await servedModel(port);
+  if (served === model) return; // right model already up (orphan/external) → reuse
+  if (child) shutdown(); // our child is serving the wrong model → stop it
+  if (served) freePort(port); // an orphan holds the port with the wrong model → reclaim
+  spawnServer(model, port);
+  const deadline = Date.now() + REQUEST_READY_MS;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 600));
+    if ((await servedModel(port)) === model) return;
+  }
+  throw new Error('mlx server still warming up');
+}
+
+/**
+ * Build the OpenAI chat-completions request body. Pure.
+ * @param {string} prompt @param {string} model @param {number} [maxTokens]
+ */
+export function buildChatBody(prompt, model, maxTokens = MAX_TOKENS) {
+  return {
+    model,
+    messages: [{ role: 'user', content: prompt }],
+    max_tokens: maxTokens,
+    temperature: 0.2,
+  };
+}
+
+/**
+ * Extract the assistant text from an OpenAI chat-completions response. Pure.
+ * @param {any} json @returns {string}
+ */
+export function parseChatContent(json) {
+  const c = json?.choices?.[0]?.message?.content;
+  if (typeof c !== 'string' || !c.trim()) throw new Error('empty MLX completion');
+  return c;
+}
+
+/**
+ * Best-effort pre-warm: spawn + load the server in the background so the first
+ * real request is fast. No-op-safe — swallows the "still warming" throw; the
+ * child keeps loading. Call at startup when the MLX backend is selected.
+ * @param {number} [port]
+ */
+export function warm(port = DEFAULT_PORT) {
+  const model = readConfig().mlxModel || DEFAULT_MODEL;
+  ensureServer(model, port).catch(() => {});
+}
+
+/**
+ * Complete a prompt via the local MLX server (spawning + warming it if needed).
+ * Throws on any failure so the caller can fall through to the next backend.
+ *
+ * @param {string} prompt
+ * @param {{ model?: string, port?: number, maxTokens?: number }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function complete(prompt, { model, port = DEFAULT_PORT, maxTokens = MAX_TOKENS } = {}) {
+  const m = model || readConfig().mlxModel || DEFAULT_MODEL;
+  await ensureServer(m, port);
+  const res = await fetch(serverBase(port) + '/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(buildChatBody(prompt, m, maxTokens)),
+    signal: AbortSignal.timeout(60_000),
+  });
+  if (!res.ok) throw new Error(`MLX server HTTP ${res.status}`);
+  const json = await res.json();
+  bumpIdle();
+  return parseChatContent(json);
+}
+
+// Best-effort: don't leave the child server orphaned when the parent exits
+// cleanly. (SIGKILL can't be trapped; an orphan is harmless — ensureServer
+// reuses whatever is already answering on the port.)
+process.on('exit', shutdown);
+process.on('SIGTERM', () => { shutdown(); process.exit(0); });
+process.on('SIGINT', () => { shutdown(); process.exit(0); });

package/lib/models.js

@@ -0,0 +1,66 @@
+/**
+ * lib/models.js — curated model catalogs + machine-aware recommendations.
+ *
+ * The enhancer's Claude and MLX models are picked from these fixed lists (the
+ * UI shows dropdowns, not freeform inputs, to minimise typos / bad ids). MLX
+ * picks are sized for Apple-Silicon unified memory (16–48 GB), and the default
+ * is chosen automatically from the host's detected RAM.
+ *
+ * Exports:
+ *  - MLX_MODELS, CLAUDE_MODELS        (catalogs)
+ *  - detectMachine() → { ramGB, arch, platform, appleSilicon }
+ *  - recommendMlxModel(ramGB) → id
+ *  - recommendClaudeModel() → id
+ */
+import os from 'node:os';
+
+/**
+ * Curated MLX instruct models (4-bit, no "thinking" mode → clean JSON for the
+ * enhancer). `sizeGB` ≈ on-disk weights; `minRamGB` is the unified-memory tier
+ * at/above which the model is a comfortable pick alongside other apps.
+ * @type {{ id: string, label: string, sizeGB: number, minRamGB: number }[]}
+ */
+export const MLX_MODELS = [
+  { id: 'mlx-community/Llama-3.2-3B-Instruct-4bit', label: 'Llama 3.2 3B', sizeGB: 1.8, minRamGB: 16 },
+  { id: 'mlx-community/Qwen2.5-3B-Instruct-4bit', label: 'Qwen2.5 3B', sizeGB: 1.8, minRamGB: 16 },
+  { id: 'mlx-community/Qwen2.5-7B-Instruct-4bit', label: 'Qwen2.5 7B', sizeGB: 4.3, minRamGB: 24 },
+  { id: 'mlx-community/Llama-3.1-8B-Instruct-4bit', label: 'Llama 3.1 8B', sizeGB: 4.5, minRamGB: 24 },
+  { id: 'mlx-community/Qwen2.5-14B-Instruct-4bit', label: 'Qwen2.5 14B', sizeGB: 8.5, minRamGB: 32 },
+  { id: 'mlx-community/Qwen2.5-32B-Instruct-4bit', label: 'Qwen2.5 32B', sizeGB: 18, minRamGB: 48 },
+];
+
+/**
+ * Curated Claude models for the `claude -p` enhancer backend/fallback.
+ * @type {{ id: string, label: string }[]}
+ */
+export const CLAUDE_MODELS = [
+  { id: 'claude-haiku-4-5', label: 'Haiku 4.5 — fast, cheap' },
+  { id: 'claude-sonnet-4-6', label: 'Sonnet 4.6 — balanced' },
+  { id: 'claude-opus-4-8', label: 'Opus 4.8 — most capable' },
+];
+
+/** Detect host specs relevant to model selection. */
+export function detectMachine() {
+  const ramGB = Math.round(os.totalmem() / 1024 ** 3);
+  const arch = os.arch();
+  const platform = os.platform();
+  return { ramGB, arch, platform, appleSilicon: platform === 'darwin' && arch === 'arm64' };
+}
+
+/**
+ * Recommend an MLX model id for a given unified-memory size. Conservative so it
+ * stays snappy alongside the user's other apps: 3B (≤23 GB) → 7B (24–47 GB) →
+ * 14B (≥48 GB).
+ * @param {number} ramGB
+ * @returns {string}
+ */
+export function recommendMlxModel(ramGB) {
+  if (ramGB >= 48) return 'mlx-community/Qwen2.5-14B-Instruct-4bit';
+  if (ramGB >= 24) return 'mlx-community/Qwen2.5-7B-Instruct-4bit';
+  return 'mlx-community/Llama-3.2-3B-Instruct-4bit';
+}
+
+/** The enhancer is a short, cheap task → Haiku is the sensible default. */
+export function recommendClaudeModel() {
+  return 'claude-haiku-4-5';
+}