@pushary/agent-hooks 0.7.0 → 0.8.1

package/data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pushary
-version: 0.1.0
+version: 0.4.1
 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:
@@ -47,13 +47,23 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 
 ## Setup
 
-Add Pushary to your MCP configuration:
+Run the CLI setup (recommended — configures MCP, hooks, permissions, and skill in one step):
+
+```bash
+npx @pushary/agent-hooks@latest setup
+```
+
+Or add Pushary manually to your MCP configuration:
 
 ```json
 {
   "mcpServers": {
     "pushary": {
-      "url": "https://pushary.com/api/mcp/mcp"
+      "type": "http",
+      "url": "https://pushary.com/api/mcp/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
     }
   }
 }
@@ -61,6 +71,12 @@ Add Pushary to your MCP configuration:
 
 Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
 
+After setup, verify with:
+
+```bash
+npx @pushary/agent-hooks@latest doctor
+```
+
 ## Tools
 
 ### send_notification
@@ -144,7 +160,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 
 ### 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.
+Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached — no need to call `wait_for_answer` separately.
 
 **Parameters:**
 
@@ -155,13 +171,20 @@ Send a question to the user via push notification. Supports three question types
 | 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") |
+| wait | boolean | No | Wait for the answer before returning (default: true). Set false for manual polling. |
+| timeoutMs | integer | No | Max wait time in ms (max 55000). Uses site policy if omitted. |
+| agentName | string | No | Identifies which agent is asking. Format: "{Agent} - {project}" (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 }`
+**Returns (when wait=true, default):**
+- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` — user responded
+- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` — timeout reached
+
+**Returns (when wait=false):**
+- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` — use `wait_for_answer` to poll
 
 **Example — confirm (yes/no):**
 
@@ -200,7 +223,7 @@ Send a question to the user via push notification. Supports three question types
 
 ### 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.
+Poll for the user's response to a question sent via `ask_user` with `wait: false`. Not needed when using the default blocking mode.
 
 **Parameters:**
 
@@ -235,21 +258,13 @@ Before executing any of the following, you MUST call `ask_user` with type "confi
 - 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.
+If `ask_user` returns `answered: false`, do NOT execute the command. Send a notification 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:**
+One tool call — `ask_user` blocks and returns the answer:
 
 ```
 result = ask_user({
@@ -259,19 +274,15 @@ result = ask_user({
   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
+if result.answered:
+    // result.value = "JWT tokens" — proceed with the chosen approach
+else:
+    // user did not respond — pick the safe default or notify and skip
 ```
 
+If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
+
 ## 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.

package/dist/bin/pushary-setup.js

@@ -26,6 +26,14 @@ var green = (s) => `\x1B[32m${s}\x1B[0m`;
 var cyan = (s) => `\x1B[36m${s}\x1B[0m`;
 var yellow = (s) => `\x1B[33m${s}\x1B[0m`;
 var check = green("\u2713");
+var parseKeyFlag = () => {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--key" && args[i + 1]) return args[i + 1].trim();
+    if (args[i].startsWith("--key=")) return args[i].slice(6).trim();
+  }
+  return void 0;
+};
 var readJson = (path) => {
   try {
     return JSON.parse(readFileSync(path, "utf-8"));
@@ -394,17 +402,41 @@ var main = async () => {
   console.log(`  ${dim("Push notifications for AI coding agents")}`);
   console.log();
   await checkForUpdates(version);
-  console.log(`  ${dim("Get your API key at")} ${cyan("pushary.com/sign-up")}`);
-  console.log();
-  const apiKey = await input({ message: "API key:" });
-  if (!apiKey.trim() || !/^pk_[a-f0-9]+\.[a-f0-9]+$/.test(apiKey.trim())) {
+  const keyPattern = /^pk_[a-f0-9]+\.[a-f0-9]+$/;
+  const flagKey = parseKeyFlag();
+  const envKey = process.env.PUSHARY_API_KEY?.trim();
+  let trimmedKey;
+  if (flagKey && keyPattern.test(flagKey)) {
+    const masked = `${flagKey.slice(0, 8)}...${flagKey.slice(-4)}`;
+    console.log(`  ${check} Using API key: ${dim(masked)}`);
+    console.log();
+    trimmedKey = flagKey;
+  } else if (envKey && keyPattern.test(envKey)) {
+    const masked = `${envKey.slice(0, 8)}...${envKey.slice(-4)}`;
+    console.log(`  ${check} Found API key in environment: ${dim(masked)}`);
+    console.log();
+    const useExisting = await confirm({ message: "Use this key?", default: true });
+    if (useExisting) {
+      trimmedKey = envKey;
+    } else {
+      const apiKey = await input({ message: "API key:" });
+      trimmedKey = apiKey.trim();
+    }
+  } else {
+    console.log(`  ${dim("Paste your API key from the onboarding page.")}`);
+    console.log(`  ${dim("Can't find it? Copy it from:")} ${cyan("pushary.com/dashboard/agent/settings")}`);
+    console.log();
+    const apiKey = await input({ message: "API key:" });
+    trimmedKey = apiKey.trim();
+  }
+  if (!trimmedKey || !keyPattern.test(trimmedKey)) {
     console.log(`
-  ${yellow("!")} Invalid key format. Expected: pk_xxx.sk_xxx`);
-    console.log(`  ${dim("Get yours at")} ${cyan("https://pushary.com/sign-up?from=ai-coding")}
+  ${yellow("!")} Invalid key format. Expected: ${dim("pk_xxx.xxx")}`);
+    console.log(`  ${dim("Copy your key from")} ${cyan("https://pushary.com/dashboard/agent/settings")}`);
+    console.log(`  ${dim("Or sign up at")} ${cyan("https://pushary.com/sign-up?from=ai-coding")}
 `);
     process.exit(1);
   }
-  const trimmedKey = apiKey.trim();
   const agents = await checkbox({
     message: "Which agents do you use? " + dim("(space = toggle, enter = confirm)"),
     choices: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushary/agent-hooks",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Permission hooks for AI coding agents: route tool approvals through Pushary push notifications",
   "author": "Pushary <business@pushary.com>",
   "homepage": "https://pushary.com",