ai-hist-mcp 0.3.2 → 0.3.5

package/README.md

@@ -6,6 +6,24 @@ Thin `npx` wrapper for the [`ai-hist`](https://www.npmjs.com/package/ai-hist) st
 npx -y ai-hist-mcp
 ```
 
+## Pair one-command setup
+
+Install the project MCP config and advisory Pair hooks for Claude Code / Codex:
+
+```bash
+npx -y ai-hist-mcp setup
+```
+
+The setup is idempotent and secret-free. It writes `.mcp.json`, `.claude/settings.json`,
+and `.codex/hooks.json` entries that call the package wrappers; it never embeds internal
+auth keys or relayhistory tokens.
+
+For the hook command alone:
+
+```bash
+npx -y ai-hist-mcp hook
+```
+
 The wrapper depends on `ai-hist` and launches its `ai-hist/mcp-server` export. It preserves the same environment contract:
 
 - `AI_HIST_DB` points to the ai-hist SQLite database.

package/bin/ai-hist-mcp.js

@@ -1,2 +1,12 @@
 #!/usr/bin/env node
-import 'ai-hist/mcp-server';
+const subcommand = process.argv[2];
+
+if (subcommand === "setup" || subcommand === "pair-setup" || subcommand === "install") {
+  process.argv.splice(2, 1);
+  await import("./pair-setup.js");
+} else if (subcommand === "hook" || subcommand === "pair-hook") {
+  process.argv.splice(2, 1);
+  await import("./pair-hook.js");
+} else {
+  await import("ai-hist/mcp-server");
+}

package/bin/pair-hook.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { isAbsolute, relative } from "node:path";
+import { promisify } from "node:util";
+
+const MAX_TASK_CHARS = 800;
+const DEFAULT_LIMIT = 3;
+const TIMEOUT_MS = Number(process.env.PAIR_CHECK_TIMEOUT_MS || 8000);
+const execFileAsync = promisify(execFile);
+const SECRET_PATTERNS = [
+  /\brth_[a-z]+_[A-Za-z0-9._-]+/g,
+  /\bsk-[A-Za-z0-9._-]+/g,
+  /\bgh[pousr]_[A-Za-z0-9_]{20,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+];
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function compact(value, limit = MAX_TASK_CHARS) {
+  if (typeof value !== "string") return undefined;
+  let text = value.replace(/\s+/g, " ").trim();
+  for (const pattern of SECRET_PATTERNS) text = text.replace(pattern, "[REDACTED]");
+  if (!text) return undefined;
+  return text.length > limit ? `${text.slice(0, limit)}...` : text;
+}
+
+function normalizeFile(cwd, file) {
+  if (typeof file !== "string" || !file.trim()) return undefined;
+  if (!cwd || !isAbsolute(file)) return file;
+  return relative(cwd, file) || file;
+}
+
+function collectFiles(cwd, input) {
+  const files = new Set();
+  if (!input || typeof input !== "object") return [];
+  for (const key of ["file_path", "filePath", "path", "target"]) {
+    const normalized = normalizeFile(cwd, input[key]);
+    if (normalized) files.add(normalized);
+  }
+  return [...files].slice(0, 20);
+}
+
+function buildContext(event) {
+  const toolInput = event.tool_input && typeof event.tool_input === "object" ? event.tool_input : {};
+  const cwd = typeof event.cwd === "string" ? event.cwd : process.cwd();
+  const files = collectFiles(cwd, toolInput);
+  const tool = event.tool_name || event.tool || undefined;
+  const target = files[0] || compact(toolInput.command, 300) || compact(toolInput.pattern, 300);
+  const prompt = compact(event.prompt);
+  const description = compact(toolInput.description, 300);
+  const command = compact(toolInput.command, 500);
+  const action = event.hook_event_name === "UserPromptSubmit" ? "prompt" : "tool";
+
+  return {
+    cwd,
+    repoPath: cwd,
+    task: prompt || description || command,
+    files,
+    tool,
+    target,
+    action,
+    recentPrompt: prompt,
+  };
+}
+
+function pushArg(args, name, value) {
+  if (typeof value === "string" && value.trim()) args.push(name, value.trim());
+}
+
+async function pairCheck(context) {
+  const bin = process.env.AI_HIST_PAIR_CHECK_BIN || "ai-hist";
+  const args = ["pair", "check", "--json"];
+  pushArg(args, "--task", context.task);
+  pushArg(args, "--tool", context.tool);
+  pushArg(args, "--target", context.target);
+  pushArg(args, "--recent-prompt", context.recentPrompt);
+  for (const file of context.files ?? []) pushArg(args, "--file", file);
+  args.push("--limit", String(process.env.PAIR_CHECK_LIMIT || DEFAULT_LIMIT));
+
+  const { stdout } = await execFileAsync(bin, args, {
+    timeout: TIMEOUT_MS,
+    maxBuffer: 1024 * 1024,
+    env: process.env,
+  });
+  const parsed = stdout.trim() ? JSON.parse(stdout) : {};
+  return Array.isArray(parsed.warnings) ? { ...parsed, warnings: parsed.warnings } : { ...parsed, warnings: [] };
+}
+
+function formatWarnings(result) {
+  if (!result.warnings?.length) return "";
+  const lines = ["Pair advisory warnings from prior convergence events:"];
+  for (const warning of result.warnings) {
+    const label = [warning.kind, warning.lens].filter(Boolean).join("/");
+    const score = typeof warning.score === "number" ? ` score=${warning.score.toFixed(2)}` : "";
+    lines.push(`- ${label ? `[${label}${score}] ` : ""}${warning.text}`);
+    for (const ev of warning.evidence ?? []) {
+      const id = [ev.machineId, ev.source, ev.sessionId, ev.eventId].filter(Boolean).join(":");
+      const when = ev.ts ? ` ${ev.ts}` : "";
+      const snippet = ev.snippet ? ` - ${ev.snippet}` : "";
+      lines.push(`  evidence: ${id || ev.eventId || "(unknown)"}${when}${snippet}`);
+    }
+  }
+  if (result.correlationId) lines.push(`correlationId: ${result.correlationId}`);
+  return lines.join("\n");
+}
+
+function outputFor(eventName, additionalContext) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext,
+    },
+  };
+}
+
+try {
+  const input = await readStdin();
+  const event = input.trim() ? JSON.parse(input) : {};
+  const eventName = event.hook_event_name || "UserPromptSubmit";
+  const result = await pairCheck(buildContext(event));
+  const warningText = formatWarnings(result);
+  if (warningText) {
+    process.stdout.write(`${JSON.stringify(outputFor(eventName, warningText))}\n`);
+  }
+} catch (err) {
+  if (process.env.PAIR_CHECK_DEBUG) {
+    process.stderr.write(`pair hook skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+  process.exit(0);
+}

