pi-usereq 0.84.0 → 0.85.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.84.0)
+# PI-useReq/pi-usereq (0.85.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.84.0",
+  "version": "0.85.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/notification-replay.ts

@@ -0,0 +1,112 @@
+/**
+ * @file
+ * @brief Persists deferred UI notifications across session rebinding for later replay.
+ * @details Stores non-agentic command-output notifications whose stale-context-safe delivery failed on one `globalThis` queue because pi rebinds extension modules for `/new`, `/resume`, `/fork`, and `/reload` while the hosting process persists across those operations, so undeliverable payloads survive until a later `session_start` restores a live UI context. Runtime is O(1) per operation. Side effects are limited to process-scoped state mutation; no local or global configuration file is ever written.
+ */
+
+/**
+ * @brief Enumerates the `session_start` reasons that trigger deferred-notification replay.
+ * @details Covers the session-restoration boundaries where pi rebuilt the TUI and invalidated prior UI contexts: `new`, `resume`, `reload`, and `fork`. The `startup` reason starts one fresh host process whose process-scoped queue is empty by construction, so it is excluded from replay. Lookup complexity is O(1).
+ */
+const DEFERRED_NOTIFICATION_REPLAY_SESSION_START_REASONS = new Set([
+  "new",
+  "resume",
+  "reload",
+  "fork",
+]);
+
+/**
+ * @brief Describes one deferred notification queued for later replay.
+ * @details Pairs the exact notification message text with its original severity so the replayed delivery preserves the deferred payload without reparsing or reconstruction. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface DeferredNotificationRecord {
+  message: string;
+  level: "info" | "error";
+}
+
+/**
+ * @brief Defines the global property used for deferred-notification replay persistence.
+ * @details The property lives on `globalThis` because pi tears down and reloads extension modules on session switches while the host process persists, so the queue survives `/new`, `/resume`, `/fork`, `/reload`, and `req-reset` session restoration. Access complexity is O(1).
+ */
+const PI_USEREQ_NOTIFICATION_REPLAY_KEY = "__piUsereqDeferredNotificationReplay";
+
+/**
+ * @brief Describes the process-scoped deferred-notification replay state persisted across extension rebinds.
+ * @details Stores the ordered queue of undelivered notification payloads so a later `session_start` on one restored UI context can redeliver exactly the evidence that stale contexts dropped. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-439
+ */
+interface ProcessScopedNotificationReplayStore {
+  queue: DeferredNotificationRecord[];
+}
+
+/**
+ * @brief Returns the process-scoped deferred-notification replay store.
+ * @details Lazily initializes one `globalThis` record holding an empty queue so session rebinds reuse the accumulated deferred payloads instead of resetting them. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {ProcessScopedNotificationReplayStore} Mutable process-scoped replay store.
+ * @satisfies REQ-439
+ */
+function getProcessScopedNotificationReplayStore(): ProcessScopedNotificationReplayStore {
+  const globalState = globalThis as typeof globalThis & {
+    __piUsereqDeferredNotificationReplay?: ProcessScopedNotificationReplayStore;
+  };
+  globalState[PI_USEREQ_NOTIFICATION_REPLAY_KEY] ??= { queue: [] };
+  return globalState[PI_USEREQ_NOTIFICATION_REPLAY_KEY]!;
+}
+
+/**
+ * @brief Queues one undeliverable notification for later replay.
+ * @details Appends the exact message plus severity to the tail of the process-scoped replay queue so the payload survives extension rebinding and can be redelivered on the next eligible `session_start`. Already-delivered notifications are never enqueued by contract, so replay can never duplicate them. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @param[in] message {string} Exact notification message text whose stale-context delivery failed.
+ * @param[in] level {"info" | "error"} Original notification severity preserved for the replayed delivery.
+ * @return {void} No return value.
+ * @satisfies REQ-439, REQ-442
+ */
+export function enqueueDeferredNotification(message: string, level: "info" | "error"): void {
+  getProcessScopedNotificationReplayStore().queue.push({ message, level });
+}
+
+/**
+ * @brief Returns a snapshot of the queued deferred notifications.
+ * @details Copies the queued records into one detached array so callers can inspect pending replay payloads without mutating the store. Runtime is O(n) in queued-record count. No external state is mutated.
+ * @return {DeferredNotificationRecord[]} Detached copy of the queued records in enqueue order.
+ * @satisfies REQ-439
+ */
+export function readDeferredNotifications(): DeferredNotificationRecord[] {
+  return [...getProcessScopedNotificationReplayStore().queue];
+}
+
+/**
+ * @brief Atomically removes and returns every queued deferred notification.
+ * @details Empties the process-scoped queue and returns the removed records in enqueue order so replay delivery owns each payload exactly once; payloads whose replay delivery fails stale again are re-enqueued by the deferred-delivery helper instead of remaining in this drain result. Runtime is O(n) in queued-record count. Side effect: clears process-scoped state.
+ * @return {DeferredNotificationRecord[]} Removed records in enqueue order.
+ * @satisfies REQ-440
+ */
+export function drainDeferredNotifications(): DeferredNotificationRecord[] {
+  const store = getProcessScopedNotificationReplayStore();
+  const drained = store.queue;
+  store.queue = [];
+  return drained;
+}
+
+/**
+ * @brief Clears every queued deferred notification.
+ * @details Resets the process-scoped queue to empty so stale deferred payloads never reach later sessions after explicit cleanup. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @return {void} No return value.
+ * @satisfies REQ-439
+ */
+export function clearDeferredNotifications(): void {
+  getProcessScopedNotificationReplayStore().queue = [];
+}
+
+/**
+ * @brief Tests whether one `session_start` event must trigger deferred-notification replay.
+ * @details Reads the loosely-typed `reason` field from the session-start payload and accepts exactly the documented restoration reasons `new`, `resume`, `reload`, and `fork`, excluding `startup` because one fresh host process starts with an empty process-scoped queue. Missing or unknown reasons degrade to `false`. Runtime is O(1). No external state is mutated.
+ * @param[in] event {unknown} Session-start payload forwarded by the pi lifecycle wrapper.
+ * @return {boolean} `true` when deferred notifications must be replayed for this session-start reason.
+ * @satisfies REQ-440
+ */
+export function shouldReplayDeferredNotificationsOnSessionStart(event: unknown): boolean {
+  const reason = (event as { reason?: unknown } | undefined)?.reason;
+  return typeof reason === "string"
+    && DEFERRED_NOTIFICATION_REPLAY_SESSION_START_REASONS.has(reason);
+}

