kiku-agent 1.3.2 → 1.3.4

package/server/agent/modelCompatibility.js

@@ -0,0 +1,352 @@
+const MODEL_PROFILES = [
+  {
+    id: 'qwen3-coder',
+    match: /qwen3[-_]?coder/i,
+    toolProtocol: 'qwen3-xml',
+    reasoningProtocol: 'qwen3',
+    supports: { nativeTools: true, legacyFunctionCall: true, textToolCalls: true, parallelTools: true },
+    contextLength: 32768,
+  },
+  {
+    id: 'qwen3',
+    match: /(?:qwen3|qwq)/i,
+    toolProtocol: 'hermes',
+    reasoningProtocol: 'qwen3',
+    supports: { nativeTools: true, legacyFunctionCall: true, textToolCalls: true, parallelTools: true },
+    contextLength: 32768,
+  },
+  {
+    id: 'qwen2.5',
+    match: /qwen(?:2[._]?5|2\.5)/i,
+    toolProtocol: 'hermes',
+    reasoningProtocol: 'none',
+    supports: { nativeTools: true, legacyFunctionCall: true, textToolCalls: true, parallelTools: true },
+    contextLength: 32768,
+  },
+  {
+    id: 'deepseek-reasoning',
+    match: /deepseek.*(?:r1|reasoner|reasoning)|deepseek-r1/i,
+    toolProtocol: 'openai',
+    reasoningProtocol: 'deepseek',
+    supports: { nativeTools: true, legacyFunctionCall: true, textToolCalls: true, parallelTools: false },
+    contextLength: 32768,
+  },
+  {
+    id: 'llama3',
+    match: /llama[-_]?3|llama4/i,
+    toolProtocol: 'llama-json',
+    reasoningProtocol: 'none',
+    supports: { nativeTools: true, legacyFunctionCall: false, textToolCalls: true, parallelTools: false },
+    contextLength: 131072,
+  },
+  {
+    id: 'mistral',
+    match: /mistral|devstral|magistral/i,
+    toolProtocol: 'mistral',
+    reasoningProtocol: 'none',
+    supports: { nativeTools: true, legacyFunctionCall: false, textToolCalls: true, parallelTools: true },
+    contextLength: 32768,
+  },
+  {
+    id: 'gemma',
+    match: /gemma/i,
+    toolProtocol: 'openai',
+    reasoningProtocol: 'none',
+    supports: { nativeTools: true, legacyFunctionCall: false, textToolCalls: true, parallelTools: true },
+    contextLength: 131072,
+  },
+  {
+    id: 'phi4',
+    match: /phi[-_]?4/i,
+    toolProtocol: 'phi4',
+    reasoningProtocol: 'none',
+    supports: { nativeTools: true, legacyFunctionCall: false, textToolCalls: true, parallelTools: false },
+    contextLength: 131072,
+  },
+];
+
+const DEFAULT_PROFILE = Object.freeze({
+  id: 'openai-compatible',
+  toolProtocol: 'openai',
+  reasoningProtocol: 'generic',
+  supports: { nativeTools: true, legacyFunctionCall: true, textToolCalls: true, parallelTools: true },
+  contextLength: null,
+});
+
+export function getModelCompatibility(provider, model) {
+  const matchText = `${provider || ''} ${model || ''}`;
+  const profile = MODEL_PROFILES.find(candidate => candidate.match.test(matchText));
+  return profile ? { ...profile, supports: { ...profile.supports } } : { ...DEFAULT_PROFILE, supports: { ...DEFAULT_PROFILE.supports } };
+}
+
+export function applyModelRequestOptions(payload, { provider, model, thinkingMode = null } = {}) {
+  const profile = getModelCompatibility(provider, model);
+  const next = { ...payload };
+  if (profile.id === 'qwen3' || profile.id === 'qwen3-coder') {
+    if (thinkingMode === 'show' || thinkingMode === 'hide') {
+      next.chat_template_kwargs = { enable_thinking: thinkingMode === 'show' };
+    }
+  }
+  return next;
+}
+
+function normalizeContent(content) {
+  if (Array.isArray(content)) {
+    return content.map(part => typeof part === 'string' ? part : part?.text || '').join('');
+  }
+  return content == null ? '' : String(content);
+}
+
+function parseArguments(argumentsValue) {
+  if (argumentsValue == null || argumentsValue === '') return '{}';
+  if (typeof argumentsValue === 'string') return argumentsValue;
+  try { return JSON.stringify(argumentsValue); } catch { return '{}'; }
+}
+
+function parsePythonArgs(argStr = '') {
+  const args = {};
+  if (!argStr || !argStr.trim()) return args;
+  
+  const regex = /([a-zA-Z0-9_]+)\s*=\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\[[\s\S]*?\]|\{[\s\S]*?\}|true|false|null|-?\d+(?:\.\d+)?)/gi;
+  let m;
+  while ((m = regex.exec(argStr)) !== null) {
+    const key = m[1];
+    let valStr = m[2];
+    if ((valStr.startsWith('"') && valStr.endsWith('"')) || (valStr.startsWith("'") && valStr.endsWith("'"))) {
+      args[key] = valStr.slice(1, -1).replace(/\\'/g, "'").replace(/\\"/g, '"');
+    } else if (valStr.toLowerCase() === 'true') {
+      args[key] = true;
+    } else if (valStr.toLowerCase() === 'false') {
+      args[key] = false;
+    } else if (valStr.toLowerCase() === 'null') {
+      args[key] = null;
+    } else if (!Number.isNaN(Number(valStr))) {
+      args[key] = Number(valStr);
+    } else {
+      try { args[key] = JSON.parse(valStr); } catch { args[key] = valStr; }
+    }
+  }
+  return args;
+}
+
+function extractTaggedCalls(content) {
+  const calls = [];
+  const patterns = [
+    /<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/gi,
+    /\[TOOL_CALLS\]\s*([\s\S]*?)(?=\[\/TOOL_CALLS\]|$)/gi,
+  ];
+  for (const pattern of patterns) {
+    for (const match of content.matchAll(pattern)) {
+      let raw = match[1].trim();
+      raw = raw.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '').trim();
+      let parsed;
+      try { parsed = JSON.parse(raw); } catch { parsed = null; }
+      const entries = Array.isArray(parsed) ? parsed : [parsed];
+      for (const entry of entries) {
+        if (!entry || typeof entry !== 'object') continue;
+        const fn = entry.function || entry;
+        const name = fn.name || entry.name || entry.tool;
+        if (!name) continue;
+        const args = fn.arguments ?? entry.arguments ?? entry.parameters ?? entry.args ?? {};
+        calls.push({
+          id: entry.id || `call_compat_${Date.now()}_${calls.length}`,
+          type: 'function',
+          function: { name: String(name), arguments: parseArguments(args) },
+        });
+      }
+    }
+  }
+
+ 
+  const pythonTagPattern = /<\|python_tag\|>([a-zA-Z0-9_]+)\(([\s\S]*?)\)/gi;
+  for (const match of content.matchAll(pythonTagPattern)) {
+    const name = match[1];
+    const argStr = match[2];
+    calls.push({
+      id: `call_compat_${Date.now()}_${calls.length}`,
+      type: 'function',
+      function: { name: String(name), arguments: JSON.stringify(parsePythonArgs(argStr)) },
+    });
+  }
+
+  return calls;
+}
+
+export function normalizeAssistantMessage(message = {}) {
+  const normalized = { ...message, role: message.role || 'assistant' };
+  let content = normalizeContent(message.content);
+  let reasoning = message.reasoning_content || message.reasoning || message.thinking || '';
+
+  const thinkPattern = /<think>\s*([\s\S]*?)(?:<\/think>|$)/gi;
+  const thinkMatches = [...content.matchAll(thinkPattern)];
+  if (thinkMatches.length > 0) {
+    for (const match of thinkMatches) {
+      if (match[1]) {
+        reasoning = `${reasoning}${reasoning ? '\n' : ''}${match[1]}`.trim();
+      }
+    }
+    content = content.replace(thinkPattern, '').trim();
+  }
+  normalized.content = content;
+  if (reasoning) normalized.reasoning_content = String(reasoning);
+
+  let toolCalls = Array.isArray(message.tool_calls) ? message.tool_calls.map((call, index) => ({
+    id: call.id || `call_compat_${Date.now()}_${index}`,
+    type: call.type || 'function',
+    function: {
+      name: call.function?.name || call.name || '',
+      arguments: parseArguments(call.function?.arguments ?? call.arguments),
+    },
+  })) : [];
+  if (toolCalls.length === 0 && message.function_call) {
+    toolCalls = [{
+      id: `call_compat_${Date.now()}_0`,
+      type: 'function',
+      function: {
+        name: message.function_call.name || '',
+        arguments: parseArguments(message.function_call.arguments),
+      },
+    }];
+  }
+  if (toolCalls.length === 0) toolCalls = extractTaggedCalls(content);
+  if (toolCalls.length > 0) {
+    normalized.tool_calls = toolCalls;
+    normalized.content = content
+      .replace(/<tool_call>\s*[\s\S]*?\s*<\/tool_call>/gi, '')
+      .replace(/\[TOOL_CALLS\][\s\S]*?(?:\[\/TOOL_CALLS\]|$)/gi, '')
+      .replace(/<\|python_tag\|>[a-zA-Z0-9_]+\([\s\S]*?\)/gi, '')
+      .trim();
+  }
+  return normalized;
+}
+
+export class StreamContentNormalizer {
+  constructor() {
+    this.buffer = '';
+    this.inThinking = false;
+    this.inToolTag = null;
+    this.toolCallBuffer = '';
+  }
+
+  push(chunk) {
+    this.buffer += String(chunk || '');
+    const answer = [];
+    const reasoning = [];
+
+    while (this.buffer) {
+      if (this.inThinking) {
+        const end = this.buffer.search(/<\/think>/i);
+        if (end < 0) {
+          reasoning.push(this.buffer);
+          this.buffer = '';
+          break;
+        }
+        reasoning.push(this.buffer.slice(0, end));
+        this.buffer = this.buffer.slice(end).replace(/^<\/think>/i, '');
+        this.inThinking = false;
+        continue;
+      }
+
+      if (this.inToolTag === 'tool_call') {
+        const end = this.buffer.search(/<\/tool_call>/i);
+        if (end < 0) {
+          this.toolCallBuffer += this.buffer;
+          this.buffer = '';
+          break;
+        }
+        this.toolCallBuffer += this.buffer.slice(0, end);
+        this.buffer = this.buffer.slice(end).replace(/^<\/tool_call>/i, '');
+        this.inToolTag = null;
+        continue;
+      }
+
+      if (this.inToolTag === 'tool_calls') {
+        const end = this.buffer.search(/\[\/TOOL_CALLS\]/i);
+        if (end < 0) {
+          this.toolCallBuffer += this.buffer;
+          this.buffer = '';
+          break;
+        }
+        this.toolCallBuffer += this.buffer.slice(0, end);
+        this.buffer = this.buffer.slice(end).replace(/^\[\/TOOL_CALLS\]/i, '');
+        this.inToolTag = null;
+        continue;
+      }
+
+      if (this.inToolTag === 'python_tag') {
+        const end = this.buffer.search(/\)/);
+        if (end < 0) {
+          this.toolCallBuffer += this.buffer;
+          this.buffer = '';
+          break;
+        }
+        this.toolCallBuffer += this.buffer.slice(0, end + 1);
+        this.buffer = this.buffer.slice(end + 1);
+        this.inToolTag = null;
+        continue;
+      }
+
+      const thinkIdx = this.buffer.search(/<think>/i);
+      const toolCallIdx = this.buffer.search(/<tool_call>/i);
+      const toolCallsIdx = this.buffer.search(/\[TOOL_CALLS\]/i);
+      const pythonTagIdx = this.buffer.search(/<\|python_tag\|>/i);
+
+      const indices = [
+        { type: 'think', idx: thinkIdx },
+        { type: 'tool_call', idx: toolCallIdx },
+        { type: 'tool_calls', idx: toolCallsIdx },
+        { type: 'python_tag', idx: pythonTagIdx },
+      ].filter(item => item.idx >= 0).sort((a, b) => a.idx - b.idx);
+
+      if (indices.length === 0) {
+        const suffix = this.buffer.match(/(?:<(?:t(?:h(?:i(?:n(?:k)?)?)?)?|t(?:o(?:o(?:l(?:_(?:c(?:a(?:l(?:l)?)?)?)?)?)?)?)?)?|\[(?:T(?:O(?:O(?:L(?:_(?:C(?:A(?:L(?:L(?:S)?)?)?)?)?)?)?)?)?)?|<\|(?:p(?:y(?:t(?:h(?:o(?:n(?:_(?:t(?:a(?:g)?)?)?)?)?)?)?)?)?)?)$/i)?.[0] || '';
+        if (suffix) {
+          answer.push(this.buffer.slice(0, -suffix.length));
+          this.buffer = suffix;
+        } else {
+          answer.push(this.buffer);
+          this.buffer = '';
+        }
+        break;
+      }
+
+      const next = indices[0];
+      answer.push(this.buffer.slice(0, next.idx));
+      if (next.type === 'think') {
+        this.buffer = this.buffer.slice(next.idx).replace(/^<think>/i, '');
+        this.inThinking = true;
+      } else if (next.type === 'tool_call') {
+        this.buffer = this.buffer.slice(next.idx).replace(/^<tool_call>/i, '');
+        this.inToolTag = 'tool_call';
+      } else if (next.type === 'tool_calls') {
+        this.buffer = this.buffer.slice(next.idx).replace(/^\[TOOL_CALLS\]/i, '');
+        this.inToolTag = 'tool_calls';
+      } else if (next.type === 'python_tag') {
+        this.buffer = this.buffer.slice(next.idx).replace(/^<\|python_tag\|>/i, '');
+        this.inToolTag = 'python_tag';
+      }
+    }
+
+    return { answer: answer.join(''), reasoning: reasoning.join('') };
+  }
+
+  flush() {
+    let reasoning = '';
+    let answer = '';
+    if (this.inThinking) {
+      reasoning = this.buffer;
+    } else if (this.inToolTag) {
+      this.toolCallBuffer += this.buffer;
+    } else {
+      answer = this.buffer;
+    }
+    const toolCallBuffer = this.toolCallBuffer;
+    this.buffer = '';
+    this.toolCallBuffer = '';
+    return {
+      answer,
+      reasoning,
+      ...(toolCallBuffer ? { toolCallBuffer } : {}),
+    };
+  }
+}

