@seamnet/client 0.12.4

package/lib/errors.cjs

@@ -0,0 +1,66 @@
+/**
+ * Seam Error — 统一错误对象。
+ *
+ * 设计：
+ * - 错误都有 code（机器可识别）、message（人可读）、hint（修复建议）、docs（排查文档锚点）
+ * - toPublic() 用于 MCP 响应——不含 stack、cause
+ * - toLog() 用于 JSONL 日志——含 stack、cause
+ */
+
+class SeamError extends Error {
+  constructor({ code, message, hint, docs, cause, reqId } = {}) {
+    super(message || code || 'unknown error');
+    this.name = 'SeamError';
+    this.code = code || 'UNKNOWN';
+    this.hint = hint;
+    this.docs = docs;
+    this.cause = cause;
+    this.reqId = reqId;
+  }
+
+  toPublic() {
+    const out = { code: this.code, message: this.message };
+    if (this.hint) out.hint = this.hint;
+    if (this.docs) out.docs = this.docs;
+    if (this.reqId) out.req_id = this.reqId;
+    return out;
+  }
+
+  toLog() {
+    return {
+      code: this.code,
+      message: this.message,
+      hint: this.hint,
+      docs: this.docs,
+      req_id: this.reqId,
+      stack: this.stack,
+      cause: this.cause?.message || (typeof this.cause === 'string' ? this.cause : undefined),
+    };
+  }
+}
+
+function seamError(opts) {
+  return new SeamError(opts);
+}
+
+/**
+ * 包装任意 error 成 SeamError。
+ * - 已经是 SeamError：不包装，补全缺失的 reqId
+ * - 其他：创建新 SeamError，cause 指向原 error
+ */
+function wrap(err, { code, hint, docs, reqId } = {}) {
+  if (err instanceof SeamError) {
+    if (reqId && !err.reqId) err.reqId = reqId;
+    return err;
+  }
+  return new SeamError({
+    code: code || 'UNKNOWN',
+    message: err?.message || String(err),
+    hint,
+    docs,
+    reqId,
+    cause: err,
+  });
+}
+
+module.exports = { SeamError, seamError, wrap };

package/lib/guardian-core.cjs

