@dv.nghiem/flowdeck 0.4.0 → 0.4.1

package/dist/hooks/notifications.d.ts

@@ -1,21 +1,86 @@
-type NotifyLevel = "info" | "critical";
+export type NotifyLevel = "info" | "critical";
+/**
+ * Structured reasons that can trigger a notification.
+ * Helps consumers understand why a notification fired.
+ */
+export type NotificationReason = "completed" | "input_required" | "confirmation_required" | "error";
+/**
+ * Normalise a raw command string to a bare command name.
+ * "/fd-discuss" → "discuss", "fd-plan" → "plan", "new-feature" → "new-feature"
+ */
+export declare function normalizeCommandName(raw: string): string;
 /**
  * Fire a desktop notification without blocking the caller.
  * Silently ignores failures — notification is best-effort only.
  */
 export declare function notify(title: string, body: string, level?: NotifyLevel): void;
+export type NotifyFn = (title: string, body: string, level?: NotifyLevel) => void;
+/**
+ * Event-driven notification controller.
+ *
+ * Lifecycle:
+ *   1. onCommandExecuted() — records that a command was dispatched (NOT yet processed)
+ *   2. onSessionIdle()     — fires notification when the agent finishes processing
+ *   3. onSessionError()    — fires notification on critical failure
+ *
+ * Deduplication: the same (command + lifecycle-state) pair is never notified twice,
+ * even if session.idle fires multiple times in a row.
+ *
+ * @param notifyFn — injectable notify function (defaults to the real OS notifier; pass
+ *                   a test stub to avoid spawning OS processes in tests).
+ * @param log      — optional diagnostic logger.
+ */
+export declare class NotificationController {
+    /** The command currently awaiting a session.idle notification, or null. */
+    private pendingCommand;
+    /** Key of the last notification that was fired; used for deduplication. */
+    private lastNotifiedKey;
+    private readonly notifyFn;
+    private readonly log;
+    constructor(notifyFn?: NotifyFn, log?: (msg: string) => void);
+    /**
+     * Called when the `command.executed` event fires.
+     * Records the command so the next session.idle can produce the right notification.
+     * Must NOT fire a notification — the command has only been dispatched, not completed.
+     */
+    onCommandExecuted(rawCommand: string): void;
+    /**
+     * Called when the `session.idle` event fires.
+     * Fires at most one notification per pending command.
+     * If no command is pending, fires a generic completion notification only when
+     * the agent actually edited files (hasEdits = true).
+     *
+     * @param hasEdits — true when the session file tracker has recorded edits this turn.
+     */
+    onSessionIdle(hasEdits: boolean): void;
+    /**
+     * Called when the `session.error` event fires.
+     * Always fires unless the identical error was already reported.
+     */
+    onSessionError(errorMsg: string): void;
+    /**
+     * Reset all state. Useful in tests or when starting a new session.
+     */
+    reset(): void;
+    getPendingCommand(): string | null;
+    getLastNotifiedKey(): string | null;
+}
 /**
- * Fires a notification when a command that needs user interaction starts.
- * Call this from command.execute.before after the command result is generated.
+ * Fires a notification when a permission is requested.
+ * This is event-driven (permission.ask hook fires after the agent's request)
+ * so it does not need to go through the NotificationController.
  */
-export declare function notifyCommandInteraction(command: string): void;
+export declare function notifyPermissionNeeded(tool: string): void;
 /**
- * Fires a notification when the session becomes idle (task complete).
+ * @deprecated Use NotificationController.onSessionIdle() instead.
+ * Kept for backward compatibility — does nothing now that the controller
+ * handles all session-idle notifications.
  */
 export declare function notifySessionIdle(): void;
 /**
- * Fires a notification when a permission is requested.
+ * @deprecated Use NotificationController.onCommandExecuted() + onSessionIdle() instead.
+ * This function fired notifications on command ENTRY (too early).
+ * It is preserved as a no-op so that any lingering callers compile without error.
  */
-export declare function notifyPermissionNeeded(tool: string): void;
-export {};
+export declare function notifyCommandInteraction(_command: string): void;
 //# sourceMappingURL=notifications.d.ts.map

package/dist/hooks/notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/hooks/notifications.ts"],"names":[],"mappings":"AAsBA,KAAK,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;AAEtC;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,WAAoB,GAAG,IAAI,CAoCrF;AAUD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAiB9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAMxC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMzD"}
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/hooks/notifications.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,CAAA;AAE7C;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,gBAAgB,GAChB,uBAAuB,GACvB,OAAO,CAAA;AAEX;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,WAAoB,GAAG,IAAI,CAoCrF;AAUD,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;AAEjF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAsB;IACjC,2EAA2E;IAC3E,OAAO,CAAC,cAAc,CAAsB;IAC5C,2EAA2E;IAC3E,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuB;gBAE/B,QAAQ,GAAE,QAAiB,EAAE,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe;IAK9E;;;;OAIG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAc3C;;;;;;;OAOG;IACH,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IA4CtC;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAgBtC;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAClC,kBAAkB,IAAI,MAAM,GAAG,IAAI;CACpC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMzD;AAID;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE/D"}

