@agimon-ai/po-user-feedback 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @agimon-ai/po-user-feedback
+
+Ask structured questions through native Po clients, including sessions using autonomous Voice.
+
+Part of the [Po distribution](https://www.npmjs.com/package/@agimon-ai/po).
+
+The `ask_user_question` tool presents concrete options and waits for a choice or custom-text answer.
+
+> **Alpha:** tool contracts may change between releases.
+
+## Requirements
+
+- Node.js 24 or newer
+- A Po session client capable of answering select and input requests
+
+## Install
+
+Define a layer in `.po/modes.yaml`, then include it in a major mode:
+
+```yaml
+layers:
+  feedback:
+    packages: ['@agimon-ai/po-user-feedback']
+
+majorMode:
+  minimal:
+    description: Interactive questions without the full default composition.
+    layers: [feedback]
+```
+
+The native server facet owns questionnaire coordination and cancellation. Disposing the facet aborts pending requests and waits for presenters to finish.
+
+## 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.
+
+## Client behavior
+
+The native tool requests choices and custom text through the session client. Questionnaires run one at a time. Cancellation or disposal aborts active requests and settles queued work.
+
+## Autonomous Voice
+
+While autonomous Voice mode is active, `ask_user_question` leaves the 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 native tool restriction composes with other restrictions and restores questionnaire availability when autonomous Voice deactivates.

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/po-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/po-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,4CAAeA,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/po-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/po-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"}