@ghl-ai/aw 0.1.44-beta.1 → 0.1.44-beta.11

package/c4/claudePluginRegistry.mjs

@@ -0,0 +1,142 @@
+/**
+ * c4/claudePluginRegistry.mjs — Claude marketplace + plugin enable + Skill
+ * permission registration.
+ *
+ * Three settings.json mutations driven by `ensureClaudeMarketplace`:
+ *
+ *   1. extraKnownMarketplaces["aw-marketplace"] = {
+ *        source: { source: "directory", path: <eccDir> }   // NESTED, easy to get wrong
+ *      }
+ *      Pilot empirically established the nested source.source shape; a flat
+ *      `source: "directory"` does not register the marketplace.
+ *
+ *   2. enabledPlugins["aw@aw-marketplace"] = true
+ *      Activates the plugin (without this Claude knows about the marketplace
+ *      but does not surface its commands/skills).
+ *
+ *   3. permissions.allow includes "Skill"
+ *      Without this Claude refuses to dispatch the Skill tool. Append-only
+ *      to preserve user-authored entries; idempotent (no duplicates, no
+ *      reordering).
+ *
+ * Atomic write + 0600 mode. Returns { changed: false } when every mutation
+ * is a no-op.
+ *
+ * Contract: spec.md::§"c4/claudePluginRegistry.mjs", tasks.md::3.4b.
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  chmodSync,
+  mkdirSync,
+  unlinkSync,
+} from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+
+const FILE_MODE = 0o600;
+const MARKETPLACE_NAME = 'aw-marketplace';
+const PLUGIN_KEY = 'aw@aw-marketplace';
+const SKILL_PERMISSION = 'Skill';
+
+function ensureDir(d) {
+  mkdirSync(d, { recursive: true });
+}
+
+function readJsonOrEmpty(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, 'utf8');
+  if (raw.trim() === '') return {};
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse JSON at ${filePath}: ${err.message}`);
+  }
+}
+
+function atomicWriteIfChanged(filePath, serialized) {
+  if (existsSync(filePath)) {
+    const prev = readFileSync(filePath, 'utf8');
+    if (prev === serialized) return false;
+  }
+
+  ensureDir(dirname(filePath));
+
+  const tmp = join(
+    dirname(filePath),
+    `.${basename(filePath)}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`
+  );
+
+  try {
+    writeFileSync(tmp, serialized, { mode: FILE_MODE });
+    renameSync(tmp, filePath);
+  } catch (err) {
+    if (existsSync(tmp)) {
+      try { unlinkSync(tmp); } catch { /* best-effort */ }
+    }
+    throw err;
+  }
+
+  try { chmodSync(filePath, FILE_MODE); } catch { /* best-effort */ }
+  return true;
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function ensureMarketplace(root, eccDir) {
+  if (!isPlainObject(root.extraKnownMarketplaces)) root.extraKnownMarketplaces = {};
+  // Nested source.source schema — pilot-verified.
+  root.extraKnownMarketplaces[MARKETPLACE_NAME] = {
+    ...(isPlainObject(root.extraKnownMarketplaces[MARKETPLACE_NAME])
+      ? root.extraKnownMarketplaces[MARKETPLACE_NAME]
+      : {}),
+    source: { source: 'directory', path: eccDir },
+  };
+}
+
+function ensurePluginEnabled(root) {
+  if (!isPlainObject(root.enabledPlugins)) root.enabledPlugins = {};
+  root.enabledPlugins[PLUGIN_KEY] = true;
+}
+
+function ensureSkillPermission(root) {
+  if (!isPlainObject(root.permissions)) root.permissions = {};
+  const existing = Array.isArray(root.permissions.allow) ? root.permissions.allow : [];
+  if (existing.includes(SKILL_PERMISSION)) {
+    root.permissions.allow = existing;
+  } else {
+    root.permissions.allow = [...existing, SKILL_PERMISSION];
+  }
+}
+
+/**
+ * Ensure Claude is wired up to surface ECC's `aw:<stage>` skills via plugin
+ * marketplace + Skill permission.
+ *
+ * @param {string} home    User home (e.g. tmp dir in tests).
+ * @param {string} eccDir  Path to the ECC plugin directory (~/.aw-ecc).
+ * @returns {{ changed: boolean }}
+ */
+export function ensureClaudeMarketplace(home, eccDir) {
+  if (!home || typeof home !== 'string') {
+    throw new Error('ensureClaudeMarketplace: home is required');
+  }
+  if (!eccDir || typeof eccDir !== 'string') {
+    throw new Error('ensureClaudeMarketplace: eccDir is required');
+  }
+
+  const settingsPath = join(home, '.claude/settings.json');
+  const root = readJsonOrEmpty(settingsPath);
+
+  ensureMarketplace(root, eccDir);
+  ensurePluginEnabled(root);
+  ensureSkillPermission(root);
+
+  const serialized = JSON.stringify(root, null, 2) + '\n';
+  const changed = atomicWriteIfChanged(settingsPath, serialized);
+  return { changed };
+}