package/src/index.ts

@@ -168,6 +168,11 @@ import {
   writePersistedPromptCommandRuntimeState,
   type PersistedPromptCommandRuntimeApi,
 } from "./core/prompt-command-state.js";
+import {
+  drainDeferredNotifications,
+  enqueueDeferredNotification,
+  shouldReplayDeferredNotificationsOnSessionStart,
+} from "./core/notification-replay.js";
 import { ensureBundledResourcesAccessible, readBundledPromptDescription } from "./core/resources.js";
 import { ReqError } from "./core/errors.js";
 import {
@@ -1199,13 +1204,13 @@ function resolveDebugProjectBase(cwd: string, statusController: PiUsereqStatusCo
 }
 
 /**
- * @brief Delivers one best-effort UI notification without failing on stale replacement contexts.
- * @details Attempts to use the supplied extension context for UI notification delivery and suppresses the documented stale-extension-context runtime error raised after session replacement, because prompt-orchestration closure can outlive the context that initiated the switch. Runtime is O(n) in message length. Side effects are limited to user notification delivery when the context is still active.
+ * @brief Delivers one best-effort UI notification, deferring the payload when the context is stale.
+ * @details Attempts to use the supplied extension context for UI notification delivery; when no context is available or pi raises the documented stale-extension-context error because the context was invalidated by session replacement or reload, the exact message plus severity is enqueued into the process-scoped deferred-notification replay store so one later eligible `session_start` can redeliver it on the restored context instead of losing the evidence. The payload is enqueued only on failed delivery, so already-delivered notifications are never replayed. Runtime is O(1). Side effects are limited to user notification delivery when the context is still active and process-scoped queue mutation when delivery fails.
  * @param[in] ctx {ExtensionContext | ExtensionCommandContext | undefined} Candidate UI context.
  * @param[in] message {string} Notification message.
  * @param[in] level {"info" | "error"} Notification severity.
- * @return {boolean} `true` when the notification was delivered and `false` when the context was already stale.
- * @satisfies REQ-280
+ * @return {boolean} `true` when the notification was delivered and `false` when delivery failed and the payload was deferred for replay.
+ * @satisfies REQ-280, REQ-439, REQ-442
  */
 function notifyContextSafely(
   ctx: (ExtensionContext | ExtensionCommandContext) | undefined,
@@ -1213,6 +1218,7 @@ function notifyContextSafely(
   level: "info" | "error",
 ): boolean {
   if (ctx === undefined) {
+    enqueueDeferredNotification(message, level);
     return false;
   }
   try {
@@ -1220,6 +1226,7 @@ function notifyContextSafely(
     return true;
   } catch (error) {
     if (isStaleExtensionContextError(error)) {
+      enqueueDeferredNotification(message, level);
       return false;
     }
     throw error;
@@ -1232,7 +1239,7 @@ function notifyContextSafely(
  * @param[in] statusController {PiUsereqStatusController} Mutable status controller supplying the latest normalized context-usage snapshot.
  * @param[in] ctx {(ExtensionContext | ExtensionCommandContext) | undefined} Candidate UI context for notification delivery.
  * @return {void} No return value.
- * @satisfies REQ-360, REQ-361, REQ-362, REQ-363, REQ-364, REQ-365
+ * @satisfies REQ-360, REQ-361, REQ-362, REQ-363, REQ-364, REQ-365, REQ-439, REQ-441
  */
 function notifyContextRetentionReminder(
   statusController: PiUsereqStatusController,
@@ -1494,7 +1501,7 @@ async function finalizeMatchedPromptSuccess(
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {Promise<void>} Promise resolved when hook processing completes.
- * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292, REQ-421, REQ-422, REQ-425
+ * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292, REQ-421, REQ-422, REQ-425, REQ-440
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -1529,6 +1536,12 @@ async function handleExtensionStatusEvent(
         "warning",
       );
     }
+    if (shouldReplayDeferredNotificationsOnSessionStart(event)) {
+      const deferredNotifications = drainDeferredNotifications();
+      for (const deferredNotification of deferredNotifications) {
+        notifyContextSafely(ctx, deferredNotification.message, deferredNotification.level);
+      }
+    }
   }
   if (hookName === "before_agent_start") {
     const requestForActivation = activePromptRequest ?? pendingPromptRequest;
@@ -3409,7 +3422,7 @@ function resolveReqResetPromptRequest(
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313
+ * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313, REQ-441
  */
 function registerReqResetCommand(
   pi: ExtensionAPI,
@@ -3484,7 +3497,7 @@ function registerReqResetCommand(
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-437, REQ-438
+ * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-437, REQ-438, REQ-441
  */
 function registerReqReferencesCommand(
   pi: ExtensionAPI,
@@ -3513,19 +3526,22 @@ function registerReqReferencesCommand(
         const executionResult = executeReqReferencesCommandExecution(executionPlan, config);
         setPiUsereqWorkflowState(statusController, "idle", ctx);
         const referencesDisplayPath = formatRuntimePathForDisplay(executionResult.referencesPath);
-        ctx.ui.notify(
+        notifyContextSafely(
+          ctx,
           executionResult.referencesChanged
             ? `req-references: Updated ${referencesDisplayPath}.`
             : `req-references: ${referencesDisplayPath} already matches the generated references content; no file update was needed.`,
           "info",
         );
-        ctx.ui.notify(
+        notifyContextSafely(
+          ctx,
           executionResult.commitCreated
             ? `req-references: Created commit ${executionResult.commitMessage}`
             : "req-references: Skipped the git commit because the references content already matched HEAD.",
           "info",
         );
-        ctx.ui.notify(
+        notifyContextSafely(
+          ctx,
           executionResult.referencesChanged && executionResult.commitCreated
             ? `SUCCESS: Updated ${referencesDisplayPath} and committed changes.`
             : `SUCCESS: req-references completed with a clean repository (${executionResult.referencesChanged ? "references updated" : "references unchanged"}; ${executionResult.commitCreated ? "commit created" : "commit skipped"}).`,
@@ -3537,7 +3553,7 @@ function registerReqReferencesCommand(
         statusController.state.activePromptRequest = undefined;
         setPiUsereqWorkflowState(statusController, "error", ctx);
         const message = error instanceof Error ? error.message : String(error);
-        ctx.ui.notify(message, "error");
+        notifyContextSafely(ctx, message, "error");
         throw error;
       }
     },