@winspan/claude-forge 8.41.0 → 8.51.0

package/src/daemon/index.ts

@@ -0,0 +1,292 @@
+/**
+ * Daemon entry point — starts the Forge daemon process
+ *
+ * Responsibilities:
+ * 1. Load config and initialize logging
+ * 2. Manage lifecycle (PID, socket, auth token)
+ * 3. Initialize storage, AI provider, and core services
+ * 4. Create event handlers and start socket server
+ * 5. Handle graceful shutdown
+ */
+
+import { SocketServer } from './server.js';
+import {
+  writePidFile,
+  removePidFile,
+  cleanSocket,
+  getSocketPath,
+  writeAuthToken,
+  syncMcpToken,
+  removeAuthToken,
+} from './lifecycle.js';
+import { routeEvent, type Handlers } from './router.js';
+import { logger } from '../core/utils/logger.js';
+import { ConfigManager } from '../core/config.js';
+import { SQLiteStorage } from '../core/storage/sqlite.js';
+import { expandPath } from '../core/utils/path.js';
+import { ClaudeProvider } from '../core/ai/provider.js';
+import { TaskSegmenter } from './services/task-segmenter.js';
+import { SkillRegistry } from '../skills/registry.js';
+import { InvocationGuard } from '../skills/invocation-guard.js';
+import { HistoryExporter } from './handlers/history-exporter.js';
+import { ResumeManager } from '../claudemd/resume-manager.js';
+import { ConventionExtractor } from '../claudemd/convention-extractor.js';
+import { UserPromptHandler } from './handlers/user-prompt.js';
+import { PostToolUseHandler } from './handlers/post-tool-use.js';
+import { StopHandler } from './handlers/stop.js';
+import { replayQueue } from '../core/queue/index.js';
+import { DEFAULTS } from '../core/constants.js';
+import type { ForgeEvent } from '../core/types.js';
+import { getUserPrompt } from '../core/event-fields.js';
+import type { HookResponse } from './server.js';
+
+export interface DaemonOptions {
+  /** Whether to enable the web server (default: use config value) */
+  web?: boolean;
+}
+
+export async function startDaemon(foreground: boolean = false, options: DaemonOptions = {}): Promise<void> {
+  // ── 0. Global Exception Handlers ───────────────────────────────────────────
+  process.on('uncaughtException', (err) => {
+    logger.error(`[Daemon] Uncaught exception: ${err.message}`);
+    logger.error(err.stack || '');
+    // Don't exit — let daemon continue running
+  });
+
+  process.on('unhandledRejection', (reason, promise) => {
+    logger.error(`[Daemon] Unhandled rejection at ${promise}: ${reason}`);
+  });
+
+  // ── 1. Config & Logging ────────────────────────────────────────────────────
+  // Log level is auto-parsed from LOG_LEVEL env var at logger module load time.
+  const config = new ConfigManager().get();
+  logger.info('Claude Forge daemon starting...');
+
+  // ── 2. Lifecycle (PID, socket, auth token) ─────────────────────────────────
+  cleanSocket();
+  writePidFile();
+  const authToken = writeAuthToken();
+  logger.info('[Security] Auth token generated');
+  syncMcpToken(authToken, config.web?.port ?? DEFAULTS.WEB_PORT);
+
+  // ── 3. Storage ─────────────────────────────────────────────────────────────
+  const dbPath = expandPath(config.storage.path);
+  const storage = new SQLiteStorage(dbPath);
+  logger.info(`Storage initialized: ${dbPath}`);
+
+  // ── 4. AI Provider ─────────────────────────────────────────────────────────
+  const apiKey = config.ai.api_key || process.env.ANTHROPIC_API_KEY || '';
+  if (!apiKey) {
+    logger.warn('No API key configured — AI features disabled');
+  }
+
+  const ai = apiKey
+    ? new ClaudeProvider(apiKey, config.ai.model, config.ai.base_url)
+    : null;
+
+  // ── 5. Initialize services ─────────────────────────────────────────────────
+  const skillApiKey = config.skill_matching?.api_key || apiKey;
+  const skillRegistry = new SkillRegistry(skillApiKey);
+  const invocationGuard = new InvocationGuard();
+  if (skillApiKey) {
+    logger.info('[Skills] Registry loaded with semantic matching support');
+  } else {
+    logger.info('[Skills] Registry loaded (keyword matching)');
+  }
+  logger.info('[Skills] InvocationGuard ready (idempotent + depth/total limits)');
+
+  const exporter = new HistoryExporter(storage);
+  const resume = new ResumeManager(storage);
+  const conventionExtractor = new ConventionExtractor();
+  const taskSegmenter = new TaskSegmenter(storage);
+
+  logger.info('[Services] Initialized: ResumeManager, TaskSegmenter, SkillRegistry');
+
+  // ── 5.5. Schedule daily maintenance ────────────────────────────────────────
+  // Clean old events every 24 hours
+  const MAINTENANCE_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+  const maintenanceInterval = setInterval(() => {
+    logger.info('[Daemon] Running daily maintenance: cleaning old events');
+    try {
+      storage.cleanOldEvents(30);
+    } catch (err) {
+      logger.error(`[Daemon] Maintenance failed: ${err}`);
+    }
+  }, MAINTENANCE_INTERVAL);
+  logger.info('[Daemon] Scheduled daily maintenance (clean events older than 30 days)');
+
+  // ── 5.6. Stale task GC (every 5 minutes) ──────────────────────────────────
+  const STALE_TASK_GC_INTERVAL = 5 * 60 * 1000; // 5 分钟
+  const STALE_TASK_IDLE_MINUTES = 10;            // idle 超 10 分钟视为滞留
+
+  const staleTaskGcInterval = setInterval(() => {
+    try {
+      const closed = storage.completeStaleActiveTasks(STALE_TASK_IDLE_MINUTES);
+      if (closed > 0) {
+        logger.info(`[Maintenance] Auto-completed ${closed} stale active task(s)`);
+      }
+    } catch (err) {
+      logger.error(`[Maintenance] Stale task GC failed: ${err}`);
+    }
+  }, STALE_TASK_GC_INTERVAL);
+
+  // ── 6. Create handlers ─────────────────────────────────────────────────────
+  const userPromptHandler = new UserPromptHandler(
+    resume,
+    conventionExtractor,
+    storage,
+    skillRegistry,
+  );
+
+  const handlers: Handlers = {
+    UserPromptSubmit: userPromptHandler,
+    PostToolUse: new PostToolUseHandler(storage),
+    Stop: new StopHandler(
+      exporter,
+      resume,
+      taskSegmenter,
+      storage,
+      invocationGuard,
+      userPromptHandler,
+    ),
+  };
+
+  // ── 7. Event handler ───────────────────────────────────────────────────────
+  const handleEvent = async (event: ForgeEvent): Promise<HookResponse | void> => {
+    try {
+      try {
+        storage.writeEvent(event);
+      } catch (writeErr) {
+        const writeMsg = writeErr instanceof Error ? writeErr.message : String(writeErr);
+        if (writeMsg.includes('UNIQUE constraint failed')) {
+          // Duplicate event_id — already in DB (e.g. replayed from queue then re-sent).
+          // Log at debug level and continue processing the event normally.
+          logger.debug(`[Event] Duplicate event_id ignored: ${event.event_id}`);
+        } else {
+          throw writeErr;
+        }
+      }
+      logger.debug(`[Event] ${event.hook_type} | tool=${event.tool_name ?? 'N/A'}`);
+
+      // Task segmentation: UserPromptSubmit starts/continues tasks
+      const prompt = getUserPrompt(event);
+      if (event.hook_type === 'UserPromptSubmit' && prompt) {
+        taskSegmenter.processPrompt(event.session_id, prompt, event.timestamp, event.event_id);
+      } else if (event.event_id) {
+        taskSegmenter.linkEvent(event.session_id, event.event_id);
+      }
+
+      // PreToolUse: always allow (governance removed)
+      if (event.hook_type === 'PreToolUse') {
+        return { allow: true };
+      }
+
+      const result = await routeEvent(event, handlers);
+
+      if (result) {
+        const handlerName = event.hook_type + 'Handler';
+        if (result.systemMessage) {
+          storage.writeInjection({
+            event_id: event.event_id,
+            session_id: event.session_id,
+            timestamp: event.timestamp,
+            source_handler: handlerName,
+            injection_type: 'systemMessage',
+            content: result.systemMessage,
+          });
+          const preview = result.systemMessage.slice(0, 200).replace(/\n/g, ' ');
+          console.error(`\x1b[36m[${handlerName}] systemMessage (${result.systemMessage.length} chars): ${preview}\x1b[0m`);
+        }
+        if (result.additionalContext) {
+          storage.writeInjection({
+            event_id: event.event_id,
+            session_id: event.session_id,
+            timestamp: event.timestamp,
+            source_handler: handlerName,
+            injection_type: 'additionalContext',
+            content: result.additionalContext,
+          });
+          const preview = result.additionalContext.slice(0, 200).replace(/\n/g, ' ');
+          console.error(`\x1b[36m[${handlerName}] additionalContext: ${preview}\x1b[0m`);
+        }
+      }
+
+      return result;
+    } catch (err) {
+      logger.error(`Event handling failed: ${err}`);
+      throw err;
+    }
+  };
+
+  // ── 8. Start socket server ─────────────────────────────────────────────────
+  const socketPath = getSocketPath();
+  const server = new SocketServer(socketPath, handleEvent, authToken);
+
+  // ── 8.1. Replay queued events (hook failures during daemon downtime) ────────
+  // Run after the socket is created so the daemon is ready to receive events.
+  // setImmediate ensures the event loop has had a chance to process the listen
+  // callback before we touch storage (not strictly required, but defensive).
+  setImmediate(() => {
+    replayQueue(storage).then(({ replayed, skipped, dead }) => {
+      if (replayed > 0 || skipped > 0 || dead > 0) {
+        logger.info(`[Queue] Replay: ${replayed} replayed, ${skipped} skipped (dup), ${dead} dead-lettered`);
+      }
+    }).catch((err) => {
+      logger.error(`[Queue] replayQueue failed: ${err}`);
+    });
+  });
+
+  // ── 8.5. Start web server (optional) ───────────────────────────────────────
+  // Priority: CLI option > env var > config file
+  const webEnabled = options.web ?? (process.env.FORGE_DAEMON_NO_WEB === '1' ? false : config.web.enabled);
+  let webServer: any = null;
+  if (webEnabled) {
+    const { WebServer } = await import('../web/server.js');
+    webServer = new WebServer({
+      port: config.web.port,
+      storage,
+      skillRegistry,
+      invocationGuard,
+    });
+    await webServer.start();
+  } else {
+    logger.info('[Web] Server disabled (--no-web or config.web.enabled=false)');
+  }
+
+  // ── 9. Graceful shutdown ───────────────────────────────────────────────────
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.info('Shutting down...');
+
+    if (ai) logger.info(`[AI Stats] ${ai.formatStats()}`);
+
+    clearInterval(maintenanceInterval);
+    clearInterval(staleTaskGcInterval);
+    if (webServer) await webServer.stop();
+    await server.close();
+    storage.close();
+    removePidFile();
+    cleanSocket();
+    removeAuthToken();
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  logger.info(`Daemon started (PID: ${process.pid})`);
+  if (foreground) {
+    process.stdout.write(`Claude Forge daemon running (PID: ${process.pid})\n`);
+    process.stdout.write('Press Ctrl+C to stop\n');
+  }
+}
+
+// Allow running as standalone script (spawned by `cf daemon start`)
+if (process.env.FORGE_DAEMON_FOREGROUND === '1') {
+  startDaemon(true).catch((err) => {
+    console.error('Daemon failed to start:', err);
+    process.exit(1);
+  });
+}