package/dist/hooks/notifications.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * NotificationController Tests
+ *
+ * Covers the core timing contract:
+ * - No notification when a command is merely entered (command.execute.before)
+ * - Notification fires on session.idle after a completion command
+ * - Notification fires on session.idle after an interactive command
+ * - Notification fires on session.error
+ * - Duplicate notifications are suppressed
+ * - Long-running command only notifies at the correct lifecycle point
+ * - Generic (non-command) idle notification fires only when edits exist
+ */
+export {};
+//# sourceMappingURL=notifications.test.d.ts.map

package/dist/hooks/notifications.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.test.d.ts","sourceRoot":"","sources":["../../src/hooks/notifications.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/hooks/session-idle-hook.d.ts

@@ -1,10 +1,12 @@
 /**
  * Session Idle Hook
  * Fires when OpenCode's session becomes idle (task completed).
- * 1. Sends a desktop notification (if notify() succeeds)
- * 2. Logs a summary of edited files via client.app.log
+ * Logs a summary of edited files via client.app.log.
  *
- * Inspired by oh-my-openagent's session notification + ECC's session.idle handler.
+ * NOTE: Desktop notifications are no longer sent from this hook.
+ * They are handled by NotificationController in notifications.ts, which
+ * fires at the correct lifecycle points (session.idle after a command,
+ * session.error on failure) and deduplicates properly.
  */
 import type { SessionFileTracker } from "./file-tracker";
 export declare function createSessionIdleHook(client: {

package/dist/hooks/session-idle-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-idle-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/session-idle-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE;IAAE,GAAG,EAAE;QAAE,GAAG,EAAE,CAAC,IAAI,EAAE;YAAE,IAAI,EAAE;gBAAE,OAAO,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,CAAA;CAAE,EAC5I,OAAO,EAAE,kBAAkB,uBAiC5B"}
+{"version":3,"file":"session-idle-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/session-idle-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE;IAAE,GAAG,EAAE;QAAE,GAAG,EAAE,CAAC,IAAI,EAAE;YAAE,IAAI,EAAE;gBAAE,OAAO,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,CAAA;CAAE,EAC5I,OAAO,EAAE,kBAAkB,uBA0B5B"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAgGjD,QAAA,MAAM,MAAM,EAAE,MAqTb,CAAA;AAED,eAAe,MAAM,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAgGjD,QAAA,MAAM,MAAM,EAAE,MAkVb,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/index.js

@@ -2553,6 +2553,9 @@ var COMPLETION_COMMANDS = new Set([
   "execute",
   "verify"
 ]);
+function normalizeCommandName(raw) {
+  return raw.replace(/^\//, "").replace(/^fd-/, "");
+}
 function notify(title, body, level = "info") {
   const platform = process.platform;
   try {
@@ -2584,16 +2587,80 @@ function tryTerminalBell() {
     process.stdout.write("\x07");
   } catch {}
 }
-function notifyCommandInteraction(command) {
-  const name = command.replace(/^\//, "").replace(/^fd-/, "");
-  if (INTERACTIVE_COMMANDS.has(name)) {
-    notify(`FlowDeck: /${name}`, "Your input is needed — please check OpenCode", "critical");
-  } else if (COMPLETION_COMMANDS.has(name)) {
-    notify(`FlowDeck: /${name} complete`, "Review the output and choose your next step", "info");
+
+class NotificationController {
+  pendingCommand = null;
+  lastNotifiedKey = null;
+  notifyFn;
+  log;
+  constructor(notifyFn = notify, log = () => {}) {
+    this.notifyFn = notifyFn;
+    this.log = log;
+  }
+  onCommandExecuted(rawCommand) {
+    const name = normalizeCommandName(rawCommand);
+    if (!INTERACTIVE_COMMANDS.has(name) && !COMPLETION_COMMANDS.has(name)) {
+      this.log(`[notify] command.executed: "${name}" — not a tracked command, skipping`);
+      return;
+    }
+    this.log(`[notify] command.executed: "${name}" recorded as pending`);
+    this.pendingCommand = name;
+    this.lastNotifiedKey = null;
+  }
+  onSessionIdle(hasEdits) {
+    if (this.pendingCommand) {
+      const name = this.pendingCommand;
+      const dedupeKey = `idle:${name}`;
+      if (this.lastNotifiedKey === dedupeKey) {
+        this.log(`[notify] suppressed duplicate: state=session.idle command=${name}`);
+        return;
+      }
+      const reason = INTERACTIVE_COMMANDS.has(name) ? "input_required" : "completed";
+      this.log(`[notify] firing notification: reason=${reason} command=${name} source=session.idle`);
+      if (reason === "input_required") {
+        this.notifyFn(`FlowDeck: /${name}`, "Your input is needed — please check OpenCode", "critical");
+      } else {
+        this.notifyFn(`FlowDeck: /${name} complete`, "Review the output and choose your next step", "info");
+      }
+      this.lastNotifiedKey = dedupeKey;
+      this.pendingCommand = null;
+      return;
+    }
+    if (hasEdits) {
+      const dedupeKey = "idle:generic";
+      if (this.lastNotifiedKey === dedupeKey) {
+        this.log(`[notify] suppressed duplicate: state=session.idle source=generic`);
+        return;
+      }
+      this.log(`[notify] firing notification: reason=completed source=session.idle (generic, has edits)`);
+      this.notifyFn("FlowDeck Task Completed", "Agent is idle and waiting for your next instruction", "info");
+      this.lastNotifiedKey = dedupeKey;
+    } else {
+      this.log(`[notify] session.idle — no pending command, no edits — suppressed`);
+    }
+  }
+  onSessionError(errorMsg) {
+    const snippet = errorMsg.slice(0, 60);
+    const dedupeKey = `error:${snippet}`;
+    if (this.lastNotifiedKey === dedupeKey) {
+      this.log(`[notify] suppressed duplicate: state=session.error`);
+      return;
+    }
+    this.log(`[notify] firing notification: reason=error source=session.error`);
+    this.notifyFn("FlowDeck Error", snippet || "An error occurred", "critical");
+    this.lastNotifiedKey = dedupeKey;
+    this.pendingCommand = null;
+  }
+  reset() {
+    this.pendingCommand = null;
+    this.lastNotifiedKey = null;
+  }
+  getPendingCommand() {
+    return this.pendingCommand;
+  }
+  getLastNotifiedKey() {
+    return this.lastNotifiedKey;
   }
-}
-function notifySessionIdle() {
-  notify("FlowDeck Task Completed", "Agent is idle and waiting for your next instruction", "info");
 }
 function notifyPermissionNeeded(tool17) {
   notify("FlowDeck Permission Required", `Agent needs approval to use tool: ${tool17}`, "critical");
@@ -3097,7 +3164,6 @@ function createSessionIdleHook(client, tracker) {
       const edited = tracker.getEditedPaths();
       if (edited.length === 0)
         return;
-      notifySessionIdle();
       const summary = `[FlowDeck] Session idle — ${edited.length} file(s) modified this session`;
       await client.app.log({ body: { service: "flowdeck", level: "info", message: summary } }).catch(() => {});
       const preview = edited.slice(0, 10);
@@ -7223,6 +7289,7 @@ var plugin = async (input, _options) => {
   const orchestratorGuard = new OrchestratorGuard;
   const appLog = (msg) => client.app.log({ body: { service: "flowdeck", level: "info", message: msg } }).catch(() => {});
   const autoLearnHook = createAutoLearnHook(client, fileTracker, directory, appLog);
+  const notifCtrl = new NotificationController(undefined, appLog);
   const agentConfigs = getAgentConfigs({});
   const mcps = createFlowDeckMcps();
   return {
@@ -7323,9 +7390,7 @@ var plugin = async (input, _options) => {
     "file.edited": fileEdited,
     "file.watcher.updated": fileWatcherUpdated,
     "experimental.session.compacting": compactionHook,
-    "command.execute.before": async (input2, _output) => {
-      notifyCommandInteraction(input2.command);
-    },
+    "command.execute.before": async (_input, _output) => {},
     "permission.ask": async (input2, _output) => {
       notifyPermissionNeeded(input2.title);
     },
@@ -7334,9 +7399,17 @@ var plugin = async (input, _options) => {
       if (type === "session.created" || type === "session.started") {
         await sessionStartHook({ directory });
       }
+      if (type === "command.executed") {
+        const commandName = event?.properties?.name ?? "";
+        if (commandName) {
+          notifCtrl.onCommandExecuted(commandName);
+        }
+      }
       await contextMonitor.event({ event });
       orchestratorGuard.onEvent(event);
       if (type === "session.idle") {
+        const hasEdits = fileTracker.getEditedPaths().length > 0;
+        notifCtrl.onSessionIdle(hasEdits);
         try {
           await sessionIdleHook();
           await autoLearnHook();
@@ -7344,6 +7417,11 @@ var plugin = async (input, _options) => {
           fileTracker.clear();
         }
       }
+      if (type === "session.error") {
+        const err = event?.properties?.error;
+        const errorMsg = (err && typeof err === "object" && "message" in err ? String(err.message) : undefined) ?? (typeof err === "string" ? err : undefined) ?? "An unexpected error occurred";
+        notifCtrl.onSessionError(errorMsg);
+      }
     },
     "tool.execute.before": async (toolInput, toolOutput) => {
       if ((toolInput.tool === "read" || toolInput.tool === "view") && toolOutput?.args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",