@trygocode/notify 0.4.0 → 0.6.0

package/dist/src/opencode.js

@@ -8,14 +8,20 @@
 //                           "command": ["npx","-y","@trygocode/notify","mcp"],
 //                           "enabled": true }
 //      `command` is a single ARRAY (binary + args), plus `type` + `enabled`.
-//   2. WRITE a `session.idle` plugin to `<config-dir>/plugin/gocode-notify.js`.
-//      OpenCode has NO stop-hook command array; instead a plugin subscribes to
-//      the `session.idle` event (the OpenCode equivalent of Cursor `stop` /
-//      Claude `Stop`) and fires the SHARED `on-stop` dispatcher:
-//        gocode-notify on-stop --source opencode --dedupe-key opencode-idle || true
-//      The child is detached + unref'd and errors are swallowed (`|| true`), so a
-//      notification/push failure can never block the session — exactly one ping
-//      per idle, in lockstep with Claude/Cursor (same `on-stop` dispatcher).
+//   2. WRITE an event plugin to `<config-dir>/plugin/gocode-notify.js` that
+//      subscribes to TWO event classes:
+//        a) END-OF-TURN — `session.idle` (legacy) + `session.status` (modern),
+//           the OpenCode equivalent of Cursor `stop` / Claude `Stop`. Fires the
+//           SHARED `on-stop` dispatcher → a `finished` ping.
+//        b) QUESTION — `permission.asked` (the "asking now" edge), the OpenCode
+//           equivalent of Claude's `Notification` hook. Fires a plain
+//           `awaiting_input` ping ("Agent needs you") so a real question shows as
+//           a QUESTION, not a misleading `finished`. (Cursor has NO such event;
+//           OpenCode genuinely exposes it via permission events. We do NOT listen
+//           to permission.updated/replied — those also fire after the user
+//           answers and would re-ping a resolved question.)
+//      Each child is detached + unref'd and errors are swallowed (`|| true`), so a
+//      notification/push failure can never block the session.
 //
 // The on-demand rule/skill (Claude SKILL.md / Cursor rule) is SKIPPED for
 // OpenCode: OpenCode has no auto-loaded standalone per-file rule mechanism (the
