pactive 0.0.0-stage → 0.0.2-alpha.1

package/bin/pactive.mjs

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+// Pactive CLI — contract §3 / design §6.
+//
+// Output discipline (design §6.3): machine-readable results (--print-plan, doctor --json,
+// --version) go to stdout; every human/diagnostic Pactive text goes to stderr, so the stdout of a
+// spawned host is never polluted.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { PactiveError } from '../src/hosts/errors.mjs';
+
+const HOSTS = ['pi', 'opcteam', 'dsh'];
+const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(CLI_DIR, '..');
+const FALLBACK_VERSION = '0.0.2-alpha.1';
+const STALE_LOCK_MS = 30 * 60 * 1000;
+
+function usage(io) {
+  io.write(`pactive — proactive companion for Pi / OPCteam / DSH
+
+Usage:
+  pactive <host> [args...]        run a host with pactive injected (stdio inherited)
+  pactive --print-plan <host>     print the launch plan as JSON (no side effects)
+  pactive doctor [--json]         diagnose hosts, state root and permissions (read-only)
+  pactive install <host>          register pactive with a host (idempotent)
+  pactive uninstall <host>        unregister pactive and remove pactive state residue
+  pactive --version | -v          print the pactive version
+  pactive --help | -h             show this help
+
+Hosts: ${HOSTS.join(', ')}
+
+Environment:
+  PACTIVE_HOME          package root override (default: this package)
+  PACTIVE_STATE_DIR     pactive state root override
+  PACTIVE_PI_BIN        override the pi executable
+  PACTIVE_OPCTEAM_BIN   override the opcteam executable
+  PACTIVE_DSH_BIN       override the dsh executable
+`);
+}
+
+function unknownHost(host, io) {
+  io.write(`pactive: unknown host '${host}'\n`);
+  io.write(`pactive: known hosts: ${HOSTS.join(', ')}\n`);
+}
+
+function resolvePkgRoot(env) {
+  return env.PACTIVE_HOME ? path.resolve(env.PACTIVE_HOME) : PKG_ROOT;
+}
+
+function pactiveVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+    if (typeof pkg.version === 'string') return pkg.version;
+  } catch {
+    // package.json not built yet — fall back to the contract version
+  }
+  return FALLBACK_VERSION;
+}
+
+async function loadAdapter(host) {
+  return import(new URL(`../src/hosts/${host}/index.mjs`, import.meta.url));
+}
+
+/** src/core is built by the pactive-core worker; until then the CLI degrades instead of faking it. */
+async function loadCore() {
+  try {
+    return await import(new URL('../src/core/index.mjs', import.meta.url));
+  } catch (err) {
+    throw new PactiveError('PACTIVE core not built yet', { code: 'CORE_MISSING', exitCode: 1, cause: err });
+  }
+}
+
+async function resolveStateRoot(env, warnings = []) {
+  if (env.PACTIVE_STATE_DIR) return path.resolve(env.PACTIVE_STATE_DIR);
+  try {
+    const core = await loadCore();
+    const paths = core.resolvePaths('pi', env);
+    if (paths?.root) return paths.root;
+    warnings.push('PACTIVE core returned no state root — using the default location');
+  } catch (err) {
+    warnings.push(`${err.message} — using the default state root`);
+  }
+  return path.join(os.homedir(), '.pactive');
+}
+
+function modeOf(p) {
+  return (statSync(p).mode & 0o777).toString(8).padStart(4, '0');
+}
+
+function probeVersion(exec) {
+  const res = spawnSync(exec, ['--version'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] });
+  const out = `${res.stdout ?? ''}${res.stderr ?? ''}`.trim();
+  if (!out) return null;
+  return out.split(/\s+/)[0];
+}
+
+function majorOf(version) {
+  const major = Number.parseInt(String(version).split('.')[0], 10);
+  return Number.isNaN(major) ? null : major;
+}
+
+function isCompatible(found, supported) {
+  if (!found || !supported) return false;
+  const a = majorOf(found);
+  const b = majorOf(supported);
+  return a !== null && b !== null && a === b;
+}
+
+function countFiles(dir) {
+  if (!existsSync(dir)) return 0;
+  let n = 0;
+  for (const name of readdirSync(dir)) {
+    const abs = path.join(dir, name);
+    if (statSync(abs).isDirectory()) n += countFiles(abs);
+    else n += 1;
+  }
+  return n;
+}
+
+function stateStats(stateRoot) {
+  const stats = {
+    exists: existsSync(stateRoot),
+    perm: { dir: null, file: null },
+    idle: { enabled: false },
+    sessions: 0,
+    tasks: 0,
+    outbox: 0,
+    locksStale: 0,
+    fails: [],
+  };
+  if (!stats.exists) return stats;
+
+  stats.perm.dir = modeOf(stateRoot);
+  if (stats.perm.dir !== '0700') {
+    stats.fails.push(`state root ${stateRoot} has mode ${stats.perm.dir}, expected 0700`);
+  }
+
+  const stateFile = path.join(stateRoot, 'state.json');
+  if (existsSync(stateFile)) {
+    stats.perm.file = modeOf(stateFile);
+    if (stats.perm.file !== '0600') {
+      stats.fails.push(`state file ${stateFile} has mode ${stats.perm.file}, expected 0600`);
+    }
+    try {
+      const state = JSON.parse(readFileSync(stateFile, 'utf8'));
+      stats.idle.enabled = Boolean(state?.idle?.enabled);
+      if (Array.isArray(state?.tasks)) stats.tasks = state.tasks.length;
+    } catch {
+      stats.fails.push(`state file ${stateFile} is not valid JSON`);
+    }
+  }
+
+  const tasksFile = path.join(stateRoot, 'tasks.json');
+  if (existsSync(tasksFile)) {
+    try {
+      const tasks = JSON.parse(readFileSync(tasksFile, 'utf8'));
+      if (Array.isArray(tasks)) stats.tasks = tasks.length;
+    } catch {
+      stats.fails.push(`tasks file ${tasksFile} is not valid JSON`);
+    }
+  }
+
+  stats.sessions = countFiles(path.join(stateRoot, 'peers'));
+  stats.outbox = countFiles(path.join(stateRoot, 'outbox'));
+
+  const locksDir = path.join(stateRoot, 'locks');
+  if (existsSync(locksDir)) {
+    const now = Date.now();
+    for (const name of readdirSync(locksDir)) {
+      const abs = path.join(locksDir, name);
+      if (statSync(abs).isFile() && now - statSync(abs).mtimeMs > STALE_LOCK_MS) stats.locksStale += 1;
+    }
+  }
+  return stats;
+}
+
+async function doctorReport(env) {
+  const warnings = [];
+  const stateRoot = await resolveStateRoot(env, warnings);
+  const hosts = [];
+  for (const host of HOSTS) {
+    const mod = await loadAdapter(host);
+    let present = false;
+    let version = null;
+    let compatible = false;
+    try {
+      const exec = mod.resolveExec({ env });
+      present = true;
+      version = probeVersion(exec);
+      compatible = isCompatible(version, mod.SUPPORTED_VERSION);
+      if (!version) {
+        warnings.push(`host ${host}: installed but its version could not be read`);
+      } else if (!compatible) {
+        warnings.push(`host ${host}: version ${version} differs from the supported ${mod.SUPPORTED_VERSION}`);
+      }
+    } catch (err) {
+      if (err.code !== 'HOST_MISSING') throw err;
+      warnings.push(`host ${host}: not installed (set PACTIVE_${host.toUpperCase()}_BIN to override)`);
+    }
+    hosts.push({ host, present, version, mode: mod.MODE, compatible });
+  }
+
+  const stats = stateStats(stateRoot);
+  if (!stats.exists) warnings.push(`state root ${stateRoot} does not exist yet`);
+  for (const fail of stats.fails) warnings.push(`FAIL: ${fail}`);
+
+  return {
+    ok: stats.fails.length === 0,
+    hosts,
+    stateRoot,
+    perm: stats.perm,
+    idle: { enabled: stats.idle.enabled, source: 'core-timeline' },
+    sessions: stats.sessions,
+    tasks: stats.tasks,
+    outbox: stats.outbox,
+    locksStale: stats.locksStale,
+    secrets: { credentialsRead: false },
+    warnings,
+  };
+}
+
+function printPlan(args, env, io) {
+  const host = args[0];
+  if (!host) {
+    unknownHost('', io.stderr);
+    return Promise.resolve(2);
+  }
+  if (!HOSTS.includes(host)) {
+    unknownHost(host, io.stderr);
+    return Promise.resolve(2);
+  }
+  return loadAdapter(host).then((mod) => {
+    const plan = mod.plan({ pkgRoot: resolvePkgRoot(env), env, userArgs: [] });
+    io.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+    return 0;
+  });
+}
+
+function doctorCmd(args, env, io) {
+  const asJson = args.includes('--json');
+  return doctorReport(env).then((report) => {
+    if (asJson) {
+      io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+      io.stderr.write(`pactive doctor: ${report.ok ? 'OK' : 'FAIL'}\n`);
+      io.stderr.write(`state root: ${report.stateRoot} (dir ${report.perm.dir}, file ${report.perm.file})\n`);
+      for (const h of report.hosts) {
+        io.stderr.write(
+          `host ${h.host}: present=${h.present} version=${h.version ?? 'unknown'} mode=${h.mode} compatible=${h.compatible}\n`,
+        );
+      }
+      io.stderr.write(
+        `sessions=${report.sessions} tasks=${report.tasks} outbox=${report.outbox} locksStale=${report.locksStale} idle.enabled=${report.idle.enabled}\n`,
+      );
+      for (const w of report.warnings) io.stderr.write(`- ${w}\n`);
+    }
+    return report.ok ? 0 : 1;
+  });
+}
+
+function runHostCommand(exec, args) {
+  const res = spawnSync(exec, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return { status: res.status ?? 1, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
+}
+
+function verifyRegistered(mod, exec, pkgRoot) {
+  const res = runHostCommand(exec, mod.verifyArgs({ pkgRoot }));
+  return mod.verifyMatch({ pkgRoot }, `${res.stdout}\n${res.stderr}`);
+}
+
+const OWNED_STATE_ENTRIES = ['state.json', 'tasks.json', 'ledger.jsonl', 'peers', 'inbox', 'outbox', 'locks'];
+
+function removeStateResidue(stateRoot) {
+  if (!existsSync(stateRoot)) return [];
+  for (const name of OWNED_STATE_ENTRIES) {
+    rmSync(path.join(stateRoot, name), { recursive: true, force: true });
+  }
+  for (const name of readdirSync(stateRoot)) {
+    if (/^(state|tasks)\.json\.corrupt-/.test(name)) {
+      rmSync(path.join(stateRoot, name), { recursive: true, force: true });
+    }
+  }
+  const left = [];
+  const walk = (dir, rel) => {
+    for (const name of readdirSync(dir)) {
+      const abs = path.join(dir, name);
+      const relPath = rel ? path.join(rel, name) : name;
+      if (statSync(abs).isDirectory()) walk(abs, relPath);
+      else left.push(relPath);
+    }
+  };
+  walk(stateRoot, '');
+  return left;
+}
+
+function installCmd(args, env, io, action) {
+  const host = args[0];
+  if (!host) {
+    unknownHost('', io.stderr);
+    return Promise.resolve(2);
+  }
+  if (!HOSTS.includes(host)) {
+    unknownHost(host, io.stderr);
+    return Promise.resolve(2);
+  }
+  return loadAdapter(host).then(async (mod) => {
+    const exec = mod.resolveExec({ env });
+    const pkgRoot = resolvePkgRoot(env);
+    if (action === 'uninstall' && typeof mod.isInstalled === 'function') {
+      let installed = true;
+      try { installed = mod.isInstalled({ pkgRoot, env }); } catch { installed = true; }
+      if (!installed) {
+        // 幂等：没装就什么都不跑（跑宿主 remove 会让 DSH 重建 profile，制造"删了又出现"的怪象）
+        if (typeof mod.cleanup === 'function') {
+          try { mod.cleanup({ pkgRoot, env }); } catch { /* residue 清理失败由下方 residue 检查兜底 */ }
+        }
+        io.stderr.write(`pactive: ${host} not installed — nothing to uninstall\n`);
+        return 0;
+      }
+    }
+    const argsFor = action === 'install' ? mod.installArgs({ pkgRoot }) : mod.uninstallArgs({ pkgRoot });
+    const res = runHostCommand(exec, argsFor);
+
+    if (res.status !== 0) {
+      const stillRegistered = verifyRegistered(mod, exec, pkgRoot);
+      if (action === 'install' ? !stillRegistered : stillRegistered) {
+        io.stderr.write(`pactive: ${action} ${host} failed (exit ${res.status})\n`);
+        if (res.stderr.trim()) io.stderr.write(`${res.stderr.trim()}\n`);
+        return 1;
+      }
+    }
+
+    if (action === 'uninstall') {
+      // Host-level residue: adapters may own resources Pactive created (e.g. the DSH profile dir).
+      if (typeof mod.cleanup === 'function') {
+        try {
+          const cleaned = mod.cleanup({ pkgRoot, env });
+          if (cleaned && cleaned.removed) io.stderr.write(`pactive: removed ${cleaned.path}\n`);
+        } catch (err) {
+          io.stderr.write(`pactive: cleanup warning: ${err?.message ?? err}\n`);
+        }
+      }
+      const stateRoot = await resolveStateRoot(env, []);
+      const residue = removeStateResidue(stateRoot);
+      if (residue.length > 0) {
+        io.stderr.write(`pactive: residue left in ${stateRoot}: ${residue.join(', ')}\n`);
+        return 1;
+      }
+    }
+
+    io.stderr.write(`pactive: ${action} ${host} ok (${pkgRoot})\n`);
+    return 0;
+  });
+}
+
+function runHost(host, userArgs, env, io) {
+  return loadAdapter(host).then((mod) => {
+    const exec = mod.resolveExec({ env });
+    const pkgRoot = resolvePkgRoot(env);
+    const argv = mod.buildArgv({ pkgRoot, userArgs });
+    io.stderr.write(`pactive: launching ${host} (${exec})\n`);
+    return new Promise((resolve) => {
+      const child = spawn(exec, argv, { stdio: 'inherit', env });
+      const forward = (sig) => {
+        if (!child.killed) child.kill(sig);
+      };
+      process.on('SIGINT', forward);
+      process.on('SIGTERM', forward);
+      child.on('error', (err) => {
+        io.stderr.write(`pactive: failed to launch ${host}: ${err.message}\n`);
+        resolve(err.code === 'ENOENT' ? 127 : 1);
+      });
+      child.on('exit', (code, signal) => {
+        process.off('SIGINT', forward);
+        process.off('SIGTERM', forward);
+        resolve(signal ? 128 + (os.constants.signals[signal] ?? 0) : (code ?? 0));
+      });
+    });
+  });
+}
+
+export async function main(argv, env = process.env, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const args = argv.slice(2);
+  if (args.length === 0) {
+    usage(io.stderr);
+    return 2;
+  }
+  const [cmd, ...rest] = args;
+  switch (cmd) {
+    case '--version':
+    case '-v':
+      io.stdout.write(`${pactiveVersion()}\n`);
+      return 0;
+    case '--help':
+    case '-h':
+      usage(io.stderr);
+      return 0;
+    case '--print-plan':
+      return printPlan(rest, env, io);
+    case 'doctor':
+      return doctorCmd(rest, env, io);
+    case 'install':
+      return installCmd(rest, env, io, 'install');
+    case 'uninstall':
+      return installCmd(rest, env, io, 'uninstall');
+    default:
+      break;
+  }
+  if (!HOSTS.includes(cmd)) {
+    unknownHost(cmd, io.stderr);
+    return 2;
+  }
+  return runHost(cmd, rest, env, io);
+}
+
+// Entry guard: compare REAL paths. Installed bin shims and macOS /tmp are symlinks, so
+// `process.argv[1]` and `import.meta.url` differ textually when they point at the same file —
+// a plain string compare silently turns the CLI into a no-op (defect found 2026-11-05 via install chain).
+const isMain = (() => {
+  try {
+    const self = realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = realpathSync(process.argv[1]);
+    return self === argv1;
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  try {
+    process.exitCode = await main(process.argv, process.env, { stdout: process.stdout, stderr: process.stderr });
+  } catch (err) {
+    const exitCode = err instanceof PactiveError ? err.exitCode : 1;
+    process.stderr.write(`pactive: ${err?.message ?? err}\n`);
+    process.exitCode = exitCode;
+  }
+}

package/commands/pactive.md

@@ -0,0 +1,46 @@
+---
+description: Pactive 主动机制 — status、schedule、tell、history（经 pactive MCP server）
+argument-hint: "[status|schedule|tell|history] [args...]"
+---
+
+# pactive:pactive
+
+把用户关于「主动机制 / 空闲触发 / 定时任务 / 跨会话消息」的请求路由到 `pactive` MCP server。
+宿主把它暴露为 `/pactive:pactive`；裸 `/pactive` 不由插件契约保证。
+
+## 工具名
+
+OPCteam 用命名空间暴露插件 MCP 工具：
+
+```
+mcp__plugin_pactive_pactive__<tool>
+```
+
+具体名字：
+
+- `mcp__plugin_pactive_pactive__pactive_status`
+- `mcp__plugin_pactive_pactive__pactive_schedule`
+- `mcp__plugin_pactive_pactive__pactive_tell`
+- `mcp__plugin_pactive_pactive__pactive_history`
+
+裸名（`pactive_status`）不一定能被 ToolSearch 发现；若命名空间工具没加载，用
+`select:mcp__plugin_pactive_pactive__pactive_status` 搜一次。
+
+## 路由
+
+| 用户说 | 调用 |
+|---|---|
+| 状态 / 为什么没触发 | `pactive_status`（看 `idle.reason`，别猜） |
+| 10 分钟后提醒我 / 定时 | `pactive_schedule` `when:"10m"` `prompt:"…"` |
+| 18:30 提醒我 | `pactive_schedule` `when:"18:30"` |
+| 每小时 | `pactive_schedule` `when:"every 1h"` |
+| 告诉另一个会话 | `pactive_tell` `to` `body`（可选 `kind:"ask"`） |
+| 最近发生过什么 | `pactive_history` `limit` |
+
+## 硬规则
+
+1. **不要替用户改配置**：pactive 的开关与配置是人工闸门（CLI `--confirm`）。用户要求改配置时，
+   告诉他用 `pactive config set … --confirm`，不要自行绕过。
+2. **回执如实转述**：`queued` 就是**还没送到**（对端离线），不要说成已送达。
+3. **默认不打扰**：空闲触发默认关闭；用户没明确要「空闲自动推进」时，不要假设它已开启。
+4. **只报新事实**：状态类输出要给出 `idle.reason` 与护栏结论，不要泛泛说「一切正常」。

package/dsh/cordis.patch.yml

@@ -0,0 +1,10 @@
+# DSH bundle overlay for the pactive package.
+#
+# Format (verified against DSH 0.2.1-rc.5 by running
+# `dsh plugin --profile <p> add <pkg>`): a **top-level YAML array** of loader
+# patch entries; each entry may carry an `insert` list of plugin rows
+# ({ id, name, config }). `name` must be the installed package name (`pactive`).
+- insert:
+    - id: pactive
+      name: pactive/dsh
+      config: {}