package/server/agent/modelDefaults.js

@@ -0,0 +1 @@
+export const KIKU_DEFAULT_MODEL = 'google/gemma-4-e4b';

package/server/agent/modelManager.js

@@ -7,6 +7,7 @@ export class ModelManager {
     if (!client) throw new Error('ModelManager requires an LLM client.');
     this.client = client;
     this.requestedModel = options.requestedModel || client.model;
+    this.strictModel = options.strictModel === true;
     this.fallbackModel = options.fallbackModel || null;
     this.fallbackModels = Array.isArray(options.fallbackModels) ? options.fallbackModels : [];
     this.lastResolution = null;
@@ -67,7 +68,30 @@ export class ModelManager {
   }
 
   async resolve(options = {}) {
-    const health = await this.client.checkConnection();
+    let health = await this.client.checkConnection();
+    const isLocalLmStudio = this.client.provider === 'lmstudio' &&
+      typeof this.client.baseUrl === 'string' &&
+      (this.client.baseUrl.includes('127.0.0.1:1234') || this.client.baseUrl.includes('localhost:1234') || this.client.baseUrl.includes(':1234'));
+
+    if ((!health.connected || (health.models || []).length === 0) && options.autoWakeup && isLocalLmStudio) {
+      try {
+        const { wakeUpLmStudio } = await import('./lmStudioWakeup.js');
+        const { getPersistedModelLoadSettings } = await import('./config.js');
+        const targetModel = options.requestedModel || this.requestedModel || this.client.model || 'google/gemma-4-e4b';
+        const loadSettings = getPersistedModelLoadSettings();
+        const wakeRes = await wakeUpLmStudio({
+          baseUrl: this.client.baseUrl,
+          model: targetModel,
+          quiet: options.quiet ?? false,
+          gpuOffload: options.gpuOffload !== undefined ? options.gpuOffload : loadSettings.gpuOffload,
+          cpuThreads: options.cpuThreads !== undefined ? options.cpuThreads : loadSettings.cpuThreads,
+        });
+        if (wakeRes.ok) {
+          health = await this.client.checkConnection();
+        }
+      } catch {}
+    }
+
     if (!health.connected) {
       return this._record({ state: 'server_offline', connected: false, models: [], error: health.error });
     }
@@ -112,15 +136,35 @@ export class ModelManager {
       : models.find(id => !NON_CHAT_MODEL.test(id));
 
     const selected = exact || fuzzyRequested || (activeLoaded && matchModelIdentifier(requested, activeLoaded) ? activeLoaded : null) || configuredFallback || recommendedFallback || activeLoaded || gemma || chatFallback;
+    if (this.strictModel && !exact && !fuzzyRequested) {
+      return this._record({
+        state: 'requested_model_missing',
+        connected: true,
+        models,
+        requestedModel: requested,
+        selectedModel: null,
+        isModelAvailable: false,
+        usedFallback: false,
+        error: `Requested model is not available: ${requested}`
+      });
+    }
     if (!selected) {
       return this._record({ state: 'no_chat_model', connected: true, models, error: 'No chat-capable model was found.' });
     }
 
     this.client.model = selected;
+    const isLocalEngine = this.client.provider === 'lmstudio' || this.client.provider === 'vllm';
+    const isLoadedInVram = isLocalEngine ? Boolean(activeLoaded) : true;
+
     return this._record({
-      state: (exact || fuzzyRequested) ? 'ready' : 'fallback_selected',
+      state: !isLoadedInVram && isLocalEngine
+        ? 'server_online_model_not_loaded'
+        : ((exact || fuzzyRequested) ? 'ready' : 'fallback_selected'),
       connected: true,
       models,
+      loadedModels: health.loadedModels || (activeLoaded ? [activeLoaded] : []),
+      activeLoadedModel: activeLoaded || null,
+      isModelLoaded: isLoadedInVram,
       selectedModel: selected,
       requestedModel: requested,
       usedFallback: !(exact || (fuzzyRequested && matchModelIdentifier(requested, selected))),

package/server/agent/newsWatch.js

@@ -62,11 +62,17 @@ export async function checkNewsWatch({ topic, days = 7, fetcher, state = null, s
 
 export function startNewsWatchLoop({ topic, days = 7, intervalMinutes = 30, fetcher, controller, state = null, statePath = WATCH_STATE_PATH, onDelta, onError } = {}) {
   const sleep = ms => new Promise(resolve => {
-    const timer = setTimeout(resolve, ms);
-    controller.signal.addEventListener('abort', () => {
+    let timer;
+    const onAbort = () => {
       clearTimeout(timer);
+      controller.signal.removeEventListener('abort', onAbort);
       resolve();
-    }, { once: true });
+    };
+    timer = setTimeout(() => {
+      controller.signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    controller.signal.addEventListener('abort', onAbort, { once: true });
   });
 
   return (async () => {

package/server/agent/processManager.js

@@ -0,0 +1,229 @@
+import { spawnSync } from 'node:child_process';
+
+const _activeProcesses = new Map();
+let _exitHooksInstalled = false;
+
+export function isPidAlive(pid) {
+  if (!pid || typeof pid !== 'number' || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+export function killProcessTreeSync(pid, signal = 'SIGTERM') {
+  if (!pid || typeof pid !== 'number' || pid <= 0) return false;
+  if (process.platform === 'win32') {
+    try {
+      const res = spawnSync('taskkill', ['/pid', String(pid), '/f', '/t'], {
+        stdio: 'ignore',
+        windowsHide: true,
+        timeout: 5000,
+      });
+      return res.status === 0 || !isPidAlive(pid);
+    } catch {
+      try {
+        process.kill(pid, 'SIGKILL');
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch {
+    try {
+      process.kill(pid, signal);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export async function killProcessTree(pid, signal = 'SIGTERM') {
+  return killProcessTreeSync(pid, signal);
+}
+
+export function killWslProcessByName(distro, pattern) {
+  if (!distro || !pattern || process.platform !== 'win32') return false;
+  try {
+    const res = spawnSync('wsl', ['-d', String(distro), 'pkill', '-f', String(pattern)], {
+      stdio: 'ignore',
+      windowsHide: true,
+      timeout: 5000,
+    });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function registerBackgroundProcess(name, childOrPid, options = {}) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('Process name must be a non-empty string');
+  }
+
+  ensureProcessExitHooks();
+
+  const isChildObj = childOrPid && typeof childOrPid === 'object' && typeof childOrPid.pid === 'number';
+  const pid = isChildObj ? childOrPid.pid : (typeof childOrPid === 'number' ? childOrPid : null);
+
+  if (!pid || pid <= 0) {
+    throw new Error(`Invalid PID for background process "${name}"`);
+  }
+
+  const existing = _activeProcesses.get(name);
+  if (existing && existing.status === 'running' && isPidAlive(existing.pid) && existing.pid !== pid) {
+    killProcessTreeSync(existing.pid);
+  }
+
+  const persistOnExit = Boolean(options.persistOnExit || options.metadata?.persistOnExit);
+
+  const record = {
+    id: `${name}-${pid}-${Date.now()}`,
+    name,
+    pid,
+    command: options.command || (isChildObj ? childOrPid.spawnfile : null) || 'unknown',
+    args: options.args || (isChildObj ? childOrPid.spawnargs : []) || [],
+    startedAt: options.startedAt || Date.now(),
+    status: 'running',
+    exitCode: null,
+    exitSignal: null,
+    persistOnExit,
+    metadata: { ...options.metadata, persistOnExit },
+    childProcess: isChildObj ? childOrPid : null,
+  };
+
+  if (isChildObj) {
+    childOrPid.once('exit', (code, signal) => {
+      record.status = code === 0 ? 'stopped' : 'exited';
+      record.exitCode = code;
+      record.exitSignal = signal;
+    });
+    childOrPid.once('error', (err) => {
+      record.status = 'failed';
+      record.metadata.lastError = err?.message || String(err);
+    });
+  }
+
+  _activeProcesses.set(name, record);
+  return record;
+}
+
+export function unregisterBackgroundProcess(name) {
+  return _activeProcesses.delete(name);
+}
+
+export function getBackgroundProcess(name) {
+  const rec = _activeProcesses.get(name);
+  if (!rec) return null;
+  const alive = isPidAlive(rec.pid);
+  if (!alive && rec.status === 'running') {
+    rec.status = 'stopped';
+  }
+  return {
+    ...rec,
+    isAlive: alive,
+    uptimeSeconds: Math.max(0, Math.floor((Date.now() - rec.startedAt) / 1000)),
+  };
+}
+
+export function listBackgroundProcesses() {
+  const results = [];
+  for (const [name, rec] of _activeProcesses.entries()) {
+    const alive = isPidAlive(rec.pid);
+    if (!alive && rec.status === 'running') {
+      rec.status = 'stopped';
+    }
+    results.push({
+      name,
+      pid: rec.pid,
+      status: rec.status,
+      isAlive: alive,
+      command: rec.command,
+      startedAt: rec.startedAt,
+      uptimeSeconds: Math.max(0, Math.floor((Date.now() - rec.startedAt) / 1000)),
+      metadata: { ...rec.metadata },
+    });
+  }
+  return results;
+}
+
+export function stopBackgroundProcess(name, options = {}) {
+  const rec = _activeProcesses.get(name);
+  if (!rec) {
+    return { ok: false, reason: `Process "${name}" not found in registry` };
+  }
+
+  const pid = rec.pid;
+  const signal = options.signal || 'SIGTERM';
+  let killed = false;
+
+  if (isPidAlive(pid)) {
+    killed = killProcessTreeSync(pid, signal);
+  } else {
+    killed = true;
+  }
+
+  if (rec.metadata?.isWsl && rec.metadata?.distro && rec.metadata?.wslProcessPattern) {
+    killWslProcessByName(rec.metadata.distro, rec.metadata.wslProcessPattern);
+  }
+
+  rec.status = 'stopped';
+  rec.exitSignal = signal;
+
+  return {
+    ok: killed,
+    name,
+    pid,
+    status: 'stopped',
+  };
+}
+
+export function stopAllBackgroundProcessesSync(options = {}) {
+  const force = Boolean(options && options.force);
+  const stopped = [];
+  for (const [name, rec] of _activeProcesses.entries()) {
+    if (!force && (rec.persistOnExit || rec.metadata?.persistOnExit)) {
+      continue;
+    }
+    if (rec.status === 'running' || isPidAlive(rec.pid)) {
+      killProcessTreeSync(rec.pid);
+      if (rec.metadata?.isWsl && rec.metadata?.distro && rec.metadata?.wslProcessPattern) {
+        killWslProcessByName(rec.metadata.distro, rec.metadata.wslProcessPattern);
+      }
+      rec.status = 'stopped';
+      stopped.push({ name, pid: rec.pid });
+    }
+  }
+  return stopped;
+}
+
+export function stopAllBackgroundProcesses(options = {}) {
+  return stopAllBackgroundProcessesSync(options);
+}
+
+export function clearProcessRegistry() {
+  _activeProcesses.clear();
+}
+
+export function ensureProcessExitHooks() {
+  if (_exitHooksInstalled) return;
+  _exitHooksInstalled = true;
+
+  const cleanupSync = () => {
+    stopAllBackgroundProcessesSync({ force: false });
+  };
+
+  process.once('exit', cleanupSync);
+}
+
+export function initProcessExitHooks() {
+  ensureProcessExitHooks();
+}