package/bin/pair-setup.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+const DEFAULT_AGENTS = "all";
+const MCP_SERVER_NAME = "ai-hist";
+
+function usage() {
+  return `Usage: npx -y ai-hist-mcp setup [options]
+
+Install Pair MCP + advisory hooks for the current project.
+
+Options:
+  --agents <all|claude|codex>   Which agent configs to update (default: all)
+  --project <path>              Project path passed to ai-hist-mcp (default: cwd)
+  --ai-hist-bin <path>          ai-hist binary used by the Pair hook (default: ai-hist)
+  --mcp-only                    Only write .mcp.json, skip hooks
+  --hooks-only                  Only write hook configs, skip .mcp.json
+  --dry-run                     Print planned writes without changing files
+  -h, --help                    Show this help
+`;
+}
+
+function parseArgs(argv) {
+  const out = {
+    agents: DEFAULT_AGENTS,
+    project: process.cwd(),
+    aiHistBin: "ai-hist",
+    hooks: true,
+    mcp: true,
+    dryRun: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      process.stdout.write(usage());
+      process.exit(0);
+    }
+    if (arg === "--agents") out.agents = requireValue(argv, ++i, arg);
+    else if (arg === "--project") out.project = requireValue(argv, ++i, arg);
+    else if (arg === "--ai-hist-bin") out.aiHistBin = requireValue(argv, ++i, arg);
+    else if (arg === "--mcp-only") out.hooks = false;
+    else if (arg === "--hooks-only") out.mcp = false;
+    else if (arg === "--dry-run") out.dryRun = true;
+    else throw new Error(`unknown option: ${arg}`);
+  }
+
+  if (!["all", "claude", "codex"].includes(out.agents)) {
+    throw new Error("--agents must be one of: all, claude, codex");
+  }
+  return out;
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("-")) throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+async function readJson(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (err) {
+    if (err?.code === "ENOENT") return fallback;
+    throw err;
+  }
+}
+
+async function writeJson(path, value, dryRun) {
+  const body = `${JSON.stringify(value, null, 2)}\n`;
+  if (dryRun) {
+    process.stdout.write(`[dry-run] would write ${path}\n`);
+    return;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, body, { mode: 0o600 });
+  process.stdout.write(`wrote ${path}\n`);
+}
+
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function hookCommand(aiHistBin) {
+  const command = "npx -y ai-hist-mcp hook";
+  if (!aiHistBin || aiHistBin === "ai-hist") return command;
+  return `AI_HIST_PAIR_CHECK_BIN=${shellQuote(aiHistBin)} ${command}`;
+}
+
+function hook(command, statusMessage) {
+  return {
+    type: "command",
+    command,
+    timeout: 10,
+    ...(statusMessage ? { statusMessage } : {}),
+  };
+}
+
+function hasHook(hooks, command) {
+  return Array.isArray(hooks) && hooks.some((entry) =>
+    Array.isArray(entry?.hooks) && entry.hooks.some((candidate) => candidate?.command === command),
+  );
+}
+
+function ensureHook(settings, eventName, entry) {
+  settings.hooks ??= {};
+  settings.hooks[eventName] ??= [];
+  const command = entry.hooks?.[0]?.command;
+  if (!command || hasHook(settings.hooks[eventName], command)) return;
+  settings.hooks[eventName].push(entry);
+}
+
+async function installMcp(project, dryRun) {
+  const path = resolve(process.cwd(), ".mcp.json");
+  const config = await readJson(path, {});
+  config.mcpServers ??= {};
+  config.mcpServers[MCP_SERVER_NAME] = {
+    command: "npx",
+    args: ["-y", "ai-hist-mcp", "--project", project],
+  };
+  await writeJson(path, config, dryRun);
+}
+
+async function installClaudeHooks(command, dryRun) {
+  const path = resolve(process.cwd(), ".claude", "settings.json");
+  const settings = await readJson(path, {});
+  ensureHook(settings, "UserPromptSubmit", {
+    hooks: [hook(command)],
+  });
+  ensureHook(settings, "PreToolUse", {
+    matcher: "Edit|Write|Bash",
+    hooks: [hook(command)],
+  });
+  await writeJson(path, settings, dryRun);
+}
+
+async function installCodexHooks(command, dryRun) {
+  const path = resolve(process.cwd(), ".codex", "hooks.json");
+  const settings = await readJson(path, {});
+  ensureHook(settings, "UserPromptSubmit", {
+    hooks: [hook(command, "Checking Pair warnings")],
+  });
+  ensureHook(settings, "PreToolUse", {
+    matcher: "Edit|Write|apply_patch|Bash",
+    hooks: [hook(command, "Checking Pair warnings")],
+  });
+  await writeJson(path, settings, dryRun);
+}
+
+try {
+  const args = parseArgs(process.argv.slice(2));
+  const project = resolve(args.project);
+  const command = hookCommand(args.aiHistBin);
+
+  if (args.mcp) await installMcp(project, args.dryRun);
+  if (args.hooks && (args.agents === "all" || args.agents === "claude")) {
+    await installClaudeHooks(command, args.dryRun);
+  }
+  if (args.hooks && (args.agents === "all" || args.agents === "codex")) {
+    await installCodexHooks(command, args.dryRun);
+  }
+
+  process.stdout.write("Pair setup complete. Restart your agent session so it reloads MCP/hooks.\n");
+} catch (err) {
+  process.stderr.write(`ai-hist pair setup failed: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "ai-hist-mcp",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "Thin npx wrapper for the ai-hist stdio MCP server.",
   "license": "MIT",
   "private": false,
   "type": "module",
   "bin": {
-    "ai-hist-mcp": "bin/ai-hist-mcp.js"
+    "ai-hist-mcp": "bin/ai-hist-mcp.js",
+    "ai-hist-pair-setup": "bin/pair-setup.js",
+    "ai-hist-pair-hook": "bin/pair-hook.js"
   },
   "files": [
     "bin",
@@ -15,14 +17,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AgentWorkforce/ai-hist.git",
+    "url": "https://github.com/AgentWorkforce/relayhistory",
     "directory": "mcp-package"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "ai-hist": "0.3.2"
+    "ai-hist": "0.3.5"
   },
   "engines": {
     "node": ">=18"