pi-usereq 0.61.0 → 0.63.0

package/README.md

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

package/src/core/prompt-command-state.ts

@@ -209,3 +209,49 @@ export function restorePersistedPromptCommandRuntimeStateForSession(
   }
   return undefined;
 }
+
+/**
+ * @brief Describes the loosely-typed extension-api surface persisted for model re-application.
+ * @details Stores only the session-scoped model appliers plus thinking-level probe needed to re-apply one captured selection after session replacement. The structural shape avoids importing concrete pi SDK types into this process-scoped module. The interface is compile-time only and introduces no runtime cost.
+ * @satisfies REQ-367, REQ-368, REQ-369
+ */
+export interface PersistedPromptCommandRuntimeApi {
+  setModel?: (model: unknown) => unknown;
+  setThinkingLevel?: (level: unknown) => unknown;
+  getThinkingLevel?: () => unknown;
+}
+
+/**
+ * @brief Defines the global property used for latest live extension-api persistence.
+ * @details The property lives on `globalThis` because pi invalidates the extension api captured by one session's extension instance whenever that session is replaced and reloads the extension against the replacement session while the host process persists. Access complexity is O(1).
+ */
+const PI_USEREQ_PROMPT_COMMAND_RUNTIME_API_KEY = "__piUsereqPromptCommandRuntimeApi";
+
+/**
+ * @brief Writes the latest live extension api into process-scoped persistence.
+ * @details Replaces the stored loosely-typed model-api surface so model re-application helpers always bind to the extension instance of the currently active session runner and never to an api invalidated by session replacement. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @param[in] runtimeApi {PersistedPromptCommandRuntimeApi | undefined} Latest extension-api surface written at extension bind time, or undefined to clear the stored surface.
+ * @return {void} No return value.
+ * @satisfies REQ-367, REQ-368, REQ-369
+ */
+export function writePersistedPromptCommandRuntimeApi(
+  runtimeApi: PersistedPromptCommandRuntimeApi | undefined,
+): void {
+  const globalState = globalThis as typeof globalThis & {
+    __piUsereqPromptCommandRuntimeApi?: PersistedPromptCommandRuntimeApi | undefined;
+  };
+  globalState[PI_USEREQ_PROMPT_COMMAND_RUNTIME_API_KEY] = runtimeApi;
+}
+
+/**
+ * @brief Reads the latest live extension api from process-scoped persistence.
+ * @details Returns the extension-api surface written by the most recent extension bind so post-switch model re-application uses a session-scoped api that remains valid after session replacement, returning undefined so callers degrade to their own captured api. Runtime is O(1). No external state is mutated.
+ * @return {PersistedPromptCommandRuntimeApi | undefined} Latest stored extension-api surface, or undefined when no extension has bound in this process.
+ * @satisfies REQ-367, REQ-368, REQ-369
+ */
+export function readPersistedPromptCommandRuntimeApi(): PersistedPromptCommandRuntimeApi | undefined {
+  const globalState = globalThis as typeof globalThis & {
+    __piUsereqPromptCommandRuntimeApi?: PersistedPromptCommandRuntimeApi | undefined;
+  };
+  return globalState[PI_USEREQ_PROMPT_COMMAND_RUNTIME_API_KEY];
+}

package/src/core/prompts.ts

@@ -81,16 +81,28 @@ const PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH = `${PI_DEV_DOCS_PROMPT_PATH}/coding-
  * @details Prompt guidance cites this directory when requiring read-only validation against the pi client implementation. Lookup complexity is O(1).
  */
 const PI_DEV_SOURCE_PROMPT_PATH = "pi.dev-src/pi-mono";
+/**
+ * @brief Stores the repository-relative root directory of the pi CLI client sources.
+ * @details Prompt guidance cites this directory when declaring the permanently read-only pi CLI client reference and source-of-truth mandates for new implementations, source-code modifications, and bug fixes. Lookup complexity is O(1).
+ */
+const PI_DEV_SOURCE_ROOT_PROMPT_PATH = "pi.dev-src";
 /**
  * @brief Defines the injected pi.dev governance guidance block.
- * @details The block requires read-only handling for documentation and pi client sources, coding-agent-document review, coding-agent-document compliance, optional manifest-referenced document handling, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
- * @satisfies REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
+ * @details The block requires read-only handling for documentation and pi client sources, mandatory read-only pi CLI client reference usage plus source-of-truth handling for new implementations, source-code modifications, and bug fixes, coding-agent-document review, coding-agent-document compliance, optional manifest-referenced document handling, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
+ * @satisfies CTN-017, CTN-023, CTN-024, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275, REQ-378
  */
 const PI_DEV_CONFORMANCE_BLOCK = [
   "- Treat every path under `docs/` as read-only; do NOT modify "
     + "any documentation file, including those under `docs/pi.dev/`.",
   "- Treat every path under `pi.dev-src/` as read-only; do NOT modify "
     + `\`${PI_DEV_SOURCE_PROMPT_PATH}\` or any other pi client source.`,
