@dashclaw/cli 0.2.0 → 0.3.2

package/lib/codex/install.js

@@ -0,0 +1,405 @@
+// cli/lib/codex/install.js
+//
+// `dashclaw install codex` — provisions DashClaw governance into Codex CLI.
+//
+// What it does, idempotently:
+//   1. Copies the Python governance hooks (pretool, posttool, stop) and the
+//      vendored `dashclaw_agent_intel` module into ~/.codex/hooks/dashclaw/.
+//   2. Merges a managed block into ~/.codex/config.toml that registers:
+//        - the DashClaw MCP server (stdio)
+//        - PreToolUse / PostToolUse / Stop hooks pointing at the copied scripts
+//        - approval_policy = "on-request" so Codex surfaces require_approval
+//          decisions from DashClaw guard
+//   3. Drops a managed block into <project>/AGENTS.md (or creates the file)
+//      that teaches the Codex agent the DashClaw governance protocol.
+//
+// Idempotency is implemented with sentinel markers:
+//
+//     # >>> dashclaw start — managed block, do not edit by hand
+//     ...
+//     # <<< dashclaw end
+//
+// Re-running replaces only the block between the markers. Anything else in
+// the file is left untouched.
+//
+// Safety: every file we mutate gets a `.dashclaw-bak` sibling on first write
+// so the user always has an escape hatch.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  copyFileSync,
+  readdirSync,
+  statSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+
+export const CODEX_HOME_DIRNAME = '.codex';
+export const DASHCLAW_HOOKS_SUBDIR = 'hooks/dashclaw';
+
+export const MANAGED_START = '# >>> dashclaw start — managed block, do not edit by hand';
+export const MANAGED_END = '# <<< dashclaw end';
+
+export const AGENTS_MANAGED_START =
+  '<!-- >>> dashclaw start — managed block, do not edit by hand -->';
+export const AGENTS_MANAGED_END = '<!-- <<< dashclaw end -->';
+
+// Hook filenames we ship from `hooks/`. The agent_intel module is a directory
+// and is handled separately.
+const HOOK_FILES = [
+  'dashclaw_pretool.py',
+  'dashclaw_posttool.py',
+  'dashclaw_stop.py',
+];
+const HOOK_INTEL_DIR = 'dashclaw_agent_intel';
+
+// -----------------------------------------------------------------------------
+// Path resolution
+// -----------------------------------------------------------------------------
+
+export function codexHome(env = process.env) {
+  if (env.CODEX_HOME) return resolve(env.CODEX_HOME);
+  return resolve(homedir(), CODEX_HOME_DIRNAME);
+}
+
+export function codexConfigPath(env = process.env) {
+  return join(codexHome(env), 'config.toml');
+}
+
+export function codexHooksDir(env = process.env) {
+  return join(codexHome(env), DASHCLAW_HOOKS_SUBDIR);
+}
+
+// -----------------------------------------------------------------------------
+// Hook copy
+// -----------------------------------------------------------------------------
+
+function copyDirRecursive(src, dst) {
+  mkdirSync(dst, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const sp = join(src, entry.name);
+    const dp = join(dst, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '__pycache__') continue;
+      copyDirRecursive(sp, dp);
+    } else if (entry.isFile()) {
+      copyFileSync(sp, dp);
+    }
+  }
+}
+
+export function copyHooks({ hooksSrc, hooksDst }) {
+  if (!existsSync(hooksSrc)) {
+    throw new Error(`Hook source directory not found: ${hooksSrc}`);
+  }
+  mkdirSync(hooksDst, { recursive: true });
+
+  for (const name of HOOK_FILES) {
+    const sp = join(hooksSrc, name);
+    if (!existsSync(sp)) {
+      throw new Error(`Required hook script missing: ${sp}`);
+    }
+    copyFileSync(sp, join(hooksDst, name));
+  }
+
+  const intelSrc = join(hooksSrc, HOOK_INTEL_DIR);
+  if (existsSync(intelSrc) && statSync(intelSrc).isDirectory()) {
+    copyDirRecursive(intelSrc, join(hooksDst, HOOK_INTEL_DIR));
+  } else {
+    throw new Error(`Required intel module missing: ${intelSrc}`);
+  }
+
+  return { hooksDst, files: HOOK_FILES, intelDir: HOOK_INTEL_DIR };
+}
+
+// -----------------------------------------------------------------------------
+// TOML managed-block merge
+// -----------------------------------------------------------------------------
+
+// We do NOT parse TOML. Instead we maintain a single contiguous block
+// delimited by MANAGED_START / MANAGED_END comment markers and rewrite that
+// block on every install. This avoids depending on a third-party TOML
+// library and keeps user-authored content outside the block 100% intact.
+
+export function replaceManagedBlock(
+  source,
+  newBlock,
+  { startMarker = MANAGED_START, endMarker = MANAGED_END } = {},
+) {
+  const start = source.indexOf(startMarker);
+  const end = source.indexOf(endMarker);
+
+  if (start !== -1 && end !== -1 && end > start) {
+    const before = source.slice(0, start);
+    const after = source.slice(end + endMarker.length);
+    return ensureTrailingNewline(
+      stripTrailingBlankLines(before) +
+        (before ? '\n\n' : '') +
+        newBlock +
+        (after.startsWith('\n') ? '' : '\n') +
+        after,
+    );
+  }
+
+  // No existing block — append.
+  const sep = source.length === 0 || source.endsWith('\n') ? '\n' : '\n\n';
+  return ensureTrailingNewline(
+    source + (source.length === 0 ? '' : sep) + newBlock,
+  );
+}
+
+function stripTrailingBlankLines(s) {
+  return s.replace(/\n+$/, '');
+}
+
+function ensureTrailingNewline(s) {
+  return s.endsWith('\n') ? s : s + '\n';
+}
+
+// -----------------------------------------------------------------------------
+// Block builders
+// -----------------------------------------------------------------------------
+
+// Quote a path for inclusion in a TOML basic string. TOML basic strings
+// require `\` and `"` to be escaped.
+function tomlString(value) {
+  return '"' + String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+export function buildConfigTomlBlock({
+  mcpServerPath,
+  hooksDir,
+  approvalPolicy = 'on-request',
+  includeNotify = false,
+  dashclawCliPath = null,
+}) {
+  const py = pythonCommand();
+  const pre = join(hooksDir, 'dashclaw_pretool.py');
+  const post = join(hooksDir, 'dashclaw_posttool.py');
+  const stop = join(hooksDir, 'dashclaw_stop.py');
+
+  const lines = [
+    MANAGED_START,
+    '#',
+    '# Re-run `dashclaw install codex` to refresh this block. Edits made',
+    '# between these markers will be overwritten on next install.',
+    '',
+    `approval_policy = ${tomlString(approvalPolicy)}`,
+  ];
+
+  if (includeNotify) {
+    if (!dashclawCliPath) {
+      throw new Error('dashclawCliPath is required when includeNotify=true');
+    }
+    // Codex's notify config takes a list of strings: argv prefix. Codex
+    // appends the JSON payload as the final argument when it fires.
+    lines.push(
+      `notify = ["node", ${tomlString(dashclawCliPath)}, "codex", "notify"]`,
+    );
+  }
+
+  lines.push(
+    '',
+    '[mcp_servers.dashclaw]',
+    `command = ${tomlString(py)}`,
+    `args = [${tomlString(mcpServerPath)}, "--agent-id", "codex"]`,
+    '',
+    '[[hooks.PreToolUse]]',
+    'matcher = "Bash|Edit|Write|MultiEdit"',
+    '[[hooks.PreToolUse.hooks]]',
+    'type = "command"',
+    `command = ${tomlString(`${py} ${pre}`)}`,
+    'timeoutSec = 3600',
+    '',
+    '[[hooks.PostToolUse]]',
+    'matcher = "Bash|Edit|Write|MultiEdit"',
+    '[[hooks.PostToolUse.hooks]]',
+    'type = "command"',
+    `command = ${tomlString(`${py} ${post}`)}`,
+    '',
+    '[[hooks.Stop]]',
+    '[[hooks.Stop.hooks]]',
+    'type = "command"',
+    `command = ${tomlString(`${py} ${stop}`)}`,
+    MANAGED_END,
+  );
+
+  return lines.join('\n');
+}
+
+function pythonCommand() {
+  // Use `python` on Windows, `python3` elsewhere. The hook scripts work with
+  // either; we just pick the canonical name for the OS so the spawn succeeds
+  // without PATH gymnastics. Users can override by editing config.toml after
+  // install (the managed block warns about overwrites — but the python
+  // command is the only path-dependent piece).
+  return process.platform === 'win32' ? 'python' : 'python3';
+}
+
+// -----------------------------------------------------------------------------
+// AGENTS.md template
+// -----------------------------------------------------------------------------
+
+export function buildAgentsMdBlock({ baseUrl } = {}) {
+  const lines = [
+    AGENTS_MANAGED_START,
+    '',
+    '## DashClaw Governance Protocol',
+    '',
+    'You are governed by DashClaw. Before any non-trivial action, follow this',
+    'protocol so a human reviewer (and the audit log) can trust your work.',
+    '',
+    '### Session start',
+    '',
+    '1. Call `dashclaw_session_start` via the `dashclaw` MCP server with your',
+    '   agent id (`codex`) and a one-sentence workspace description. This',
+    '   groups all your actions for tracking in Mission Control.',
+    '2. Read the `dashclaw://policies` and `dashclaw://capabilities` MCP',
+    '   resources to learn what rules govern you and what capabilities are',
+    '   registered. Treat unknown action types as high-risk by default.',
+    '',
+    '### Before each risky action',
+    '',
+    "Call `dashclaw_guard` with the action you intend to take. You will get",
+    'back one of four decisions:',
+    '',
+    '- `allow` — proceed; call `dashclaw_record` afterward with the outcome.',
+    '- `warn` — proceed with caution; include the warning context in your',
+    '  `dashclaw_record` call.',
+    '- `block` — stop. Report the block reason to the user and do not attempt',
+    '  the action through another path.',
+    "- `require_approval` — call `dashclaw_wait_for_approval` and wait. Don't",
+    '  poll faster than the tool already does.',
+    '',
+    'Risky actions include: shell commands that write or delete, file edits',
+    'outside the project root, network requests, package installs, deploys,',
+    'and any external API call you have not used in this session before.',
+    '',
+    "The PreToolUse hook installed by `dashclaw install codex` will guard",
+    'Bash, Edit, Write, and MultiEdit automatically. The guidance above is',
+    'still required for tool calls that fall outside that matcher (MCP tool',
+    "invocations, agent-internal capabilities) so DashClaw's audit trail",
+    'covers them too.',
+    '',
+    '### After each action',
+    '',
+    'Call `dashclaw_record` with the action id (from `dashclaw_guard` or from',
+    'a PostToolUse-emitted breadcrumb) and the outcome (`success`,',
+    '`failure`, or `partial`). This is what makes the decision replayable.',
+    '',
+    baseUrl ? `### This instance\n\nDashClaw: ${baseUrl}` : '',
+    '',
+    AGENTS_MANAGED_END,
+  ];
+  return lines.filter((l) => l !== null).join('\n');
+}
+
+// -----------------------------------------------------------------------------
+// File mutation helpers
+// -----------------------------------------------------------------------------
+
+function backupOnce(path) {
+  if (!existsSync(path)) return null;
+  const bak = path + '.dashclaw-bak';
+  if (existsSync(bak)) return bak;
+  copyFileSync(path, bak);
+  return bak;
+}
+
+export function mergeConfigToml({
+  configPath,
+  mcpServerPath,
+  hooksDir,
+  approvalPolicy,
+  includeNotify = false,
+  dashclawCliPath = null,
+}) {
+  const before = existsSync(configPath) ? readFileSync(configPath, 'utf8') : '';
+  const block = buildConfigTomlBlock({
+    mcpServerPath,
+    hooksDir,
+    approvalPolicy,
+    includeNotify,
+    dashclawCliPath,
+  });
+  const after = replaceManagedBlock(before, block);
+  mkdirSync(dirname(configPath), { recursive: true });
+  const backup = backupOnce(configPath);
+  writeFileSync(configPath, after);
+  return { changed: before !== after, backup };
+}
+
+export function mergeAgentsMd({ agentsMdPath, baseUrl }) {
+  const before = existsSync(agentsMdPath) ? readFileSync(agentsMdPath, 'utf8') : '';
+  const block = buildAgentsMdBlock({ baseUrl });
+  const after = replaceManagedBlock(before, block, {
+    startMarker: AGENTS_MANAGED_START,
+    endMarker: AGENTS_MANAGED_END,
+  });
+  mkdirSync(dirname(agentsMdPath), { recursive: true });
+  const backup = backupOnce(agentsMdPath);
+  writeFileSync(agentsMdPath, after);
+  return { changed: before !== after, backup };
+}
+
+// -----------------------------------------------------------------------------
+// Top-level install
+// -----------------------------------------------------------------------------
+
+export async function installCodex({
+  repoRoot,
+  projectDir = process.cwd(),
+  baseUrl,
+  approvalPolicy = 'on-request',
+  includeNotify = false,
+  env = process.env,
+  logger = console,
+}) {
+  if (!repoRoot) {
+    throw new Error('repoRoot is required (path to the DashClaw checkout)');
+  }
+
+  const hooksSrc = join(repoRoot, 'hooks');
+  const mcpServerPath = join(repoRoot, 'mcp-server', 'bin', 'dashclaw-mcp.js');
+  const dashclawCliPath = join(repoRoot, 'cli', 'bin', 'dashclaw.js');
+
+  if (!existsSync(mcpServerPath)) {
+    throw new Error(`MCP server entrypoint missing: ${mcpServerPath}`);
+  }
+  if (includeNotify && !existsSync(dashclawCliPath)) {
+    throw new Error(`dashclaw CLI not found at ${dashclawCliPath} — can't wire notify`);
+  }
+
+  const hooksDst = codexHooksDir(env);
+  const configPath = codexConfigPath(env);
+  const agentsMdPath = join(projectDir, 'AGENTS.md');
+
+  logger.info(`Installing DashClaw hooks → ${hooksDst}`);
+  const hookResult = copyHooks({ hooksSrc, hooksDst });
+
+  logger.info(`Merging Codex config → ${configPath}`);
+  const configResult = mergeConfigToml({
+    configPath,
+    mcpServerPath,
+    hooksDir: hooksDst,
+    approvalPolicy,
+    includeNotify,
+    dashclawCliPath: includeNotify ? dashclawCliPath : null,
+  });
+
+  logger.info(`Merging governance protocol → ${agentsMdPath}`);
+  const agentsResult = mergeAgentsMd({ agentsMdPath, baseUrl });
+
+  return {
+    hooks: hookResult,
+    config: { path: configPath, ...configResult },
+    agentsMd: { path: agentsMdPath, ...agentsResult },
+  };
+}

package/lib/codex/notify.js

@@ -0,0 +1,203 @@
+// cli/lib/codex/notify.js
+//
+// `dashclaw codex notify` — Codex legacy `notify` config target.
+//
+// Codex CLI supports a `notify` config that runs an external command after
+// each agent turn completes. Codex appends a JSON payload as the FINAL argv
+// argument:
+//
+//   notify = ["node", "/path/to/dashclaw.js", "codex", "notify"]
+//
+// then on each turn-complete, Codex spawns:
+//
+//   node /path/to/dashclaw.js codex notify '{"type":"agent-turn-complete", ...}'
+//
+// This module:
+//   1. Extracts the JSON payload from the last argv arg.
+//   2. Validates it's an `agent-turn-complete` event.
+//   3. POSTs a record to /api/actions/by-tool-use-id (the same endpoint the
+//      PostToolUse Python hook uses for its terminal patch) with an action
+//      shape that represents the turn as a single observable unit.
+//
+// Failure mode: Codex spawns notify fire-and-forget with stdio nulled. We
+// MUST exit 0 on any failure so we don't surface error output to the user.
+// All errors are logged to stderr and swallowed by the spawn.
+
+import { request } from 'node:http';
+import { request as requestHttps } from 'node:https';
+
+const TURN_COMPLETE_TYPE = 'agent-turn-complete';
+
+/**
+ * Parse the Codex notify payload from argv. Codex appends the JSON as the
+ * final argv slot. We accept either:
+ *  - argv last arg is a JSON string → parse it
+ *  - argv last arg is empty + stdin has JSON → read stdin
+ *
+ * Returns the parsed object, or null if no valid payload was found.
+ */
+export function parseNotifyPayload(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return null;
+  const last = argv[argv.length - 1];
+  if (typeof last !== 'string' || last.length === 0) return null;
+  if (last[0] !== '{') return null;
+  try {
+    return JSON.parse(last);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Map a Codex turn-complete payload to a DashClaw action_record shape.
+ * We declare the turn as a single coarse action so it shows up in the
+ * decision ledger. Token/cost data is not in the notify payload — it will
+ * be back-filled by the Phase 3 JSONL ingest path.
+ */
+export function buildActionFromNotify(payload, { agentId = 'codex' } = {}) {
+  const lastMessage = payload.last_assistant_message || '';
+  const summary = lastMessage.length > 200
+    ? lastMessage.slice(0, 197) + '...'
+    : lastMessage;
+
+  return {
+    agent_id: agentId,
+    action_type: 'agent_turn',
+    declared_goal: `Codex turn ${payload.turn_id || '?'} (${payload.thread_id || 'thread'})`,
+    outcome: 'success',
+    metadata: {
+      source: 'codex-notify',
+      thread_id: payload.thread_id,
+      turn_id: payload.turn_id,
+      cwd: payload.cwd,
+      client: payload.client || 'codex',
+      input_message_count: Array.isArray(payload.input_messages)
+        ? payload.input_messages.length
+        : 0,
+      last_assistant_summary: summary,
+    },
+  };
+}
+
+/**
+ * Send an action record to DashClaw. Returns:
+ *  - { status: 'sent', actionId }   on 2xx
+ *  - { status: 'skipped', reason }  on local-validation skip
+ *  - { status: 'error', reason }    on network/4xx/5xx
+ *
+ * Never throws. All errors are returned in the result object so the caller
+ * can decide whether to swallow them.
+ */
+export async function postNotifyAction({ baseUrl, apiKey, action, timeoutMs = 5000 }) {
+  if (!baseUrl || !apiKey) {
+    return { status: 'skipped', reason: 'missing_config' };
+  }
+
+  let url;
+  try {
+    url = new URL('/api/actions', baseUrl);
+  } catch (err) {
+    return { status: 'error', reason: 'invalid_base_url', detail: err.message };
+  }
+
+  const body = JSON.stringify(action);
+  const headers = {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(body).toString(),
+    'x-api-key': apiKey,
+  };
+
+  return new Promise((resolve) => {
+    const lib = url.protocol === 'https:' ? requestHttps : request;
+    const req = lib(
+      {
+        method: 'POST',
+        host: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: url.pathname + url.search,
+        headers,
+      },
+      (res) => {
+        let chunks = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => { chunks += c; });
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            let parsed = null;
+            try { parsed = JSON.parse(chunks); } catch { /* keep null */ }
+            resolve({
+              status: 'sent',
+              actionId: parsed?.action_id || parsed?.id || null,
+            });
+          } else {
+            resolve({
+              status: 'error',
+              reason: `http_${res.statusCode}`,
+              detail: chunks.slice(0, 200),
+            });
+          }
+        });
+      },
+    );
+
+    req.on('error', (err) => {
+      resolve({ status: 'error', reason: 'network', detail: err.message });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      resolve({ status: 'error', reason: 'timeout' });
+    });
+
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Run the notify command. This is the CLI entrypoint.
+ *
+ * IMPORTANT: must always exit 0 (the caller calls process.exit(0)).
+ * Codex spawns notify with stdio nulled and treats any failure as silent.
+ * We log to stderr (which Codex discards by design) for diagnostics.
+ *
+ * Options:
+ *   argv      — argv array (defaults to process.argv.slice(2))
+ *   baseUrl   — DashClaw instance URL
+ *   apiKey    — DashClaw API key
+ *   agentId   — agent identity (default: codex)
+ *   logger    — { warn, info } for diagnostic output
+ *   skipPost  — if true, do everything except the HTTP call (testing)
+ */
+export async function runCodexNotify({
+  argv = process.argv.slice(2),
+  baseUrl,
+  apiKey,
+  agentId = 'codex',
+  logger = console,
+  skipPost = false,
+} = {}) {
+  const payload = parseNotifyPayload(argv);
+  if (!payload) {
+    logger.warn('codex-notify: no JSON payload in argv, exiting 0');
+    return { status: 'skipped', reason: 'no_payload' };
+  }
+  if (payload.type !== TURN_COMPLETE_TYPE) {
+    logger.warn(`codex-notify: unknown payload type "${payload.type}", exiting 0`);
+    return { status: 'skipped', reason: 'unknown_type', type: payload.type };
+  }
+
+  const action = buildActionFromNotify(payload, { agentId });
+
+  if (skipPost) {
+    return { status: 'dry_run', action };
+  }
+
+  const result = await postNotifyAction({ baseUrl, apiKey, action });
+  if (result.status === 'sent') {
+    logger.info?.(`codex-notify: recorded action ${result.actionId || '(unknown id)'}`);
+  } else if (result.status === 'error') {
+    logger.warn(`codex-notify: ${result.reason}${result.detail ? ' — ' + result.detail : ''}`);
+  }
+  return result;
+}