package/src/daemon/launchd/com.claude-forge.daemon.plist.template

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.claude-forge.daemon</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{NODE_PATH}}</string>
+        <string>{{DAEMON_PATH}}</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>{{HOME}}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+        <key>NODE_ENV</key>
+        <string>production</string>
+        <key>FORGE_DAEMON_FOREGROUND</key>
+        <string>1</string>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>{{HOME}}/.claude-forge/daemon-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{HOME}}/.claude-forge/daemon-stderr.log</string>
+</dict>
+</plist>

package/src/daemon/launchd-installer.ts

@@ -0,0 +1,260 @@
+/**
+ * macOS LaunchAgent integration for the Forge daemon.
+ *
+ * Renders the plist template, installs/uninstalls the LaunchAgent via launchctl,
+ * and reports status. Intended to give the daemon supervisor-grade auto-restart
+ * behavior on darwin without depending on systemd.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execSync, execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const LAUNCHD_LABEL = 'com.claude-forge.daemon';
+export const LAUNCH_AGENTS_DIR = path.join(os.homedir(), 'Library', 'LaunchAgents');
+export const PLIST_PATH = path.join(LAUNCH_AGENTS_DIR, `${LAUNCHD_LABEL}.plist`);
+
+export const TEMPLATE_PATH = path.resolve(
+  __dirname,
+  'launchd',
+  'com.claude-forge.daemon.plist.template'
+);
+
+export function ensureDarwin(): void {
+  if (process.platform !== 'darwin') {
+    throw new Error(
+      `LaunchAgent commands are only supported on macOS (current platform: ${process.platform}). ` +
+        `Use './scripts/dev-daemon.sh' or 'cf daemon start' on other platforms.`
+    );
+  }
+}
+
+export function getUid(): number {
+  if (typeof process.getuid === 'function') {
+    return process.getuid();
+  }
+  // Fallback: shell out (process.getuid is undefined on Windows but always defined on darwin).
+  return parseInt(execSync('id -u', { encoding: 'utf-8' }).trim(), 10);
+}
+
+export interface RenderOptions {
+  /**
+   * If true, points ProgramArguments at the local development build
+   * (`<repo>/dist/daemon/index.js` resolved from this module's location).
+   * Otherwise, resolves the daemon entry from the globally-installed package.
+   */
+  dev?: boolean;
+  /**
+   * Optional explicit path to the daemon entrypoint.
+   * Takes precedence over `dev`.
+   */
+  daemonPath?: string;
+  /**
+   * Optional explicit node path. Defaults to `process.execPath`.
+   */
+  nodePath?: string;
+}
+
+/**
+ * Resolve the path to `dist/daemon/index.js`.
+ *
+ * - In dev mode: resolves relative to this module (works in both src and dist).
+ * - In production mode: prefers a globally-installed `claude-forge` binary,
+ *   falling back to the path resolved from this module.
+ */
+export function resolveDaemonPath(opts: RenderOptions = {}): string {
+  if (opts.daemonPath) {
+    if (!fs.existsSync(opts.daemonPath)) {
+      throw new Error(`Provided daemon path does not exist: ${opts.daemonPath}`);
+    }
+    return opts.daemonPath;
+  }
+
+  // From `dist/daemon/launchd-installer.js` -> `dist/daemon/index.js`
+  // From `src/daemon/launchd-installer.ts` -> would resolve to src path; but we only ship dist.
+  const localGuess = path.resolve(__dirname, 'index.js');
+
+  if (opts.dev) {
+    if (!fs.existsSync(localGuess)) {
+      throw new Error(
+        `Local daemon entry not found at ${localGuess}. Run 'npm run build' first.`
+      );
+    }
+    return localGuess;
+  }
+
+  // Production mode: try to find global install via `which claude-forge`.
+  try {
+    const cliPath = execSync('command -v claude-forge', { encoding: 'utf-8' }).trim();
+    if (cliPath) {
+      const resolved = fs.realpathSync(cliPath);
+      // The CLI lives at <pkg>/dist/cli/index.js; daemon at <pkg>/dist/daemon/index.js.
+      const pkgRoot = path.resolve(path.dirname(resolved), '..');
+      const candidate = path.join(pkgRoot, 'daemon', 'index.js');
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  } catch {
+    // Ignore — fall through to local guess.
+  }
+
+  if (fs.existsSync(localGuess)) {
+    return localGuess;
+  }
+
+  throw new Error(
+    `Could not locate daemon entry. Install claude-forge globally (npm i -g @winspan/claude-forge) ` +
+      `or run with --dev after 'npm run build'.`
+  );
+}
+
+export function renderPlist(opts: RenderOptions = {}): string {
+  if (!fs.existsSync(TEMPLATE_PATH)) {
+    throw new Error(`plist template missing at ${TEMPLATE_PATH}. Did you run 'npm run build'?`);
+  }
+  const template = fs.readFileSync(TEMPLATE_PATH, 'utf-8');
+  const nodePath = opts.nodePath ?? process.execPath;
+  const daemonPath = resolveDaemonPath(opts);
+  const home = os.homedir();
+
+  return template
+    .replace(/{{NODE_PATH}}/g, nodePath)
+    .replace(/{{DAEMON_PATH}}/g, daemonPath)
+    .replace(/{{HOME}}/g, home);
+}
+
+function runLaunchctl(args: string[]): { stdout: string; stderr: string; code: number } {
+  try {
+    const stdout = execFileSync('launchctl', args, {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { stdout, stderr: '', code: 0 };
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { stdout?: Buffer; stderr?: Buffer; status?: number };
+    return {
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? e.message ?? '',
+      code: e.status ?? 1,
+    };
+  }
+}
+
+export interface InstallResult {
+  plistPath: string;
+  nodePath: string;
+  daemonPath: string;
+  reloaded: boolean;
+}
+
+export function install(opts: RenderOptions = {}): InstallResult {
+  ensureDarwin();
+  fs.mkdirSync(LAUNCH_AGENTS_DIR, { recursive: true });
+
+  const uid = getUid();
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+
+  // Idempotent: bootout existing service before re-installing.
+  let reloaded = false;
+  if (fs.existsSync(PLIST_PATH)) {
+    const r = runLaunchctl(['bootout', `gui/${uid}`, PLIST_PATH]);
+    if (r.code === 0 || /No such process|Could not find specified service/.test(r.stderr)) {
+      reloaded = true;
+    } else {
+      // Non-fatal; proceed and let bootstrap surface real errors.
+      reloaded = true;
+    }
+  }
+
+  const rendered = renderPlist(opts);
+  fs.writeFileSync(PLIST_PATH, rendered, { mode: 0o644 });
+
+  const bootstrap = runLaunchctl(['bootstrap', `gui/${uid}`, PLIST_PATH]);
+  if (bootstrap.code !== 0) {
+    throw new Error(
+      `launchctl bootstrap failed (exit ${bootstrap.code}): ${bootstrap.stderr.trim() || bootstrap.stdout.trim()}\n` +
+        `Service target: ${target}`
+    );
+  }
+
+  // Best-effort kickstart so the daemon comes up immediately.
+  runLaunchctl(['kickstart', '-k', target]);
+
+  // Read back rendered values to report.
+  const nodePath = opts.nodePath ?? process.execPath;
+  const daemonPath = resolveDaemonPath(opts);
+
+  return { plistPath: PLIST_PATH, nodePath, daemonPath, reloaded };
+}
+
+export interface UninstallResult {
+  removedPlist: boolean;
+  bootedOut: boolean;
+}
+
+export function uninstall(): UninstallResult {
+  ensureDarwin();
+  const uid = getUid();
+
+  let bootedOut = false;
+  if (fs.existsSync(PLIST_PATH)) {
+    const r = runLaunchctl(['bootout', `gui/${uid}`, PLIST_PATH]);
+    bootedOut =
+      r.code === 0 || /No such process|Could not find specified service/.test(r.stderr);
+  }
+
+  let removedPlist = false;
+  if (fs.existsSync(PLIST_PATH)) {
+    fs.unlinkSync(PLIST_PATH);
+    removedPlist = true;
+  }
+
+  return { bootedOut, removedPlist };
+}
+
+export interface LaunchdStatus {
+  installed: boolean;
+  loaded: boolean;
+  pid: number | null;
+  lastExitCode: number | null;
+  state: string | null;
+  raw: string;
+}
+
+export function status(): LaunchdStatus {
+  ensureDarwin();
+  const uid = getUid();
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+  const installed = fs.existsSync(PLIST_PATH);
+
+  const r = runLaunchctl(['print', target]);
+  if (r.code !== 0) {
+    return {
+      installed,
+      loaded: false,
+      pid: null,
+      lastExitCode: null,
+      state: null,
+      raw: r.stderr.trim() || r.stdout.trim(),
+    };
+  }
+
+  const out = r.stdout;
+  const pidMatch = out.match(/^\s*pid\s*=\s*(\d+)/m);
+  const stateMatch = out.match(/^\s*state\s*=\s*([\w-]+)/m);
+  const exitMatch = out.match(/^\s*last exit code\s*=\s*(-?\d+)/mi);
+
+  return {
+    installed,
+    loaded: true,
+    pid: pidMatch ? parseInt(pidMatch[1], 10) : null,
+    state: stateMatch ? stateMatch[1] : null,
+    lastExitCode: exitMatch ? parseInt(exitMatch[1], 10) : null,
+    raw: out,
+  };
+}