pi-usereq 0.87.0 → 0.89.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.87.0)
+# PI-useReq/pi-usereq (0.89.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.87.0",
+  "version": "0.89.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/command-report-entry.ts

@@ -126,6 +126,20 @@ export function buildCommandReportErrorEntryData(
   };
 }
 
+/**
+ * @brief Serializes one durable command report entry into its complete plain-text form.
+ * @details Joins the `pi-usereq <command>: execution report` header with every per-operation outcome line using newline separators so notification `%%OUTPUT%%` substitution carries exactly the report content rendered in the transcript. Runtime is O(n) in aggregate report-line length. No external state is mutated.
+ * @param[in] data {CommandReportEntryData} Report entry payload to serialize.
+ * @return {string} Complete execution-report text starting with the report header.
+ * @satisfies REQ-436, REQ-448
+ */
+export function buildCommandReportEntryText(data: CommandReportEntryData): string {
+  return [
+    `pi-usereq ${data.command}: execution report`,
+    ...data.lines,
+  ].join("\n");
+}
+
 /**
  * @brief Appends one durable command report entry to the active session when the host supports custom entries.
  * @details Probes the optional `pi.appendEntry(...)` surface before use so legacy hosts and offline harnesses without custom-entry support skip persistence silently; supported hosts persist the payload as a `custom` session entry that survives session restore while remaining excluded from LLM context. Runtime is O(1) plus delegated session-entry persistence. Side effects include session-file entry persistence on supported hosts.

package/src/core/pi-notify.ts

@@ -80,10 +80,10 @@ export const DEFAULT_PI_NOTIFY_PUSHOVER_TITLE = "%%PROMT%% @ %%BASE%% [%%TIME%%]
 
 /**
  * @brief Defines the default Pushover text template.
- * @details Prefixes outbound Pushover messages with the terminal outcome token and preserves the raw prompt arguments on the following line so notifications remain traceable to the invoked prompt command. Access complexity is O(1).
- * @satisfies REQ-185
+ * @details Delivers the final LLM agent output as the outbound Pushover message body so completed prompt runs push the last assistant message instead of the invoked command arguments; `buildPiNotifyPushoverBody` falls back to the terminal outcome token when the substituted body resolves empty. Access complexity is O(1).
+ * @satisfies REQ-185, REQ-450
  */