@@ -0,0 +1,200 @@
+/**
+ * Guardian Core — 两阶段生命周期 + socket server。
+ *
+ * 设计：
+ * 1. 注册阶段：所有插件 register 到 hub，actions 建立唯一性检查
+ * 2. Init 阶段：依次 init 每个插件，错误经 hub.run 隔离
+ * 3. Serve 阶段：socket server 按 action 路由到插件
+ * 4. Stop 阶段：倒序 destroy，每个有 5s 超时
+ */
+
+const net = require('node:net');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { createHub } = require('./hub.cjs');
+const { createLogger } = require('./services/logger/index.cjs');
+const { createStateService } = require('./services/state/index.cjs');
+const { createEventBus } = require('./services/event-bus/index.cjs');
+const { createMessageBuffer } = require('./services/message-buffer/index.cjs');
+const { createInboxService } = require('./services/inbox/index.cjs');
+const { wrap } = require('./errors.cjs');
+
+/**
+ * 启动 guardian core。
+ *
+ * @param {Object} opts
+ * @param {string} opts.seamDir       - .seam/ 路径
+ * @param {string} opts.socketPath    - Unix socket 路径
+ * @param {string} opts.logPath       - JSONL 日志路径
+ * @param {string} [opts.ccSession]   - CC tmux 会话名（可选）
+ * @param {Object} [opts.credentials] - IM 凭据
+ * @param {Array}  [opts.plugins]     - 符合 Plugin 契约的插件数组
+ * @returns {Promise<{hub, server, stop}>}
+ */
+async function startGuardianCore({
+  seamDir,
+  socketPath,
+  logPath,
+  ccSession = '',
+  ccSocket = '',
+  credentials = {},
+  plugins = [],
+}) {
+  const logger = createLogger({ logPath });
+  const coreLog = logger.child({ plugin: 'guardian' });
+  const hub = createHub({ seamDir, ccSession, ccSocket, credentials, logger });
+
+  // === 注册内置 Services ===
+  const stateService = createStateService({
+    stateFile: path.join(seamDir, 'state.json'),
+  });
+  const eventBus = createEventBus();
+  const messageBuffer = createMessageBuffer();
+  const inboxService = createInboxService();
+  hub.registerService(stateService);
+  hub.registerService(eventBus);
+  hub.registerService(messageBuffer);
+  hub.registerService(inboxService);
+
+  for (const svc of hub.listServices()) {
+    const [err] = await hub.run(svc.name, () => svc.init(hub));
+    if (err) {
+      coreLog.error('service_init_failed', err.toLog ? err.toLog() : err, {
+        service: svc.name,
+      });
+    } else {
+      coreLog.info('service_init_success', { service: svc.name });
+    }
+  }
+
+  // === 阶段 1: 注册 ===
+  const actionMap = new Map();
+  for (const plugin of plugins) {
+    hub.register(plugin);
+    for (const action of plugin.actions || []) {
+      if (actionMap.has(action)) {
+        throw new Error(
+          `Duplicate action: ${action} (already registered by ${actionMap.get(action).name}, now ${plugin.name})`
+        );
+      }
+      actionMap.set(action, plugin);
+    }
+  }
+  coreLog.info('plugins_registered', {
+    count: plugins.length,
+    names: plugins.map((p) => p.name),
+    actions: [...actionMap.keys()],
+  });
+
+  // === 阶段 2: init（错误隔离）===
+  for (const plugin of plugins) {
+    const [err] = await hub.run(plugin.name, () => plugin.init(hub));
+    if (err) {
+      coreLog.error('plugin_init_failed', err.toLog ? err.toLog() : err, {
+        plugin: plugin.name,
+      });
+    } else {
+      coreLog.info('plugin_init_success', { plugin: plugin.name });
+    }
+  }
+
+  // === 阶段 3: socket server ===
+  if (fs.existsSync(socketPath)) {
+    fs.unlinkSync(socketPath);
+  }
+
+  const server = net.createServer((conn) => {
+    let buffer = '';
+    conn.on('data', async (chunk) => {
+      buffer += chunk;
+      let req;
+      try {
+        req = JSON.parse(buffer);
+      } catch {
+        return; // incomplete, wait for more
+      }
+
+      const reqId = req.req_id || crypto.randomUUID();
+      const reqLog = logger.child({ plugin: 'guardian', reqId });
+      reqLog.info('request', { action: req.action });
+
+      const plugin = actionMap.get(req.action);
+      if (!plugin) {
+        reqLog.warn('unknown_action', { action: req.action });
+        conn.end(
+          JSON.stringify({
+            error: {
+              code: 'UNKNOWN_ACTION',
+              message: `No plugin handles action: ${req.action}`,
+              req_id: reqId,
+            },
+          })
+        );
+        return;
+      }
+
+      const [err, result] = await hub.run(plugin.name, () =>
+        plugin.handleRequest({ ...req, req_id: reqId })
+      );
+      if (err) {
+        if (!err.reqId) err.reqId = reqId;
+        reqLog.error('handler_failed', err.toLog ? err.toLog() : err, {
+          action: req.action,
+          plugin: plugin.name,
+        });
+        const publicErr = err.toPublic ? err.toPublic() : { code: 'UNKNOWN', message: String(err), req_id: reqId };
+        conn.end(JSON.stringify({ error: publicErr }));
+      } else {
+        reqLog.info('request_done', { action: req.action, plugin: plugin.name });
+        conn.end(JSON.stringify({ ...(result || {}), req_id: reqId }));
+      }
+    });
+    conn.on('error', (e) => {
+      coreLog.error('conn_error', e);
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(socketPath, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+  // Restrict socket to owner only (单机多用户防护)
+  try {
+    fs.chmodSync(socketPath, 0o600);
+  } catch (e) {
+    coreLog.warn('chmod_failed', { message: e.message });
+  }
+
+  coreLog.info('serving', { socketPath });
+
+  // === Stop function ===
+  async function stop() {
+    coreLog.info('stopping');
+    return new Promise(async (resolve) => {
+      server.close(async () => {
+        // destroy plugins first (they may depend on services)
+        for (const plugin of [...plugins].reverse()) {
+          await hub.run(plugin.name, () => plugin.destroy(), { timeout: 5000 });
+        }
+        // then destroy services
+        for (const svc of [...hub.listServices()].reverse()) {
+          await hub.run(svc.name, () => svc.destroy(), { timeout: 5000 });
+        }
+        try {
+          if (fs.existsSync(socketPath)) fs.unlinkSync(socketPath);
+        } catch {}
+        coreLog.info('stopped');
+        resolve();
+      });
+    });
+  }
+
+  return { hub, server, actionMap, stop, logger };
+}
+
+module.exports = { startGuardianCore };

package/lib/guardian.js

@@ -0,0 +1,261 @@
+/**
+ * Seam Guardian — 后台长驻进程。
+ *
+ * guardianStart: spawn detached node 子进程跑 guardianRun（在当前 tmux 会话后台）
+ * guardianRun:   加载插件 → 调 startGuardianCore → 保留业务逻辑（greeting / CC 重启）
+ * guardianStop:  根据 .seam/guardian.pid 发 SIGTERM
+ *
+ * 设计：
+ * - 不再 fork 独立 tmux session；guardian 作为**当前 tmux session 的后台进程**运行
+ * - auto-restart CC 直接 send-keys 到当前 session 的前台 pane（就是 CC）
+ * - 生命期：绑定当前 tmux 会话（session 关掉 guardian 也挂，这是预期的）
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, openSync, readlinkSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { execSync, spawn } from 'node:child_process';
+import { SEAM_DIR, CREDENTIALS_PATH, SOCKET_PATH, LOGS_DIR, PID_PATH } from './paths.js';
+
+/**
+ * 解析 $TMUX 里的 socket path。返回可用于 `tmux -S <path>` 的绝对路径或 null。
+ *
+ * $TMUX 格式：`<socket_path>,<tmux_pid>,<window_index>`
+ * - 绝对路径（如 `/tmp/tmux-1003/default`）直接用
+ * - 相对名（如 `my`）通过 /proc/<pid>/cwd 拼成绝对路径
+ */
+export function resolveTmuxSocketPath(tmuxEnv = process.env.TMUX) {
+  if (!tmuxEnv) return null;
+  const [rawPath, pidStr] = tmuxEnv.split(',');
+  if (!rawPath) return null;
+  if (isAbsolute(rawPath)) return rawPath;
+  if (pidStr) {
+    try {
+      const cwd = readlinkSync(`/proc/${pidStr}/cwd`);
+      return join(cwd, rawPath);
+    } catch {}
+  }
+  return null;
+}
+
+function tmuxCmd(socketPath) {
+  return socketPath ? `tmux -S ${JSON.stringify(socketPath)}` : 'tmux';
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readGuardianPid() {
+  if (!existsSync(PID_PATH)) return null;
+  try {
+    const pid = parseInt(readFileSync(PID_PATH, 'utf8').trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isGuardianRunning() {
+  const pid = readGuardianPid();
+  return pid !== null && isPidAlive(pid);
+}
+
+export async function guardianStart() {
+  if (!existsSync(CREDENTIALS_PATH)) {
+    console.error('No credentials found. Run: npx seam-client init first.');
+    process.exit(1);
+  }
+
+  if (isGuardianRunning()) {
+    const pid = readGuardianPid();
+    console.log(`Guardian already running (pid: ${pid})`);
+    return;
+  }
+
+  // 清理 stale pid 文件
+  if (existsSync(PID_PATH)) {
+    try { unlinkSync(PID_PATH); } catch {}
+  }
+
+  if (!existsSync(LOGS_DIR)) mkdirSync(LOGS_DIR, { recursive: true });
+
+  const socketPath = resolveTmuxSocketPath();
+  const tmux = tmuxCmd(socketPath);
+
+  let ccSession = '';
+  try {
+    ccSession = execSync(`${tmux} display-message -p '#S'`, { encoding: 'utf8' }).trim();
+  } catch {}
+
+  const cwd = process.cwd();
+  const localCli = join(cwd, 'node_modules', '@seamnet', 'client', 'bin', 'cli.js');
+  const logPath = join(LOGS_DIR, 'guardian.log');
+  const logFd = openSync(logPath, 'a');
+
+  const child = spawn(process.execPath, [localCli, 'guardian', 'run'], {
+    cwd,
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env: {
+      ...process.env,
+      SEAM_CC_SESSION: ccSession,
+      SEAM_CC_SOCKET: socketPath || '',
+    },
+  });
+
+  child.unref();
+
+  writeFileSync(PID_PATH, String(child.pid));
+
+  console.log(`Guardian started (pid: ${child.pid}, background in current tmux session)`);
+  console.log(`  Logs:   ${logPath}`);
+  console.log(`  JSONL:  ${join(LOGS_DIR, 'guardian.jsonl')}`);
+  if (socketPath) {
+    console.log(`  Socket: ${socketPath}`);
+  }
+  if (ccSession) {
+    console.log(`  CC will auto-restart when guardian is ready (session: ${ccSession}).`);
+  }
+}
+
+export async function guardianRun() {
+  if (!existsSync(CREDENTIALS_PATH)) {
+    console.error('No credentials found.');
+    process.exit(1);
+  }
+
+  const credentials = JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf8'));
+  const ccSession = process.env.SEAM_CC_SESSION || '';
+  const ccSocket = process.env.SEAM_CC_SOCKET || resolveTmuxSocketPath() || '';
+  const jsonlPath = join(LOGS_DIR, 'guardian.jsonl');
+
+  if (!existsSync(LOGS_DIR)) mkdirSync(LOGS_DIR, { recursive: true });
+
+  // Refresh CHANNEL_RULES.md + CLAUDE.md references from latest template
+  try {
+    const { syncChannelRules, patchClaudeMd } = await import('./init.js');
+    const rulesPath = syncChannelRules();
+    patchClaudeMd();
+    console.log(`[guardian] CHANNEL_RULES refreshed: ${rulesPath}`);
+  } catch (e) {
+    console.error(`[guardian] CHANNEL_RULES sync failed: ${e.message}`);
+  }
+
+  const { createRequire } = await import('node:module');
+  const require = createRequire(import.meta.url);
+  const { startGuardianCore } = require('./guardian-core.cjs');
+
+  // 插件加载：从 .seam/config.json 读 plugins 列表，缺省 [im, wechat]
+  // 插件工厂约定：export createXxxPlugin（XxxPlugin 是 PascalCase 插件名）
+  const configPath = join(SEAM_DIR, 'config.json');
+  let pluginNames = ['im', 'wechat', 'scheduler'];
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+      if (Array.isArray(cfg?.plugins) && cfg.plugins.length) {
+        pluginNames = cfg.plugins;
+      }
+    } catch (e) {
+      console.error(`[guardian] bad .seam/config.json, fall back to default: ${e.message}`);
+    }
+  }
+  const plugins = pluginNames.map((name) => {
+    const mod = require(`./plugins/${name}/index.cjs`);
+    const factoryKey = `create${name.charAt(0).toUpperCase()}${name.slice(1)}Plugin`;
+    const factory = mod[factoryKey];
+    if (typeof factory !== 'function') {
+      throw new Error(`plugin "${name}" missing ${factoryKey} export`);
+    }
+    return factory();
+  });
+
+  console.log(`[guardian] Starting for ${credentials.userId}...`);
+
+  const { hub, stop } = await startGuardianCore({
+    seamDir: SEAM_DIR,
+    socketPath: SOCKET_PATH,
+    logPath: jsonlPath,
+    ccSession,
+    ccSocket,
+    credentials,
+    plugins,
+  });
+
+  const guardianState = hub.service('state').scope('guardian');
+
+  // 自动重启 CC 加载 MCP
+  // - 首次入网：cc_restarted 未设置
+  // - 升级后：pending_upgrade_restart 标记（upgrade 命令写入）
+  const isFirstStart = !guardianState.has('cc_restarted');
+  const isUpgradeRestart = guardianState.has('pending_upgrade_restart');
+  if (ccSession && (isFirstStart || isUpgradeRestart)) {
+    const safeSession = ccSession.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const tmux = tmuxCmd(ccSocket);
+    hub.logger('guardian').info('auto_restart_cc_scheduled', {
+      session: safeSession,
+      socket: ccSocket || 'default',
+      reason: isUpgradeRestart ? 'upgrade' : 'first_start',
+    });
+    const notice = isUpgradeRestart
+      ? '🔄 [Seam] 升级完成。Guardian 将在 10 秒后重启 CC 以加载新的 MCP 工具。你会在新对话里看到单个 seam 工具取代原来的多个工具。'
+      : '🔄 [Seam] 入网完成。Guardian 将在 10 秒后重启 CC 以加载 MCP 工具。重启后你会在新的对话里读到 IDENTITY.md。';
+    hub.inject(notice);
+    setTimeout(() => {
+      try {
+        execSync(`${tmux} send-keys -t ${safeSession} '/exit' Enter`, {
+          stdio: 'ignore',
+          timeout: 5000,
+        });
+        setTimeout(() => {
+          try {
+            execSync(
+              `${tmux} send-keys -t ${safeSession} 'claude --dangerously-skip-permissions' Enter`,
+              { stdio: 'ignore', timeout: 5000 }
+            );
+            guardianState.set('cc_restarted', new Date().toISOString());
+            if (isUpgradeRestart) guardianState.delete('pending_upgrade_restart');
+            hub.logger('guardian').info('cc_restart_injected');
+          } catch (e) {
+            hub.logger('guardian').error('cc_restart_failed', e);
+          }
+        }, 3000);
+      } catch (e) {
+        hub.logger('guardian').error('cc_exit_failed', e);
+      }
+    }, 10000); // 3s → 10s 给 AI 读到通知的时间
+  }
+
+  // Keep alive + graceful shutdown (pid 文件清理)
+  const shutdown = async (signal) => {
+    hub.logger('guardian').info('shutdown_signal', { signal });
+    try { if (existsSync(PID_PATH)) unlinkSync(PID_PATH); } catch {}
+    await stop();
+    process.exit(0);
+  };
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+export async function guardianStop() {
+  const pid = readGuardianPid();
+  if (!pid || !isPidAlive(pid)) {
+    console.log('Guardian is not running.');
+    if (existsSync(PID_PATH)) {
+      try { unlinkSync(PID_PATH); } catch {}
+    }
+    return;
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+    console.log(`Guardian stopped (pid: ${pid})`);
+  } catch (e) {
+    console.error(`Failed to stop guardian (pid: ${pid}): ${e.message}`);
+  }
+  try { unlinkSync(PID_PATH); } catch {}
+}

package/lib/hub.cjs

@@ -0,0 +1,140 @@
+/**
+ * Seam Hub — Guardian 提供给插件的上下文对象。
+ *
+ * 设计：
+ * - 插件通过 Hub 访问环境（seamDir, ccSession, credentials）
+ * - 插件通过 hub.get(name) 调用其他插件（避免循环依赖）
+ * - 插件方法统一经 hub.run 调用——错误隔离，一个插件崩不拖垮其他
+ * - 插件日志统一 hub.logger(name)——自动带 plugin 字段
+ */
+
+const { execFileSync } = require('node:child_process');
+const { wrap } = require('./errors.cjs');
+
+function createHub({ seamDir, ccSession, ccSocket, credentials, logger }) {
+  const plugins = new Map();
+  const services = new Map();
+  const rootLogger = logger;
+  // 预置 tmux 参数：有 socket 就加 -S <path>，没有就走默认 socket
+  const tmuxBaseArgs = ccSocket ? ['-S', ccSocket] : [];
+
+  function register(plugin) {
+    if (!plugin || !plugin.name) {
+      throw new Error('Plugin must have a name');
+    }
+    if (plugins.has(plugin.name)) {
+      throw new Error(`Plugin already registered: ${plugin.name}`);
+    }
+    plugins.set(plugin.name, plugin);
+  }
+
+  function get(name) {
+    return plugins.get(name);
+  }
+
+  function list() {
+    return [...plugins.values()];
+  }
+
+  // === Service registry ===
+  // Services 是 Guardian 内部能力（scheduler/watcher/state/...），
+  // 只对插件可见，不对 MCP 暴露。
+  function registerService(service) {
+    if (!service || !service.name) {
+      throw new Error('Service must have a name');
+    }
+    if (services.has(service.name)) {
+      throw new Error(`Service already registered: ${service.name}`);
+    }
+    services.set(service.name, service);
+  }
+
+  function service(name) {
+    return services.get(name);
+  }
+
+  function listServices() {
+    return [...services.values()];
+  }
+
+  function inject(text) {
+    if (!ccSession) return false;
+    try {
+      const sanitized = String(text).replace(/[\x00-\x1f]/g, ' ').slice(0, 2000);
+      execFileSync('tmux', [...tmuxBaseArgs, 'send-keys', '-t', ccSession, sanitized], {
+        stdio: 'ignore',
+        timeout: 5000,
+      });
+      execFileSync('tmux', [...tmuxBaseArgs, 'send-keys', '-t', ccSession, 'Enter'], {
+        stdio: 'ignore',
+        timeout: 5000,
+      });
+      return true;
+    } catch (e) {
+      rootLogger.error('inject_failed', e, { textLength: String(text).length });
+      return false;
+    }
+  }
+
+  function loggerFor(name) {
+    return rootLogger.child({ plugin: name });
+  }
+
+  /**
+   * 错误隔离执行 fn。返回 [err, result]。
+   * - fn 正常完成：返回 [null, result]
+   * - fn 抛异常：记日志，返回 [wrappedError, null]
+   * - 超时：返回超时错误
+   */
+  async function run(pluginName, fn, { timeout } = {}) {
+    const log = loggerFor(pluginName);
+    try {
+      let promise = Promise.resolve().then(() => fn());
+      if (timeout && timeout > 0) {
+        promise = Promise.race([
+          promise,
+          new Promise((_, reject) =>
+            setTimeout(
+              () =>
+                reject(
+                  new Error(`plugin ${pluginName} exceeded timeout ${timeout}ms`)
+                ),
+              timeout
+            )
+          ),
+        ]);
+      }
+      const result = await promise;
+      return [null, result];
+    } catch (err) {
+      const wrapped = wrap(err, { code: err?.code });
+      log.error('plugin_call_failed', wrapped.toLog(), { pluginName });
+      return [wrapped, null];
+    }
+  }
+
+  return {
+    // read-only context
+    seamDir,
+    ccSession,
+    ccSocket,
+    credentials,
+
+    // plugin registry
+    register,
+    get,
+    list,
+
+    // service registry
+    registerService,
+    service,
+    listServices,
+
+    // operations (shortcuts to services)
+    inject,
+    logger: loggerFor,
+    run,
+  };
+}
+
+module.exports = { createHub };