@agimon-ai/doompi-user-feedback 0.0.1-alpha.11 → 0.0.1-alpha.110

package/README.md

@@ -1,24 +1,31 @@
 # @agimon-ai/doompi-user-feedback
 
-Structured, blocking user questions for Pi, with an autonomous-Voice handoff.
+Ask structured questions in interactive Pi sessions, including sessions using autonomous Voice.
 
-The `ask_user_question` tool presents concrete options instead of asking the model to continue on a guess.
+Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).
+
+The `ask_user_question` tool presents concrete options and waits for a choice or custom-text answer.
 
 > **Alpha:** tool and Voice-handoff contracts may change between releases.
 
 ## Requirements
 
 - Node.js 22.19.0 or newer
-- Pi 0.84.2 and Pi TUI 0.84.2
+- Pi 1.0.0 and Pi TUI 0.85.0
 
 ## Install
 
-Add the package to a DoomPi layer:
+Define a layer in `.doom/modes.yaml`, then include it in a major mode:
 
 ```yaml
 layers:
   feedback:
     packages: ['@agimon-ai/doompi-user-feedback']
+
+majorMode:
+  minimal:
+    description: Interactive questions without the full default composition.
+    layers: [feedback]
 ```
 
 For standalone Pi:
@@ -27,6 +34,9 @@ For standalone Pi:
 pi install npm:@agimon-ai/doompi-user-feedback
 ```
 
+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
@@ -51,48 +61,52 @@ pi install npm:@agimon-ai/doompi-user-feedback
 }
 ```
 
-A call accepts 1–4 questions. Each question requires 2–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.
+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.
+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.
 
 ## UI, RPC, and headless behavior
 
-The tool requires an interactive UI. It uses the TUI questionnaire when available and can use Pi's dialog/RPC UI bridge. A truly headless context returns a structured `no_ui` cancellation rather than waiting forever.
+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.
 
-Questionnaires are coordinated one at a time. Cancellation, session replacement, or shutdown aborts the active prompt and settles queued work.
+Questionnaires are coordinated one at a time. Cancellation, session replacement, or shutdown
+aborts the active prompt and settles queued work.
 
-## Autonomous Voice handoff
+## Autonomous Voice
 
-When autonomous Voice mode is active, the extension formats the questions as plain text, requests narration, and returns `terminate: true`. The current turn ends while waiting; the next spoken answer arrives as a normal user message rather than a synthetic questionnaire selection.
+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.
 
-Reusable integrations can create a session-scoped handoff:
+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.
 
-```ts
-import { createVoiceQuestionHandoff } from '@agimon-ai/doompi-user-feedback/voice-question-handoff';
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-
-export function installVoiceHandoff(pi: ExtensionAPI, sessionId: string): () => void {
-  const handoff = createVoiceQuestionHandoff({
-    bus: pi.events,
-    source: '@example/review-extension',
-    sessionId,
-  });
-  return () => handoff.dispose();
-}
-```
+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.
 
-Always dispose the handle during shutdown.
+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
 
-```ts
-import { registerUserFeedbackExtension } from '@agimon-ai/doompi-user-feedback';
-```
-
-Event constants are available through `/events`; the Pi adapter is `/extensions/pi`.
+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
@@ -100,6 +114,10 @@ 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"}