package/c4/codexConfig.mjs

@@ -0,0 +1,148 @@
+/**
+ * c4/codexConfig.mjs — Codex-only ~/.codex/config.toml editor.
+ *
+ * Codex hooks silently no-op without `[features] codex_hooks = true` in this
+ * file (validated in pilot). The MCP block lives in the same file as a
+ * `[mcp_servers.<name>]` table with optional `[mcp_servers.<name>.headers]`
+ * sub-table.
+ *
+ * We use @iarna/toml's parse + stringify for full round-trip fidelity.
+ * Atomic write (tmp file + rename, chmod 0600) keeps Codex from reading a
+ * partial file mid-write.
+ *
+ * Contract: spec.md::§"c4/codexConfig.mjs", tasks.md::3.3.
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  chmodSync,
+  mkdirSync,
+  unlinkSync,
+} from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import TOML from '@iarna/toml';
+
+export const MCP_URL_DEFAULT =
+  'https://services.leadconnectorhq.com/agentic-workspace/mcp';
+
+const FILE_MODE = 0o600;
+
+function ensureDir(d) {
+  mkdirSync(d, { recursive: true });
+}
+
+function readTomlOrEmpty(filePath) {
+  if (!existsSync(filePath)) return {};
+  const raw = readFileSync(filePath, 'utf8');
+  if (raw.trim() === '') return {};
+  try {
+    return TOML.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to parse TOML at ${filePath}: ${err.message}`);
+  }
+}
+
+function atomicWriteIfChanged(filePath, serialized) {
+  if (existsSync(filePath)) {
+    const prev = readFileSync(filePath, 'utf8');
+    if (prev === serialized) return false;
+  }
+
+  ensureDir(dirname(filePath));
+
+  const tmp = join(
+    dirname(filePath),
+    `.${basename(filePath)}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`
+  );
+
+  try {
+    writeFileSync(tmp, serialized, { mode: FILE_MODE });
+    renameSync(tmp, filePath);
+  } catch (err) {
+    if (existsSync(tmp)) {
+      try { unlinkSync(tmp); } catch { /* best-effort */ }
+    }
+    throw err;
+  }
+
+  try { chmodSync(filePath, FILE_MODE); } catch { /* best-effort */ }
+  return true;
+}
+
+function configPathFor(home) {
+  return join(home, '.codex/config.toml');
+}
+
+/**
+ * Ensure `[features] codex_hooks = true` in ~/.codex/config.toml.
+ * Preserves all other keys (round-trip via @iarna/toml).
+ *
+ * @param {string} home
+ * @returns {{ changed: boolean }}
+ */
+export function ensureCodexHooksFlag(home) {
+  if (!home || typeof home !== 'string') {
+    throw new Error('ensureCodexHooksFlag: home is required');
+  }
+  const filePath = configPathFor(home);
+  const root = readTomlOrEmpty(filePath);
+  if (root.features == null || typeof root.features !== 'object' || Array.isArray(root.features)) {
+    root.features = {};
+  }
+  root.features.codex_hooks = true;
+  const serialized = TOML.stringify(root);
+  const changed = atomicWriteIfChanged(filePath, serialized);
+  return { changed };
+}
+
+/**
+ * Ensure `[mcp_servers.ghl-ai]` block with url + Bearer token + transport.
+ * URL falls back to env MCP_URL → MCP_URL_DEFAULT.
+ *
+ * @param {string} home
+ * @param {string} token
+ * @returns {{ changed: boolean }}
+ */
+export function ensureCodexMcpServer(home, token) {
+  if (!home || typeof home !== 'string') {
+    throw new Error('ensureCodexMcpServer: home is required');
+  }
+  if (!token || typeof token !== 'string') {
+    throw new Error('ensureCodexMcpServer: token is required');
+  }
+
+  const url = process.env.MCP_URL || MCP_URL_DEFAULT;
+  const filePath = configPathFor(home);
+  const root = readTomlOrEmpty(filePath);
+
+  if (
+    root.mcp_servers == null ||
+    typeof root.mcp_servers !== 'object' ||
+    Array.isArray(root.mcp_servers)
+  ) {
+    root.mcp_servers = {};
+  }
+
+  const ghlAi = root.mcp_servers['ghl-ai'] ?? {};
+  ghlAi.url = url;
+  ghlAi.transport = 'http';
+  // Match the canonical `aw init` reference (libs/aw/mcp.mjs::tomlMcpServerBlock)
+  // which always sets startup_timeout_sec = 30 for HTTP MCP servers.
+  ghlAi.startup_timeout_sec = 30;
+  if (
+    ghlAi.headers == null ||
+    typeof ghlAi.headers !== 'object' ||
+    Array.isArray(ghlAi.headers)
+  ) {
+    ghlAi.headers = {};
+  }
+  ghlAi.headers.Authorization = `Bearer ${token}`;
+  root.mcp_servers['ghl-ai'] = ghlAi;
+
+  const serialized = TOML.stringify(root);
+  const changed = atomicWriteIfChanged(filePath, serialized);
+  return { changed };
+}

