@jini-ai/mcp 0.4.3 → 0.4.4

package/dist/server/tools/tool-catalog-tools.js

@@ -4,24 +4,40 @@
  * `search_tools` / `describe_tool` — the discovery half of `ai-control-plane.md` §29 /
  * `PROP-tool-catalog-discovery-2026-07-26.md` §6.1, proxying `@jini-ai/http-kit`'s
  * `GET /api/tools/search` / `GET /api/tools/:id` exactly as `run-tools.ts`'s tools proxy
- * `runs.ts` — no separate authorization mechanism, no caching, no state.
+ * `runs.ts` — no separate authorization mechanism or catalog cache.
  *
  * v0 scope: no principal scoping, no versioning, no schema narrowing. Execution is unchanged —
- * a caller still runs a discovered id through `execute_delegated_tool`
- * (`../tools/delegated-tool.js`), which is the only thing that ever reaches `ToolExecutor`.
+ * a caller runs a discovered id through the delegated gateway (`../tools/delegated-tool.js`),
+ * either with its legacy wrapper or a concrete definition published after a successful describe.
+ * Both reach the same `ToolExecutor`.
  * Finding a tool id here grants nothing (`PROP` §6.3).
  */
 import { getDaemonJson } from '../daemon-client.js';
+import { isRecord } from '../tool-arguments.js';
 import { daemonCallOptions, requireString } from '../tool-protocol.js';
 const READ_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
     openWorldHint: false,
 };
