@ghl-ai/aw 0.1.44-beta.2 → 0.1.44-beta.4

package/c4/index.mjs

@@ -35,6 +35,7 @@ export {
   REQUIRED_ENFORCEMENT_PHRASES,
   REQUIRED_STAGE_MARKERS_CLAUDE,
   REQUIRED_STAGE_MARKERS_CURSOR,
+  REQUIRED_MCP_FALLBACK_MARKERS,
   SLIM_CARD_CLAUDE,
   SLIM_CARD_CURSOR,
   buildSlimRouterCard,

package/c4/jsonMerge.mjs

@@ -110,9 +110,23 @@ function commandMatchesAnyPattern(command, patterns) {
  * @param {object} opts.newEntry           Entry to append after dedup.
  * @param {string[]} opts.commandPatterns  Substrings; existing entries with
  *                                         a matching `command` field are stripped.
+ * @param {object} [opts.ensureTopLevel]   Optional map of top-level keys to set
+ *                                         on the JSON root (always overwritten).
+ *                                         Used to guarantee schema-required
+ *                                         markers like `{ version: 1 }` for
+ *                                         Cursor's `~/.cursor/hooks.json`.
+ *                                         Without this, Cursor's runtime fails
+ *                                         open and silently skips the hook
+ *                                         (cursor.com/docs/hooks §schema, §979).
  * @returns {{ changed: boolean, prevEntriesRemoved: number }}
  */
-export function jsonMergeWithDedup({ filePath, jsonPointer, newEntry, commandPatterns }) {
+export function jsonMergeWithDedup({
+  filePath,
+  jsonPointer,
+  newEntry,
+  commandPatterns,
+  ensureTopLevel,
+}) {
   if (!filePath || typeof filePath !== 'string') throw new Error('filePath is required');
   if (typeof jsonPointer !== 'string') throw new Error('jsonPointer is required');
   if (newEntry == null || typeof newEntry !== 'object') throw new Error('newEntry must be an object');
@@ -142,6 +156,14 @@ export function jsonMergeWithDedup({ filePath, jsonPointer, newEntry, commandPat
   filtered.push(newEntry);
   parent[key] = filtered;
 
+  // Apply schema-required top-level keys last, so callers can pin invariants
+  // (e.g. `version: 1`) even if a stale on-disk file is missing them.
+  if (ensureTopLevel != null && typeof ensureTopLevel === 'object' && !Array.isArray(ensureTopLevel)) {
+    for (const [k, v] of Object.entries(ensureTopLevel)) {
+      root[k] = v;
+    }
+  }
+
   const serialized = JSON.stringify(root, null, 2) + '\n';
   const changed = atomicWriteIfChanged(filePath, serialized);
 

package/c4/slimRouter.mjs

@@ -47,6 +47,94 @@ export const REQUIRED_STAGE_MARKERS_CURSOR = [
   'Hard Gate',
 ];
 
+/* MCP fallback markers — must be present on every cloud-harness card.
+ * Cursor Cloud only honors MCPs added via the dashboard; if the native
+ * `mcp_ghl-ai_*` surface is missing, the agent must reach ghl-ai via
+ * direct JSON-RPC over HTTP. These substrings let the slim-card validator
+ * fail loudly if a future edit accidentally drops the section. */
+export const REQUIRED_MCP_FALLBACK_MARKERS = [
+  'MCP fallback',
+  'services.leadconnectorhq.com/agentic-workspace/mcp',
+  'GITHUB_PAT',
+  'Bearer',
+  'tools/list',
+  'tools/call',
+  'text/event-stream',
+];
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * MCP fallback sections — appended to both slim cards. Cursor variant adds
+ * the dashboard-upgrade hint (cursor.com/agents); Claude variant omits it
+ * (Claude Code Web reads ~/.claude/settings.json::mcpServers natively).
+ * ───────────────────────────────────────────────────────────────────────── */
+
+const MCP_FALLBACK_CURSOR = `
+## MCP fallback — cloud harness only (use ONLY if native MCP is missing)
+
+\`aw c4\` registers \`ghl-ai\` in \`~/.cursor/mcp.json\`, but Cursor Cloud
+agents only honor MCPs added via the dashboard
+(\`cursor.com/dashboard?tab=integrations\` for Team plans, or the MCP
+dropdown at \`cursor.com/agents\` for personal). When \`mcp_ghl-ai_*\`
+tools are missing from your tool surface, fall back to direct HTTP
+JSON-RPC.
+
+- Endpoint: \`https://services.leadconnectorhq.com/agentic-workspace/mcp\`
+- Headers: \`Authorization: Bearer $GITHUB_PAT\`,
+  \`Content-Type: application/json\`,
+  \`Accept: application/json, text/event-stream\`
+- Protocol: JSON-RPC 2.0 — call \`tools/list\` to discover, then
+  \`tools/call\` with \`{ name, arguments }\`. SSE responses arrive as
+  \`data: <json>\` lines; parse the first JSON payload.
+
+Example (list GKE clusters):
+
+\`\`\`bash
+curl -sS -X POST \\
+  https://services.leadconnectorhq.com/agentic-workspace/mcp \\
+  -H "Authorization: Bearer $GITHUB_PAT" \\
+  -H "Content-Type: application/json" \\
+  -H "Accept: application/json, text/event-stream" \\
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
+       "params":{"name":"gcp_kube-list-clusters",
+                 "arguments":{"location":"-"}}}'
+\`\`\`
+
+Security: NEVER echo, log, or print \`$GITHUB_PAT\` — it is sensitive.
+Use this fallback ONLY when the native MCP tools are unavailable.
+`;
+
+const MCP_FALLBACK_CLAUDE = `
+## MCP fallback (use ONLY if native MCP is missing)
+
+\`aw c4\` registers \`ghl-ai\` in \`~/.claude/settings.json::mcpServers\`.
+If the \`mcp_ghl-ai_*\` tool surface is unavailable in this runtime,
+fall back to direct HTTP JSON-RPC.
+
+- Endpoint: \`https://services.leadconnectorhq.com/agentic-workspace/mcp\`
+- Headers: \`Authorization: Bearer $GITHUB_PAT\`,
+  \`Content-Type: application/json\`,
+  \`Accept: application/json, text/event-stream\`
+- Protocol: JSON-RPC 2.0 — call \`tools/list\` to discover, then
+  \`tools/call\` with \`{ name, arguments }\`. SSE responses arrive as
+  \`data: <json>\` lines; parse the first JSON payload.
+
+Example (list GKE clusters):
+
+\`\`\`bash
+curl -sS -X POST \\
+  https://services.leadconnectorhq.com/agentic-workspace/mcp \\
+  -H "Authorization: Bearer $GITHUB_PAT" \\
+  -H "Content-Type: application/json" \\
+  -H "Accept: application/json, text/event-stream" \\
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
+       "params":{"name":"gcp_kube-list-clusters",
+                 "arguments":{"location":"-"}}}'
+\`\`\`
+
+Security: NEVER echo, log, or print \`$GITHUB_PAT\` — it is sensitive.
+Use this fallback ONLY when the native MCP tools are unavailable.
+`;
+
 /* ─────────────────────────────────────────────────────────────────────────
  * Card text — copied verbatim from spec.md::§"Slim card content".
  * Trailing newline is intentional: Claude/Cursor parse the file as a single
@@ -118,7 +206,7 @@ Platform rules live under \`.aw/.aw_rules/platform/\` — search in this order:
 \`~/.aw/.aw_registry/.aw_rules/platform/\`. Read \`universal/AGENTS.md\` and
 \`security/AGENTS.md\` first, then the touched-domain \`AGENTS.md\` plus
 \`references/*.md\` on demand.
-`;
+${MCP_FALLBACK_CLAUDE}`;
 
 export const SLIM_CARD_CURSOR = `# AW Router (Compact) — using-aw-skills
 
@@ -185,7 +273,7 @@ Platform rules live under \`.aw/.aw_rules/platform/\` — search in this order:
 \`~/.aw/.aw_registry/.aw_rules/platform/\`. Read \`universal/AGENTS.md\` and
 \`security/AGENTS.md\` first, then the touched-domain \`AGENTS.md\` plus
 \`references/*.md\` on demand.
-`;
+${MCP_FALLBACK_CURSOR}`;
 
 /* ─────────────────────────────────────────────────────────────────────────
  * Hook scripts — embedded as bash one-liners that emit fixed JSON envelopes.
@@ -276,6 +364,11 @@ export function buildSlimRouterCard(harness) {
       throw new Error(`Slim card for ${harness} missing stage marker: "${marker}"`);
     }
   }
+  for (const marker of REQUIRED_MCP_FALLBACK_MARKERS) {
+    if (!card.includes(marker)) {
+      throw new Error(`Slim card for ${harness} missing MCP fallback marker: "${marker}"`);
+    }
+  }
 
   return { card, bytes };
 }
@@ -404,6 +497,14 @@ function installCursorSlim({ home, escaped }) {
   // Same rationale as installClaudeSlim — escape mode skips the card write.
   ensureDir(dirname(hooksJsonPath));
 
+  // Cursor's hooks.json schema requires `"version": 1` at the top level
+  // (cursor.com/docs/hooks). Without it, the runtime silently fails open
+  // and never invokes our hooks — which is exactly the bug that prevented
+  // the slim card from reaching cursor-cloud agents in 0.1.44-beta.3.
+  // We pin this on every merge call so the file is always schema-valid,
+  // even if a stale or partial file already exists on disk.
+  const cursorHooksTopLevel = { version: 1 };
+
   // (G1) The Node-adapter wrapper that satisfies Cursor's request-rewrite
   // JSON contract. NEVER delegate to shared/user-prompt-submit.sh directly.
   const promptHookCommand =
@@ -431,6 +532,7 @@ function installCursorSlim({ home, escaped }) {
         'aw-slim-session-start.sh',
         '.cursor/hooks/session-start.sh',
       ],
+      ensureTopLevel: cursorHooksTopLevel,
     });
   } else {
     const fullEcc =
@@ -448,6 +550,7 @@ function installCursorSlim({ home, escaped }) {
         'aw-slim-session-start.sh',
         '.cursor/hooks/session-start.sh',
       ],
+      ensureTopLevel: cursorHooksTopLevel,
     });
   }
 
@@ -460,6 +563,7 @@ function installCursorSlim({ home, escaped }) {
       description: 'AW per-prompt rules reminder (ECC Node-adapter)',
     },
     commandPatterns: ['before-submit-prompt.sh'],
+    ensureTopLevel: cursorHooksTopLevel,
   });
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.44-beta.2",
+  "version": "0.1.44-beta.4",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {