pi-ask-user-x 0.1.0 → 0.1.1

package/README.md

@@ -4,18 +4,18 @@ Bilingual structured questionnaire extension for the Pi coding agent (`@earendil
 
 ## Overview & Architecture
 
-`pi-ask-user-x` provides the `bilingual_questionnaire` tool for interactive user questionnaires, preference elicitation, and architectural decision trees.
+`pi-ask-user-x` provides the `ask_user` tool for interactive user questionnaires, preference elicitation, and architectural decision trees.
 
-- **Non-Interception & Tool Separation**: The existing built-in `ask_user_question` tool is **not intercepted**, patched, or monkey-patched. Agents choose `bilingual_questionnaire` directly or via manual user prompt/system guidance without global state mutations.
+- **Non-Interception & Tool Separation**: The separate `ask_user_question` plugin is **not intercepted**, patched, or monkey-patched. Models invoke `ask_user` directly to ask structured questions with single or multiple choices, or open freeform input, without global state mutations.
 - **Dual Execution Modes**:
-  - **Co-operative with `pi-translate-x`**: When `pi-translate-x` (>=0.1.3) is active and enabled, question headers, prompts, descriptions, and predefined options are dynamically translated into the user's target language via the versioned translation service (`TranslationService`, protocol v1 over `pi.events`). Custom user prose and notes are reverse-translated back to English for the LLM.
+  - **Co-operative with `pi-translate-x`**: When `pi-translate-x` (>=0.1.3) is active and enabled, question headers, prompts, descriptions, and predefined options are dynamically translated into the user's target language via the versioned translation service (`TranslationService`, protocol v1 over `pi.events`). Custom user prose and notes are reverse-translated back to English for the LLM. Translation is a presentation implementation detail—the model tool name, label, and description remain clean and neutral.
   - **Standalone Mode**: When `pi-translate-x` is absent or disabled at launch, `pi-ask-user-x` operates standalone in canonical English without failure. When an active translation service is detected but incompatible, malformed, or fails rediscovery/retry, users are presented with an explicit recovery choice (Retry discovery, Continue in English, or Cancel questionnaire) rather than silently degrading. Once an enabled service is discovered, answer translation obligation is pinned: custom user prose and notes are never submitted raw to the LLM without translation or explicit user recovery choice.
 - **English-Canonical Contract & Stable IDs**: Predefined choices resolve strictly by stable, immutable string identifiers (`id`), completely independent of translated display text or duplicate localized labels. Predefined option choices are never back-translated. The model-facing tool arguments and return results remain strictly canonical English.
 - **Submit-Only Privacy & Persistence**: Only confirmed, submitted questionnaire answers and their durable bilingual display snapshot are persisted to the session transcript (as context-excluded custom entries of type `pi-ask-user-x:questionnaire`). In-progress drafts, uncommitted answers, and cancelled questionnaire sessions are discarded from memory and never written to transcript storage. Persisted records are static; changing translator settings later does not re-translate or mutate session history. Durable transcript records are rendered visually for the human user but excluded from LLM context injection.
 
 ## Question Types and Configuration
 
-The `bilingual_questionnaire` tool supports 1 to 8 structured questions per invocation:
+The `ask_user` tool supports 1 to 8 structured questions per invocation:
 
 | Question Type | Behavior & Fields |
 |---|---|
@@ -49,17 +49,43 @@ The TUI component (`QuestionnaireTUIComponent`) provides an accessible, fully re
 
 When running headless or via RPC (`ctx.mode === "rpc"`), interactive terminal components degrade gracefully to standard dialog methods (`ui.select`, `ui.input`, `ui.confirm`). Rich Markdown previews degrade to text label and description hints.
 
-## Local Installation & Usage
+## Installation & Usage
 
-Do not run duplicate translation services. `pi-translate-x` is the companion translator package (requiring minimum `0.1.3` for service integration), while `pi-ask-user-x` (`0.1.0`) is prepared for manual initial npm bootstrap. To run or test both extensions locally from checkout:
+### Installing Published Packages
 
+Install the companion questionnaire package directly from npm:
+```sh
+pi install npm:pi-ask-user-x
+```
+
+When using alongside `pi-translate-x` for bilingual translation support, ensure `pi-translate-x` is at least version `0.1.3`:
+```sh
+pi install npm:pi-translate-x
+```
+
+### Source Checkout, Migration, and Release Status
+
+- **Tool Name Migration**:
+  - In `pi-ask-user-x@0.1.0` (published on npm): The tool was named `bilingual_questionnaire`.
+  - In `pi-ask-user-x@0.1.1` (prepared in checkout): The tool is renamed to `ask_user` with label `Ask User` and a neutral model description (`structured questions / choices / freeform`).
+- **Published Tarball vs Source**: Version `0.1.0` of `pi-ask-user-x` is verified public latest on npm (integrity `sha512-MYTZ9F1Ll7DKmyeUtq5iAzBF/r6vwomizfeR2WUjr25KK+si36iHINRgMon5WzUcNkxzjnc/mGeWtnG/d1Mdiw==`, owner `carmelocampos`). Because npm enforces package immutability, version 0.1.0 cannot and will not be republished. Version `0.1.1` is prepared in this repository workspace.
+- **Future Automated Releases**: Subsequent releases will be automated via GitHub Actions workflow `.github/workflows/publish-ask-user.yml` triggered exclusively by published GitHub Releases (`GHrelease.published`) with tag `pi-ask-user-x-v<packageversion>`.
+- **npm Trusted Publisher Configuration**:
+  - GitHub repository: `dogalyir/pi-translate-x`
+  - Workflow name: `publish-ask-user.yml`
+  - Environment name: `npm`
+  *(Do not configure the trusted publisher in the npm owner UI until confirmed.)*
+
+### Local Development from Checkout
+
+To run or test both extensions locally from this checkout without loading duplicate extensions:
 ```sh
 pi --no-extensions --extension ./src/index.ts --extension ./packages/ask-user/src/index.ts
 ```
 
 ## Runnable Schema Example
 
-Below is a complete, runnable invocation of `bilingual_questionnaire` demonstrating `single`, `multi`, and `text` question types, markdown previews, supplemental custom text, notes, and selection bounds:
+Below is a complete, runnable invocation of `ask_user` demonstrating `single`, `multi`, and `text` question types, markdown previews, supplemental custom text, notes, and selection bounds:
 
 ```json
 {
@@ -129,6 +155,14 @@ Below is a complete, runnable invocation of `bilingual_questionnaire` demonstrat
 
 Automated test suites pass deterministically using headless Vitest assertions, mock terminal renderers, and simulated event busses. **No manual assistive technology (AT), hardware cursor, screen-reader, or live terminal/provider verification is claimed.** Manual terminal inspection remains required for physical terminal emulator quirks.
 
+## Documentation & Monorepo Links
+
+For additional architectural details and guides, see the repository documentation:
+- [Questionnaire Guide](https://github.com/dogalyir/pi-translate-x/blob/main/docs/questionnaire.md)
+- [Translation Pipeline Guide](https://github.com/dogalyir/pi-translate-x/blob/main/docs/translation.md)
+- [Release Operations & Verification](https://github.com/dogalyir/pi-translate-x/blob/main/docs/releases.md)
+- [Monorepo Documentation Index](https://github.com/dogalyir/pi-translate-x/blob/main/docs/index.md)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-user-x",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Bilingual structured questionnaire extension for Pi coding agent",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -96,12 +96,12 @@ export default function register(pi: ExtensionAPI): void {
     });
   }
 
-  // 2. Register tool bilingual_questionnaire
+  // 2. Register tool ask_user
   pi.registerTool({
-    name: "bilingual_questionnaire",
-    label: "Bilingual Questionnaire",
+    name: "ask_user",
+    label: "Ask User",
     description:
-      "Interactive bilingual questionnaire to collect user preferences, architectural decisions, and configurations.",
+      "Ask the user structured questions with single or multiple choices, or open freeform input, to collect preferences, requirements, and decisions.",
     exposure: "model-only",
     parameters: BilingualQuestionnaireParamsSchema,
     execute: async (toolCallId, params: BilingualQuestionnaireParams, signal, _onUpdate, ctx) => {
@@ -927,7 +927,7 @@ function makeUnsupportedResult(params: BilingualQuestionnaireParams, reason: str
     content: [
       {
         type: "text" as const,
-        text: "Error: bilingual_questionnaire requires interactive UI mode (TUI or RPC). Headless execution is not supported.",
+        text: "Error: ask_user requires interactive UI mode (TUI or RPC). Headless execution is not supported.",
       },
     ],
     isError: true,

package/src/ui/renderer.ts

@@ -19,7 +19,7 @@ export function renderQuestionnaireEntry(
   }
 
   const record: DurableQuestionnaireRecord = entry.data;
-  const title = record.canonical.title ?? "Bilingual Questionnaire";
+  const title = record.canonical.title ?? "Ask User";
   const dateStr = new Date(record.createdAt).toLocaleTimeString();
   const langBadge = record.display?.language ? `[${record.display.language.toUpperCase()}]` : "";