+/** Validate the daemon's identity before publishing; discovery cannot substitute another tool.
+ * Unknown risk remains unclassified and therefore cannot claim a read-only annotation.
+ * @complexity O(1); no effects. The schema is checked by the publication boundary.
+ */
+function describedDescriptor({ id, data }) {
+    if (!isRecord(data) || data.id !== id)
+        throw new Error('daemon returned a mismatched tool descriptor');
+    return {
+        id,
+        ...(typeof data.description === 'string' ? { description: data.description } : {}),
+        ...(typeof data.readOnly === 'boolean' ? { readOnly: data.readOnly } : {}),
+        ...(data.inputSchema === undefined ? {} : { inputSchema: data.inputSchema }),
+    };
+}
 /** `search_tools` -> `GET /api/tools/search` (`packages/http/src/tool-catalog.ts`'s `toolCatalogSearchRoute`). */
 export const searchToolsTool = {
     name: 'search_tools',
-    description: 'Search the durable tool catalog. Returns ranked {id, description, source, score} candidates only — no input schemas, so this stays cheap to call broadly. Call describe_tool on the 1-3 candidates that look right before calling execute_delegated_tool. If nothing in the results fits, re-search with a higher limit or different phrasing rather than assuming the tool does not exist.',
+    description: 'Search the durable tool catalog. Returns ranked {id, description, source, score, readOnly, sideEffects} candidates only — no input schemas, so this stays cheap to call broadly. Call describe_tool on the 1-3 candidates that look right before calling execute_delegated_tool. If nothing in the results fits, re-search with a higher limit or different phrasing rather than assuming the tool does not exist.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -80,19 +96,25 @@ export const searchToolsTool = {
 /** `describe_tool` -> `GET /api/tools/:id` (`packages/http/src/tool-catalog.ts`'s `toolCatalogDescribeRoute`). */
 export const describeToolTool = {
     name: 'describe_tool',
-    description: 'Get the full descriptor for one tool id found via search_tools — description and input schema. Paid for only on the candidates that survive search, per the tool catalog\'s staged-discovery design.',
+    description: 'Get the full descriptor for one tool id found via search_tools — description, input schema, readOnly and sideEffects. When dynamic publication is enabled, this also exposes that operation as a concrete tool in tools/list; call it with its own arguments. Legacy fallback: use execute_readonly_delegated_tool only when readOnly is true. Supply id (aliases: toolId or name). Paid for only on the candidates that survive search, per the tool catalog\'s staged-discovery design.',
     inputSchema: {
         type: 'object',
         properties: {
-            id: { type: 'string', description: 'Tool id returned by search_tools. Required.' },
+            id: { type: 'string', description: 'Tool id returned by search_tools. Supply id, toolId, or name.' },
+            toolId: { type: 'string', description: 'Alias of id, matching the delegated-execute wrappers.' },
+            name: { type: 'string', description: 'Alias of id.' },
         },
-        required: ['id'],
+        anyOf: [{ required: ['id'] }, { required: ['toolId'] }, { required: ['name'] }],
         additionalProperties: false,
     },
+    argumentNormalization: { aliases: { toolId: 'id', name: 'id' } },
     annotations: { ...READ_ANNOTATIONS, title: 'Describe a tool' },
     handler: async ({ args, ctx }) => {
         const id = requireString({ value: args.id, name: 'id' });
-        return getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/tools/${encodeURIComponent(id)}` }, daemonCallOptions({ ctx }));
+        const data = await getDaemonJson({ baseUrl: ctx.baseUrl, route: `/api/tools/${encodeURIComponent(id)}` }, daemonCallOptions({ ctx }));
+        if (ctx.publishTool)
+            await ctx.publishTool({ descriptor: describedDescriptor({ id, data }) });
+        return data;
     },
 };
 /** Both tool-catalog discovery tools, ready to pass as `createMcpToolServer`'s `tools` option. */

package/dist/tools/ask-choice/index.d.ts

@@ -1,9 +1,23 @@
-import type { AskChoiceCall, AskChoiceExchangeStore, AskChoiceMessages, AskChoicePendingStore, AskChoicePolicy, AskChoicePresentation } from './types.js';
+import type { AskChoiceCall, AskChoiceExchange, AskChoiceExchangeStore, AskChoiceMessages, AskChoicePendingStore, AskChoicePolicy, AskChoicePresentation, AskChoiceQuestion } from './types.js';
 export type * from './types.js';
 export { ASK_CHOICE_INPUT_SCHEMA } from './schema.js';
 export { createAskChoiceAnswerTicketStore } from './pending.js';
 /** Existing callback wire keys; the tool's identity is supplied by the host. */
 export declare const ASK_CHOICE_ANSWER_TICKET_PARAM = "__askChoiceAnswerTicket";
+/** Run a trusted host question through the same abort, delivery, validation and cleanup lifecycle
+ * as the model-facing tool. The host owns presentation and action policy, never exchange mechanics.
+ * @returns Classified human answer, including an offered action when configured.
+ * @complexity O(n) offered options and selections.
+ */
+export declare function askChoice({ exchange, question, toolId, principalId, presentation, signal, messages }: {
+    exchange: AskChoiceExchange;
+    question: AskChoiceQuestion;
+    toolId: string;
+    principalId: string;
+    presentation: Pick<AskChoicePresentation, 'render'>;
+    signal: AbortSignal;
+    messages: AskChoiceMessages;
+}, _options?: {}): Promise<Record<string, unknown>>;
 /** Creates a choice tool without a CMS, renderer, permission system, clock, or global store.
  * The host composes this descriptor/handler into its registry and mounts callbacks against the
  * same exchange and pending stores. Policy and presentation are required, with no product defaults.
@@ -29,15 +43,50 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
         inputSchema: {
             readonly type: "object";
             readonly additionalProperties: false;
-            readonly required: readonly ["title"];
             readonly anyOf: readonly [{
-                readonly required: readonly ["singleSelect"];
+                readonly required: readonly ["question", "options"];
             }, {
-                readonly required: readonly ["multiSelect"];
+                readonly required: readonly ["title", "singleSelect"];
+            }, {
+                readonly required: readonly ["title", "multiSelect"];
             }];
             readonly properties: {
+                readonly question: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "The question to ask the human.";
+                };
+                readonly options: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["label"];
+                        readonly properties: {
+                            readonly label: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly value: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly description: "Defaults to label when omitted.";
+                            };
+                            readonly description: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+                readonly multiple: {
+                    readonly type: "boolean";
+                    readonly description: "Allow several selections. Defaults to false.";
+                };
                 readonly title: {
                     readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: "Legacy alias: title with singleSelect or multiSelect.";
                 };
                 readonly description: {
                     readonly type: "string";
@@ -46,25 +95,33 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
                     readonly type: "string";
                 };
                 readonly singleSelect: {
+                    readonly description: "Legacy nested single-choice alias.";
                     readonly type: "object";
                     readonly additionalProperties: false;
                     readonly required: readonly ["label", "options"];
                     readonly properties: {
                         readonly label: {
                             readonly type: "string";
+                            readonly minLength: 1;
                         };
                         readonly options: {
                             readonly type: "array";
                             readonly minItems: 1;
                             readonly items: {
+                                readonly required: readonly ["value", "label"];
                                 readonly type: "object";
                                 readonly additionalProperties: false;
-                                readonly required: readonly ["value", "label"];
                                 readonly properties: {
+                                    readonly label: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
                                     readonly value: {
                                         readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly description: "Defaults to label when omitted.";
                                     };
-                                    readonly label: {
+                                    readonly description: {
                                         readonly type: "string";
                                     };
                                 };
@@ -73,25 +130,33 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
                     };
                 };
                 readonly multiSelect: {
+                    readonly description: "Legacy nested multiple-choice alias.";
                     readonly properties: {
                         readonly hint: {
                             readonly type: "string";
                         };
                         readonly label: {
                             readonly type: "string";
+                            readonly minLength: 1;
                         };
                         readonly options: {
                             readonly type: "array";
                             readonly minItems: 1;
                             readonly items: {
+                                readonly required: readonly ["value", "label"];
                                 readonly type: "object";
                                 readonly additionalProperties: false;
-                                readonly required: readonly ["value", "label"];
                                 readonly properties: {
+                                    readonly label: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
                                     readonly value: {
                                         readonly type: "string";
+                                        readonly minLength: 1;
+                                        readonly description: "Defaults to label when omitted.";
                                     };
-                                    readonly label: {
+                                    readonly description: {
                                         readonly type: "string";
                                     };
                                 };
@@ -102,19 +167,153 @@ export declare function createAskChoiceTool({ toolId, description, permission, p
                     readonly additionalProperties: false;
                     readonly required: readonly ["label", "options"];
                 };
-                readonly choice: {
+            };
+        };
+    };
+    invocationSchema: {
+        readonly anyOf: readonly [{
+            readonly required: readonly ["question", "options"];
+        }, {
+            readonly required: readonly ["title", "singleSelect"];
+        }, {
+            readonly required: readonly ["title", "multiSelect"];
+        }, {
+            readonly required: readonly ["choice", "__askChoiceAnswerTicket"];
+        }, {
+            readonly required: readonly ["selections", "__askChoiceAnswerTicket"];
+        }];
+        readonly properties: {
+            readonly choice: {
+                readonly type: "string";
+            };
+            readonly selections: {
+                readonly type: "array";
+                readonly items: {
                     readonly type: "string";
-                    readonly description: "Set by the rendered form; never by the model.";
                 };
-                readonly selections: {
-                    readonly type: "array";
-                    readonly items: {
+            };
+            readonly __askChoiceAnswerTicket: {
+                readonly type: "string";
+            };
+            readonly question: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "The question to ask the human.";
+            };
+            readonly options: {
+                readonly type: "array";
+                readonly minItems: 1;
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["label"];
+                    readonly properties: {
+                        readonly label: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly value: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "Defaults to label when omitted.";
+                        };
+                        readonly description: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly multiple: {
+                readonly type: "boolean";
+                readonly description: "Allow several selections. Defaults to false.";
+            };
+            readonly title: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Legacy alias: title with singleSelect or multiSelect.";
+            };
+            readonly description: {
+                readonly type: "string";
+            };
+            readonly submitLabel: {
+                readonly type: "string";
+            };
+            readonly singleSelect: {
+                readonly description: "Legacy nested single-choice alias.";
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["label", "options"];
+                readonly properties: {
+                    readonly label: {
                         readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly required: readonly ["value", "label"];
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly value: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "Defaults to label when omitted.";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            readonly multiSelect: {
+                readonly description: "Legacy nested multiple-choice alias.";
+                readonly properties: {
+                    readonly hint: {
+                        readonly type: "string";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly required: readonly ["value", "label"];
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly properties: {
+                                readonly label: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly value: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                    readonly description: "Defaults to label when omitted.";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
                     };
-                    readonly description: "Set by the rendered form; never by the model.";
                 };
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["label", "options"];
             };
         };
+        readonly type: "object";
+        readonly additionalProperties: false;
     };
     handler({ ctx }: {
         ctx: AskChoiceCall;

package/dist/tools/ask-choice/index.js

@@ -1,5 +1,5 @@
-import { parseQuestion, QuestionShapeError } from './question.js';
-import { ASK_CHOICE_INPUT_SCHEMA } from './schema.js';
+import { matchesOptions, parseQuestion, QuestionShapeError } from './question.js';
+import { ASK_CHOICE_INPUT_SCHEMA, ASK_CHOICE_INVOCATION_SCHEMA } from './schema.js';
 export { ASK_CHOICE_INPUT_SCHEMA } from './schema.js';
 export { createAskChoiceAnswerTicketStore } from './pending.js';
 /** Existing callback wire keys; the tool's identity is supplied by the host. */
@@ -14,7 +14,32 @@ function describeAnswer(params, messages) {
         return { submitted: false, reason: 'no-answer', note: messages.noAnswer };
     return { submitted: true, ...(choice === undefined ? {} : { choice }), ...(selections === undefined ? {} : { selections }), note: messages.submitted };
 }
-async function waitForAnswer({ exchange, ui, signal, messages }) {
+// Classifies a delivered form answer: cancel wins over typed text, typed text wins over picks,
+// and picks must stay inside the offered options and actions.
+function classifyReceived({ params, question, messages }) {
+    if (params[SURFACE_DISMISSED_PARAM] === true)
+        return { submitted: false, reason: 'cancelled', note: messages.cancelled };
+    const typed = params[SURFACE_TYPED_ANSWER_PARAM];
+    if (typeof typed === 'string' && typed.trim())
+        return { submitted: true, freeText: typed.trim(), note: messages.typed };
+    const described = describeAnswer(params, messages);
+    if (described.submitted !== true)
+        return described;
+    return withOfferedAction({ described, params, question, messages });
+}
+function withOfferedAction({ described, params, question, messages }) {
+    const invalid = { submitted: false, reason: 'invalid-answer', note: messages.noAnswer };
+    // Live exchanges need the same offered-option boundary as fallback tickets.
+    if (!matchesOptions({ question, params }))
+        return invalid;
+    if (!question.actions)
+        return described;
+    const action = params['__choiceAction'];
+    if (!question.actions.some(offered => offered.id === action))
+        return invalid;
+    return { ...described, action };
+}
+async function waitForAnswer({ exchange, ui, signal, messages, question }) {
     const close = () => exchange.close({});
     signal.addEventListener('abort', close, { once: true });
     try {
@@ -26,18 +51,31 @@ async function waitForAnswer({ exchange, ui, signal, messages }) {
         const answer = await exchange.receive({});
         if (answer.status !== 'received')
             return { submitted: false, reason: answer.status, note: messages[answer.status] };
-        if (answer.params[SURFACE_DISMISSED_PARAM] === true)
-            return { submitted: false, reason: 'cancelled', note: messages.cancelled };
-        const typed = answer.params[SURFACE_TYPED_ANSWER_PARAM];
-        if (typeof typed === 'string' && typed.trim())
-            return { submitted: true, freeText: typed.trim(), note: messages.typed };
-        return describeAnswer(answer.params, messages);
+        return classifyReceived({ params: answer.params, question, messages });
     }
     finally {
         signal.removeEventListener('abort', close);
         close();
     }
 }
+/** Run a trusted host question through the same abort, delivery, validation and cleanup lifecycle
+ * as the model-facing tool. The host owns presentation and action policy, never exchange mechanics.
+ * @returns Classified human answer, including an offered action when configured.
+ * @complexity O(n) offered options and selections.
+ */
+export async function askChoice({ exchange, question, toolId, principalId, presentation, signal, messages }, _options = {}) {
+    let ui;
+    try {
+        ui = presentation.render({ toolName: toolId, principalId, question,
+            baseParams: { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id },
+        }, { cancelParams: { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id, [SURFACE_DISMISSED_PARAM]: true } });
+    }
+    catch (error) {
+        exchange.close({});
+        throw error;
+    }
+    return waitForAnswer({ exchange, ui, signal, messages, question });
+}
 /** Creates a choice tool without a CMS, renderer, permission system, clock, or global store.
  * The host composes this descriptor/handler into its registry and mounts callbacks against the
  * same exchange and pending stores. Policy and presentation are required, with no product defaults.
@@ -49,50 +87,56 @@ export function createAskChoiceTool({ toolId, description, permission, policy, p
     };
     return {
         descriptor,
+        invocationSchema: ASK_CHOICE_INVOCATION_SCHEMA,
         async handler({ ctx }) {
             await policy.authorize({ ctx, toolId });
             const input = typeof ctx.input === 'object' && ctx.input !== null ? ctx.input : {};
-            const isAnswer = typeof input['title'] !== 'string' && (typeof input['choice'] === 'string' || Array.isArray(input['selections']));
-            if (isAnswer) {
-                const rawTicket = input[ASK_CHOICE_ANSWER_TICKET_PARAM];
-                const ticket = typeof rawTicket === 'string' ? rawTicket : undefined;
-                if (!pendingQuestions.redeem({ ticket, principalId: ctx.principalId, params: input })) {
-                    throw policy.inputError({ message: messages.forgedAnswer });
-                }
-                return describeAnswer(input, messages);
-            }
-            let question;
-            try {
-                question = parseQuestion({ input, toolId });
-            }
-            catch (error) {
-                if (!(error instanceof QuestionShapeError))
-                    throw error;
-                throw policy.shapeError({ message: error.message, toolId, inputSchema: ASK_CHOICE_INPUT_SCHEMA });
-            }
+            if (isAnswerCall(input))
+                return redeemAnswer({ input, ctx, pendingQuestions, policy, messages });
+            const question = parseOrRefuse({ input, toolId, policy });
             if (ctx.signal.aborted)
                 return { submitted: false, reason: 'abandoned', note: messages.abandoned };
             const exchange = ctx.emitSurface ? surfaceExchanges.open({ toolId, principalId: ctx.principalId, emit: ctx.emitSurface }) : undefined;
-            const ticket = exchange ? undefined : pendingQuestions.mint({ principalId: ctx.principalId, question });
-            const baseParams = exchange ? { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id } : { [ASK_CHOICE_ANSWER_TICKET_PARAM]: ticket };
-            let ui;
-            try {
-                ui = presentation.render({
-                    toolName: toolId, principalId: ctx.principalId, question, baseParams,
-                }, { ...(exchange ? { cancelParams: { [SURFACE_EXCHANGE_ID_PARAM]: exchange.id, [SURFACE_DISMISSED_PARAM]: true } } : {}),
-                });
-                if (!exchange)
-                    return presentation.buildResult({ modelText: messages.pending, ui });
-            }
-            catch (error) {
-                exchange?.close({});
-                // A form that was not delivered must not leave a redeemable fallback ticket behind.
-                if (ticket !== undefined)
-                    pendingQuestions.redeem({ ticket, principalId: ctx.principalId, params: {} });
-                throw error;
-            }
-            return waitForAnswer({ exchange, ui, signal: ctx.signal, messages });
+            if (exchange)
+                return askChoice({ exchange, question, toolId, principalId: ctx.principalId, presentation, signal: ctx.signal, messages });
+            return presentFallback({ question, toolId, principalId: ctx.principalId, pendingQuestions, presentation, messages });
         },
     };
 }
+// A second call carrying a pick (and no question title) is an answer to a fallback form.
+function isAnswerCall(input) {
+    return typeof input['title'] !== 'string' && typeof input['question'] !== 'string' && (typeof input['choice'] === 'string' || Array.isArray(input['selections']));
+}
+// The ticket is the only proof the answer came from a rendered form: redeem is fail-closed.
+function redeemAnswer({ input, ctx, pendingQuestions, policy, messages }) {
+    const rawTicket = input[ASK_CHOICE_ANSWER_TICKET_PARAM];
+    const ticket = typeof rawTicket === 'string' ? rawTicket : undefined;
+    if (!pendingQuestions.redeem({ ticket, principalId: ctx.principalId, params: input })) {
+        throw policy.inputError({ message: messages.forgedAnswer });
+    }
+    return describeAnswer(input, messages);
+}
+function parseOrRefuse({ input, toolId, policy }) {
+    try {
+        return parseQuestion({ input, toolId });
+    }
+    catch (error) {
+        if (!(error instanceof QuestionShapeError))
+            throw error;
+        throw policy.shapeError({ message: error.message, toolId, inputSchema: ASK_CHOICE_INPUT_SCHEMA });
+    }
+}
+// No emit seam: return the form itself, bound to a freshly minted single-use ticket.
+function presentFallback({ question, toolId, principalId, pendingQuestions, presentation, messages }) {
+    const ticket = pendingQuestions.mint({ principalId, question });
+    try {
+        const ui = presentation.render({ toolName: toolId, principalId, question, baseParams: { [ASK_CHOICE_ANSWER_TICKET_PARAM]: ticket } });
+        return presentation.buildResult({ modelText: messages.pending, ui });
+    }
+    catch (error) {
+        // A form that was not delivered must not leave a redeemable fallback ticket behind.
+        pendingQuestions.redeem({ ticket, principalId, params: {} });
+        throw error;
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/tools/ask-choice/question.d.ts

@@ -5,10 +5,14 @@ export declare class QuestionShapeError extends Error {
         message: string;
     }, options?: ErrorOptions);
 }
+/** Normalize the flat model question into the existing UI/answer contract.
+ * @throws QuestionShapeError for malformed questions or ambiguous mixed forms.
+ * @complexity O(n) in offered options; no effects.
+ */
 export declare function parseQuestion({ input, toolId }: {
     input: Record<string, unknown>;
     toolId: string;
-}): AskChoiceQuestion;
+}, _options?: {}): AskChoiceQuestion;
 export declare function matchesOptions({ question, params }: {
     question: AskChoiceQuestion;
     params: Record<string, unknown>;

package/dist/tools/ask-choice/question.js

@@ -21,11 +21,45 @@ function readSelect(raw, field, toolId) {
         if (typeof value !== 'string' || !value || typeof label !== 'string' || !label) {
             throw new QuestionShapeError({ message: `${toolId}: every '${field}' option requires a string 'value' and 'label'.` });
         }
-        return { value, label };
+        return { value, label, ...(typeof option['description'] === 'string' ? { description: option['description'] } : {}) };
     });
     return { label: spec['label'], options, ...(typeof spec['hint'] === 'string' ? { hint: spec['hint'] } : {}) };
 }
-export function parseQuestion({ input, toolId }) {
+function normalizeFlatQuestion({ input, toolId }, _options = {}) {
+    const question = input['question'];
+    if (typeof question !== 'string' || !question.trim())
+        throw new QuestionShapeError({ message: `${toolId}: 'question' is required.` });
+    if (input['multiple'] !== undefined && typeof input['multiple'] !== 'boolean') {
+        throw new QuestionShapeError({ message: `${toolId}: 'multiple' must be a boolean.` });
+    }
+    const options = normalizeFlatOptions({ rawOptions: input['options'] });
+    const select = { label: question, options };
+    return { title: question, ...(typeof input['description'] === 'string' ? { description: input['description'] } : {}),
+        ...(typeof input['submitLabel'] === 'string' ? { submitLabel: input['submitLabel'] } : {}),
+        [input['multiple'] === true ? 'multiSelect' : 'singleSelect']: select };
+}
+function normalizeFlatOptions({ rawOptions }, _options = {}) {
+    return Array.isArray(rawOptions) ? rawOptions.map(entry => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+            return entry;
+        const option = entry;
+        return { ...option, value: option['value'] === undefined ? option['label'] : option['value'] };
+    }) : rawOptions;
+}
+function normalizeQuestion({ input, toolId }, _options = {}) {
+    if (input['question'] === undefined && input['options'] === undefined && input['multiple'] === undefined)
+        return input;
+    if (input['title'] !== undefined || input['singleSelect'] !== undefined || input['multiSelect'] !== undefined) {
+        throw new QuestionShapeError({ message: `${toolId}: use {question, options, multiple?} or the legacy nested selects; do not mix them.` });
+    }
+    return normalizeFlatQuestion({ input, toolId });
+}
+/** Normalize the flat model question into the existing UI/answer contract.
+ * @throws QuestionShapeError for malformed questions or ambiguous mixed forms.
+ * @complexity O(n) in offered options; no effects.
+ */
+export function parseQuestion({ input, toolId }, _options = {}) {
+    input = normalizeQuestion({ input, toolId });
     const title = input['title'];
     if (typeof title !== 'string' || !title)
         throw new QuestionShapeError({ message: `${toolId}: 'title' is required.` });