import { defineTool, DirectReturnError } from 'libllmorbiter';

/**
 * ask_user tool:
 * Allows the LLM to ask the user for clarification or a decision (e.g. which SKU or ID
 * they meant, or what parameter to use).
 *
 * When invoked, it raises a DirectReturnError with recordResult: false so the LLMOrbiter
 * halts the inference loop immediately without generating a synthetic tool response.
 * The conversation transitions into `idle` state, allowing the client/user to submit
 * a tool response via the API.
 */
export function createAskUserTool() {
    return defineTool({
        name: 'ask_user',
        description:
            'Ask the user when you need clarification or a decision (e.g. which SKU or ID they meant, or what parameter to use). ' +
            'Give a concise question + up to 3 short options (A,B,C); the user may select an option or provide free-form text.',
        strict: false,
        parameters: {
            type: 'object',
            additionalProperties: false,
            required: ['question'],
            properties: {
                question: {
                    type: 'string',
                    description: 'Question for the user.',
                },
                options: {
                    type: 'array',
                    description: 'Up to 3 short option labels.',
                    items: { type: 'string' },
                    maxItems: 3,
                },
            },
        },
        invoke: async ({ question, options = [] }) => {
            const capped = Array.isArray(options) ? options.slice(0, 3) : [];
            // Stop LLM loop immediately so the conversation stays idle awaiting user tool response
            throw new DirectReturnError({ question, options: capped }, { recordResult: false });
        },
    });
}