prompt_user

Instructions

Implementation Reference

• src/features/prompt.ts:74-126 (handler)

  Main handler function that executes the prompt_user tool logic. It validates params via validatePromptParams, builds an AppleScript command via buildPromptCommand, executes it using osascript, parses the result to extract the button clicked and user text input, and returns a PromptResult. It also handles errors like user cancellation, command failures, and permission denied.

  export async function promptUser(params: PromptParams): Promise<PromptResult> {
    try {
      validatePromptParams(params);
      const command = buildPromptCommand(params);
      const { stdout } = await execAsync(command);
      
      // Parse the AppleScript result
      // Format: button returned:OK, text returned:user input
      const match = stdout.match(/button returned:([^,]+)(?:, text returned:(.+))?/);
      if (!match) {
        throw new Error('Failed to parse dialog result');
      }
      
      const buttonText = match[1];
      const text = match[2];
      
      // Find the index of the clicked button
      const buttons = params.buttons || ['Cancel', 'OK'];
      const buttonIndex = buttons.findIndex(b => b === buttonText);
      
      return {
        text: text,
        buttonIndex: buttonIndex !== -1 ? buttonIndex : 0
      };
    } catch (error) {
      if (error instanceof NotificationError) {
        throw error;
      }
  
      const err = error as Error;
      if (err.message.includes('User canceled')) {
        throw new NotificationError(
          NotificationErrorType.PROMPT_CANCELLED,
          'User cancelled the prompt'
        );
      } else if (err.message.includes('execution error')) {
        throw new NotificationError(
          NotificationErrorType.COMMAND_FAILED,
          'Failed to execute prompt command'
        );
      } else if (err.message.includes('permission')) {
        throw new NotificationError(
          NotificationErrorType.PERMISSION_DENIED,
          'Permission denied when trying to show prompt'
        );
      } else {
        throw new NotificationError(
          NotificationErrorType.UNKNOWN,
          `Unexpected error: ${err.message}`
        );
      }
    }
  }

• src/types.ts:29-38 (schema)

  PromptParams interface defining the input schema for the prompt_user tool: message (required string), defaultAnswer (optional string), buttons (optional array of strings, max 3), and icon (optional enum: 'note', 'stop', 'caution').

  export interface PromptParams {
    /** Text to display in the prompt dialog */
    message: string;
    /** Optional default text to pre-fill */
    defaultAnswer?: string;
    /** Optional custom button labels */
    buttons?: string[];
    /** Optional icon name to display (note, stop, caution) */
    icon?: 'note' | 'stop' | 'caution';
  }

• src/types.ts:43-48 (schema)

  PromptResult interface defining the return type: text (optional string, the user's input) and buttonIndex (number, 0-based index of the clicked button).

  export interface PromptResult {
    /** Text entered by the user, or undefined if cancelled */
    text?: string;
    /** Index of the button clicked (0-based) */
    buttonIndex: number;
  }

• src/index.ts:248-267 (registration)

  Tool registration in the CallToolRequestSchema handler: the 'prompt_user' case extracts message, defaultAnswer, buttons, and icon from request params, creates a PromptParams object, calls the promptUser handler, and returns the result as JSON.

  case 'prompt_user': {
    const { message, defaultAnswer, buttons, icon } = request.params.arguments as Record<string, unknown>;
    
    const params: PromptParams = {
      message: message as string,
      defaultAnswer: typeof defaultAnswer === 'string' ? defaultAnswer : undefined,
      buttons: Array.isArray(buttons) ? buttons as string[] : undefined,
      icon: ['note', 'stop', 'caution'].includes(icon as string) ? icon as 'note' | 'stop' | 'caution' : undefined
    };
  
    const result = await promptUser(params);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result),
        },
      ],
    };
  }

• src/index.ts:87-117 (registration)

  Tool definition and inputSchema registered in ListToolsRequestSchema: declares the 'prompt_user' tool with its description and JSON Schema input schema (message required, optional defaultAnswer, buttons array max 3, icon enum).

    name: 'prompt_user',
    description: 'Display a dialog prompt to get user input',
    inputSchema: {
      type: 'object',
      properties: {
        message: {
          type: 'string',
          description: 'Text to display in the prompt dialog',
        },
        defaultAnswer: {
          type: 'string',
          description: 'Optional default text to pre-fill',
        },
        buttons: {
          type: 'array',
          items: {
            type: 'string'
          },
          description: 'Optional custom button labels (max 3)',
          maxItems: 3
        },
        icon: {
          type: 'string',
          enum: ['note', 'stop', 'caution'],
          description: 'Optional icon to display'
        }
      },
      required: ['message'],
      additionalProperties: false,
    },
  },