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

package/dist/extensions/server.mjs

@@ -0,0 +1,622 @@
+import { composeServerProviderOverrides, defineServerPlugin, readPackageResource } from "@agimon-ai/po-core/serverFacet";
+import { composeRootHooks, defineResource, defineRoot, defineServerTool, defineToolRestriction } from "@agimon-ai/po-core/extensionFile";
+import { DOOM_HELP_WHEN } from "@agimon-ai/po-core/help";
+import { DOOM_VOICE_AUTO_MODE_ID } from "@agimon-ai/po-core/voiceTools";
+import { Type } from "typebox";
+//#region src/services/questionnaireCoordinator/index.ts
+function cancelledResult(entry) {
+	return {
+		answers: entry.latestAnswers.map((answer) => ({ ...answer })),
+		cancelled: true
+	};
+}
+var QuestionnaireCoordinator = class {
+	pending = [];
+	running = /* @__PURE__ */ new Set();
+	active;
+	nextRequestId = 1;
+	accepting = true;
+	enqueue(runner, externalSignal) {
+		if (!this.accepting || externalSignal?.aborted) return Promise.resolve({
+			answers: [],
+			cancelled: true
+		});
+		return new Promise((resolve, reject) => {
+			const entry = {
+				id: this.nextRequestId,
+				runner,
+				controller: new AbortController(),
+				...externalSignal ? { externalSignal } : {},
+				latestAnswers: [],
+				state: "queued",
+				resolve,
+				reject
+			};
+			this.nextRequestId += 1;
+			const abort = () => this.cancel(entry);
+			externalSignal?.addEventListener("abort", abort, { once: true });
+			entry.removeAbortListener = () => externalSignal?.removeEventListener("abort", abort);
+			this.pending.push(entry);
+			this.startNext();
+		});
+	}
+	shutdown() {
+		if (!this.accepting && !this.active && this.pending.length === 0) return;
+		this.accepting = false;
+		if (this.active) this.cancel(this.active);
+		while (this.pending.length > 0) {
+			const entry = this.pending[0];
+			if (!entry) break;
+			this.cancel(entry);
+		}
+	}
+	/** Waits for every started presenter to observe cancellation and finish. */
+	async waitForIdle() {
+		while (this.running.size > 0) await Promise.allSettled(this.running);
+	}
+	startNext() {
+		if (!this.accepting || this.active) return;
+		const entry = this.pending.shift();
+		if (!entry) return;
+		entry.state = "active";
+		this.active = entry;
+		const reportProgress = (result) => {
+			if (this.active?.id !== entry.id || entry.state !== "active") return;
+			entry.latestAnswers = result.answers.map((answer) => ({ ...answer }));
+		};
+		let operation;
+		try {
+			operation = entry.runner({
+				signal: entry.controller.signal,
+				reportProgress
+			});
+		} catch (error) {
+			operation = Promise.reject(error);
+		}
+		this.running.add(operation);
+		operation.then((result) => this.complete(entry, result), (error) => this.fail(entry, error)).finally(() => this.running.delete(operation));
+	}
+	complete(entry, result) {
+		if (this.active?.id !== entry.id || entry.state !== "active") return;
+		this.releaseActive(entry);
+		entry.resolve(result);
+		this.startNext();
+	}
+	fail(entry, error) {
+		if (this.active?.id !== entry.id || entry.state !== "active") return;
+		this.releaseActive(entry);
+		entry.reject(error);
+		this.startNext();
+	}
+	cancel(entry) {
+		if (entry.state === "settled") return;
+		if (entry.state === "queued") {
+			const index = this.pending.indexOf(entry);
+			this.pending.splice(index, 1);
+			entry.state = "settled";
+			entry.removeAbortListener?.();
+			entry.controller.abort();
+			entry.resolve(cancelledResult(entry));
+			return;
+		}
+		const result = cancelledResult(entry);
+		this.releaseActive(entry);
+		entry.controller.abort();
+		entry.resolve(result);
+		this.startNext();
+	}
+	releaseActive(entry) {
+		entry.state = "settled";
+		entry.removeAbortListener?.();
+		this.active = void 0;
+	}
+};
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/_lib/root.server.ts
+const root = defineRoot((_context) => {
+	const coordinator = new QuestionnaireCoordinator();
+	return {
+		value: { coordinator },
+		onDispose: async () => {
+			coordinator.shutdown();
+			await coordinator.waitForIdle();
+		}
+	};
+});
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/root.server.ts
+var root_server_default = defineRoot(root);
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/resource/poUseUserFeedback.server.ts
+var poUseUserFeedback_server_default = defineResource({
+	name: "po-use-user-feedback",
+	when: DOOM_HELP_WHEN,
+	kind: "skill",
+	read: () => readPackageResource(import.meta.url, "src/prompts/po-use-user-feedback/SKILL.md")
+});
+//#endregion
+//#region src/constants/questionnaire.ts
+const RESERVED_LABELS = [
+	"Other",
+	"Type something.",
+	"Next"
+];
+//#endregion
+//#region src/constants/tool.ts
+const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/tool-restriction/askUserQuestion.server.ts
+var askUserQuestion_server_default$1 = defineToolRestriction({
+	when: { state: { "minor-mode": DOOM_VOICE_AUTO_MODE_ID } },
+	excludedTools: [ASK_USER_QUESTION_TOOL_NAME]
+});
+//#endregion
+//#region src/schemas/questionnaire.ts
+const OptionSchema = Type.Object({
+	label: Type.String({
+		maxLength: 60,
+		description: "MAX 60 CHARACTERS, hard limit. Concise option label shown to the user, ideally 1-5 words."
+	}),
+	description: Type.String({ description: "Explanation of what the option means and its important trade-offs." }),
+	preview: Type.Optional(Type.String({ description: "Optional markdown preview rendered while this option is focused." }))
+}, { additionalProperties: false });
+const QuestionSchema = Type.Object({
+	question: Type.String({ description: "The complete, clear question to ask the user." }),
+	header: Type.String({
+		maxLength: 16,
+		description: "MAX 16 CHARACTERS, short label used when navigating several questions."
+	}),
+	options: Type.Array(OptionSchema, {
+		minItems: 2,
+		maxItems: 4,
+		description: "The 2-4 choices offered for this question."
+	}),
+	multiSelect: Type.Optional(Type.Boolean({
+		description: "Allow more than one option to be selected.",
+		default: false
+	}))
+}, { additionalProperties: false });
+const QuestionParamsSchema = Type.Object({ questions: Type.Array(QuestionSchema, {
+	minItems: 1,
+	maxItems: 4,
+	description: "Questions to ask the user (1-4 questions)."
+}) }, { additionalProperties: false });
+function decodeAnswerEnvelope(value) {
+	if (value === void 0 || !value.startsWith("doom-ask-user/v1:")) return { kind: "absent" };
+	if (value.length > 65536) return { kind: "malformed" };
+	try {
+		return {
+			kind: "envelope",
+			payload: JSON.parse(value.slice(17))
+		};
+	} catch {
+		return { kind: "malformed" };
+	}
+}
+//#endregion
+//#region src/services/answerEnvelope/index.ts
+/**
+* Read a whole-questionnaire answer envelope back against the questions it claims to answer.
+*
+* The envelope arrives on a select response, which is reader input rather than
+* anything the tool authored, so nothing in it is taken on trust: an index has
+* to name a question that was asked, a chosen label has to be one that
+* question offered, and free text is capped. An envelope that fails is refused
+* rather than repaired, because a half-read answer set reaches the model as
+* the reader's decision and there is no way to tell from there that part of it
+* was invented.
+*
+* `preview` is the clearest case: it is read from the option the tool
+* declared, never from the wire, so the model cannot be shown a preview that
+* was never offered.
+*
+* Host-neutral by construction: the questions and the payload both arrive as
+* arguments, so the same arguments always produce the same result.
+*/
+const MAX_ANSWER_TEXT_LENGTH = 4e3;
+const ANSWER_KINDS = [
+	"option",
+	"custom",
+	"multi"
+];
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalNote(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed.slice(0, MAX_ANSWER_TEXT_LENGTH);
+}
+/** One answer, rebuilt from the question it names rather than copied off the wire. */
+function readAnswer(entry, params, seen) {
+	if (!isRecord(entry)) return "an answer was not an object";
+	const questionIndex = entry.questionIndex;
+	if (typeof questionIndex !== "number" || !Number.isInteger(questionIndex)) return "an answer carried no question index";
+	const question = params.questions[questionIndex];
+	if (question === void 0) return `no question ${String(questionIndex)} was asked`;
+	if (seen.has(questionIndex)) return `question ${String(questionIndex)} was answered twice`;
+	seen.add(questionIndex);
+	const kind = entry.kind;
+	if (typeof kind !== "string" || !ANSWER_KINDS.includes(kind)) return `question ${String(questionIndex)} carried an unknown answer kind`;
+	const notes = optionalNote(entry.notes);
+	const base = {
+		questionIndex,
+		question: question.question,
+		...notes === void 0 ? {} : { notes }
+	};
+	if (kind === "multi") {
+		const selected = entry.selected;
+		if (!Array.isArray(selected)) return `question ${String(questionIndex)} selected nothing readable`;
+		const labels = selected.filter((label) => typeof label === "string");
+		if (labels.length !== selected.length) return `question ${String(questionIndex)} selected a non-label`;
+		if (labels.some((label) => !question.options.some((option) => option.label === label))) return `question ${String(questionIndex)} selected an option it was not offered`;
+		return {
+			...base,
+			kind: "multi",
+			answer: null,
+			selected: [...new Set(labels)]
+		};
+	}
+	if (kind === "option") {
+		const label = entry.answer;
+		const chosen = typeof label === "string" ? question.options.find((option) => option.label === label) : void 0;
+		if (chosen === void 0) return `question ${String(questionIndex)} chose an option it was not offered`;
+		return {
+			...base,
+			kind: "option",
+			answer: chosen.label,
+			...chosen.preview ? { preview: chosen.preview } : {}
+		};
+	}
+	const typed = entry.answer;
+	if (typeof typed !== "string") return `question ${String(questionIndex)} typed nothing readable`;
+	return {
+		...base,
+		kind: "custom",
+		answer: typed.slice(0, MAX_ANSWER_TEXT_LENGTH)
+	};
+}
+function readAnswerEnvelope(payload, params) {
+	if (!isRecord(payload) || !Array.isArray(payload.answers)) return {
+		ok: false,
+		reason: "no answers were carried"
+	};
+	if (payload.answers.length === 0) return {
+		ok: false,
+		reason: "no answers were carried"
+	};
+	if (payload.answers.length > params.questions.length) return {
+		ok: false,
+		reason: "more answers than questions"
+	};
+	const seen = /* @__PURE__ */ new Set();
+	const answers = [];
+	for (const entry of payload.answers) {
+		const answer = readAnswer(entry, params, seen);
+		if (typeof answer === "string") return {
+			ok: false,
+			reason: answer
+		};
+		answers.push(answer);
+	}
+	answers.sort((left, right) => left.questionIndex - right.questionIndex);
+	return {
+		ok: true,
+		answers
+	};
+}
+//#endregion
+//#region src/services/questionnaireService/index.ts
+const CUSTOM_LABEL = "Type something.";
+const DONE_LABEL = "Next";
+function cancelled(answers) {
+	return {
+		answers,
+		cancelled: true
+	};
+}
+/** True when this response was the whole set, in which case the sink now holds the answer. */
+function takeEnvelope(sink, selected) {
+	const read = decodeAnswerEnvelope(selected);
+	if (read.kind === "absent") return false;
+	if (read.kind === "malformed") {
+		sink.result = {
+			answers: [],
+			cancelled: true,
+			error: "malformed_answers"
+		};
+		return true;
+	}
+	const envelope = readAnswerEnvelope(read.payload, sink.params);
+	sink.result = envelope.ok ? {
+		answers: envelope.answers,
+		cancelled: false
+	} : {
+		answers: [],
+		cancelled: true,
+		error: "malformed_answers"
+	};
+	return true;
+}
+async function askForCustomAnswer(interaction, question, questionIndex, signal) {
+	const answer = await interaction.input(question.question, "Type your answer", signal);
+	if (answer === void 0) return void 0;
+	return {
+		questionIndex,
+		question: question.question,
+		kind: "custom",
+		answer
+	};
+}
+async function askSingleChoice(interaction, question, questionIndex, sink, signal) {
+	const labels = [...question.options.map((option) => option.label), CUSTOM_LABEL];
+	const selected = await interaction.select(question.question, labels, signal);
+	if (selected === void 0) return void 0;
+	if (takeEnvelope(sink, selected)) return void 0;
+	if (selected === CUSTOM_LABEL) return askForCustomAnswer(interaction, question, questionIndex, signal);
+	const option = question.options.find((candidate) => candidate.label === selected);
+	if (!option) return void 0;
+	return {
+		questionIndex,
+		question: question.question,
+		kind: "option",
+		answer: option.label,
+		...option.preview ? { preview: option.preview } : {}
+	};
+}
+function multiChoiceLabels(question, selected) {
+	return [
+		...question.options.map((option) => {
+			return `${selected.has(option.label) ? "[x]" : "[ ]"} ${option.label}`;
+		}),
+		CUSTOM_LABEL,
+		DONE_LABEL
+	];
+}
+function stripSelectionMarker(value) {
+	return value.replace(/^\[[ x]\]\s/u, "");
+}
+async function askMultipleChoice(interaction, question, questionIndex, sink, signal) {
+	const selected = /* @__PURE__ */ new Set();
+	while (!signal?.aborted) {
+		const choice = await interaction.select(`${question.question} (choose options, then Next)`, multiChoiceLabels(question, selected), signal);
+		if (choice === void 0) return void 0;
+		if (takeEnvelope(sink, choice)) return void 0;
+		if (choice === CUSTOM_LABEL) return askForCustomAnswer(interaction, question, questionIndex, signal);
+		if (choice === DONE_LABEL) return {
+			questionIndex,
+			question: question.question,
+			kind: "multi",
+			answer: null,
+			selected: [...selected]
+		};
+		const label = stripSelectionMarker(choice);
+		if (!question.options.some((option) => option.label === label)) continue;
+		if (selected.has(label)) selected.delete(label);
+		else selected.add(label);
+	}
+}
+async function runQuestionnaire(interaction, params, signal, reportProgress) {
+	const answers = [];
+	const sink = { params };
+	for (let questionIndex = 0; questionIndex < params.questions.length; questionIndex += 1) {
+		if (signal?.aborted) return cancelled(answers);
+		const question = params.questions[questionIndex];
+		if (!question) continue;
+		const answer = question.multiSelect ? await askMultipleChoice(interaction, question, questionIndex, sink, signal) : await askSingleChoice(interaction, question, questionIndex, sink, signal);
+		if (sink.result !== void 0) {
+			const whole = sink.result;
+			if (!whole.cancelled) reportProgress?.({
+				...whole,
+				answers: whole.answers.map((item) => ({ ...item }))
+			});
+			return whole;
+		}
+		if (!answer) return cancelled(answers);
+		answers.push(answer);
+		reportProgress?.({
+			answers: answers.map((item) => ({ ...item })),
+			cancelled: false
+		});
+	}
+	return {
+		answers,
+		cancelled: false
+	};
+}
+//#endregion
+//#region src/services/responseService/index.ts
+const DECLINE_MESSAGE = "User declined to answer questions";
+const ENVELOPE_PREFIX = "User has answered your questions:";
+const ENVELOPE_SUFFIX = "You can now continue with the user's answers in mind.";
+const NO_INPUT_PLACEHOLDER = "(no input)";
+function buildToolResult(text, details) {
+	return {
+		content: [{
+			type: "text",
+			text
+		}],
+		details
+	};
+}
+function formatAnswer(answer) {
+	if (answer.kind === "multi") return answer.selected && answer.selected.length > 0 ? answer.selected.join(", ") : NO_INPUT_PLACEHOLDER;
+	return answer.answer && answer.answer.length > 0 ? answer.answer : NO_INPUT_PLACEHOLDER;
+}
+function buildAnswerSegment(answer) {
+	const sections = [`"${answer.question}"="${formatAnswer(answer)}"`];
+	if (answer.preview) sections.push(`selected preview: ${answer.preview}`);
+	if (answer.notes) sections.push(`user notes: ${answer.notes}`);
+	return `${sections.join(". ")}.`;
+}
+function buildQuestionnaireResponse(result, params) {
+	if (!result || result.cancelled) return buildToolResult(DECLINE_MESSAGE, {
+		answers: result?.answers ?? [],
+		cancelled: true
+	});
+	const segments = params.questions.flatMap((_question, index) => {
+		const answer = result.answers.find((candidate) => candidate.questionIndex === index);
+		return answer ? [buildAnswerSegment(answer)] : [];
+	});
+	if (segments.length === 0) return buildToolResult(DECLINE_MESSAGE, {
+		answers: result.answers,
+		cancelled: true
+	});
+	return buildToolResult(`${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`, result);
+}
+//#endregion
+//#region src/services/validationService/index.ts
+const ERROR_NO_QUESTIONS = "Error: At least one question is required";
+const ERROR_TOO_MANY_QUESTIONS = `Error: At most 4 questions are allowed per invocation`;
+const ERROR_DUPLICATE_QUESTION = "Error: Question text must be unique within an invocation";
+const ERROR_TOO_FEW_OPTIONS = `Error: Each question requires at least 2 options`;
+const ERROR_RESERVED_LABEL = `Error: Option label is reserved (${RESERVED_LABELS.join(", ")})`;
+const ERROR_DUPLICATE_OPTION_LABEL = "Error: Option labels must be unique within a question";
+const reservedLabels = new Set(RESERVED_LABELS);
+function validateQuestionnaire(params) {
+	if (params.questions.length === 0) return {
+		ok: false,
+		error: "no_questions",
+		message: ERROR_NO_QUESTIONS
+	};
+	if (params.questions.length > 4) return {
+		ok: false,
+		error: "too_many_questions",
+		message: ERROR_TOO_MANY_QUESTIONS
+	};
+	const seenQuestions = /* @__PURE__ */ new Set();
+	for (const question of params.questions) {
+		if (seenQuestions.has(question.question)) return {
+			ok: false,
+			error: "duplicate_question",
+			message: ERROR_DUPLICATE_QUESTION
+		};
+		seenQuestions.add(question.question);
+	}
+	for (const question of params.questions) {
+		if (question.options.length < 2) return {
+			ok: false,
+			error: "empty_options",
+			message: ERROR_TOO_FEW_OPTIONS
+		};
+		const seenLabels = /* @__PURE__ */ new Set();
+		for (const option of question.options) {
+			if (reservedLabels.has(option.label)) return {
+				ok: false,
+				error: "reserved_label",
+				message: ERROR_RESERVED_LABEL
+			};
+			if (seenLabels.has(option.label)) return {
+				ok: false,
+				error: "duplicate_option_label",
+				message: ERROR_DUPLICATE_OPTION_LABEL
+			};
+			seenLabels.add(option.label);
+		}
+	}
+	return { ok: true };
+}
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/_tools/askUserHeadless.ts
+function output(result) {
+	return {
+		content: result.content,
+		details: result.details
+	};
+}
+function createAskUserHeadlessTool(coordinator) {
+	return {
+		name: ASK_USER_QUESTION_TOOL_NAME,
+		label: "Ask User Question",
+		description: "Ask the user one or more structured questions during execution.",
+		parameters: QuestionParamsSchema,
+		promptSnippet: "Ask the user structured questions when requirements are ambiguous",
+		executionMode: "serial",
+		async execute(_toolCallId, parameters, signal, _onUpdate, executionContext) {
+			const params = parameters;
+			const validation = validateQuestionnaire(params);
+			if (!validation.ok) return output(buildToolResult(validation.message, {
+				answers: [],
+				cancelled: true,
+				error: validation.error
+			}));
+			const activeCoordinator = coordinator ?? new QuestionnaireCoordinator();
+			try {
+				return output(buildQuestionnaireResponse(await activeCoordinator.enqueue(async ({ signal: requestSignal, reportProgress }) => {
+					requestSignal.throwIfAborted();
+					const questionnaire = await runQuestionnaire({
+						select: async (title, options, interactionSignal) => {
+							requestSignal.throwIfAborted();
+							const response = await executionContext.client.request({
+								kind: "select",
+								title,
+								options: options.map((label) => ({
+									label,
+									value: label
+								}))
+							}, interactionSignal);
+							return typeof response === "string" ? response : void 0;
+						},
+						input: async (title, placeholder, interactionSignal) => {
+							requestSignal.throwIfAborted();
+							const response = await executionContext.client.request({
+								kind: "input",
+								title,
+								message: placeholder
+							}, interactionSignal);
+							return typeof response === "string" ? response : void 0;
+						}
+					}, params, requestSignal, reportProgress);
+					requestSignal.throwIfAborted();
+					return questionnaire;
+				}, signal), params));
+			} finally {
+				if (coordinator === void 0) {
+					activeCoordinator.shutdown();
+					await activeCoordinator.waitForIdle();
+				}
+			}
+		}
+	};
+}
+//#endregion
+//#region src/extensions/workspaces/sessions/(backend)/tool/askUserQuestion.server.ts
+var askUserQuestion_server_default = defineServerTool((context) => createAskUserHeadlessTool(context.root.coordinator));
+//#endregion
+//#region generated/server.ts
+const at = (value, context) => typeof value === "function" ? value(context) : value;
+const via = (identity, value) => value === void 0 ? void 0 : {
+	...identity,
+	...value
+};
+const facet = defineServerPlugin({
+	name: "@agimon-ai/po-user-feedback",
+	providerOverrides: composeServerProviderOverrides(root_server_default),
+	session: async (context) => {
+		const scopeSession = await root_server_default(context);
+		const contextSession = {
+			...context,
+			root: scopeSession.value
+		};
+		return {
+			...composeRootHooks(scopeSession),
+			get resources() {
+				return [at(poUseUserFeedback_server_default, contextSession)];
+			},
+			get toolRestrictions() {
+				return [at(askUserQuestion_server_default$1, contextSession)];
+			},
+			get tools() {
+				return [via({ name: "ask_user_question" }, at(askUserQuestion_server_default, contextSession))];
+			},
+			services: [...scopeSession.services ?? []],
+			get activities() {
+				return [...scopeSession.activities ?? []];
+			}
+		};
+	}
+});
+//#endregion
+export { facet as default, facet };
+
+//# sourceMappingURL=server.mjs.map