@@ -72,6 +78,21 @@ export const OPENCODE_MCP_ENTRY = {
 // resolved version forever and never auto-updates (npm/cli#6664). Pinning
 // `@latest` makes the hook always fetch the newest publish so users self-update.
 export const OPENCODE_STOP_COMMAND = "npx -y @trygocode/notify@latest on-stop --source opencode --dedupe-key opencode-idle || true";
+/**
+ * The shell command the plugin fires when OpenCode raises a PERMISSION request —
+ * the OpenCode equivalent of "the agent needs the user" (Claude's `Notification`
+ * hook / the Cursor AskQuestion hook). Unlike Cursor, OpenCode genuinely exposes
+ * this signal: the `permission.asked` event fires the instant the agent pauses to
+ * ask the user to approve/answer something. We map it to a plain `awaiting_input`
+ * ping ("Agent needs you") — the SAME kind Claude Code fires — so a real question
+ * surfaces as a QUESTION notification, not a misleading `finished`. (We listen to
+ * `permission.asked` ONLY, never `permission.updated`/`permission.replied`, which
+ * also fire AFTER the user answers and would re-ping a resolved question.)
+ *
+ * Ends in `|| true` so a failed push can never block the session; carries a
+ * distinct `--dedupe-key` so it coalesces with itself but not with the idle ping.
+ */
+export const OPENCODE_ASK_COMMAND = 'npx -y @trygocode/notify@latest send --kind awaiting_input --source opencode --title "Agent needs you" --dedupe-key opencode-permission || true';
 /**
  * Substrings that together identify our plugin file as OURS. Used to keep
  * uninstall surgical: we only delete the plugin file when BOTH markers are
@@ -157,13 +178,15 @@ import { spawn } from "node:child_process";
 // Per-session last-fire timestamps so idle+status for the SAME turn coalesce.
 const lastFiredAt = new Map();
 const DEDUPE_MS = 4000;
+// Separate per-session debounce for permission/question events so a rapid burst
+// of permission.asked events for one prompt coalesces into a single ping, while
+// staying INDEPENDENT of the end-of-turn debounce (a question must not be
+// suppressed by a recent finished ping — different event class).
+const lastAskedAt = new Map();
 
-function fire() {
+function fire(command) {
   try {
-    const child = spawn(
-      ${JSON.stringify(OPENCODE_STOP_COMMAND)},
-      { shell: true, detached: true, stdio: "ignore" },
-    );
+    const child = spawn(command, { shell: true, detached: true, stdio: "ignore" });
     child.unref();
   } catch {
     // never block the session on a notification failure
@@ -195,13 +218,39 @@ function maybeFire(sessionID) {
   const prev = lastFiredAt.get(key) ?? 0;
   if (now - prev < DEDUPE_MS) return; // coalesce idle+status for one turn
   lastFiredAt.set(key, now);
-  fire();
+  fire(${JSON.stringify(OPENCODE_STOP_COMMAND)});
+}
+
+// The agent paused to ask the user (permission.asked). Fire an "Agent needs
+// you" question ping. Debounced separately from the end-of-turn ping so a burst
+// of asks for one prompt coalesces into one.
+function maybeAsk(sessionID) {
+  const key = sessionID || "_";
+  const now = Date.now();
+  const prev = lastAskedAt.get(key) ?? 0;
+  if (now - prev < DEDUPE_MS) return;
+  lastAskedAt.set(key, now);
+  fire(${JSON.stringify(OPENCODE_ASK_COMMAND)});
 }
 
 export const GocodeNotify = async () => ({
   event: async ({ event }) => {
     if (!event) return;
     const props = event.properties ?? {};
+    // QUESTION signal — the agent is waiting on the user (OpenCode's real
+    // "needs you" event; Cursor has no equivalent). Fired BEFORE the idle/status
+    // checks so a permission request is never misread as a plain end-of-turn.
+    //
+    // We listen ONLY to \`permission.asked\` — the moment the agent RAISES a
+    // request. We deliberately do NOT listen to \`permission.updated\` /
+    // \`permission.replied\`: those are state transitions that ALSO fire AFTER the
+    // user answers, which would re-emit "Agent needs you" once the question is
+    // already resolved — exactly the false-notification class this fix exists to
+    // avoid. \`permission.asked\` is the unambiguous "asking now" edge.
+    if (event.type === "permission.asked") {
+      maybeAsk(props.sessionID);
+      return;
+    }
     if (event.type === "session.idle") {
       maybeFire(props.sessionID);
       return;
@@ -332,7 +381,7 @@ export async function writeOpenCodeConfig(runtime, opts) {
             runtime: name,
             written,
             skipped: false,
-            detail: "merged mcp.gocode-notify entry; wrote session.idle plugin (rule skipped — OpenCode has no standalone rule file)",
+            detail: "merged mcp.gocode-notify entry; wrote end-of-turn + permission(question) plugin (rule skipped — OpenCode has no standalone rule file)",
         };
     }
     catch (err) {

package/dist/src/send.js

@@ -32,8 +32,25 @@ export const NOTIFY_KINDS = [
 export function isNotifyKind(value) {
     return typeof value === "string" && NOTIFY_KINDS.includes(value);
 }
-/** Default request timeout (PRD §4.4: 5s hard cap). */
-export const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Default PER-ATTEMPT request timeout. Bumped 5s → 12s (2026-06-20): a cold
+ * self-hosted OpenHands server reached over Tailscale routinely takes 5-8s to
+ * answer its first request after idle, so the old 5s cap silently dropped real
+ * `finished` / `awaiting_input` pushes (observed in `notify.log`:
+ * "timeout after 5000ms"). 12s comfortably clears a cold-start round-trip while
+ * still being a hard cap so a wedged server can never hang a hook's turn.
+ */
+export const DEFAULT_TIMEOUT_MS = 12000;
+/**
+ * How many times to ATTEMPT a send before giving up (1 = no retry). A single
+ * cold-start timeout or transient network blip used to mean the user got no
+ * notification at all; we now retry transient failures (timeout / network /
+ * 5xx) with a short backoff so a slow-but-reachable server still delivers.
+ * A 4xx (auth / bad request) is permanent and is NOT retried.
+ */
+export const DEFAULT_MAX_ATTEMPTS = 3;
+/** Backoff (ms) applied BEFORE attempt N (index 0 = before the 2nd attempt). */
+export const RETRY_BACKOFF_MS = [500, 1500];
 /** Rotate `notify.log` once it grows past this (keeps one `.1` backup). */
 export const MAX_LOG_BYTES = 256 * 1024;
 /** Absolute path to the failure log. */
@@ -93,13 +110,32 @@ async function failure(reason, opts, extra = {}) {
     await appendLog(`SEND FAIL: ${reason}`, opts);
     return { ok: false, error: reason, ...extra };
 }
+/** Real backoff sleep (cancellable-free; the caller never aborts a backoff). */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
- * Send one push to `/notify/send`. Resolves (never rejects) to a
- * {@link SendResult}; callers may treat ANY result as "exit 0".
+ * Send one push to `/notify/send`, retrying transient failures with a short
+ * backoff. Resolves (never rejects) to a {@link SendResult}; callers may treat
+ * ANY result as "exit 0".
+ *
+ * Retry policy (2026-06-20): a single cold-start timeout or transient network
+ * blip used to drop the user's notification entirely. We now attempt up to
+ * {@link DEFAULT_MAX_ATTEMPTS} times, backing off per {@link RETRY_BACKOFF_MS}
+ * between attempts. A 4xx (auth / bad-request) is PERMANENT and stops the loop
+ * immediately — retrying it would just burn the hook's time budget. Every
+ * attempt's failure is logged so `notify.log` shows the full retry trail.
  */
 export async function send(payload, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    // Coerce defensively: a NaN (e.g. a failed CLI numeric parse) must not make
+    // `Math.max(1, NaN) === NaN` skip the loop and then throw on `last!.result`.
+    const rawAttempts = opts.maxAttempts;
+    const maxAttempts = typeof rawAttempts === "number" && Number.isFinite(rawAttempts)
+        ? Math.max(1, Math.floor(rawAttempts))
+        : DEFAULT_MAX_ATTEMPTS;
+    const sleep = opts.sleepImpl ?? defaultSleep;
     let creds;
     try {
         creds = await readCredentials(opts);
@@ -112,41 +148,78 @@ export async function send(payload, opts = {}) {
     }
     const server = normalizeServer(opts.server ?? creds.server ?? builtinDefaultServer());
     const url = `${server}/api/v1/notify/send`;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const res = await fetchImpl(url, {
-            method: "POST",
-            headers: {
-                "content-type": "application/json",
-                authorization: `Bearer ${creds.api_key}`,
-            },
-            body: JSON.stringify(buildBody(payload)),
-            signal: controller.signal,
-        });
-        if (!res.ok) {
-            return failure(`server responded ${res.status} for kind=${payload.kind}`, opts, {
-                status: res.status,
+    const apiKey = creds.api_key;
+    const body = JSON.stringify(buildBody(payload));
+    /** One attempt — resolves to an {@link AttemptOutcome}, never throws. */
+    const attempt = async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${apiKey}`,
+                },
+                body,
+                signal: controller.signal,
             });
+            if (!res.ok) {
+                // 5xx is transient (server hiccup / cold start) → retriable.
+                // 4xx is permanent (auth / bad request) → do not retry.
+                const retriable = res.status >= 500;
+                return {
+                    result: { ok: false, status: res.status, error: `server responded ${res.status} for kind=${payload.kind}` },
+                    retriable,
+                };
+            }
+            let sent;
+            try {
+                const json = (await res.json());
+                if (typeof json?.sent === "number")
+                    sent = json.sent;
+            }
+            catch {
+                // A 2xx with an unparseable body still counts as delivered.
+            }
+            return { result: { ok: true, status: res.status, sent }, retriable: false };
         }
-        let sent;
-        try {
-            const json = (await res.json());
-            if (typeof json?.sent === "number")
-                sent = json.sent;
+        catch (err) {
+            // Timeout (aborted) and network errors are both transient → retriable.
+            const reason = controller.signal.aborted
+                ? `timeout after ${timeoutMs}ms for kind=${payload.kind}`
+                : `request failed: ${errMessage(err)}`;
+            return { result: { ok: false, error: reason }, retriable: true };
         }
-        catch {
-            // A 2xx with an unparseable body still counts as delivered.
+        finally {
+            clearTimeout(timer);
         }
-        return { ok: true, status: res.status, sent };
-    }
-    catch (err) {
-        const reason = controller.signal.aborted
-            ? `timeout after ${timeoutMs}ms for kind=${payload.kind}`
-            : `request failed: ${errMessage(err)}`;
-        return failure(reason, opts);
-    }
-    finally {
-        clearTimeout(timer);
+    };
+    let last;
+    for (let i = 0; i < maxAttempts; i++) {
+        if (i > 0) {
+            // Backoff before this retry. Clamp to the last defined step for any
+            // attempt count beyond the table so a larger `maxAttempts` still works.
+            const backoff = RETRY_BACKOFF_MS[Math.min(i - 1, RETRY_BACKOFF_MS.length - 1)] ?? 0;
+            await sleep(backoff);
+        }
+        last = await attempt();
+        if (last.result.ok) {
+            // Note the recovery in the log when an earlier attempt had failed, so a
+            // "it worked on retry 2" story is visible in notify.log.
+            if (i > 0) {
+                await appendLog(`SEND OK on attempt ${i + 1}/${maxAttempts} for kind=${payload.kind}`, opts);
+            }
+            return last.result;
+        }
+        // Log every failed attempt so the retry trail is diagnosable.
+        const willRetry = last.retriable && i < maxAttempts - 1;
+        await appendLog(`SEND FAIL (attempt ${i + 1}/${maxAttempts}${willRetry ? ", will retry" : ""}): ${last.result.error}`, opts);
+        // Permanent failure (4xx) — stop immediately, retrying can't help.
+        if (!last.retriable)
+            break;
     }
+    // All attempts exhausted (or a permanent failure). `last` is always set here
+    // because the loop runs at least once (maxAttempts >= 1).
+    return last.result;
 }

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Single source of truth for the CLI version. Keep in sync with package.json.
-export const VERSION = "0.4.0";
+export const VERSION = "0.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trygocode/notify",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Free phone + branded desktop notifications for any coding agent (Cursor, Claude Code, OpenCode, Ralph/Homer) via the GoCode app.",
   "license": "MIT",
   "type": "module",