+  `- Every file under \`${PI_DEV_SOURCE_ROOT_PROMPT_PATH}/\` is a pi CLI client `
+    + "source: it MAY and MUST be used as read-only reference material "
+    + "during analysis, implementation, verification, and bug fixing.",
+  `- Treat \`${PI_DEV_SOURCE_ROOT_PROMPT_PATH}/\` as the source-of-truth (SoT) `
+    + "for new implementations, source-code modifications, and bug fixes; "
+    + "derive pi-client-facing behavior from it without modifying it "
+    + "in any way.",
   "- If the task creates or modifies software that interfaces with the "
     + `pi.dev CLI, review \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` `
     + "before analysis, implementation, verification, or bug fixing.",
@@ -110,11 +122,11 @@ const PI_DEV_CONFORMANCE_BLOCK = [
 
 /**
  * @brief Builds the conditional pi.dev governance block for one rendered prompt.
- * @details Emits the coding-agent-document-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the `docs/pi.dev/coding-agent-docs/` directory; the manifest file is optional and its absence does not suppress the block. Time complexity O(1). No filesystem writes.
+ * @details Emits the coding-agent-document-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the `docs/pi.dev/coding-agent-docs/` directory; the manifest file is optional and its absence does not suppress the block. The emitted rules declare `pi.dev-src/` the permanently read-only pi CLI client reference and source-of-truth for new implementations, source-code modifications, and bug fixes. Time complexity O(1). No filesystem writes.
  * @param[in] promptName {string} Bundled prompt identifier.
  * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Markdown bullet block or the empty string when injection is not applicable.
- * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
+ * @satisfies CTN-023, CTN-024, REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275, REQ-378
  */
 function buildPiDevConformanceBlock(promptName: string, projectBase: string): string {
   if (!PI_DEV_AWARE_PROMPT_NAMES.has(promptName)) {
@@ -134,7 +146,7 @@ function buildPiDevConformanceBlock(promptName: string, projectBase: string): st
  * @param[in] promptName {string} Bundled prompt identifier.
  * @param[in] projectBase {string} Absolute project root used for coding-agent-docs directory existence checks.
  * @return {string} Prompt markdown with zero or one injected conformance block.
- * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
+ * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275, REQ-378
  */
 function injectPiDevConformanceBlock(text: string, promptName: string, projectBase: string): string {
   const block = buildPiDevConformanceBlock(promptName, projectBase);
@@ -326,7 +338,7 @@ function renderBundledCommitInstruction(
  * @param[in] config {UseReqConfig} Effective project configuration used for path substitutions.
  * @param[in] executionPlan {PromptCommandExecutionPlan | undefined} Optional prompt-command execution plan used for injected runtime guidance.
  * @return {string} Fully rendered prompt markdown ready for `pi.sendUserMessage(...)`.
- * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108, REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209, REQ-211, REQ-213, REQ-214, REQ-273, REQ-274, REQ-275, REQ-329, REQ-330, REQ-331, REQ-332
+ * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108, REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209, REQ-211, REQ-213, REQ-214, REQ-273, REQ-274, REQ-275, REQ-378, REQ-329, REQ-330, REQ-331, REQ-332
  */
 export function renderPrompt(
   promptName: string,

package/src/index.ts

@@ -145,8 +145,11 @@ import { PROMPT_COMMAND_NAMES } from "./core/prompt-command-catalog.js";
 import { resolveRuntimeGitPath } from "./core/runtime-project-paths.js";
 import {
   clearPersistedPromptCommandRuntimeState,
+  readPersistedPromptCommandRuntimeApi,
   readPersistedPromptCommandRuntimeState,
+  writePersistedPromptCommandRuntimeApi,
   writePersistedPromptCommandRuntimeState,
+  type PersistedPromptCommandRuntimeApi,
 } from "./core/prompt-command-state.js";
 import { ensureBundledResourcesAccessible, readBundledPromptDescription } from "./core/resources.js";
 import { ReqError } from "./core/errors.js";
@@ -3148,8 +3151,8 @@ function resolveCurrentThinkingLevel(pi: ExtensionAPI, ctx: unknown): string | u
 
 /**
  * @brief Builds the loosely-typed model-selection surface from the runtime API plus context.
- * @details Wraps `setModel` and `setThinkingLevel` with defensive function probes so the surface only exposes appliers the running host actually implements, and copies the context model, thinking level, and model registry used by the guarded re-apply comparison. Returns undefined when no context is available so re-application degrades to a not-attempted skip. Runtime is O(1). No external state is mutated.
- * @param[in] pi {ExtensionAPI} Active extension API instance supplying the session-scoped model appliers.
+ * @details Wraps `setModel` and `setThinkingLevel` with defensive function probes so the surface only exposes appliers the running host actually implements, and copies the context model, thinking level, and model registry used by the guarded re-apply comparison. The supplied api MUST be the latest live extension api bound to the active session runner because pi invalidates captured extension apis after session replacement. Returns undefined when no context is available so re-application degrades to a not-attempted skip. Runtime is O(1). No external state is mutated.
+ * @param[in] pi {ExtensionAPI} Latest live extension api instance supplying the session-scoped model appliers; after session replacement callers pass the rebound api rather than a captured pre-switch api.
  * @param[in] ctx {unknown} Active extension or command context supplying model probes.
  * @return {PromptCommandModelSelectionSurface | undefined} Re-apply surface, or undefined when no context exists.
  * @satisfies REQ-367, REQ-370, REQ-371
@@ -3182,10 +3185,10 @@ function resolvePromptCommandModelSurface(
 
 /**
  * @brief Re-applies one captured model selection onto the active post-switch session.
- * @details Builds the guarded re-apply surface from the runtime API plus context, forwards the captured selection plus thinking level into `reapplyPromptCommandSessionSelection(...)`, and routes every warning through `notifyContextSafely(...)` so stale replacement contexts after session replacement never abort orchestration. Runtime is O(1) plus one awaited model mutation. Side effects include session-scoped model and thinking-level mutation plus stale-safe warning notifications.
+ * @details Builds the guarded re-apply surface from the latest process-scoped extension api plus context, preferring the api written by the most recent extension bind because pi invalidates the api captured before session replacement, and falls back to the caller-supplied api for hosts that do not rebind. Forwards the captured selection plus thinking level into `reapplyPromptCommandSessionSelection(...)` and routes every warning through `notifyContextSafely(...)` so stale replacement contexts after session replacement never abort orchestration. Runtime is O(1) plus one awaited model mutation. Side effects include session-scoped model and thinking-level mutation plus stale-safe warning notifications.
  * @param[in] selection {PromptCommandModelSelection | undefined} Captured model provider plus identifier.
  * @param[in] thinkingLevel {string | undefined} Captured thinking level.
- * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in] pi {ExtensionAPI} Extension api captured by the running handler, used only as fallback when no rebound api is stored.
  * @param[in] ctx {unknown} Active extension or command context used for probes and warning delivery.
  * @return {Promise<void>} Promise resolved once the guarded re-application completed.
  * @satisfies REQ-367, REQ-368, REQ-369, REQ-370, REQ-371, REQ-372
@@ -3196,10 +3199,12 @@ async function reapplyCapturedPromptModelSelection(
   pi: ExtensionAPI,
   ctx: unknown,
 ): Promise<void> {
+  const liveApi = readPersistedPromptCommandRuntimeApi();
+  const activeApi = liveApi ?? pi;
   await reapplyPromptCommandSessionSelection({
     selection,
     thinkingLevel,
-    surface: resolvePromptCommandModelSurface(pi, ctx),
+    surface: resolvePromptCommandModelSurface(activeApi as ExtensionAPI, ctx),
     notifyWarning: (message) => {
       notifyContextSafely(ctx as ExtensionContext, message, "error");
     },
@@ -5132,12 +5137,13 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and timer scheduling.
+ * @details Persists the live extension api into process-scoped storage on every bind so model re-application after session replacement binds to the api of the currently active session runner instead of an invalidated captured api, then validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, process-scoped extension-api persistence, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
  * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325, REQ-326, REQ-327
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
+  writePersistedPromptCommandRuntimeApi(pi as unknown as PersistedPromptCommandRuntimeApi);
   const statusController = createPiUsereqStatusController();
   ensureBundledResourcesAccessible();
   registerReqResetCommand(pi, statusController);