@agimon-ai/doompi-user-feedback 0.0.1-alpha.9 → 0.0.1-alpha.91

package/README.md

@@ -1,62 +1,123 @@
 # @agimon-ai/doompi-user-feedback
 
-**Sometimes the agent needs an answer. Make it ask.**
+Ask structured questions in interactive Pi sessions, including sessions using autonomous Voice.
 
-This package provides the structured `ask_user_question` interaction for Pi. In a normal
-terminal session it opens a blocking questionnaire and returns the selected answer to the
-agent. The question does not get buried in prose and the turn does not continue on a
-guess.
+Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).
 
-In autonomous Voice mode there is no modal to click. The extension formats the choices as
-plain text, hands them to narration, terminates the turn, and accepts the next spoken reply
-as an ordinary user message.
+The `ask_user_question` tool presents concrete options and waits for a choice or custom-text answer.
 
-This implementation is written for Pi and has no dependency on the old Juicesharp
-packages. It keeps the established `rpiv:ask-user:prompt` and `rpiv:ask-user:blocked`
-channel names so existing Doompi listeners can migrate without being rewritten.
+> **Alpha:** tool and Voice-handoff contracts may change between releases.
 
-This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). The bundled
-`ask-user` layer loads it where structured feedback is wanted.
+## Requirements
 
-## Install
-
-```bash
-npm install @agimon-ai/doompi-user-feedback
-```
+- Node.js 22.19.0 or newer
+- Pi 0.85.0 and Pi TUI 0.85.0
 
-## How it loads
+## Install
 
-Put the bare package name in a layer, then add that layer to a major mode:
+Define a layer in `.doom/modes.yaml`, then include it in a major mode:
 
 ```yaml
 layers:
-  ask-user:
+  feedback:
     packages: ['@agimon-ai/doompi-user-feedback']
 
 majorMode:
-  dev:
-    description: Development mode with structured user clarification.
-    layers: [ask-user]
+  minimal:
+    description: Interactive questions without the full default composition.
+    layers: [feedback]
+```
+
+For standalone Pi:
+
+```bash
+pi install npm:@agimon-ai/doompi-user-feedback
 ```
 
-The package's Pi manifest selects the Pi adapter. The explicit `/extensions/pi` subpath
-remains available when an adapter path is required.
+Pi loads the package through `package.json.pi.extensions`. Each factory invocation owns one package
+instance. Session replacement resets its state, and shutdown removes its registrations.
+
+## Ask a question
+
+```json
+{
+  "questions": [
+    {
+      "header": "Storage",
+      "question": "Where should session results be stored?",
+      "options": [
+        {
+          "label": "Project files",
+          "description": "Easy to inspect and commit, but visible in the repository."
+        },
+        {
+          "label": "User state",
+          "description": "Keeps generated state outside the repository."
+        }
+      ],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+A call accepts 1 to 4 questions. Each question requires 2 to 4 options. Headers are at most 16
+characters; option labels are at most 60 characters. Use `multiSelect: true` when several choices
+are valid. An option can include a Markdown `preview` for meaningful visual comparison.
+
+The tool result contains readable answer text plus structured `details.answers`; cancellation sets
+`cancelled: true`. Pressing Escape declines the questionnaire. Do not add an `Other` option because
+the UI supplies a custom-text row.
 
-## Reusable voice handoff
+## UI, RPC, and headless behavior
 
-`@agimon-ai/doompi-user-feedback/voice-question-handoff` exposes the same minor-mode
-detection, plain-text formatting, and narration handoff to other tools.
-`createVoiceQuestionHandoff()` returns a session-scoped handle; call `dispose()` when its
-session ends so subscriptions do not outlive their owner.
+The tool requires an interactive UI. It uses the TUI questionnaire when available and can use Pi's
+dialog or RPC UI bridge. A headless context without either UI returns a structured `no_ui`
+cancellation rather than waiting forever.
 
-Voice results include the readable question, set `terminate: true`, and mark the turn as
-waiting for a response. The answer then arrives through the normal user-message path.
+Questionnaires are coordinated one at a time. Cancellation, session replacement, or shutdown
+aborts the active prompt and settles queued work.
+
+## Autonomous Voice
+
+While autonomous Voice mode is active, `ask_user_question` leaves Pi's active tool set. Voice already
+speaks its own question through `narrate` and then waits for the spoken reply, so keeping a
+questionnaire tool alongside it asks the same thing twice. The agent asks by narrating, and the
+answer arrives as an ordinary user message.
+
+The gate tracks its own removal. A tool switched off by the user stays off, no other package's tools
+are touched, and the removal is restored when Voice deactivates, when the Voice services unload, or
+when this runtime shuts down.
+
+A call already in flight when Voice activates still hands off: the extension formats the questions as
+plain text, requests narration, and returns `terminate: true`, ending the turn while it waits.
+
+Both paths use the shared `doom/minor-mode-catalog` and `doom/narration` Cordis services. If a
+provider unloads, User Feedback restores the tool and falls back to its interactive questionnaire
+without retaining the old provider.
 
 ## Public API
 
-The package exports the extension, event names, reusable voice handoff, and Pi adapter
-through supported subpaths.
+Question and result types are available from the package root. Cross-extension ask-user events and
+Voice services come from `@agimon-ai/doompi-core`; consumers should use those Cordis
+contracts. Pi loads the default export of `/extensions/pi` through package metadata, so installation
+does not require a manual registration call.
+
+## Development
+
+Run from this package directory in the workspace:
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
 
 ## License
 
 MIT
+
+The named Pi and server factories live in `src/extensions`. Tools return typed declarations using questionnaire services. TUI renderers are supplied by the Pi entry. Each Pi mount owns optional Voice service subscriptions, a live tool restriction, and awaited questionnaire shutdown through `onDispose`. Public types are exposed through flat `src/exports`.

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = (0, require("@agimon-ai/doompi-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,gDAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/doompi-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/doompi-core/apiContracts';\n\n/** This facet contributes agent tools, commands or lifecycle only, with no separate HTTP or socket surface. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}