-export const DEFAULT_PI_NOTIFY_PUSHOVER_TEXT = "%%RESULT%%\n%%ARGS%%";
+export const DEFAULT_PI_NOTIFY_PUSHOVER_TEXT = "%%OUTPUT%%";
 
 /**
  * @brief Defines the Pushover Message API `message` field limit in characters.
@@ -801,21 +801,23 @@ function truncatePiNotifyPushoverBody(body: string): string {
 
 /**
  * @brief Builds the Pushover message body for one prompt-end request.
- * @details Resolves the configured `notify-pushover-text` template with raw runtime placeholder substitution so the pushed text remains configurable and deterministic, then head-truncates over-limit bodies to the Pushover Message API `message` limit. Runtime is O(n) in template length. No external state is mutated.
+ * @details Resolves the configured `notify-pushover-text` template with raw runtime placeholder substitution, falls back to the terminal outcome token when the fully substituted body resolves empty so Pushover delivery never targets an empty `message` field, then head-truncates over-limit bodies to the Pushover Message API `message` limit. Runtime is O(n) in template length. No external state is mutated.
  * @param[in] config {PiNotifyConfigFields} Effective notification configuration.
  * @param[in] outcome {PiNotifyOutcome} Classified prompt-end outcome.
  * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata.
  * @return {string} Pushover message body within the 1024-character API limit.
- * @satisfies REQ-185, REQ-186, REQ-187, REQ-199, REQ-443, REQ-444, REQ-445
+ * @satisfies REQ-185, REQ-186, REQ-187, REQ-199, REQ-443, REQ-444, REQ-445, REQ-450
  */
 function buildPiNotifyPushoverBody(
   config: PiNotifyConfigFields,
   outcome: PiNotifyOutcome,
   request: PiNotifyEventRequest,
 ): string {
-  return truncatePiNotifyPushoverBody(
-    substitutePiNotifyTextTemplate(config["notify-pushover-text"], request, outcome),
-  );
+  const substitutedBody = substitutePiNotifyTextTemplate(config["notify-pushover-text"], request, outcome);
+  const resolvedBody = substitutedBody.trim().length > 0
+    ? substitutedBody
+    : formatPiNotifyResult(outcome);
+  return truncatePiNotifyPushoverBody(resolvedBody);
 }
 
 /**
@@ -893,7 +895,7 @@ export function setPiNotifySpawnForTests(spawnImpl: PiNotifySpawn | undefined):
 
 /**
  * @brief Dispatches prompt-end notify, sound, and Pushover effects for one agent-end payload.
- * @details Classifies the terminal outcome, executes `PI_NOTIFY_CMD` when command-notify prerequisites are satisfied, executes the configured sound command when sound prerequisites are satisfied, and dispatches the native Pushover request when Pushover prerequisites are satisfied; `%%OUTPUT%%` resolves from the caller-supplied final agent output and Pushover bodies are head-truncated to the provider message limit. Runtime is O(m + c + b) in message count, command length, and Pushover payload size. Side effects include child-process spawning and outbound HTTPS requests.
+ * @details Classifies the terminal outcome from the `agent_end` payload and delegates to `runPiNotifyEffectsForOutcome(...)`; `%%OUTPUT%%` resolves from the caller-supplied final agent output and Pushover bodies are head-truncated to the provider message limit. Runtime is O(m + c + b) in message count, command length, and Pushover payload size. Side effects include child-process spawning and outbound HTTPS requests.
  * @param[in] config {PiNotifyConfigFields} Effective notification configuration.
  * @param[in] event {Pick<AgentEndEvent, "messages">} Agent-end payload subset.
  * @param[in] request {PiNotifyEventRequest | undefined} Optional prompt-end request metadata used for command-notify and Pushover substitution.
@@ -905,7 +907,23 @@ export function runPiNotifyEffects(
   event: Pick<AgentEndEvent, "messages">,
   request?: PiNotifyEventRequest,
 ): void {
-  const outcome = classifyPiNotifyOutcome(event);
+  runPiNotifyEffectsForOutcome(config, classifyPiNotifyOutcome(event), request);
+}
+
+/**
+ * @brief Dispatches prompt-end notify, sound, and Pushover effects for one explicit prompt-end outcome.
+ * @details Executes `PI_NOTIFY_CMD` when command-notify prerequisites are satisfied, executes the configured sound command when sound prerequisites are satisfied, and dispatches the native Pushover request when Pushover prerequisites are satisfied; `%%OUTPUT%%` resolves from the caller-supplied final agent output or command process output, and Pushover bodies head-truncate to the provider message limit with an outcome-token fallback for empty bodies. Agentic callers classify the outcome from the `agent_end` payload through `runPiNotifyEffects(...)`; non-agentic `req-references` and `req-reset` command callers pass the explicit completed or failed outcome per REQ-447. Runtime is O(c + b) in command length and Pushover payload size. Side effects include child-process spawning and outbound HTTPS requests.
+ * @param[in] config {PiNotifyConfigFields} Effective notification configuration.
+ * @param[in] outcome {PiNotifyOutcome} Explicit prompt-end outcome.
+ * @param[in] request {PiNotifyEventRequest | undefined} Optional prompt-end request metadata used for command-notify and Pushover substitution.
+ * @return {void} No return value.
+ * @satisfies 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-199, REQ-443, REQ-444, REQ-445, REQ-447, REQ-450
+ */
+export function runPiNotifyEffectsForOutcome(
+  config: PiNotifyConfigFields,
+  outcome: PiNotifyOutcome,
+  request?: PiNotifyEventRequest,
+): void {
   if (shouldRunPiNotifyCommand(config, outcome, request)) {
     runPiNotifyCommand(config, outcome, request as PiNotifyEventRequest);
   }

package/src/core/req-reset-command.ts

@@ -59,6 +59,29 @@ export interface ReqResetCommandExecutionResult {
   errorMessage?: string;
 }
 
+/**
+ * @brief Builds the per-operation outcome lines of one `req-reset` run for `%%OUTPUT%%` notification substitution.
+ * @details Emits one machine-readable line per recovery or cleanup fact — terminal outcome, execution-transcript preservation, `base-path` restoration, removed generated worktree count, removed generated branch count — and appends the surfaced error diagnostic for failed runs so prompt-end notification effects carry exactly the output produced during the process. Runtime is O(1). No external state is mutated.
+ * @param[in] executionResult {ReqResetCommandExecutionResult} Recovery and cleanup outcome facts of the attempted run.
+ * @return {string[]} Ordered outcome lines starting with the terminal outcome.
+ * @satisfies REQ-449
+ */
+export function buildReqResetCommandOutcomeLines(
+  executionResult: ReqResetCommandExecutionResult,
+): string[] {
+  const lines = [
+    `outcome: ${executionResult.errorMessage ? "error" : "success"}`,
+    `transcript preserved: ${executionResult.transcriptPreserved ? "yes" : "no"}`,
+    `base-path restored: ${executionResult.restoredBasePath ? "yes" : "no"}`,
+    `worktrees removed: ${executionResult.removedWorktreeDirs.length}`,
+    `branches removed: ${executionResult.removedBranchNames.length}`,
+  ];
+  if (executionResult.errorMessage) {
+    lines.push(`error: ${executionResult.errorMessage}`);
+  }
+  return lines;
+}
+
 /**
  * @brief Describes the session-bound context surface reused during `req-reset` recovery.
  * @details Reuses the session-switching contract already accepted by `restorePromptCommandExecution(...)` so the dedicated reset command can restore the original session without depending on concrete pi runtime classes. The alias is compile-time only and introduces no runtime cost.

package/src/index.ts

@@ -61,7 +61,9 @@ import {
   normalizePiNotifyTemplateValue,
   parsePiNotifyControlSequenceText,
   runPiNotifyEffects,
+  runPiNotifyEffectsForOutcome,
   type PiNotifyEventRequest,
+  type PiNotifyOutcome,
   type PiNotifyPushoverPriority,
   type PiNotifySoundLevel,
 } from "./core/pi-notify.js";
@@ -118,6 +120,7 @@ import {
 } from "./core/req-references-command.js";
 import {
   REQ_RESET_COMMAND_DESCRIPTION,
+  buildReqResetCommandOutcomeLines,
   executeReqResetCommandExecution,
   prepareReqResetCommandExecution,
   type ReqResetCommandExecutionResult,
@@ -176,6 +179,7 @@ import {
 import { ensureBundledResourcesAccessible, readBundledPromptDescription } from "./core/resources.js";
 import {
   appendCommandReportEntry,
+  buildCommandReportEntryText,
   buildCommandReportErrorEntryData,
   buildReqReferencesCommandReportEntryData,
   registerCommandReportEntryRenderer,
@@ -1239,6 +1243,32 @@ function notifyContextSafely(
   }
 }
 
+/**
+ * @brief Dispatches prompt-end notification effects for one non-agentic command outcome.
+ * @details Builds the effective notification configuration subset with the active runtime sound level and forwards the explicit completed or failed outcome plus the command-produced process output into `runPiNotifyEffectsForOutcome(...)`, so `req-references` and `req-reset` completions feed the same command-notify, sound, and Pushover gates as `agent_end` runs. Runtime is O(1) plus delegated effect cost. Side effects include optional child-process spawning and outbound HTTPS requests.
+ * @param[in] statusController {PiUsereqStatusController} Mutable status controller supplying the active runtime sound level.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] outcome {PiNotifyOutcome} Explicit terminal command outcome.
+ * @param[in] request {PiNotifyEventRequest} Prompt-end request metadata carrying the command process output.
+ * @return {void} No return value.
+ * @satisfies REQ-447, REQ-448, REQ-449
+ */
+function dispatchNonAgenticCommandNotifyEffects(
+  statusController: PiUsereqStatusController,
+  config: UseReqConfig,
+  outcome: PiNotifyOutcome,
+  request: PiNotifyEventRequest,
+): void {
+  runPiNotifyEffectsForOutcome(
+    {
+      ...config,
+      "notify-sound": getPiUsereqRuntimeSoundLevel(statusController),
+    },
+    outcome,
+    request,
+  );
+}
+
 /**
  * @brief Emits the final context-retention reminder info notification for a successfully completed `/req-*` orchestration.
  * @details Builds one message stating that the session context content was retained, recommending a clean-context session start before the next `/req-*` command, and appending the current context-usage percentage when the controller holds a normalized snapshot. Delivers exclusively through `notifyContextSafely(...)`, so stale replacement-session contexts are suppressed, and performs no session message send and no session switch. Runtime is O(1). Side effect is user notification delivery only when the supplied context is still active.
@@ -3459,11 +3489,11 @@ function resolveReqResetPromptRequest(
 
 /**
  * @brief Registers the specialized `req-reset` slash command.
- * @details Registers the non-agentic prompt-recovery command that accepts any current workflow state, reuses persisted prompt runtime state when available, restores the original session-backed `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by session restoration plus git cleanup. Side effects include command registration, status-controller mutation, active-session replacement, worktree deletion, branch deletion, and user notifications.
+ * @details Registers the non-agentic prompt-recovery command that accepts any current workflow state, reuses persisted prompt runtime state when available, restores the original session-backed `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, notifies pi without starting an LLM session or creating a worktree, and dispatches prompt-end notification effects carrying the command process output as `%%OUTPUT%%`. Runtime is dominated by session restoration plus git cleanup. Side effects include command registration, status-controller mutation, active-session replacement, worktree deletion, branch deletion, user notifications, and optional prompt-end notify, sound, and Pushover dispatch.
  * @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, REQ-441
+ * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313, REQ-441, REQ-447, REQ-449
  */
 function registerReqResetCommand(
   pi: ExtensionAPI,
@@ -3471,7 +3501,8 @@ function registerReqResetCommand(
 ): void {
   pi.registerCommand("req-reset", {
     description: REQ_RESET_COMMAND_DESCRIPTION,
-    handler: async (_args, ctx) => {
+    handler: async (args, ctx) => {
+      const commandStartMs = Date.now();
       const promptRequest = resolveReqResetPromptRequest(statusController);
       const resetModelSelection = promptRequest?.originalModel
         ?? resolveCurrentModelSelection((ctx as unknown as PromptModelSelectionContextSurface).model);
@@ -3505,6 +3536,13 @@ function registerReqResetCommand(
         const message = error instanceof Error ? error.message : String(error);
         setPiUsereqWorkflowState(statusController, "error", resetContext);
         notifyContextSafely(resetContext, message, "error");
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "failed", {
+          promptName: "req-reset",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: message,
+        });
         throw error;
       }
 
@@ -3519,6 +3557,13 @@ function registerReqResetCommand(
       if (executionResult.errorMessage) {
         setPiUsereqWorkflowState(statusController, "error", resetContext);
         notifyContextSafely(resetContext, executionResult.errorMessage, "error");
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "failed", {
+          promptName: "req-reset",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: buildReqResetCommandOutcomeLines(executionResult).join("\n"),
+        });
         throw new ReqError(executionResult.errorMessage, 1);
       }
 
@@ -3527,6 +3572,13 @@ function registerReqResetCommand(
         ? `SUCCESS: req-reset restored base-path and removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es).`
         : `SUCCESS: req-reset removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es) and restored idle state.`;
       notifyContextSafely(resetContext, successMessage, "info");
+      dispatchNonAgenticCommandNotifyEffects(statusController, config, "completed", {
+        promptName: "req-reset",
+        promptArgs: args,
+        basePath: projectBase,
+        completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+        agentOutput: buildReqResetCommandOutcomeLines(executionResult).join("\n"),
+      });
       notifyContextRetentionReminder(statusController, resetContext);
     },
   });
@@ -3534,11 +3586,11 @@ function registerReqResetCommand(
 
 /**
  * @brief Registers the specialized `req-references` slash command.
- * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, appends one durable `pi-usereq.command-report` session entry recording the executed operations with their outcomes so the report renders in the transcript and survives session restore, and emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, session-entry persistence, and user notifications.
+ * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, appends one durable `pi-usereq.command-report` session entry recording the executed operations with their outcomes so the report renders in the transcript and survives session restore, emits execution notifications that conform to the operations actually performed — one stating whether the references file was updated or already matched the generated content and one stating whether the fixed-message commit was created or skipped — regardless of the update and commit outcomes, dispatches prompt-end notification effects carrying the complete execution-report text (header plus per-operation outcome lines) as `%%OUTPUT%%` for completed and failed runs, all without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, session-entry persistence, user notifications, and optional prompt-end notify, sound, and Pushover dispatch.
  * @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-436, REQ-437, REQ-438, REQ-441
+ * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-436, REQ-437, REQ-438, REQ-441, REQ-447, REQ-448
  */
 function registerReqReferencesCommand(
   pi: ExtensionAPI,
@@ -3546,7 +3598,8 @@ function registerReqReferencesCommand(
 ): void {
   pi.registerCommand("req-references", {
     description: REQ_REFERENCES_COMMAND_DESCRIPTION,
-    handler: async (_args, ctx) => {
+    handler: async (args, ctx) => {
+      const commandStartMs = Date.now();
       if (statusController.state.workflowState !== "idle") {
         rejectNonIdleReqCommand(statusController, ctx);
       }
@@ -3589,6 +3642,13 @@ function registerReqReferencesCommand(
             : `SUCCESS: req-references completed with a clean repository (${executionResult.referencesChanged ? "references updated" : "references unchanged"}; ${executionResult.commitCreated ? "commit created" : "commit skipped"}).`,
           "info",
         );
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "completed", {
+          promptName: "req-references",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: buildCommandReportEntryText(buildReqReferencesCommandReportEntryData(executionResult)),
+        });
         notifyContextRetentionReminder(statusController, ctx);
       } catch (error) {
         statusController.state.pendingPromptRequest = undefined;
@@ -3597,6 +3657,13 @@ function registerReqReferencesCommand(
         const message = error instanceof Error ? error.message : String(error);
         appendCommandReportEntry(pi, buildCommandReportErrorEntryData("req-references", message));
         notifyContextSafely(ctx, message, "error");
+        dispatchNonAgenticCommandNotifyEffects(statusController, config, "failed", {
+          promptName: "req-references",
+          promptArgs: args,
+          basePath: projectBase,
+          completionTimeMs: Math.max(0, Date.now() - commandStartMs),
+          agentOutput: buildCommandReportEntryText(buildCommandReportErrorEntryData("req-references", message)),
+        });
         throw error;
       }
     },