import { defineTool, DirectReturnError } from 'libllmorbiter';
import { TOOL_DESCRIPTIONS, TOOL_PARAMETER_DESCRIPTIONS } from './prompts.js';

/**
 * 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: TOOL_DESCRIPTIONS.ask_user,
        strict: false,
        parameters: {
            type: 'object',
            additionalProperties: false,
            required: ['question'],
            properties: {
                question: {
                    type: 'string',
                    description: TOOL_PARAMETER_DESCRIPTIONS.ask_user.question,
                },
                options: {
                    type: ['array', 'null'],
                    description: TOOL_PARAMETER_DESCRIPTIONS.ask_user.options,
                    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 });
        },
    });
}