agent-blocked 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# agent-blocked
+
+CLI installer and reporter for Agent Blocked.
+
+Install adapters in any agent project:
+
+```bash
+npx agent-blocked install --tool=all
+```
+
+Report a blocker manually:
+
+```bash
+npx agent-blocked report --event=needs_direction --severity=medium --reason="Need human direction"
+```
+
+After `install`, the project gets local helper files under `.agent-blocked/`, so agents can report without depending on the Agent Blocked app repository:
+
+```bash
+node .agent-blocked/report.mjs --event=needs_credentials --severity=critical --reason="Missing deploy credentials"
+```

package/bin/agent-blocked.mjs

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+
+const root = process.cwd();
+const markerStart = "<!-- agent-blocked:start -->";
+const markerEnd = "<!-- agent-blocked:end -->";
+
+function arg(name, fallback = "") {
+  const prefix = `--${name}=`;
+  const index = process.argv.indexOf(`--${name}`);
+  const found = process.argv.find((value) => value.startsWith(prefix));
+  if (found) return found.slice(prefix.length);
+  if (index !== -1 && process.argv[index + 1] && !process.argv[index + 1].startsWith("--")) {
+    return process.argv[index + 1];
+  }
+  return fallback;
+}
+
+function hasFlag(name) {
+  return process.argv.includes(`--${name}`);
+}
+
+function commandName() {
+  return process.argv[2] && !process.argv[2].startsWith("--") ? process.argv[2] : "help";
+}
+
+function shellQuoted(value) {
+  return `'${String(value).replace(/'/g, "'\"'\"'")}'`;
+}
+
+function writeFileIfMissing(path, content) {
+  if (existsSync(path) && !hasFlag("force")) {
+    console.log(`Kept existing ${path}. Use --force to overwrite.`);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  console.log(`Wrote ${path}.`);
+}
+
+const reportScript = `#!/usr/bin/env node
+
+function arg(name, fallback = "") {
+  const prefix = \`--\${name}=\`;
+  const index = process.argv.indexOf(\`--\${name}\`);
+  const found = process.argv.find((value) => value.startsWith(prefix));
+  if (found) return found.slice(prefix.length);
+  if (index !== -1 && process.argv[index + 1] && !process.argv[index + 1].startsWith("--")) {
+    return process.argv[index + 1];
+  }
+  return fallback;
+}
+
+const webhookUrl = arg("url", process.env.AGENT_BLOCKED_WEBHOOK_URL || "https://agentblocked.com/api/agent-blocked");
+const token = arg("token", process.env.AGENT_BLOCKED_AGENT_TOKEN || "");
+const agentId = arg("agent", process.env.AGENT_NAME || "coding-agent");
+const eventType = arg("event", "needs_direction");
+const severity = arg("severity", "medium");
+const reason = arg("reason", "The agent needs human help to continue.");
+const details = arg("details", "");
+const runId = arg("run-id", "");
+const provider = arg("provider", "");
+const model = arg("model", "");
+const confidence = arg("confidence", "");
+
+if (!token) {
+  console.error("Missing AGENT_BLOCKED_AGENT_TOKEN or --token=...");
+  process.exit(1);
+}
+
+const payload = {
+  agentId,
+  eventType,
+  severity,
+  reason,
+  ...(details ? { details } : {}),
+  ...(runId ? { runId } : {}),
+  ...(provider ? { provider } : {}),
+  ...(model ? { model } : {}),
+  ...(confidence ? { confidence: Number(confidence) } : {})
+};
+
+const response = await fetch(webhookUrl, {
+  method: "POST",
+  headers: {
+    authorization: \`Bearer \${token}\`,
+    "content-type": "application/json"
+  },
+  body: JSON.stringify(payload)
+});
+
+const body = await response.text();
+
+if (!response.ok) {
+  console.error(\`Agent Blocked report failed: \${response.status} \${body}\`);
+  process.exit(1);
+}
+
+console.log(body);
+`;
+
+const claudeHookScript = `#!/usr/bin/env node
+
+let input = "";
+process.stdin.setEncoding("utf8");
+for await (const chunk of process.stdin) input += chunk;
+
+const event = input ? JSON.parse(input) : {};
+const webhookUrl = process.env.AGENT_BLOCKED_WEBHOOK_URL || "https://agentblocked.com/api/agent-blocked";
+const token = process.env.AGENT_BLOCKED_AGENT_TOKEN;
+const agentId = process.env.AGENT_NAME || "claude-code";
+
+if (!token) process.exit(0);
+
+function mapEventType(eventName, notificationType) {
+  if (eventName === "Notification" && notificationType === "permission_prompt") return "approval_required";
+  if (eventName === "Notification" && notificationType === "idle_prompt") return "needs_direction";
+  if (eventName === "PermissionDenied") return "needs_credentials";
+  if (eventName === "StopFailure") return "tool_failure";
+  return "needs_direction";
+}
+
+const eventType = mapEventType(event.hook_event_name, event.notification_type);
+const payload = {
+  agentId,
+  eventType,
+  severity: eventType === "tool_failure" || eventType === "needs_credentials" ? "high" : "medium",
+  reason: event.message || event.title || \`Claude Code hook fired: \${event.hook_event_name || "unknown"}\`,
+  details: JSON.stringify({
+    hookEventName: event.hook_event_name,
+    notificationType: event.notification_type,
+    cwd: event.cwd,
+    sessionId: event.session_id
+  }),
+  provider: "anthropic",
+  model: "claude-code",
+  runId: event.session_id
+};
+
+try {
+  await fetch(webhookUrl, {
+    method: "POST",
+    headers: {
+      authorization: \`Bearer \${token}\`,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(payload)
+  });
+} catch {
+  // Hooks should not break Claude Code when notification delivery fails.
+}
+`;
+
+const instructions = `# Agent Blocked instructions for coding agents
+
+When you are blocked by missing credentials, unclear direction, approval requirements, repeated tool failures, low confidence, or external context, stop burning tokens and report the blockage.
+
+Preferred report command from the repository root:
+
+\`\`\`bash
+node .agent-blocked/report.mjs --event=needs_direction --severity=medium --reason="I need human direction to continue" --details="Explain what decision or context is missing."
+\`\`\`
+
+Environment expected by the report command:
+
+\`\`\`bash
+export AGENT_BLOCKED_WEBHOOK_URL="https://agentblocked.com/api/agent-blocked"
+export AGENT_BLOCKED_AGENT_TOKEN="your-scoped-token"
+export AGENT_NAME="your-agent-name"
+\`\`\`
+
+Event types:
+
+- hard_blocked
+- needs_credentials
+- needs_direction
+- tool_failure
+- approval_required
+- low_confidence
+- lonely_agent
+- other
+
+Never include secrets, API keys, passwords, OAuth tokens, or private customer data in the report payload.
+`;
+
+function ensureHelperFiles() {
+  writeFileIfMissing(join(root, ".agent-blocked", "report.mjs"), reportScript);
+  writeFileIfMissing(join(root, ".agent-blocked", "instructions.md"), instructions);
+}
+
+function mergeHookEntries(existing = [], incoming = []) {
+  const seen = new Set(existing.map((value) => JSON.stringify(value)));
+  const merged = [...existing];
+
+  for (const entry of incoming) {
+    const sig = JSON.stringify(entry);
+    if (!seen.has(sig)) {
+      merged.push(entry);
+      seen.add(sig);
+    }
+  }
+
+  return merged;
+}
+
+function mergeClaudeSettings(path, settings) {
+  let currentSettings = {};
+  let currentHooks = {};
+
+  if (existsSync(path)) {
+    const existingRaw = readFileSync(path, "utf8");
+    try {
+      const parsed = JSON.parse(existingRaw);
+      currentSettings = parsed && typeof parsed === "object" ? parsed : {};
+      currentHooks = currentSettings.hooks && typeof currentSettings.hooks === "object" ? currentSettings.hooks : {};
+    } catch {
+      console.log(`Could not parse ${path}. Wrote example file for manual merge instead.`);
+      writeFileIfMissing(join(root, ".claude", "settings.agent-blocked.example.json"), `${JSON.stringify(settings, null, 2)}\n`);
+      return;
+    }
+  }
+
+  const mergedHooks = { ...currentHooks };
+  for (const [eventName, hooks] of Object.entries(settings.hooks || {})) {
+    mergedHooks[eventName] = mergeHookEntries(
+      Array.isArray(mergedHooks[eventName]) ? mergedHooks[eventName] : [],
+      hooks || []
+    );
+  }
+
+  currentSettings.hooks = mergedHooks;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(currentSettings, null, 2)}\n`);
+  console.log(`Updated ${path} with Agent Blocked hooks.`);
+}
+
+function upsertMarkedSection(path, title) {
+  const section = `${markerStart}
+## ${title}
+
+${instructions}
+${markerEnd}`;
+
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const next = current.includes(markerStart) && current.includes(markerEnd)
+    ? current.replace(new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`), section)
+    : `${current.trim() ? `${current.trim()}\n\n` : ""}${section}\n`;
+
+  writeFileSync(path, next);
+  console.log(`Installed Agent Blocked instructions in ${path}.`);
+}
+
+function installClaude() {
+  writeFileIfMissing(join(root, ".agent-blocked", "claude-hook.mjs"), claudeHookScript);
+
+  const settings = {
+    hooks: {
+      Notification: [
+        {
+          matcher: "permission_prompt|idle_prompt",
+          hooks: [{ type: "command", command: "node .agent-blocked/claude-hook.mjs" }]
+        }
+      ],
+      PermissionDenied: [
+        {
+          hooks: [{ type: "command", command: "node .agent-blocked/claude-hook.mjs" }]
+        }
+      ],
+      StopFailure: [
+        {
+          hooks: [{ type: "command", command: "node .agent-blocked/claude-hook.mjs" }]
+        }
+      ]
+    }
+  };
+
+  writeFileIfMissing(join(root, ".claude", "settings.agent-blocked.example.json"), `${JSON.stringify(settings, null, 2)}\n`);
+  mergeClaudeSettings(join(root, ".claude", "settings.local.json"), settings);
+}
+
+function installCodex() {
+  upsertMarkedSection(join(root, "AGENTS.md"), "Codex Agent Blocked setup");
+}
+
+function installGemini() {
+  upsertMarkedSection(join(root, "GEMINI.md"), "Gemini CLI Agent Blocked setup");
+}
+
+function installAider() {
+  upsertMarkedSection(join(root, "CONVENTIONS.md"), "Aider Agent Blocked setup");
+}
+
+const installers = {
+  claude: installClaude,
+  codex: installCodex,
+  gemini: installGemini,
+  aider: installAider
+};
+
+function install() {
+  const tool = arg("tool", "all").toLowerCase();
+  const selected = tool === "all" ? Object.keys(installers) : tool.split(",").map((value) => value.trim()).filter(Boolean);
+
+  ensureHelperFiles();
+
+  for (const name of selected) {
+    if (!installers[name]) {
+      console.error(`Unknown tool "${name}". Use --tool=claude,codex,gemini,aider or --tool=all.`);
+      process.exit(1);
+    }
+    installers[name]();
+  }
+
+  console.log("\nNext: set AGENT_BLOCKED_WEBHOOK_URL, AGENT_BLOCKED_AGENT_TOKEN, and AGENT_NAME in the shell where your agent runs.");
+  console.log("Manual report command: node .agent-blocked/report.mjs --event=needs_direction --severity=medium --reason=\"Need human direction\"");
+}
+
+async function report() {
+  const webhookUrl = arg("url", process.env.AGENT_BLOCKED_WEBHOOK_URL || "https://agentblocked.com/api/agent-blocked");
+  const token = arg("token", process.env.AGENT_BLOCKED_AGENT_TOKEN || "");
+  const agentId = arg("agent", process.env.AGENT_NAME || "coding-agent");
+  const eventType = arg("event", "needs_direction");
+  const severity = arg("severity", "medium");
+  const reason = arg("reason", "The agent needs human help to continue.");
+  const details = arg("details", "");
+
+  if (!token) {
+    console.error("Missing AGENT_BLOCKED_AGENT_TOKEN or --token=...");
+    process.exit(1);
+  }
+
+  const response = await fetch(webhookUrl, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({
+      agentId,
+      eventType,
+      severity,
+      reason,
+      ...(details ? { details } : {})
+    })
+  });
+
+  const body = await response.text();
+  if (!response.ok) {
+    console.error(`Agent Blocked report failed: ${response.status} ${body}`);
+    process.exit(1);
+  }
+  console.log(body);
+}
+
+async function codex() {
+  const separator = process.argv.indexOf("--");
+  const args = separator === -1 ? process.argv.slice(3) : process.argv.slice(separator + 1);
+  const command = args[0] || "codex";
+  const commandArgs = args[0] ? args.slice(1) : [];
+
+  const child = spawn(command, commandArgs, { stdio: "inherit", shell: false });
+  const code = await new Promise((resolve) => child.on("close", resolve));
+
+  if (code && process.env.AGENT_BLOCKED_AGENT_TOKEN) {
+    process.argv = [
+      process.argv[0],
+      process.argv[1],
+      "report",
+      "--event=tool_failure",
+      "--severity=high",
+      `--reason=Codex exited with code ${code}`,
+      `--details=${command} ${commandArgs.join(" ")}`
+    ];
+    await report();
+  }
+
+  process.exit(code || 0);
+}
+
+function help() {
+  console.log(`Agent Blocked CLI
+
+Usage:
+  agent-blocked install --tool=claude|codex|gemini|aider|all
+  agent-blocked report --event=needs_direction --severity=medium --reason="Need human help"
+  agent-blocked codex -- codex "your task"
+
+Examples:
+  npx agent-blocked install --tool=all
+  npx agent-blocked report --event=needs_credentials --severity=critical --reason="Missing AWS credentials"
+`);
+}
+
+switch (commandName()) {
+  case "install":
+    install();
+    break;
+  case "report":
+    await report();
+    break;
+  case "codex":
+    await codex();
+    break;
+  default:
+    help();
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "agent-blocked",
+  "version": "0.1.0",
+  "description": "CLI installer and reporter for Agent Blocked AI agent escalation alerts.",
+  "type": "module",
+  "bin": {
+    "agent-blocked": "bin/agent-blocked.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "alerts",
+    "claude",
+    "codex",
+    "gemini",
+    "aider"
+  ],
+  "license": "MIT"
+}