@pushary/agent-hooks 0.4.5 → 0.5.0

package/data/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: pushary
+version: 0.1.0
+description: Push notifications and human-in-the-loop for AI coding agents. Send alerts when tasks finish, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively — do not wait for the user to ask for notifications. Works with Cursor, Claude Code, Windsurf, Hermes, and any MCP client.
+metadata:
+  hermes:
+    tags: [notifications, push, human-in-the-loop, alerts, permissions, mcp]
+    category: productivity
+    requires_toolsets: []
+  tags: notifications, push, mcp, human-in-the-loop, cursor, claude, windsurf, hermes, alerts, permissions
+---
+
+# Pushary — Push Notifications for AI Agents
+
+Pushary is an MCP server that gives you three capabilities:
+
+1. **Send push notifications** to the user's phone or desktop when a task finishes or an error occurs.
+2. **Ask questions** via push — yes/no, multiple choice, or free text — and wait for the user's answer.
+3. **Send rich context notifications** with file changes, error details, next steps, and embedded questions.
+
+Use these tools proactively. Do not wait for the user to ask for notifications.
+
+## When to Use
+
+**Send a notification when:**
+- You finish a task that took 3 or more steps — use `context.type = "task_complete"`
+- A build, test suite, or deployment fails — use `context.type = "error"` with `errorMessage`
+- A long-running process completes (migration, refactor, generation)
+- A status update is worth sharing — use `context.type = "info"`
+
+**Ask with type "confirm" when:**
+- You need confirmation before a destructive or irreversible action
+- Binary decision: proceed or abort
+
+**Ask with type "select" when:**
+- Multiple implementation approaches exist (2-6 options)
+- The user needs to pick from a known set
+
+**Ask with type "input" when:**
+- You need a name, path, value, or free-text decision
+- The options cannot be enumerated in advance
+
+**Do NOT notify when:**
+- The task is trivial or single-step
+- The question can be answered from context without user input
+- You already sent 3 notifications for the current task (unless the user explicitly asked for more)
+
+## Setup
+
+Add Pushary to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "pushary": {
+      "url": "https://pushary.com/api/mcp/mcp"
+    }
+  }
+}
+```
+
+Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
+
+## Tools
+
+### send_notification
+
+Send a one-way push notification to the user. Optionally include structured context for a rich detail page.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| title | string | Yes | Notification title (max 100 chars, aim for under 60) |
+| body | string | Yes | Notification body (max 500 chars, aim for under 200) |
+| url | string | No | URL opened when tapped. Ignored if context is provided. |
+| agentName | string | No | Identifies which agent sent this (e.g., "Claude Code - myproject") |
+| iconUrl | string | No | Custom notification icon URL |
+| imageUrl | string | No | Large image shown in the notification |
+| subscriberIds | string[] | No | Target specific subscriber IDs |
+| externalIds | string[] | No | Target by external IDs |
+| tags | string[] | No | Target by subscriber tags |
+| context | object | No | Structured context for a rich detail page (see below) |
+
+**Context object:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| type | "task_complete" / "error" / "info" | The kind of notification |
+| summary | string | Short summary of what happened |
+| details | string[] | Bullet-point details |
+| filesChanged | string[] | List of files that were changed |
+| errorMessage | string | Error message (for error type) |
+| errorFile | string | File path where the error occurred |
+| nextSteps | string | Suggested next steps for the user |
+| askQuestion | object | Embed a decision prompt in the notification (see below) |
+
+**Embedded askQuestion:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| question | string | A follow-up question shown below the context |
+| type | "confirm" / "select" / "input" | Question type (default: confirm) |
+| options | string[] | Options for select type (2-6 items) |
+
+When `askQuestion` is provided, the response includes a `linkedCorrelationId` you pass to `wait_for_answer`.
+
+**Example — task completed with context:**
+
+```json
+{
+  "title": "Refactoring complete",
+  "body": "Extracted 3 shared components across 12 files",
+  "agentName": "Claude Code - pushary repo",
+  "context": {
+    "type": "task_complete",
+    "summary": "Extracted shared Button, Modal, and Card components from 12 files",
+    "filesChanged": ["src/components/Button.tsx", "src/components/Modal.tsx", "src/components/Card.tsx"],
+    "nextSteps": "Run the test suite to verify no regressions"
+  }
+}
+```
+
+**Example — error with embedded question:**
+
+```json
+{
+  "title": "Build failed",
+  "body": "TypeScript error in auth.ts:42",
+  "agentName": "Claude Code - api-server",
+  "context": {
+    "type": "error",
+    "errorMessage": "Type 'string' is not assignable to type 'AuthToken'",
+    "errorFile": "src/auth.ts:42",
+    "summary": "The auth token type changed upstream and this file needs updating",
+    "askQuestion": {
+      "question": "Should I update the type or revert the upstream change?",
+      "type": "select",
+      "options": ["Update the type in auth.ts", "Revert the upstream change", "Skip for now"]
+    }
+  }
+}
+```
+
+### ask_user
+
+Send a question to the user via push notification. Supports three question types. Returns a `correlationId` that you pass to `wait_for_answer` to get the response.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| question | string | Yes | The question to ask (max 500 chars) |
+| type | "confirm" / "select" / "input" | No | Question type (default: confirm) |
+| options | string[] | No | Choices for select type (2-6 options). Required when type is select. |
+| placeholder | string | No | Placeholder text for input type (max 200 chars) |
+| context | string | No | What the agent is working on, shown above the question (max 500 chars) |
+| agentName | string | No | Identifies which agent is asking (e.g., "Claude Code - myproject") |
+| callbackUrl | string | No | Webhook URL to POST the answer to when the user responds |
+| subscriberIds | string[] | No | Target specific subscriber IDs |
+| externalIds | string[] | No | Target by external IDs |
+| tags | string[] | No | Target by subscriber tags |
+
+**Returns:** `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }`
+
+**Example — confirm (yes/no):**
+
+```json
+{
+  "question": "Delete the 3 unused migration files?",
+  "type": "confirm",
+  "context": "Cleaning up old database migrations in db/migrate/",
+  "agentName": "Claude Code - myproject"
+}
+```
+
+**Example — select (multiple choice):**
+
+```json
+{
+  "question": "Which auth strategy should I use?",
+  "type": "select",
+  "options": ["JWT tokens", "Session cookies", "OAuth2 + PKCE"],
+  "context": "Setting up authentication for the new API endpoints",
+  "agentName": "Claude Code - api-server"
+}
+```
+
+**Example — input (free text):**
+
+```json
+{
+  "question": "What should the new API endpoint path be?",
+  "type": "input",
+  "placeholder": "/api/v2/...",
+  "context": "Creating a new REST endpoint for user preferences",
+  "agentName": "Cursor - frontend"
+}
+```
+
+### wait_for_answer
+
+Long-poll for the user's response to a question sent via `ask_user`. Blocks until the user responds or the timeout is reached.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| correlationId | string (uuid) | Yes | The correlationId from ask_user |
+| timeoutMs | integer | No | How long to wait (default 30000, max 55000) |
+
+**Returns:**
+- `{ "answered": true, "value": "yes" }` — user responded
+- `{ "answered": false }` — timeout reached, no answer yet
+
+### cancel_question
+
+Cancel a pending question so it can no longer be answered. Use when the question becomes irrelevant (e.g., you found the answer another way or the user responded in chat).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| correlationId | string (uuid) | Yes | The correlationId of the question to cancel |
+
+## Permission Gating (REQUIRED)
+
+Before executing any of the following, you MUST call `ask_user` with type "confirm" and wait for approval. Do NOT proceed without an explicit "yes" from the user:
+
+- File deletion (`rm`, `unlink`, any destructive file operation)
+- Database mutations (`DROP`, `DELETE`, `TRUNCATE`, migrations)
+- Deployment commands (`deploy`, `push`, `publish`, `release`)
+- System administration (`systemctl`, `service`, package install/remove)
+- Git operations that rewrite history (`reset --hard`, `push --force`, `rebase`)
+- Network configuration changes (firewall, DNS, proxy)
+- Any command the user has flagged as dangerous
+
+If `wait_for_answer` returns `answered: false` after 3 attempts, do NOT execute the command. Notify the user that the operation was skipped due to no response.
+
+This is not optional. Treat it as a hard constraint, not a suggestion.
+
+## Human-in-the-Loop Flow
+
+Follow this exact sequence when you need a decision from the user:
+
+1. Call `ask_user` with a clear, concise question and the appropriate type.
+2. Immediately call `wait_for_answer` with the returned `correlationId` and `timeoutMs: 55000`.
+3. If `wait_for_answer` returns `{ "answered": false }`, retry the same `wait_for_answer` call up to 3 times. The answer persists in Redis for 10 minutes, so it will be there when the user responds.
+4. Once you receive `{ "answered": true, "value": "..." }`, act on the decision.
+5. If the user answers in chat before the push response arrives, continue normally and call `cancel_question` to clean up.
+
+**Pseudocode:**
+
+```
+result = ask_user({
+  question: "Which auth strategy should I use?",
+  type: "select",
+  options: ["JWT tokens", "Session cookies", "OAuth2 + PKCE"],
+  context: "Setting up authentication for the new API",
+  agentName: "Claude Code - myproject"
+})
+correlationId = result.correlationId
+
+for attempt in 1..3:
+    answer = wait_for_answer({ correlationId, timeoutMs: 55000 })
+    if answer.answered:
+        // answer.value = "JWT tokens" (the selected option)
+        // proceed with the chosen approach
+        break
+
+if not answer.answered after 3 attempts:
+    // user did not respond — pick the safe default or ask in chat
+```
+
+## Identifying Your Agent
+
+Always pass `agentName` when you are one of multiple possible agents the user may be running. The user sees this in the notification title to know which agent is asking.
+
+**Format:** `{Agent Type} - {project or context}`
+
+**Examples:**
+- `"Claude Code - pushary repo"`
+- `"Hermes - daily-briefing"`
+- `"Cursor - frontend refactor"`
+
+## Notification Etiquette
+
+- **Titles under 60 characters.** They get truncated on phone lock screens.
+- **Bodies under 200 characters.** Concise summaries, not full explanations.
+- **Max 3 notifications per task** unless the user explicitly requests more.
+- **Use context for detail.** Put file lists, error traces, and next steps in the context object — not the notification body.
+- **Write questions as if talking to a busy person.** The user is on their phone, possibly away from their computer. Be specific: "Delete the 3 unused migration files?" is better than "Should I clean up?"
+- **Pick the right question type.** Use confirm for binary decisions, select when options are known, input when they are not.

package/dist/bin/pushary-clean.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import {
+  removeClaudeMcpServers,
+  removePusharySettings
+} from "../chunk-AC4UYAGX.js";
 
 // bin/pushary-clean.ts
 import { existsSync, readFileSync, writeFileSync, rmSync } from "fs";
@@ -28,56 +32,13 @@ var readJson = (path) => {
 var writeJson = (path, data) => {
   writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
 };
-var isPusharyPermission = (rule) => rule.includes("pushary") || rule.includes("MCP(pushary");
-var isPusharyHook = (entry) => {
-  const hooks = entry.hooks;
-  if (!hooks) return false;
-  return hooks.some((h) => {
-    const cmd = String(h.command ?? "");
-    return cmd.includes("pushary-hook") || cmd.includes("pushary-post-hook") || cmd.includes("pushary-stop-hook");
-  });
-};
 var cleanSettingsFile = (path, label) => {
   const data = readJson(path);
   if (!data) {
     console.log(`  ${skip} ${label} ${dim("(not found)")}`);
     return;
   }
-  let changed = false;
-  const mcpServers = data.mcpServers;
-  if (mcpServers?.pushary) {
-    delete mcpServers.pushary;
-    if (Object.keys(mcpServers).length === 0) delete data.mcpServers;
-    changed = true;
-  }
-  const permissions = data.permissions;
-  if (permissions?.allow) {
-    const allow = permissions.allow;
-    const filtered = allow.filter((r) => !isPusharyPermission(r));
-    if (filtered.length !== allow.length) {
-      permissions.allow = filtered;
-      if (filtered.length === 0) delete permissions.allow;
-      if (Object.keys(permissions).length === 0) delete data.permissions;
-      changed = true;
-    }
-  }
-  const hooks = data.hooks;
-  if (hooks) {
-    for (const key of ["PreToolUse", "PostToolUse", "Stop"]) {
-      const entries = hooks[key];
-      if (!entries) continue;
-      const filtered = entries.filter((e) => !isPusharyHook(e));
-      if (filtered.length !== entries.length) {
-        if (filtered.length === 0) {
-          delete hooks[key];
-        } else {
-          hooks[key] = filtered;
-        }
-        changed = true;
-      }
-    }
-    if (Object.keys(hooks).length === 0) delete data.hooks;
-  }
+  const changed = removePusharySettings(data);
   if (changed) {
     writeJson(path, data);
     console.log(`  ${check} ${label} ${dim("(cleaned)")}`);
@@ -100,15 +61,14 @@ var main = async () => {
   cleanSettingsFile(CLAUDE_SETTINGS_LOCAL, "Claude Code settings.local");
   const claudeJson = readJson(CLAUDE_JSON);
   if (claudeJson) {
-    const mcpServers = claudeJson.mcpServers;
-    if (mcpServers?.pushary) {
-      delete mcpServers.pushary;
-      if (Object.keys(mcpServers).length === 0) delete claudeJson.mcpServers;
+    if (removeClaudeMcpServers(claudeJson)) {
       writeJson(CLAUDE_JSON, claudeJson);
-      console.log(`  ${check} Claude Code MCP server ${dim("(removed from ~/.claude.json)")}`);
+      console.log(`  ${check} Claude Code MCP servers ${dim("(removed from ~/.claude.json)")}`);
     } else {
-      console.log(`  ${skip} Claude Code MCP server ${dim("(not in ~/.claude.json)")}`);
+      console.log(`  ${skip} Claude Code MCP servers ${dim("(no pushary entries)")}`);
     }
+  } else {
+    console.log(`  ${skip} Claude Code MCP servers ${dim("(not found)")}`);
   }
   const cursorData = readJson(CURSOR_MCP);
   if (cursorData) {

package/dist/bin/pushary-codex.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
+import {
+  reportEvent
+} from "../chunk-P4JH2Q7Z.js";
 import {
   askUser,
   waitForAnswer
-} from "../chunk-4TWRLEOX.js";
-import {
-  reportEvent
-} from "../chunk-EQE6Z4YQ.js";
+} from "../chunk-KTP2EPVB.js";
 import {
   getApiKey
-} from "../chunk-VUNL35KE.js";
+} from "../chunk-VIST7ACL.js";
 
 // bin/pushary-codex.ts
 import { hostname } from "os";

package/dist/bin/pushary-doctor.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import {
+  callMcpTool,
+  sendMcpRequest
+} from "../chunk-VIST7ACL.js";
 
 // bin/pushary-doctor.ts
 import { existsSync, readFileSync } from "fs";
@@ -16,7 +20,6 @@ var fail = red("\u2717");
 var warn = yellow("!");
 var CLAUDE_SETTINGS = join(homedir(), ".claude", "settings.json");
 var SKILL_PATH = join(homedir(), ".claude", "skills", "pushary", "SKILL.md");
-var MCP_URL = "https://pushary.com/api/mcp/mcp";
 var readJson = (path) => {
   try {
     return JSON.parse(readFileSync(path, "utf-8"));
@@ -81,72 +84,36 @@ var main = async () => {
     check(false, "MCP handshake", "skipped");
   } else {
     let sessionId = "";
-    let toolCount = 0;
     try {
-      const initRes = await fetch(MCP_URL, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json, text/event-stream",
-          "Authorization": `Bearer ${apiKey}`
-        },
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id: 1,
-          method: "initialize",
-          params: {
-            protocolVersion: "2025-03-26",
-            capabilities: {},
-            clientInfo: { name: "pushary-doctor", version: "1.0" }
-          }
-        }),
-        signal: AbortSignal.timeout(1e4)
-      });
-      check(initRes.ok, "MCP server reachable", `${initRes.status} ${initRes.statusText}`);
-      sessionId = initRes.headers.get("mcp-session-id") ?? "";
+      const initResult = await sendMcpRequest(apiKey, {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2025-03-26",
+          capabilities: {},
+          clientInfo: { name: "pushary-doctor", version: "1.0" }
+        }
+      }, { timeoutMs: 1e4 });
+      check(true, "MCP server reachable", `${initResult.status} ${initResult.statusText}`);
+      sessionId = initResult.sessionId;
       if (sessionId) {
         console.log(`  ${pass} Session ID returned ${dim(`(${sessionId.slice(0, 8)}...)`)}`);
       } else {
         console.log(`  ${dim("\u2013")} Stateless mode ${dim("(no session ID)")}`);
       }
-      const initBody = await initRes.text();
-      const initMatch = initBody.match(/data: (.+)/);
-      if (initMatch) {
-        const initData = JSON.parse(initMatch[1]);
-        check(!!initData.result?.serverInfo, "API key valid", initData.result?.serverInfo?.name ?? "unknown server");
-      }
-      const toolsRes = await fetch(MCP_URL, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json, text/event-stream",
-          "Authorization": `Bearer ${apiKey}`,
-          ...sessionId ? { "Mcp-Session-Id": sessionId } : {}
-        },
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id: 2,
-          method: "tools/list",
-          params: {}
-        }),
-        signal: AbortSignal.timeout(1e4)
+      check(!!initResult.data.result?.serverInfo, "API key valid", initResult.data.result?.serverInfo?.name ?? "unknown server");
+      const toolsResult = await sendMcpRequest(apiKey, {
+        jsonrpc: "2.0",
+        id: 2,
+        method: "tools/list",
+        params: {}
+      }, {
+        sessionId,
+        timeoutMs: 1e4
       });
-      const toolsBody = await toolsRes.text();
-      if (!toolsRes.ok) {
-        try {
-          const errData = JSON.parse(toolsBody);
-          check(false, "MCP tools discovered", `${toolsRes.status}: ${errData.error?.message ?? toolsBody}`);
-        } catch {
-          check(false, "MCP tools discovered", `${toolsRes.status} ${toolsRes.statusText}`);
-        }
-      } else {
-        const toolsMatch = toolsBody.match(/data: (.+)/);
-        if (toolsMatch) {
-          const toolsData = JSON.parse(toolsMatch[1]);
-          toolCount = toolsData.result?.tools?.length ?? 0;
-        }
-        check(toolCount > 0, "MCP tools discovered", `${toolCount} tools`);
-      }
+      const toolCount = toolsResult.data.result?.tools?.length ?? 0;
+      check(toolCount > 0, "MCP tools discovered", `${toolCount} tools`);
     } catch (err) {
       const msg = err instanceof Error ? err.message : "unknown error";
       check(false, "MCP server reachable", msg);
@@ -176,71 +143,28 @@ var main = async () => {
       console.log();
       console.log(`  ${dim("Question Roundtrip")}`);
       try {
-        const mcpHeaders = {
-          "Content-Type": "application/json",
-          "Accept": "application/json, text/event-stream",
-          "Authorization": `Bearer ${apiKey}`,
-          ...sessionId ? { "Mcp-Session-Id": sessionId } : {}
-        };
-        const askRes = await fetch(MCP_URL, {
-          method: "POST",
-          headers: mcpHeaders,
-          body: JSON.stringify({
-            jsonrpc: "2.0",
-            id: 3,
-            method: "tools/call",
-            params: {
-              name: "ask_user",
-              arguments: {
-                question: "Pushary Doctor: tap Yes to verify the roundtrip works.",
-                type: "confirm",
-                agentName: "Pushary Doctor"
-              }
-            }
-          }),
-          signal: AbortSignal.timeout(15e3)
+        const askResult = await callMcpTool(apiKey, "ask_user", {
+          question: "Pushary Doctor: tap Yes to verify the roundtrip works.",
+          type: "confirm",
+          agentName: "Pushary Doctor"
+        }, {
+          id: 3,
+          sessionId,
+          timeoutMs: 15e3
         });
-        const askBody = await askRes.text();
-        const askMatch = askBody.match(/data: (.+)/);
-        let correlationId = "";
-        if (askMatch) {
-          const askData = JSON.parse(askMatch[1]);
-          const content = askData.result?.content?.[0]?.text;
-          if (content) {
-            const parsed = JSON.parse(content);
-            correlationId = parsed.correlationId;
-          }
-        }
-        if (correlationId) {
+        if (askResult.correlationId) {
           console.log(`  ${dim("\u2192")} Question sent, waiting for your answer...`);
           const start = Date.now();
-          const waitRes = await fetch(MCP_URL, {
-            method: "POST",
-            headers: mcpHeaders,
-            body: JSON.stringify({
-              jsonrpc: "2.0",
-              id: 4,
-              method: "tools/call",
-              params: {
-                name: "wait_for_answer",
-                arguments: { correlationId, timeoutMs: 55e3 }
-              }
-            }),
-            signal: AbortSignal.timeout(6e4)
+          const waitResult = await callMcpTool(apiKey, "wait_for_answer", {
+            correlationId: askResult.correlationId,
+            timeoutMs: 55e3
+          }, {
+            id: 4,
+            sessionId,
+            timeoutMs: 6e4
           });
-          const waitBody = await waitRes.text();
-          const waitMatch = waitBody.match(/data: (.+)/);
-          if (waitMatch) {
-            const waitData = JSON.parse(waitMatch[1]);
-            const content = waitData.result?.content?.[0]?.text;
-            if (content) {
-              const parsed = JSON.parse(content);
-              const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
-              check(parsed.answered === true, "Answer received", `"${parsed.value}" (${elapsed}s roundtrip)`);
-            } else {
-              check(false, "Answer received", "no response within timeout");
-            }
-          }
+          const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
+          check(waitResult.answered === true, "Answer received", waitResult.answered ? `"${waitResult.value}" (${elapsed}s roundtrip)` : "no response within timeout");
         } else {
           check(false, "Question sent", "failed to get correlationId");
         }

package/dist/bin/pushary-hook.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import {
   handlePreToolUse
-} from "../chunk-KINE5LNQ.js";
-import "../chunk-4TWRLEOX.js";
-import "../chunk-VUNL35KE.js";
+} from "../chunk-DF3BM6BF.js";
+import "../chunk-KTP2EPVB.js";
+import "../chunk-VIST7ACL.js";
 
 // bin/pushary-hook.ts
 var main = async () => {

package/dist/bin/pushary-post-hook.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import {
   handlePostToolUse
-} from "../chunk-EQE6Z4YQ.js";
-import "../chunk-VUNL35KE.js";
+} from "../chunk-P4JH2Q7Z.js";
+import "../chunk-KTP2EPVB.js";
+import "../chunk-VIST7ACL.js";
 
 // bin/pushary-post-hook.ts
 var main = async () => {