package/c4/codexPromptInjector.mjs

@@ -0,0 +1,187 @@
+/**
+ * c4/codexPromptInjector.mjs — Bug B (Codex non-persistence) workaround.
+ *
+ * Codex Web does not persist `additionalContext` across turns; the slim card
+ * approach used for Claude/Cursor is insufficient. Instead, we wrap ECC's
+ * existing `~/.codex/hooks/aw-user-prompt-submit.sh` so that EVERY
+ * UserPromptSubmit emits the full using-aw-skills SKILL.md body wrapped in
+ * `<EXTREMELY_IMPORTANT>` framing.
+ *
+ * The wrapper:
+ *   1. Reads stdin (Codex's UserPromptSubmit payload).
+ *   2. Calls the original hook (renamed to `<hookPath>.upstream`) with the
+ *      same stdin to capture its output.
+ *   3. If env AW_PROMPT_ROUTER_INJECT=0, passes the upstream output through
+ *      verbatim (escape hatch for debugging Bug B itself).
+ *   4. Otherwise reads the router skill body, builds the merged envelope:
+ *        { hookSpecificOutput: { hookEventName: "UserPromptSubmit",
+ *          additionalContext: "<EXTREMELY_IMPORTANT>" + skill +
+ *          "</EXTREMELY_IMPORTANT>\n\n" + upstream_additionalContext } }
+ *      and prints it to stdout.
+ *
+ * Idempotency: the wrapper carries a `# aw-c4 router injector v1` header
+ * marker; reinstalls detect this and no-op (the upstream backup is NOT
+ * overwritten on the second run, which would otherwise destroy the original
+ * hook).
+ *
+ * Source-of-truth path: `aw-ecc/scripts/lib/codex-aw-hook-files.js` lists
+ * `aw-user-prompt-submit.sh` as one of the files materialized into
+ * `~/.codex/hooks/` during `aw init`. NOT in the registry path.
+ *
+ * Contract: spec.md::§"c4/codexPromptInjector.mjs", tasks.md::3.2.
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  chmodSync,
+  mkdirSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const WRAPPER_HEADER_MARKER = '# aw-c4 router injector v1';
+
+/**
+ * @returns {string} Default hook path: ${os.homedir()}/.codex/hooks/aw-user-prompt-submit.sh
+ */
+export function defaultHookPath() {
+  return join(homedir(), '.codex/hooks/aw-user-prompt-submit.sh');
+}
+
+/**
+ * Render the wrapper script that re-emits the router skill on every prompt.
+ *
+ * Implementation note: the wrapper is pure bash + python3 (which Codex Web
+ * always has available). It uses `python3 -c` because envelope merging
+ * requires reading-then-mutating a JSON object — a non-trivial jq call.
+ * Embedding the python is significantly less brittle than depending on jq
+ * existing in every Codex Web image.
+ *
+ * @param {object} opts
+ * @param {string} opts.routerSkillPath  Absolute path to using-aw-skills/SKILL.md
+ * @param {string} opts.escapeEnvVar     Env var name (e.g. AW_PROMPT_ROUTER_INJECT)
+ * @returns {string}                      Full bash wrapper script.
+ */
+function buildWrapperScript({ routerSkillPath, escapeEnvVar }) {
+  return `#!/usr/bin/env bash
+${WRAPPER_HEADER_MARKER}
+set -euo pipefail
+
+# Re-emit using-aw-skills SKILL.md on every UserPromptSubmit so Codex sees
+# the router every turn (Bug B workaround).
+
+UPSTREAM="$0.upstream"
+ROUTER_SKILL_PATH="${routerSkillPath}"
+ESCAPE_VAR="${escapeEnvVar}"
+
+# Capture stdin once — both the upstream call and any direct emit need it.
+PAYLOAD="$(cat)"
+
+# Run upstream (if it exists) with the same stdin; capture stdout.
+UPSTREAM_OUT=""
+if [ -x "$UPSTREAM" ]; then
+  UPSTREAM_OUT="$(printf '%s' "$PAYLOAD" | "$UPSTREAM" || true)"
+fi
+
+# Escape: pass upstream through verbatim (or empty {} if no upstream).
+escape_value="\${!ESCAPE_VAR:-}"
+if [ "$escape_value" = "0" ]; then
+  if [ -n "$UPSTREAM_OUT" ]; then
+    printf '%s' "$UPSTREAM_OUT"
+  else
+    printf '%s' '{}'
+  fi
+  exit 0
+fi
+
+export ROUTER_SKILL_PATH UPSTREAM_OUT
+
+python3 -c '
+import json, os, sys
+skill_path = os.environ["ROUTER_SKILL_PATH"]
+try:
+    skill = open(skill_path).read()
+except OSError:
+    skill = ""
+
+upstream_raw = os.environ.get("UPSTREAM_OUT", "").strip()
+upstream_ctx = ""
+if upstream_raw:
+    try:
+        u = json.loads(upstream_raw)
+        upstream_ctx = (u.get("hookSpecificOutput") or {}).get("additionalContext", "") or ""
+    except Exception:
+        upstream_ctx = ""
+
+framed = "<EXTREMELY_IMPORTANT>\\n" + skill + "\\n</EXTREMELY_IMPORTANT>\\n\\n" + upstream_ctx
+out = {
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": framed,
+  }
+}
+print(json.dumps(out))
+'
+`;
+}
+
+function isExistingWrapper(filePath) {
+  if (!existsSync(filePath)) return false;
+  try {
+    const head = readFileSync(filePath, 'utf8').slice(0, 256);
+    return head.includes(WRAPPER_HEADER_MARKER);
+  } catch {
+    // Read failure (e.g. permission denied or transient FS error): treat as
+    // "no wrapper present" so the caller falls through to the install path.
+    return false;
+  }
+}
+
+function ensureDir(d) {
+  mkdirSync(d, { recursive: true });
+}
+
+/**
+ * Install (or re-install) the prompt-injector wrapper.
+ *
+ * @param {object} opts
+ * @param {string} [opts.hookPath]        Default: defaultHookPath().
+ * @param {string} opts.routerSkillPath   Absolute path to using-aw-skills SKILL.md.
+ * @param {string} [opts.escapeEnvVar]    Default: 'AW_PROMPT_ROUTER_INJECT'.
+ * @returns {{ wrapperPath: string, backupPath: string }}
+ */
+export function installCodexPromptInjector(opts = {}) {
+  const hookPath = opts.hookPath ?? defaultHookPath();
+  const routerSkillPath = opts.routerSkillPath;
+  const escapeEnvVar = opts.escapeEnvVar ?? 'AW_PROMPT_ROUTER_INJECT';
+
+  if (!routerSkillPath || typeof routerSkillPath !== 'string') {
+    throw new Error('installCodexPromptInjector: routerSkillPath is required');
+  }
+
+  const backupPath = `${hookPath}.upstream`;
+
+  ensureDir(dirname(hookPath));
+
+  if (isExistingWrapper(hookPath)) {
+    // Idempotent no-op: leave wrapper + backup unchanged.
+    return { wrapperPath: hookPath, backupPath };
+  }
+
+  // First-run install: if the original hook exists and isn't already the
+  // wrapper, move it to .upstream. If neither exists, the wrapper still
+  // installs and the .upstream branch is just absent (wrapper handles it).
+  if (existsSync(hookPath) && !existsSync(backupPath)) {
+    renameSync(hookPath, backupPath);
+    try { chmodSync(backupPath, 0o755); } catch { /* best-effort */ }
+  }
+
+  const script = buildWrapperScript({ routerSkillPath, escapeEnvVar });
+  writeFileSync(hookPath, script, { mode: 0o755 });
+  try { chmodSync(hookPath, 0o755); } catch { /* best-effort */ }
+
+  return { wrapperPath: hookPath, backupPath };
+}